143 lines
8.4 KiB
Markdown
143 lines
8.4 KiB
Markdown
# lc-mcp — 基于 AALC 的 Limbus Company MCP server
|
||
|
||
把 [AhabAssistantLimbusCompany (AALC)](https://github.com/KIYI671/AhabAssistantLimbusCompany)
|
||
的识别与操控能力包装成 MCP 工具,给 AI agent(codex / 任意 MCP 客户端)用。
|
||
|
||
- **低层**:截图、RapidOCR、AALC 模板图匹配(几百张按钮/图标模板)、后台点击/按键,全部直接调 AALC 的 `module.automation`
|
||
- **高层**:`run_task` 直接跑 AALC 现成的完整流程(日常经验本/纽本、领奖励、狂气换体力、镜牢),自带战斗处理、掉线重试、游戏重启
|
||
|
||
AALC 以 git submodule 引入(`vendor/aalc`,固定到某个 commit),不改它的代码,升级时只需更新 submodule 指针。
|
||
|
||
## 架构
|
||
|
||
```
|
||
MCP 客户端 ──ssh──> python lc_mcp/bridge.py (stdio, 只用标准库)
|
||
│ 127.0.0.1:8765, 首行 token 认证
|
||
▼
|
||
python -m lc_mcp.server ← 登录时由计划任务在「交互桌面会话」启动
|
||
├─ AalcEngine → AALC auto / ocr / screen (找窗口、后台截图、PostMessage 输入)
|
||
└─ TaskRunner → 子进程 python -m lc_mcp.aalc_task <task> (停止 = 杀进程树)
|
||
```
|
||
|
||
为什么要常驻服务 + bridge:SSH 登录的进程跑在 session 0,看不到游戏窗口,也发不了输入。
|
||
旧版靠"每次截图注册一个计划任务"绕过,慢且不能输入;现在整个服务常驻在桌面会话里。
|
||
|
||
## 部署(Windows,跑游戏的那台机器)
|
||
|
||
```powershell
|
||
git clone --recursive https://git.lingll.icu/yws/lc-mcp
|
||
cd lc-mcp\vendor\aalc
|
||
uv sync # 按 AALC 的 pyproject 装依赖 (Python >= 3.12),生成 .venv
|
||
# 先用 AALC 自己的界面 (uv run main.py) 配好队伍、镜牢设置等,lc-mcp 读同一个 config.yaml
|
||
cd ..\..
|
||
powershell -ExecutionPolicy Bypass -File scripts\install_logon_task.ps1
|
||
```
|
||
|
||
`install_logon_task.ps1` 会注册 `LcMCPServer` 计划任务(登录时启动、普通权限、失败自动重启)。
|
||
游戏以管理员身份运行时才需要加 `-Elevated`。卸载:`-Uninstall`。
|
||
|
||
## MCP 客户端配置
|
||
|
||
```jsonc
|
||
{
|
||
"mcpServers": {
|
||
"limbus": {
|
||
"type": "stdio",
|
||
"command": "ssh",
|
||
"args": ["win", "python", "C:/Users/<you>/lc-mcp/lc_mcp/bridge.py"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
bridge 读取 `~/lc_mcp/token` 认证(服务首次启动时生成),所以 SSH 用户必须和登录桌面的用户是同一个账号。
|
||
服务没起来时 bridge 仍会完成握手,并对每个调用返回“服务未运行”的原因。
|
||
|
||
本机直接用(客户端本身就在桌面会话里):`python -m lc_mcp.server --stdio`。
|
||
|
||
本机 Codex 也可以连接常驻后台服务(将路径替换为自己的仓库目录):
|
||
|
||
```powershell
|
||
codex mcp add limbus --env PYTHONUTF8=1 -- D:\lc-mcp\vendor\aalc\.venv\Scripts\python.exe -X utf8 D:\lc-mcp\lc_mcp\bridge.py
|
||
```
|
||
|
||
常驻服务使用 `pythonw.exe` 时,启动日志写入 `~/lc_mcp/server.log`。
|
||
直接 stdio 模式会在导入 AALC 前隔离日志,并统一使用 UTF-8,避免日志破坏 JSON-RPC 或中文乱码。
|
||
模板识别会根据当前客户区的 16:9 画面比例临时缩放,匹配结束后恢复内存中的原配置。
|
||
|
||
## 工具
|
||
|
||
| 工具 | 说明 |
|
||
|------|------|
|
||
| `get_state` | 截图 + OCR,返回窗口内全部文字 `{text,x,y,w,h,score}` |
|
||
| `click_text(text, index)` | 按文字点击;忽略空格/大小写,完全匹配优先 |
|
||
| `wait_for_text` / `wait_for_text_gone` | 轮询 OCR 等文字出现/消失(上限 300s) |
|
||
| `find_image` / `click_image(name, threshold, model)` | AALC 模板图匹配,适合没有文字的按钮 |
|
||
| `list_images(prefix)` | 列出模板图,如 `battle/`、`mirror/` |
|
||
| `screenshot` | 窗口截图(`~/lc_mcp/shots`,只保留最近 30 张) |
|
||
| `click(x,y,times)` / `keypress` / `type_text` | 低层输入(窗口客户区坐标) |
|
||
| `drag(from_x,from_y,to_x,to_y,duration)` | 保持左键按下并缓慢拖动,适用于卡包;默认 1 秒,范围 0.1–10 秒;坐标以 `get_state` 的客户区截图为准 |
|
||
| `run_task(task, …)` | `all` / `daily(exp,thread)` / `reward` / `enkephalin(times)` / `mirror(count)` |
|
||
| `task_status(lines)` / `stop_task` | 任务状态、日志尾部(`~/lc_mcp/runs`)、强制停止 |
|
||
|
||
任务运行期间,点击/按键类工具会被拒绝(防止打乱 AALC 的流程),只读工具仍可用。
|
||
`run_task` 传入的次数只对本次运行生效,结束后恢复 `config.yaml` 原值。
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `AALC_DIR` | `vendor/aalc` | 使用其他位置的 AALC 源码 |
|
||
| `LCP_PORT` | 8765 | 服务/bridge 端口 |
|
||
| `LCP_KEEP_SHOTS` | 30 | 截图保留张数 |
|
||
|
||
## 开发 / 测试
|
||
|
||
```bash
|
||
python -m unittest discover -s tests # 不需要 Windows/AALC (FakeEngine)
|
||
python -m lc_mcp.server --stdio --fake # 假引擎手动调试协议
|
||
```
|
||
|
||
服务安装后,可通过真实 bridge 做 MCP 握手和工具调用:
|
||
|
||
```powershell
|
||
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\mcp_probe.py task_status
|
||
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\mcp_probe.py get_state
|
||
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\mcp_probe.py find_image '{"name":"mirror/road_in_mir/setting_assets.png"}'
|
||
```
|
||
|
||
该脚本只调用指定工具;输入类工具会实际操作游戏。完整 AALC 任务依赖已配置好的队伍与流程,基础连接测试不需要启动完整任务。
|
||
|
||
## Jev 镜牢执行器与真实反馈
|
||
|
||
`scripts/jev_mirror_agent.py` 通过 MCP bridge 操作游戏,普通分支交给 Jev;战斗采用 P → 回车宏,事件先 SKIP,回车失效时使用当前按钮。它保留用户已配好的队伍,商店无可替换出战角色时至多刷新 4 次,加载期间不读取旧库存继续操作。
|
||
|
||
安装 AALC 依赖并启动常驻服务后,把 `OPENCODE_API_KEY` 设为自己的凭据,再运行:
|
||
|
||
```powershell
|
||
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py scripts\jev_config.example.json --steps 250 --seconds 1800
|
||
```
|
||
|
||
运行数据默认写到 `~/lc_mcp/jev`,可用 `LC_JEV_HOME` 指定其他目录。创建该目录下的 `JEV_STOP` 文件即可停止;续跑前移除它。不要与 AALC 完整任务或另一个游戏执行器同时操作。
|
||
|
||
每局运行现在有独立标识。默认续跑尚未结束且上下文一致的当前局;已完成或没有运行记录时建立新局。重新开一局时使用 `--new-run`,明确要求续跑时使用 `--resume`。旧版本未完成记录会保留楼层和强化进度,但旧的领取及战斗标记不会作为本局完成证据;只有上下文而没有运行记录时会重置它。领取截图和返回大厅截图必须属于当前局,才能记录完成。
|
||
|
||
```powershell
|
||
# 新开一局:清除上一局的楼层、饰品与领取状态
|
||
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py scripts\jev_config.example.json --new-run --seconds 1800
|
||
# 续跑已保存的未完成局,保持原计时起点
|
||
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py scripts\jev_config.example.json --resume --seconds 1800
|
||
```
|
||
|
||
MCP 客户端默认每次请求等待 30 秒,文字等待工具按自身时长延长响应期限。等待回复期间也检查停止标记和本次运行的时间预算。超时或中断时关闭客户端连接,并记录结果可能未知;不会自动重发点击或按键。常驻服务已经接收的操作可能仍会完成,需核对当前画面后再续跑。`battle_batch.py` 与主执行器共用判定、奖励、死亡和地图等战斗退出条件,并在每个按键前检查停止标记。
|
||
|
||
设置 `LC_FIXED_FALLBACK=1` 可只使用固定候选,无需 Jev API 密钥;仍需运行 MCP 服务。完整 AALC 任务启动时,如有 MCP 工具正在执行,会立即返回忙碌错误,避免与当前输入交错;查询与停止任务不受影响。
|
||
|
||
本轮修复、验证范围与已知限制见 [2026-10-03 运行可靠性改进](docs/mcp_runtime_improvements_20261003.md)。
|
||
|
||
本次修复、实际失败反馈、操作日志、截图清单、修改源码快照和速通 skill 见 [2026-10-02 实测记录](docs/feedback/2026-10-02/README.md);安装与测试说明见 [INSTALL_TEST_REPORT.md](INSTALL_TEST_REPORT.md)。这些是开发中的真实记录,包含失败和仍未验证的步骤。
|
||
|
||
## 许可证
|
||
|
||
AALC 使用 AGPL-3.0。本项目会导入并运行 AALC 的代码,分发时需遵守 AGPL-3.0。
|