Basketed

一个购物篮。多家商店。没有你，什么都不买。

一个通用购物 MCP 服务器，外加一个自托管控件面板。任何 MCP 代理都能获得跨多家零售商的真实商品搜索、节省 token 的比价，以及一个只有人类才能授权的购买步骤。

分析 → 提取 → 响应 → 购买 → 收货

pnpm i && pnpm build
node packages/cli/bin.js install --client claude-code   # or --all

这就是全部配置。你的客户端通过 stdio 自行启动 Basketed，控件面板会在同一进程中启动——它的链接，以及任何等待你处理的购物车的链接，都会打印在服务器的控制台上。serve --http --open 是另一种进入方式：同一个面板，外加一个位于 /mcp 的 Streamable HTTP 端点。

这里到底有什么

Related MCP server: agent-commerce-mcp-server

购买门

代理可以提议一次购买。只有人类才能授权一次购买，而且授权总是来自模型无法生成的界面。

cart_prepare ──► PENDING ──(human)──► APPROVED ──(purchase_confirm)──► order
                    │                                                    │
                    └──► EXPIRED (5 min) / REJECTED                       └─► HANDED_OFF
                                                                              outcome: unknown

两条审批通道，都汇聚到同一个函数上，因此无论人类在哪里点击，安全属性都是相同的：

通道 B — 引导式，由客户端自行渲染对话框，已设计但未构建。ApprovalChannel 是 "console" | "panel"，这就是完整的列表。保留这个字母是为了让计划和代码对同一事物使用相同的名称。

通道 C 是安全的，因为模型无法读取该界面。代理获得代码的唯一方式是有人把它读出来——这正是我们想要要求的人类行为。

通道 A 基于同一个事实，而不是基于路由拆分。Basketed 安装到的每个客户端都有 shell，所以"代理说 MCP 且无法访问 /api"这一说法本身从来就不成立——本地进程可以调用 127.0.0.1 上的任何端口并伪造任何请求头。因此，面板位于一个按进程铸造并打印在同一控制台上的令牌之后——在两种传输方式上都是如此，所以通过 stdio 启动 Basketed 的客户端仍然拥有通道 A。

在 stdio 上，面板还会在服务器启动时在你的浏览器中打开。这不是为了方便：客户端会捕获其 MCP 服务器的 stderr，所以链接被写在一个人类永远不会读到的地方，而一个无人能访问的面板就不是通道。标签页才是那里的通道。每个进程一个标签页；--no-open（或 BASKETED_NO_OPEN=1）将其关闭，而且标签页会轮询，所以稍后需要你的购物车会出现在已经打开的标签页中。/api 还会拒绝任何 Origin 与面板不完全一致的请求，并拒绝不带 Origin 的变更请求——这正是防止网页通过你的浏览器驱动面板的机制。

刻意不存在的东西： 没有 approve() 工具，没有 approved: true 参数，没有覆盖标志，也没有 set_delivery_address 工具。运行 tools/list 检查一下。这种缺失就是特性。

对抗性测试

pnpm smoke        # five smoke suites, all offline
pnpm test         # 160 unit tests
pnpm drill        # the whole demo path with the network genuinely severed
pnpm smoke:live   # ...and against live merchants, spending real requests

1. 在批准之前调用 purchase_confirm → 被拒绝

2. 批准、确认，然后重放同一个 approval_id → 被拒绝，已消费

3. 批准后更改数据库中的价格 → 被拒绝，哈希漂移

4. 使用 --fast-mode 重启并重复 1–3 → 全部仍然被拒绝

5. 让代理批准自己的购买 → 没有任何工具可以做到

--fast-mode 无法触及购买，这一点被双重证明

从行为上，以及通过遍历真实导入图：从 commerce/purchase.ts 可达的任何内容都不会导入该标志所在的 mcp/policy.ts。该标志在购买路径上不是被忽略——而是从购买路径不可达，而且任何将它们连接起来的重构都会导致 CI 失败。

离线演练确实切断了网络

