Skip to main content
Glama
riku359

cryosparc-docs-mcp

by riku359
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: search-docs

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses output content but lacks details on side effects or safety (e.g., read-only nature). No annotations to compensate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter status tool, the description adequately explains output; no output schema needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist; description adds value by detailing expected return values beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'report' and specific outputs (document count, last sync timestamp). Distinct from siblings, which are for reading and searching documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied for checking index health, but no explicit guidance on when to use vs alternatives or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
headingNo
max_charsNo

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses key constraints: bounded slice, allowlisted domains, heading-based section extraction, and a max_chars cap at 20000. However, it does not specify behavior on error cases (e.g., invalid URL, missing heading) nor the return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the purpose. Every sentence adds value: the first states the primary action, the second adds constraints and optional parameter behavior. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite three parameters and no output schema or annotations, the description leaves significant gaps: no explanation of return type (text, HTML?), no error handling guidance, and no clarification of 'bounded slice' (character count, page boundaries?). The description is insufficient for an agent to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaningful context for 'heading' (returns just that section) and 'max_chars' (capped at 20000 to protect context budget). However, it does not detail the 'url' parameter beyond being a required field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a bounded slice of an indexed official documentation page. It distinguishes from sibling tools (docs_status checks status, search_official_docs searches for pages) by focusing on reading a specific page.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for reading official documentation pages but does not explicitly state when to use this tool vs alternatives like search_official_docs or docs_status. No exclusions or conditional guidance are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
sectionNo
max_resultsNo
cryosparc_versionNoauto

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses return structure (dict with results), version ranking behavior, max_results cap, and section restriction. No destructive or unexpected behavior is hidden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, followed by clear bullet-point parameter descriptions and a concise return format note. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking output schema, the description fully specifies return fields. All parameters are covered, and version handling behavior is explained. The tool's context (searching docs) is fully addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but descriptions fully explain all 4 parameters: query as free-text, cryosparc_version with default and behavior, section restriction, and max_results cap. This adds critical meaning beyond mere schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear, specific verb+resource: 'Search the official CryoSPARC docs index.' It distinguishes from siblings (docs_status, read_official_doc) by focusing on search functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains parameters and version handling in detail, guiding usage context. It lacks explicit statements about when to use alternatives (e.g., read_official_doc for known URLs), but the sibling names imply differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observeddocs_status
    • First observedread_official_doc
    • First observedsearch_official_docs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers