跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 04

04-04|实战:把订单能力暴露为 MCP Server

完成 Support Agent V0.4:复用现有订单 Tool Contract,构建可发现、可调用、可测试的教学 MCP Server。

实战 · MCP Server · V0.4

Business Goal

把 V0.3 的 get_order_summary 从单一 Agent Runtime 内部能力升级为可被 MCP Host 发现和调用的教学 Server。Server 继续使用安全 Mock 或现有 Adapter,不连接生产 Shopify,不增加退款、取消或改地址能力。

完成后得到 Support Agent V0.4 External Integration:Agent 可以通过 MCP Client 使用订单能力,同时保留 V0.3 的 Schema、授权、错误和 Trace 约束。

Current Architecture

Customer → Intent V0.1 → Loop V0.2 → Internal Tool V0.3 → Mock / Adapter

Tool Contract 已经稳定,但能力注册和执行都属于当前 Runtime,其他 Host 无法通过共同协议发现。

This Lesson Change

Support Agent Host
↓
MCP Client
↓ discovery + tools/call
Order MCP Server
↓ Runtime Context + Authorization
V0.3 Order Handler → Mock / Provider Adapter
图 1|V0.4 增加标准连接层;业务 handler 与权限边界继续复用 V0.3。

Codex Task

为 Cross-border AI Support Agent 构建教学用 Order MCP Server。

先检查仓库语言、包管理器、测试框架和当前 MCP 官方稳定版本。
当前官方 TypeScript SDK 稳定线为 v2,但实现必须以项目锁定版本为准。

要求:
- 暴露只读 Tool:get_order_summary。
- 复用 V0.3 input/output/failure contract,不复制业务逻辑。
- 模型参数只包含 orderId;tenant/customer 从可信运行上下文注入。
- 数据源使用教学 Mock 或项目已有安全 Adapter。
- 支持 tool discovery 与 tool call 的集成测试。
- 覆盖 invalid_input、not_found、unauthorized、timeout、malformed_result。
- Tool Result 保留 source、updatedAt、requestId;失败后禁止猜测。
- 不连接生产系统,不新增写操作,不修改范围外架构。

实现前报告文件范围、SDK 版本和 transport 选择;实现后运行标准验证。

Interface / Contract

模型能看到的参数保持最小:

{
  "name": "get_order_summary",
  "input": { "orderId": "XB-1024" }
}

Server handler 在模型之外取得:

{
  "tenantId": "from_verified_session",
  "customerId": "from_verified_session",
  "requestId": "runtime_generated"
}
  1. 1Host选择已连接的 Order Server
  2. 2Client发现 get_order_summary 与 Schema
  3. 3Agent提交 orderId
  4. 4Server注入身份并校验授权
  5. 5Handler调用 Mock / Adapter
  6. 6Client接收结构化 Result
  7. 7Loop写入 Trace 并决定回复或停止
图 2|发现和传输由 MCP 标准化;身份、授权、业务查询和恢复策略仍由应用负责。

Expected Inputs / Outputs

场景MCP ResultLoop 行为
当前客户订单ok + order summary可继续查询物流或回复
缺少 orderIdinvalid_input追问客户
授权范围内未找到not_found说明未找到并核对编号
其他客户订单unauthorized立即停止,不泄露存在性
Adapter 超时timeout预算内重试一次
返回缺字段malformed_result拒绝使用并升级

Test Cases

  1. 独立 Client 能发现 Server 和唯一的只读订单 Tool。
  2. Tool Schema 不含 tenantId、customerId、API token。
  3. 正常调用返回最小订单字段与来源。
  4. Client 传入额外身份字段时被拒绝或忽略,不能覆盖可信 Context。
  5. 五类失败映射到 V0.3 的稳定 Failure Contract。
  6. Server 断开、版本不兼容和超时能被 Host 识别。
  7. Tool 失败后的 final response 不包含虚构订单状态。
Contract

Schema 与 Result

Handler

授权与 Adapter

Protocol

discover / list / call

End-to-end

Host → MCP → Trace

图 3|协议测试不能替代 handler 授权测试;端到端测试也不能替代确定契约测试。

Failure Lab

在 MCP handler 里重写订单逻辑

为什么诱人: 一个文件就能跑通 Demo。

为什么失败: 内部 Tool 与 MCP Server 出现两套授权、错误和字段定义。

更合理设计: MCP handler 只做协议适配,调用 V0.3 已测试的业务 handler。

测试只验证 tools/list

为什么诱人: 能看到 Tool 就像集成成功。

为什么失败: 执行时的身份注入、错误映射和结果校验仍可能全部失效。

更合理设计: 同时覆盖 discovery、call、handler 和 Loop 消费结果。

为演示直接使用生产凭证

为什么诱人: 真实订单让 Demo 更有说服力。

为什么失败: 教学环境缺少生产授权、审计和数据隔离,可能泄露客户数据。

更合理设计: 使用确定 Mock 或供应商沙箱;生产接入留到完成安全与部署验收之后。

Acceptance Criteria

  • ☐ 独立 MCP Client 能发现并调用订单 Tool。
  • ☐ V0.3 Contract 与 Failure Contract 被复用。
  • ☐ 模型不能提交或覆盖可信身份。
  • ☐ Server handler 每次执行授权检查。
  • ☐ 五类失败有集成测试,失败后没有猜测。
  • ☐ Host Trace 记录 server、tool、requestId、result 与 stop reason。
  • ☐ 未连接生产系统,未暴露写操作。
  • ☐ README 或测试记录锁定协议、SDK 与 transport 版本。
  • ☐ TypeScript、lint、测试与 production build 通过。

Architecture After This Lesson

Support Agent V0.4
  Intent V0.1
    → Loop Runtime V0.2
      → Stable Tools V0.3
        → MCP Client / Order MCP Server V0.4
          → Mock or Provider Adapter

Week 04 完成。下一周会把退款从“Agent 想下一步”拆成可恢复的 Workflow:固定状态、合法转移、超时、重试和幂等都由确定系统掌握。

延伸阅读 / Sources

核查日期:2026-10-18。

长期有效的原理: 协议适配与业务逻辑分离,身份由可信运行时提供,失败可测试。当前实现方式: 示例包名、注册方法和 transport 配置属于当前 SDK;实现时必须锁定版本并保存验证证据。