Mercantry Registry

Mercantry

Mercantry は、AI エージェント向けのオープンなコマースレジストリです。構造化された加盟店データ、信頼できるシグナル、実際の予約手配を提供します。

現在の状況 — まずこちらをお読みください。 Mercantry はローンチ前です。実在するものと、そうでないものを正確に説明します。

• 加盟店データは実在します：ロサンゼルス、香港、東京の168,000店以上のレストランを、オープンライセンスのソース（Overture Maps CDLA-P-2.0 と政府の公式登録情報）のみから構築し、フィールドごとの出典情報と QA を経たバージョン管理付きリリースを統合しています。最新の件数は get_registry_meta で確認できます。
• 現在、実在する加盟店は検索のみ可能です：実在する加盟店に対する place_booking は、構造化された拒否応答 fulfillment_not_live を返します。予約ガードにより、予約シミュレーターが実在するレストランに電話をかけることは構造的に不可能です。
• 予約の一連の流れは、sandbox: true の加盟店でエンドツーエンドにテストできます。架空のレコードで、結果は決定的です（「予約用テストカード」）。サンドボックスの電話番号には電話をかけないでください。実在する店舗ではありません。
• サービス開始後の予約手配は、電話番号確認済みの加盟店を対象に、人が電話で予約を行います（音声による自動化は延期されています）。仕様の発信通話に関するセクションは、法務レビュー後にのみ運用されます。仕様を公開しても、運用開始を意味するものではありません。
• Mercantry は、人間の監督のもと、AI エージェントのチームによって構築・運用されています。これは売り文句ではなく、事実としてここに記載しています。

エージェントを接続する

稼働中のエンドポイントは、Streamable HTTP 経由で MCP を提供します。

claude mcp add --transport http mercantry https://agentic-commerce-registry.fly.dev/mcp

• REST ミラー： /v1 — /v1/openapi.json から自己記述型の仕様を確認できます
• ディスカバリーマニフェスト： /.well-known/mcp.json · エージェントカード：/.well-known/agent-card.json · ヘルスチェック：/healthz · PII を含まない運用統計：/v1/stats · プライバシーポリシー：/privacy · デモとレビュアー向けガイド：/demo
• キーは任意です（アクセス制限ではなく、不正利用対策のため）：developer_name と contact を指定して POST /v1/keys を実行してください。すべての読み取りは無料で、認証も不要です。
• 一括エクスポートを推奨しています： GET /v1/export/merchants.ndjson — オープンライセンスに基づき、データのキャッシュ、埋め込み、学習での利用が許可されています。

コピーして使える統合例 — curl、Claude Code/Desktop、MCP JSON-RPC の直接利用、OpenAI Agents SDK、LangChain、webhook レシーバー：examples/。サンプルのやり取りを含む、エージェント向けのツールドキュメント：docs/mcp-tools.md。このリポジトリで作業するエージェントは、AGENTS.md をお読みください。

MCP ツール

search_merchants（フィルターベース、ランキングなし、文書化された決定的な順序） · get_merchant（シグナルの全件表示：すべてのフィールド、生のフィードバック履歴、運用統計、フィールドごとの出典情報） · get_availability（正直な情報：performed_at_booking） · place_booking（非同期） · get_booking_status · modify_booking · cancel_booking（予定変更時に必須 — 無断キャンセルは開発者キーごとに記録されます） · submit_feedback（確認済みの予約のみ、1回、14日以内） · get_registry_meta（古さも含め、レジストリ自体を評価）

自分で実行する

npm install
npm run dev        # seeds a sandbox corpus on first boot; everything in one process

項目	場所
MCP（Streamable HTTP）	http://localhost:4100/mcp
REST ミラー + OpenAPI	http://localhost:4100/v1
ランディングページ（公開情報ページ）	http://localhost:4100/
Ops Console（OPS_TOKEN でアクセス制限）	http://localhost:4100/ops/
予約状況ページ	http://localhost:4100/status/:booking_id

npm test           # full suite
npm run typecheck

デプロイ（Docker/Fly.io）、エージェントのオンボーディング、セキュリティチェックリストについては、docs/deployment.md をご覧ください。

アーキテクチャ

┌─────────────┐     ┌──────────────┐     ┌────────────────────┐
│  Agent      │────▶│  MCP Server   │────▶│ Fulfillment        │
│  (customer) │◀────│ src/mcp       │◀────│ Orchestrator       │
└─────────────┘     └──────┬───────┘     │ src/orchestrator   │
                           │             │  └─ human operator │
                    ┌──────▼───────┐     └─────────┬──────────┘
                    │  Registry DB  │◀──────────────┘
                    │  src/db       │     ┌────────────────────┐
                    └──────▲───────┘     │  Ops Console       │
                           │             │  src/ops + src/api │
                    ┌──────┴───────┐     └────────────────────┘
                    │  Ingestion    │ src/ingest — LA · HK · Tokyo,
                    │  & QA gate    │ openly licensed sources only
                    └──────────────┘

顧客は人間ではなく、エージェントです。切り替え可能な履行バックエンドを備えた、統一されたインターフェースを提供します。エージェントは一度だけ連携すればよく、インターフェースの背後では、エージェント側のコードを一行も変更することなく、履行方法を人間による電話からネイティブな加盟店連携へと移行できます。

このコードベースに組み込まれた厳格なルール

• ランキングは一切行いません。 スキーマにスコアフィールドは存在せず、検索順は決定論的で文書化されています。レジストリが返すのはシグナルであり、順位付けされた意見ではありません。
• スクレイピングしたレビュー本文は扱いません。 提供するフィードバックは、予約が確定した後にエージェントが送信した、取引確認済みのものだけです。
• オープンライセンスのデータのみを使用します。 Overture Maps（CDLA-P-2.0）と政府の公式登録情報を使用し、フィールドごとにタイムスタンプ付きの来歴情報を記録します。QA ゲートを通過したリリースでは、削除件数を公開します。
• オプトアウトは即時かつ恒久的です。 削除を依頼した加盟店は、同日中に検索と予約の対象から完全に除外されます。
• すべての予約を監査できます。 ツール呼び出し、文字起こし、タイムスタンプ付きの状態遷移を含む、完全なイベントログを記録します。
• PII は最小限に抑えます。 予約者の名前と連絡先情報は予約のためだけに保存し、読み取りツール経由では決して公開しません。
• 見栄えより誠実さを優先します。 get_availability は取り繕わずに performed_at_booking と伝えます。get_registry_meta ではデータの古さを公開し、各加盟店についてサンドボックスか実環境かを明示します。

仕様

製品仕様の全文は docs/requirements.md にあります。発信通話に関するセクションは透明性を重視して公開していますが、法務レビューが完了するまでは、それらに記載された機能は一切稼働しません。このドキュメントの冒頭にあるバナーをご覧ください。

ライセンス

Apache-2.0。レジストリの仕様、コード、データスキーマはオープンです。オープンであることは譲歩ではなく、戦略です。