Skip to main content

如何添加一个自定义 MCP 服务

MCP(Model Context Protocol)给 Agent 挂载”工具 / 数据源”。本教程说明如何在 GIS Agent 中新增 一个自定义 MCP,适用于本机开发环境与离线 / 内网部署。 与添加自定义技能不同,MCP 的生效面更窄也更专:它只影响 Agent 工具列表,没有”技能市场”那种文件遍历展示。所以理解 MCP 只需要抓住一条链路—— “登记 → 打包同步(或 L1 热更下发)→ 运行实例读取”。

先选择形态

GIS Agent 支持两种 MCP,按需选一种:
下面以内置的 knowledgecli(remote)作为参照实现讲解。你新增自己的 MCP 时,把 knowledgecli 换成你自己的 id(如 hello)、把服务与端口换成你自己的即可。

关键约束(离线部署)

  • 镜像必须内置:remote MCP 的服务镜像要加入 package.sh 的镜像清单,被 docker save 导出、 目标机 docker load,运行期零公网(内网机器拉不到 registry)。
  • 端口预留:新增 remote MCP 的内部端口不得与既有端口冲突—— 17076(GISAgent)、17072(数据库)、18081、18088(knowledge MCP)、19081、3333(Gateway)、 17077(文档站)。选一个未占用的内部端口即可,通常只需内部网络可达,不必对外发布。
  • secret 卫生:MCP 若需鉴权 key,一律走 config/local/secrets/<ENV_KEY>(file 后端)或 ASE, 在配置里用 ${env.X} 引用,绝不写死进目录 / 镜像 / 文档;并纳入 verify-no-secret-literals.sh 扫描。
  • 多 CLI 对齐:Agent 侧除了 OpenCode,还有 .claude / .qwen / .qoder 各自的 settings.json。新 MCP 需在 opencode.json 与各 CLI 的 mcpServers 里都登记,指向同一服务, 否则换 Agent 内核时工具不一致。

MCP 生效链路(一条)

要点:任何 opencode.json 的 mcp 变更,只有被 rewrite_staged_agent_model_config 同步进 OPENCODE_CONFIG_CONTENT 才会被运行实例读到;不经过它就改了不生效。

形态一:新增一个 remote HTTP MCP(推荐路径)

参照内置 knowledgecli:opencode.json 里就是
对应 Compose 有 knowledge-mcp-http 服务(镜像 knowledge-mcp-http:latest、内部端口 18088、 健康检查 /health)。你新增自己的 remote MCP,按下面 6 步。
模板工程:官方在 gisagent/custom/mcp/hello-mcp/ 提供了一个最小但完整的 remote HTTP MCP 模板工程(Node.js + @modelcontextprotocol/sdk、/health + /mcp、内部端口 18090), 包含 package.json、package-lock.json、tsconfig.json、src/index.ts、Dockerfile、README.md。 你可以直接复制 这个目录改造成自己的 MCP 服务。

1. 备好 MCP 服务镜像

用一个能对外暴露 http://<host>:<port>/mcp 的服务,自带镜像或写一个 Dockerfile。

2. 在 docker-compose.yml 加服务

若源目录路径可能需要可移植(离线 bundle 用相对路径),在 package.sh 的 generate_portable_compose 替换表里,把宿主机绝对路径改写成 bundle 相对路径(参照 knowledge 的写法)。
健康检查工具注意:模板镜像基于 node:20-alpine,内含 wget 但没有 curl, 因此 healthcheck 用 wget。若你的镜像里有 curl 也可以改用 curl -f。

3. 让镜像离线内置

把 hello-mcp:latest 加入 package.sh 顶部镜像清单(与 knowledge-mcp-http:latest 同列), ./package.sh 时会 docker save 进 bundle,目标机 docker load。

4. 在 opencode.json 登记

编辑 config/opencode/opencode.json,在 mcp 下新增一项:
url 用服务名 + 内部端口(Docker 内网解析),不是 localhost。

5. 对齐各 CLI 的 mcpServers

