CodeGuardian MCP

The Problem

AI coding assistants hallucinate. They generate code that compiles fine but breaks at runtime:

// [X] AI generates this:
const user = getUserById(id);  // Function doesn't exist!

// [OK] Your codebase has:
const user = findUserById(id);  // Correct function name

Common AI Hallucinations:

• [CRITICAL] Calling getUserById() when your codebase has findUserById()

• [CRITICAL] Using methods that aren't on your classes

• [CRITICAL] Importing from modules that don't export what they claim

• [CRITICAL] Creating dead code that nothing ever uses

Related MCP server: CodeTruth MCP Server

The Solution

CodeGuardian validates AI-generated code against your actual codebase before you run it.

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  AI Generates   │────▶│  CodeGuardian    │────▶│  Issues Found   │
│     Code        │     │   Validates      │     │  + Suggestions  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                       │                         │
         ▼                       ▼                         ▼
   Vibe Coding              AST Parsing              Fix Before
   Confidently              Symbol Matching          Runtime

Installation

Prerequisites

• Node.js v20 or higher (Download)

Install from npm

# Using npx (no install needed — recommended)
npx codeguardian-mcp

# Or install globally
npm install -g codeguardian-mcp

# Or with pnpm
pnpm add -g codeguardian-mcp

Install from source (for contributors)

git clone https://github.com/codegoddy/codeguardian_mcp.git
cd codeguardian_mcp
pnpm install
pnpm run build

Connecting to Your MCP Client

Add CodeGuardian to your MCP client config. No cloning or building required — npx handles everything.

Claude Desktop (claude_desktop_config.json):

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

Windsurf (mcp_config.json):

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

Cursor (.cursor/mcp.json):

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

OpenCode (opencode.json in your project root):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codeguardian": {
      "type": "local",
      "command": ["npx", "-y", "codeguardian-mcp"],
      "enabled": true
    }
  }
}

Gemini CLI (settings.json):

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

Claude Code (CLI):

claude mcp add --transport stdio codeguardian -- npx -y codeguardian-mcp

Restart your IDE / MCP client for the changes to take effect. You should see CodeGuardian's tools become available.

Note: If you installed globally (npm install -g codeguardian-mcp), you can use "command": "codeguardian-mcp" with no args instead of npx.

Quick Start

The two primary tools that handle everything for you:

start_validation — Full Project Health Check

Scans your entire codebase for hallucinations, dead code, and bad imports. Best for on-demand audits.

Where to run: From the specific subdirectory you want to validate (e.g., frontend/ or backend/), not the monorepo root.

# Example: Validate frontend only
cd /path/to/your/project/frontend
start_validation({
  projectPath: "/path/to/your/project/frontend",
  language: "typescript"
})

# Example: Validate backend only  
cd /path/to/your/project/backend
start_validation({
  projectPath: "/path/to/your/project/backend", 
  language: "python"
})

This runs in the background (no timeouts). Check progress and get results with:

• get_validation_status({ jobId: "..." }) — poll progress

• get_validation_results({ jobId: "..." }) — get the final report

start_guardian — Real-Time File Watcher

Watches your project and automatically validates files as you (or your AI) edit them. Runs continuously in the background.

Where to run: From the project root directory (monorepo root). Guardian will auto-detect and watch all subprojects (frontend, backend, etc.).

# Run from project root (monorepo root)
cd /path/to/your/project
start_guardian({
  projectPath: "/path/to/your/project",
  language: "typescript"  // or "python" or "auto"
})

Once running, it catches issues in real-time across all subprojects. Use these companion tools:

• get_guardian_alerts — see current issues found by the watcher

• get_guardian_status — check which guardians are active

• stop_guardian — stop a guardian when done

Tip: These two tools handle everything without needing to call individual validation tools manually. start_validation for focused audits on specific subdirectories, start_guardian for continuous protection across the entire project.

Features

AI Hallucination Detection

Catches non-existent functions, classes, and methods with 95% confidence

Confidence Scoring

Every issue includes a confidence score (0-100%) and detailed reasoning

Dead Code Detection

Finds exported functions and classes that nothing imports

API Contract Validation

Detects mismatches between frontend and backend — wrong endpoints, missing fields, type incompatibilities

Multi-Language Support

• TypeScript / JavaScript — full support

• Python — full support

Full-Stack Projects

Automatically detects full-stack projects (e.g. React + FastAPI, Next.js + Express) and validates each language correctly.

Real-Time Validation

Validates code immediately after generation with sub-second response times

What It Catches

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    CodeGuardian Pipeline                     │
├─────────────────────────────────────────────────────────────┤
│  1. AST Parsing                                              │
│     └─> Uses tree-sitter to parse your codebase              │
│     └─> Extracts all symbols (functions, classes, methods)   │
│                                                              │
│  2. Context Building                                         │
│     └─> Builds searchable index of project symbols           │
│     └─> Caches for fast subsequent validations               │
│                                                              │
│  3. Validation                                               │
│     └─> Compares AI-generated code against index             │
│     └─> Flags anything that doesn't exist                    │
│                                                              │
│  4. Suggestions                                              │
│     └─> Uses fuzzy matching to suggest corrections           │
│     └─> Provides confidence scores and reasoning             │
└─────────────────────────────────────────────────────────────┘

All Tools

Primary Tools (start here)

Validation Job Tools

Guardian Tools

Individual Tools

API Contract Tools

What It Skips (No False Positives)

• [OK] External packages (npm/pip) - not your code

• [OK] Built-ins (console.log, print, Math.random)

• [OK] New code being created in the same snippet

• [OK] Entry points (index.ts, main.py)

• [OK] Test files

Limitations

• No Python type inference — CodeGuardian uses static AST analysis, not a type system. It cannot resolve types through variable assignments, function return values, or chained calls. For example, if db.query(User) returns a Query object and you call .filter() on it, CodeGuardian cannot verify that .filter() is a valid method because it doesn't track the return type of db.query(). This would require building a mini mypy-style type checker, which is out of scope. Python method calls on dynamically-typed variables are skipped to avoid false positives.

• Doesn't catch logic errors (that's still on you)

• Dynamic code (eval, reflection) can't be tracked

• Method calls on untyped objects may be skipped to avoid false positives

• Very large monorepos (>1000 files) should use start_validation with batching

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.