claude-code-docs MCP Server

Version: 1.0.0
Runtime: Node.js >=18 (TypeScript, ESM)
Key dependencies: @modelcontextprotocol/sdk, zod, yaml, stemmer
License: Not specified in this package

Problem Statement

Claude Code's documentation is large and frequently updated, but most MCP clients need fast, local search results rather than full-document scans. This server fetches the official docs, chunks them into semantic sections, builds an in-memory BM25 index, and exposes MCP tools that return ranked snippets.

The result is a small, focused MCP server that provides deterministic, query-focused results with minimal client integration surface: a stdio transport, four tools, and a cache-backed indexing pipeline.

Quick Start

1. From this directory, install dependencies: npm install
2. Build the server: npm run build
3. Start the MCP server (stdio transport): npm start

To use the server from an MCP client, see Client Configuration below.

How It Works

Pipeline overview:

1. Fetch official docs from the configured URL and parse Source: markers into sections.
2. Synthesize frontmatter (topic/id/category) and chunk each section at semantic boundaries.
3. Tokenize and build a BM25 index (with heading-based score boosting).
4. Serve MCP tool calls against the in-memory index.

Design properties:

• Two-cache model: a raw content cache (TTL-based) and a serialized index cache (version-gated).
• Fail-open on expected fetch/validation errors by falling back to stale cache when allowed.
• Fail-closed on programmer errors to avoid masking regressions.
• Concurrency-safe index loading with a shared in-flight promise and retry backoff.

Configuration

Environment variables:

Variable	Default	Purpose	Constraints / Behavior
DOCS_URL	https://code.claude.com/docs/llms-full.txt	Source documentation URL.	Validated on startup; must be a valid https URL.
DOCS_TRUST_MODE	official	Trust mode controlling source validation and canary policy.	official: pins source to code.claude.com, full canary evaluation (fallback-segment delta + relative-drift checks + absolute fallback-ratio warn). unsafe: accepts any HTTPS URL, structural canaries only (count + size checks). Use unsafe only for local testing or private mirrors.
RETRY_INTERVAL_MS	60000	Retry backoff for failed index loads.	Validated on startup; must be an integer between 1000 and 600000.
CACHE_TTL_MS	86400000	Content cache freshness window in milliseconds.	Integer >=0. 0 means the cache is never considered fresh (fetch each load); values > 1 year are capped.
DOCS_CACHE_MAX_STALE_MS	0	Maximum allowed age for stale cache fallback.	Validated on startup; must be an integer >=0. 0 disables the limit.
MIN_SECTION_COUNT	(unset)	Override for the canary's index floor.	Integer >=0. Unset → canary uses its trust-mode default (official: 40, unsafe: 3). 0 disables the index floor. Does NOT affect the content-cache write guard, which is fixed at 40 (CACHE_WRITE_MIN_SECTIONS) and is NOT env-disableable.
MAX_INDEX_CACHE_BYTES	52428800	Max serialized index size in bytes before writing cache.	Validated on startup; must be an integer >0. If exceeded, index cache write is skipped (server keeps in-memory index).
MAX_RESPONSE_BYTES	10485760	Max HTTP response size in bytes.	Integer >0. If declared or streamed size exceeds, fetch fails and falls back to stale cache when available.
FETCH_TIMEOUT_MS	30000	HTTP fetch timeout in milliseconds.	Integer >=0. 0 results in immediate timeout.
CACHE_PATH	unset	Override the content cache file path.	Must include a filename (not just a directory). Does not move the index cache.
XDG_CACHE_HOME	unset	Base cache directory for defaults.	When set, affects default content and index cache paths.

Default cache locations:

• macOS content cache: ~/Library/Caches/claude-code-docs/llms-full.txt
• macOS index cache: ~/Library/Caches/claude-code-docs/llms-full.index.json
• Linux content cache: $XDG_CACHE_HOME/claude-code-docs/llms-full.txt (or ~/.cache/claude-code-docs/llms-full.txt)
• Linux index cache: same directory, llms-full.index.json

Notes:

• CACHE_PATH overrides only the content cache file path. The index cache always uses the default cache directory derived from XDG_CACHE_HOME or OS defaults.
• Content cache writes use a lock file (.lock) to coordinate concurrent writers.

Tools

search_docs

