vibecheck-mcp-server 4.1.0 → 4.3.0

package/README.md

@@ -1,211 +1,284 @@
-# vibecheck MCP Server v4.0
+# @vibecheck/mcp-server
 
-Professional Model Context Protocol server for vibecheck AI.
+<p align="center">
+  <strong>VibeCheck — AI Code Firewall</strong><br/>
+  MCP Server for hallucination prevention in AI-assisted development
+</p>
 
-> "Stop shipping pretend features."
+<p align="center">
+  <a href="https://www.npmjs.com/package/@vibecheck/mcp-server"><img alt="npm version" src="https://img.shields.io/npm/v/@vibecheck/mcp-server?style=flat-square&color=CB3837&logo=npm" /></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
+</p>
+
+---
+
+## What is this?
+
+The VibeCheck MCP Server provides AI agents (like Claude, Cursor, Windsurf) with tools to prevent hallucinations in generated code. It integrates directly with MCP-compatible clients to:
+
+- **Block ghost routes** - Prevent AI from referencing API endpoints that don't exist
+- **Validate environment variables** - Ensure env vars exist before they're used
+- **Enforce file locks** - Protect critical files from AI modification
+- **Generate truthpacks** - Create a source of truth from your codebase
+- **Provide smart context** - Give AI accurate information about your project
+
+---
 
 ## Installation
 
 ```bash
-npm install -g @vibecheckai/cli
+# npm
+npm install -g @vibecheck/mcp-server
+
+# pnpm
+pnpm add -g @vibecheck/mcp-server
+
+# yarn
+yarn global add @vibecheck/mcp-server
 ```
 
-## Configuration
+---
+
+## Quick Start
+
+### Cursor Integration
 
-Add to your AI IDE's MCP configuration:
+Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "vibecheck": {
-      "command": "npx",
-      "args": ["@vibecheckai/cli", "mcp"]
+      "command": "vibecheck-mcp"
     }
   }
 }
 ```
 
-See [MCP-QUICK-START.md](../docs/MCP-QUICK-START.md) for editor-specific setup.
+### Claude Desktop
 
-## Development
+Add to your Claude MCP settings (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "vibecheck": {
+      "command": "vibecheck-mcp"
+    }
+  }
+}
+```
+
+### CLI Usage
 
 ```bash
-cd mcp-server
-npm install
-npm start
+# Start with stdio (default, for Cursor/Claude)
+vibecheck-mcp
+
+# Start HTTP server (for custom integrations)
+vibecheck-mcp --http --port 3001
+
+# Start WebSocket server (for real-time connections)
+vibecheck-mcp --websocket --port 3002
+
+# Show help
+vibecheck-mcp --help
 ```
 
 ---
 
-## Core MCP Tools (v4.0)
+## Available Tools
 
-These are the primary tools available via MCP:
+### Truthpack Tools
 
 | Tool | Description |
 |------|-------------|
-| `vibecheck_audit` | 🔍 Static analysis - routes, secrets, contracts |
-| `vibecheck_ship` | 🚀 Verdict engine - SHIP / WARN / BLOCK |
-| `vibecheck_prove` | 🔬 Full proof loop: audit → reality → ship |
-| `vibecheck_fix` | 🛠️ Mission-based auto-fix with safety gates |
-| `vibecheck_reality` | 🧪 Browser-based runtime verification |
-| `vibecheck_forge` | 📝 Generate AI IDE rules (.cursorrules, .windsurf) |
-| `vibecheck_shield` | 🛡️ Agent Firewall controls |
-| `vibecheck_doctor` | 🏥 Environment health check |
-| `vibecheck_checkpoint` | 📍 Snapshot & restore, baseline comparison |
-| `vibecheck_polish` | ✨ Production polish - final cleanup |
+| `truthpack_generate` | Scan codebase and generate truthpack (routes, env, auth, contracts) |
+| `truthpack_query` | Query truthpack for specific information |
+| `truthpack_validate` | Validate truthpack against current codebase |
+| `truthpack_routes` | Get API routes with filtering |
+| `truthpack_env` | Get environment variables (required/optional) |
 
----
+### Firewall Tools
 
