alice-mcp

# alice-mcp — MCP 热启动网关（agent 层调用，零客户端配置） > 架构（硬性理解）： > - MCP server **不写入任何客户端 config**（codex/dsh/claude/workbuddy/pi 一律不写）。 > - `mcp_gateway.py` 按 registry 直接 spawn server 进程（stdio JSON-RPC），取工具目录、 > 转发调用，结果以普通命令输出喂给 agent —— **即加即用，无需重启客户端**。 > - 热开关：registry `disabled=true/false` 即时生效（gateway 每次调用现读）。 > - 兼容回退：`--client-sync` 可选把 registry 编译进当前客户端配置（默认不用）。 ## 脚本与入口 | 命令 | 作用 | |:--|:--| | `mcp_manager.py --check` | 环境自检：registry / mcpRoot / server 健康与生效提示 | | `mcp_manager.py --add <名> --cmd X --args "..." [--cwd D] [--env K=V]` | 添加 stdio server（**即加即用**） | | `mcp_manager.py --add <名> --url U [--headers "K=V"]` | 添加 http server | | `mcp_manager.py --remove <名>` | 移除 | | `mcp_manager.py --disable <名>` / `--enable <名>` | **热关/热开**（即时生效） | | `mcp_manager.py --test <名>` | server 进程握手验证 | | `mcp_manager.py --wrap <目录> [--name S]` | 目录内可执行文件 → 一个 MCP server（每文件一个 `run_<名>` 工具） | | `mcp_gateway.py list` | **agent 工具目录发现入口**（所有启用 server 的工具清单） | | `mcp_gateway.py list <server> --json` | 单 server 工具目录（JSON） | | `mcp_gateway.py call <server> <tool> '{"k":"v"}'` | 调用工具（stdout 即结果） | | `mcp_gateway.py ping [server]` | 批量握手存活 | | `mcp_gateway.py start/stop/status` | 常驻池预热/关闭/状态 | 脚本位置：`<技能根>/aliceskill/scripts/`。退出码 0/2/3/4。 ## AI 执行流程 ### 工具发现（每个任务开始时，动态） ```bash python "<技能根>/aliceskill/scripts/mcp_gateway.py" list ``` - 输出形如 `mcp__<server>__<tool> — 描述`；**以这条命令的实时输出为准**，不凭记忆假设有哪些 server。 - 调用： ```bash python "<技能根>/aliceskill/scripts/mcp_gateway.py" call <server> <tool> '{"参数": "值"}' --timeout 300 ``` ### 添加（吸收）MCP 1. 问清四件事：名字、stdio（本地命令）还是 http（远程 URL）、**归属分类**（crack/reverse/pentest/game/ai/assist，可多选——决定出现在哪些路由页）、一句话说明。 2. stdio：`--add <名> --cmd <命令> --args "<参数>" --cwd <工作目录> --classes <类,类> --desc "<说明>"`（相对参数自动转绝对；`--classes` 决定该 server 出现在哪些路由页）。 3. http：`--add <名> --url <URL> --headers "Authorization=Bearer xxx" --classes <类,类>`。**网关双传输**：stdio（本地进程）与 Streamable HTTP（远程 MCP，如 github `https://api.githubcopilot.com/mcp/`）都已实现——registry 里有 `url` 自动走 HTTP，无 `url` 走 stdio；认证失败报 `HTTP 401/400` 并指向检查 headers。 4. 从 GitHub 装：先验证仓库真是 MCP server（package.json bin / pyproject 入口 / Dockerfile / 现成 http URL），验证不过不入库；装完走第 2/3 步。 5. **即加即用**：加完 `mcp_gateway.py list` 立即可见，无需重启客户端、无需写 config。 6. **归类落到路由页**：`--classes` 写入 registry 后重跑 `rebuild_menu.py`，该 server 自动出现在对应六类路由页的「可用 MCP 工具（按需使用，不全部加载）」段——例如 IDA 类 server 归 `reverse,crack` 就同时出现在逆和破两页。改归属 = 重新 `--add` 同名条目再重建。 ### 使用中调用（优先级规则） - 会话内盘点到与任务相关的 MCP 工具 → **优先调用**（经 gateway，输出即结果）。 - 调用失败/超时/无匹配 → **立即回退**本地命令与脚本继续执行，不停手、不追问、不要求用户装环境。 - **开工先汇报工作链路**：正式动手前向用户输出一行——`当前预使用 MCP 工具: xxx | xxx | xxx`（按需列出，无则写：无，走本地）+ `使用技能 N 个，取自: <模块id>.md | <模块id>.md | …`（N 个对应 `_modules/` 里的具体 SKILL.md 文件名，不是类名或领域名）；执行中新增取模块或启用新 MCP server 时同步更新。 - 模块 frontmatter `x-alice-mcp: <server名>` 仅作核对提示：gateway list 里有就用，没有就回退。 ### 热开关（不使用时关闭） ```bash mcp_manager.py --disable <名> # 热关：gateway 立即拒绝该 server 调用 mcp_manager.py --enable <名> # 热开：立即可调 ``` - registry 每次调用现读，**无需重启任何东西**——这就是"要使用时申请、不使用时关闭"的实现。 ### 目录包装（把任意工具目录变成 MCP） ```bash mcp_manager.py --wrap <目录> --name <server名> mcp_gateway.py list <server名> mcp_gateway.py call <server名> run_<文件名> '{"argv": ["--help"], "timeout": 60}' ``` ## MCP 工作目录（mcpRoot）——向用户解释用 首次 `--add` 时 manager 会问「MCP 工作目录」。向用户转述以下要点（不要让用户猜）： - **它是什么**：一个存放 MCP 数据的文件夹。你添加的所有 MCP server 清单（`servers.json`）、`--wrap` 生成的包装 server 都存在这里；gateway 每次调用都来这读配置。 - **怎么选**：直接用默认（`<客户端主目录>/mcp`，如 `~/.workbuddy-ai/mcp`）即可——跟客户端数据待在一起，备份/迁移顺手。别放 U 盘或网络盘（server 启动路径要稳定）。 - **确认方式**：回车确认默认，或指定目录后执行 `mcp_manager.py --set-root "<目录>"` 落盘（写入 `aliceskill/config/mcp_settings.json`，之后不再询问）。 - **换位置**：改/删 `mcp_settings.json` 后重新 `--set-root`；registry 里带旧绝对路径的 server 需重新 `--add`（用 `--test <名>` 逐个验证）。 - **换电脑**：发布包不含此目录的锁存信息（`mcp_settings.json` 不随包），新机首次使用重新问一次——这是设计行为。 ## 常见故障 | 现象 | 处置 | |:--|:--| | `gateway list` 报 unavailable | `--ping <名>` 看握手错误；命令不存在 → 修 registry 路径 | | 工具调用超时 | `--timeout` 加大；server 卡死用 `gateway stop --all` 清池 | | mcpRoot 未锁存 | manager 会 exit 3 问用户；用户给目录后 `--set-root` 落盘 | | codex 报 duplicate key（历史遗留） | 旧版曾写客户端 config 且逐键重复子表头；现架构已不写 config，`--client-sync` 写入器已修复为单子表头 | ## 与其它机制的关系 - **客户端原生 MCP**（dsh cordis / pi mcp.json）与本网关**互不干扰**：原生由客户端拉起、工具直接出现在会话；本网关由 agent 显式调用。同一 server 两边都配会重复，选一种。 - 提示词注入块（`inject_route_prompt.py`）只写「动态发现」规则，不含任何 server 清单。