Hou Tea — Buy Chinese tea via x402 USDC

@hou-tea/mcp-server

面向 hou-tea.com 的 Agent 应用 MCP 服务——让你的 AI Agent 通过 x402 协议浏览、获取推荐，并使用 USDC 购买正宗中国茶。

专为 Claude Desktop、Cursor、Cline、Continue、Zed 以及任何兼容 Model Context Protocol 的 AI Agent 设计。

v0.3.0-beta - 服务现在以 Agent 应用层的形式提供，而不仅仅是工具列表： 渐进式工具发现（核心 + 扩展）、严格的 JSON Schema、结构化的 响应/错误封装（ok、data、error、next_action、meta.request_id）、 稳定的错误代码、明确的交接提示（交给钱包 MCP），以及由公开的 @hou-tea/agent-ui-contract 软件包支持的 MCP Apps UI 元数据。请参阅下文的 0.3.0 版本有哪些变化。

---

功能

将 hou-tea Agent API 暴露为 MCP 工具，让 AI 助手代你购物。

默认的 tools/list（核心 + 元工具）——始终可见：

工具	功能
hou_tea_browse	使用筛选条件（类别、价格、季节、难度）浏览茶叶目录
hou_tea_recommend	自然语言推荐：“适合寒冷冬夜的暖身茶”
hou_tea_explain	深入了解一款产品：冲泡指南、故事、健康信息
hou_tea_get_payment_requirements	发起 x402 支付意图（返回收款方 + 金额；自动执行 register_buyer_list_token / buyer_list_token，用于买家订单历史记录）
hou_tea_check_order	支付后查询订单状态
hou_tea_list_my_orders	按 buyer_list_token 列出你的 x402 订单（Bearer；使用 HOU_TEA_BUYER_LIST_TOKEN 环境变量）
hou_tea_discover_extended	按需显示扩展工具（比较 / 健康筛选 / agent-card）

扩展工具（执行 hou_tea_discover_extended 后显示）：

工具	功能
hou_tea_compare	并排比较 2–4 款候选产品
hou_tea_filter_by_health	按状况筛选：怀孕、失眠、对咖啡因敏感
hou_tea_agent_card	获取完整的 Agent 能力描述符（诊断信息）

支付由支持 x402 的钱包 MCP 处理（例如 @coinbase/payments-mcp）——此服务仅生成支付意图，不持有密钥，也不会签署交易。

---

安装

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "hou-tea": {
      "command": "npx",
      "args": ["-y", "@hou-tea/mcp-server@next"]
    },
    "coinbase-payments": {
      "command": "npx",
      "args": ["-y", "@coinbase/payments-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x..."
      }
    }
  }
}

重启 Claude Desktop。你应该会在工具列表中看到“hou-tea”。

Cursor

添加到 ~/.cursor/mcp.json 或 <project>/.cursor/mcp.json：

{
  "mcpServers": {
    "hou-tea": {
      "command": "npx",
      "args": ["-y", "@hou-tea/mcp-server@next"]
    }
  }
}

Cline / Continue / Zed

在它们的 MCP 配置中使用相同的 npx -y @hou-tea/mcp-server@next 调用。

配对钱包 MCP

Hou Tea 会生成 x402 支付要求，但不会持有密钥或签署交易。要使用面向 Agent 的结账流程，请将此 MCP 与支持 x402 的钱包 MCP 配对，例如 @coinbase/payments-mcp：

{
  "mcpServers": {
    "hou-tea": {
      "command": "npx",
      "args": ["-y", "@hou-tea/mcp-server@next"]
    },
    "coinbase-payments": {
      "command": "npx",
      "args": ["-y", "@coinbase/payments-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x..."
      }
    }
  }
}

让 Agent 购买前，请先为钱包充值 Base USDC。首次成功购买后，将返回的 buyer_list_token 复制到 HOU_TEA_BUYER_LIST_TOKEN，这样后续查询的订单历史就会限定在同一买家身份下。

---

试用

安装后，向你的 Agent 提问：

"推荐一款适合冬夜饮用、价格约为 $30 的暖身茶。"

Agent 会调用 hou_tea_recommend，返回包含价格和冲泡说明的真实商品，然后提出购买建议。

"我要第一个。"

