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.

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)