CodeGuardian MCP

Catches AI hallucinations before they break your code

<a href="#installation">Installation</a> • <a href="#connecting-to-your-mcp-client">Connect MCP</a> • <a href="#quick-start">Quick Start</a> • <a href="#features">Features</a> • <a href="#all-tools">All Tools</a> • <a href="#contributing">Contributing</a>

---

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

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): ``json { "mcpServers": { "codeguardian": { "command": "npx", "args": ["-y", "codeguardian-mcp"] } } } ``

Windsurf (mcp_config.json): ``json { "mcpServers": { "codeguardian": { "command": "npx", "args": ["-y", "codeguardian-mcp"] } } } ``

Cursor (.cursor/mcp.json): ``json { "mcpServers": { "codeguardian": { "command": "npx", "args": ["-y", "codeguardian-mcp"] } } } ``

OpenCode (opencode.json in your project root): ``json { "$schema": "https://opencode.ai/config.json", "mcp": { "codeguardian": { "type": "local", "command": ["npx", "-y", "codeguardian-mcp"], "enabled": true } } } ``

Gemini CLI (settings.json): ``json { "mcpServers": { "codeguardian": { "command": "npx", "args": ["-y", "codeguardian-mcp"] } } } ``

Claude Code (CLI): ``bash 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

| Score | Level | Action | |-------|-------|--------| | 0-49 | Critical | REJECT - Major hallucinations detected | | 50-69 | Low | REVIEW - Multiple issues need attention | | 70-89 | Medium | CAUTION - Minor issues, review suggested | | 90-100 | High | ACCEPT - Code is safe to use |

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

| Type | Example | Severity | Confidence | |------|---------|----------|------------| | Non-existent function | getUserById() when it doesn't exist | Critical | 95% | | Non-existent class | new PaymentService() when undefined | Critical | 95% | | Bad import | import { foo } from './utils' when not exported | Critical | 93% | | Missing dependency | import 'react-ui' not in package.json | Critical | 95% | | Wrong method | user.getFullName() on class without it | Medium | 70% | | Wrong param count | func(a, b) when expects 3 params | High | 88% | | Dead export | Exported function nothing imports | Medium | 85% | | Hardcoded credentials | API_KEY = 'sk_live_...' | Critical | 85% | | API contract mismatch | Frontend calls endpoint that doesn't exist on backend | Critical | 90% |

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)

| Tool | Description | |------|-------------| | start_validation | Full project scan — runs in background, no timeouts. Use for on-demand audits. | | start_guardian | Real-time file watcher — validates files as they change. Use for continuous protection. |

Validation Job Tools

| Tool | Description | |------|-------------| | get_validation_status | Poll progress of a start_validation job | | get_validation_results | Get final results when a validation job completes |

Guardian Tools

| Tool | Description | |------|-------------| | get_guardian_alerts | Get current issues found by active guardians | | get_guardian_status | Check which guardians are running | | stop_guardian | Stop a specific guardian or all guardians |

Individual Tools

| Tool | Description | |------|-------------| | validate_code | Validate a single code snippet against your project's symbols | | build_context | Build/rebuild project symbol index (usually auto-called) | | get_dependency_graph | Show what files depend on what — understand the blast radius of changes |

API Contract Tools

| Tool | Description | |------|-------------| | validate_api_contracts | Validate frontend/backend API contract compatibility | | get_api_contract_report | Generate a detailed API contract validation report |

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.

---

Made by developers who are tired of AI hallucinations

<a href="https://github.com/codegoddy/codeguardian_mcp">Star us on GitHub</a> • <a href="https://github.com/codegoddy/codeguardian_mcp/issues">Report Issues</a> • <a href="https://github.com/codegoddy/codeguardian_mcp/discussions">Discussions</a>

CodeGuardian MCP

CodeGuardian MCP

The Problem

The Solution

Installation

Prerequisites

Install from npm

Install from source (for contributors)

Connecting to Your MCP Client

Quick Start

`start_validation` — Full Project Health Check

`start_guardian` — Real-Time File Watcher

Features

AI Hallucination Detection

Confidence Scoring

Dead Code Detection

API Contract Validation

Multi-Language Support

Full-Stack Projects

Real-Time Validation

What It Catches

How It Works

All Tools

Primary Tools (start here)

Validation Job Tools

Guardian Tools

Individual Tools

API Contract Tools

What It Skips (No False Positives)

Limitations

Contributing

License

Related MCP servers

MCP servers by category

CodeGuardian MCP

CodeGuardian MCP

The Problem

The Solution

Installation

Prerequisites

Install from npm

Install from source (for contributors)

Connecting to Your MCP Client

Quick Start

start_validation — Full Project Health Check

start_guardian — Real-Time File Watcher

Features

AI Hallucination Detection

Confidence Scoring

Dead Code Detection

API Contract Validation

Multi-Language Support

Full-Stack Projects

Real-Time Validation

What It Catches

How It Works

All Tools

Primary Tools (start here)

Validation Job Tools

Guardian Tools

Individual Tools

API Contract Tools

What It Skips (No False Positives)

Limitations

Contributing

License

Related MCP servers

MCP servers by category

`start_validation` — Full Project Health Check

`start_guardian` — Real-Time File Watcher