# 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

```bash
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`:

```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):

```bash
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):

```md
## 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

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