Mercantry Registry

Mercantry

Mercantry 是面向 AI Agent 的开放式商业注册库，提供结构化商户数据、真实可靠的信号和现实世界的预订履约服务。

当前状态——请先阅读。 Mercantry 尚未上线。以下内容准确说明了哪些是真实的，哪些还不是：

• 商户数据是真实的：洛杉矶、香港和东京有 168,000 多家餐厅，数据完全来自开放许可来源（Overture Maps CDLA-P-2.0 + 官方政府登记册），并按字段记录来源，经过质量检查后按版本发布。实时数量：get_registry_meta。
• 目前只能发现真实商户：对真实商户调用 place_booking 会返回结构化拒绝结果 fulfillment_not_live。预订保护机制从结构上确保预订模拟器不可能拨打真实餐厅的电话。
• 可针对 sandbox: true 商户端到端测试预订流程——这些是虚构记录，结果确定性可预测（“预订测试卡”）。请勿拨打沙盒电话号码；这些都不是真实商家。
• 上线后的履约服务将由人工通过电话完成预订，且仅适用于经过电话验证的一批商户（语音自动化将推迟推出）。规范中有关外呼的部分仅在法律审查后执行——发布规范不代表已投入运营。
• Mercantry 由一支 AI Agent 团队在人工监督下构建并运营，这是一项事实，而非噱头。

连接你的 Agent

线上端点通过 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 · Agent 卡片：/.well-known/agent-card.json · 健康检查：/healthz · 不含 PII 的运维统计：/v1/stats · 隐私政策：/privacy · 演示与审核指南：/demo
• 密钥为可选项（用于滥用控制，不作为访问门槛）：通过 POST /v1/keys 并提供 developer_name + contact。所有读取操作均免费且无需身份验证。
• 欢迎批量导出： GET /v1/export/merchants.ndjson — 根据开放许可，允许缓存、创建嵌入和使用这些数据进行训练。

可复制粘贴的集成示例——curl、Claude Code/Desktop、原始 MCP JSON-RPC、OpenAI Agents SDK、LangChain、Webhook 接收器：examples/。面向 Agent 的工具文档及示例对话：docs/mcp-tools.md。如果你是正在此代码库中工作的 Agent，请阅读 AGENTS.md。

MCP 工具

search_merchants（基于筛选条件，绝不排序，顺序确定且有文档说明） · get_merchant（完整信号明细：所有字段、原始反馈历史、运营统计、逐字段来源信息） · get_availability（如实返回：performed_at_booking） · place_booking（异步） · get_booking_status · modify_booking · cancel_booking（行程变更时必须调用——每个开发者密钥都会追踪未到店记录） · submit_feedback（仅限已确认的预订，每笔预订一次，且须在 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_TOKEN 访问）	http://localhost:4100/ops/
预订状态页	http://localhost:4100/status/:booking_id

npm test           # full suite
npm run typecheck

部署（Docker/Fly.io）、Agent 入门指南和安全检查清单：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
                    └──────────────┘

客户是 Agent，而不是人类。采用统一接口，并支持切换履约后端：Agent 只需集成一次；在接口背后，履约方式可以从人工电话逐步升级为商家原生集成，而无需 Agent 修改任何代码。

本代码库中编码的硬性规则

• 绝不进行排名。 架构中不存在评分字段；搜索顺序是确定的，并有文档说明。注册表只返回信号，绝不返回带排序的意见。
• 不使用抓取的评论文本。 唯一提供的反馈是交易验证后的反馈，由 Agent 针对已确认的预订提交。
• 仅使用采用开放许可的数据。 Overture Maps（CDLA-P-2.0）+ 政府官方登记信息；每个字段均记录来源及时间戳；发布经过 QA 把关，并公布剔除数量。
• 退出请求立即生效且永久有效。 商家申请移除后，当天即会从发现和预订中永久排除。
• 每笔预订均可审计。 完整事件日志：工具调用、转录文本、带时间戳的状态变更。
• 尽量减少个人身份信息（PII）。 预订姓名和联系方式仅为完成预订而存储，绝不通过读取工具公开。
• 诚实优先于表面完善。 get_availability 会说明 performed_at_booking，而不作虚假承诺；get_registry_meta 会公开我们自身数据的过时情况；每家商家均会标明是沙盒还是真实环境。

规范

完整的产品规范位于 docs/requirements.md。描述外呼的章节虽为开放透明而发布，但在法律审核完成前，其中的任何内容都不会启用——请参见该文档顶部的横幅。

许可证

Apache-2.0。注册表规范、代码和数据架构均为开源——开放是我们的策略，而不是妥协。