codeguardian-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Godwin Mayodi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# CodeGuardian MCP
+
+<p align="center">
+  <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**:
+
+```typescript
+// [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](https://nodejs.org/))
+- **pnpm** package manager ([Install](https://pnpm.io/installation))
+
+### Clone & Build
+
+```bash
+# Clone the repository
+git clone https://github.com/codegoddy/codeguardian_mcp.git
+cd codeguardian_mcp
+
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm run build
+```
+
+## Connecting to Your MCP Client
+
+After building, you need to tell your MCP client (Claude Desktop, Windsurf, Cursor, etc.) where CodeGuardian lives.
+
+The key is the **absolute path** to `dist/server.js` inside wherever you cloned the repo.
+
+### 1. Find your path
+
+Run this from inside the cloned repo to get the exact path:
+
+```bash
+echo "$(pwd)/dist/server.js"
+```
+
+This will output something like:
+- **Linux**: `/home/youruser/codeguardian_mcp/dist/server.js`
+- **macOS**: `/Users/youruser/codeguardian_mcp/dist/server.js`
+- **Windows**: `C:\Users\youruser\codeguardian_mcp\dist\server.js`
+
+### 2. Add to your MCP client config
+
+Copy the path from step 1 and add it to your client's MCP configuration:
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "codeguardian": {
+      "command": "node",
+      "args": ["/home/youruser/codeguardian_mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+**Windsurf / Cursor** (`mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "codeguardian": {
+      "command": "node",
+      "args": ["/home/youruser/codeguardian_mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+**OpenCode** (`opencode.json` in your project root):
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "codeguardian": {
+      "type": "local",
+      "command": ["node", "/home/youruser/codeguardian_mcp/dist/server.js"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Gemini CLI / Antigravity** (`settings.json`):
+```json
+{
+  "mcpServers": {
+    "codeguardian": {
+      "command": "node",
+      "args": ["/home/youruser/codeguardian_mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+**Claude Code** (CLI):
+```bash
+claude mcp add --transport stdio codeguardian -- node /home/youruser/codeguardian_mcp/dist/server.js
+```
+
+> **Important:** Replace the path with the actual output from step 1. The path depends on where **you** cloned the repo.
+
+### 3. Restart your MCP client
+
+Restart your IDE / MCP client for the changes to take effect. You should see CodeGuardian's tools become available.
+
+## 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.
+
+```
+start_validation({
+  projectPath: "/absolute/path/to/your/project",
+  language: "typescript"
+})
+```
+
+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.
+
+```
+start_guardian({
+  projectPath: "/absolute/path/to/your/project",
+  language: "typescript"
+})
+```
+
+Once running, it catches issues in real-time. 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 audits, `start_guardian` for continuous protection.
+
+## 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](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](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>

package/dist/agent/agentTools.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent Tools - Start/Stop Agent Mode
+ *
+ * MCP tools to control the proactive agent mode.
+ *
+ * @format
+ */
+import { ToolDefinition } from "../types/tools.js";
+export declare const startGuardianTool: ToolDefinition;
+export declare const stopGuardianTool: ToolDefinition;
+export declare const getGuardianAlertsTool: ToolDefinition;
+export declare const getGuardianStatusTool: ToolDefinition;
+export declare const validateApiContractsTool: ToolDefinition;
+export declare const getApiContractReportTool: ToolDefinition;
+/**
+ * Stop all in-memory guardian watchers WITHOUT removing persisted configs.
+ * Called during server shutdown so guardians auto-restore on next startup.
+ */
+export declare function shutdownGuardiansGracefully(): Promise<void>;
+/**
+ * Restore guardians from persisted configs.
+ * Called once during server startup to resume any guardians that were
+ * running before the server was restarted (e.g., new LLM session).
+ */
+export declare function restoreGuardians(): Promise<number>;
+//# sourceMappingURL=agentTools.d.ts.map

package/dist/agent/agentTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentTools.d.ts","sourceRoot":"","sources":["../../src/agent/agentTools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAoInD,eAAO,MAAM,iBAAiB,EAAE,cAqH/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cA4F9B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,cA6GnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,cAiDnC,CAAC;AAMF,eAAO,MAAM,wBAAwB,EAAE,cAqEtC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,cA2FtC,CAAC;AAMF;;;GAGG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAQjE;AAMD;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAiExD"}