🎯 VibeCheck MCP Server

Stop writing lazy prompts. Start shipping better code.

VibeCheck is an MCP (Model Context Protocol) server that acts as a quality gate for AI-assisted coding. It intercepts underspecified prompts and refines them into high-density, context-aware instructions — so your AI assistant produces better code with fewer iterations.

---

Why VibeCheck?

Most AI coding prompts are too vague. "Add a login page" tells your AI nothing about auth providers, styling, error handling, or scope. You end up in a loop of corrections that burns tokens and time.

VibeCheck scores your prompt, flags what's missing, detects your tech stack, suggests relevant files, and transforms it into a structured instruction with persona-specific requirements — all before a single line of code is generated.

---

Features

Feature	Description
🎯 Prompt Refinement	Transforms vague prompts into structured, actionable instructions
📊 Vibe Scoring	Scores prompts 1–100 across specificity, context, criteria, and persona alignment
🏗️ 5 Expert Personas	Default, Senior Engineer, Product Manager, Security Auditor, Performance Specialist
🔧 Tech-Stack Detection	Auto-detects Node.js, Python, and Go projects with framework identification
📦 Dependency Checking	Verifies if libraries mentioned in your prompt are actually installed
📂 Context Suggestion	Scans your project and recommends relevant files to include
🔒 Security Guardrails	Flags prompts that attempt to disable auth, hardcode secrets, or bypass validation
📝 History Tracking	Logs all refinements to .vibecheck/history.json with auto-rotation
🔄 Iterative Refinement	Feed back on a refined prompt to generate improved V2
📄 Prompt Templates	Starter templates for features, refactors, bug fixes, tests, and API endpoints

---

Quick Start

Prerequisites

• Node.js 18+
• An MCP-compatible client (Cursor, Claude Desktop, VS Code, Windsurf, etc.)

Install

# Clone the repo
git clone https://github.com/yusef1975/Vcheck.git
cd Vcheck

# Install dependencies
npm install

# Build
npm run build

Connect to Your Editor

Add VibeCheck to your MCP client configuration:

Cursor

Create or edit .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "vibecheck": {
      "command": "node",
      "args": ["/absolute/path/to/Vcheck/dist/index.js"]
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vibecheck": {
      "command": "node",
      "args": ["/absolute/path/to/Vcheck/dist/index.js"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "vibecheck": {
        "command": "node",
        "args": ["/absolute/path/to/Vcheck/dist/index.js"]
      }
    }
  }
}

Windsurf / Antigravity

Add to your MCP config file (mcp_config.json):

{
  "mcpServers": {
    "vibecheck": {
      "command": "node",
      "args": ["/absolute/path/to/Vcheck/dist/index.js"]
    }
  }
}

Tip: Replace /absolute/path/to/Vcheck with the actual path where you cloned the repo.

After adding the config, restart your editor. The tools will be available immediately.

---

Tools

refine_vibe_prompt

The core tool. Validates, scores, and transforms your prompt.

Input:  "add a login page to my nextjs app"
Output: Structured instruction with tech-stack context, persona requirements, 
        file suggestions, security checks, and a completion checklist.

Parameters:

Parameter	Type	Required	Description
prompt	string	✅	The raw prompt to refine
persona	enum	❌	Expert persona to apply
projectRoot	string	❌	Absolute path to project root
context	string	❌	Additional context to include

score_vibe

Scores a prompt 1–100 with a detailed breakdown.

Scoring Categories:

Category	Max Points
🎯 Specificity	30
📂 Context	30
✅ Acceptance Criteria	20
🏗️ Persona Alignment	20

Score Badges: ❌ LAZY (0–19) → ⚠️ WEAK (20–39) → ⚡ DECENT (40–59) → ✅ STRONG (60–79) → 🏆 ELITE (80–100)

suggest_vibe_context

Scans your project and suggests relevant files based on keyword matching.

detect_tech_stack

Auto-detects your project's runtime, frameworks, and dependencies from package.json, requirements.txt, or go.mod.

refinement_loop

Takes feedback on a previously refined prompt and generates an improved V2.

init_vibecheck

Generates a default .vibecheckrc config file, creates the .vibecheck/ directory, and updates .gitignore.

list_vibe_templates

Returns starter prompt templates:

• 🚀 New Feature — structured feature request
• 🔧 Refactor — refactoring guide
• 🐛 Bug Fix — bug report with reproduction steps
• 🧪 Test Suite — test planning template
• 🌐 API Endpoint — REST endpoint specification

---

Resources

VibeCheck exposes two MCP resources that other agents can read:

Resource URI	Description
vibecheck://history	JSON array of all prompt refinement history
vibecheck://rules	Markdown document with refinement principles and persona definitions

---

Personas

Each persona applies domain-specific expert constraints to your prompt:

Persona	Focus
🧑‍💻 Default	Clean code, SOLID principles, error handling
🏗️ Senior Engineer	Scalability, failure modes, observability, race conditions
📊 Product Manager	User impact, accessibility, analytics, i18n
🛡️ Security Auditor	Input validation, injection attacks, secrets, CORS
⚡ Performance Specialist	Profiling, caching, lazy loading, connection pooling

---

Configuration

Run init_vibecheck to generate a .vibecheckrc in your project root:

{
  "ignoredDirs": ["node_modules", ".git", "dist", "..."],
  "ignoredExtensions": [".lock", ".log", ".map", "..."],
  "maxScanFiles": 500,
  "maxScanDepth": 10,
  "customPersonas": {
    "my persona": {
      "name": "My Persona",
      "emoji": "🎨",
      "description": "A custom expert with specific constraints.",
      "expertConstraints": [
        "Always use design tokens from the shared theme.",
        "Prefer CSS Grid over Flexbox for page layouts."
      ]
    }
  }
}

---

Project Structure

src/
├── index.ts        # MCP server, tool registrations, refinement engine
├── config.ts       # .vibecheckrc loading and defaults
├── personas.ts     # 5 built-in personas + custom persona support
├── scanner.ts      # Async project scanner, context suggestion, tech-stack detection
├── scoring.ts      # Vibe Score (1–100) calculation
├── security.ts     # Security guardrail patterns
├── history.ts      # History logging with 200-entry rotation
└── templates.ts    # 5 starter prompt templates

---

Environment Variables

Variable	Description
VIBECHECK_PROJECT_ROOT	Override the default project root (falls back to cwd)

---

Development

# Watch mode (auto-recompile on changes)
npm run dev

# Build
npm run build

# Run directly
npm start

---

License

MIT — Built by yusef1975