Hou Tea — Buy Chinese tea via x402 USDC

@hou-tea/mcp-server

hou-tea.com 用のエージェントアプリ向け MCP サーバーです。x402 protocol を介して、AI エージェントが本格的な中国茶を閲覧、推薦し、USDC で購入できるようにします。

Claude Desktop、Cursor、Cline、Continue、Zed、および Model Context Protocol 互換のあらゆる AI エージェント向けに設計されています。

v0.3.0-beta - サーバーはツール一覧だけでなく、エージェントアプリレイヤー として提供されるようになりました： 段階的なツール検出（コア＋拡張）、厳格な JSON Schemas、構造化された レスポンス／エラーエンベロープ（ok、data、error、next_action、meta.request_id）、 安定したエラーコード、ウォレット MCP への明示的な引き継ぎヒント、および 公開パッケージ @hou-tea/agent-ui-contract に基づく MCP Apps UI メタデータが含まれます。以下の0.3.0 での変更点をご覧ください。

---

できること

hou-tea エージェント 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（Bearer。HOU_TEA_BUYER_LIST_TOKEN 環境変数を使用）で自身の x402 注文を一覧表示します
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）が処理します。このサーバーは支払いインテントを生成するだけで、キーを保持したりトランザクションに署名したりすることはありません。

---

インストール

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 の支払い要件を出力しますが、キーを保持したりトランザクションに署名したりすることはありません。エージェントによるチェックアウトを実現するには、この MCP を @coinbase/payments-mcp のような x402 対応ウォレット 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..."
      }
    }
  }
}

エージェントに購入を依頼する前に、ウォレットに Base USDC を入金してください。最初の購入が成功したら、返された buyer_list_token を HOU_TEA_BUYER_LIST_TOKEN に設定してください。これにより、以降の注文履歴の問い合わせが同じ購入者 ID に限定されます。

---

試してみる

インストール後、エージェントに次のように尋ねてください。

「冬の夜に飲む、30 ドル前後の体が温まるお茶をおすすめしてください。」

エージェントは hou_tea_recommend を呼び出し、実際の商品と価格、淹れ方のメモを返した後、購入を提案します。

「最初のものにします。」

エージェントは hou_tea_get_payment_requirements を呼び出し、マーチャントの Base チェーン上の USDC アドレスと金額に加えて、buy_request_body フィールド（register_buyer_list_token または保存済みの buyer_list_token を含む）を含む 402 を受け取ります。支払い後に /pay/api/v1/buy へ再試行の POST を送信する際は、必ずその JSON 本文をそのまま使用し、X-Payment ヘッダーも付けてください。そうしないと、購入者のグループ化が機能しません。資金を入金したウォレットを使用する @coinbase/payments-mcp もインストールしている場合は、同じ本文を転送するよう設定してください。最初の購入が成功した後、JSON レスポンスから buyer_list_token をコピーし、MCP 環境変数 HOU_TEA_BUYER_LIST_TOKEN に設定すると、hou_tea_list_my_orders と今後のチェックアウトで同じ ID を使用できます。

---

設定

すべての設定は環境変数で行います（任意）。

環境変数	デフォルト	用途
HOU_TEA_API_BASE	https://hou-tea.com	API ホストを上書きします（例：ステージング環境用）。
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	/buy で register_buyer_list_token / buyer_list_token を送信しないようにするには、false に設定します（従来の動作）。

ほとんどのユーザーはこれらの設定を必要としません。公開カタログと x402 の購入エンドポイントは開放されています。購入者の注文履歴を利用するには、購入が確定した後に HOU_TEA_BUYER_LIST_TOKEN を設定してください。

---

エージェント UI と MCP Apps

next ベータ版では、構造化されたツール結果を表示できるホスト向けに 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 マニフェストを確認できます。

公開されている情報：

• エージェントカード：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/*      │
│ ┌─────────────┐ │ ──────► │  (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 ページから、npm パッケージ、スキーマ JSON、MCP のインストール用スニペット、ウォレットのペアリング手順をエージェントや開発者に案内します。

これは next タグ付きのベータ版です。次のコマンドでインストールできます。

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

0.1.x 系統も引き続き動作します。ツール名は変更されていませんが、next ベータ版では構造化エンベロープ、段階的な検出、UI メタデータが追加されています。

---

0.2.0-beta での変更点

Anthropic の Skills + 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）は、必要に応じて公開されます。検出前に拡張ツールを呼び出すと、次の構造化エラーが返されます。

   { "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 なども指定しています。そのため、エージェント側のバリデーターでこれらを前提にできます。

4. ウォレット MCP への引き継ぎヒント。 hou_tea_get_payment_requirements は、402 の buy_request_body と、エージェントを x402 ウォレット MCP（例：@coinbase/payments-mcp）に案内し、その後 hou_tea_check_order に戻す next_action ブロックを返します。

5. トレーサビリティ。 すべての応答に meta.request_id が含まれるため、サポートチケットやログに記載できます。

これは next タグ付きのベータ版です。次のコマンドでインストールできます。

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

0.1.x 系統も引き続き動作します。ツール名は変更されておらず、異なるのは結果の形式と、デフォルトの tools/list のサイズのみです。

---

これが存在する理由

中国茶には 1500 年以上の文化的な深みがあり、世界市場の規模はコーヒーを上回ります。しかしこれまでは、AI エージェントが（a）学習データから商品名を幻覚したり、（b）JavaScript で描画されるストアフロントのスクレイピングに失敗したりしていました。この MCP は、実際の価格と実際のオンチェーン決済を備えた実在の商品カタログへ、エージェントが直接、信頼できる、エージェント向けの方法でアクセスできるようにします。

AI ショッピングエージェントやお茶のおすすめアプリを開発している方、あるいは Claude で実際にお茶を買えるようにしたい方に最適です。

---

ライセンス

MIT © hou-tea