-## Shield (Agent Firewall) Tools
+| Tool | Description |
+|------|-------------|
+| `firewall_evaluate` | Full evaluation with evidence resolution |
+| `firewall_quick_check` | Fast hallucination check |
+| `firewall_get_tier` | Get confidence tier for a rule |
+| `firewall_should_block` | Check if tier should block |
+| `firewall_tier_stats` | Get statistics by confidence tier |
+| `firewall_set_mode` | Set mode (observe/enforce/lockdown) |
 
-Control the Agent Firewall via MCP:
+### Context Tools
 
 | Tool | Description |
 |------|-------------|
-| `vibecheck_shield_status` | Get firewall status |
-| `vibecheck_shield_enforce` | Enable enforcement mode |
-| `vibecheck_shield_observe` | Enable observe-only mode |
-| `vibecheck_shield_lock` | Hard lockdown (all rules enforced) |
-| `vibecheck_shield_unlock` | Release lock |
-| `vibecheck_shield_verify` | Verify claims/prompts |
+| `context_gather` | Gather AI context for a coding task |
+| `context_file` | Get context for a specific file |
+| `context_smart` | Smart context based on task description |
 
----
+### Validation Tools
 
-## Intent & Approval Tools
+| Tool | Description |
+|------|-------------|
+| `validate_code` | Validate generated code against truthpack |
+| `validate_imports` | Check import statements |
+| `validate_api_calls` | Verify API endpoint usage |
 
-For declaring AI intent and approving changes:
+### Intent (ISL) Tools
 
 | Tool | Description |
 |------|-------------|
-| `vibecheck_intent_start` | 🎯 Declare intent before making changes |
-| `vibecheck_intent_check` | ✅ Check if changes align with stated intent |
-| `vibecheck_intent_complete` | ✅ Complete step and generate proof artifact |
-| `vibecheck_approve` | 👍 Review and approve session changes |
+| `intent_set` | Set current coding intent/spec |
+| `intent_get` | Get active intent |
+| `intent_clear` | Clear current intent |
+| `intent_validate` | Validate code against intent |
 
----
+### Hook Tools
+
+| Tool | Description |
+|------|-------------|
+| `hook_pre_generation` | Pre-generation checks with enhanced context |
+| `hook_post_generation` | Validate generated code for issues |
+| `hook_file_write` | Validate file write operations |
+
+### Lock Tools
 
-## Checkpoint Tools
+| Tool | Description |
+|------|-------------|
+| `lock_check` | Check if file/folder is locked |
+| `lock_list` | Get all locked files/folders |
 
-Pre-write validation and time machine:
+### Forge Tools
 
 | Tool | Description |
 |------|-------------|
-| `vibecheck_checkpoint` | 🛡️ Validate code before writing - blocks on issues |
-| `vibecheck_checkpoint_status` | 📊 Get current checkpoint status |
-| `vibecheck_checkpoint_restore` | ⏪ Restore to a previous checkpoint |
-| `vibecheck_checkpoint_compare` | 📈 Compare baseline vs current |
+| `forge_generate` | Generate AI context rules for .cursor/rules |
+| `forge_scan` | Scan codebase for rule generation |
 
----
+### DocGuard Tools
 
-## Report & Artifact Tools
+| Tool | Description |
+|------|-------------|
+| `docguard_check` | Check documentation quality |
+| `docguard_validate` | Validate docs against code |
 
-Generate outputs and evidence:
+### Translator Tools
 
 | Tool | Description |
 |------|-------------|
-| `vibecheck_packs_evidence` | 📦 Bundle videos, traces, screenshots |
-| `vibecheck_packs_report` | 📄 Generate HTML/MD/SARIF reports |
-| `vibecheck_packs_graph` | 📊 Proof graph visualization |
-| `vibecheck_seal` | 🏆 Generate ship badge and attestation |
+| `translate_nl_to_isl` | Convert natural language to ISL spec |
+| `translate_isl_to_checks` | Convert ISL to validation checks |
 
 ---
 
-## Example Usage
+## Confidence Tiers
 
-### Run Analysis
+The firewall uses three confidence tiers:
 
-```json
-{
-  "tool": "vibecheck_audit",
-  "arguments": {
-    "path": ".",
-    "profile": "full"
-  }
-}
-```
+| Tier | Confidence | Behavior |
+|------|------------|----------|
+| `hard_block` | High | Ghost routes, missing env vars → **Always blocks** |
+| `soft_block` | Medium | Dynamic routes, patterns → **Blocks in enforce mode** |
+| `warn` | Low | Style issues, best practices → **Warning only** |
 