Agent 会调用 hou_tea_get_payment_requirements，获取一个 402 响应，其中包含商家的 Base 链 USDC 地址和金额，以及 buy_request_body 字段（包含 register_buyer_list_token 或你保存的 buyer_list_token）。支付后重试 POST 请求 /pay/api/v1/buy 时，必须使用完全相同的 JSON 请求体，并附上 X-Payment 标头，否则买家分组会失效。如果你也安装了 @coinbase/payments-mcp 并为其配置了有资金的钱包，请将其配置为转发相同的请求体。首次成功购买后，将 JSON 响应中的 buyer_list_token 复制到 MCP 环境变量 HOU_TEA_BUYER_LIST_TOKEN，这样 hou_tea_list_my_orders 和之后的结账操作都会使用同一身份。

---

配置

所有设置均通过环境变量配置（可选）：

环境变量	默认值	用途
HOU_TEA_API_BASE	https://hou-tea.com	覆盖 API 主机（例如用于 staging）。
HOU_TEA_PAY_BASE	https://hou-tea.com/pay	覆盖 x402 中间件主机。
HOU_TEA_STORE_ID	fengshui	默认 store_id。
HOU_TEA_AGENT_KEY	(无)	可选的 X-Agent-Key，用于提高速率限制或访问私有技能。请联系 [email protected]。
HOU_TEA_BUYER_LIST_TOKEN	(无)	首次成功调用 /buy 后，将响应中的 buyer_list_token 粘贴到此处。后续调用 hou_tea_get_payment_requirements 时会将其作为 buyer_list_token 发送；此设置可启用 hou_tea_list_my_orders。
HOU_TEA_AUTO_REGISTER_BUYER_LIST_TOKEN	true	设置为 false，即可停止在 /buy 请求中发送 register_buyer_list_token / buyer_list_token（旧版行为）。

大多数用户无需设置这些变量——公共商品目录和 x402 购买端点均开放使用。如需查看买家订单历史，请在获得 HOU_TEA_BUYER_LIST_TOKEN 后设置该变量。

---

Agent UI 和 MCP Apps

next beta 版为能够呈现结构化工具结果的主机提供 MCP Apps 元数据。共享 UI 契约为公开内容：

npm i @hou-tea/agent-ui-contract

该契约目前定义了：

组件	用途
TeaRecommendationGrid	hou_tea_browse、hou_tea_recommend
PaymentReviewCard	hou_tea_get_payment_requirements
OrderTimeline	hou_tea_check_order、hou_tea_list_my_orders

工具描述符包含 _meta.ui.component、_meta.ui.schemaVersion、 _meta.ui.resourceUri 和 _meta.ui.resultMappingId。MCP 主机可以读取 相应的资源 URI，并检查嵌入的 agent-ui/v1 清单。

公开信息：

• Agent Card：https://hou-tea.com/.well-known/agent
• Agent App 文档：https://shop.hou-tea.com/agents
• UI 架构 JSON：https://shop.hou-tea.com/api/agent-ui-contract

---

故障排除

• 未显示工具：编辑 MCP 配置后，重启主机应用，然后在终端中运行 npx -y @hou-tea/mcp-server@next --help，确认 npm 可以 下载此软件包。
• 支付失败：确认已单独安装钱包 MCP、钱包中有 Base USDC，并且重试 POST 请求使用 hou_tea_get_payment_requirements 返回的完全相同的 buy_request_body。
• 订单历史为空：将已确认购买响应中的 HOU_TEA_BUYER_LIST_TOKEN 设为环境变量。没有该令牌时，hou_tea_list_my_orders 无法安全地限定买家范围。
• 公司网络阻止 npm：使用 npm i -g @hou-tea/mcp-server@next 安装一次，然后将 MCP 配置中的命令指向 hou-tea-mcp。

---

架构

