MCP 集成

ForgeaX CLI 通过 MCP（Model Context Protocol） 接入外部工具与数据源。

配置文件

自动发现并合并（项目覆盖用户）：

1. ~/.forgeax/mcp.json
2. <cwd>/.forgeax/mcp.json

也可用 flag 指定：

forgeax --mcp /path/to/mcp.json

形状

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"]
    }
  }
}

具体 server 字段以实现为准；未知键会透传给 MCP 客户端装配层。

Token 注入

避免把密钥写进可提交的 JSON：

forgeax --mcp-token github=GITHUB_TOKEN
forgeax --mcp-token =GLOBAL_TOKEN_ENV     # 通配：所有 server 同一 env 名

语法：server=ENV_NAME 或 =ENV_NAME（wildcard）。

作为 MCP Server（反向）

把本内核工具暴露给其他 MCP 客户端：

forgeax mcp-serve
forgeax mcp-serve --allow-writes

• 默认偏只读；改动型工具需 --allow-writes 或 FORGEAX_MCP_ALLOW_WRITES=1
• 非交互：ask 类权限一律拒绝；deny 仍强制生效
• 与 --serve（AgentKernel sidecar）是不同形态，可并存理解：一个对外工具，一个对外内核 RPC

排错

现象	排查
工具未出现	确认 mcp.json 路径存在且 JSON 合法；看启动日志
鉴权失败	检查 --mcp-token / server env 是否指向真实 env
超时 / spawn 失败	本机能否直接跑 command + args

更多见故障排除。