> ## Documentation Index
> Fetch the complete documentation index at: https://gisagent.mapgis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 添加自定义 MCP

> 在 GIS Agent（含离线部署）中新增一个自定义 MCP（Model Context Protocol）服务的教程：remote HTTP 与 local/stdio 两种形态、镜像内置、端口预留、opencode.json 与各 CLI settings.json 登记、secret 卫生、离线部署、L1 热更新与验证。

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

MCP（Model Context Protocol）给 Agent 挂载"工具 / 数据源"。本教程说明如何在 GIS Agent 中新增
一个自定义 MCP，适用于本机开发环境与**离线 / 内网**部署。

与[添加自定义技能](https://gisagent.mapgis.com/docs/custom-skill-tutorial.md)不同，MCP 的生效面更窄也更专：它只影响 Agent
工具列表，**没有"技能市场"那种文件遍历展示**。所以理解 MCP 只需要抓住一条链路——
"登记 → 打包同步（或 L1 热更下发）→ 运行实例读取"。

## 先选择形态

GIS Agent 支持两种 MCP，按需选一种：

| 形态 | 典型例子 | 运行方式 | 何时用 |
| - | - | - | - |
| **remote HTTP** | 内置的 `knowledgecli` | 独立容器/服务，通过 `http://<服务>:<端口>/mcp` 访问 | 有服务端、需常驻、可多 Agent 共享 |
| **local / stdio** | 内置的 `personal-knowledge-mcp` | 打进包、以标准输入输出在 Agent 容器内本地拉起 | 单文件/轻量、随进程起、不需要网络端口 |

> 下面以内置的 `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 生效链路（一条）

```text theme={null}
MCP 服务（remote 镜像 / stdio npm 包）
  └─ package.sh：镜像进清单导出 docker save / stdio 包 copy_tree_contents_excluding + sanitize
       └─ Compose：remote 起独立服务（内网端口）/ stdio 挂载进 agent 容器
            └─ config/opencode/opencode.json  mcp.<id>
                 └─ rewrite_staged_agent_model_config → OPENCODE_CONFIG_CONTENT.mcp
                      └─ ACP 运行实例实时读取（对话内可见该 MCP 的工具）
            └─ 各 CLI settings.json 的 mcpServers 指向同一服务（.claude/.qwen/.qoder）
```

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

***

## 形态一：新增一个 remote HTTP MCP（推荐路径）

参照内置 `knowledgecli`：`opencode.json` 里就是

```json theme={null}
{ "mcp": { "knowledgecli": { "type": "remote", "url": "http://knowledge-mcp-http:18088/mcp", "enabled": true } } }
```

对应 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` 加服务

```yaml theme={null}
  hello-mcp:
    image: hello-mcp:latest
    build:
      context: ./gisagent/custom/mcp/hello-mcp        # 模板工程目录
      dockerfile: Dockerfile
    container_name: hello-mcp
    restart: unless-stopped
    ports:
      - "18090:18090"                        # 预留段内、不与上表冲突
    networks:
      - gisagent-network                     # 与其它服务同内网即可，不必对外发布
    environment:
      - HELLO_MCP_PORT=18090
      - HELLO_MCP_ENDPOINT=/mcp
      - NODE_ENV=production
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:18090/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
```

> 若源目录路径可能需要可移植（离线 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` 下新增一项：

```json theme={null}
{
  "mcp": {
    "knowledgecli": { "type": "remote", "url": "http://knowledge-mcp-http:18088/mcp", "enabled": true },
    "hello": { "type": "remote", "url": "http://hello-mcp:18090/mcp", "enabled": true }
  }
}
```

`url` 用**服务名 + 内部端口**（Docker 内网解析），不是 `localhost`。

### 5. 对齐各 CLI 的 `mcpServers`

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

### 6. 打包并生效

```bash theme={null}
./package.sh          # 同步 opencode.json 的 mcp → OPENCODE_CONFIG_CONTENT，导出镜像
# 目标机部署后：重启 gisagent → 重建该用户运行实例 → 新建会话
```

***

## 形态二：新增一个 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：手工热更（步骤少，适合一次性调试）

```bash theme={null}
cd /opt/gisagent/<你的-bundle-目录>

# 1) 载入服务镜像（若有）并起服务（bundle compose 已含该服务时）
docker load -i images/hello-mcp.tar
docker compose up -d hello-mcp

# 2) 从 gisagent 容器网络确认服务可达（端口换成你的；gisagent 镜像里有 curl，没有 wget）
docker exec mapgis-ai-gisagent sh -lc 'curl -s -o /dev/null -w "http_code=%{http_code}\n" http://hello-mcp:18090/health'

# 3) 备份后，在挂载 profile config/local/agent.local-*.json 的
#    runtime.env.OPENCODE_CONFIG_CONTENT（一段内嵌 JSON 字符串）的 mcp 里
#    增加一项：{"hello": {"type": "remote", "url": "http://hello-mcp:18090/mcp", "enabled": true}}
#    agent-opencode 与 agent-claude 两个块都要加

# 4) 只定向重启生效的两个服务，不动其它容器
docker compose restart gisagent agent-opencode
```

### 方式 B：热更包（推荐，自动备份 + 健康闸门 + 失败自动回滚）

`docker-hot-update` 框架把更新分为 L0\~L3：**L0** 免重启刷卷（用于 SKILL 同步），**L1** 配置
热更（MCP 注册就是这一层），**L2** 单镜像热更，**L3** 全量 bundle 冷更。

开发机改好 profile 后打包（`scripts/package-hotfix.sh`）：

```bash theme={null}
bash scripts/package-hotfix.sh --layer L1 \
  --config config/local/agent.local-qwen-fable.json:config/local/agent.local-qwen-fable.json \
  --restart gisagent,agent-opencode \
  --http-check http://<GISAgent主机>:17076/gis/:200
# 产物: dist/hotfix/gisagent-hotfix-L1-<日期>-<序号>.tar.gz
```

把该 tar 包传到目标机执行（新版 bundle 已内置 `scripts/hot-update.sh`，`package.sh` 自
2026-09-23 起同步拷贝；旧 bundle 把该脚本单独拷进栈目录即可；执行机需 `python3` +
PyYAML 解析 manifest）：

```bash theme={null}
bash scripts/hot-update.sh \
  --package gisagent-hotfix-L1-<日期>-<序号>.tar.gz \
  --stack-dir /opt/gisagent/<你的-bundle-目录>
```

执行器流程：解包校验 → 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）：

  ```bash theme={null}
  docker exec agent-opencode sh -lc 'cd /workspace && opencode mcp list'
  ```

  每个服务会带 `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`。

## 下一步

* 想扩展技能而非工具：阅读[如何添加自定义技能](https://gisagent.mapgis.com/docs/custom-skill-tutorial.md)。
* 独立 volume、联网判定等更复杂扩展场景：参考工程规范
  `openspecs/changes/docker-skill-mcp-extension/`（含"验证台账 / 场景用例"，CASE-07 即
  SKILL/MCP 热加的实测记录）。
* 热更框架的分级模型（L0\~L3）、manifest 契约与回滚语义：参考
  `openspecs/changes/docker-hot-update/`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.