┌─────────────────┐         ┌────────────────────┐
│ Claude / Cursor │         │  hou-tea.com       │
│                 │  HTTPS  │  /api/agent/*      │
│ ┌─────────────┐ │ ──────► │  (catalog/         │
│ │ hou-tea MCP │ │ ◄────── │   recommend/etc.)  │
│ └─────────────┘ │         └────────────────────┘
│                 │
│ ┌─────────────┐ │  HTTPS  ┌────────────────────┐
│ │ payments MCP│ │ ──────► │ /pay/api/v1/buy    │
│ │ (Coinbase)  │ │ ◄ 402 ─ │ x402-middleware    │
│ └─────────────┘ │         │                    │
│       │         │  Base   │   verifies on-     │
│       └─────────┼──────►──┤   chain tx, marks  │
│   USDC transfer │  chain  │   order confirmed  │
└─────────────────┘         └────────────────────┘

---

从源代码构建

git clone https://github.com/hou-tea/hou-tea-mcp-server.git
cd hou-tea-mcp-server
npm install
npm run build
node dist/index.js          # speaks MCP over stdio

npm run test:unit           # offline unit tests (envelope + registry)
npm run test:smoke          # live HTTP smoke (hits hou-tea.com)
npm run test:mcp            # full MCP stdio smoke (build + spawn)

---

0.3.0-beta 版本更新内容

此版本新增了公开的 Agent UI 协议层：

1. 公开的 MCP Apps 清单。 核心购买工具现通过 _meta.ui 提供 UI 元数据， 包括组件名称、agent-ui/v1 架构版本、资源 URI 和结果映射 ID。

2. 共享 npm 契约。 @hou-tea/agent-ui-contract 已发布，作为组件清单、 TypeScript 类型、MCP UI 资源名称和结果映射的唯一事实来源。

3. 由清单支持的 UI 资源。 MCP resources/read 响应现在会在 HTML 中嵌入 完整组件清单，使兼容的宿主无需抓取文本即可呈现商品网格、支付确认卡片和订单时间线。

4. 外部发现入口。 Agent Card 和公开的 /agents 页面会向 Agent 和开发者 提供 npm 包、架构 JSON、MCP 安装片段和钱包配对说明。

这是一个带有 next 标签的 Beta 版本；安装命令如下：

npm i @hou-tea/mcp-server@next
# or, in MCP config: "args": ["-y", "@hou-tea/mcp-server@next"]

0.1.x 系列仍可正常使用——工具名称没有变化，但 next Beta 版新增了结构化封装、 渐进式发现和 UI 元数据。

---

0.2.0-beta 版本更新内容

Anthropic 的 Skills + MCP 指南推动 MCP 服务从“一组平铺的工具”转向Agent 应用层： 渐进式发现、严格架构、适合程序处理的响应，以及明确移交给其他 MCP。 此版本将这些理念引入 @hou-tea/mcp-server：

1. 渐进式工具发现。 默认的 tools/list 会返回 6 个核心工具

   • hou_tea_discover_extended。扩展工具（hou_tea_compare、 hou_tea_filter_by_health、hou_tea_agent_card）会按需展示。 在发现前调用扩展工具会返回结构化错误：

   { "ok": false,
     "error": { "code": "extended_not_revealed",
                "retryable": true,
                "hint": "Call hou_tea_discover_extended …" } }
   

2. 每次调用都采用结构化封装。

   {
     "ok": true,
     "data": { /* tool payload */ },
     "next_action": [
       { "tool": "hou_tea_explain", "reason": "...", "args_hint": { "skill_id": "..." } }
     ],
     "meta": { "request_id": "req_…", "tool": "hou_tea_recommend",
               "took_ms": 412, "server_version": "0.2.0-beta.0" }
   }
   

   错误使用相同的封装，包含 ok: false 和稳定的 error.code （bad_request、unauthorized、not_found、conflict、timeout、 rate_limited、server_error、network_error、 missing_buyer_list_token、extended_not_revealed、unknown_tool、 internal_error）。每个错误还包含 retryable 和 hint。

3. 严格的 JSON Schema。 每个 inputSchema 都会设置 additionalProperties: false，并使用 required、enum、pattern、 minItems / maxItems 等字段，因此 Agent 端的验证器可以依赖这些约束。

4. 移交给钱包 MCP 的提示。 hou_tea_get_payment_requirements 会返回 402 buy_request_body，以及一个 next_action 区块，指引 Agent 使用 x402 钱包 MCP（例如 @coinbase/payments-mcp），然后返回 hou_tea_check_order。

5. 可追溯性。 每个响应都包含 meta.request_id，方便你将其添加到 支持工单或日志中。

这是一个带有 next 标签的 Beta 版本；安装命令如下：

npm i @hou-tea/mcp-server@next
# or, in MCP config: "args": ["-y", "@hou-tea/mcp-server@next"]

0.1.x 系列仍可正常使用——工具名称没有变化，只有结果格式和默认的 tools/list 数量不同。

---

为什么推出此项目

中国茶拥有 1,500 多年的深厚文化底蕴，全球市场规模也超过咖啡。但此前，AI Agent 要么（a）根据训练数据编造商品名称，要么（b）无法抓取由 JavaScript 渲染的商店页面。此 MCP 为 Agent 提供了一条直接、权威、原生适配 Agent的途径，让它们能够访问真实商品目录、真实价格，并通过链上结算。

如果你正在构建 AI 购物 Agent、茶叶推荐应用，或者只是希望 Claude 真正能为你买茶——这就是为你准备的。

---

许可证

MIT © hou-tea