mcp修复

docs/architecture/spatial-mcp-v1.md

@@ -4,14 +4,22 @@
 
 首版 MCP 内嵌在现有 Go 服务中，使用标准库实现 HTTP/JSON-RPC 协议层，使用 `pgx/v5` 原生连接池访问 PostgreSQL/PostGIS。没有引入 MCP SDK、Web 框架或 ORM。
 
-采用这一边界是因为当前只需要 SuperAgent 已验证的 `2025-06-18` 四个方法和同步 JSON 响应；业务复杂度位于固定空间查询、权限范围和安全语义，而不是协议框架。
+采用这一边界是因为当前只需要与不能配置协议版本的 SuperAgent 客户端协作：服务端实际提供 `2025-06-18` 版本标识、四个方法和同步 JSON 响应；版本字段和 Header 按已稳定接通的 SuperAgent 兼容档案处理，不作为拒绝门禁。业务复杂度位于固定空间查询、权限范围和安全语义，而不是协议框架。
+
+## SuperAgent 兼容档案
+
+同一 SuperAgent 中已稳定启用的 `th-hotel-simple-superagent` 服务不会读取 `initialize.params.protocolVersion`，也不会读取或校验 `MCP-Protocol-Version` Header；它固定返回 `2025-06-18`，并正常处理 `notifications/initialized`、`tools/list` 与 `tools/call`。本项目对齐这一已验证的接入方式，目标是让 SuperAgent 能调用消防 MCP，而不是追求最新 MCP 版本。
+
+`initialize.params.protocolVersion` 的缺失、空值、非字符串或其他值，不单独触发版本拒绝；可解析的 JSON-RPC initialize 始终返回 `result.protocolVersion: "2025-06-18"`。`MCP-Protocol-Version` Header 同样不作为拒绝门禁，SuperAgent 配置中无需增加版本或 Header 项。服务端并不因此实现或声明支持客户端填写的任意版本，也不把 `2025-03-26`、`2025-11-25` 等版本列为实现目标；固定返回 `2025-06-18` 是兼容响应。
+
+上述兼容仅针对版本元数据。HTTP 方法、JSON-RPC 结构、独立 Bearer、`Content-Type`、非空 `Origin`、工具 schema、只读查询、服务端数据范围和结果脱敏等安全及业务边界仍由 Handler、Service 和 Repository 强制执行。initialize 结果可按实际字段记录 `direct_success`（值为 `2025-06-18`）或 `compatibility_success`（缺失或其他值被兼容处理），不得记录原始版本值。
 
 ## 模块关系
 
 ```mermaid
 flowchart TD
     APP["internal/app\n依赖装配与 readiness"]
-    H["internal/handler\nBearer、JSON-RPC、schema、限流边界"]
+    H["internal/handler\nBearer、JSON-RPC、握手协商、schema、限流边界"]
     S["internal/service\n查询边界、超时、结果语义"]
     D["internal/domain\n稳定空间领域对象"]
     R["internal/repository\npgxpool、固定参数化 PostGIS SQL"]

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 或恢复全路径反代规避问题。

docs/specs/fire-safety-ymd-superagent-mcp-spatial-readonly-v1.md

@@ -2,9 +2,9 @@
 
 | 项 | 内容 |
 | --- | --- |
-| 状态 | Implemented；live readiness 与本地 7 tools/call 已通过，SuperAgent 回调待联调 |
+| 状态 | Implemented；live readiness 与本地 7 tools/call 已通过；同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定启用/调用并作为兼容档案参照；公网 `/mcp` 已到达 Go，但旧版本门禁曾返回错误，消防服务按 proven-profile 兼容方式部署后仍需完成真实工具回调 |
 | 日期 | 2026-09-05 |
-| Checkpoint | `fire-safety-ymd-superagent-mcp-spatial-readonly-v1` |
+| Checkpoint | `fire-safety-ymd-superagent-mcp-proven-profile-compatibility`（基础空间工具契约沿用 v1） |
 | 需求来源 | 用户提供 8 张 PostgreSQL/PostGIS 表结构与每表 2 条样例，要求先基于现有数据建设 MCP |
 
 ## 1. 背景与已核对输入
@@ -29,11 +29,12 @@ SQL 文件仅作为结构和数据契约参考。文件包含 `DROP TABLE` 等
 - 样例几何十六进制是未携带 SRID 的 WKB；坐标数值及水源表独立经纬度字段看起来符合 WGS84，但这只能作为待验证线索。
 - 样例 DDL 只有防火网格明确包含 GiST 几何索引。
 - 多张表含姓名、电话等受限字段；首版 MCP 不返回这些字段。
+- 用户提供的 SuperAgent 现场截图显示公网 `/mcp` 请求已经到达 Go 服务，Bearer、`Content-Type` 和 JSON-RPC 前置校验通过，随后旧版本门禁返回错误；截图没有捕获客户端版本字段是否存在、类型和值。同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定启用/调用，这是兼容档案的现场参照，但消防 MCP 尚未完成公网数据库工具调用。
 
 ## 2. 目标
 
 - 在现有 Go HTTP 服务内提供默认关闭的 `POST /mcp`。
-- 与已经验证的 SuperAgent 配置保持兼容，采用 MCP `2025-06-18`、JSON-RPC 2.0 和单请求 JSON 响应。
+- 与不能配置协议版本的 SuperAgent 客户端保持兼容：服务端固定返回 MCP `2025-06-18`，对齐已稳定接通的 `th-hotel-simple-superagent` compatibility profile；initialize 中的版本字段和后续协议 Header 都不作为拒绝门禁。使用 JSON-RPC 2.0 和单请求 JSON 响应，目标是打通工具调用而不是追求最新协议。
 - 通过独立 Bearer Token 鉴权；不得复用 SuperAgent Open API Key。
 - 只提供固定、参数化、只读、按服务端可信数据范围执行的空间查询工具；默认使用镇街白名单，数据库全范围必须显式启用。
 - 支持在现有业务记录中按地名搜索有界候选，让没有坐标的用户先确认一个候选，再进入距离和包含关系查询。
@@ -61,7 +62,15 @@ SQL 文件仅作为结构和数据契约参考。文件包含 `DROP TABLE` 等
 - `tools/list`
 - `tools/call`
 
-服务端声明协议版本 `2025-06-18` 和 `tools` capability。首版是无会话、非流式的 Streamable HTTP 子集：`POST` 返回 `application/json`；`GET /mcp` 返回 `405 Method Not Allowed`。
+服务端固定返回协议版本标识 `2025-06-18` 和 `tools` capability。首版是无会话、非流式的 Streamable HTTP 子集：`POST` 返回 `application/json`；`GET /mcp` 返回 `405 Method Not Allowed`。
+
+#### SuperAgent compatibility profile
+
+服务端固定返回 `result.protocolVersion=2025-06-18`，但不把客户端版本字段当作版本协商或拒绝依据：可解析的 JSON-RPC `initialize` 中，`params.protocolVersion` 可以缺失、为空、为非字符串或为其他值，均不单独触发版本错误。`MCP-Protocol-Version` Header 可以缺失或携带任意值，也不作为版本拒绝门禁；SuperAgent 配置中不需要填写版本字段或 Header。
+
+固定返回 `2025-06-18` 不表示服务实现或声明支持客户端填写的任意版本，也不把 `2025-03-26`、`2025-11-25` 等值列为实现目标。该 profile 只为兼容已稳定接通的 SuperAgent 客户端，版本字段/Header 之外的 HTTP 方法、JSON-RPC 结构、鉴权、Origin、Content-Type、工具 schema、只读数据范围和敏感字段边界仍严格执行。
+
+initialize 日志只记录 `direct_success`（客户端值为 `2025-06-18`）或 `compatibility_success`（版本字段缺失或其他值被兼容处理），不记录客户端原始版本值。
 
 ### 4.2 入站控制
 
@@ -69,6 +78,7 @@ SQL 文件仅作为结构和数据契约参考。文件包含 `DROP TABLE` 等
 - 只接受 `Content-Type: application/json`。
 - 使用 `Authorization: Bearer <FIRE_SAFETY_MCP_AUTH_TOKEN>`，常量时间比较。
 - Token 至少 32 个可打印 ASCII 字符，且不能等于 SuperAgent Open API Key。
+- 初始化响应固定返回 `protocolVersion: 2025-06-18`；请求 body 中的 `protocolVersion` 以及 `MCP-Protocol-Version` Header 均为兼容元数据，不作为拒绝门禁。SuperAgent 配置不需要增加版本字段或 Header。
 - 请求体默认最大 256 KiB，最大可配置 1 MiB。
 - 首版只接受服务到服务请求；带非空 `Origin` 的请求拒绝，避免浏览器和 DNS rebinding 风险。
 - 不接受模型提供的用户、角色、租户或授权范围。范围模式和可选镇街列表只来自服务端配置。
@@ -190,6 +200,8 @@ SQL 文件仅作为结构和数据契约参考。文件包含 `DROP TABLE` 等
 - MCP 启用但 Token、合法范围、PostGIS 或显式 SRID 缺失时配置加载失败；`all` 与非空镇街列表同时出现时失败，错误不含 Secret。
 - 无 Token、错误 Token、错误 Content-Type、非空 Origin、超大 body 和非法 JSON 均被稳定拒绝。
 - `initialize`、initialized notification、`tools/list` 和 7 个 `tools/call` 契约通过本地测试。
+- `initialize` 对客户端版本字段缺失、空值、非字符串、`2025-06-18` 或其他值均固定返回 `2025-06-18`；版本字段和 `MCP-Protocol-Version` Header 不作为拒绝门禁。服务端不宣称支持任意其他版本，也不追求最新版本；日志按 `direct_success`/`compatibility_success` 分类且不包含原始版本值。
+- 真实 SuperAgent 验收必须在部署后依次出现 `initialize` → `notifications/initialized`（HTTP 202）→ `tools/list`（7 个固定工具）→ 至少一个受控只读 `tools/call`；只有 initialize 成功不能宣称 MCP 已接通。
 - 工具 schema 限制地名长度、经纬度、半径、数量和未知字段；工具不接受授权身份参数。
 - Service 测试证明可信数据库全范围/镇街白名单来自构造时配置，并覆盖互斥校验、无结果、超时和仓储失败。
 - Repository 只使用参数化值，MCP 结果不包含联系人字段。
@@ -203,7 +215,8 @@ SQL 文件仅作为结构和数据契约参考。文件包含 `DROP TABLE` 等
 - 实库源 CRS 已由数据提供方确认为 EPSG:4326 且无偏移；2026-09-05 已通过单独审核、显式确认和单事务迁移为 4,048 条非空几何补齐 SRID 4326，严格 readiness 已通过。重新导入无 SRID 的原始 SQL 时仍必须重新经过该流程，应用查询不得静默赋值。
 - 实库 35 条无效面几何按首版决策排除；需评估由此造成的网格、责任单位和风险区域覆盖缺口是否满足生产要求。
 - 各资源状态字段的枚举、更新时间含义和数据刷新责任人。
-- MCP 回调网络地址、TLS、SuperAgent 实际 Header 行为及 Token 轮换方式。
+- MCP 回调网络地址、TLS、SuperAgent Token 轮换方式及真实工具权限。
+- SuperAgent 无法配置协议版本；proven-profile 兼容响应、`notifications/initialized`、`tools/list` 和真实 `tools/call` 仍待目标机重建后确认。是否发送 `MCP-Protocol-Version` 不影响版本兼容验收。
 - 最终用户身份、区域权限、精确位置权限和审计保留策略。
 - 真实数据量下地名重复率、字段质量和无索引包含搜索性能；后续是否引入标准地名表、别名词典、`pg_trgm` 或经审批的外部地理编码服务。
 - 路线规划需要的路网拓扑、路面/宽度/坡度/车辆限制、实时封路、火场和天气数据。