内容
# @hou-tea/mcp-server
> 为 [hou-tea.com](https://hou-tea.com) 提供的智能代理应用MCP服务器 —— 让您的AI代理可以浏览、推荐和 **使用USDC购买正宗中国茶**，通过 [x402协议](https://www.x402.org)。
专为Claude Desktop、Cursor、Cline、Continue、Zed以及任何兼容 [模型上下文协议](https://modelcontextprotocol.io) 的AI代理设计。
> **v0.3.0-beta** - 服务器现在作为 *代理应用层* 发布，而不仅仅是一个工具列表：
> 渐进式工具发现（核心 + 扩展）、严格的JSON模式、结构化的响应/错误信封（`ok`、`data`、`error`、`next_action`、`meta.request_id`）、
> 稳定的错误代码、显式的钱包MCP交接提示，以及MCP应用UI元数据，由公共的`@hou-tea/agent-ui-contract`包支持。参见
> [0.3.0版本变更](#what-changed-in-030-beta) 。
---
## 功能介绍
将 [hou-tea代理API](https://hou-tea.com/.well-known/agent) 以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` | 按需显示扩展工具（比较 / 健康过滤 / 代理卡） |
**扩展工具（在`hou_tea_discover_extended`后显示）：**
| 工具 | 功能 |
|---|---|
| `hou_tea_compare` | 2-4个候选产品的并排比较 |
| `hou_tea_filter_by_health` | 按条件过滤：孕妇、失眠、咖啡因敏感 |
| `hou_tea_agent_card` | 获取完整的代理能力描述符（诊断） |
**支付由支持x402的钱包MCP处理** （例如 [`@coinbase/payments-mcp`](https://github.com/coinbase/payments-mcp)) —— 该服务器仅发出支付意向，不持有密钥或签名交易。
---
## 安装
### Claude Desktop
编辑 `claude_desktop_config.json` （设置 → 开发者 → 编辑配置）：
```json
{
"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`：
```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支付要求，但不持有密钥或签名交易。对于代理原生结账，请将此MCP与支持x402的钱包MCP配对，例如`@coinbase/payments-mcp`：
```json
{
"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..."
}
}
}
}
```
在首次成功购买之前，请用Base USDC充值钱包。首次成功购买后，将返回的`buyer_list_token`复制到`HOU_TEA_BUYER_LIST_TOKEN`中，以便未来的订单历史查询限定为同一买家身份。
---
## 试用
安装后，询问您的代理：
> “推荐一种适合冬季夜晚的温暖茶，大约30美元。”
代理将调用`hou_tea_recommend`，返回带有价格和冲泡说明的真实产品，然后提供购买选项。
> “我要第一个。”
代理调用`hou_tea_get_payment_requirements`，获取带有商家Base链USDC地址和金额的402，以及`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主机（例如，用于预发布）。 |
| `HOU_TEA_PAY_BASE` | `https://hou-tea.com/pay` | 覆盖x402中间件主机。 |
| `HOU_TEA_STORE_ID` | `fengshui` | 默认商店ID。 |
| `HOU_TEA_AGENT_KEY` | *无* | 可选的`X-Agent-Key`，用于更高的速率限制/私有技能。联系 [support@hou-tea.com](mailto:support@hou-tea.com)。 |
| `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`。
---
## 代理UI和MCP应用
`next`测试版公开了MCP应用元数据，供可以渲染结构化工具结果的主机使用。共享的UI合约是公开的：
```bash
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` 清单。
公共发现：
- 代理卡：`https://hou-tea.com/.well-known/agent`
- 代理应用文档：`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/* │
│ ┌─────────────┐ │ ──────► │ (目录/ │
│ │ hou-tea MCP │ │ ◄────── │ 推荐/等) │
│ └─────────────┘ │ └────────────────────┘
│ │
│ ┌─────────────┐ │ HTTPS ┌────────────────────┐
│ │ 支付MCP│ │ ──────► │ /pay/api/v1/buy │
│ │ (Coinbase) │ │ ◄ 402 ─ │ x402中间件 │
│ └─────────────┘ │ │ │
│ │ │ Base │ 验证链上 │
│ └─────────┼──────►──┤ 交易，标记 │
│ USDC转账 │ 链 │ 订单确认 │
└─────────────────┘ └────────────────────┘
```
---
## 从源码构建
```bash
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 # 通过stdio进行MCP通信
npm run test:unit # 离线单元测试（信封 + 注册表）
npm run test:smoke # 直连HTTP冒烟测试（访问hou-tea.com）
npm run test:mcp # 完整MCP_stdio冒烟测试（构建 + 启动）
```
---
## 0.3.0版本变更
此版本添加了公共代理UI协议层：
1. **公共MCP应用清单。** 核心购物工具现在通过 `_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. **外部发现表面。** 代理卡和公共 `/agents` 页面指向代理和开发者npm包、模式JSON、MCP安装代码段和钱包配对说明。
这是一个标记为 `next` 的测试版；使用以下命令安装：
```bash
npm i @hou-tea/mcp-server@next
# 或，在MCP配置中： "args": ["-y", "@hou-tea/mcp-server@next"]
```
0.1.x版本继续有效 - 工具名称未更改，但 `next` 测试版添加了结构化信封、渐进式发现和UI元数据。
---
## 0.2.0版本变更
Anthropic的技能 + MCP指南将MCP服务器从“一平面的工具列表”推向 **代理应用层**：渐进式发现、严格的模式、程序友好型响应和显式交接给其他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`）按需显示。在发现之前调用扩展工具将返回结构化错误：
```json
{ "ok": false,
"error": { "code": "extended_not_revealed",
"retryable": true,
"hint": "调用hou_tea_discover_extended …" } }
```
2. **每次调用的结构化信封。**
```json
{
"ok": true,
"data": { /* 工具有效载荷 */ },
"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模式。** 每个 `inputSchema` 设置 `additionalProperties: false`，具有 `required`、`enum`、`pattern`、`minItems` / `maxItems` 等 - 以便代理端验证器可以依赖它。
4. **交接提示到钱包MCP。** `hou_tea_get_payment_requirements` 返回402 `buy_request_body` 以及指向x402钱包MCP（例如`@coinbase/payments-mcp`）的 `next_action` 块，然后返回到 `hou_tea_check_order`。
5. **可追溯性。** 每个响应都带有 `meta.request_id`，以便您可以将其包含在支持票/日志中。
这是一个标记为 `next` 的测试版；使用以下命令安装：
```bash
npm i @hou-tea/mcp-server@next
# 或，在MCP配置中： "args": ["-y", "@hou-tea/mcp-server@next"]
```
0.1.x版本继续有效 — 工具名称未更改，仅结果形状和默认`tools/list`大小不同。
---
## 为什么存在
中国茶有1500多年的文化深度和比咖啡更大的全球市场。但在此之前，AI代理要么（a）从训练数据中臆造产品名称，要么（b）无法刮取JavaScript渲染的商店前端。这个MCP为代理提供了一个 **直接、权威、代理原生** 的路径，通往具有真实价格和链上结算的真实目录。
如果您正在构建AI购物代理、茶推荐应用，或者只想让您的Claude能够为您购买茶 - 这就是为您准备的。
---
## 许可证
MIT © hou-tea
