npm package: @mrzadexinho/docguard
Description: API documentation drift detector MCP server — find where your docs lie before your users do
Author: Idris Idriszade
Latest version: 0.1.0

# docguard

[![npm version](https://img.shields.io/npm/v/@mrzadexinho/docguard.svg)](https://www.npmjs.com/package/@mrzadexinho/docguard)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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.

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

### As Library

```typescript
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

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

## License

MIT