╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║   ██████╗  █████╗  ██████╗██╗  ██╗███████╗███╗   ██╗██████╗ ║
║   ██╔══██╗██╔══██╗██╔════╝██║ ██╔╝██╔════╝████╗  ██║██╔══██╗║
║   ██████╔╝███████║██║     █████╔╝ █████╗  ██╔██╗ ██║██║  ██║║
║   ██╔══██╗██╔══██║██║     ██╔═██╗ ██╔══╝  ██║╚██╗██║██║  ██║║
║   ██████╔╝██║  ██║╚██████╗██║  ██╗███████╗██║ ╚████║██████╔╝║
║   ╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝╚═════╝║
║                                                              ║
║           ███╗   ███╗ █████╗ ██╗  ██╗                        ║
║           ████╗ ████║██╔══██╗╚██╗██╔╝                        ║
║           ██╔████╔██║███████║ ╚███╔╝                         ║
║           ██║╚██╔╝██║██╔══██║ ██╔██╗                         ║
║           ██║ ╚═╝ ██║██║  ██║██╔╝ ██╗                        ║
║           ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝                        ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

🩺 AI-Powered Backend Diagnostics for Claude Code

The backend bugs your linter can't see. The contract drift your tests don't cover. Caught before deploy.

Quick Start · Features · Tools · Roadmap

</div>

🤔 What Is This?

Backend Max is a Model Context Protocol (MCP) server that gives Claude deep diagnostic vision into your backend. It statically analyzes your codebase — both frontend and backend — to surface bugs, contract drift, missing validation, security gaps, and performance anti-patterns that no other single tool catches.

Think of it as a senior backend engineer that reviews every route, checks every contract, and never goes on vacation.

🔭 How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   📂 Your Codebase          🩺 Backend Max           📋 Report     │
│                                                                     │
│   ┌───────────┐             ┌──────────────┐        ┌───────────┐  │
│   │ Frontend   │────────▶   │  Cross-       │        │ Health    │  │
│   │ API Calls  │            │  Boundary     │──────▶ │ Score     │  │
│   └───────────┘             │  Analysis     │        ├───────────┤  │
│                             │              │        │ Issues    │  │
│   ┌───────────┐             │  ┌──────────┐ │        ├───────────┤  │
│   │ Backend   │────────▶   │  │ 6 Audit  │ │──────▶ │ API Docs  │  │
│   │ Routes    │            │  │ Engines  │ │        ├───────────┤  │
│   └───────────┘             │  └──────────┘ │        │ Fixes     │  │
│                             │              │        │ Guide     │  │
│   ┌───────────┐             │  ┌──────────┐ │        └───────────┘  │
│   │ Config    │────────▶   │  │ Intent   │ │                       │
│   │ & Env     │            │  │ Engine   │ │                       │
│   └───────────┘             │  └──────────┘ │                       │
│                             └──────────────┘                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

⚡ Why Backend Max?

Existing tools catch syntax errors and type mismatches. Backend Max catches the bugs that ship to production.

| Bug Category | TypeScript | ESLint | Jest/Vitest | Backend Max | |:---|:---:|:---:|:---:|:---:| | Frontend calls /api/user but backend exposes /api/users | ❌ | ❌ | ❌ | ✅ | | Frontend sends { name } but backend expects { username } | ❌ | ❌ | ❌ | ✅ | | Route handler missing try/catch | ❌ | ❌ | ❌ | ✅ | | Zod schema missing on POST route | ❌ | ❌ | ❌ | ✅ | | process.env.SECRET used but not in .env | ❌ | ❌ | ❌ | ✅ | | Auth middleware missing on sensitive route | ❌ | ❌ | ❌ | ✅ | | N+1 query in a loop | ❌ | ❌ | ❌ | ✅ | | API docs out of date | ❌ | ❌ | ❌ | ✅ |

💡 Backend Max doesn't replace your existing tools. It catches what they architecturally cannot — cross-boundary issues that require understanding both sides of the stack.

🚀 Quick Start

Install with your MCP client

<details> <summary>Claude Code (recommended)</summary>

claude mcp add backend-max -- npx -y backend-max

Done. Open any project and type /backendmax run a full diagnosis.

</details> <details> <summary>Claude Desktop</summary>

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "backend-max": {
      "command": "npx",
      "args": ["-y", "backend-max"]
    }
  }
}

