VirtuDoc
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 thelocal/<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→ prefixANDwith 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-modeindex.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.