xiaoqu_mcp_service/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md

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	代理商总数

{ "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. 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: ...

---

7. mall.order.list.query

查询商城订单列表（分页），对应老系统 POST /mallGoodsOrder/listByPage。

• 分类：customer ｜ 类型：读
• 数据来源：m1 商城库（xiaoqu_mall_d）mall_goods_order 表
• 行级权限（PermissionService.applyOrderRowFilter，移植老接口 WrapperUtils.getSaleCompany 语义）：
  • 总部（isagent=0）：全部；
  • 代理商（isagent=1）：sale_company_id IN (自己 + 直属下级 + warehouse_agent_auth 代管代理)，有代管物业授权时再 OR property_id IN (agent_manage_district_auth 代管物业)；
  • 销售部门非负责人：property_id IN (自己创建的物业 + 代管代理名下物业)，与上一条互斥。

入参：

参数	类型	必填	说明
orderNo	string	否	订单编号，模糊匹配
agentId	number	否	代理商 id，精确匹配
propertyId	number	否	物业 id，精确匹配
orderType	number	否	订单类型：0=代理 1=物业
orderState	number	否	订单状态（单选）：0=待付款 1=待出库 2=待发货 3=已发货 4=已签收 5=已收货 6=已取消 7=已删除
payState	number	否	回款状态：0=待付款 1=已付款 2=付款中
startOrderTime	string	否	下单时间起，yyyy-MM-dd
endOrderTime	string	否	下单时间止，yyyy-MM-dd（含当天）
page	number	否	页码，从 1 开始，默认 1
rows	number	否	每页条数，默认 20，上限 100（超出截断为 100 并在 notice 提示）

出参 records 字段（按 id 倒序）：

字段	说明
id / orderNo / orderTime	订单 id / 编号 / 下单时间（yyyy-MM-dd HH:mm:ss）
orderType / agentName / propertyName	订单类型 / 代理名称 / 物业名称
saleCompany	销售公司
payMoney / paidMoney / unPayMoney	应付 / 已付 / 未付金额
orderState / payState / warehouseState	订单状态 / 回款状态 / 出库状态（0=未出库 1=已出库 2=部分出库）
customerName	客户名称：orderType=0 取代理金蝶名称，否则取物业金蝶名称（批量富化，同老接口）

---

8. mall.order.detail.query

按订单号查询商城订单详情（订单 + 商品明细 + 收货地址一次返回，合并老系统三个接口）。

• 分类：customer ｜ 类型：读
• 数据来源：m1 库 mall_goods_order + mall_order_details + mall_shipping_address
• 行级权限：与 mall.order.list.query 一致；订单不存在或无权查看时 record=null 并在 notice 说明（两者不区分，不泄露订单是否存在）。

入参：

参数	类型	必填	说明
orderNo	string	是	订单编号

出参：

• record：订单关键字段（金额类 payMoney/paidMoney/unPayMoney/totalMoney/goodsMoney/postageMoney/discountMoney，状态类 orderState/payState/orderPayState/warehouseState/orderInvoiceState，时间类 orderTime/payTime/receiptTime/signTime/createTime，及 accountsType/paymentType/goodsType/saleCompany/payNo/memo 等）+ 收货信息（reveiveName/reveiveNumber/province/city/countyseat/address，由 address_id 关联 mall_shipping_address）。
• items：商品明细列表，每行含 spuNo/spuName/skuNo/count/price/payMoney/payState/warehouseState。

---

9. mall.order.logistics.query

按订单号查询商城订单物流（发货信息 + 物流轨迹），对应老系统 GET /mallGoodsOrder/getMallLogistics。

• 分类：customer ｜ 类型：读
• 数据来源：m1 库 mall_order_logistics + mall_order_logistics_detai
• 行级权限：与 mall.order.list.query 一致；订单不存在或无权查看时 logistics=null 并在 notice 说明（两者不区分）。
• 注意：轨迹表 logistics_order_no 字段老系统写入时塞的是订单号而非快递单号，故按 orderNo 查询（照搬老系统语义）。物流轨迹为系统内业务节点手工写入的记录，非实时快递查询，可能不全（菜鸟定时同步已停用）。

入参：

参数	类型	必填	说明
orderNo	string	是	订单编号

出参：

• logistics（无物流记录时为 null）：logisticsName（快递公司）/ logisticsOrderNo（快递单号）/ sendMode（0=快递 1=自送）/ state（0=已出单 1=已出库 2=已发货 3=已揽件 4=运输中 5=待取件 6=派送中 7=已签收）/ deliverName / deliverNumber / sendTime / receivingGoodsName / reveiveName / reveiveNumber / address。
• tracks：轨迹列表，按时间正序，每行含 memo（轨迹描述）/ state / picList / createTime。

---

附录：在线查看工具清单

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

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