</details> <details> <summary>VS Code / Cursor</summary>

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "backend-max": {
      "command": "npx",
      "args": ["-y", "backend-max"]
    }
  }
}

</details> <details> <summary>Windsurf</summary>

Add to your MCP config:

{
  "mcpServers": {
    "backend-max": {
      "command": "npx",
      "args": ["-y", "backend-max"]
    }
  }
}

</details> <details> <summary>From source (for development)</summary>

git clone https://github.com/rish-e/backend-max.git
cd backend-max
npm install && npm run build

Then add to your MCP client config:

{
  "command": "node",
  "args": ["/path/to/backend-max/dist/server.js"]
}

</details>

Run Your First Diagnosis

Open your MCP client in any project and ask:

/backendmax run a full diagnosis on my project

That's it. Backend Max will analyze your project and return a full diagnostic report with health score, issues, and fix suggestions.

4. CI/CD Mode (Optional)

Run diagnostics from the command line or GitHub Actions:

# Basic diagnosis
npx backend-max-cli diagnose ./my-project

# CI mode — fail if health score drops below 75 or critical issues found
npx backend-max-cli diagnose ./my-project --ci --min-score 75 --fail-on critical

# Output formats
npx backend-max-cli diagnose ./my-project --format markdown  # PR comments
npx backend-max-cli diagnose ./my-project --format sarif     # GitHub Code Scanning
npx backend-max-cli diagnose ./my-project --format json      # Raw data

🔬 Features Deep Dive

🆕 v2.2 — Tier 2 Feature Drop

| Feature | Description | |---------|-------------| | ⚡ Fastify Support | Full route analysis with built-in JSON Schema validation detection, error handler checks, param extraction | | 🔥 Hono Support | Route analysis with basePath resolution, zValidator detection, middleware arg parsing | | 🚦 Rate Limiting Audit | Detects rate limiting packages/patterns, flags unprotected auth endpoints, checks caching coverage | | 📐 API Versioning | Detects path/header versioning, finds version gaps, flags inconsistent versioning | | 🔗 Middleware Visualization | Maps global/inline middleware chains per route, checks ordering, generates markdown visualization | | 🔍 Multi-Layer Type Tracing | Traces types across frontend → route → service → repository → DB, finds cross-layer mismatches |

v2.1 — Tier 1 Feature Drop

| Feature | Description | |---------|-------------| | 🔧 Auto-Fix Engine | Generates real unified diff patches for common issues — try/catch wrapping, Zod validation, auth guards, pagination. Apply with git apply | | 👁️ Watch Mode | Incremental analysis — shows new issues, fixed issues, and health score delta since last run. No full re-scan needed | | 🔀 tRPC Support | Full router analysis — procedures, input validation, protected/public, queries vs mutations. 3 tRPC-specific checks | | 🕸️ GraphQL Analysis | Resolver scanning for Apollo, Yoga, Mercurius, type-graphql, NestJS. N+1 detection, auth checks, input validation | | 📦 Dependency Scanner | Built-in vulnerability database (12+ packages), deprecated package detection, lock file checks, npm audit integration |

v2.0 Features

| Feature | Description | |---------|-------------| | 🗄️ Prisma Schema Integration | Parses your .prisma schema and cross-references every database call — catches nonexistent models, fields, and missing indexes | | 🔍 Deep Type Flow Analysis | Traces frontend response variables to check property access against backend return types — catches data.user.firstName vs data.user.first_name | | ⚡ Server Actions | Full audit of Next.js Server Actions ('use server') — validation, auth, error handling, database patterns | | 🚀 CI/CD Mode | CLI entry point with --ci, --min-score, --fail-on, and 4 output formats (text, markdown, JSON, SARIF) | | 🟢 Express.js Support | Route scanning, middleware detection, Express-specific checks (error middleware, 404, helmet/CORS) | | 📄 Pages Router | Next.js Pages Router API routes (pages/api/) full

BackendMax

Install / Use

README

🩺 AI-Powered Backend Diagnostics for Claude Code

🤔 What Is This?

🔭 How It Works

⚡ Why Backend Max?

🚀 Quick Start

Install with your MCP client

Run Your First Diagnosis

4. CI/CD Mode (Optional)

🔬 Features Deep Dive

🆕 v2.2 — Tier 2 Feature Drop

v2.1 — Tier 1 Feature Drop

v2.0 Features