Skip to main content
Glama
999aryaDharma

docctx

by 999aryaDharma
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesChunk ID from search_docs result.
token_budgetNoMax tokens for content. Content truncated if over budget.
include_neighborsNoInclude prev/next chunk summaries for context.
include_document_metaNoInclude document metadata (title, fetched_at, URL).

TDQS

A4.5/5.0
Behavior4/5

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

The description discloses key behaviors: content truncation based on token_budget and optional inclusion of neighboring chunks and document metadata. It does not mention error handling (e.g., invalid ID) or side effects, but for a read-only retrieval tool, the core behavior is transparent.

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 concise, using three short sentences to convey purpose, usage, and optional features. Parameter descriptions are similarly succinct and free of fluff.

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?

The description gives enough context for a moderately simple tool with 4 parameters and no output schema. It covers the main use case and parameter semantics, but omits edge-case behavior (e.g., missing ID, token_budget limits) and any return structure, which would be useful for full completeness.

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

Parameters5/5

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

All four parameters have clear, descriptive explanations that specify their purpose and effect. The id parameter notes its source (search_docs result), token_budget explains truncation, and the boolean flags define what extra context is included. The schema is fully covered.

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 specifies the action ('Retrieve full content') and the target resource ('a specific chunk by ID'). It also situates the tool in a workflow by referencing search_docs, distinguishing it from the sibling search tool.

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?

The description explicitly states when to use the tool ('after search_docs to lazily expand only the chunks you need'), which is helpful. However, it does not explicitly mention when not to use it or name alternative tools for other scenarios, leaving some inference to the agent.

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

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
name_patternNoOptional glob filter for pack names (e.g. 'react*').

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided. The description implies a read-only listing operation but does not explicitly disclose side effects, permissions, or non-destructive behavior, leaving some burden on the agent.

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 concise and well-structured, with three short sentences covering purpose, usage, and return fields without unnecessary detail.

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?

The description lists the return fields (name, entry_url, version, chunk count, freshness status) and provides usage context. It does not elaborate on field meanings or edge cases, but the information is sufficient for basic invocation.

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?

The input schema fully describes the single parameter (name_pattern) with an example. The tool description adds no additional parameter semantics beyond what is already in the schema.

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 lists all available documentation packs, with a specific verb and resource. The relationship to search_docs is hinted at, but the core purpose is unambiguous.

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 advises using this tool before search_docs to know what documentation is available. It does not explicitly state when not to use it, but the primary usage context is clear.

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

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
packNoFilter to specific pack(s). Supports glob patterns (e.g. 'react*').
limitNoMax chunks to return (default 5, max 10).
queryYesSearch query. Supports camelCase and snake_case symbols.
token_budgetNoMax tokens for response. System packs as many chunks as possible within budget.
response_modeNoResponse detail level. 'compact' = summary only (~50 tok/chunk). 'standard' = summary + preview (~115 tok/chunk).
min_confidenceNoMinimum confidence level. 'high' = BM25 score ≥ 6.0, 'any' = above floor.

TDQS

A4.8/5.0
Behavior4/5

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

With no annotations provided, the description takes on full responsibility. It discloses that results are always structured JSON, never null, and that empty results include scanned counts and a suggestion. It also details token costs per response mode. It stops short of explicitly stating read-only semantics, but the content strongly implies no side effects.

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?

Well-organized with clear sections: purpose, recommended pattern, token cost guide, and result note. Front-loaded with the main purpose and every sentence adds value. No redundancy or filler.

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?

Despite no output schema, the description explains the return format, empty-result behavior, and provides a usage flow integrating with sibling tools. All six parameters are effectively explained both in schema and description, making the tool fully callable without additional context.

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

Parameters5/5

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

Schema coverage is 100%, yet the description adds meaningful context: token cost for each response_mode, BM25 score thresholds for min_confidence, and how token_budget packs chunks. This goes well beyond the parameter descriptions and helps the agent choose effective values.

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 searches documentation chunks using keyword/BM25 search, distinguishing it from sibling tools that list packs or retrieve full chunks. The verb+resource+method are specific and not a tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a recommended workflow (list_packs → search_docs → get_chunk) with token cost guidance, explicitly showing when to use this tool versus siblings. It also explains response_mode and token_budget options for controlling output size.

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.

  1. 3 tool updatesv0.1.0
    • First observedget_chunk
    • First observedlist_packs
    • First observedsearch_docs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • agentmako

    drhalto
    A
    license
    C
    quality
    A
    maintenance
    Local-first codebase intelligence engine providing AI coding agents with a typed MCP toolset for understanding and navigating code repositories.
    100
    51
    Apache 2.0

  • rag-retriever-mcp

    code-lawyer
    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
    -

  • KnowledgeRail

    Deviank88
    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
    318 npm
    Apache 2.0