Skip to main content

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.

Think of it as Upstash Context7 running entirely on your machine: 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.

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

# 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 reindexes changed sources on every start, so the agent always sees the 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. 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. Queries cascade: exact AND → prefix AND with ending 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.
  • 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.

Metadata

Release files for virtudoc 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for virtudoc 0.1.0
File Size Uploaded Provenance Actions
virtudoc-0.1.0.tar.gz 50.8 kB Without provenance Details for virtudoc-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for virtudoc 0.1.0
File Interpreter ABI Platform Actions
virtudoc-0.1.0-py3-none-any.whl Python 3 none any Details for virtudoc-0.1.0-py3-none-any.whl

Total release size: 89.4 kB

Release files / virtudoc-0.1.0.tar.gz

Download URL virtudoc-0.1.0.tar.gz
Size 50.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f684d6de9be9976257cce4d3515c25355e022e547269bcfb7edf1807dd70d961
BLAKE2b-256 checksum
How to use checksums
2a4d944fc9ce0c7cfeeaee2e81c2bc23a01a713e7e0a3aa7f59771182e77dc7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / virtudoc-0.1.0-py3-none-any.whl

Download URL virtudoc-0.1.0-py3-none-any.whl
Size 38.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
73bc164895e09c6103b571fb519fbda56ebbcba54aec09dd2fb03109c5227347
BLAKE2b-256 checksum
How to use checksums
97f4d847cd38fe9eb2aaa80535d4a55daec402a4733cf84c7a3d64b6b1e96073
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for virtudoc 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page