mcp接口增加分页
This commit is contained in:
andy committed
1 parent
7243319bbb
commit
7f4adad7b1
16 files changed
+1157
-281
No files matched your search
@@ -2,7 +2,7 @@
|
||||
|
||||
| 项 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | Implemented；live readiness 与本地 7 tools/call 已通过；同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定启用/调用并作为兼容档案参照；公网 `/mcp` 已到达 Go，但旧版本门禁曾返回错误，消防服务按 proven-profile 兼容方式部署后仍需完成真实工具回调 |
|
||||
| 状态 | Implemented；live readiness 与分页改造前的本地 7 tools/call 已通过；分页代码和自动化已通过，分页版真实 PostGIS 查询待复验；同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定启用/调用并作为兼容档案参照，消防服务仍需完成公网真实工具回调 |
|
||||
| 日期 | 2026-09-05 |
|
||||
| Checkpoint | `fire-safety-ymd-superagent-mcp-proven-profile-compatibility`（基础空间工具契约沿用 v1） |
|
||||
| 需求来源 | 用户提供 8 张 PostgreSQL/PostGIS 表结构与每表 2 条样例，要求先基于现有数据建设 MCP |
|
||||
@@ -93,11 +93,43 @@ initialize 日志只记录 `direct_success`（客户端值为 `2025-06-18`）或
|
||||
|
||||
## 5. MCP 工具
|
||||
|
||||
除地名候选工具外，所有工具的坐标参数使用 WGS84：`longitude` 范围 `[-180, 180]`，`latitude` 范围 `[-90, 90]`。需要距离的工具接收 `radius_meters` 和 `limit`，同时有工具级默认值和硬上限。
|
||||
除地名候选工具外，所有工具的坐标参数使用 WGS84：`longitude` 范围 `[-180, 180]`，`latitude` 范围 `[-90, 90]`。需要距离的工具接收 `radius_meters`；七个工具均可选 `limit` 和 `offset`，并统一执行本节的分页契约。
|
||||
|
||||
### 5.0 统一分页契约
|
||||
|
||||
七个工具均接受可选的 `limit` 和 `offset`：
|
||||
|
||||
- `limit` 范围为 `1..20`，默认值按工具类别确定：地名候选、水源、指挥部候选、防火通道和风险区域默认为 `10`；防火网格和责任中队默认为 `20`。
|
||||
- `offset` 范围为 `0..10000`，默认值为 `0`。它表示在稳定排序结果中的零基偏移量，不是页码。
|
||||
- 未传入参数时仍保持各工具既有默认返回数量；传入超出范围或非整数值时返回 `INVALID_ARGUMENT`。
|
||||
- `data` 始终是数组，即使网格或责任中队通常只返回一条记录；无结果页也返回空数组，不使用 `null` 或对象替代。
|
||||
- 所有工具必须先应用服务端授权范围、空间条件、有效几何排除和其他业务过滤，再在完整有效结果上计算 `total_count`，最后按稳定排序执行 `offset`/`limit`。总量不得泄露授权范围外的记录。
|
||||
- 稳定排序沿用各工具的业务主排序（例如距离、匹配优先级）；主排序相同或距离相同时，必须使用资源类型和源记录 ID 等确定性字段作并列决胜，保证同一数据快照的分页不会重复或漏项。
|
||||
|
||||
统一成功响应的 `metadata` 为：
|
||||
|
||||
```json
|
||||
{
|
||||
"result_count": 10,
|
||||
"total_count": 27,
|
||||
"limit": 10,
|
||||
"offset": 0,
|
||||
"has_more": true,
|
||||
"next_offset": 10
|
||||
}
|
||||
```
|
||||
|
||||
字段语义如下：
|
||||
|
||||
- `result_count` 是当前页 `data` 数组的元素数量，不是全部匹配数。
|
||||
- `total_count` 是授权范围和全部有效过滤完成后、分页前的总数量。
|
||||
- `has_more` 在仍有下一页时为 `true`；等价于 `offset + result_count < total_count`。
|
||||
- `next_offset` 在 `has_more=true` 时为下一次请求应使用的偏移量（`offset + result_count`），末页为 `null`。
|
||||
- 只有 `total_count=0` 时 `status` 才能为 `no_results`。当 `total_count>0` 但 `offset` 超过末页时，响应仍为 `status=ok`、`data=[]`、`result_count=0`、`has_more=false`、`next_offset=null`。
|
||||
|
||||
### 5.1 `fire_safety_search_place_candidates`
|
||||
|
||||
输入 `place_name`（去除首尾空白后 2 至 100 字符）和可选 `limit`（默认 10、最大 20），在 8 张现有业务表的名称、镇街和村庄字段中做不区分大小写的文字包含匹配。百分号和下划线按普通文字处理，不作为 SQL 通配符。
|
||||
输入 `place_name`（去除首尾空白后 2 至 100 字符）以及可选分页参数，在 8 张现有业务表的名称、镇街和村庄字段中做不区分大小写的文字包含匹配。该工具默认 `limit=10`、`offset=0`，百分号和下划线按普通文字处理，不作为 SQL 通配符。
|
||||
|
||||
返回稳定资源类型、记录 ID、名称、镇街、村庄、命中字段、`exact | partial`、WGS84 坐标和 `location_kind`：
|
||||
|
||||
@@ -137,12 +169,17 @@ initialize 日志只记录 `direct_success`（客户端值为 `2025-06-18`）或
|
||||
```json
|
||||
{
|
||||
"status": "ok | no_results",
|
||||
"data": {},
|
||||
"data": [],
|
||||
"metadata": {
|
||||
"generated_at": "RFC3339 UTC",
|
||||
"data_sources": [],
|
||||
"spatial_reference": "EPSG:4326",
|
||||
"result_count": 0
|
||||
"result_count": 0,
|
||||
"total_count": 0,
|
||||
"limit": 10,
|
||||
"offset": 0,
|
||||
"has_more": false,
|
||||
"next_offset": null
|
||||
},
|
||||
"warnings": []
|
||||
}
|
||||
@@ -202,11 +239,12 @@ initialize 日志只记录 `direct_success`（客户端值为 `2025-06-18`）或
|
||||
- `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 限制地名长度、经纬度、半径、数量和未知字段；工具不接受授权身份参数。
|
||||
- 七个工具的 schema 都接受可选 `limit`/`offset`；默认值、`1..20` 的 `limit`、`0..10000` 的 `offset`、未知字段和非法分页值均有稳定校验，工具不接受授权身份参数。
|
||||
- 七个工具的成功响应都保持 `data` 数组，并返回 `result_count`、`total_count`、`limit`、`offset`、`has_more` 和 `next_offset`；`total_count` 在授权范围和全部过滤完成后、分页前计算，排序稳定，`no_results` 与超尾页语义符合统一契约。
|
||||
- Service 测试证明可信数据库全范围/镇街白名单来自构造时配置，并覆盖互斥校验、无结果、超时和仓储失败。
|
||||
- Repository 只使用参数化值，MCP 结果不包含联系人字段。
|
||||
- readiness 测试证明无效几何不阻塞启动、会产生排除 warning，且全部固定查询显式包含 `ST_IsValid`；SRID、类型和越界仍为硬失败。
|
||||
- 地名 Service/Repository 测试覆盖首尾空白、长度、控制字符、结果上限、服务端范围、8 张固定表和候选确认 warning。
|
||||
- 地名 Service 测试覆盖首尾空白、长度、控制字符、结果上限、分页元数据、超尾页、服务端范围和候选确认 warning；Repository 测试覆盖 8 张固定表、窗口总量、稳定排序、参数位置和空后续页辅助语义。其他六个工具覆盖默认分页、边界值、总量与当前页计数；真实连续分页待测试库验证。
|
||||
- readiness probe 不输出业务行、电话、负责人、DSN 或 SQL。
|
||||
- `gofmt`、`go test -count=1 ./...`、`go test -race -count=1 ./...` 和 `go vet ./...` 通过。
|
||||
|
||||
|
||||
Reference in new issue
Block a user