cod-doc MCP server
Commit Nov 12, 2026Maintains project documentation integrity by using a SQLite database as the source of truth and providing hash-verified markdown projections.
Also known as Orange-hanter/cod-doc
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- MIT
What is cod-doc MCP?
cod-doc maintains project documentation integrity by using a SQLite database as the source of truth and providing hash-verified markdown projections.
Summary generated from the project's README
About cod-doc MCP server
Maintaining documentation that stays synchronized with code changes is what cod-doc enables for developers and LLM agents. By using a local SQLite database as the single source of truth, this system ensures that markdown files are merely projections of the underlying state. This prevents documentation from silently drifting away from the actual tasks, plans, and architectural decisions recorded in the database.
Users interact with the system through a CLI, a web UI, or an MCP server configured via cod-doc-mcp. The MCP server provides specific profiles, such as the agent profile for documentation curators or the full profile for coding agents. It requires Python 3.14+ and relies on a single local database file located in the project directory.
What distinguishes this tool is its use of content hashes to detect when markdown files have been edited outside of the system. It offers an append-only revision history for every document and task, allowing for precise reverts without relying on git blame. The system also manages a seven-state task lifecycle with dependency graphs to prevent agents from racing during work execution.
What you can do with it
- 1Detecting documentation driftIdentify which markdown files were modified manually instead of through the database system.
- 2Managing task dependenciesCoordinate complex development workflows using a structured task engine and dependency graphs.
- 3Tracking document revisionsReview the full history of changes for a specific document or task to perform reverts.
Written from the project's README. Every use case is checked against a quote from it.
README
View on GitHubDocs, tasks, plans, stories, links and revisions live in a database
(<project>/.cod-doc/state.db). Markdown is a projection of that state, not
the source of truth — so a doc can never silently drift away from the task that
changed it.
Features
- Hash-verified docs. Every markdown file carries a content hash of the DB
state it was projected from.
cod-doc doc drifttells you exactly which file was edited behind the system's back. - Every edit is a revision. Full append-only history per document and per
task, with revert — not a
git blameon a 900-line file. - First-class links. Documents, sections, tasks, ADRs and git commits reference each other as rows. Renames cascade instead of rotting.
- Task engine with atomic checkout. 7-state task lifecycle, dependency graph, plan sections, ready-queue — agents lock work instead of racing it.
- Built for LLM agents. The default
agentMCP profile is a documentation curator (agent_capabilities,curator_next,ctx_search,ctx_drift,context_get,agent_report): one queue of what to fix, with a ready command per item — no full-catalog cold start. Task-centric tools (agent_pick,task_checkout,task_complete, …) are not in theagentprofile: they are visible only on--profile standard/full, where coding agents execute tasks. - Zero infrastructure. Python 3.14+ and the SQLite that ships with it. No daemon, no indexer, no external database — the project DB is a single file.
Quick start
pip install cod-doc
cod-doc project add . --name myproj # register the project, create its DB
cod-doc import docs myproj # ingest existing .md into the DB
cod-doc serve # REST API + web UI on http://localhost:8765
cod-doc-mcp --profile agent # MCP over stdio for Claude Code / Desktop
Why not just…
| Markdown + Git | Wiki (Notion, Confluence) | COD-DOC | |
|---|---|---|---|
| Detects doc↔code drift | ❌ | ❌ | ✅ content hashes |
| Queryable structure (tasks, deps, links) | ❌ grep only | ⚠️ proprietary | ✅ SQL + API |
| Native interface for LLM agents | ❌ | ⚠️ via API tokens | ✅ MCP, first-class |
| Per-entity history & revert | ⚠️ per-file git log | ✅ | ✅ append-only revisions |
| Lives in your repo, works offline | ✅ | ❌ SaaS | ✅ single SQLite file |
| Human & agent share one contract | ❌ | ❌ | ✅ same service layer |
Four equal surfaces
| Surface | Entry point | For |
|---|---|---|
| CLI | cod-doc |
day-to-day human work; task, doc, plan, story, link, adr groups |
| MCP | cod-doc-mcp |
LLM agents; profiles agent (curator tools, default), minimal, standard, full — counts: python -m cod_doc.mcp.profile_counts |
| REST + Web | cod-doc serve |
dashboards, review, editing in the browser |
| TUI | cod-doc tui |
legacy terminal UI |
New functionality lands in the service layer and must appear in both the CLI and MCP — agent and human get an identical interface by construction.
Screenshots
| Overview | Docs | Tasks |
|---|---|---|
 |
 |
 |
| Plans | Task detail | Revision history |
|---|---|---|
 |
 |
 |
Documentation
| Document | What it is |
|---|---|
docs/cod-doc-guide.md |
tutorial: document a project from scratch, ~30 min |
docs/HANDBOOK.md |
reference: install, CLI, web UI tour, config, troubleshooting |
docs/adoption-playbook.md |
adopting COD-DOC on an existing repo with accumulated markdown |
docs/mcp-integration.md |
wiring the MCP server into Claude Code, Claude Desktop, VS Code |
docs/zsh-completion.md |
zsh tab-completion: install, how live DB values are resolved |
AGENTS.md |
contributing: DB workflow, Definition of Done, PR requirements |
MASTER.md |
the project's own map, maintained by COD-DOC itself |
The repository is documented in Russian; this README is the English entry point.
Requirements
Python 3.14+ (3.14 tested in CI; 3.13 dropped 2026-10-05, 3.11/3.12 on 2026-09-07). SQLite ships with Python; no
external database, daemon or indexer is required. The project DB is a single
file under .cod-doc/ and must live on a local disk — WAL mode does not work
on iCloud, NFS or SMB shares.
License
MIT.
cod-doc MCP questions
How does cod-doc prevent documentation from drifting from the code?
It uses hash-verified documentation where every markdown file carries a content hash of the database state it was projected from, allowing the system to detect edits made outside the tool.
Does this require an external database or complex infrastructure?
No, it requires zero infrastructure and uses the SQLite that ships with Python, storing everything in a single project database file.
Can LLM agents use this server?
Yes, it includes a dedicated MCP profile designed for LLM agents to act as documentation curators.
Where is the data stored?
The project database is stored as a single file in the <project>/.cod-doc/state.db directory.