Skip to main content
Glama
cryosparc-docs-mcp

cryosparc-docs-mcp

by riku359

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.

Related MCP server: context

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

Available Tools

3 tools
docs_statusA

Report index health: document count and last sync timestamp.

Inputs: no named parameters.

read_official_docA

Return a bounded slice of one indexed official documentation page.

Only allowlisted official domains are accepted. Provide a heading to return just that section. max_chars is capped at 20000 to protect context budget.

Inputs: url (required), heading, max_chars.

search_official_docsA

Search the official CryoSPARC docs index.

Args: query: Free-text query (CLI command, API name, parameter, workflow…). cryosparc_version: Target version such as "v5.0+" or "v4.7"; "auto" uses the server's configured default_version_scope. Version-incompatible pages are ranked below compatible ones. section: Restrict to "guide" or "tools"; omit for both. max_results: Number of hits to return (capped at 20).

Returns a dict with a "results" list; each result includes title, source_url, official_source, version_scope, retrieved_at, and matched_excerpt.

Inputs: query (required), section, max_results, cryosparc_version.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct purpose: docs_status reports index health, read_official_doc retrieves a page or section, and search_official_docs performs free-text search. There is no ambiguity or overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case: docs_status, read_official_doc, search_official_docs. The naming is predictable and clear.

    Tool Count4/5

    With only 3 tools, the set is minimal but covers the essential documentation operations: checking health, reading a specific doc, and searching. It is well-scoped for its purpose, though a few additional tools (e.g., listing available pages) might enhance completeness.

    Completeness4/5

    The tool set covers the core workflows of browsing documentation: searching, reading, and checking index status. Missing is the ability to list or navigate documentation structure, but the search+read combination likely suffices for most agent tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers