contextqmd-mcp

MCP server for local-first, version-aware library documentation. Install, search, and retrieve docs for any library directly from your AI coding assistant.

What it does

ContextQMD is an alternative to context7 that keeps documentation local. It downloads doc packages from the ContextQMD registry, indexes them with QMD (BM25 + vector + LLM reranking), and serves results through the Model Context Protocol.

Install flow is bundle-first:

1. search the library catalog and choose a library/version
2. fetch manifest
3. download a tar.gz docs bundle when available
4. verify SHA256 checksum and unpack into the local cache
5. index with QMD
6. search locally

If a compatible bundle is missing, the server falls back to page-index plus per-page fetches. Installs are atomic with rollback on failure.

Install

npm install -g contextqmd-mcp

Or run directly with npx:

npx contextqmd-mcp

MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "contextqmd": {
      "command": "npx",
      "args": ["-y", "contextqmd-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "contextqmd": {
      "command": "contextqmd-mcp"
    }
  }
}

CLI Options

--transport   Transport type: stdio (default) or http
--port      HTTP port (default: 3001)
--registry     Registry URL override
--token      API token
--cache-dir   Cache directory override

Available Tools

Search Modes

search_docs supports four modes via the mode parameter:

• auto (default) — Smart routing based on query classification: short keyword queries use FTS, conceptual/how-to questions use vector, complex multi-aspect queries use hybrid.
• fts — BM25 full-text search (fast, keyword-based). Best for API names, function lookups, and code patterns.
• vector — Semantic vector search. Best for conceptual questions. Falls back to FTS on timeout.
• hybrid — Combined BM25 + vector with LLM reranking (best quality, slower). Falls back to FTS on timeout.

Cross-library searches always use FTS regardless of mode.

Progressive Retrieval

The server uses a progressive retrieval model — search returns small snippets with line anchors, then get_doc allows bounded expansion:

1. Discover candidate libraries: search_libraries({ query: "react refs" })
2. Install the exact docs package: install_docs({ library: "react", version: "19.2.0" })
3. Search the local index: search_docs({ query: "how can i optimize refs", library: "react", version: "19.2.0" })
4. Read a bounded excerpt from the best result: get_doc({ library: "react", version: "19.2.0", doc_path: "reference/react/useRef.md", from_line: 40, max_lines: 30 })

search_docs results

Each result includes: doc_path, page_uid, title, content_md, score, snippet, line_start, line_end, search_mode, and url.

search_docs is local-only. If the library is not installed, it returns a NOT_INSTALLED error instead of silently fetching from the network.

get_doc reading modes

• Sequential: from_line + max_lines (default: line 1, 60 lines)
• Context window: around_line + before/after (default: 30 before, 60 after)
• Line numbers: set line_numbers: true to get line-number-prefixed output

Upgrade Note

Older installed libraries may still have legacy page_uid.md paths in the local QMD index. The server lazily rebuilds those indexes on first search. If the rebuild is interrupted, rerun update_docs or reinstall the affected library version.

Configuration

Config file location: ~/.config/contextqmd/config.json

{
  "registry_url": "https://contextqmd.com",
  "local_cache_dir": "~/.cache/contextqmd",
  "default_install_mode": "slim",
  "preferred_search_mode": "auto"
}

Environment variables:

• CONTEXTQMD_API_TOKEN — API token for authenticated endpoints

Architecture

src/
  index.ts              # CLI entry point, MCP server, 7 tool handlers
  lib/
    types.ts            # TypeScript interfaces for the API contract
    config.ts           # Config loader (~/.config/contextqmd/config.json)
    registry-client.ts  # HTTP client for the ContextQMD registry API
    local-cache.ts      # Local filesystem cache manager (atomic installs, page layout)
    doc-indexer.ts      # QMD-backed search indexer (FTS, vector, hybrid, query classifier)

Key design patterns:

• Local-first: All search is local-only. search_docs never touches the network.
• Bundle-first installs: Prefers tar.gz bundles; falls back to page-by-page API fetches.
• Atomic installs: Staged temp directories with backup/restore for safe upgrades.
• Idempotent operations: install_docs is a no-op when the same version/checksum is already installed.
• Security: Bundle extraction validates against path traversal, symlinks, and unsupported entry types.

Development

npm install          # install dependencies
npm run build        # compile TypeScript to dist/
npm run dev          # watch mode
npm run check        # type-check without emitting
npm test             # run tests (vitest)
npm run test:watch   # watch mode tests

Set SKIP_INTEGRATION=1 to skip integration tests that require a running registry at localhost:3000.

Requirements

• Node.js >= 22.0.0

License

MIT