docguard

API documentation drift detector MCP server. Find where your docs lie — before your users do.

Problem

API docs drift from code constantly. A developer adds a route, forgets to update the OpenAPI spec. Another removes an endpoint but the docs still list it. Parameters change, status codes change — the spec becomes fiction.

docguard compares your OpenAPI spec against actual code routes and reports exactly what's out of sync. No live traffic needed, no LLM calls — pure static analysis.

Quick Start

As MCP Server

Works with any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Continue.dev, Zed, Cline, and more.

{
  "mcpServers": {
    "docguard": {
      "command": "npx",
      "args": ["-y", "@mrzadexinho/docguard"]
    }
  }
}

As Library

import { parseSpec, extractRoutes, compareDrift, formatDriftReport } from '@mrzadexinho/docguard';
import { readFileSync } from 'fs';

// Parse your OpenAPI spec
const spec = parseSpec(readFileSync('openapi.yaml', 'utf-8'));

// Extract routes from code
const code = extractRoutes(readFileSync('src/routes.ts', 'utf-8'), 'src/routes.ts');

// Compare and report drift
const drift = compareDrift(spec.routes, code.routes);
console.log(formatDriftReport(drift));

MCP Tools

| Tool | Description | |------|-------------| | check_drift | Compare OpenAPI spec against code routes. Reports undocumented routes, stale docs, and parameter mismatches | | extract_routes | Scan a code file and extract API routes with methods, paths, and parameters | | validate_spec | Validate OpenAPI spec for structure and completeness (missing operationIds, summaries, responses) |

What It Detects

| Drift Type | Severity | Description | |-----------|----------|-------------| | Undocumented route | Error | Route exists in code but path is completely missing from spec | | Undocumented method | Warning | Path exists in spec but this HTTP method isn't documented | | Stale documentation | Error | Endpoint in spec but no matching route in code | | Stale method | Warning | Path exists in code but this HTTP method was removed | | Parameter mismatch | Warning | Path params differ between spec and code |

Framework Support

Auto-detects and extracts routes from:

| Framework | Patterns detected | |-----------|-------------------| | Express | app.get(), router.post(), app.use('/prefix', router) | | FastAPI | @app.get(), @router.post(), APIRouter(prefix=...) | | Hono | app.get(), app.post(), .basePath() |

Spec Support

• OpenAPI 3.x (YAML and JSON)
• Swagger 2.0 (JSON)
• Path parameter extraction ({id} normalized to :id)
• Base path from servers[0].url or basePath

Example Output

# API Documentation Drift Report

**8 spec routes, 10 code routes, 4 drift issue(s):**
- 2 route(s) in code but missing from spec
- 1 route(s) in spec but missing from code (stale docs)
- 1 parameter mismatch(es)

## Undocumented Routes (in code, not in spec)

[ERROR] GET /health exists in code but is completely missing from spec
  Code: src/routes.ts:12

[ERROR] POST /webhooks exists in code but is completely missing from spec
  Code: src/routes.ts:45

## Stale Documentation (in spec, not in code)

[ERROR] DELETE /users/:id documented in spec but not found in code (stale docs)
  Spec: operationId: deleteUser

## Parameter Mismatches

[WARNING] Path parameter mismatch on GET /users/:id
  Spec params: id
  Code params: userId

Architecture

docguard/
  src/
    spec/            # OpenAPI spec parsing
      types          # SpecRoute, SpecParam, SpecResponse
      parser         # Parse OpenAPI 3.x / Swagger 2.0
    routes/          # Code route extraction
      types          # CodeRoute, FrameworkType
      express        # Express route extractor
      fastapi        # FastAPI route extractor
      hono           # Hono route extractor
      detector       # Auto-detect framework, multi-file extraction
    drift/           # Drift detection engine
      types          # DriftFinding, DriftType, DriftSeverity
      comparator     # Compare spec vs code routes
      reporter       # Format drift report (markdown)
    mcp/             # MCP server layer
      tools/         # 3 MCP tools
  tests/             # 77 tests mirroring src/ structure

Prerequisites

• Node.js >= 20.0.0
• An OpenAPI spec file (YAML or JSON)

Development

git clone https://github.com/mrzadexinho/docguard.git
cd docguard
npm install
npm run build
npm test

License

MIT