# ShopDB MCP server

Exposes a ShopDB instance to an LLM client (Claude Code, Claude Desktop, or any
other MCP client) so it can discover and call the API directly, instead of
someone generating a client by hand from the spec.

## The token is the security boundary

**Read this before pointing it at production.**

Every operation the credential is allowed to perform is reachable through this
server, including writes and deletes. There is no separate allow-list here: the
scope of the personal access token decides what can happen, and nothing else
does.

That is a deliberate choice, and it puts the decision where it can be enforced
server-side rather than in a client that a model is talking to. It also means:

- For anything exploratory, create a **read-scoped token**. A read-scoped token
  cannot be talked into a write, whatever the model decides to call.
- Give it the narrowest scopes that cover the task, not your admin session.
- `DELETE` against an asset database is irreversible. The tool descriptions say
  so, which makes a model markedly more careful, but a token that permits it is
  the only thing standing in the way.

Create a token under Settings > API Tokens. `shopdb_whoami` reports what the
token can do; call it first.

## Install

    pip install -e tools/mcp

Then register it with your client. For Claude Code:

    claude mcp add shopdb \
      --env SHOPDB_URL=https://shopdb.example.net/shopdb \
      --env SHOPDB_TOKEN=<token> \
      -- shopdb-mcp

`SHOPDB_URL` must include the mount path if the site is served under one
(`/shopdb`), because that is what the instance's own spec declares.

| Variable | Required | Meaning |
|---|---|---|
| `SHOPDB_URL` | yes | Base URL including any mount path |
| `SHOPDB_TOKEN` | yes | Personal access token |
| `SHOPDB_VERIFY_TLS` | no | `0` to accept a self-signed certificate. Defaults to verifying |

## Tools

| Tool | Purpose |
|---|---|
| `shopdb_whoami` | Instance, identity, scopes, operation count. Call first |
| `shopdb_search_operations` | Find operations by keyword or tag. Start here |
| `shopdb_describe_operation` | Parameters, request body and responses for one operation |
| `shopdb_call` | Call any operation |
| `shopdb_llms_guide` | The instance's own orientation guide |

## Why five tools and not 483

ShopDB publishes 483 operations. One tool each would be unusable: MCP clients
degrade badly past a few dozen tools and models start choosing wrong ones. So
the surface is small and generic, and the instance's own published index is what
makes it navigable - `search` reads `/api/docs/operations.txt` (about 70 KB for
every operation) and `describe` fetches only the tag group it needs rather than
the 700 KB spec.

Nothing is generated ahead of time. Enabling a plugin adds operations this
server can already reach, with no change here and no reinstall.

## Staying current

The server reads everything from the live instance, so it describes whatever
that instance actually serves. The staleness risk is upstream: `docs/openapi.json`
is generated and committed, and if it drifts, the instance serves a stale spec
and this server faithfully reports stale information.

That is guarded by the `api-contract` CI job and by
`python scripts/gen_openapi.py --refresh`. See CONTRIBUTING.md.

## Limitations

- Air-gapped sites need `mcp` vendored; it is not bundled here.
- No streaming or subscriptions - every tool is a request and a response.
- Responses over 100 KB are truncated with a note. Paginate instead
  (`perpage` is silently capped at 100 by the API).