Skip to main content
Glama

VirtuDoc

CI PyPI Python versions License: MIT

A local documentation server for AI agents. It indexes documentation from local directories into SQLite with FTS5 full-text search and serves relevant fragments to an agent through MCP tools. Fully offline: no network access happens in any mode.

Private and internal docs never leave your computer: there are no API keys, request limits, or cloud dependencies.

Installation

pip install virtudoc

Requires Python 3.11+. The only runtime dependencies are markdown-it-py (Markdown parsing) and the mcp SDK.

Related MCP server: document-index-mcp

Quick start

# Register a documentation directory and index it
virtudoc add /path/to/docs --name mylib --version 2.1.0

# Index statistics
virtudoc list

# Search from the terminal (same results an agent will get via MCP)
virtudoc search "how to handle authentication errors"

# Incremental reindexing after the docs changed
virtudoc update              # all libraries
virtudoc update --name mylib

# Full rebuild of one library (applies changed chunk.* settings)
virtudoc reindex mylib

# Remove a library
virtudoc remove mylib

# Attach a team convention note to a library (agents receive it with docs)
virtudoc note add mylib --text "Use the retry helper for all outbound calls."

# Warn when the indexed docs version diverges from the project dependency
virtudoc link mylib --project /path/to/consuming/project
virtudoc doctor   # config, sources, index integrity, version drift summary

# Zero-config onboarding: scan the project's manifests and match libraries
virtudoc init .              # report only; add --link to create the links

# Pull public documentation from a git URL or archive (the only networked command)
virtudoc fetch --repo https://github.com/org/docs --name theirlib

# Move your whole setup to another machine (see docs/installation.md)
virtudoc export            # dump the library list to ~/.virtudoc/libraries.toml
virtudoc import            # register and index everything from the file

Connect your agent

Run the MCP server and register it in your agent's config. The server speaks stdio by default and refreshes a library incrementally when an agent first requests it, so the agent always sees current documentation. Agents spawn the server with a default environment, so the data directory is ~/.virtudoc — set VIRTUDOC_HOME in the server env block if you need a custom location.

Claude Code — add to .mcp.json in your project (or run claude mcp add virtudoc --scope user -- virtudoc serve):

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

Cursor — add to .cursor/mcp.json:

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

OpenCode — add to opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "virtudoc": {
      "type": "local",
      "command": ["virtudoc", "serve"],
      "enabled": true
    }
  }
}

MCP tools

  • find-library(libraryName, query) — find the local/<name> id of a library by its name and your question. Call it first.

  • get-library-docs(libraryId, query, tokens=5000, language, page, mode, section) — Markdown fragments with heading paths and source file paths, assembled under the token budget. total_matches and has_more describe pagination; page=N+1 continues the ranking. Relevant project notes are included before the fragments. Empty results return the library's top-level sections to help rephrase the query.

Optionally expose the server over streamable HTTP on 127.0.0.1 for clients without stdio support: virtudoc serve --http [port] (default port 8765).

Supported formats: Markdown (.md, .mdx), reStructuredText (.rst), plain text (.txt), HTML (.html, .htm, best-effort text extraction). Hidden files and directories are always skipped; a .virtudocignore file at the source root (.gitignore-compatible syntax: globs, **, ! negation, directory patterns) excludes generated or vendor trees from indexing.

How it works

  • The chunker splits documents along H2/H3 headings (target chunk size 600 tokens, hard limit 1200, 60-token overlap); code blocks are never split.

  • Search is SQLite FTS5 with BM25 ranking; fragment scores are BM25 values, not positions. Queries cascade: exact AND → prefix AND with Russian ending / English suffix stemming → OR, so Russian inflections (пакетная finds пакетной) and fuzzy phrasing both resolve.

  • Results are assembled under a token budget (default 5000) with a topic boost for chunks whose heading path matches the query on token boundaries.

  • Indexing is incremental: unchanged files are skipped by content hash.

  • All data lives in ~/.virtudoc/ (WAL-mode index.db, config, log). Deleting the directory removes the system completely.

Configuration

~/.virtudoc/config.toml (all keys optional):

[chunk]
target_tokens = 600
max_tokens = 1200
overlap_tokens = 60

[search]
default_tokens = 5000
max_results = 20

[log]
level = "INFO"

Changing chunk.* only affects new indexing; the existing index is not rebuilt automatically.

Documentation

  • docs/ — full documentation: installation, getting started, CLI reference, MCP integration, configuration, indexing and search internals, project notes, version drift warnings

  • ARCHITECTURE.md — components, data flows, storage schema

Development

pip install -e '.[dev]'
pytest
ruff check virtudoc tests
ruff format virtudoc tests

Status

Milestones M1 (core: indexing, chunking, FTS5 search, CLI) and M2 (MCP server over stdio/HTTP, project notes, outline mode, .virtudocignore) are done, plus link/doctor version drift warnings and the fetch command. Published on PyPI; a demo screencast is planned.

License

MIT, see LICENSE.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Provides fast, token-efficient search over coding agent documentation (e.g., Claude Code, Cursor) using local SQLite FTS5 indexing, with tools for searching snippets, reading pages, and grepping markdown.
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Indexes local documents (PDF, Word, Markdown, text) into a SQLite database for AI agents to search and retrieve bounded, source-located passages. Runs fully locally with optional OCR, preserving privacy.
      5
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI coding agents to search, index, and manage documentation libraries with hybrid retrieval and live web fallback, all self-hosted and offline.
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to search a local, fully offline personal document library (Markdown/txt/PDF/docx) via SQLite FTS5 trigram search with subject-terminology expansion, returning every hit with its domain, document title, section path, and page or offset provenance. It also exposes domain statistics, incremental ingestion, and document deprecation as tools, alongside a read-only, runtime-persona-scoped ask/coverage mode.
      -