Skip to main content
Glama

docctx

Local-first deterministic context retrieval engine for coding agents.

What is docctx?

docctx solves a specific problem: when a coding agent needs documentation, it delivers the most precise chunks from the most trusted sources — with explainable ranking — or returns nothing.

Key principle: Wrong context is more dangerous than no context. An agent with no docs knows it doesn't know. An agent with wrong docs confidently generates wrong code.

Related MCP server: rag-retriever-mcp

Installation

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

Quick Start

# Add documentation
docctx add https://react.dev/reference/react/useEffect

# List packs
docctx list

# Query documentation
docctx query "useEffect cleanup"

# Start MCP server
docctx serve

CLI Commands

Command

Description

docctx add <url>

Ingest a URL as a context pack

docctx refresh <pack>

Re-crawl an existing pack

docctx remove <pack>

Hard delete a pack

docctx list

List all packs

docctx query "<query>"

Search documentation

docctx inspect <url|pack>

Inspect extraction or pack structure

docctx explain "<query>"

Show retrieval reasoning

docctx doctor

Health check

docctx serve

Start MCP server

MCP Configuration

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "docctx": {
      "command": "docctx",
      "args": ["serve"]
    }
  }
}

Or with uv run:

{
  "mcpServers": {
    "docctx": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/docctx", "docctx", "serve"]
    }
  }
}

MCP Tools

  • search_docs — Search chunks. Supports response_mode: compact|standard, token_budget, min_confidence: high|low|any

  • get_chunk — Get full chunk content by ID. Lazy expansion after search_docs.

  • list_packs — Discover available documentation packs.

Configuration

Config file: ~/.docctx/config.toml (auto-created on first run)

[retrieval]
floor_score = 3.0          # BM25 minimum to include
confidence_cutoff = 6.0    # BM25 threshold for "high" confidence
default_limit = 5
max_limit = 10

[chunking]
target_tokens = 400
max_tokens = 800
min_tokens = 80

[ingestion]
rate_limit_rps = 1.0
max_pages = 50
max_depth = 2
respect_robots = true

Scope Rules

Scope

Crawls

page-only

Entry URL only

siblings

Entry URL + sibling pages (same parent path) — default for deep URLs

subtree

Entry URL + all descendants

site

Entire domain (requires --scope site)

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run specific test file
pytest tests/unit/test_chunker.py -v

Architecture

INGESTION (CLI, network):
URL → Discover → Fetch → Extract → Chunk → Index → DB

SERVING (MCP, offline):
Query → FTS5 → Boost → Filter → Threshold → Chunks

Storage: ~/.docctx/store.db (SQLite WAL)
Cache: ~/.docctx/cache/ (SHA256-keyed HTML)

Available Tools

3 tools
get_chunkA

Retrieve full content of a specific chunk by ID. Use this after search_docs to lazily expand only the chunks you need. Optionally include neighboring chunks (prev/next) and document metadata.

Inputs: id (required), token_budget, include_neighbors, include_document_meta.

list_packsA

List all available documentation packs. Use this before search_docs to know what documentation is available. Returns: name, entry_url, version, chunk count, freshness status.

Inputs: name_pattern.

search_docsA

Search documentation chunks using keyword/BM25 search.

RECOMMENDED PATTERN (most token-efficient):

  1. list_packs → discover available packs

  2. search_docs (response_mode="compact") → get chunk IDs and summaries (~50 tokens/chunk)

  3. get_chunk (for relevant IDs) → get full content on demand

Token cost guide: compact: ~50 tokens/chunk (summary only) standard: ~115 tokens/chunk (summary + preview) [default] full: ~250 tokens/chunk (full content)

Result is always a structured JSON object — never null. Empty results include scanned counts and a suggestion.

Inputs: query (required), pack, limit, token_budget, +2 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: list_packs discovers available packs, search_docs finds relevant chunks, and get_chunk retrieves a specific chunk by ID. There is no functional overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: list_packs, search_docs, get_chunk. The naming is predictable and makes the action and target of each tool immediately clear.

    Tool Count5/5

    Three tools is a well-scoped size for a read-only documentation retrieval server. Each tool fills a necessary step in the discovery-search-retrieval workflow without redundancy.

    Completeness4/5

    The core workflow of listing packs, searching chunks, and retrieving full chunk content is well covered. A minor gap is that there is no direct way to enumerate all chunks within a pack, but this can be worked around via search for most retrieval needs.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Local-first codebase intelligence engine providing AI coding agents with a typed MCP toolset for understanding and navigating code repositories.
      100
      54
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      A local-first document retrieval engine that mounts as an MCP tool for agents to index files, search for relevant passages, and let the agent's own LLM answer.
      4
      -
    • A
      license
      C
      quality
      A
      maintenance
      Local-first MCP server that turns project documentation and source code into durable, evidence-backed context for AI agents, with bounded retrieval and explicit gap reporting.
      8
      256 npm
      Apache 2.0