-### Get Ship Verdict
+---
 
-```json
-{
-  "tool": "vibecheck_ship",
-  "arguments": {
-    "path": "."
-  }
-}
-```
+## Environment Variables
 
-### Full Proof Loop
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VIBECHECK_MODE` | Mode (local/cloud/hybrid) | `local` |
+| `VIBECHECK_TRANSPORT` | Transport (stdio/http/websocket) | `stdio` |
+| `VIBECHECK_PORT` | Port for HTTP/WS | `3001` |
+| `VIBECHECK_HOST` | Host for HTTP/WS | `localhost` |
+| `VIBECHECK_PROJECT_ROOT` | Project root path | `process.cwd()` |
 
-```json
-{
-  "tool": "vibecheck_prove",
-  "arguments": {
-    "url": "http://localhost:3000",
-    "maxFixRounds": 3
-  }
-}
-```
+---
 
-### Runtime Verification
+## Example Usage
+
+Once the MCP server is connected, AI agents can use tools like:
 
-```json
-{
-  "tool": "vibecheck_reality",
-  "arguments": {
-    "url": "http://localhost:3000",
-    "headed": false,
-    "maxPages": 18,
-    "maxDepth": 2
-  }
-}
 ```
+User: Add a new API endpoint for user profiles
 
-### AI-Powered Fixes
+AI (using truthpack_routes): Let me check existing routes...
+   Found 15 routes. Similar patterns: GET /api/v1/users/:id
 
-```json
-{
-  "tool": "vibecheck_fix",
-  "arguments": {
-    "apply": true,
-    "autopilot": false,
-    "maxMissions": 8
-  }
-}
+AI (using hook_pre_generation): Running pre-generation checks...
+   ✓ No conflicts with existing routes
+   ✓ Auth patterns identified
+
+AI: I'll create GET /api/v1/users/:id/profile following your existing patterns...
 ```
 
-### Generate IDE Rules
+---
 
-```json
-{
-  "tool": "vibecheck_forge",
-  "arguments": {
-    "format": "cursor",
-    "enhanced": true
-  }
-}
+## Development
+
+```bash
+# Clone the monorepo
+git clone https://github.com/vibecheckai/vibecheck.git
+cd vibecheck
+
+# Install dependencies
+pnpm install
+
+# Build MCP server
+pnpm --filter @vibecheck/mcp-server build
+
+# Run tests
+pnpm --filter @vibecheck/mcp-server test
+
+# Start in dev mode
+pnpm --filter @vibecheck/mcp-server dev
 ```
 
 ---
 
-## Resources
+## Related Packages
 
-- `vibecheck://rules` - Generated AI rules
-- `vibecheck://truthpack` - Repo reality index
-- `vibecheck://status` - Server status and health
+- [vibecheck-ai](https://www.npmjs.com/package/vibecheck-ai) - CLI tool
+- [VibeCheck VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Vibecheck-AI.vibecheck-ai) - VS Code integration
 
 ---
 
-## Documentation
+## Changelog
+
+### v1.2.0
+- **Enhanced Tool Set** - All MCP tools verified and tested
+- **Improved Firewall** - Better confidence tier evaluation
+- **Context Tools** - Smarter context gathering for AI agents
+- **Performance** - Faster truthpack generation and validation
+- **Stability** - Various bug fixes and improvements
 
-- [MCP Quick Start](../docs/MCP-QUICK-START.md)
-- [Full CLI Documentation](../docs/CLI-REFERENCE.md)
-- [Agent Firewall Spec](../docs/AGENT_FIREWALL_V2_SPEC.md)
+### v1.1.1
+- Bug fixes and stability improvements
+
+### v1.1.0
+- Added confidence tiers (hard_block, soft_block, warn)
+- Added tier statistics tool
+- Improved firewall evaluation
+- Added DocGuard and Translator tools
+
+### v1.0.0
+- Initial release
+- Truthpack management tools
+- Firewall evaluation
+- Context gathering
+- ISL (Intent Specification Language) support
 
 ---
 
-## Privacy & Trust
+## License
+
+MIT © VibeCheck Team
+
+---
 
-- Runs locally
-- Artifacts saved to `.vibecheck/`
-- No upload unless you explicitly export/share
+<p align="center">
+  <a href="https://vibecheckai.dev">Website</a> •
+  <a href="https://x.com/VibeCheck_AI">Twitter</a>
+</p>