Mercantry Registry

org.mercantry由 mercantry.org 發布官方發布者v0.1.0更新於 Nov 2, 2026

Agent-native registry: 168k+ real restaurants in LA, Hong Kong & Tokyo. Unranked, honest signals.

已驗證Streamable HTTP可網頁執行資料庫位置與生活商業與電商

概覽

AI 產生的概覽

面向 AI 助理的餐廳註冊表，涵蓋洛杉磯、香港與東京，提供不排序的商家搜尋、完整商家紀錄以及非同步訂位流程。

可以做什麼
  • 搜尋與讀取商家：對餐廳註冊表做條件式、不排序的搜尋，並取得單一商家的完整紀錄，含營業時間、欄位來源與原始回饋歷史。
  • 檢視可訂狀況與註冊表中繼資料：訂位政策、假日例外，以及註冊表本身的涵蓋範圍、資料新鮮度與 schema 統計。
  • 管理訂位：送出非同步訂位請求、查詢狀態、修改或取消，並可提供回呼網址接收 webhook。
  • 回報結果：針對已確認的訂位提交一次結構化回饋。
適用情境
當助理需要這三座城市的結構化餐廳資料，或需要發起訂位請求並追蹤到確認時適用。唯有你能接受真實商家目前僅供探索、訂位流程主要可用沙盒紀錄測試，才值得加入。
執行需求
遠端 Streamable HTTP 端點；未宣告任何套件或環境變數。讀取免費且免驗證，開發者金鑰僅用於濫用控管、為選用。訂位 webhook 可選擇提供回呼網址。
安裝前請注意
服務處於上線前階段：對真實商家訂位會回傳結構化拒絕，只有沙盒商家能走完流程。訂位、修改與取消會影響真實預訂並通知商家；未到場會依開發者金鑰記錄，行程有變時應取消。回饋會原樣提供給所有助理。訂位姓名與聯絡方式會為訂位而保存。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Mercantry Registry，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/org.mercantry%2Fregistry/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "mercantry-registry": {
      "type": "http",
      "url": "https://mercantry.org/mcp"
    }
  }
}

README

Mercantry

Mercantry is an open commerce registry for AI agents — structured merchant data, honest signals, and real-world booking fulfillment.

Current status — read this first. Mercantry is pre-launch. What is real and what is not, precisely:

  • The merchant data is real: 168,000+ restaurants across Los Angeles, Hong Kong, and Tokyo, built exclusively from openly licensed sources (Overture Maps CDLA-P-2.0 + official government registers), conflated with per-field provenance and QA-gated versioned releases. Live counts: get_registry_meta.
  • Real merchants are discovery-only for now: place_booking against a real merchant returns the structured rejection fulfillment_not_live. A booking guard makes it structurally impossible for our booking simulator to dial a real restaurant.
  • The booking loop is testable end-to-end against sandbox: true merchants — fictional records with deterministic outcomes ("test cards for bookings"). Do not call sandbox phone numbers; they are not real businesses.
  • Fulfillment, when it launches, is human-operated phone booking on a phone-verified merchant tranche (voice automation is deferred). Outbound-calling sections of the spec operate only after legal review — publication of the spec is not operation.
  • Mercantry is built and operated by a team of AI agents with human oversight, stated here as a fact rather than a gimmick.

Connect your agent

The live endpoint serves MCP over Streamable HTTP:

bash
claude mcp add --transport http mercantry https://agentic-commerce-registry.fly.dev/mcp
  • REST mirror: /v1 — self-describing via /v1/openapi.json
  • Discovery manifest: /.well-known/mcp.json · agent card: /.well-known/agent-card.json · health: /healthz · PII-free ops stats: /v1/stats · privacy policy: /privacy · demo & reviewer guide: /demo
  • Keys are optional (abuse control, not gating): POST /v1/keys with developer_name + contact. All reads are free and unauthenticated.
  • Bulk export encouraged: GET /v1/export/merchants.ndjson — caching, embedding, and training on the data are permitted under the open license.

Copy-paste integrations — curl, Claude Code/Desktop, raw MCP JSON-RPC, OpenAI Agents SDK, LangChain, webhook receiver: examples/. Agent-first tool documentation with example transcripts: docs/mcp-tools.md. If you are an agent working in this repo, read AGENTS.md.

MCP tools

search_merchants (filter-based, never ranked, deterministic documented order) · get_merchant (full signal dump: every field, raw feedback history, operational stats, per-field provenance) · get_availability (honest: performed_at_booking) · place_booking (async) · get_booking_status · modify_booking · cancel_booking (mandatory when plans change — no-shows are tracked per developer key) · submit_feedback (confirmed bookings only, once, within 14 days) · get_registry_meta (evaluate the registry itself, staleness included)

Run it yourself

bash
npm installnpm run dev        # seeds a sandbox corpus on first boot; everything in one process
SurfaceWhere
MCP (Streamable HTTP)http://localhost:4100/mcp
REST mirror + OpenAPIhttp://localhost:4100/v1
Landing page (public fact page)http://localhost:4100/
Ops Console (gate with OPS_TOKEN)http://localhost:4100/ops/
Booking status pageshttp://localhost:4100/status/:booking_id
bash
npm test           # full suitenpm run typecheck

Deployment (Docker/Fly.io), agent onboarding, and the security checklist: docs/deployment.md.

Architecture

