CodeMax

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

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 for development setup, guidelines, and architecture principles.

Roadmap

License

MIT

FilesExpand file tree

README.md

Latest commit

History