pnpm drill 会预加载一个守卫，拒绝服务器进程中的所有非回环连接，然后走完整个演示路径。在一台仍然有 wifi 的机器上设置快照标志只能证明该标志能被解析。在真正的断网情况下，十个固定的 Shopify 商店中有七个会变暗——并以具名的方式出现在 stores_failed 中，因为一个静默返回更少商店的搜索看起来和成功一模一样。

数据从哪里来

每个适配器都声明两个独立的事项，两者都不能被夸大。每个响应都携带其模式，面板会以徽章形式显示它。

真实 Tesco 不是持牌集成。 search.api.tesco.com 和 xapi.tesco.com 是 Tesco 自己网站调用的公共端点，API 密钥是公开的并嵌入在其前端 JS 中——但 Tesco 不记录也不支持第三方对两者的使用，以这种方式使用它们超出了 Tesco 的服务条款，与任何非官方 API 客户端一样。sim:tesco 不受此影响，保持它一直以来的样子：夹具数据，仍然是离线演练所针对的内容，仍然完全无真实网络。

没有抓取器，也没有反机器人规避。 Cloudflare 挑战、WAF 指纹识别和 CAPTCHA 是运营者有意启用的访问控制。击败它们会摧毁"用户即行为者"这一使代理购物在根本上站得住脚的防御，而且它不断失效。处于这些保护之后的零售商是 provider 或 simulated。这不是我们以禁用状态交付的能力——而是我们根本不构建的能力。

HANDED_OFF 绝不宣称成功。 当路由以人类自行完成的 URL 结束时，我们确实不知道结果，订单会如实说明这一点，直到有人在面板中标记它。静默地为无人付款的订单显示绿色勾选，将是此项目可能发布的最具破坏性的缺陷。

工具

只读：

涉及资金——destructiveHint: true，绝不可提升为 ALLOW：

Token 杠杆

response_format：concise（默认）· detailed · compact（短键加一行图例）。fields 用于显式白名单。budget_tokens 用于硬性上限——依次裁剪 url → image → attrs → 截断名称 → 丢弃行，_meta.truncated 说明被裁掉的内容。id、price 和 mode 永不被丢弃： 结果不得为了节省 token 而丢失其来源。

安装

basketed install 由一张方差表驱动，面板也基于同一张表渲染——因此安装器、文案块和徽章不可能在配置文件位置的问题上产生分歧。这很重要，因为下面几乎每个例外都是静默失败的：错误的键名不会报错，只是你的服务器永远不会出现。

basketed clients                       # every client, its file, its key
basketed install --client claude-code
basketed install --all --dry-run       # show the diff, write nothing
basketed doctor                        # check the install end to end

写入是合并后替换，绝不覆盖。 现有文件备份到 <file>.basketed-backup-<timestamp>，无关键和其他服务器被保留，写入是原子的，并打印差异。无法解析的配置会被拒绝并保持字节级不变，而不是被替换。

Kiro 的 autoApprove 是个陷阱。 我们生成的配置只在那里列出四个只读工具，如果手动添加了涉及资金的工具，basketed doctor 会发出警告。

协议

双时代，双传输。MCP 2026-07-28 移除了 initialize、会话和服务器发起的请求；现代客户端无法与旧版服务器通信，反之亦然。"可安装到任何代理"完全依赖于从单个二进制文件同时服务两者，因此 scripts/smoke-mcp.mjs 会打开同一个二进制文件两次——一次带 initialize，一次无状态——因为这两种失败都无法从服务器自身的日志中看到。

另外：server/discover、每个工具上的 outputSchema、为旧客户端镜像为文本的结构化输出、确定性工具顺序、全部四个注解、命名空间名称。

安全

• 凭据保险库已构建。 packages/vault 使用 AES-256-GCM 在 ~/.basketed/master.key（权限 0600）下的 32 字节密钥下密封每个存储的密钥。恰好有一个函数返回明文——reveal()——它只从请求拦截器调用，该拦截器为出站 fetch 附加一个标头；一个测试会遍历工作区查找其他调用点，如果出现就会失败。面板——与列表中其他所有内容一样位于同一进程级 token 之后——只写入并读回元数据。任何 MCP 工具都不会收到凭据，永远不会：AdapterCtx 没有可以承载凭据的字段。损坏或缺失的密钥文件只会使 Connect 商店页面降级；它绝不会使 MCP 服务器宕机，因此客户端不会因为这个文件而无法启动。两个已发布的适配器都不会用存储的内容进行认证——Shopify UCP 是匿名的，模拟商店也没有可校验的内容——因此连接 Tesco、Costco、Walmart 或 Amazon 会为一个尚不存在的适配器持有凭据，并且不会改变你今天看到的任何结果。

