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 分