在 package.sh 重写 .claude / .qwen / .qoder 的 settings.json 的段落里,为 hello 增加同名 server,指向同一内部 URL(照 knowledgecli 现有写法复制一份)。这样换用 Claude / Qwen / Qoder 内核时也能看到该工具。

6. 打包并生效


形态二:新增一个 local / stdio MCP

参照内置 personal-knowledge-mcp(opencode.json 里以本地 stdio 拉起)。复用它的打包范式:
  1. 用 package.sh 的 copy_tree_contents_excluding 把 npm 包拷进 bundle(默认去掉 .git / node_modules / target;确需 vendor node_modules 时再放行)。
  2. 写一个 sanitize 步骤(照 sanitize_staged_personal_knowledge):清空运行期数据 / 索引、 生成 portable config.json、chmod 收紧、确保运行 UID(1001)可读其运行目录。
  3. Compose 把该目录只读挂进 agent-*(例如 ./personal-knowledge-mcp:/opt/mcp/<name>:ro), 以 stdio 命令启动。
  4. 在 config/opencode/opencode.json 的 mcp.<id> 登记本地 / stdio 形态,并在各 CLI mcpServers 里对齐;纳入 verify-no-secret-literals.sh 扫描。
stdio 形态无需内网端口,也就不涉及端口预留冲突,但同样要遵守镜像 / 依赖离线内置与 secret 卫生。

已部署环境就地热加(免全量重部署)

若目标机已在运行、只想挂一个 remote MCP 验证或增量上线,不需要走 package.sh 全量重打包。 但先要认清生效载体,避免改错文件:
  • 运行实例(含 Web UI 每会话拉起的临时 ACP 容器)真正读取的是 gisagent 挂载的 profile config/local/agent.local-*.json(${GISAGENT_AGENT_CONFIG},默认 agent.local-qwen-fable.json)里 runtime.env.OPENCODE_CONFIG_CONTENT 的 mcp 段。
  • bundle 的 config/opencode/opencode.json 是打包期源文件,经 rewrite_staged_agent_model_config 同步进上面的 profile;只改它、不热更也不重启, 对正在运行的会话无效。
  • 变更后必须新建会话验证(旧会话缓存工具快照)。
新增 remote MCP 的注册在 GISAgent 侧的生效面只有 OPENCODE_CONFIG_CONTENT 的 mcp 段, 所以热加是单步配置热更(L1)。以下两种方式任选其一(2026-09-23 已在本机栈 “应用 → Web UI 新会话验收 → 同链路还原清理”全闭环实测)。

方式 A:手工热更(步骤少,适合一次性调试)

方式 B:热更包(推荐,自动备份 + 健康闸门 + 失败自动回滚)

docker-hot-update 框架把更新分为 L0~L3:L0 免重启刷卷(用于 SKILL 同步),L1 配置 热更(MCP 注册就是这一层),L2 单镜像热更,L3 全量 bundle 冷更。 开发机改好 profile 后打包(scripts/package-hotfix.sh):
把该 tar 包传到目标机执行(新版 bundle 已内置 scripts/hot-update.sh,package.sh 自 2026-09-23 起同步拷贝;旧 bundle 把该脚本单独拷进栈目录即可;执行机需 python3 + PyYAML 解析 manifest):
执行器流程:解包校验 → preflight → 备份 → 定向 apply → 健康闸门(/gis/ 返回 200 才算过), 失败自动回滚;历史记录在 <栈目录>/.hotfix-backups/hotfix-history.log。 撤销热加:把还原后的 profile 再打一个 L1”还原包”,按同链路 apply 即可(实测清理即此法, 还原后生效副本回到 mcp=[hello, knowledgecli])。 若热加的是一个全新 MCP 服务镜像(不只是注册):起镜像属 L2(docker load 版本化 tag + 定向 recreate,镜像需已随 bundle 交付或人工 docker save/scp 传输);base 镜像链变化 (如 postgiscli)则必须回 L3 全量。
正式交付边界:热更加完别忘了把同一 MCP 登记回仓库 config/opencode/opencode.json 与各 CLI settings.json 的 mcpServers,以下一次 package.sh 全量包为准——打包门禁会校验 注册面一致性,热更只解决”当场生效”。

