CodeGuardian MCP

CodeGuardian MCP

<p align="center"> <img src="https://img.shields.io/npm/v/codeguardian-mcp?style=for-the-badge&color=FF6B6B" alt="npm version"> <img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black" alt="JavaScript"> <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/MCP%20Server-FF6B6B?style=for-the-badge&logo=server&logoColor=white" alt="MCP Server"> </p>

<p align="center"> <img src="https://img.shields.io/badge/AI%20Hallucination%20Detection-00C853?style=for-the-badge&logo=artificial-intelligence&logoColor=white" alt="AI Hallucination Detection"> <img src="https://img.shields.io/badge/Dead%20Code%20Detection-FF9800?style=for-the-badge&logo=code&logoColor=white" alt="Dead Code Detection"> <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"> </p>

<p align="center"> <b>Catches AI hallucinations before they break your code</b> </p>

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

---

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.

---

<p align="center"> <b>Made by developers who are tired of AI hallucinations</b> </p>

<p align="center"> <a href="https://github.com/codegoddy/codeguardian_mcp">Star us on GitHub</a> &bull; <a href="https://github.com/codegoddy/codeguardian_mcp/issues">Report Issues</a> &bull; <a href="https://github.com/codegoddy/codeguardian_mcp/discussions">Discussions</a> </p>