Oneshot MCP Server

oneshot-mcp

An MCP server that lets your coding agent query the OneShot catalog of receipt-verified build packs without you leaving your editor. Mid-build, your agent can ask "is there a verified pack for this?" instead of you having to remember to check the storefront.

Why you'd add this (honestly)

This is a vendor catalog: it lets your agent query OneShot's own paid build packs, plus their verification data, from inside your normal workflow. It's worth adding because it's useful independent of whether you ever buy anything -- search_packs and list_packs tell you plainly whether a receipt-verified pack exists for what you're building, with real "M of N runs passed" numbers, not marketing copy. get_pack puts the price, refund terms, and exact receipt facts in front of you before you decide anything. But be clear-eyed about what it is: this is OneShot listing its own products to your agent, not an independent recommendation engine. It never calls a pack "best" or invents a verification a receipt doesn't support, and every result carries the price and refund pointer -- but the catalog is ours, and every entry in it is something we sell.

Tools

• search_packs({ query, limit? }) -- keyword search (stack, problem, or niche) over the catalog. Returns matching packs: title, one-liner, price, verification status stated exactly as the receipt supports (e.g. "3 of 3 clean-room runs passed", or "unverified" if no receipt exists yet), a receipt summary, the refund-policy pointer, and the storefront URL. Never ranks or calls a result "best" -- describes each match and leaves the decision to the caller.
• get_pack({ slug }) -- full detail for one pack: what you get, architecture-decision highlights, scale envelope, FAQ, exact receipt facts (per-check pass/fail, model, token/wall-time cost) when verified, price, refund pointer, and the buy URL.
• list_packs() -- the whole catalog, compact: slug, title, one-liner, niche, price, and verification status per pack, plus the refund-policy summary once.

Data source: fetch-with-fallback (not a bundled catalog)

Two options were on the table: read packs/*/pack.yaml + receipt/receipt.json

• LISTING.md live at runtime, or ship a generated catalog.json baked into the npm package. Chosen: live reads, preferring the storefront's /catalog.json over a local checkout, in that order:

1. Try GET $ONESHOT_CATALOG_URL (default https://oneshotpacks.com/catalog.json, 3s timeout). Accepts either a bare array of pack objects or { "packs": [...] }.
2. If that fails for any reason -- network error, non-2xx, not JSON, wrong shape -- fall back to reading packs/*/pack.yaml + LISTING.md + receipt/receipt.json directly off disk under $PACKS_DIR (default ../packs, resolved from the current working directory -- matches storefront/lib/packs.ts's own convention when both this package and packs/ sit at the repo root).
3. If neither source has anything, list_packs/search_packs say so plainly (catalog_source: "none" + an explanatory note) instead of serving stale bundled data. This server never fabricates catalog contents.

A baked-in catalog.json was rejected because it goes stale the moment a pack is re-verified or newly listed, and every server update would then require a new npm release just to refresh data the storefront already has live. Live reads cost one fetch + a YAML parse -- the same low cost the storefront's own loader pays -- and stay fresh without a redeploy of this server, which is the whole point per docs/03-marketing-distribution.md Lever 2.

The storefront's /catalog.json endpoint is being built concurrently by a colleague and may not exist yet. This server does not depend on it existing: any fetch failure (including a plain 404 today) is treated as "not there yet" and falls straight through to the local-file fallback, logged to stderr, no crash. Once /catalog.json ships, this server picks it up automatically on its next 5-minute cache refresh -- no config change needed as long as it's at the default URL.

Responses are cached in-process for 5 minutes so a long-lived stdio session doesn't refetch on every tool call.

Install

Not yet published to npm (publishing is step one of the launch checklist -- see docs/09-launch-checklist.md). Until then, point your MCP client at the absolute path of this checked-out repo. After publishing, switch to the npx form -- same shape, just swap command/args.

Claude Code

Add to your project's .mcp.json (or via claude mcp add):

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

Once published to npm:

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

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

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

Once published to npm, same swap as above ("command": "npx", "args": ["-y", "oneshot-mcp"]).

Env vars (optional, either client config's env block or your shell)

Requirements

Node >= 22.6 (uses Node's built-in TypeScript type-stripping to run .ts source directly -- no build step, no bundler, no tsc in the loop).

Development

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 exercises search_packs, get_pack, and list_packs directly against fixture data in fixtures/packs/ (not through the MCP protocol -- the tool logic in src/catalog.ts is plain, transport-agnostic functions; src/index.ts only wires them to the SDK). Coverage: a search hit, a search miss, an unverified pack rendered honestly (no fabricated pass rate), a malformed pack.yaml skipped without crashing the rest of the catalog, and the full fetch-with-fallback chain (remote success, remote 404, remote network error, malformed remote shape, remote-entry-level tolerance, and TTL caching).