验证结果

  • 本机快速验证(看运行实例到底加载了哪些 MCP):
    每个服务会带 connected / 失败状态。注意 opencode 读的是运行实例当前生效的配置:聊天 ACP 的 mcp 来自 OPENCODE_CONFIG_CONTENT(由 gisagent 从挂载目录注入,会与全局 ~/.config/opencode/opencode.json 合并)。因此只改仓库 config/opencode/opencode.json 不会立刻 反映到这条命令——要么”重新打包 → 重启 gisagent → 重建运行实例”,要么按上文 “已部署环境就地热加”直接改挂载 profile 并定向重启;只想快速核对,可临时 OPENCODE_CONFIG_CONTENT='{...}' opencode mcp list 或直接改容器内生效配置。
  • 服务健康(从 gisagent 容器网络):curl -s -o /dev/null -w "%{http_code}\n" http://<mcp服务名>:<内部端口>/health 返回 200(gisagent 镜像里有 curl,没有 wget)。
  • 对话可见:新建会话(旧会话缓存工具快照),向 Agent 询问它有哪些工具或直接触发该 MCP 能力。

常见问题

服务起了,但 Agent 里看不到工具? 确认 opencode.json 的 mcp.<id> 已登记,并且已进入生效载体 OPENCODE_CONFIG_CONTENT—— 要么经 package.sh 同步进 profile,要么按”已部署环境就地热加”直接改挂载 profile; 再确认已”重启 gisagent(+ agent-opencode)→ 新建会话”。只改仓库源文件而不热更/重打包, 运行实例读不到。 opencode mcp list 显示 connected,但 Web UI 聊天里 Agent 说工具不存在? 这是最常见的原因:Web UI 每个会话启动临时容器(gisagent-agent-opencode-<user>-<session>-<hash>), 不是长运行的 agent-opencode 容器。临时容器的 OPENCODE_CONFIG_CONTENT 来自 gisagent 挂载的 config/local/agent.local-*.json(→ /workspace/config/agent.json),不是仓库的 config/opencode/opencode.json。如果 agent.local-*.json 里的 OPENCODE_CONFIG_CONTENT 没有 包含你的 MCP,Web UI 会话就看不到工具。 开发机修复:更新 config/local/agent.local-*.json 的 OPENCODE_CONFIG_CONTENT(加入新 MCP), 然后 docker compose restart gisagent,再新建会话。不需要 package.sh (package.sh 仅用于离线 bundle 交付打包)。 目标机拉不到镜像(connection refused)? 离线机器没有 registry 访问。remote MCP 镜像必须先加入 package.sh 镜像清单被 docker save 导出, 部署时 docker load;运行期不联网。 端口起不来 / 服务不健康? 检查端口是否在预留段内、有无冲突(对照上文端口清单),以及 url 用的是服务名+内部端口而非 localhost(跨容器要用服务名)。若服务本身正常(手动请求 /health 返回 200)但 Docker 报 unhealthy,检查 healthcheck 命令用的工具在镜像里是否存在——例如 node:20-alpine 有 wget 没有 curl,healthcheck 要用 wget。 换了 Claude / Qwen 内核后工具没了? 只在 opencode.json 登记不够,还要在各 CLI 的 settings.json mcpServers 里对齐同一服务。 MCP 需要密钥? 走 config/local/secrets/<ENV_KEY> 或 ASE,用 ${env.X} 引用,绝不写死;纳入 verify-no-secret-literals.sh。

下一步

  • 想扩展技能而非工具:阅读如何添加自定义技能。
  • 独立 volume、联网判定等更复杂扩展场景:参考工程规范 openspecs/changes/docker-skill-mcp-extension/(含”验证台账 / 场景用例”,CASE-07 即 SKILL/MCP 热加的实测记录)。
  • 热更框架的分级模型(L0~L3)、manifest 契约与回滚语义:参考 openspecs/changes/docker-hot-update/。