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

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

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

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

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

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

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

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"]
    }
  }
}

# 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

- 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

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

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

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

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)

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

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

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

# 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.

{
  "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"
  }
}

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

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