mcp修复

docs/project/integrations/superagent-mcp-client.example.json

@@ -3,13 +3,12 @@
   "mcpServers": {
     "fire-safety-ymd-spatial-readonly": {
       "transport": "http",
-      "protocolVersion": "2025-06-18",
       "url": "https://<fire-safety-server-domain>/mcp",
       "method": "POST",
       "headers": {
         "Authorization": "Bearer ${FIRE_SAFETY_MCP_AUTH_TOKEN}",
         "Content-Type": "application/json",
-        "Accept": "application/json"
+        "Accept": "application/json, text/event-stream"
       },
       "tools": {
         "allow": [
@@ -25,6 +24,7 @@
       },
       "runtimeNotes": {
         "authTokenSource": "Use a separate per-environment high-entropy secret; never reuse the SuperAgent Open API Key.",
+        "protocolCompatibility": "SuperAgent cannot configure protocolVersion here. The fire-safety-ymd server follows the proven th-hotel-simple-superagent compatibility profile: it does not use initialize.params.protocolVersion or MCP-Protocol-Version as version refusal gates and always returns protocolVersion 2025-06-18. This is a compatibility response, not support for arbitrary client versions or a latest-version target. Do not add a protocol-version or protocol-header setting.",
         "scopeSource": "The all or town-allowlist data scope is configured on the fire-safety-ymd server and is never supplied by tool arguments.",
         "safety": "Results are planning evidence only. Invalid source geometries are excluded, so results may be incomplete. Availability, passability, command-post suitability, live team positions and assembly sites require field confirmation."
       }

docs/project/integrations/superagent-mcp-spatial.md

@@ -2,9 +2,9 @@
 
 | 项 | 内容 |
 | --- | --- |
-| 状态 | 代码已实现；实库严格 readiness 与本地 7 工具冒烟已通过，公网/SuperAgent 联调待执行 |
+| 状态 | 代码已实现；实库严格 readiness 与本地 7 工具冒烟已通过；同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定启用/调用并作为兼容档案参照；公网 `/mcp` 已到达 Go，但旧版本门禁曾返回错误，消防服务的兼容档案仍需部署后按完整调用链重测 |
 | Endpoint | `POST /mcp` |
-| MCP 版本 | `2025-06-18` |
+| MCP 响应版本 | 固定返回 `2025-06-18` |
 | 传输 | 单 JSON 请求/响应；不提供服务端 SSE |
 | 数据源 | PostgreSQL/PostGIS，固定只读查询 |
 
@@ -20,6 +20,18 @@ flowchart LR
 
 SuperAgent Open API Key 用于本服务调用 SuperAgent；MCP Token 用于 SuperAgent 回调本服务。两者方向、权限和生命周期不同，必须使用不同 Secret。
 
+## SuperAgent 兼容档案
+
+SuperAgent 当前不能在 MCP 服务配置中填写或固定 `protocolVersion`；配置只需要 URL、HTTP 方法和独立 Bearer。已稳定接通的 `th-hotel-simple-superagent` 不读取 `initialize.params.protocolVersion`，也不读取或校验 `MCP-Protocol-Version` Header，而是固定返回 `2025-06-18`，并正常执行 `notifications/initialized`、`tools/list` 和 `tools/call`；工具结果同时提供 `structuredContent`。消防 MCP 按同一已验证档案接入，目标是打通工具调用，不是追求最新协议。
+
+本服务端固定返回 `2025-06-18`：
+
+- 可解析的 JSON-RPC `initialize` 中，`params.protocolVersion` 的缺失、空值、非字符串或其他值，都不单独触发版本拒绝，响应中的 `result.protocolVersion` 始终为 `2025-06-18`。
+- `MCP-Protocol-Version` Header 的缺失或值同样不作为版本拒绝门禁；SuperAgent 配置中无需增加该 Header 或任何版本字段。
+- 固定返回 `2025-06-18` 不表示服务实现或声明支持客户端填写的任意版本，也不把 `2025-03-26`、`2025-11-25` 列为实现目标；这是为了兼容已稳定接通的客户端。
+
+上述兼容只放宽版本元数据，不放宽 HTTP 方法、JSON-RPC 结构、独立 Bearer、`Content-Type`、非空 `Origin`、工具 schema、只读 SQL、服务端数据范围或字段脱敏边界。日志仅记录 `direct_success`（客户端值恰为 `2025-06-18`）或 `compatibility_success`（版本字段缺失或其他值被兼容处理），不记录客户端原始版本值。
+
 ## 首版工具
 
 | 工具 | 数据表 | 能回答 | 不能回答 |
@@ -119,11 +131,27 @@ FIRE_SAFETY_MCP_ENABLED=true
 curl -sS http://127.0.0.1:8080/mcp \
   -H "Authorization: Bearer ${FIRE_SAFETY_MCP_AUTH_TOKEN}" \
   -H 'Content-Type: application/json' \
-  -H 'Accept: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual-probe","version":"1"}}}'
 ```
 
-随后发送 `notifications/initialized`、`tools/list` 和受控测试地名/坐标的 `tools/call`。联调不得使用真实火情或未授权精确坐标。
+初始化响应中的 `result.protocolVersion` 应固定为 `2025-06-18`。后续请求不需要携带协议版本 Header；如果客户端自行携带，服务端也不以其值作为版本拒绝条件：
+
+```bash
+curl -sS http://127.0.0.1:8080/mcp \
+  -H "Authorization: Bearer ${FIRE_SAFETY_MCP_AUTH_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+
+curl -sS http://127.0.0.1:8080/mcp \
+  -H "Authorization: Bearer ${FIRE_SAFETY_MCP_AUTH_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
+```
+
+再发送受控测试地名/坐标的 `tools/call`，同样无需配置或携带版本 Header。SuperAgent 的真正验收顺序是 `initialize` → `notifications/initialized`（HTTP 202）→ `tools/list`（7 个固定工具）→ 至少一个受控只读 `tools/call`；只看到 initialize 成功不能宣称 MCP 已接通。联调不得使用真实火情或未授权精确坐标。
 
 SuperAgent 侧配置模板见 [`superagent-mcp-client.example.json`](superagent-mcp-client.example.json)。
 
@@ -140,7 +168,8 @@ SuperAgent 侧配置模板见 [`superagent-mcp-client.example.json`](superagent-
 ## 当前联调门禁
 
 - 样例 SQL 不可执行，也不可提交；其中包含破坏性 DDL 和受限联系人数据。
-- 2026-09-05 已完成受控 SRID 元数据迁移和严格 audit：8 表共 4,055 条记录，4,048 条非空几何均为 SRID 4326，SRID/类型/范围硬门禁通过。7 条空几何、35 条无效面几何以及 7 张缺 GiST 索引表仍按预期告警；真实 `tools/call` 尚未执行，因此当前仍不能宣称 MCP 的业务结果已经联调验证。
+- 2026-09-05 已完成受控 SRID 元数据迁移和严格 audit：8 表共 4,055 条记录，4,048 条非空几何均为 SRID 4326，SRID/类型/范围硬门禁通过。7 条空几何、35 条无效面几何以及 7 张缺 GiST 索引表仍按预期告警；本地实库 7 个 `tools/call` 已执行并通过，但公网 SuperAgent `tools/call` 尚未执行，因此当前仍不能宣称公网 MCP 业务联调完成。
+- 用户提供的 SuperAgent 现场截图证明公网 `/mcp` 请求已经到达 Go 服务，Bearer、`Content-Type` 和 JSON-RPC 前置校验通过；随后旧版本门禁返回错误。该历史截图没有捕获客户端版本字段是否存在、类型和值。同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定调用是兼容档案的参照，但不是消防 MCP 的成功证据；部署后仍需观察 `direct_success` 或 `compatibility_success`，并完成 initialize → initialized → tools/list → 至少一个 tools/call。
 - 缺少适用于距离表达式的 GiST 索引时可做小数据开发联调，但生产前必须补齐并验证查询计划。
 - 地名包含匹配当前没有专用名称索引；真实数据量下先验证查询耗时，后续再决定标准地名表、别名词典或 `pg_trgm` 索引。
 - 用户身份、动态区域授权和持久审计仍是后续 checkpoint；当前一个 MCP Token 只对应一个静态数据库全范围或镇街白名单。
@@ -150,7 +179,7 @@ SuperAgent 侧配置模板见 [`superagent-mcp-client.example.json`](superagent-
 服务仅监听 `127.0.0.1:18080`，使用运行时只读 PostGIS 账号和显式 `all` 数据范围完成测试；未输出联系人、完整业务记录或测试坐标。
 
 - `GET /health` 返回 200；无 Token 的 `POST /mcp` 返回 401。
-- `initialize` 协商 MCP `2025-06-18`；initialized notification 返回 202；`tools/list` 返回全部 7 个工具。
+- `initialize` 固定返回 MCP `2025-06-18`；版本字段/Header 不作为拒绝门禁，initialized notification 返回 202；`tools/list` 返回全部 7 个工具，并至少完成一个受控 `tools/call`。该记录仍需目标机和真实消防 Profile 提供公网证据。
 - 使用“观水镇”得到 10 个地点候选，并选取一个精确匹配的 `recorded_point` 蓄水池记录，仅作为获授权测试坐标。
 - 网格上下文返回 1 条；水源、指挥部候选和通道各返回 10 条；责任中队返回 1 条；风险区域返回 9 条。
 - 7 个响应的 `structuredContent` 与文本 JSON 投影一致，空间参考均为 EPSG:4326，计数与数据数组一致，不包含已禁止的联系人类字段键。

docs/project/operations/docker-test-deployment.md

@@ -6,7 +6,7 @@
 | 运行方式 | 宿主机 Nginx 终止 HTTPS，Docker Compose 运行单个 Go 服务 |
 | 应用监听边界 | 容器内监听 8080，只发布到宿主机 127.0.0.1:16587 |
 | 数据库 | 使用现有 PostgreSQL/PostGIS；本手册不创建数据库容器、不导入 SQL |
-| 状态 | 测试环境部署基线；目标服务器、公网 DNS/TLS 和 SuperAgent 回调仍需现场验证 |
+| 状态 | 测试环境部署基线；目标机镜像构建和 Nginx 语法检查已由现场截图证明通过，但容器稳定运行、公网 TLS 和 SuperAgent MCP 握手/工具回调仍待重测 |
 
 本手册不包含真实 Token、API Key、数据库密码或旧 Nginx 配置内容。命令中的尖括号是服务器上需要替换的占位符；不要把 Secret 写进命令行、Nginx 文件、镜像构建参数或 Git。
 
@@ -305,9 +305,28 @@ Method: POST
 Authorization: Bearer <FIRE_SAFETY_MCP_AUTH_TOKEN>
 ~~~
 
-该 Bearer 必须是 .env 中独立的 FIRE_SAFETY_MCP_AUTH_TOKEN，不要填 Chat xtoken 或 SuperAgent Open API Key。SuperAgent 还可能需要公网来源 IP 白名单、TLS CA 或自定义 Header，按实际平台和网络策略确认。
+该 Bearer 必须是 .env 中独立的 FIRE_SAFETY_MCP_AUTH_TOKEN，不要填 Chat xtoken 或 SuperAgent Open API Key。SuperAgent 当前不能在配置中指定 `protocolVersion`；不要把它或 `MCP-Protocol-Version` 作为客户端配置项加入。已稳定接通的 `th-hotel-simple-superagent` 不读取或校验这些版本元数据，而是固定返回 `2025-06-18`；消防 MCP 按这一已验证兼容档案接入，目标是打通工具调用，不是追求最新协议。SuperAgent 还可能需要公网来源 IP 白名单、TLS CA 或其他平台级 Header，按实际平台和网络策略确认。
 
-在服务器或受控终端用独立变量测试初始化：
+服务端兼容规则如下：对可解析的 JSON-RPC `initialize`，`params.protocolVersion` 的缺失、空值、非字符串或其他值都不作为版本拒绝条件，响应固定返回 `result.protocolVersion: "2025-06-18"`；`MCP-Protocol-Version` Header 的缺失或值也不作为版本拒绝条件。固定返回该版本不表示服务实现或声明支持任意客户端版本，`2025-03-26`、`2025-11-25` 等值也不改变服务端实现目标。兼容仅针对版本元数据，Bearer、`Content-Type`、非空 `Origin`、JSON-RPC 结构、只读工具、服务端数据范围和敏感字段边界仍严格执行。
+
+现场截图只证明公网 `/mcp` 已到达 Go 服务：Bearer、`Content-Type` 和 JSON-RPC 前置检查已通过，随后旧版本门禁返回错误。该历史截图没有捕获客户端版本字段是否存在、类型和值；同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定调用是兼容档案参照，但不是消防 MCP 成功证据。部署后通过 `direct_success`（客户端值为 `2025-06-18`）或 `compatibility_success`（版本字段缺失或其他值被兼容处理）日志分类确认，并完成完整调用链；服务端不得记录原始版本值。公网 SuperAgent 尚未调用消防数据库工具，因此不能把该截图当成公网部署或业务联调完成。
+
+如果修改了 MCP Handler 或握手协商逻辑，目标机必须拉取包含该修改的明确 revision 后重建镜像；仅 `docker compose restart` 不会更新镜像中的代码：
+
+~~~bash
+cd /home/firee-safety-ymd
+git fetch --prune origin
+git switch main
+git pull --ff-only origin main
+docker compose config --quiet
+docker compose build --pull
+docker compose up -d --force-recreate --remove-orphans
+docker compose ps
+docker compose logs --tail=100 api
+curl --fail http://127.0.0.1:16587/health
+~~~
+
+在服务器或受控终端用独立变量测试初始化。下面的版本字段只是普通 JSON-RPC 参数示例，SuperAgent 不需要配置它；也可以省略或使用客户端实际发送的值：
 
 ~~~bash
 read -rsp 'MCP bearer: ' MCP_BEARER
@@ -315,23 +334,33 @@ printf '\n'
 curl --fail \
   -H "Authorization: Bearer $MCP_BEARER" \
   -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
   --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual-probe","version":"1"}}}' \
   'https://agent.nianxx.com/mcp'
 
 curl --fail --output /dev/null --write-out 'initialized HTTP %{http_code}\n' \
   -H "Authorization: Bearer $MCP_BEARER" \
   -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
   --data '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
   'https://agent.nianxx.com/mcp'
 
 curl --fail \
   -H "Authorization: Bearer $MCP_BEARER" \
   -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
   --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
   'https://agent.nianxx.com/mcp'
+
+curl --fail \
+  -H "Authorization: Bearer $MCP_BEARER" \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fire_safety_search_place_candidates","arguments":{"place_name":"观水镇","limit":3}}}' \
+  'https://agent.nianxx.com/mcp'
 ~~~
 
-确认第一步返回 `protocolVersion: 2025-06-18`，第二步返回 HTTP 202，第三步列出 7 个固定工具；再用无敏感信息的已知地名/点位做少量只读调用，核对正确 Bearer 成功、错误/缺失 Bearer 为 401、warnings 保留、非法参数不会变成任意 SQL。查询到资源记录不代表实时可用、路线已规划或正式集结点。
+确认第一步固定返回 `result.protocolVersion: 2025-06-18`，第二步返回 HTTP 202，第三步列出 7 个固定工具，第四步至少完成一个受控只读 `tools/call`。这四步 `initialize` → `notifications/initialized` → `tools/list` → `tools/call` 才是 SuperAgent 能调用消防 MCP 的验收链路；只看到 initialize 成功不能宣称接通。版本 Header 不需要配置或继续携带。再用无敏感信息的已知地名/点位做少量只读调用，核对正确 Bearer 成功、错误/缺失 Bearer 为 401、warnings 保留、非法参数不会变成任意 SQL。查询到资源记录不代表实时可用、路线已规划或正式集结点。
 
 完成 MCP 测试后清理当前 shell 中的临时变量：
 
@@ -408,7 +437,7 @@ docker compose down
 - 目标机 nginx -t 和 reload 成功；443 证书、DNS、安全组及旧 location / 已确认不再生效。
 - Chat 首轮/多轮 SSE、错误凭证、未知 app/path 的实际 HTTPS 响应。
 - 若为已交付旧客户端临时开启 Chat legacy 短凭证兼容，应记录受控迁移窗口，确认启动 warning 不含 Secret，并在凭证轮换后恢复 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false`。
-- SuperAgent -> /mcp 的独立 Bearer、TLS/网络白名单、工具发现和至少一个受控只读工具调用。
+- SuperAgent -> `/mcp` 的独立 Bearer、TLS/网络白名单、无版本配置 initialize 兼容响应、`notifications/initialized`、`tools/list` 和至少一个受控只读 `tools/call`。版本字段/Header 不作为配置或拒绝门禁；公网请求到达但没有完成这条调用链，不算完成。
 - 数据库未公开 5432，运行账号保持只读，PostGIS readiness warning 和 35 条无效面几何缺口已记录。
 
 若目标服务器无法使用 host.docker.internal、Compose 不支持 --quiet、Nginx include 目录不同、证书路径不同或 SuperAgent 对 MCP 的认证格式不同，应先记录实际环境并调整部署 Spec；不要通过放开端口、写入 Token、关闭 readiness 或恢复全路径反代规避问题。