@vibecheck-ai/mcp 20.0.4 → 23.0.0

package/README.md

@@ -0,0 +1,315 @@
+<div align="center">
+
+<br />
+
+<img src="https://github.com/guardiavault-oss/Vibecheck/raw/HEAD/packages/vscode-extension/images/vibecheck_logo_transparent_2x.png" alt="VibeCheck MCP Server" width="80" />
+
+<br />
+
+# VibeCheck MCP Server
+
+### Give your AI agent a trust layer.
+
+The Model Context Protocol server that lets Cursor, Claude, Windsurf, and any MCP-compatible AI agent scan code for hallucinations, compute trust scores, and gate deployments — using the same 17-engine pipeline as the CLI and VS Code extension.
+
+<br />
+
+[![npm version](https://img.shields.io/npm/v/@vibecheck-ai/mcp?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@vibecheck-ai/mcp)&nbsp;&nbsp;[![Downloads](https://img.shields.io/npm/dm/@vibecheck-ai/mcp?style=for-the-badge&logo=npm&logoColor=white&color=333)](https://www.npmjs.com/package/@vibecheck-ai/mcp)&nbsp;&nbsp;[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](../../LICENSE)
+
+</div>
+
+<br />
+
+<!-- TODO: Replace with actual GIF showing MCP in Cursor/Claude -->
+<p align="center">
+  <img src="https://github.com/guardiavault-oss/Vibecheck/raw/HEAD/docs/assets/mcp-cursor-demo.gif" alt="VibeCheck MCP Server running inside Cursor" width="820" />
+</p>
+
+<br />
+
+---
+
+<br />
+
+## What is this?
+
+The **Model Context Protocol (MCP)** is the open standard that connects AI coding agents to external tools. VibeCheck's MCP server exposes the full scanning, scoring, and guarding pipeline as tools that any MCP-compatible client can call.
+
+**Your AI agent writes the code. VibeCheck verifies it didn't hallucinate.**
+
+<br />
+
+### How it works
+
+```
+┌──────────────────┐     stdio / MCP      ┌────────────────────┐
+│   Cursor / Claude │ ◄──────────────────► │  VibeCheck MCP     │
+│   Windsurf / Cline│     tool calls       │  Server            │
+│   Any MCP client  │                      │                    │
+└──────────────────┘                      │  ┌──────────────┐  │
+                                          │  │ 17 Detection  │  │
+                                          │  │ Engines       │  │
+                                          │  └──────────────┘  │
+                                          │  ┌──────────────┐  │
+                                          │  │ Trust Score   │  │
+                                          │  │ Engine        │  │
+                                          │  └──────────────┘  │
+                                          │  ┌──────────────┐  │
+                                          │  │ Context       │  │
+                                          │  │ Engine        │  │
+                                          │  └──────────────┘  │
+                                          └────────────────────┘
+```
+
+<br />
+
+---
+
+<br />
+
+## Quick Start
+
+### Cursor
+
+Add to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["-y", "@vibecheck-ai/mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["-y", "@vibecheck-ai/mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP config:
+
+```json
+{
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["-y", "@vibecheck-ai/mcp"]
+    }
+  }
+}
+```
+
+### Any MCP Client (stdio)
+
+```bash
+npx @vibecheck-ai/mcp
+```
+
+The server communicates over **stdio** using the MCP protocol. No HTTP. No ports. No config files.
+
+<br />
+
+<!-- TODO: Replace with actual screenshot of MCP config in Cursor -->
+<p align="center">
+  <img src="https://github.com/guardiavault-oss/Vibecheck/raw/HEAD/docs/assets/mcp-setup.png" alt="MCP server configuration in Cursor" width="720" />
+</p>
+
+<br />
+
+---
+
+<br />
+
+## Tools
+
+The server exposes 7 tools that your AI agent can call:
+
+### Core Tools (Free)
+
+| Tool | Description |
+|:---|:---|
+| **`vibecheck_scan`** | Scan a file or directory for AI hallucinations and code trust issues. Returns findings with severity, location, and fix suggestions. |
+| **`vibecheck_score`** | Compute a 0–100 trust score with letter grade (A–F) and ship decision (SHIP / REVIEW / NO_SHIP). |
+| **`vibecheck_guard`** | Run a pass/fail gate check. Returns structured pass/fail based on trust score and critical findings. |
+| **`vibecheck_roast`** | Scan and return findings with maximum sass. Same brutal honesty as `vibecheck roast` in the CLI. |
+
+### Context Engine Tools (Paid)
+
+| Tool | Description |
+|:---|:---|
+| **`vibecheck_context_proactive`** | Get proactive context for a focused file — file context, graph neighbors, and learned co-edits. |
+| **`vibecheck_context_intent`** | Query the codebase by natural language intent. Returns matching files and symbols. |
+| **`vibecheck_context_evolve`** | Learn from provenance (`edits.jsonl`) and update `learned.json`. Run periodically to improve context quality. |
+| **`vibecheck_context_feedback`** | Record explicit feedback (helpful / not helpful) to improve future context ranking. |
+
+<br />
+
+---
+
+<br />
+
+## What Your Agent Can Do
+
+Once connected, your AI agent can ask VibeCheck to verify its own work:
+
+### Scan before committing
+
+> *"Scan this file for hallucinations before I save it."*
+
+The agent calls `vibecheck_scan` and gets back every finding with severity, line number, and a suggested fix.
+
+### Gate deployments
+
+> *"Check if this project is safe to ship."*
+
+The agent calls `vibecheck_guard` and gets a structured SHIP / NO_SHIP verdict with the exact issues blocking deployment.
+
+### Score trust
+
+> *"What's the trust score for src/payments/?"*
+
+The agent calls `vibecheck_score` and gets a 0–100 score, letter grade, and dimensional breakdown.
+
+### Get roasted
+
+> *"Roast this codebase."*
+
+The agent calls `vibecheck_roast` for an opinionated, brutally honest assessment.
+
+<br />
+
+<!-- TODO: Replace with actual screenshot of agent using vibecheck_scan -->
+<p align="center">
+  <img src="https://github.com/guardiavault-oss/Vibecheck/raw/HEAD/docs/assets/mcp-agent-scan.png" alt="AI agent using vibecheck_scan tool" width="720" />
+</p>
+
+<br />
+
+---
+
+<br />
+
+## 17 Detection Engines
+
+The same engines that power the CLI and VS Code extension:
+
+| # | Engine | What it catches |
+|:---:|:---|:---|
+| 1 | **Ghost Routes** | API calls to endpoints that were never implemented |
+| 2 | **Dead UI** | Buttons, forms, and links wired to empty handlers |
+| 3 | **Phantom Imports** | Packages referenced but never installed |
+| 4 | **Silent Failures** | Try/catch blocks that swallow errors |
+| 5 | **Hardcoded Mocks** | Test data left in production paths |
+| 6 | **Credential Leaks** | API keys, tokens, secrets in source |
+| 7 | **Env Drift** | Missing `.env` variable references |
+| 8 | **Auth Gaps** | Nonexistent auth providers |
+| 9 | **Type Holes** | `@ts-ignore`, `any` casts hiding bugs |
+| 10 | **Console Pollution** | Debug logs in production bundles |
+| 11 | **Version Hallucinations** | Wrong API for installed version |
+| 12 | **Slopsquatting** | Typosquat package names |
+| 13 | **Architectural Drift** | Structural pattern violations |
+| 14 | **Dependency Vulnerabilities** | Known CVEs |
+| 15 | **Performance Anti-patterns** | Sync I/O in async paths |
+| 16 | **Accessibility Violations** | Missing ARIA, keyboard traps |
+| 17 | **Contract Drift** | Code diverged from spec |
+
+<br />
+
+---
+
+<br />
+
+## Plan-Gated Access
+
+Core scanning tools are **free forever**. Context Engine tools require a paid plan.
+
+| Tool | Free | Vibecoder | Developer | Engineer |
+|:---|:---:|:---:|:---:|:---:|
+| `vibecheck_scan` | ✓ | ✓ | ✓ | ✓ |
+| `vibecheck_score` | ✓ | ✓ | ✓ | ✓ |
+| `vibecheck_guard` | ✓ | ✓ | ✓ | ✓ |
+| `vibecheck_roast` | ✓ | ✓ | ✓ | ✓ |
+| `vibecheck_context_*` | | | ✓ | ✓ |
+
+When a tool is gated, the server returns a clear error message with upgrade instructions — your agent can surface this to the user.
+
+<br />
+
+---
+
+<br />
+
+## Production Hardening
+
+The MCP server includes enterprise-grade reliability features:
+
+- **Input validation** — All tool arguments are validated before execution
+- **Rate limiting** — Prevents runaway agents from overwhelming the scanner
+- **Circuit breaker** — Automatic recovery from transient failures
+- **Health monitoring** — Built-in health check endpoint
+- **Observability** — Structured logging for debugging and monitoring
+- **Error sanitization** — Sensitive paths and data are never leaked in error messages
+
+<br />
+
+---
+
+<br />
+
+## Available on 4 Surfaces
+
+| Surface | Install | Use case |
+|:---|:---|:---|
+| **MCP Server** (you are here) | `npx @vibecheck-ai/mcp` | AI agent integration (Cursor, Claude, etc.) |
+| **CLI** | `npm i -g @vibecheck-ai/cli` | CI/CD pipelines, terminal workflows, scripting |
+| **VS Code Extension** | [Marketplace](https://marketplace.visualstudio.com/items?itemName=Vibecheck-AI.vibecheck-AI) | Interactive scanning, sidebar dashboard, inline fixes |
+| **GitHub Action** | `vibecheck-ai/action@v2` | Pull request verification, deployment gating |
+
+<br />
+
+---
+
+<br />
+
+## Privacy & Security
+
+- All scanning runs **locally on your machine**
+- **Zero code is transmitted** — ever
+- The MCP server communicates via **stdio only** — no network ports opened
+- Works **fully offline** and in air-gapped environments
+- [Open source](https://github.com/guardiavault-oss/Vibecheck) — read every line
+
+<br />
+
+---
+
+<br />
+
+<div align="center">
+
+### Build with AI. Ship with proof.
+
+<br />
+
+[Website](https://vibecheckai.dev) &nbsp;&nbsp;·&nbsp;&nbsp; [Documentation](https://docs.vibecheckai.dev) &nbsp;&nbsp;·&nbsp;&nbsp; [Discord](https://discord.gg/vibecheck) &nbsp;&nbsp;·&nbsp;&nbsp; [GitHub](https://github.com/guardiavault-oss/Vibecheck)
+
+<br />
+
+<sub>MIT License &nbsp;·&nbsp; Copyright 2024–2026 VibeCheck AI</sub>
+
+</div>