# MCP 接入 (AI 客户端)

把 CZL Express 的查价、轨迹、偏远查询等能力接进 CZL Agent、Claude、Cursor 等支持 MCP (Model Context Protocol) 的 AI 客户端，直接用自然语言提问，例如“5kg 40×30×30 的箱子寄美国 10001 哪个渠道最便宜”。

## 接入地址

| 端点 | 鉴权 | 可用工具 | 额度 |
| --- | --- | --- | --- |
| `https://tms-go.czl.net/api/mcp/public` | 无需鉴权 | 公开工具 | 每个 IP 每 5 分钟 30 次、每天 300 次 |
| `https://tms-go.czl.net/api/mcp` | `Authorization: Bearer <API_KEY>` 或 `X-API-Key: <API_KEY>` | 公开工具 + 账号工具；管理员账号另有录单工具 | 按接口平台为 `/api/mcp` 配置的每日限额，管理员不限 |

- 传输方式: Streamable HTTP (无状态)
- 额度按**工具调用次数**计算，连接握手和获取工具列表不计数
- API Key 与接口平台通用，在控制台「API密钥」页创建；非管理员账号使用 `/api/mcp` 需要管理员在接口平台为其开通 `MCP 接入` 权限，未开通返回 `403`

## 客户端配置

### CZL Agent (ai.czl.net)

我司自有 Agent，MCP 能力在 **CZL AI 桌面端**里提供 (网页版不能接本机 MCP)。两种方式任选：

- 直接在对话里让 CZL Agent 接入本 MCP 并把这份文档发给它，它会自行安装 (写入桌面端的 `config/mcp.json`，安装前弹窗确认)，装好后自动加入「始终启用」
- 手动在「设置 → 桌面端」的 MCP 配置里添加 (格式同 Claude Code 的 `mcpServers`)：

```json
{
  "mcpServers": {
    "czl": {
      "type": "http",
      "url": "https://tms-go.czl.net/api/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}
```

没有 API Key 时把 `url` 换成公开端点 `https://tms-go.czl.net/api/mcp/public` 并去掉 `headers`。已在 Claude Code / Codex 里配置过本 MCP 的，桌面端会自动读取，无需重复添加。

### Claude Code

```bash
# 公开端点
claude mcp add --transport http czl https://tms-go.czl.net/api/mcp/public

# API Key 端点
claude mcp add --transport http czl https://tms-go.czl.net/api/mcp --header "Authorization: Bearer your_api_key"
```

### Cursor / Windsurf / Cline 等 (mcp.json)

```json
{
  "mcpServers": {
    "czl": {
      "url": "https://tms-go.czl.net/api/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}
```

### Claude 网页版 / 桌面版 (自定义连接器)

在「设置 → 连接器 → 添加自定义连接器」中填入公开端点 `https://tms-go.czl.net/api/mcp/public`。自定义连接器只支持 OAuth 鉴权，不能携带 API Key，因此只能使用公开工具。

## 公开工具

| 工具 | 说明 |
| --- | --- |
| `query_price` | 按目的国、邮编、包装类型 (`P` 包裹 / `D` 文件 / `B` 袋子) 与包裹尺寸重量查询各渠道报价 (人民币)，按总价从低到高返回最便宜的 30 个渠道。结果不含偏远附加费。渠道说明 (禁运、理赔、退件规则) 默认不返回，用 `product_keyword` 筛到 5 个以内渠道并设 `include_notes: true` 时返回 |
| `track_shipment` | 查询运单轨迹，合并我司系统与 DHL / FedEx / UPS 等承运商官方轨迹，附可发给客户的轨迹页链接。匿名每次 1 个单号，API Key 每次最多 5 个 |
| `query_remote` | 查询收件地对 DHL / FedEx / UPS / TNT 及自定义渠道是否偏远。结果含 `query_cities` 时表示该邮编对应多个城市，需带 `selected_city` 再查一次 |
| `calc_chargeable_weight` | 按尺寸与实重计算体积重和计费重，默认除数 5000，可传 `divisor` (如 6000) |
| `get_fuel_surcharge` | 查询 DHL / FedEx / UPS 当前及近期燃油附加费率 |

国家一律使用 ISO 3166-1 二字码 (`US`、`GB`、`DE`)，重量单位 kg，尺寸单位 cm。

## 账号工具 (需 API Key)

| 工具 | 说明 |
| --- | --- |
| `get_my_usage` | 当前 API Key 所属账号的调用量、近 7 天趋势、各接口权限、每日限额与今日已用次数 |

## 管理员工具 (需管理员账号的 API Key)

管理员账号的 API Key 连接 `/api/mcp` 时额外提供录单工具：把客户发来的文字、图片、表格交给 AI 客户端，由它整理成结构化订单后直接录入。

| 工具 | 说明 |
| --- | --- |
| `create_order` | 建一张本地录单，返回本地订单 ID 与订单号。只写本系统，不上传物流通、不发新订单通知，可在后台订单详情页人工核对修改 |
| `list_orders` | 分页查看录单 (按创建时间倒序)，支持按客户代码 / 订单 ID / 收件人 / 电话搜索，含上传状态、处理状态、物流单号与收发货时间 |
| `get_order` | 按订单 ID 查看收件人、申报物品、箱体尺寸重量、关税与报关方式 |
| `upload_order_to_tms` | 上传订单到物流通建单。**不可撤销**，客户端会在调用前请求确认；已上传过的订单再次上传必须带重传后缀 `order_code_suffix` (如 `-1`) |

## 错误码

工具执行失败时返回 `isError: true`，文本为“数字码 + 英文说明”：

| 错误码 | 含义 |
| --- | --- |
| `40001` | 参数错误，按说明修正后重试 (不计入匿名额度) |
| `40301` | 账号未开通 MCP 权限 |
| `42901` | 账号今日调用已达每日限额 |
| `42902` | 匿名 IP 额度已用完，可改用 API Key 端点 |
| `50201` | 上游查询失败，可稍后重试 |
| `50202` | 物流通拒绝建单，文本附带拒单原因 (仅管理员工具) |
| `50001` | 服务内部错误 |

HTTP 层面：API Key 端点缺少或携带无效 Key 返回 `401`，Key 有效但未开通权限返回 `403`。

## 调用示例 (JSON-RPC)

```bash
curl --request POST \
  --url https://tms-go.czl.net/api/mcp/public \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "calc_chargeable_weight",
      "arguments": {
        "packages": [{ "weight_kg": 3.2, "length_cm": 40, "width_cm": 30, "height_cm": 30, "count": 2 }]
      }
    }
  }'
```