mcp修复

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` 或经审批的外部地理编码服务。
 - 路线规划需要的路网拓扑、路面/宽度/坡度/车辆限制、实时封路、火场和天气数据。