Skip to main content
Glama

Docs Auditor MCP

License: MIT TypeScript MCP Tests

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:fixture

Exit 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_TOKEN for higher GitHub API rate limits

1. Install

git clone https://github.com/saikattanti/docs-auditor-mcp.git
cd docs-auditor-mcp
npm install

2. 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 high

3. CLI — audit a local path

npx tsx src/cli.ts --path /path/to/your/repo --format json --out audit.json

4. 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 markdown

5. 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_audit on a local path or GitHub repo

  • Prompt: audit-quickstart for a DevRel-ready prioritized fix report

  • Prompt: fix-drift for a dry-run-first patch workflow

  • Resource: audit://report/latest for the last structured JSON + markdown report

  • Tool: apply_doc_patches with dryRun: true (default), then false to 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

fetch_repo_structure

Local tree or GitHub git tree

Tool

read_docs

README + docs

Tool

cross_check_snippets

Paths, imports, exports, arity, npm scripts

Tool

analyze_open_issues

Open docs/readme/quickstart issues

Tool

generate_fix_patch

Before/after doc patches

Tool

run_full_audit

Full pipeline → markdown/JSON + updates latest resource

Tool

apply_doc_patches

Unified diff; dryRun default true

Prompt

audit-quickstart

DevRel-ready prioritized fix report

Prompt

fix-drift

Safe dry-run-first patch guidance

Resource

audit://report/latest

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

--format json|markdown

Report format (--json alias)

--fail-on critical|high|medium|low|none

Exit 2 when findings at that severity or worse exist

--path / --github

Local path, GitHub URL, or owner/repo


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.yml

Scripts

Command

Purpose

npm run audit:fixture

Demo audit on intentional drift

npm run audit -- --path <dir>

Audit any local checkout

npm run mcp

Start MCP server on stdio

npm test

Unit + fixture + MCP registration tests

npm run build

Emit dist/


Contributing

See CONTRIBUTING.md. Please follow the Code of Conduct. Security reports: SECURITY.md.


License

MIT © 2026 Saikat Tanti

Available Tools

7 tools
analyze_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

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 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.
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      8
      17 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Checks 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 npm
      MIT