lc-mcp — 基于 AALC 的 Limbus Company MCP server
把 AhabAssistantLimbusCompany (AALC) 的识别与操控能力包装成 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,跑游戏的那台机器)
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 客户端配置
{
"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 也可以连接常驻后台服务(将路径替换为自己的仓库目录):
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 运行中会整份保存配置,
所以任务启动时先把原值写到 ~/lc_mcp/runs/*.restore.json;stop_task 强停或任务进程异常退出后,
服务会据此写回。写回失败时 task_status 显示 pending_restore,并在写回成功前拒绝启动新任务。
state 只反映任务子进程的退出码。AALC 在单次战斗失败(例如日志里的
超出最大尝试次数,未能进入战斗)后仍会继续跑完并正常退出,所以 task_status
会把日志尾部的 [ERROR]/异常行放进 errors 字段:看到 succeeded 也要先看 errors。
与上游 AALC 的差异(不改其源码)
lc_mcp/aalc_input_patch.py 在 bootstrap() 时给 Windows 输入适配器打补丁,只补上游缺的东西:
- 编队列表滑动:AALC 基类要求适配器覆盖
mouse_swipe_for_team_scroll以"规避队伍拖拽判定", 但上游只有 MuMu 模拟器适配器覆盖了它(见input_handlers/__init__.py注释)。Windows 前台/后台适配器 仍用普通列表手势build_windows_scroll_swipe_plan(escape 30px/0.01s),在游戏的编队列表里不足以脱离 "按住罪人卡"判定,滑动会被当成拖动卡片:队伍顺序被拖乱,缺人时后续还会"未能进入战斗"。 补丁按 MuMu 的参数(按set_win_size缩放 60px escape、保持 0.1s、分段走完、松手前停稳 0.5s) 在Input(前台)和BackgroundInput(后台)上补上等价实现;WindowMoveInput没有set_mouse_pos,保持原样。
环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
AALC_DIR |
vendor/aalc |
使用其他位置的 AALC 源码 |
LCP_PORT |
8765 | 服务/bridge 端口 |
LCP_KEEP_SHOTS |
30 | 截图保留张数 |
开发 / 测试
Jev 决策接口
scripts/jev_mirror_agent.py 使用 scripts/jev_client.py 读取本地配置中的
model、baseUrl、sessionId、transport 和 timeoutSeconds。
Jev 默认地址为 https://opencode.ai/zen/v1/systemone;baseUrl 填到 /v1,
客户端会追加 /systemone。Go 网关的模型列表与 Jev 原生接口不同,不能仅替换地址就假设支持相同模型。
从 scripts/jev_config.example.json 创建仓库外的私有配置,API key 使用
OPENCODE_API_KEY 环境变量或私有配置中的 apiKey。不要把凭据提交到仓库。
Windows 上若 Python HTTPS 遇到握手中断,可用 "transport": "curl",
并把超时提高到 20 秒;认证头通过 stdin 交给 curl,保留证书验证。
通用客户端也支持主线等其他场景的候选决策,不会发送游戏输入:
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_client.py <private-config.json> <observation.json>
observation.json 提供 state(当前画面观察文本)、criteria(候选名到描述的映射)
和 instructions(当前任务规则)。返回候选名和耗时,候选之外的响应会被拒绝。
镜牢执行器的场景规则只适用于镜牢,推进主线时应提供主线观察和规则。
python -m unittest discover -s tests # 不需要 Windows/AALC (FakeEngine)
python -m lc_mcp.server --stdio --fake # 假引擎手动调试协议
服务安装后,可通过真实 bridge 做 MCP 握手和工具调用:
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 设为自己的凭据,再运行:
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 完整任务或另一个游戏执行器同时操作。
中途续跑沿用 jev_shop_context.json;一局领取完成后它会归档为 jev_shop_context.<时间>.json,下一局从干净状态开始。
工具调用失败(截图暂不可用、按钮已消失等)会记入日志并重新观察画面,同一画面上同一动作最多尝试两次,不会因单次失败整局退出。
本次修复、实际失败反馈、操作日志、截图清单、修改源码快照和速通 skill 见 2026-10-02 实测记录;安装与测试说明见 INSTALL_TEST_REPORT.md。这些是开发中的真实记录,包含失败和仍未验证的步骤。
2026-10-03 主线实测与耗时复盘记录了 4-48 未通关、三次 Jev 抉择耗时、混合操作限制、输入修复的验证边界及 94 项回归结果。
许可证
AALC 使用 AGPL-3.0。本项目会导入并运行 AALC 的代码,分发时需遵守 AGPL-3.0。