MCP

MCP（Model Context Protocol）标准模式在 /open/v1/mcp 端点暴露业务工具，Agent 通过 JSON-RPC 2.0 调用。

项目	值
URL	`https://open.longxiachuxing.com/api/open/v1/mcp`
方法	`POST`
协议	JSON-RPC 2.0
鉴权	HMAC-SHA256 签名或 Bearer Token（与标准 REST 一致）
传输	MCP "Streamable HTTP"：支持 JSON 一次性响应 / SSE 流式推送

鉴权方式

与标准 REST 接口完全一致，二选一：

1. HMAC-SHA256 签名

签名算法：

canonical = METHOD + "\n" + REQUEST_URI + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(BODY)
sign      = HMAC_SHA256(app_secret, canonical)

详见鉴权说明。

2. Bearer Token

传输模式

MCP "Streamable HTTP" 支持两种响应模式，通过 Accept 头控制：

JSON 模式（默认）

一次性返回完整 JSON-RPC 响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

SSE 模式

返回 SSE 流，每条 JSON-RPC 消息一个 event: message 帧：

event: message
data: {"jsonrpc":"2.0","id":1,"result":{...}}

适用场景：长时间查询、需要中间进度反馈的工具（当前所有工具都是快速响应，SSE 主要用于协议兼容性）。

协议流程

1. 初始化（可选）

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-agent",
      "version": "1.0.0"
    }
  },
  "id": 1
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "rideclaw-mcp",
      "version": "1.0.0"
    }
  }
}

2. 获取工具列表

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}

响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "flight.search",
        "description": "按出发/到达城市与日期搜索航班，返回带舱位价格的航班列表。",
        "inputSchema": {
          "type": "object",
          "required": ["trip_mode", "trip_type", "from_code", "to_code", "depart_date"],
          "properties": {
            "trip_mode": { "type": "string", "enum": ["domestic", "international"] },
            "from_code": { "type": "string" },
            "to_code": { "type": "string" },
            "depart_date": { "type": "string" }
          }
        }
      },
      ...
    ]
  }
}

3. 调用工具

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "flight.search",
    "arguments": {
      "trip_mode": "domestic",
      "trip_type": "oneway",
      "from_code": "SZX",
      "to_code": "PEK",
      "depart_date": "2026-06-12",
      "passengers": { "adult": 1, "child": 0, "infant": 0 },
      "page_size": 10
    }
  },
  "id": 3
}

响应：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"search_id\":\"S_2026-06-12_SZX_PEK\",\"total\":42,\"flights\":[...]}"
      }
    ],
    "isError": false
  }
}

错误响应（工具执行失败）：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "flight.search 参数错误: trip_mode 必填"
      }
    ],
    "isError": true
  }
}

注意：工具执行错误返回 result.isError=true，不是 JSON-RPC error 对象。只有协议层错误（如 method 不存在、JSON 格式错误）才返回 error。

工具列表

机票（9 个）

工具名	用途	关键参数
`flight.search`	航班列表查询	`from_code`, `to_code`, `depart_date`
`flight.airport_search`	机场搜索	`keyword`
`flight.pricing`	验价	`search_offer_id`, `passengers`
`flight.order_create`	创建订单	`offer_id`, `out_trade_no`, `passengers`, `contact`
`flight.order_pay`	发起支付	`system_no`, `pay_type`
`flight.order_detail`	订单详情	`system_no` / `out_trade_no`
`flight.order_list`	订单列表	`status`, `start_date`, `end_date`
`flight.order_cancel_fee`	查询取消手续费	`order_id`
`flight.order_cancel`	取消 / 退票	`system_no`, `reason`

酒店（3 个）

工具名	用途	关键参数
`hotel.search`	酒店列表查询	`destination`, `check_in`, `check_out`
`hotel.rooms`	房型详情	`search_offer_id`
`hotel.order_create`	创建订单	`offer_id`, `out_trade_no`, `guests`, `contact`

其他（3 个）

