Support MCP

Support MCP 是 MaxWork 售后系统的 MCP 协议适配层，用于 AI Agent 通过后端 OpenAPI 契约发现和调用售后业务接口。

边界

• 只负责 MCP 工具、资源、提示词和协议输入输出。
• 动作目录来自 MaxWork 后端 SpringDoc /v3/api-docs，不在 MCP 端复制 DTO、枚举、状态机或业务规则。
• 实际业务调用仍走 MaxWork 后端接口；权限、审批、服务单状态、客户/设备归属、附件和审计以后端为准。
• 不直连数据库，不 import 或复制后端 Service。
• 不保存用户明文账号密码；运行时读取当前环境提供的 SUPPORT_AGENT_TOKEN / SUPPORT_TOKEN。

配置

复制 .env.example 为 .env，填入售后系统后端地址和当前账号 token：

SUPPORT_BASE_URL=http://127.0.0.1:8080
SUPPORT_API_PREFIX=/api
SUPPORT_OPENAPI_URL=http://127.0.0.1:8080/v3/api-docs
SUPPORT_AGENT_TOKEN=BearerTokenWithoutBearerPrefix
SUPPORT_TIMEOUT_MS=30000
SUPPORT_REGISTER_DYNAMIC_TOOLS=false
SUPPORT_ACTION_SEARCH=lexical

SUPPORT_REGISTER_DYNAMIC_TOOLS 默认关闭。关闭时 MCP 只注册稳定工具，通过 support_action.list/detail/execute 覆盖 OpenAPI 中的业务能力；打开后会把动作额外展开成 support.<动作编码> 工具，适合客户端能承载大量工具的场景。

运行

npm install
npm run build
npm run dev

MCP 客户端配置示例：

{
  "mcpServers": {
    "support-mcp": {
      "command": "node",
      "args": ["/path/to/support-mcp/dist/index.js"],
      "env": {
        "SUPPORT_BASE_URL": "https://your-support.example.com",
        "SUPPORT_API_PREFIX": "/api",
        "SUPPORT_OPENAPI_URL": "https://your-support.example.com/v3/api-docs",
        "SUPPORT_AGENT_TOKEN": "BearerTokenWithoutBearerPrefix",
        "SUPPORT_TIMEOUT_MS": "30000",
        "SUPPORT_REGISTER_DYNAMIC_TOOLS": "false"
      }
    }
  }
}

工具

• support_action.catalog：刷新并加载 OpenAPI 暴露的售后动作紧凑目录。
• support_action.list：按自然语言意图检索动作，例如“服务单派工”“客户报修列表”“零件申请审批”。
• support_action.detail：查看动作的 HTTP 方法、路径、参数、请求体和响应 schema 摘要。
• support_action.execute：执行动作。只读动作默认 commit；写入动作默认 preview，只有显式 executionMode=commit 才调用后端。
• support_api.read：读取普通业务接口。默认只允许 GET；POST 仅允许明显只读语义的路径。
• support://agent/context：售后 Agent 通用操作边界和安全规则。
• support://flows/service-order：服务单主链路读取顺序与阻断原则。

confirm_required 在当前版本只返回待确认请求计划；MaxWork 后端尚未提供受控 AI 确认单网关，因此不会持久化确认单。真正写入必须由调用方在用户确认后再次以 executionMode=commit 调用，后端仍会做权限、状态、审批和审计校验。

开发

npm install
npm run build

新增业务能力应优先落在 MaxWork 后端 Controller、DTO、权限和 SpringDoc 契约中；Support MCP 通过刷新 OpenAPI 动作目录自动暴露，不为新业务手写一套平行字段或规则。