oneshot-mcp

# 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`):

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

Once published to npm:

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

### Cursor

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

```json
{
  "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)

| Var | Default | Purpose |
|---|---|---|
| `ONESHOT_CATALOG_URL` | `https://oneshotpacks.com/catalog.json` | Remote catalog tried first |
| `ONESHOT_SITE_URL` | `https://oneshotpacks.com` | Base URL used to build pack/buy links |
| `PACKS_DIR` | `../packs` (from cwd) | Local fallback packs directory |

## 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

```bash
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).