cryosparc-docs-mcp

A small, read-only local MCP server that lets Codex / Claude Code search the official CryoSPARC documentation (guide.cryosparc.com and tools.cryosparc.com) with version awareness.

It never connects to a CryoSPARC instance, database, CLI, or job — it only serves text from a locally-built search index, so it is safe and fast.

How it works

Codex / Claude Code
   └── cryosparc-docs MCP (local stdio, Python + uv)
          └── local index: data/docs.sqlite  (SQLite FTS5 / BM25)
                 ↑ scripts/sync_docs.py fetches via sitemap (run weekly)
                    ├── guide.cryosparc.com
                    └── tools.cryosparc.com

The server does no network I/O at runtime; it reads the prebuilt index only.

Tools

tool	purpose
search_official_docs(query, cryosparc_version="auto", section=None, max_results=5)	BM25 search; version-incompatible pages are ranked lower
read_official_doc(url, heading=None, max_chars=8000)	bounded slice of one indexed page (allowlisted domains only)
docs_status()	document count + last sync time

Every search result carries: title, source_url, official_source=true, version_scope (v5.0+ / ≤v4.7 / v4.1+ / general), retrieved_at, matched_excerpt.

Setup

cd /path/to/cryosparc-docs-mcp
uv sync                                   # install deps
uv run python scripts/sync_docs.py        # build the index (network; run weekly)
uv run python scripts/sync_docs.py --limit 20   # quick smoke test

Configuration lives in config.toml — notably default_version_scope (general by default; set to v5.0+ or v4.7 to match your instance, since cryosparcm version auto-detection is not available on this box).

Register the server

Codex — ~/.codex/config.toml:

[mcp_servers.cryosparc_docs]
command = "uv"
args = ["run", "python", "-m", "cryosparc_docs_mcp"]
cwd = "/path/to/cryosparc-docs-mcp"
enabled_tools = ["search_official_docs", "read_official_doc", "docs_status"]
default_tools_approval_mode = "auto"
startup_timeout_sec = 20
tool_timeout_sec = 30

Verify: codex mcp list

Claude Code (user scope):

claude mcp add --transport stdio --scope user cryosparc-docs \
  -- uv run --directory /path/to/cryosparc-docs-mcp \
  python -m cryosparc_docs_mcp

Verify: claude mcp list, then /mcp inside a session.

Agent usage policy

Add this to your AGENTS.md (Codex) and CLAUDE.md (Claude Code):

## CryoSPARC documentation policy
1. For any CryoSPARC CLI / cryosparc-tools API / job parameter / workflow /
   version-specific question, call the cryosparc-docs MCP before answering or
   editing code.
2. Prefer documentation matching the installed CryoSPARC version.
3. Include the source URL and version scope in the answer.
4. Do not infer undocumented API arguments.
5. Do not use CryoSPARC Forum posts unless explicitly requested.
6. Do not execute CryoSPARC commands solely based on retrieved docs.

Development

uv run pytest        # tests (no network)
uv run ruff check    # lint