![\"npm](\"https://img.shields.io/npm/v/codeguardian-mcp?style=for-the-badge&color=FF6B6B\")
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white\"){kind=icon}
\n ![\"JavaScript\"](\"https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black\"){kind=icon}
\n ![\"Python\"](\"https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white\"){kind=icon}
\n ![\"MCP](\"https://img.shields.io/badge/MCP%20Server-FF6B6B?style=for-the-badge&logo=server&logoColor=white\"){kind=icon}
\n\n
\n ![\"AI](\"https://img.shields.io/badge/AI%20Hallucination%20Detection-00C853?style=for-the-badge&logo=artificial-intelligence&logoColor=white\"){kind=icon}
![\"Dead](\"https://img.shields.io/badge/Dead%20Code%20Detection-FF9800?style=for-the-badge&logo=code&logoColor=white\"){kind=icon}
![\"License\"](\"https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge\"){kind=icon}
\n Catches AI hallucinations before they break your code\n
\n\n\n Installation •\n Connect MCP •\n Quick Start •\n Features •\n All Tools •\n Contributing\n
\n\n---\n\n## The Problem\n\nAI coding assistants hallucinate. They generate code that **compiles fine but breaks at runtime**:\n\n```typescript\n// [X] AI generates this:\nconst user = getUserById(id); // Function doesn't exist!\n\n// [OK] Your codebase has:\nconst user = findUserById(id); // Correct function name\n```\n\n**Common AI Hallucinations:**\n- [CRITICAL] Calling `getUserById()` when your codebase has `findUserById()`\n- [CRITICAL] Using methods that aren't on your classes\n- [CRITICAL] Importing from modules that don't export what they claim\n- [CRITICAL] Creating dead code that nothing ever uses\n\n## The Solution\n\nCodeGuardian validates AI-generated code against your **actual codebase** before you run it.\n\n```\n┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐\n│ AI Generates │────▶│ CodeGuardian │────▶│ Issues Found │\n│ Code │ │ Validates │ │ + Suggestions │\n└─────────────────┘ └──────────────────┘ └─────────────────┘\n │ │ │\n ▼ ▼ ▼\n Vibe Coding AST Parsing Fix Before\n Confidently Symbol Matching Runtime\n```\n\n## Installation\n\n### Prerequisites\n\n- **Node.js** v20 or higher ([Download](https://nodejs.org/))\n\n### Install from npm\n\n```bash\n# Using npx (no install needed — recommended)\nnpx codeguardian-mcp\n\n# Or install globally\nnpm install -g codeguardian-mcp\n\n# Or with pnpm\npnpm add -g codeguardian-mcp\n```\n\n### Install from source (for contributors)\n\n```bash\ngit clone https://github.com/codegoddy/codeguardian_mcp.git\ncd codeguardian_mcp\npnpm install\npnpm run build\n```\n\n## Connecting to Your MCP Client\n\nAdd CodeGuardian to your MCP client config. No cloning or building required — `npx` handles everything.\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n \"mcpServers\": {\n \"codeguardian\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codeguardian-mcp\"]\n }\n }\n}\n```\n\n**Windsurf** (`mcp_config.json`):\n```json\n{\n \"mcpServers\": {\n \"codeguardian\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codeguardian-mcp\"]\n }\n }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n```json\n{\n \"mcpServers\": {\n \"codeguardian\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codeguardian-mcp\"]\n }\n }\n}\n```\n\n**OpenCode** (`opencode.json` in your project root):\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"codeguardian\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"codeguardian-mcp\"],\n \"enabled\": true\n }\n }\n}\n```\n\n**Gemini CLI** (`settings.json`):\n```json\n{\n \"mcpServers\": {\n \"codeguardian\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codeguardian-mcp\"]\n }\n }\n}\n```\n\n**Claude Code** (CLI):\n```bash\nclaude mcp add --transport stdio codeguardian -- npx -y codeguardian-mcp\n```\n\nRestart your IDE / MCP client for the changes to take effect. You should see CodeGuardian's tools become available.\n\n> **Note:** If you installed globally (`npm install -g codeguardian-mcp`), you can use `\"command\": \"codeguardian-mcp\"` with no args instead of `npx`.\n\n## Quick Start\n\nThe two primary tools that handle everything for you:\n\n### `start_validation` — Full Project Health Check\n\nScans your entire codebase for hallucinations, dead code, and bad imports. Best for on-demand audits.\n\n> **Where to run:** From the **specific subdirectory** you want to validate (e.g., `frontend/` or `backend/`), not the monorepo root.\n\n```\n# Example: Validate frontend only\ncd /path/to/your/project/frontend\nstart_validation({\n projectPath: \"/path/to/your/project/frontend\",\n language: \"typescript\"\n})\n\n# Example: Validate backend only \ncd /path/to/your/project/backend\nstart_validation({\n projectPath: \"/path/to/your/project/backend\", \n language: \"python\"\n})\n```\n\nThis runs in the background (no timeouts). Check progress and get results with:\n- `get_validation_status({ jobId: \"...\" })` — poll progress\n- `get_validation_results({ jobId: \"...\" })` — get the final report\n\n### `start_guardian` — Real-Time File Watcher\n\nWatches your project and automatically validates files as you (or your AI) edit them. Runs continuously in the background.\n\n> **Where to run:** From the **project root directory** (monorepo root). Guardian will auto-detect and watch all subprojects (frontend, backend, etc.).\n\n```\n# Run from project root (monorepo root)\ncd /path/to/your/project\nstart_guardian({\n projectPath: \"/path/to/your/project\",\n language: \"typescript\" // or \"python\" or \"auto\"\n})\n```\n\nOnce running, it catches issues in real-time across all subprojects. Use these companion tools:\n- `get_guardian_alerts` — see current issues found by the watcher\n- `get_guardian_status` — check which guardians are active \n- `stop_guardian` — stop a guardian when done\n\n> **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.\n\n## Features\n\n### AI Hallucination Detection\nCatches non-existent functions, classes, and methods with **95% confidence**\n\n### Confidence Scoring\nEvery issue includes a confidence score (0-100%) and detailed reasoning\n\n| Score | Level | Action |\n|-------|-------|--------|\n| 0-49 | Critical | **REJECT** - Major hallucinations detected |\n| 50-69 | Low | **REVIEW** - Multiple issues need attention |\n| 70-89 | Medium | **CAUTION** - Minor issues, review suggested |\n| 90-100 | High | **ACCEPT** - Code is safe to use |\n\n### Dead Code Detection\nFinds exported functions and classes that nothing imports\n\n### API Contract Validation\nDetects mismatches between frontend and backend — wrong endpoints, missing fields, type incompatibilities\n\n### Multi-Language Support\n- **TypeScript / JavaScript** — full support\n- **Python** — full support\n\n### Full-Stack Projects\nAutomatically detects full-stack projects (e.g. React + FastAPI, Next.js + Express) and validates each language correctly.\n\n### Real-Time Validation\nValidates code immediately after generation with sub-second response times\n\n## What It Catches\n\n| Type | Example | Severity | Confidence |\n|------|---------|----------|------------|\n| Non-existent function | `getUserById()` when it doesn't exist | Critical | 95% |\n| Non-existent class | `new PaymentService()` when undefined | Critical | 95% |\n| Bad import | `import { foo } from './utils'` when not exported | Critical | 93% |\n| Missing dependency | `import 'react-ui'` not in package.json | Critical | 95% |\n| Wrong method | `user.getFullName()` on class without it | Medium | 70% |\n| Wrong param count | `func(a, b)` when expects 3 params | High | 88% |\n| Dead export | Exported function nothing imports | Medium | 85% |\n| Hardcoded credentials | `API_KEY = 'sk_live_...'` | Critical | 85% |\n| API contract mismatch | Frontend calls endpoint that doesn't exist on backend | Critical | 90% |\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ CodeGuardian Pipeline │\n├─────────────────────────────────────────────────────────────┤\n│ 1. AST Parsing │\n│ └─> Uses tree-sitter to parse your codebase │\n│ └─> Extracts all symbols (functions, classes, methods) │\n│ │\n│ 2. Context Building │\n│ └─> Builds searchable index of project symbols │\n│ └─> Caches for fast subsequent validations │\n│ │\n│ 3. Validation │\n│ └─> Compares AI-generated code against index │\n│ └─> Flags anything that doesn't exist │\n│ │\n│ 4. Suggestions │\n│ └─> Uses fuzzy matching to suggest corrections │\n│ └─> Provides confidence scores and reasoning │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## All Tools\n\n### Primary Tools (start here)\n\n| Tool | Description |\n|------|-------------|\n| `start_validation` | Full project scan — runs in background, no timeouts. Use for on-demand audits. |\n| `start_guardian` | Real-time file watcher — validates files as they change. Use for continuous protection. |\n\n### Validation Job Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_validation_status` | Poll progress of a `start_validation` job |\n| `get_validation_results` | Get final results when a validation job completes |\n\n### Guardian Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_guardian_alerts` | Get current issues found by active guardians |\n| `get_guardian_status` | Check which guardians are running |\n| `stop_guardian` | Stop a specific guardian or all guardians |\n\n### Individual Tools\n\n| Tool | Description |\n|------|-------------|\n| `validate_code` | Validate a single code snippet against your project's symbols |\n| `build_context` | Build/rebuild project symbol index (usually auto-called) |\n| `get_dependency_graph` | Show what files depend on what — understand the blast radius of changes |\n\n### API Contract Tools\n\n| Tool | Description |\n|------|-------------|\n| `validate_api_contracts` | Validate frontend/backend API contract compatibility |\n| `get_api_contract_report` | Generate a detailed API contract validation report |\n\n## What It Skips (No False Positives)\n\n- [OK] External packages (npm/pip) - not your code\n- [OK] Built-ins (`console.log`, `print`, `Math.random`)\n- [OK] New code being created in the same snippet\n- [OK] Entry points (`index.ts`, `main.py`)\n- [OK] Test files\n\n## Limitations\n\n- **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.\n- Doesn't catch logic errors (that's still on you)\n- Dynamic code (`eval`, reflection) can't be tracked\n- Method calls on untyped objects may be skipped to avoid false positives\n- Very large monorepos (>1000 files) should use `start_validation` with batching\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n\n Made by developers who are tired of AI hallucinations\n
\n\n\n Star us on GitHub •\n Report Issues •\n Discussions\n
\n","readmeFilename":"README.md"}