Skip to main content
Glama
jpsweeney97

claude-code-docs

by jpsweeney97
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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.

Related MCP server: MCP Context Manager

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, environments, 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.

Available Tools

4 tools
dump_index_metadataDump Index MetadataA

Dump full BM25 index metadata: categories, chunk IDs, headings, code literals, config keys, and distinctive terms. No parameters.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
built_atYesDEPRECATED: Response generation time. Use index_created_at for actual index build time.
categoriesYes
docs_epochYes
index_versionYes
index_created_atYes

TDQS

A4.3/5.0
Behavior4/5

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

No annotations provided, but description clearly indicates a read-only dump operation with no side effects. Could mention potential performance impact or locking, but current text is adequate for a simple tool.

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?

One sentence plus 'No parameters.' Extremely concise with no wasted words. Front-loaded with main action.

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?

Given an output schema exists (not shown), description needn't detail return format. It lists what is dumped, providing sufficient context for a straightforward dump operation.

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; schema coverage is 100%. The description adds value by enumerating the metadata contents, exceeding the bare schema. Baseline 4 justified.

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 the tool dumps BM25 index metadata and lists specific items (categories, chunk IDs, etc.). Distinguishes from sibling tools (reload_docs, search_docs, get_status) by focusing on metadata retrieval.

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?

Implies usage when needing index metadata but does not explicitly state when to avoid or contrast with alternatives. The 'No parameters' clue helps, but lacks direct guidance.

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

get_statusGet Server StatusA

Get current status of the claude-code-docs server: trust mode, documentation source, index age, and any active warnings.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
docs_urlYes
is_loadingYes
trust_modeYes
docs_originYes
source_kindYes
corpus_age_msYes
warning_codesYes
last_load_errorYes
index_created_atYes
corpus_obtained_atYes
last_load_attempt_atYes

TDQS

A4.1/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses the output fields and implies a read operation, but does not explicitly state safety, side effects, or auth requirements. For a simple status tool, this is adequate but not thorough.

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 a single sentence that is front-loaded with purpose and includes key details. Every word earns its place; no waste.

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?

For a zero-parameter tool with an output schema, the description fully explains what the tool returns and covers all relevant aspects. It is complete and sufficient for an agent to select and invoke correctly.

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?

There are no parameters, and schema coverage is 100%. The description adds no parameter info because none is needed. Baseline is 3, but the absence of parameters makes the description sufficient.

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 retrieves server status and lists specific fields (trust mode, documentation source, index age, warnings). It is a specific verb+resource and distinguishes from siblings like reload_docs and search_docs.

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 does not provide explicit when-to-use or when-not-to-use guidance. However, the sibling tools are clearly different actions, so usage is implied for status checks. No exclusions or alternatives are mentioned.

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

reload_docsReload Claude Code DocsA

Force reload of Claude Code documentation. Use after editing docs to refresh search index.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior2/5

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

No annotations are provided, so description must disclose behavioral traits. It only says 'Force reload', which implies a destructive or disruptive action but does not explain potential side effects (e.g., temporary search unavailability, auth requirements, or whether it is idempotent).

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?

Two efficient sentences, front-loaded with purpose, no wasted words.

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?

Given zero parameters and no output schema, the description covers the action and when to use it. Could mention if it blocks or returns a status, but overall adequate.

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 has zero parameters (100% coverage), so description need not add parameter details. Baseline score 4 is appropriate with no parameters to document.

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?

Description clearly states the verb 'Force reload' and the resource 'Claude Code documentation'. It distinguishes from siblings by specifying the purpose is to refresh the search index after editing docs.

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?

Explicitly says 'Use after editing docs to refresh search index', providing a clear context. While it doesn't mention alternatives, the sibling tools suggest other actions like searching or status checks.

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

search_docsSearch Claude Code DocsA

Search Claude Code documentation (extensions, setup, security, providers, IDE integration, CI/CD, and more). Use specific queries.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results to return (default: 5, max: 20)
queryYesSearch query — be specific (e.g., "PreToolUse JSON output", "skill frontmatter properties")
categoryNoFilter to a specific category (e.g., "hooks", "plugins", "security")

Output Schema

ParametersJSON Schema
NameRequiredDescription
metaNoProvenance and trust metadata for the search index
errorNoError message if search failed
resultsYes

TDQS

A3.5/5.0
Behavior2/5

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

No annotations provided, and description does not disclose behavioral traits such as response structure, rate limits, or what happens with empty results. Only states the purpose.

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?

Two sentences, front-loaded purpose, no wasted words. Highly concise and structured.

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

Completeness3/5

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

Output schema exists so return values are covered, but description lacks context on result behavior (e.g., no results, limit usage) and is minimal for a search tool.

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

Parameters3/5

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

Schema description coverage is 100%, so baseline is 3. Description adds minimal value beyond schema; 'Use specific queries' is already suggested in the query parameter's description.

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?

Description clearly states 'Search Claude Code documentation' with specific verb and resource, and lists example topics that distinguish it from sibling tools like reload_docs or get_status.

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?

Implies usage by saying 'Use specific queries' but provides no explicit guidance on when to use this tool versus siblings or when not to use it.

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. Dates show when Glama detected each change.

  1. 4 tool updatesv1.1.0
    • First observeddump_index_metadata
    • First observedget_status
    • First observedreload_docs
    • First observedsearch_docs
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: reloading docs, searching, getting server status, and dumping index metadata. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case (e.g., reload_docs, search_docs, get_status, dump_index_metadata), making them predictable.

Tool Count5/5

Four tools is well-scoped for a documentation management server, covering all necessary operations without being excessive or insufficient.

Completeness4/5

The tool set covers the core lifecycle: reloading, searching, status, and metadata inspection. A minor gap could be a tool to add or update documentation sources, but current set is largely complete.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Semantic Search MCP Server

    camilojourney
    F
    license
    Not graded
    quality
    B
    maintenance
    Provides hybrid semantic and keyword code search for Claude Code using BM25 and vector retrieval. It enables indexing and searching local codebases with language-aware chunking and local embeddings.
    -

  • MCP Context Manager

    transparentlyok
    A
    license
    A
    quality
    D
    maintenance
    Enables efficient code navigation and retrieval through natural language search, BM25 ranking, and fuzzy matching across multiple programming languages. It drastically reduces token usage by allowing Claude to query specific code symbols and logic instead of reading entire files.
    13
    11
    13
    MIT

  • code-rag-mcp

    qduc
    A
    license
    A
    quality
    D
    maintenance
    Enables semantic search over codebases using natural language queries, returning relevant code snippets with source locations. Integrates with Claude Code for automatic codebase exploration.
    1
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jpsweeney97/claude-code-docs-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server