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`，ak 在管理后台「用户与 Token」签发，服务端只存 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	代理商总数

{ "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`

{
  "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. sys.ping

服务自检（demo 工具，证明链路连通）。

分类：system ｜类型：读

入参：无

出参：

字段	说明
service	服务名（spring.application.name）
version	服务版本
time	服务器当前时间
redis	`PONG` 表示 Redis 连通；否则为 `ERROR: ...`

附录：在线查看工具清单

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":{}}'

也可在管理后台「工具管理」页查看全量注册工具（不受作用域过滤）。

5.9 KiB Raw Blame History Unescape Escape