213 lines
9.2 KiB
Markdown
213 lines
9.2 KiB
Markdown
# xiaoqu-agent-service MCP 工具接口文档
|
||
|
||
> 本文档是 MCP 服务**对外暴露工具**的接口契约。新增/修改工具时必须同步更新本文档（开发约定见 `agent-mcp-service-design.md` §12）。
|
||
> 文档中的入参与代码 `@ToolParam`、出参与工具实际返回保持一致；在线验证方式见文末附录。
|
||
|
||
## 0. 调用约定（所有工具共用）
|
||
|
||
| 项 | 说明 |
|
||
|---|---|
|
||
| 端点 | `POST http://<host>:8088/mcp`（MCP Streamable HTTP） |
|
||
| 认证 | Header `Authorization: Bearer xqak_xxx`，Token 由管理后台或受信任 Open API 获取；服务端保存 SHA-256 及加密密文 |
|
||
| 工具可见性 | `tools/list` 按 ak 作用域过滤，只返回该 ak 作用域并集内且启用状态的工具（2026-09-04 起，服务端 servlet 层重写响应实现）；`tools/call` 另有强制校验兜底，越权返回可读拒绝信息并落审计（denied） |
|
||
| 行级数据权限 | 跟 ak 所属人走，照搬老系统 `getByIsAgent` 语义（见设计文档 §3.3），与作用域无关 |
|
||
| 分页 | 列表类工具统一 `page`（从 1 开始，默认 1）、`rows`（默认 20，**上限 100**，超出截断为 100 并在返回 `notice` 字段提示） |
|
||
| 分页出参 | 统一含 `total`（总数）、`page`、`rows`、`records`（本页记录）、`notice`（仅截断时出现） |
|
||
|
||
---
|
||
|
||
## 1. agent.count
|
||
|
||
统计代理商总数（demo 工具）。
|
||
|
||
- 分类：system ｜ 类型：读
|
||
- 数据来源：m0 库 `agent` 表，固定条件 `soft_delete = 0`
|
||
|
||
**入参**：无
|
||
|
||
**出参**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| count | number | 代理商总数 |
|
||
|
||
```json
|
||
{ "count": 62 }
|
||
```
|
||
|
||
---
|
||
|
||
## 2. agent.list.query
|
||
|
||
查询代理商列表（分页），对应老系统 `/agent/listByPage`。
|
||
|
||
- 分类：customer ｜ 类型：读
|
||
- 数据来源：m0 库 `agent` 表
|
||
- 行级权限：权限组 `isagent=1`（代理商身份）只查自己名下直属下级（`supervisor_id = 自己agentId`）；`isagent=0`（总部）看全部。传 `id` 精确查询时：代理商仅限自己或直属下级，总部可传任意合法 id，且其余过滤条件失效。
|
||
|
||
**入参**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| id | number | 否 | 代理商 id，精确查询；传入后忽略其他过滤条件 |
|
||
| name | string | 否 | 代理商名称，模糊匹配 |
|
||
| level | number | 否 | 级别：0=总部 1=一级 2=二级 |
|
||
| channelNo | string | 否 | 渠道编号：Z=总部 F=分公司 D=代理 |
|
||
| province | string | 否 | 省份，精确匹配，如 `北京市` |
|
||
| city | string | 否 | 城市，精确匹配，如 `北京市` |
|
||
| serialnumber | string | 否 | 代理商编号，精确匹配 |
|
||
| page | number | 否 | 页码，从 1 开始，默认 1 |
|
||
| rows | number | 否 | 每页条数，默认 20，上限 100 |
|
||
|
||
**出参 records 字段**：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| id / name | 代理商 id / 名称 |
|
||
| level / channelNo / serialnumber | 级别 / 渠道编号 / 代理商编号 |
|
||
| supervisorName | 上级代理名称（无上级为 `-`，批量富化） |
|
||
| province / city / countyseat | 省 / 市 / 区县 |
|
||
| contact / phone | 联系人 / 电话 |
|
||
| agencyarea / memo | 代理区域 / 备注 |
|
||
| createTime | 创建时间，`yyyy-MM-dd HH:mm:ss` |
|
||
|
||
```json
|
||
{
|
||
"total": 62, "page": 1, "rows": 20,
|
||
"records": [ { "id": 19, "name": "北京D类代理", "level": 2, "channelNo": "D", "...": "..." } ]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. property.list.query
|
||
|
||
查询物业（客户）列表（分页），对应老系统 `/property/listByPage`。
|
||
|
||
- 分类：customer ｜ 类型：读
|
||
- 数据来源：m0 库 `properyt` 表
|
||
- 行级权限（完整版 `getByIsAgent` 语义）：
|
||
- 总部（isagent=0）：全部；
|
||
- 代理商（isagent=1）：自己 + 直属下级代理 + `warehouse_agent_auth` 代管代理 名下物业，及 `agent_manage_district_auth` 授权代管的物业；
|
||
- 销售部门非负责人：自己创建的物业 ∪ 代管授权代理名下物业（`id IN (...)` 结构，与其余规则互斥，1:1 复刻老代码 saleFlag 分支）。
|
||
- **不含** enterprise_type=2 物业用户限自己物业的规则（物业用户不查此列表）。
|
||
|
||
**入参**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| name | string | 否 | 物业名称，模糊匹配 |
|
||
| agentId | number | 否 | 所属代理商 id，精确匹配 |
|
||
| serialnumber | string | 否 | 物业编号，精确匹配 |
|
||
| province | string | 否 | 省份，精确匹配 |
|
||
| city | string | 否 | 城市，精确匹配 |
|
||
| contact | string | 否 | 联系人，精确匹配 |
|
||
| phone | string | 否 | 联系电话，精确匹配 |
|
||
| page | number | 否 | 页码，从 1 开始，默认 1 |
|
||
| rows | number | 否 | 每页条数，默认 20，上限 100 |
|
||
|
||
**出参 records 字段**：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| id / name / serialnumber | 物业 id / 名称 / 编号 |
|
||
| agentName | 所属代理商名称（查不到为 `未查询到`） |
|
||
| createName | 创建人/销售姓名（未分配为 `未分配`） |
|
||
| province / city / countyseat / address | 省 / 市 / 区县 / 详细地址 |
|
||
| contact / phone | 联系人 / 电话 |
|
||
| createTime | 创建时间，`yyyy-MM-dd HH:mm:ss` |
|
||
|
||
---
|
||
|
||
## 4. district.list.query
|
||
|
||
分页查询站点列表，对应老系统 `/district/districtlistByPage`，但使用固定轻量字段契约。
|
||
|
||
- 分类：customer ｜ 类型：读
|
||
- 数据来源：m0 库 `district_district_strategy` 视图，固定 `soft_delete = 0`、`id DESC`
|
||
- 行级权限：总部看全部；代理商按自己、直属下级、代管代理及授权物业过滤；销售部门非负责人沿用老接口的互斥物业范围。筛选条件只能缩小权限结果。
|
||
|
||
**入参**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| id | number | 否 | 站点 id，正整数，精确匹配 |
|
||
| districtName | string | 否 | 站点名称，模糊匹配 |
|
||
| districtState | number | 否 | 0=测试 1=履约 2=演示 3=撤机 |
|
||
| province | string | 否 | 省份，模糊匹配 |
|
||
| city | string | 否 | 城市，模糊匹配 |
|
||
| agentId | number | 否 | 代理商 id，正整数，精确匹配 |
|
||
| propertyId | number | 否 | 物业 id，正整数，精确匹配 |
|
||
| page | number | 否 | 页码，从 1 开始，默认 1 |
|
||
| rows | number | 否 | 每页条数，默认 20，上限 100 |
|
||
|
||
**出参 records 字段**：
|
||
|
||
`id`、`districtName`、`districtNumber`、`propertyId`、`propertyName`、`agentId`、`agentName`、`province`、`city`、`countyseat`、`address`、`districtState`、`onlineState`、`hardwareCount`、`isSmart`。
|
||
|
||
`propertyName`、`agentName` 均为批量富化，查不到时返回 `未查询到`。
|
||
|
||
---
|
||
|
||
## 5. district.detail.get
|
||
|
||
按站点 id 获取扩展详情。站点 id 与当前用户行权限在同一个数据库查询条件中组合。
|
||
|
||
- 分类：customer ｜ 类型：读
|
||
- 入参：`id`（number，必填，正整数）
|
||
- 找到：`{ "found": true, "data": { ... } }`
|
||
- 不存在或无权限：`{ "found": false, "message": "站点不存在或无权访问" }`
|
||
|
||
**data 字段**：
|
||
|
||
| 分组 | 字段 |
|
||
|---|---|
|
||
| 归属 | id、districtName、districtNumber、propertyId、propertyName、agentId、agentName、salesId、salesName、serviceCompanyId、serviceCompany |
|
||
| 地址联系人 | province、city、countyseat、address、contact、phone、mail |
|
||
| 站点属性 | businessFormat、attributeId、attributeName、installType、isSmart、lnfluenceLevel、buildCount、hardwareCount、airdetectorFlag |
|
||
| 状态周期 | districtState、onlineState、testDate、honourDate、weaningDate、testDays |
|
||
| 设备耗材 | deviceSalesType、paperSalesType、consumablesType、posDevicePaperNorm、toiletDevicePaperNorm |
|
||
| 功能开关 | pointState、assignmentWorkState、airState、messageFlag、reportFlag、lockMachineFlag、eventRepairFlag、rfidUseFlag、calibratedFlag、illegalPaperDisable |
|
||
| 语音配置 | lowerPaperState、noPaperState、powerWarning、waitTimes |
|
||
| 报警配置 | warning、warning2、warning3、warningTime、paperPercentWarn、maintainOrderWarning、foamCountWarning、foamPowerWarning |
|
||
| 业务配置 | pointDeduction、effectiveUseTime、consumablesPrice、billDate、billType、billTypeStr、fineMoney |
|
||
| 运行配置 | districtRefresh（Redis 未配置默认 5）、forbidFunction（Redis 未配置默认 0） |
|
||
| 审计信息 | createId、createName、createTime、modifyTime、memo |
|
||
|
||
固定不返回 `softDelete`、`enterpriseId`、`modifyId`、内部服务 URL、重复 `districtId`、语义未确认的 `supervisorId` 和 SKU 列表。
|
||
|
||
---
|
||
|
||
## 6. sys.ping
|
||
|
||
服务自检（demo 工具，证明链路连通）。
|
||
|
||
- 分类：system ｜ 类型：读
|
||
|
||
**入参**：无
|
||
|
||
**出参**：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| service | 服务名（spring.application.name） |
|
||
| version | 服务版本 |
|
||
| time | 服务器当前时间 |
|
||
| redis | `PONG` 表示 Redis 连通；否则为 `ERROR: ...` |
|
||
|
||
---
|
||
|
||
## 附录：在线查看工具清单
|
||
|
||
```bash
|
||
AK=xqak_xxx; H=http://localhost:8088/mcp
|
||
# 1) initialize，从响应头取 mcp-session-id
|
||
# 2) 带 mcp-session-id 发 notifications/initialized
|
||
# 3) 带 mcp-session-id 调用 tools/list
|
||
curl -X POST $H -H "Authorization: Bearer $AK" -H "mcp-session-id: $SID" \
|
||
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
|
||
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
|
||
```
|
||
|
||
也可在管理后台「工具管理」页查看全量注册工具（不受作用域过滤）。
|