CodeMax

CodeMax

The full-stack MCP that sees what single-side tools miss.

[](https://www.npmjs.com/package/codemax-mcp) [](LICENSE) [](https://nodejs.org) [](https://www.typescriptlang.org) []()

---

CodeMax bridges the gap between frontend and backend analysis. It scans both sides of your stack, cross-references API contracts, and surfaces the issues that neither side can detect alone.

Built to work alongside UIMax (frontend analysis) and BackendMax (backend analysis) — or completely standalone.

                    MCP Client
           (Claude Code, Cursor, etc.)
          ┌──────────┼──────────┐
          │          │          │
     ┌────▼───┐ ┌───▼────┐ ┌──▼────────┐
     │ UIMax  │ │CodeMax │ │BackendMax │
     │  (FE)  │ │(bridge)│ │   (BE)    │
     └────────┘ └───┬────┘ └───────────┘
                    │
            ┌───────▼───────┐
            │  Cross-Stack  │
            │    Engine     │
            └───────────────┘

---

Install

Claude Code

claude mcp add codemax -- npx -y codemax-mcp

Cursor

Add to your MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "codemax": {
      "command": "npx",
      "args": ["-y", "codemax-mcp"]
    }
  }
}

VS Code (Copilot)

Add to your user or workspace settings (.vscode/mcp.json):

{
  "servers": {
    "codemax": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codemax-mcp"]
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "codemax": {
      "command": "npx",
      "args": ["-y", "codemax-mcp"]
    }
  }
}

Cline

Add to Cline MCP settings:

{
  "mcpServers": {
    "codemax": {
      "command": "npx",
      "args": ["-y", "codemax-mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codemax": {
      "command": "npx",
      "args": ["-y", "codemax-mcp"]
    }
  }
}

From Source

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

{
  "mcpServers": {
    "codemax": {
      "command": "node",
      "args": ["/path/to/codemax/dist/index.js"]
    }
  }
}

---

CLI Mode

CodeMax also works as a standalone CLI for CI/CD pipelines and terminal use:

# Full audit with markdown output
npx codemax-mcp audit .

# JSON output (pipe to jq, etc.)
npx codemax-mcp audit . --format json

# SARIF output (GitHub Code Scanning)
npx codemax-mcp audit . --format sarif > results.sarif

# CI mode — exit code 1 if health score below threshold
npx codemax-mcp audit . --ci --threshold 75

# Only scan files changed in git
npx codemax-mcp audit . --diff

# Combine everything
npx codemax-mcp audit . --diff --ci --format sarif

CLI Options

| Option | Description | |--------|-------------| | --format, -f | Output format: markdown (default), json, sarif | | --ci | CI mode — exit code 1 if health below threshold | | --threshold, -t | Health score threshold for --ci (default: 70) | | --diff | Only scan files changed in git (staged + unstaged) | | --version | Print version | | --help | Print help |

GitHub Actions

- name: Run CodeMax
  run: npx codemax-mcp audit . --ci --format sarif > codemax.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: codemax.sarif

---

What It Finds

CodeMax detects cross-stack issues that frontend-only or backend-only tools structurally cannot see:

| Issue | What happens | Example | |-------|-------------|---------| | Phantom Calls | Frontend calls an endpoint that doesn't exist | fetch('/api/users') but no /api/users route handler | | Dead Endpoints | Backend exposes a route nobody calls | GET /api/admin/stats with zero frontend consumers | | Method Mismatch | Frontend sends POST, backend expects GET | Form submit uses POST but route only exports GET | | Field Drift | Frontend expects fields the backend doesn't return | Destructures data.avatar but API returns data.image | | Auth Gaps | One side assumes auth, the other doesn't | Frontend sends Bearer token but backend never checks it | | Missing Validation | POST/PUT with no input validation | Backend accepts any payload with no Zod/schema check | | Over-Fetching | Backend returns 50 fields, frontend uses 3 | Wastes bandwidth and may leak sensitive data | | N+1 API Calls | Frontend fetches list then each item separately | List endpoint + N detail calls in a loop | | Env Drift | Code references vars not defined in .env | process.env.API_KEY but no API_KEY in .env | | Prefix Issues | Client code uses non-public env vars | process.env.SECRET in a React component (always undefined) |

---

Tools

Full Analysis

| Tool | Description | |------|-------------| | full_stack_audit | Comprehensive analysis — scans both sides, cross-references contracts, scores health across 6 dimensions. The complete picture. | | health_check | Quick pulse check — health grade (A-F) with top 5 issues. Faster than a full audit. |

Cross-Stack

| Tool | Description | |------|-------------| | check_contracts | Compare every frontend API call against every backend route. Find phantom calls, dead endpoints, and mismatches. | | trace_issue | Given a bug or error message, determine which layer owns it — frontend, backend, or cross-stack. | | map_dependencies | Map all connections between frontend files and backend routes. Find orphans and phantoms. | | check_env | Cross-reference .env files against actual usage in frontend and backend code. |

Documentation & History

| Tool | Description | |------|-------------| | get_history | Audit trail — health trend over time, issue lifecycle (new, fixed, regressed), scan statistics. | | log_fix | Document how a specific issue was resolved. Recorded in the ledger and appears in REPORT.md. | | acknowledge_issue | Mark an issue as intentional/acceptable. Won't be flagged in future reports. | | get_report | Read the living REPORT.md — all issues, fixes, trends, and contract maps in one document. |

Individual Scans

| Tool | Description | |------|-------------| | scan_frontend | All frontend API calls — fetch, axios, SWR, React Query, server actions. | | scan_backend | All backend routes — Next.js, Express, server actions. Auth, validation, and error handling. | | detect_project | Project structure — frameworks, monorepo, ORM, paths, package manager. |

---

How It Works

1. Project Detection

CodeMax auto-detects your project structure:

• Monorepo? Checks for turbo.json, pnpm-workspace.yaml, lerna.json, workspace configs
• Frontend framework? Next.js (App/Pages), React, Vue, Svelte, Angular
• Backend framework? Next.js API, Server Actions, Express, Fastify, tRPC, GraphQL
• ORM? Prisma, Drizzle, TypeORM, Sequelize
• Layer boundaries? Identifies which directories are frontend, backend, and shared

2. Dual Scanning

The frontend scanner finds every API call:

fetch('/api/users')           → GET /api/users (fetch)
axios.post('/api/posts')      → POST /api/posts (axios)
useSWR('/api/dashboard')      → GET /api/dashboard (swr)
useQuery(['posts'])           → GET (react-query)
createUser(formData)          → POST server-action:createUser

The backend scanner finds every route handler:

app/api/users/route.ts        → GET /api/users, POST /api/users
app/api/users/[id]/route.ts   → GET /api/users/:param
pages/api/auth.ts             → GET,POST /api/auth
server.ts (Express)           → router.get('/api/...'), router.post('/api/...')
actions.ts ('use server')     → server-action:createUser

3. Contract Analysis

The bridge engine cross-references both sides:

Frontend Calls          Backend Routes
──────────────          ──────────────
GET /api/users    ───►  GET /api/users       matched
POST /api/posts   ───►  (nothing)            phantom call
(nothing)         ◄───  GET /api/admin       dead endpoint
POST /api/auth    ───►  GET /api/auth        method mismatch

4. Health Scoring

Six dimensions, weighted and combined into a single grade:

API Contracts    [████████░░] 80/100  — 1 phantom call, 2 mismatches
Error Handling   [██████░░░░] 60/100  — 4/10 calls missing try/catch
Security         [█████████░] 90/100  — 1 unprotected mutation
Performance      [██████████] 100/100 — no anti-patterns
Data Flow        [███████░░░] 70/100  — 2 field mismatches
Environment      [█████████░] 95/100  — 1 missing env var

Overall: B (78/100)

---

Project Documentation (.codemax/)

Every audit automatically persists results to a .codemax/ directory in your project. This gives your team a living audit trail without needing to run CodeMax themselves.

.codemax/
├── ledger.json     # Issue lifecycle tracking (all issues, ever)
└── REPORT.md       # Human-readable living document

REPORT.md

A Markdown file any developer can read — no tools needed. Updated on every full_stack_audit:

• Health Dashboard — current scores across all 6 dimensions
• Health Trend — score over time, so you can see if things are improving
• Latest Scan Changes — what's new, what's fixed, what regressed
• Open Issues — every issue with evidence, code snippets, and fix suggestions
• Fix Log — table of everything that was resolved, when, and how
• Regression History — issues that were fixed but came back
• API Contract Map — full frontend-to-backend connection table
• Project Structure — detected frameworks, ORM, paths

Issue Lifecycle

Issues are tracked through their lifecycle across scans:

Discovered ──► open ──► fixed (disappears from next scan)
                │                    │
                ▼                    ▼
          acknowledged          regressed (comes back)
         (intentional)               │
                                     ▼
                                   fixed (again)

• Auto-detection: Issues are automatically marked fixed when they disappear from a scan
• Manual logging: Use log_fix to document how something was resolved
• Regression tracking: If a fixed issue reappears, it's flagged as regressed
• Deterministic fingerprints: Same issue = same fingerprint, even if line numbers shift

Example Workflow

1. Run `full_stack_audit` → finds 8 issues, creates .codemax/REPORT.md
2. Fix 3 issues in your code
3. Run `full_stack_audit` again → auto-detects 3 fixes, finds 1 new issue
4. Use `log_fix CTR-X-a1b2c3 "Added Zod validation to POST /api/users"` → records the how
5. Use `acknowledge_issue DEP-B-d4e5f6` → dead endpoint is intentional (consumed by mobile app)
6. Open .codemax/REPORT.md → full audit trail, readable by anyone

---

Example Output

full_stack_audit

# Full-Stack Audit Report — Grade: B (78/100)

Project: /home/user/my-app
Stack: Next.js (App Router) + Next.js API Routes + prisma
Scanned: 42 frontend files, 18 backend files in 1.2s

## Overview
- 12 frontend API calls found
- 8 backend routes found
- 7 matched contracts
- 1 phantom call (frontend → nowhere)
- 1 dead endpoint (backend → unused)

## Top Issues (6 total)
- [CRITICAL] Frontend calls non-existent endpoint: GET /api/analytics
  Create the backend route handler or fix the frontend URL.
- [HIGH] Frontend expects fields [avatar, role] but backend doesn't return them
  Add the missing fields to the backend response or update the frontend.
- [HIGH] Unprotected mutation: POST /api/comments
  Add authentication middleware or session check.
- [MEDIUM] No error handling: GET /api/dashboard
  Add try/catch or .catch() and show a user-friendly error message.
- [MEDIUM] Over-fetching: GET /api/users — backend returns 15 fields, frontend uses 4
  Use field selection or a DTO to return only needed fields.
- [LOW] Unused endpoint: DELETE /api/legacy-users
  Remove if unused, or document the external consumer.

---

Supported Stacks

Frontend

• Next.js 13+ (App Router)
• Next.js (Pages Router)
• React (CRA, Vite)
• Vue / Nuxt
• Svelte / SvelteKit
• Angular

Backend

• Next.js API Routes (App + Pages)
• Next.js Server Actions
• Express
• Fastify
• tRPC
• GraphQL (Apollo, Yoga)

Data Fetching

• fetch()
• axios
• useSWR
• useQuery / useMutation (React Query / TanStack)
• Server Actions ("use server")

ORM Detection

• Prisma
• Drizzle
• TypeORM
• Sequelize

Monorepo Support

• Turborepo
• pnpm workspaces
• Yarn workspaces
• Lerna
• Nx

---

The Ecosystem

CodeMax is part of a three-MCP ecosystem:

| MCP | Focus | Tools | |-----|-------|-------| | UIMax | Frontend — screenshots, accessibility, Lighthouse, code analysis | 34 tools | | BackendMax | Backend — route scanning, security audit, Prisma, error handling | 20 tools | | CodeMax | Cross-stack — contract verification, issue tracing, health scoring | 13 tools |

Use any combination:

• UIMax alone — pure frontend analysis
• BackendMax alone — pure backend analysis
• CodeMax alone — cross-stack analysis with built-in frontend + backend scanners
• All three — maximum coverage, each MCP focuses on what it does best

---

Configuration

CodeMax works zero-config out of the box. It auto-detects everything.

For advanced cases, you can create a .codemaxrc.json:

{
  "frontendPaths": ["packages/web/src"],
  "backendPaths": ["packages/api/src"],
  "sharedPaths": ["packages/shared"],
  "ignore": ["**/*.test.ts", "**/__mocks__/**"],
  "severity": {
    "phantom-call": "critical",
    "dead-endpoint": "low",
    "over-fetching": "medium"
  }
}

---

Development

git clone https://github.com/rish-e/codemax.git
cd codemax
npm install
npm run build
npm test

Project Structure

src/
├── index.ts                    # Entry point (MCP server + CLI dispatcher)
├── cli.ts                      # CLI mode (audit, --format, --diff, --ci)
├── server.ts                   # MCP server + 13 tool registrations
├── types.ts                    # Shared type definitions
├── analyzers/
│   ├── project-detector.ts     # Framework, monorepo, ORM detection
│   ├── frontend-scanner.ts     # API call extraction (fetch, axios, SWR, etc.)
│   ├── backend-scanner.ts      # Route extraction (Next.js, Express, etc.)
│   └── env-analyzer.ts         # Environment variable cross-referencing
├── bridge/
│   ├── orchestrator.ts         # Full audit coordination + ledger integration
│   ├── contract-analyzer.ts    # Frontend ↔ backend contract comparison
│   ├── correlator.ts           # Cross-stack issue detection
│   └── health-scorer.ts        # 6-dimension health scoring
├── formatters/
│   └── sarif.ts                # SARIF 2.1.0 output (GitHub Code Scanning)
├── tools/
│   ├── ledger-manager.ts       # Issue lifecycle tracking (fingerprint, fix, regress)
│   └── report-writer.ts        # Living REPORT.md generation
├── utils/
│   └── helpers.ts              # URL normalization, scoring, formatting
└── __tests__/
    ├── helpers.test.ts
    ├── project-detector.test.ts
    ├── contract-analyzer.test.ts
    ├── scanners.test.ts
    └── ledger.test.ts

---

Safety

CodeMax is read-only static analysis:

• Never executes code — pure AST parsing and regex matching
• Never reads .env values — only checks variable names exist
• Never modifies files — zero writes to your codebase (only to .codemax/)
• Never sends data externally — everything stays local
• Caps scan scope — 5,000 files max, 1MB per file, 15 directory levels

---

Contributing

Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, guidelines, and architecture principles.

---

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rish-e
• Source: rish-e/CodeMax
• License: MIT
• Homepage: https://www.npmjs.com/package/codemax-mcp

Install and usage instructions live in the source repository linked above.