oneshot-mcp

oneshot-mcp

一个 MCP 服务，让你的编码 Agent 无需离开编辑器，就能查询 OneShot 的收据验证构建包目录。构建过程中，Agent 可以询问“这里有经过验证的构建包吗？”，而不必由你记得去查看商店。

为什么要添加它（说实话）

这是一个供应商目录：它让你的 Agent 能在常规工作流中查询 OneShot 自家的付费构建包及其验证数据。添加它很有价值，因为无论你最终是否购买，它都能发挥作用——search_packs 和 list_packs 会明确告诉你，你正在构建的内容是否有经过收据验证的构建包，并提供真实的“通过 M 次／共 N 次运行”数据，而不是营销文案。get_pack 会在你做决定前，向你展示价格、退款条款和确切的收据事实。但要清楚它的性质：这是 OneShot 向你的 Agent 展示自家产品，并非独立的推荐引擎。它绝不会称某个构建包“最好”，也不会编造收据无法证明的验证结果；每条结果都会附带价格和退款说明链接——但这个目录属于我们，其中的每一项都是我们销售的产品。

工具

• search_packs({ query, limit? }) -- 对目录进行关键词搜索（技术栈、问题或细分领域）。返回匹配的构建包：标题、一句话简介、价格、严格按照收据所支持内容表述的验证状态（例如 "3 of 3 clean-room runs passed"；如果尚无收据，则为 "unverified"）、收据摘要、退款政策链接和商店 URL。绝不对结果排名或称其为“最好”——只描述每项匹配结果，由调用方自行决定。
• get_pack({ slug }) -- 获取某个构建包的完整详情：包含内容、架构决策要点、规模范围、常见问题解答、确切的收据事实（已验证时包括各项检查的通过／失败情况、模型、Token／耗时成本）、价格、退款说明链接和购买 URL。
• list_packs() -- 以精简形式列出整个目录：每个构建包的 slug、标题、一句话简介、细分领域、价格和验证状态，以及一份退款政策摘要。

数据源：获取并回退（非内置目录）

有两个备选方案：运行时实时读取 packs/*/pack.yaml + receipt/receipt.json

• LISTING.md，或在 npm 包中附带生成好的 catalog.json。选择：实时读取，并按以下顺序优先使用 storefront 的 /catalog.json，其次使用本地检出内容：

1. 尝试 GET $ONESHOT_CATALOG_URL（默认值为 https://oneshotpacks.com/catalog.json， 超时时间为 3s）。接受裸的 pack 对象数组或 { "packs": [...] }。
2. 如果因任何原因失败——网络错误、非 2xx 响应、不是 JSON、格式错误——则回退到从 $PACKS_DIR 下的磁盘直接读取 packs/*/pack.yaml + LISTING.md + receipt/receipt.json（默认值为 ../packs，相对于当前工作目录解析——当此包和 packs/ 都位于仓库根目录时，这与 storefront/lib/packs.ts 自身的约定一致）。
3. 如果两个来源都没有内容，list_packs/search_packs 会明确说明这一点 （catalog_source: "none" + 说明性备注），而不是提供过时的内置数据。此服务绝不会捏造目录内容。

我们否决了内置 catalog.json，因为 pack 一旦重新验证或新近上架，它就会过时；之后每次更新服务都需要发布新的 npm 版本，只为刷新 storefront 已经实时提供的数据。实时读取只需一次 fetch + YAML 解析——成本与 storefront 自身的加载器相同——而且无需重新部署此服务即可保持数据最新，这正是 docs/03-marketing-distribution.md Lever 2 所述的核心目标。

**一位同事正在并行开发 storefront 的 /catalog.json 端点，该端点可能尚不存在。**此服务不依赖该端点已存在： 任何获取失败（包括目前的普通 404）都会被视为“尚未就绪”，随后直接回退到本地文件，并将错误记录到 stderr，不会崩溃。/catalog.json 发布后，只要 URL 仍为默认值，此服务就会在下一次 5 分钟缓存刷新时自动获取，无需更改配置。

响应会在进程内缓存 5 分钟，避免长时间运行的 stdio 会话在每次工具调用时都重新获取数据。

安装

目前尚未发布到 npm（发布是启动清单的第一步—— 参见 docs/09-launch-checklist.md）。在此之前，请将 MCP 客户端指向此仓库检出的绝对路径。发布后，切换到 npx 形式——结构相同，只需替换 command/args。

Claude Code

添加到项目的 .mcp.json（或通过 claude mcp add）：

{
  "mcpServers": {
    "oneshot": {
      "command": "node",
      "args": ["/absolute/path/to/oneshot/oneshot-mcp/src/index.ts"]
    }
  }
}

发布到 npm 后：

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "oneshot-mcp"]
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "oneshot": {
      "command": "node",
      "args": ["/absolute/path/to/oneshot/oneshot-mcp/src/index.ts"]
    }
  }
}

发布到 npm 后，按上述方式替换（"command": "npx", "args": ["-y", "oneshot-mcp"]）。

环境变量（可选，可放在任一客户端配置的 env 块中，或设置在 shell 中）

变量	默认值	用途
ONESHOT_CATALOG_URL	https://oneshotpacks.com/catalog.json	优先尝试的远程目录
ONESHOT_SITE_URL	https://oneshotpacks.com	用于构建 pack/购买链接的基础 URL
PACKS_DIR	../packs（相对于 cwd）	本地回退 pack 目录

要求

Node >= 22.6（使用 Node 内置的 TypeScript 类型剥离功能直接运行 .ts 源文件——无需构建步骤、打包器，也无需使用 tsc）。

开发

npm install
npm test              # node --test test/tools.test.ts
npm start             # runs the server on stdio (Ctrl-C to stop)
node src/index.ts --help

test/tools.test.ts 使用 fixtures/packs/ 中的 fixture 数据直接测试 search_packs、get_pack 和 list_packs （不经过 MCP 协议——src/catalog.ts 中的工具逻辑是与传输无关的普通函数；src/index.ts 只负责将它们接入 SDK）。覆盖范围：搜索命中、搜索未命中、如实呈现未经验证的 pack（不捏造通过率）、跳过格式错误的 pack.yaml 且不导致目录的其余部分崩溃，以及完整的获取并回退链路（远程获取成功、远程 404、远程网络错误、远程格式错误、远程条目级容错和 TTL 缓存）。