Validates documentation against code implementation to detect drift and provides structured repair tasks for AI agents.
Also known as raccioly/docguard, docguard-cli
- Stars
- 34
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- 0.48.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is DocGuard MCP?
DocGuard validates documentation against code implementation to detect drift and provides structured repair tasks for AI agents. It exposes 12 tools, such as docguard_guard, docguard_score, docguard_explain.
Summary generated from the project's README
About DocGuard MCP server
DocGuard serves as an enforcement layer for Spec-Driven Development, helping developers maintain alignment between their documentation and actual code implementation. It is designed for teams practicing Canonical-Driven Development, where documentation acts as the primary source of truth. The tool identifies documentation drift and provides structured repair tasks that AI agents can execute to resolve discrepancies.
Users can run DocGuard locally via the docguard-cli using npm or pip, or deploy it as a read-only MCP server using a Docker container. When used as an MCP server, the project directory is mounted to a workspace, allowing clients like Claude or Cursor to inspect documentation through tools such as guard, score, and diagnose. The system distinguishes between mechanical fixes, which can be applied automatically without AI, and agent-based fixes that require human-like judgment for prose and architectural updates.
What you can do with it
- 1Detect documentation driftAn AI agent can run a diagnostic command to find where the current code implementation has diverged from the written specifications.
- 2Automate mechanical documentation repairsDevelopers can use the tool to automatically delete outdated documentation blocks that no longer match the codebase.
- 3Measure documentation maturityA developer can evaluate the structural quality of their project documentation using a weighted scoring system.
Written from the project's README. Every use case is checked against a quote from it.
How to install DocGuard MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall DocGuard MCP in Claude Code
$ claude mcp add docguard -- npx -y docguard-cli mcpInstall DocGuard MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"docguard": {
"command": "npx",
"args": [
"-y",
"docguard-cli",
"mcp"
]
}
}
}Install DocGuard MCP in VS Code
.vscode/mcp.json
{
"servers": {
"docguard": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"docguard-cli",
"mcp"
]
}
}
}Install DocGuard MCP in VS Code CLI
$ code --add-mcp '{"name":"docguard","type":"stdio","command":"npx","args":["-y","docguard-cli","mcp"]}'Install DocGuard MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"docguard": {
"command": "npx",
"args": [
"-y",
"docguard-cli",
"mcp"
]
}
}
}Install DocGuard MCP in Codex
$ codex mcp add docguard -- npx -y docguard-cli mcpInstall DocGuard MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.docguard] command = "npx" args = ["-y", "docguard-cli", "mcp"]
Install DocGuard MCP in Gemini CLI
$ gemini mcp add -s user docguard npx -- -y docguard-cli mcpInstall DocGuard MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"docguard": {
"command": "npx",
"args": [
"-y",
"docguard-cli",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for docguard-cli 0.48.0 in an isolated container with no network and no keys. It answered and listed 12 tools.
DocGuard MCP tools 12
Read from the server with tools/listdocguard_guardRead-onlyRun every enabled DocGuard validator against the project's canonical docs. Returns status (PASS/WARN/FAIL), every finding once with its stable code and suggestion, each code's evidence once, nextStep, doc coverage, semantic-claim count, and per-validator status and counts. Pass detail "full" for the complete guard JSON contract (per-validator finding copies, the reportable subset, raw benchmark statistics per code).
docguard_scoreRead-onlyCompute the project's CDD maturity score (0-100) with letter grade and per-category breakdown.
docguard_explainRead-onlyExplain a stable DocGuard finding code (e.g. STR001, ENV003): what it means, which validator emits it, and the inline suppression to use if it's a confirmed false positive.
docguard_verify_evidenceRead-onlyEvaluate `.docguard-evidence.json` against bounded local sources. Returns explicit verified-within-scope, contradicted, stale, inconclusive, and unsupported states; verification applies only to each selected statement.
docguard_verify_claimsRead-onlyExtract the semantic claims in the project's canonical docs — documented numbers, limits, and enums — as a verification task list. Deterministic discovery, LLM judgment — the caller verifies each claim against the code.
docguard_reportRead-onlyGenerate the commit-stamped compliance-evidence bundle: guard verdict per validator, findings grouped by stable code, CDD score, ALCOA+ data-integrity attributes, fix history, and a tamper-evident sha256 integrity hash. Evidence, not a gate — it reports state without failing.
docguard_docs_for_pathRead-onlyExact answer to "which documentation describes this file?": canonical doc lines that name it (with heading, anchor and section), AGENTS.md/CLAUDE.md/GEMINI.md lines, the @implements/@req IDs it declares, its @doc annotations, doc sections whose covers= includes it with their review state, the referencing docs that are not active (superseded, retired) under docs.lifecycle, and, when a guard run for this exact tree state is cached, the open finding codes of each doc under docs.openFindings. Deterministic, bounded, no model.
docguard_doc_structureRead-onlyA document's headings (level, text, anchor, line range, bytes), docguard:section markers (id, source, pinned, covers), fact markers, marker issues, last-reviewed date and size — so an agent can read one section instead of the whole file.
docguard_read_sectionRead-onlyReturn one section's text, resolved by docguard:section id, then heading anchor, then exact heading text — or, with `line`, just the lines around one reference from docguard_docs_for_path (the cheapest read for a table row). Bounded: 8192 bytes by default, 32768 at most; a truncated result carries nextOffset. An ambiguous match fails with the candidates.
docguard_task_contextRead-onlyThe same deterministic packet as `docguard agent --task <text> --format json`: current task-linked requirements, pointers to implementing code and tests, excerpts, and verification steps; abstains when relevance is weak.
docguard_anchorsRead-onlyThe same listing as `docguard anchors --format json`: each @implements/@req tag, the requirement it resolves to, and the file, symbol, statement or route it anchors to with the tier that resolved it, plus problems. Read-only; bounded to 200 links.
docguard_diagnoseRead-onlyRun guard and return only what needs fixing: failing/warning validators with their messages, structured findings, and suggested next actions — shaped for an agent to act on.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub🛡️ DocGuard
English · Português (BR) · Español
The enforcement layer for Spec-Driven Development. Validate. Score. Enforce. Ship documentation that AI agents can actually use.
✨ See what DocGuard catches in 30 seconds — no install, no setup:
npx docguard-cli demoRuns against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.

📚 Documentation: Installation · Existing projects · Spec Kit · CI · Languages and frameworks · Coding agents · Finding codes · Troubleshooting
Table of Contents
- What is DocGuard?
- Why DocGuard?
- Quick Start
- Spec Kit Integration
- Usage
- Validators
- Reading a finding
- Templates
- AI Agent Support
- Slash Commands
- Examples
- Testing
- Enterprise Adoption
- CI/CD Integration
- What's New
- File Structure
- Configuration
- Research Credits
What is DocGuard?
DocGuard enforces Canonical-Driven Development (CDD) — a methodology where documentation is the source of truth, not an afterthought. AI writes the docs, DocGuard validates them.
| Traditional Development | Canonical-Driven Development |
|---|---|
| Code first, docs maybe | Docs first, code conforms |
| Docs rot silently | Drift is tracked and enforced |
| Docs are optional | Docs are required and validated |
| One AI agent, one context | Any agent, shared context via canonical docs |
DocGuard is an official GitHub Spec Kit community extension. It validates the artifacts that Spec Kit creates, ensuring your specs stay high-quality throughout the development lifecycle.
🧭 How it works (10-page brief) (PDF) · 📖 Philosophy · 📋 CDD Standard · ⚖️ Comparisons · 🔬 Validation · 🗺️ Roadmap
Architecture
graph TD
CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (28)"]
Commands --> guard["guard"]
Commands --> generate["generate"]
Commands --> score["score"]
Commands --> diagnose["diagnose"]
Commands --> setup["setup wizard"]
Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs · ignore<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
guard --> Validators["Validators (36)"]
generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
score --> Scoring["Weighted Scoring<br/>8 categories"]
diagnose --> Validators
diagnose --> AIPrompts["AI-Ready<br/>Fix Prompts"]
Validators --> Output["Output"]
Scanners --> Output
Scoring --> Output
Output --> Terminal["Terminal"]
Output --> JSON["JSON"]
Output --> Badge["Badge"]
style CLI fill:#2d5016,color:#fff
style Validators fill:#1a3a5c,color:#fff
style Scanners fill:#1a3a5c,color:#fff
style Output fill:#5c3a1a,color:#fff
Distribution: Node.js core (npm) · Python wrapper (PyPI) · GitHub Action (
action.yml) · Spec Kit Extension (ZIP)
Why DocGuard?
DocGuard checks declared documentation facts against repository evidence and gives agents structured repair tasks. Deterministic checks cover supported facts, references, and generated sections. Human-authored requirements and architectural decisions retain their authority when implementation diverges.
A guard result describes the checks performed. The CDD grade measures structural maturity. Exact declarations in .docguard-evidence.json can verify selected statements against current local evidence; every other statement remains unverified. Coverage and unresolved claims remain visible, so teams can choose an appropriate enforcement policy.
Research motivates evaluation of this approach. A 2026 study found that repository context files did not generally improve task success and increased inference cost in its evaluated settings. It also found agents generally followed the instructions. These results support testing concise, relevant context and measuring actual task outcomes; they do not establish DocGuard's effectiveness. Evaluating AGENTS.md, revised June 2026.
The current roadmap prioritizes accurate detection, reproducible evidence, document lifecycle management, and contributor-supplied regression cases. Released plans and superseded specifications are removed from active AI context and remain recoverable from Git.
⚡ Quick Start
Package naming: this repo is
raccioly/docguard; the published package isdocguard-clion both npm and PyPI; the installed command isdocguard. Same project — the-clisuffix is just the registry name. The package runs no install scripts, sonpm i -g docguard-cli --ignore-scriptsis equivalent.
Node.js (npm)
# No install needed — run directly
npx docguard-cli diagnose
# Or install globally
npm i -g docguard-cli
docguard diagnose
Python (PyPI)
pip install docguard-cli
docguard diagnose
Note: The Python package is a thin wrapper that delegates to
npx. Node.js 18+ is required on the system.
Docker (MCP server)
The MCP server ships as a container image on GHCR — no Node.js install required. Public image, so no authentication is needed to pull it:
# Run the MCP server against the current directory
docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:latest
The entrypoint is the stdio MCP transport: stdout is the JSON-RPC channel, so keep every other output off it. Mount the project you want inspected at /workspace; tools inspect it by default, and a projectDir in a tool call must be /workspace or a directory inside it (add --root <dir> after the image name to serve another mounted tree).
Pin a version rather than tracking latest in CI:
docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:0.34.9
The server is read-only: it only reads the mounted project.
More ways to integrate
- pre-commit — changed-only guard on every commit:
repos: - repo: https://github.com/raccioly/docguard rev: v0.47.0 hooks: [{ id: docguard-guard }] # docguard-guard-full for pre-push - MCP (Claude, Cursor, any MCP client) —
claude mcp add docguard -- npx -y docguard-cli mcp; read-only tools to check docs (guard, score, diagnose, …) and to navigate them one bounded section at a time — the full list is in docs/ai-integration.md. Registry manifest ships in-repo (server.json, Smithery-ready). - GitLab CI — component staged at
templates/ci/gitlab-component.yml(guard/score/ci job with a SARIF artifact). - Homebrew —
brew install raccioly/tap/docguard. The release workflow renders the formula template inpackaging/homebrew/from the published npm tarball and pushes it to the tap.
Core Workflow
# 1. Initialize docs for your project
npx docguard-cli init
# 2. Or reverse-engineer docs from existing code
npx docguard-cli generate
# 3. AI diagnoses issues and generates fix prompts
npx docguard-cli diagnose
# 4. Validate — use as CI gate
npx docguard-cli guard
# 5. Check maturity score
npx docguard-cli score
The AI Loop
diagnose → AI reads prompts → AI fixes docs → guard verifies
↑ ↓
└───────────────── issues found? ←──────────────────────┘
diagnose is the primary command. It runs all validators, maps every failure to an AI-actionable fix prompt, and outputs a remediation plan. Your AI agent runs it, fixes the docs, and runs guard to verify.
Mechanical vs. agent fixes
DocGuard splits drift into two kinds and is explicit about which is which:
| Kind | Example | How it's fixed |
|---|---|---|
| Mechanical (deterministic) | An endpoint documented in API-REFERENCE.md that the OpenAPI spec confirms is gone |
docguard fix --write deletes the row + detail block itself — no AI |
| Agent (needs judgment) | Rewriting an X-Ray prose section as CloudWatch; writing a new endpoint's request/response | Routed to an AI agent via diagnose / fix --doc prompts |
docguard fix --write only touches docs marked <!-- docguard:generated true --> (override with --force), is idempotent, and prints exactly what changed. Prose stays with the agent.
Continuous documentation workflow
guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)
- CI / pre-commit:
docguard hooks --type pre-commit --auto-fixinstalls a hook that applies mechanical fixes, re-stages the docs, then runsguard; anything left is surfaced as agent prompts. - Agent-driven:
docguard diagnose --autoscaffolds missing docs and applies mechanical fixes, then emits prompts for the content rewrites that remain. - JSON for automation:
guard/diagnose --format jsoninclude amechanicalFixesarray and tag each issuemechanicalvsagent, so an agent can apply or delegate precisely.
☁️ AWS AI-DLC Integration
DocGuard reads AWS AI-DLC workspaces on its own: traceability targets that no longer exist, gaps left in completed stages, deliverables removed after a unit, and agent memory that names what is gone (AID001–AID004, MEM001–MEM002). It also ships as an AI-DLC plugin, whose docguard-guard sensor fails a construction gate when the stage introduced drift. See the AI-DLC guide.
🌱 Spec Kit Integration
DocGuard is a community extension for GitHub's Spec Kit framework. While Spec Kit focuses on creating specifications (via AI slash commands like /speckit.specify and /speckit.plan), DocGuard focuses on validating their quality.
How They Work Together
┌─────────────────┐ ┌──────────────────┐
│ Spec Kit │ │ DocGuard │
│ │ │ │
│ /speckit.specify│ ──────→ │ docguard guard │
│ Creates specs │ │ Validates specs │
│ (AI-driven) │ │ (automated) │
└─────────────────┘ └──────────────────┘
| Phase | Tool | What happens |
|---|---|---|
| 1. Initialize | specify init |
Creates .specify/ directory and templates |
| 2. Write specs | /speckit.specify |
AI creates spec.md with FR-IDs, user stories |
| 3. Validate | docguard guard |
Checks spec quality (mandatory sections, FR/SC IDs) |
| 4. Plan | /speckit.plan |
AI creates plan.md with technical context |
| 5. Validate | docguard guard |
Checks plan quality (sections, structure) |
| 6. Tasks | /speckit.tasks |
AI creates tasks.md with phased breakdown |
| 7. Validate | docguard guard |
Checks task quality (phases, T-IDs) |
| 8. Implement | /speckit.implement |
AI writes code |
| 9. Enforce | docguard guard |
Final quality gate — CI/CD |
What DocGuard Validates in Spec Kit Projects
- spec.md — Mandatory sections (User Scenarios, Requirements, Success Criteria), FR-xxx IDs, SC-xxx IDs
- plan.md — Summary, Technical Context, Project Structure sections
- tasks.md — Phased task breakdown (Phase 1, 2, 3+), T-xxx task IDs
- constitution.md — Detected at
.specify/memory/constitution.mdor project root - Requirement traceability — FR, SC, NFR, US, AC, UC, SYS, ARCH, MOD, T IDs
Installing as a Spec Kit Extension
docguard init does this for you: when the specify CLI (Spec Kit ≥ 0.11.2, the floor the
extension declares) is on your PATH, it initializes Spec Kit for the coding agent the repository
already uses, then registers the DocGuard extension shipped inside the installed package. Nothing
is downloaded for the registration. If a project's registered extension is from another DocGuard
release, init re-registers it when the versions differ (keeping its priority), and
docguard upgrade --apply does the same. init says the workflow hooks are active only after each mandatory hook
(speckit.docguard.brief before specify, speckit.docguard.preflight before tasks,
speckit.docguard.guard after implement) resolves to a command file your agent can run; otherwise
it names the missing one. Spec Kit registers no extension commands for its generic integration,
so for generic DocGuard writes them next to Spec Kit's own commands (.agent/commands/ by
default). Every failure is printed with Spec Kit's own error and the command to run by hand. Only
init and upgrade --apply touch Spec Kit; other commands print a one-line hint at most.
DocGuard's own skills go where your agent reads them: .claude/skills/ for Claude Code (or the
skills directory of another skills-based integration), .agent/ for the generic integration or
an agent DocGuard cannot place. A commands-only integration such as Gemini gets Spec Kit's
speckit.docguard.* commands and no extra copies. The command and skill files run docguard from
your PATH when it is installed, and otherwise npx --yes docguard-cli@<version>, pinned to the
release they shipped with; they never fetch @latest.
Suggestions DocGuard prints (Next: …, Fix: …) name a slash command only when its file exists
for your agent, in its form (/speckit-docguard-guard in Claude Code, /speckit.docguard.guard
for generic); otherwise they print the CLI command.
docguard init registers the copy of the extension inside the installed package. To register
it yourself, use a release ZIP or a local checkout. A bare specify extension add docguard does
not work on a default Spec Kit setup: DocGuard is in Spec Kit's community catalog, which Spec Kit
uses for discovery only.
specify extension add docguard --from https://github.com/raccioly/docguard/releases/download/vX.Y.Z/spec-kit-docguard-vX.Y.Z.zip
specify extension add ./node_modules/docguard-cli/extensions/spec-kit-docguard --dev
See the Spec Kit guide for the hooks, the spec lifecycle registry and an end-to-end flow.
This registers the speckit.docguard.* commands listed in
extension.yml (invoked as
/speckit-docguard-guard and so on in skills-based agents such as Claude Code) and the
workflow hooks that run them.
DocGuard MCP questions
How do I add DocGuard MCP to Claude Code?
Run claude mcp add docguard -- npx -y docguard-cli mcp in your terminal. Add --scope user to make it available in every project.
How do I add DocGuard MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does DocGuard MCP provide?
It exposes 12 tools, including docguard_guard, docguard_score, docguard_explain, docguard_verify_evidence, docguard_verify_claims.
How can I run the DocGuard MCP server using Docker?
You can run it using the command: docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:latest. You must mount your project directory to /workspace.