工具名	用途	关键参数
`taxi.estimate`	打车估价	`from_lng`, `from_lat`, `to_lng`, `to_lat`
`train.search`	高铁查询	`from_station`, `to_station`, `dep_date`
`bus.search`	城际巴士查询	`start_city_code`, `end_city_code`, `date`

完整 inputSchema 见 tools/list 响应。

调用示例

Python（使用 requests）

cURL（Bearer Token）

错误处理

协议层错误（JSON-RPC error）

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "方法不存在: tools/unknown"
  }
}

常见错误码：

code	含义
`-32700`	JSON 解析失败
`-32600`	无效请求
`-32601`	方法不存在
`-32602`	参数错误
`-32603`	内部错误

工具执行错误（result.isError）

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "参数错误: from_code 不能为空"}],
    "isError": true
  }
}

Agent 收到 isError=true 后应自我修正参数重试。

批量调用（可选）

JSON-RPC 2.0 支持批量请求，但不推荐用于 MCP 工具调用：

工具调用通常有依赖关系（验价依赖搜索结果），批量请求无法表达这种依赖。

批量请求的事务语义不明确（部分成功时如何处理）。

建议顺序调用，由 Agent 控制调用顺序与依赖。

调试工具

MCP Inspector

Anthropic 官方的 MCP 调试工具：github.com/modelcontextprotocol/inspector

配置方式：

{
  "servers": {
    "rideclaw": {
      "url": "https://open.longxiachuxing.com/api/open/v1/mcp",
      "headers": {
        "Authorization": "Bearer rdak_live_xxxxxxxx"
      }
    }
  }
}

测试 Agent

项目自带测试 Agent（cmd/agent），连接本地 /open/v1/mcp 端点，通过阿里云通义千问模型驱动。

详见 cmd/agent/README.md。

注意事项

工具调用频率：MCP 工具调用受到与标准 REST 相同的速率限制（QPS / 日配额）。

幂等性：写操作（order_create）的幂等键为 <app_id, out_trade_no>，重复调用返回首次创建的订单。

offer_id 过期：搜索 / 验价返回的 offer_id 有效期 10 分钟，超时需重新调用。

异步状态推进：订单支付成功后由平台异步推进状态（pending_pay → paid → ticketed），通过 Webhook 推送，不建议轮询 order_detail。

SSE 与 HTTP/2：SSE 模式在 HTTP/2 下可能被中间件缓冲，建议用 HTTP/1.1 或降级到 JSON 模式。

最佳实践

1. 工具调用链

搜索 → 验价 → 下单 → 支付
  ↓       ↓       ↓       ↓
flight. flight. flight. flight.
search  pricing order_  order_
                create  pay

每个环节返回的令牌（search_offer_id / offer_id / system_no）传递给下一环节。

2. 错误重试

工具调用失败时，Agent 应根据 isError=true 的错误文本自我修正：

"from_code 不能为空" → 补充缺失参数重试

"offer_id 过期" → 重新验价获取新 offer_id

"IP 不在白名单" → 提示用户联系管理员

3. 上下文优化

MCP 工具返回的 JSON 较大（如 flight.search 返回 20 个航班），Agent 应提取关键信息（前 3 个推荐）后再回答用户，避免上下文溢出。

4. 多步查询切换到 Code Mode

当 Agent 需要多次调用工具（如「先查明天，价格超 2000 再查后天」），建议切换到 Code Mode，在沙箱中编排逻辑，减少 Agent 上下文消耗。

鉴权方式#

1. HMAC-SHA256 签名#

2. Bearer Token#

传输模式#

JSON 模式（默认）#

SSE 模式#

协议流程#

1. 初始化（可选）#

2. 获取工具列表#

3. 调用工具#

工具列表#

机票（9 个）#

酒店（3 个）#

其他（3 个）#

调用示例#

Python（使用 requests）#

cURL（Bearer Token）#

错误处理#

协议层错误（JSON-RPC error）#

工具执行错误（result.isError）#

批量调用（可选）#

调试工具#

MCP Inspector#

测试 Agent#

注意事项#

最佳实践#

1. 工具调用链#

2. 错误重试#

3. 上下文优化#

4. 多步查询切换到 Code Mode#