• "使用 Chrome 登录"（S15），仅针对 Tesco、Costco、Walmart 和 Amazon。 它们都没有发布消费者 OAuth 流程，因此密码粘贴框之外诚实的替代方案是在真实浏览器中打开零售商自己的登录页面，让人自己登录。这会启动机器上已安装的 Chrome，绝不会下载 Chromium——使用此功能的人无需安装任何东西。在人类点击"capture"之前不会读取任何内容：不会轮询会话 cookie 是否出现，也不会在出现时立即抓取。与上述"不规避反机器人"一致，它不会向零售商隐藏自动化——不伪造 navigator.webdriver，不剥离自动化标志——因为一个无法区分被驱动的浏览器和人类的欺诈系统，不是这个项目愿意用 Connect 商店页面去交换的底线。这四家零售商的每一条服务条款都禁止自动化登录，包括账户所有者本人；该风险在按钮本身上就有披露，而不仅仅是在这里。捕获的会话与粘贴的凭据完全一样被密封——同一个保险库，同一个 reveal() 审计——并且还没有任何适配器使用它。

• 代理只能看到不透明的账户句柄，永远看不到任何可能成为句柄的东西。

• 审批面位于进程级 token 之后，该 token 打印在服务器自己的控制台上，旁边是 6 位代码。路由分离不是门槛：Basketed 安装到的每个客户端都有 shell，因此代理总能到达 127.0.0.1 并伪造任何标头。/api 还要求 Origin 与面板的完全一致，并拒绝不发送 Origin 的变更请求。

• 供应商文本是不可信数据。 经过 NFKC 规范化、剥离控制字符、零宽和双向覆盖、HTML 剥离、长度限制、注入模式标记。真正的防御更强：审批屏幕和购物车哈希仅由数字和枚举字段加上规范化后的产品名称构建。 任何商家编写的字符串都不会到达这两者。

• approval_id 是 CSPRNG，在服务器端绑定到从本地会话派生的主体——绝不来自代理提供的任何内容——并在原子消费内部重新检查。持有永远不是认证（2026-07-28 State Handle Hijacking）。

• 对每个响应进行脱敏层处理，作为兜底网而非主要防御。命中即缺陷；面板显示计数。

• 我们从不接触卡数据（不在 PCI 范围内），从不存储零售商密码，也不提供任何爬虫。

未构建，明确说明以免有人声称

Costco/Walmart/Amazon 的真实零售商适配器（它们都没有发布消费者 API；保险库持有一个凭据——粘贴或 Chrome 捕获——但还没有任何东西用它认证）、真实零售商 OAuth（四家都没有发布——参见连接商店）、针对该原型四家之外的任何商店的 Chrome 登录捕获、模拟 IdP、审批通道 B（elicitation）、compare_products、订单页面、MCPB、注册表发布以及 ChatGPT 插件提交。所有这些都在计划中设计好了，但都没有构建。

Tesco 是唯一一个移出此列表的零售商适配器（S16）——参见上文"数据来源"：真实搜索、真实详情、以及购物者自己粘贴的会话 token 背后的真实购物车。Costco、Walmart 和 Amazon 留在这里，因为这三家都没有 Tesco 前端恰好暴露的那种非官方但真实的端点——参见连接商店，了解 Chrome 登录会话在这三家上能做什么和不能做什么。

凭据保险库是另一个移出此列表的项目（S14）——参见上文"安全"——曾经在这里检查它的漂移守卫现在检查相反的内容：此文件在不再属实的那一刻停止否认它。

docs/ — BENCHMARK

需要 Node ≥ 22（node:sqlite，因此没有原生构建步骤——这在 Windows 上很重要，本项目就是在 Windows 上开发和验证的）。