AI Agent Engineering · Week 04
04-04|实战:把订单能力暴露为 MCP Server
完成 Support Agent V0.4:复用现有订单 Tool Contract,构建可发现、可调用、可测试的教学 MCP Server。
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
↓
MCP Client
↓ discovery + tools/call
Order MCP Server
↓ Runtime Context + Authorization
V0.3 Order Handler → Mock / Provider Adapter
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"
}
- 1Host选择已连接的 Order Server
- 2Client发现 get_order_summary 与 Schema
- 3Agent提交 orderId
- 4Server注入身份并校验授权
- 5Handler调用 Mock / Adapter
- 6Client接收结构化 Result
- 7Loop写入 Trace 并决定回复或停止
Expected Inputs / Outputs
| 场景 | MCP Result | Loop 行为 |
|---|---|---|
| 当前客户订单 | ok + order summary | 可继续查询物流或回复 |
| 缺少 orderId | invalid_input | 追问客户 |
| 授权范围内未找到 | not_found | 说明未找到并核对编号 |
| 其他客户订单 | unauthorized | 立即停止,不泄露存在性 |
| Adapter 超时 | timeout | 预算内重试一次 |
| 返回缺字段 | malformed_result | 拒绝使用并升级 |
Test Cases
- 独立 Client 能发现 Server 和唯一的只读订单 Tool。
- Tool Schema 不含 tenantId、customerId、API token。
- 正常调用返回最小订单字段与来源。
- Client 传入额外身份字段时被拒绝或忽略,不能覆盖可信 Context。
- 五类失败映射到 V0.3 的稳定 Failure Contract。
- Server 断开、版本不兼容和超时能被 Host 识别。
- Tool 失败后的 final response 不包含虚构订单状态。
Schema 与 Result
授权与 Adapter
discover / list / call
Host → MCP → Trace
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。
- MCP 官方文档:Architecture overview。用于核对发现、Tool 调用和参与者职责。
- MCP TypeScript SDK v2。用于核对当前稳定 Server SDK 与 transport 入口。
- MCP Specification 2026-07-28。用于核对协议版本、能力与安全边界。
长期有效的原理: 协议适配与业务逻辑分离,身份由可信运行时提供,失败可测试。当前实现方式: 示例包名、注册方法和 transport 配置属于当前 SDK;实现时必须锁定版本并保存验证证据。