Docs Auditor MCP
Provides tools and CLI capabilities to audit GitHub repositories via the GitHub API, including fetching repository structure and documentation, and analyzing open documentation-related GitHub issues.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Docs Auditor MCP audit the README in ./my-app and list broken quickstart commands"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Docs Auditor MCP
Production-grade Docs & Quickstart Auditor — an MCP server + CI-friendly CLI that catches documentation drift before developers do.
Broken quickstart commands, invented file paths, missing exports, env-var gaps, arity mismatches, and open GitHub docs issues — surfaced as structured findings, unified diffs, and optional safe patch application.
npm install
npm test
npm run audit:fixtureExit code 2 when --fail-on thresholds are hit (default: high). Exit code 0 means clean for that threshold.
The problem
Developer products lose adopters when the README lies.
A quickstart that says npm run start:dev after the script was renamed to dev is not a content problem — it is a docs/code consistency problem. The same goes for renamed exports, undocumented process.env keys, and prose links to docs that were never written.
This project turns that check into MCP tools, prompts, and resources an agent can call — no LLM inside the auditor itself.
Related MCP server: FullStack Audit MCP
Architecture
Seven-step multi-tool flow (plus patch apply):
flowchart LR
subgraph Client["Cursor / Claude Desktop / CLI / CI"]
A[Agent or CLI]
end
subgraph MCP["docs-auditor-mcp"]
T1[fetch_repo_structure]
T2[read_docs]
T3[cross_check_snippets]
T4[analyze_open_issues]
T5[generate_fix_patch]
T6[run_full_audit]
T7[apply_doc_patches]
P1[prompt: audit-quickstart]
P2[prompt: fix-drift]
R1[resource: audit://report/latest]
end
subgraph Sources["Sources"]
L[Local checkout]
G[GitHub API]
end
A --> T6
A --> P1
A --> P2
T6 --> T1 --> T2 --> T3 --> T4 --> T5
T6 --> R1
T7 --> L
T1 --> L
T1 --> G
T2 --> L
T2 --> G
T5 --> Diff[Unified diffs + patches]Deterministic checks: repo tree, package.json scripts, export/import parsing, call arity, env-var drift vs README/.env.example, GitHub docs issues.
Quickstart
Prerequisites
Node.js 20+
Optional:
GITHUB_TOKENfor higher GitHub API rate limits
1. Install
git clone https://github.com/saikattanti/docs-auditor-mcp.git
cd docs-auditor-mcp
npm install2. CLI — audit the bundled fixture
npm run audit:fixture
# or with CI flags:
npx tsx src/cli.ts --path fixtures/drifted-sdk --format markdown --fail-on high3. CLI — audit a local path
npx tsx src/cli.ts --path /path/to/your/repo --format json --out audit.json4. CLI — audit a public GitHub repo (API, no clone)
npx tsx src/cli.ts --github expressjs/express --format json --fail-on critical
# GitHub URLs also work:
npx tsx src/cli.ts --path https://github.com/expressjs/express --format markdown5. Cursor MCP setup
{
"mcpServers": {
"docs-auditor": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/docs-auditor-mcp/src/index.ts"],
"env": {
"GITHUB_TOKEN": ""
}
}
}
}Then try:
Tool:
run_full_auditon a local path or GitHub repoPrompt:
audit-quickstartfor a DevRel-ready prioritized fix reportPrompt:
fix-driftfor a dry-run-first patch workflowResource:
audit://report/latestfor the last structured JSON + markdown reportTool:
apply_doc_patcheswithdryRun: true(default), thenfalseto write
stdio mode never uses console.log (logs go to console.error only).
Real execution traces
Fixture (intentional drift)
Running docs audit…
[ 7ms] 1. Fetch repo structure — 5 files (local)
[ 1ms] 2. Read documentation — 1 doc file(s), 893 bytes
[ 8ms] 3. Cross-check snippets vs code — 4 snippet(s), 5 finding(s)
[ 1ms] 4. Check prose path references — 1 prose finding(s)
[ 9ms] 5. Check environment variable drift — 1 env finding(s)
[ 0ms] 6. Analyze open docs-related issues — Skipped (local path; pass --github to enable)
[ 0ms] 7. Generate fix patches — 3 proposed patch(es)
Done in 28ms · 7 finding(s) (1 critical)Catches: broken start:dev script, invented createUser import → suggests createClient, missing docs/auth.md, undocumented ACME_REGION.
Full sample: examples/fixture-audit-report.md.
Real repo — expressjs/express (GitHub API)
npx tsx src/cli.ts --github expressjs/express --format json --fail-on critical [1795ms] 1. Fetch repo structure — 216 files (github)
[ 688ms] 2. Read documentation — 2 doc file(s)
[ 348ms] 3. Cross-check snippets vs code — 11 snippet(s), 1 finding(s)
[ 1ms] 5. Check environment variable drift — 0 env finding(s)
[ 613ms] 6. Analyze open docs-related issues — 10 open docs-related issue(s)
Done in ~3.4s · 11 finding(s) (1 critical)Notable finding: README documents npm start, but package.json has no start script (critical). Plus 10 open docs-related GitHub issues surfaced for triage.
Saved sample: examples/express-audit.json.
MCP primitives
Kind | Name | Purpose |
Tool |
| Local tree or GitHub git tree |
Tool |
| README + docs |
Tool |
| Paths, imports, exports, arity, npm scripts |
Tool |
| Open docs/readme/quickstart issues |
Tool |
| Before/after doc patches |
Tool |
| Full pipeline → markdown/JSON + updates latest resource |
Tool |
| Unified diff; |
Prompt |
| DevRel-ready prioritized fix report |
Prompt |
| Safe dry-run-first patch guidance |
Resource |
| Latest structured report |
CI mode (GitHub Actions)
name: Docs audit
on: [pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
cache: npm
- run: npm ci
- run: npm test
- name: Fail on high/critical docs drift
run: npx tsx src/cli.ts --path . --format json --fail-on high
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Also see .github/workflows/docs-audit.yml.
CLI flags:
Flag | Meaning |
| Report format ( |
| Exit |
| Local path, GitHub URL, or |
Project structure
docs-auditor-mcp/
├── src/
│ ├── index.ts # stdio MCP entry (console.error only)
│ ├── server.ts # tools + prompts + resources
│ ├── cli.ts # CI-friendly CLI
│ └── lib/
│ ├── audit.ts # Orchestrator
│ ├── cross-check.ts # Snippet / export / arity checks
│ ├── env-drift.ts # process.env vs README/.env.example
│ ├── signatures.ts # Lightweight export/call parsers
│ ├── patch.ts # Unified diff + apply
│ ├── report-store.ts # audit://report/latest backing store
│ ├── github.ts / fs-repo.ts
│ └── ...
├── fixtures/drifted-sdk/ # Intentional drift fixture
├── examples/
│ ├── fixture-audit-report.md
│ ├── express-audit.json
│ └── cursor-mcp.config.json
└── .github/workflows/docs-audit.ymlScripts
Command | Purpose |
| Demo audit on intentional drift |
| Audit any local checkout |
| Start MCP server on stdio |
| Unit + fixture + MCP registration tests |
| Emit |
Contributing
See CONTRIBUTING.md. Please follow the Code of Conduct. Security reports: SECURITY.md.
License
MIT © 2026 Saikat Tanti
Available Tools
7 toolsanalyze_open_issuesAnalyze open docs issuesB
Search open GitHub issues related to docs, README, or quickstart gaps.
Inputs: github (required).
apply_doc_patchesApply doc patchesA
Apply proposed documentation patches to a local checkout. Defaults to dryRun=true and returns unified diffs. Set dryRun=false to write files.
Inputs: path (required), dryRun, runAuditFirst.
cross_check_snippetsCross-check snippetsB
Extract fenced code blocks from docs and verify referenced files, imports, exports, call arity, and npm scripts against the repo.
Inputs: path, github.
fetch_repo_structureFetch repo structureA
List files in a local directory or GitHub repository. Use this first before reading docs.
Inputs: path, github, maxFiles.
generate_fix_patchGenerate fix patchesB
Propose concrete before/after doc patches for findings from a docs audit.
Inputs: path, github.
read_docsRead documentationA
Read README and docs/* from a local path or GitHub repo. Call after fetch_repo_structure.
Inputs: path, github.
run_full_auditRun full docs auditA
Run the full multi-step docs audit pipeline: structure → docs → cross-check → env drift → issues → fix patches. Returns markdown report + structured JSON. Also updates audit://report/latest.
Inputs: path, format, github.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: inspecting structure, reading docs, cross-checking snippets, analyzing issues, generating patches, and applying patches. The main overlap is run_full_audit, which duplicates the individual pipeline steps and also returns fix patches, but its description makes the orchestration role clear enough to avoid serious misselection.
All tool names use snake_case and follow a predictable verb-first pattern: fetch_*, read_*, cross_check_*, analyze_*, generate_*, run_*, apply_*. The convention is consistent throughout the set.
Seven tools is well-scoped for a docs auditing server, with each tool covering a meaningful step in the audit workflow. The full-audit convenience tool is justified alongside the granular tools rather than feeling like padding.
The surface covers the core docs audit lifecycle: inspect repo structure, read docs, verify snippets, search issues, generate patches, and apply them. Minor gaps remain, such as no standalone env-drift tool despite run_full_audit mentioning it, and patch application limited to local checkouts rather than remote PR creation.
Maintenance
Related MCP Connectors
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
Generate and review codebase docs. 77 tools; scoped, credit-approved repository reviews.
Audit and repair any public GitHub repo. Free survey; paid source, unified diffs and a pull request.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceExposes tools that scan a repository's manifests, CI workflows and layout to generate truthful AGENTS.md/CLAUDE.md agent instructions, then audit those docs for drift such as dead commands, undocumented scripts and CI mismatches. Enables agents to keep their own onboarding documentation accurate and CI-verifiable instead of hand-written and rotting.1MIT
- AlicenseBqualityCmaintenanceEnables AI coding agents to perform evidence-based, read-only audits of supported software projects by exposing bounded project inventory and static-analysis findings for discovery, code review, integration tracing, security, and tests. Reports are returned as Markdown or JSON directly in the tool response, with no code executed or files written.817 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to check their own instruction files for drift before a run, returning findings with file and line for stale counts, missing files, broken links, and missing commands. Also lets agents list which agent docs get inspected.14 npmMIT
- AlicenseNot gradedqualityBmaintenanceChecks AGENTS.md and CLAUDE.md against a repository's actual file tree and package.json, reporting missing referenced paths and scripts so agent instructions stay accurate. Returns deterministic findings with file, line, and exact source text through a single tool.60 npmMIT