@anzenghui/ahu-go-api-mcp

v0.4.0

Published

2 months ago

用于扣子调用 AHU Go 服务接口的 MCP 适配服务。

0High
0Medium
0Low

anzenghui

ahu-go-api-mcp

AHU Go 接口的 MCP 适配服务。它让扣子或其他 MCP 客户端通过 MCP tool 调用现有 Go/Kratos 服务接口。

当前 npm 包：

@anzenghui/ahu-go-api-mcp

当前版本：

0.4.0

功能

get_order_inspection：根据 ENC_... 加密订单 ID 获取订单详情。
save_inspection_result：推送订单审核/质检结果。
ping：连通性测试。

运行方式一：stdio 模式

stdio 模式适合支持命令行拉起 MCP 的客户端。

AGENT_AHYK_BASE_URL=http://127.0.0.1:9410 npx @anzenghui/ahu-go-api-mcp

AGENT_AHYK_BASE_URL 是 Go 服务基础地址，例如：

http://127.0.0.1:9410
https://api.example.com

运行方式二：HTTP URL 模式

如果平台只支持填写 URL，例如扣子 MCP 服务配置页要求填写 URL，需要使用 HTTP 模式。

本地启动：

AGENT_AHYK_BASE_URL=http://127.0.0.1:9410 \
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_PORT=3000 \
npx @anzenghui/ahu-go-api-mcp

启动后 MCP URL 为：

http://服务器IP或域名:3000/mcp

生产环境建议使用 HTTPS 反向代理，例如：

https://mcp.example.com/mcp

健康检查地址：

GET /health

HTTP 模式相关环境变量：

| 环境变量 | 默认值 | 说明 | | --- | --- | --- | | MCP_TRANSPORT | stdio | 设置为 http 时启动 URL 模式。 | | MCP_HOST | 0.0.0.0 | HTTP 服务监听地址。 | | MCP_PORT | 3000 | HTTP 服务监听端口。 | | PORT | 无 | 部署平台常用端口变量，优先级高于 MCP_PORT。 | | MCP_ALLOWED_HOSTS | 无 | 可选，逗号分隔的 Host 白名单，用于限制访问域名。 |

MCP 客户端配置：stdio

在支持 MCP 的客户端中，可以配置：

{
  "mcpServers": {
    "ahu-go-api-mcp": {
      "command": "npx",
      "args": ["@anzenghui/ahu-go-api-mcp"],
      "env": {
        "AGENT_AHYK_BASE_URL": "http://你的Go服务地址:9410"
      }
    }
  }
}

如果扣子侧要求填写命令和参数：

命令：npx
参数：@anzenghui/ahu-go-api-mcp
环境变量：AGENT_AHYK_BASE_URL=http://你的Go服务地址:9410

扣子 URL 配置

如果扣子页面只允许填写 MCP 服务 URL，请先部署 HTTP 模式，然后在扣子中填写：

https://你的MCP域名/mcp

扣子云端访问不到你的本机 127.0.0.1，因此：

AGENT_AHYK_BASE_URL 必须配置为 MCP 服务器能访问到的 Go 服务地址。
MCP URL 必须是扣子云端能访问到的公网 HTTPS 地址，或扣子环境可访问的内网地址。
不要把 app_secret 写进环境变量；它仍然作为 tool 入参由扣子每次调用时传递。

环境变量

| 环境变量 | 是否必填 | 说明 | | --- | --- | --- | | AGENT_AHYK_BASE_URL | 是 | Go 服务基础地址，不包含具体接口路径。 |

工具一：获取订单详情

Tool 名称：

get_order_inspection

对应 Go 接口：

GET /order/inspection/orders

入参：

{
  "app_id": "test_app_001",
  "app_secret": "test_secret_123",
  "order_id": "ENC_xxx"
}

字段说明：

| 字段 | 必填 | 说明 | | --- | --- | --- | | app_id | 是 | AHU Go 服务分配的应用 ID。 | | app_secret | 是 | 用于生成 HMAC 签名的应用密钥。 | | order_id | 是 | ENC_... 加密订单 ID。MCP 不接收明文订单 ID。 |

MCP 会把 order_id 转成 Go 接口的 query 参数：

encrypted_order_id=ENC_xxx

工具二：推送订单审核结果

Tool 名称：

save_inspection_result

对应 Go 接口：

POST /order/inspection/records

入参：

{
  "app_id": "test_app_001",
  "app_secret": "test_secret_123",
  "order_type": 1,
  "order_id": 12345,
  "is_compliant": false,
  "violations": [
    {
      "dimension": "价格",
      "field": "course_price",
      "issue": "实际成交价与系统价格不符",
      "severity": "high"
    }
  ],
  "ai_model": "coze-workflow"
}

字段说明：

| 字段 | 必填 | 说明 | | --- | --- | --- | | app_id | 是 | AHU Go 服务分配的应用 ID。 | | app_secret | 是 | 用于生成 HMAC 签名的应用密钥。 | | order_type | 是 | 订单类型：1 电销，2 网销，3 天猫，4 医陪。 | | order_id | 是 | 业务订单主键 ID，注意这里是明文业务 ID，不是 ENC_...。 | | is_compliant | 是 | 审核结果是否合规。 | | violations | 否 | 违规项列表，合规时可传空数组或不传。 | | ai_model | 否 | 执行审核的 AI 模型名称。 |

violations 元素说明：

| 字段 | 说明 | | --- | --- | | dimension | 违规维度，例如基础信息、价格、商品、礼品、物流。 | | field | 存在问题的字段名。 | | issue | 问题描述。 | | severity | 严重程度，例如 high、medium、low。 |

签名和认证

MCP 会自动生成 Go 服务要求的请求头：

| Header | 来源 | | --- | --- | | X-App-Id | tool 入参 app_id。 | | X-Timestamp | 当前 Unix 秒级时间戳。 | | X-Nonce | 每次请求生成的随机 UUID。 | | X-Signature | 使用 app_secret 生成的 HMAC-SHA256 签名。 |

签名规则和 Go 服务保持一致：

message = app_id + timestamp + nonce + body
signature = HMAC-SHA256(message, app_secret)

GET 请求：

body = ""

POST 请求：

body = MCP 实际发送给 Go 服务的原始 JSON 字符串

是否采用加密逻辑

当前 MCP 只做 HMAC-SHA256 签名认证，用于调用 Go 服务接口。

当前 MCP 不做订单 ID 的 ENC_... 加密，也不接收明文订单 ID。原因是业务链路里不会存在明文订单 ID，扣子传给 MCP 的 order_id 已经是上游系统生成好的 ENC_...。

MCP 只负责：

校验 order_id 必须以 ENC_ 开头。
将 order_id 作为 encrypted_order_id 传给 Go 服务。
使用 app_secret 生成 HMAC 签名。
调用 Go 服务接口。

Go 服务端仍然会按自己的逻辑用应用凭证中的 key_secret 解密 encrypted_order_id。这个 key_secret 不需要、也不应该传给 MCP。

本地开发

cd ahu-go-api-mcp
npm install
AGENT_AHYK_BASE_URL=http://127.0.0.1:9410 npm run dev

常用脚本：

npm run typecheck
npm run build
npm pack --dry-run

发布

当前包已发布到 npm：

npm view @anzenghui/ahu-go-api-mcp version

发布新版本时需要先升级 package.json 版本号，再执行：

npm run typecheck
npm run build
npm pack --dry-run
npm publish --access public

详细发布流程见 NPM_PUBLISH_SOP.md。