Merchant Context

商家上下文

Merchant Context 是一套面向 Agent 构建者的开放商家预检方案。

它从一个实际问题开始：

Agent 能否在不猜测的情况下判断你卖什么、面向谁、价格多少、适用哪些规则，以及下一步该采取什么操作？

此仓库包含：

• 商家发布清单；
• 商家上下文架构草案；
• 完整的 SaaS 示例；以及
• 主要商务与发现标准概览。

规范来源

• 产品与机器简介：https://merchant.atomandbits.com/llms.txt
• 0.1 版架构：https://merchant.atomandbits.com/schema/merchant-context-v0.1.json
• UCP 发现：https://merchant.atomandbits.com/.well-known/ucp
• 开源项目与历史记录：https://github.com/ihint/merchant-context

域名架构与 schema/merchant-context.schema.json 在语义上必须保持一致。版本化发布会保留旧版契约。

状态

这是 Atom & Bits 发布的早期公开草案。它不是新的支付或结账协议，也不认证对 ACP、UCP、MCP、A2A、x402 或 Web Bot Auth 的支持。

UCP 配置未声明任何服务、结账能力或支付处理程序。它为 Agent 提供明确的发现响应，不会声称支持不存在的操作。

我们的目标是为商家提供一个可测试的上下文层，并能映射到这些不断发展的系统。

我们不会依据内部测试、注册表视图、仓库活动或自费支付来声称获得了外部采用。

Agent 端点

• MCP：https://api.merchant.atomandbits.com/mcp
• 免费 MCP 工具：resolve_merchant
• 免费 HTTP：POST https://api.merchant.atomandbits.com/v1/resolve
• 付费 MCP 工具：refresh_merchant
• 付费 HTTP x402：POST https://api.merchant.atomandbits.com/v1/refresh
• 价格：在 Base 上支付 0.01 USDC
• 首笔已验证结算：Base 交易 0x2f0f…57af

首笔付费调用于 2026-08-04 完成结算，并返回了对 https://merchant.atomandbits.com 的实时检查结果。

快速开始

1. 按照 CHECKLIST.md 操作。
2. 复制 examples/saas.json。
3. 将每个示例值替换为来自你自己网站或系统的事实。
4. 确保价格、库存、政策和操作 URL 始终保持最新。
5. 发布前运行 python3 scripts/validate.py。

将其添加到 Agent

远程 MCP 端点适用于支持 Streamable HTTP 的客户端：

https://api.merchant.atomandbits.com/mcp

从 resolve_merchant 开始。

它是免费的。

命中缓存时，不会获取商家信息，也不会进行付费检查调用。

请参阅 Agent 集成指南，了解 Codex、Claude Code、 Gemini CLI、Cursor 和 OpenAI Responses API 的集成方式。

支持开放的 Agent Skills 格式的 Agent 可以使用 skills/merchant-context。

设计规则

• 事实胜于口号。
• URL 不是 API。
• Agent 不得推断价格、库存、政策或权限。
• 每项声明都应注明来源和更新时间。
• 购买或其他高影响操作应说明何时需要人工审批。
• 优先采用现有标准。应映射到这些标准，而不是发明私有方言。

Agent 服务

worker 目录包含正在测试的托管 MCP 服务。它提供：

• resolve_merchant，免费的商家记录，包含来源、时效性、未知信息、安全操作和归属信息；
• search_merchants，对缓存的、有来源的记录进行中立搜索；
• compare_offers，保留未知值的有来源比价；
• get_safe_actions，由商家提供的操作交接，并包含审批和恢复规则；
• preflight，可复用的解析和操作门控；
• check_merchant，免费的商家网站诊断；
• refresh_merchant，收费 $0.01 的 x402 最新检查，需要明确审批；
• inspect_merchant，首个版本中用于兼容付费刷新的别名；
• /v1 下的直接 HTTP 路由；以及
• /.well-known/merchant-context，面向 Agent 和注册表的公开服务记录。

检查器仅接受公开的 HTTPS 源站。它会阻止本地和 IP 目标，检查每次重定向，限制响应大小和耗时，并且不会返回页面正文。支付流程记录哈希，而非钱包地址或已签名的支付令牌。

运行本地检查：

cd worker
npm install
npm test
npm run typecheck
npx wrangler deploy --dry-run

参与贡献

欢迎提交问题、示例和更正。提交拉取请求前，请阅读 CONTRIBUTING.md。

许可证

MIT。请参阅 LICENSE。