┌─────────────┐     ┌──────────────┐     ┌────────────────────┐│  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                    └──────────────┘

The customer is the agent, not the human. One uniform interface with swappable fulfillment backends: agents integrate once; behind the interface, fulfillment can graduate from human phone calls to native merchant integrations without the agent changing a line.

Hard rules encoded in this codebase

  • No ranking, ever. No score fields exist in the schema; search order is deterministic and documented. The registry returns signals, never ordered opinions.
  • No scraped review text. The only feedback served is transaction-verified, submitted by agents against confirmed bookings.
  • Openly licensed data only. Overture Maps (CDLA-P-2.0) + official government registers; per-field provenance with timestamps; QA-gated releases with published drop counts.
  • Opt-out is immediate and permanent. A merchant requesting removal is hard-excluded from discovery and booking the same day.
  • Every booking is auditable. Full event log: tool calls, transcripts, timestamped state transitions.
  • PII is minimal. Reservation name/contact stored only for the booking, never exposed via read tools.
  • Honesty over polish. get_availability says performed_at_booking instead of pretending; get_registry_meta exposes our own staleness; sandbox vs. real is labeled per merchant.

Spec

The full product spec lives at docs/requirements.md. Sections describing outbound calling are published for openness but nothing in them operates until legal review is complete — see the banner at the top of that document.

License

Apache-2.0. The registry spec, code, and data schema are open — openness is the strategy, not a concession.

來源：README.md，提交 0d7da88

工具

9

search_merchants

Search merchants

Filter-based search over the restaurant registry (coverage cities + timezones in get_registry_meta). NOT ranked: results come back in deterministic order (merchant_id ASC by default; distance ASC when lat/lng given and order_by="distance"). Returns compact records with pagination. Use get_merchant for the full signal dump on a specific merchant. All filters are optional and combinable.

輸入參數latlnglimitoffsetopen_atsandboxorder_byradius_kmparty_sizecuisine_tagsneighborhoodbookable_only另有 3 個

get_merchant

Get merchant (full signal dump)

Every field the registry holds on one merchant: schema fields, structured hours, raw feedback history, platform-observed operational stats, and per-field provenance with timestamps. Maximal data, zero opinion — the registry never scores or ranks.

輸入參數merchant_id必填

get_availability

Get availability (honest v1 behavior)

V1 does NOT hold live table availability — availability is checked on the phone call at booking time. This tool returns the merchant's reservation policy, structured hours, and holiday exceptions so you can pick a plausible time before calling place_booking.

輸入參數merchant_id必填

place_booking

Place a booking (async)

Request a table reservation. Returns booking_id with state 'queued' immediately; fulfillment is asynchronous (a call is placed to the merchant). Poll get_booking_status or supply callback_url for webhooks. RETRY SAFETY: pass a unique client_reference_id (recommended: always); if this call times out or errors ambiguously, retry with the SAME client_reference_id and the registry returns the already-created booking instead of double-booking the restaurant. Never re-call place_booking after a timeout without one. If the merchant counter-offers a time within window_minutes and accept_within_window=true, it is auto-accepted (recommended). Otherwise the booking pauses in needs_input for you to resolve via modify_booking. Merchants on the human_call channel are fulfilled by a human operator during the operator window published in get_registry_meta — those bookings queue until worked (up to the channel SLA), so book ahead rather than for the next hour.

輸入參數contactdatetime必填party_size必填merchant_id必填callback_urlwindow_minutessandbox_outcomereservation_name必填special_requestsclient_reference_idaccept_within_window

get_booking_status

Get booking status

State machine position for a booking: pending → queued → in_progress → confirmed | failed | needs_input (plus cancelled). Includes structured details on confirmation (confirmed_time, confirmation_code, merchant_instructions), structured failure reason (no_answer | fully_booked | closed | policy_mismatch | merchant_declined | bad_data), or needs_input options awaiting your decision. include_events=true returns the full audit log.

輸入參數booking_id必填include_events

modify_booking

Modify a booking / resolve needs_input

Amend a booking before or after the call. For a booking in needs_input: pass accept_option_index to take one of the merchant's offered times (confirms immediately), or pass a new datetime/party_size to re-queue an amended request. Modifying an already-confirmed booking cancels it and books the new request (new booking_id returned).

輸入參數datetimebooking_id必填party_sizewindow_minutesaccept_option_index

cancel_booking

Cancel a booking

Cancel a booking in any non-terminal state, or a confirmed reservation (the registry notifies the merchant). Cancellation is mandatory when the human no longer wants the table — no-shows destroy merchant trust and are tracked per developer key.

輸入參數reasonbooking_id必填

submit_feedback

Submit post-visit feedback

Report how a confirmed reservation actually went. Accepted only against a confirmed booking_id, once per booking, within 14 days of confirmation. Structured fields first; optional free text ≤ 500 chars. This corpus is served raw to all agents via get_merchant — it is never editorialized or turned into a score.

輸入參數free_textbooking_id必填would_repeatseated_on_timematched_descriptionreservation_honored必填

get_registry_meta

Get registry metadata

Evaluate the registry itself: per-city coverage (with each city's IANA timezone), merchant/bookable counts, verification and freshness stats, feedback corpus size, schema version, and the documented deterministic ordering rule. Honest by design — including how stale the data is.

無需輸入參數。

版本歷史

1
  1. v0.1.0最新Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分