Searches the indexed Claude Code docs.

Parameters:

Name	Type	Required	Default	Notes
query	string	yes	-	Max 500 chars, trimmed, must be non-empty.
limit	integer	no	5	1-20.
category	string	no	-	Canonical categories or aliases (see below).

Canonical categories: hooks, skills, commands, agents, plugins, plugin-marketplaces, mcp, channels, settings, memory, overview, getting-started, cli, best-practices, interactive, security, providers, gateways, ide, ci-cd, automation, agent-sdk, desktop, integrations, config, operations, troubleshooting, changelog, uncategorized

Aliases: subagents -> agents, sub-agents -> agents, slash-commands -> commands, claude-md -> memory, configuration -> config, gateway -> gateways

Return shape:

Field	Type	Description
results[]	object	Array of matches.
results[].chunk_id	string	Chunk identifier.
results[].content	string	Full chunk content.
results[].snippet	string	Snippet best matching the query.
results[].category	string	Derived category.
results[].source_file	string	Source URL/path.
meta	object	Index provenance attached to each search response.
meta.trust_mode	string	Active trust mode: official or unsafe.
meta.source_kind	string or null	How content was obtained: fetched, cached, stale-fallback, or bundled-snapshot. Null if no corpus loaded.
meta.index_created_at	string or null	ISO timestamp when the BM25 index was built. Null if not yet loaded.
meta.corpus_age_ms	integer or null	Milliseconds since the corpus content was obtained (Date.now() - corpus.obtainedAt). Null if no corpus loaded.
error	string	Present only on failure.

reload_docs

Forces a refresh of the docs and rebuilds the index.

Parameters: none.

Return:

• Text message indicating success, chunk count, and any parse warnings.

get_status

Returns a lightweight runtime status snapshot. Use this to check index health, trust configuration, and canary evaluation results without triggering a reload or dumping the full metadata.

Parameters: none.

Return shape:

Field	Type	Description
trust_mode	string	Active trust mode: official or unsafe.
docs_origin	string	Hostname of the documentation source URL.
docs_url	string	Full documentation source URL.
source_kind	string or null	How content was obtained: fetched, cached, stale-fallback, or bundled-snapshot. Null if no corpus loaded.
index_created_at	string or null	ISO timestamp when the BM25 index was built. Null if not yet loaded.
corpus_age_ms	number or null	Milliseconds since corpus content was obtained. Null if no corpus loaded.
corpus_obtained_at	string or null	ISO timestamp when corpus content was obtained. Null if no corpus loaded.
last_load_attempt_at	string or null	ISO timestamp of the most recent load attempt. Null if never attempted.
last_load_error	string or null	Error message from the most recent failed load. Null if last load succeeded.
warning_codes	string[]	Active warning codes: fallback_segment_drift, fallback_ratio_high, parse_issues, section_count_drift, stale_corpus.
is_loading	boolean	Whether a load/reload is currently in progress.

dump_index_metadata

Returns structured index metadata useful for debugging ingestion, category mapping, and chunk coverage without dumping the full corpus.

Parameters: none.

Return shape:

Field	Type	Description
index_version	string	Serialized index format version.
built_at	string	ISO timestamp for the response build time.
docs_epoch	string or null	Content hash for the currently loaded docs.
categories[]	object	Per-category chunk metadata.
categories[].name	string	Canonical category name.
categories[].aliases	string[]	Accepted aliases for the category.
categories[].chunk_count	integer	Number of chunks in the category.
categories[].chunks[]	object	Chunk-level metadata for debugging and inventory building.

Resources

None.

Transport

The server uses stdio transport via the MCP SDK.

Client Configuration

Example .mcp.json entry:

{
  "mcpServers": {
    "claude-code-docs": {
      "command": "node",
      "args": ["/absolute/path/to/claude-code-docs/dist/index.js"]
    }
  }
}

Tests

Run: npm test

The suite covers parser, chunker, loader, lifecycle, fetcher, metadata, and cache behavior. Special cases:

• tests/integration.test.ts is skipped unless INTEGRATION=1.
• tests/corpus-validation.test.ts depends on a populated content cache.

Known Limitations

• Stdio transport only; no HTTP/SSE transport.
• No background refresh loop; use reload_docs for refreshes.
• Category filtering is limited to the predefined list above.