Plume
Loads Shopify API documentation into a versioned, searchable knowledge base, enabling hybrid documentation search, exact endpoint/field/scope lookups, and citation-backed answers about the Shopify API.
Loads WooCommerce API documentation into a versioned, searchable knowledge base, enabling hybrid documentation search, exact endpoint/field/scope lookups, and citation-backed answers about the WooCommerce API.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Plume
Plume turns an API's documentation into a searchable, versioned knowledge base and serves it to Claude (and any MCP client), so answers about the API come with citations instead of guesses.
Builds and tags. Each import of an API's docs is an immutable, sealed build.
latestis a movable tag: publishing moves it, rolling back moves it back.Search and exact facts. Hybrid search (pgvector + Postgres full text) plus an exact index of every documented endpoint, field and scope, so "is this documented?" has evidence, and "not documented" is only said when the sources were complete.
Quality gate. Gold questions per API; a build that answers worse than the live one is not published.
Canonical models. Claude maps one concept (Order, Product…) across 2–6 APIs; Plume checks every citation against the docs and stores the result as an immutable snapshot.
Interfaces. MCP (reader + maintainer), an HTTP API, a CLI, a Claude Code plugin and a web UI.
Status: early, working end to end on Shopify, WooCommerce and Mirakl packages. Open source (MIT).
Quick start (from zero, about 5 minutes)
You need Docker, Python 3.12 with uv, and, for the web UI, Node 24.
1. Start the stack (Postgres + pgvector, the HTTP API, the MCP server):
git clone <this repository> plume && cd plume
make install # uv sync (the CLI runs on the host)
export PLUME_EMBEDDER=hash # offline embeddings; see "Real embeddings" below
export PLUME_MAINTAINER_TOKENS='["pl_change_me_to_a_long_random_token"]' # >= 16 chars
make up # API 127.0.0.1:18480, MCP 127.0.0.1:184812. Load an API. A sample package ships with the tests:
uv run plume load tests/fixtures/packages/shopify-mini --gold tests/fixtures/gold/shopify.json
uv run plume apis # shopify shopify e-commerceload reads the package, chunks and embeds it, extracts the facts, seals the build, runs the
gold questions and moves latest to it.
3. Ask something over HTTP:
curl -s -X POST 127.0.0.1:18480/v1/apis/shopify/search \
-H 'content-type: application/json' -d '{"query": "list products", "topK": 3}'
curl -s -X POST 127.0.0.1:18480/v1/apis/shopify/find-fact \
-H 'content-type: application/json' -d '{"name": "since_id"}'4. Connect Claude Code.
claude mcp add --transport http plume http://127.0.0.1:18481/mcpor load the plugin (MCP config + skills that make Claude use Plume and cite it):
claude --plugin-dir ./plugin # or /plugin install plume --marketplace <owner>/plumeThen ask, e.g. "In Shopify, which scope do I need to list assigned fulfillment orders?".
Claude Desktop/web: add http://127.0.0.1:18481/mcp as a custom connector (a local URL only
works where that host can reach it).
5. Open the web UI (browse, try search, the maintainer wizard, canonical models):
cd web && cp .env.example .env.local
# in .env.local: VITE_API_BASE_URL=http://127.0.0.1:18480 and VITE_USE_MOCKS=false
npm ci && npm run dev # http://127.0.0.1:18473Sign in to Maintainer with the token from step 1. More in web/README.md.
For a shared or long-running deployment, serve the built web UI and the API from one
origin: a reverse proxy serves web/dist and forwards /v1/ to the API (build the web with
VITE_API_BASE_URL set to that same origin). Cross-origin API calls depend on
PLUME_CORS_ORIGINS and are blocked by some embedded browsers (e.g. Claude's browser pane);
same-origin needs no CORS at all. A minimal nginx block:
location /v1/ {
proxy_pass http://127.0.0.1:18480;
proxy_set_header Host $host;
proxy_buffering off; # build and generation progress are event streams
}
location / { root /srv/plume-web; try_files $uri /index.html; }Stop with make down (data is kept in a Docker volume).
Related MCP server: docrag
Add your own API
Plume reads a connector package: a folder with connector/ (and optionally
knowledge-export/), in the format produced by Kariz stream (contract schemaVersion 1.x).
my-api/
connector/
package.json {"schemaVersion": "1.2"}
app.json name, summary, docLink, category, apiVersioning, errorFormat
endpoints/<id>/request.json method, url, name, description, responses, requiredScopes…
params.schema.json variables.schema.json body.schema.json
responses/200.schema.json
models/<name>.schema.json JSON schema (x-complete: false = partial)
knowledge/<id>.json + <id>.md guides
auth/<id>.json auth schemes and their scopes
knowledge-export/**/*.md optional cleaned page text (front matter source_url)The exact fields, and what Plume ignores, are in docs/package-contract.md. Check a package before loading it:
PLUME_CONTRACT_PACKAGES=/path/to/my-api uv run pytest tests/contract/test_package_contract.pyThen either load it with the CLI (uv run plume load /path/to/my-api) or upload it as a .zip
in the web UI's maintainer wizard (upload → review the diff and embedding plan → build with
live progress → publish). The API id comes from app.json name (slugged).
Gate it. If the package has
knowledge-export/gold-questions.json, convert it withuv run plume gold-import <package> --out <api>.json. Or write a gold set<api>.json(search questions with the expected document ids, plus present/absent facts; seetests/fixtures/gold/) and load with--gold, or put it in a folder listed inPLUME_GOLD_DIRS(the compose API mountstests/fixtures/gold, override withPLUME_GOLD_DIR). A failing build is sealed but not published (plume loadexits 2).Update it. Load the new package; unchanged chunks reuse their vectors.
plume diff <old> <new>shows what changed;plume tag <build> latestrolls back.Share it.
plume export <api> --out x.plume.jsonl.gzwrites a verified dump;plume restoreloads it anywhere in one transaction.
Real embeddings
The offline hash embedder needs no key but is not semantic. For real search quality use
Gemini embeddings (768 dims), with either key:
export PLUME_EMBEDDER=vertex PLUME_VERTEX_API_KEY=... # Vertex AI express mode
# or: export PLUME_EMBEDDER=gemini PLUME_GEMINI_API_KEY=... # Gemini API
make up && uv run plume load <package>The CLI that loads and the servers that answer must use the same embedder: a build remembers its embedding model, and search refuses to mix models (full-text mode still works). Changing the embedder means loading the packages again.
What a build contains
Item | From the package | Used for |
Endpoint documents ( |
| search, |
Model documents ( |
| search, facts, canonical models |
Guides, auth, app |
| search |
Facts | every endpoint, field (path/query/header/body/response/model) and scope, with a JSON pointer |
|
Chunks + vectors | documents split by size/headings | hybrid search |
Eval | your gold set | the gate, the quality shown in the UI |
Ids never contain the vendor's version, so the same endpoint keeps its id across vendor releases. See docs/package-contract.md.
Reference
CLI (uv run plume --help): migrate, load, apis, builds, diff, tag, eval,
gold-import, export, restore, serve (HTTP), mcp (MCP), openapi.
HTTP: docs/openapi.json (also served at /openapi.json and /docs).
Besides search and facts, each API exposes what its package contains, verbatim:
/v1/apis/{api}/items?kind=&tag= (every id resolves at /documents/{id}, with the source JSON as
raw), /auth, /triggers (events + the webhook mechanism), /environments, /mcp (the vendor's
MCP server, when it has one) and /icon; an absent section says so.
Reader routes are public and rate limited; maintainer routes need Authorization: Bearer <token>: docs/maintainer-api.md.
MCP: reader at /mcp (public, read-only), maintainer at /maintainer/mcp (bearer token):
docs/mcp-tools.md. Canonical models: docs/canonical-models.md.
Configuration (PLUME_* environment variables or a .env file; see .env.example):
Variable | Default | |
|
| |
|
|
|
| – | never logged |
| – | the Vertex key as a file (read when used, never logged): for embeddings and generation, so no key sits in a container's env |
|
| JSON list, each ≥ 16 chars; empty = maintainer API off (503) |
|
| folders of |
|
| the quality gate |
|
| per-embedder recall floor, e.g. |
|
| per client address; |
|
| behind N proxies that append to |
| the web dev server | JSON list |
| loopback | Host headers the MCP server accepts |
|
| log each MCP request's method (initialize: client, protocol, MCP Apps declared; |
|
| browser origins allowed to call the MCP endpoints (browser-based MCP clients such as the ext-apps basic-host); off by default |
|
| uploads and dumps |
| 200 MiB | package uploads |
|
|
|
|
| API evidence server generation sends the model, shared fairly by the APIs (~4 characters per prompt token); raise it for big models (e.g. |
|
| the embedding model's location on the project path (whenever |
| – / | with a project, generation calls the model at that location (gemini-4-argon answers only at |
|
| the generation model and its repair rounds |
| the packaged file | the MCP App bundle (model view) served as |
| – | the web UI's base URL; model share links are |
Compose host ports: PLUME_PG_HOST_PORT (18432), PLUME_API_HOST_PORT (18480),
PLUME_MCP_HOST_PORT (18481). Plume keeps to the 18400–18499 block.
Security notes and known limits: docs/security.md.
Development
make lint # ruff, ruff format --check, mypy --strict, import-linter
make test # architecture + unit + contract (fakes); no Docker, a few seconds
make test-int # contract (Postgres) + integration, via testcontainers
make e2e # its own compose project (ports 18434/18484/18485), torn down afterwards
make eval # the gold sets of the fixtures through the gate
make e2e-live # live embeddings (needs a key)
make e2e-live-claude # Claude Code as the client, opt-in and billed: docs/level2.mdClean architecture, enforced by import-linter (.importlinter) and tests/architecture:
src/plume/
domain/ entities and rules (builds, tags, facts, eval, canonical models); stdlib only
application/ use cases and ports (typing.Protocol)
infrastructure/ adapters: Postgres/pgvector, Alembic, embedders, package reader, dumps, settings
interfaces/ CLI (Typer), HTTP (FastAPI), MCP servers
bootstrap/ composition root
web/ React UI (talks only to the HTTP API)
plugin/ Claude Code plugin (MCP config + skills); .claude-plugin/marketplace.jsonSee docs/adr/0001-clean-architecture.md.
Docs
what Plume reads from a package, what it ignores | |
MCP tools, reader and maintainer | |
jobs, uploads, live events, publish, the gate | |
sessions, evidence, draft format, refusal codes | |
surface, controls, known gaps | |
Claude Code as the client (harness) | |
the HTTP contract |
License
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Versioned documentation registry and semantic search for AI tools and coding assistants.
Search and read the Claude Platform documentation and API reference.
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
Search the official docs of Claude Code, Cursor, OpenAI Codex and MCP, refreshed daily.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables searching and fetching Claude and Anthropic documentation with intelligent relevance scoring, optimized for MCP development, APIs, and examples.249 npm7MIT
- AlicenseNot gradedqualityDmaintenanceProvides RAG (Retrieval Augmented Generation) access to technical documentation through MCP, enabling LLMs to search and retrieve relevant documentation on-demand.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables users to search Groq's API documentation using natural language queries through an MCP-compatible interface.MIT

neonrecallofficial
AlicenseBqualityBmaintenanceEnables MCP clients to search ingested documents and ask citation-backed questions through the search_docs and ask tools.2MIT