Vibe Check Enhanced MCP Server

Project-agnostic constitutional AI system with file-based rules, automatic detection, and per-project isolation.

---

Note: This is an enhanced fork of the original vibe-check-mcp-server by Pruthvi Bhat, tailored for local deployment with file-based constitutional rules and project-agnostic workflows.

---

🚀 What Is This?

This enhanced version of Vibe Check MCP provides:

• ✅ File-Based Constitutional Rules - JSON-based rules with inheritance (Base → Project → Session)
• ✅ Automatic Project Detection - Zero manual configuration, auto-detects project name from directory path
• ✅ Per-Project Isolation - Each project gets its own history-{projectName}.json and vibe-log-{projectName}.json
• ✅ Metacognitive Vibe Checking - Catch tunnel vision before cascading errors (from original vibe-check)
• ✅ Pattern Learning - Record mistakes and solutions for institutional memory
• ✅ Hot Reload (Optional) - Live rule updates during development without restart
• ✅ Pre-Flight Validation - Catch configuration errors before runtime

---

🎯 Key Differences from Original

Feature	Original vibe-check-mcp	This Enhanced Version
Deployment	Global npm package (npx @pv-bhat/vibe-check-mcp)	Local per-project installation
Constitutional Rules	Runtime-only (in-memory via update_constitution)	File-based with JSON inheritance
Project Awareness	Single global instance	Per-project isolation with auto-detection
Configuration	Manual environment variables	Auto-configured via init script
Storage	Generic filenames (history.json, vibe-log.json)	Project-specific filenames (history-{projectName}.json)
Setup	npm install + manual config	Zero-config with automatic setup

---

📦 Local Installation (Recommended)

This enhanced version is designed to run locally per project, not as a global npm package.

Prerequisites

• Node.js 18.x or higher
• npm 9.x or higher
• A Gemini API key (get one at https://makersuite.google.com/app/apikey)

Quick Install with Initialization Script

# 1. Clone the repository
git clone https://github.com/ArtificialMonks/vibe-workflow
cd vibe-workflow

# 2. Run initialization script (sets up everything automatically)
bash init.sh /path/to/your/project

# 3. (Optional) Generate intelligent constitutional templates from your CLAUDE.md
cd /path/to/your/project/.vibe-check/enhanced-mcp-server
npx tsx scripts/intelligent-constitution-generator.ts /path/to/your/project

# 4. Add your Gemini API key to .mcp.json (if not entered during init)
# 5. Restart Claude Code

What Gets Installed

The init script creates a complete, production-ready installation:

1. Enhanced MCP Server (.vibe-check/enhanced-mcp-server/)

• ✅ Full TypeScript source code (src/)
• ✅ Compiled JavaScript ready to run (build/)
• ✅ All helper scripts for intelligent generation
• ✅ Complete package with dependencies installed

2. Base Constitutional Rules (.vibe-check/shared/) 🆕

• ✅ 12 foundational rules that apply to ALL projects
  • 5 CRITICAL rules (Vitest-only, NestJS 10.4.20, pg.Pool, security, deployment)
  • 5 HIGH priority rules (TypeScript strict, testing, error handling, code review, accessibility)
  • 2 MEDIUM rules (documentation, performance)
• ✅ JSON Schema for rule validation (VS Code integration)
• ✅ Inheritance system - Your project rules extend base rules

3. Generic Work-Type Templates (.vibe-check/constitutions/)

• ✅ 7 project-agnostic templates ready to customize:
  • api-development.json - REST API standards
  • database-migrations.json - Schema change patterns
  • testing.json - Test coverage and quality
  • deployment.json - Production deployment safety
  • integration-development.json - Third-party integrations
  • ui-components.json - Frontend component standards
  • workflow-automation.json - Browser automation patterns

4. Project-Specific Configuration

• ✅ constitutional-rules.json - Your project's custom rules
• ✅ .mcp.json - MCP server configuration with absolute paths
• ✅ Auto-created on first use: history-{projectName}.json, vibe-log-{projectName}.json

Intelligent Constitutional Generation (Optional)

After initialization, you can auto-generate customized rules:

cd /path/to/your/project/.vibe-check/enhanced-mcp-server
npx tsx scripts/intelligent-constitution-generator.ts /path/to/your/project

What it does:

• 🧠 Analyzes codebase - Scans package.json, CLAUDE.md, directory structure
• 🧠 Discovers work types - Detects ML, blockchain, payments, auth, realtime, GraphQL
• 🧠 Customizes templates - Merges generic rules with your project-specific patterns
• 🧠 Generates new templates - Creates templates for discovered specialized domains
• 🧠 Extracts rules from CLAUDE.md - Maps sections to work-type templates automatically
• 🧠 100% project-aware - Complete constitutional system tailored to YOUR project

Example output:

Analyzed codebase: NestJS, React, Prisma, Stripe detected
Discovered 3 new work types: payment-processing, auth-security, realtime-communication
Extracted 89 rules from CLAUDE.md
Customized 7 templates with project-specific rules
Generated 3 new templates
Total: 10 templates with 168 rules ✅

See SETUP.md for detailed installation guide and examples/saas-starter/ for a complete working example.

---

🏗️ Directory Structure After Installation

After running init.sh, your project will have this structure:

your-project/
├── .vibe-check/                           # Created by init.sh
│   ├── constitutional-rules.json          # ✅ Project-specific rules (auto-generated)
│   │
│   ├── shared/                            # ✅ Base rules (copied from template/)
│   │   ├── base-constitutional-rules.json # 12 universal foundational rules
│   │   ├── schema/
│   │   │   └── constitutional-rules.schema.json  # JSON Schema for validation
│   │   └── README.md                      # Documentation
│   │
│   ├── constitutions/                     # ✅ Work-type templates (copied from template/)
│   │   ├── api-development.json           # REST API standards
│   │   ├── database-migrations.json       # Schema change patterns
│   │   ├── testing.json                   # Test coverage and quality
│   │   ├── deployment.json                # Production deployment safety
│   │   ├── integration-development.json    # Third-party integrations
│   │   ├── ui-components.json             # Frontend component standards
│   │   ├── workflow-automation.json        # Browser automation patterns
│   │   └── README.md                      # Templates guide
│   │
│   ├── enhanced-mcp-server/               # ✅ Complete MCP server (copied from template/)
│   │   ├── build/                         # Compiled JavaScript (ready to run)
│   │   ├── src/                           # TypeScript source code
│   │   ├── scripts/                       # Helper scripts
│   │   │   ├── intelligent-constitution-generator.ts
│   │   │   ├── load-work-type-constitution.ts
│   │   │   └── generate-rules-from-docs.ts
│   │   ├── node_modules/                  # Dependencies (npm install)
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── history-your-project.json          # ⏳ Auto-created on first vibe_check
│   └── vibe-log-your-project.json         # ⏳ Auto-created on first vibe_learn
│
└── .mcp.json                              # ✅ MCP configuration (auto-created by init.sh)

Legend:

• ✅ Created by init.sh during installation
• ⏳ Auto-created on first use (runtime)

---

⚙️ Configuration

Automatic Configuration (via init.sh)

The init.sh script automatically creates all configuration files with absolute paths.

You don't need to manually create these files - they're generated during installation.

1. .mcp.json (Auto-Created)

The init script creates this file with correct absolute paths:

{
  "mcpServers": {
    "pv-bhat-vibe-check-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/your-project/.vibe-check/enhanced-mcp-server/build/index.js"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GEMINI_API_KEY": "your-gemini-api-key",
        "DEFAULT_LLM_PROVIDER": "gemini",
        "DEFAULT_MODEL": "gemini-2.5-flash",
        "USE_LEARNING_HISTORY": "true",
        "VIBE_CHECK_STORAGE_DIR": "/absolute/path/to/your-project/.vibe-check",
        "VIBE_CHECK_RULES_FILE": "/absolute/path/to/your-project/.vibe-check/constitutional-rules.json",
        "VIBE_CHECK_HOT_RELOAD": "false"
      }
    }
  }
}

Note: You only need to add your Gemini API key if you didn't enter it during init.sh.

2. constitutional-rules.json (Auto-Created)

The init script creates this file with your project name:

{
  "$schema": "shared/schema/constitutional-rules.schema.json",
  "version": "1.0.0",
  "extends": ["shared/base-constitutional-rules.json"],
  "description": "Constitutional rules for your-project",
  "rules": {
    "your-project-rule-1": {
      "id": "your-project-rule-1",
      "name": "Your Project Rule Example",
      "description": "ALWAYS follow your-project-specific patterns",
      "category": "best-practices",
      "severity": "HIGH",
      "enabled": true
    }
  }
}

3. Restart Claude Code

After configuration, restart Claude Code to load the enhanced MCP server.

---

🎯 How It Works: Automatic Project Detection

The server automatically extracts your project name from the directory path:

VIBE_CHECK_STORAGE_DIR = /path/to/MY-PROJECT/.vibe-check
                                ↓ (auto-extract)
PROJECT_NAME = "MY-PROJECT"
                                ↓
history-MY-PROJECT.json     ✅ Auto-created
vibe-log-MY-PROJECT.json    ✅ Auto-created

No manual configuration needed! Each project automatically gets isolated storage.

---

📚 File-Based Constitutional Rules with Inheritance

Base Rules (12 Universal Foundational Rules)

Located in .vibe-check/shared/base-constitutional-rules.json:

CRITICAL Rules (5):

1. vitest-only - Always use Vitest for testing (NEVER Jest)
2. nestjs-version-pinning - Use NestJS 10.4.20 exactly (NEVER 11.x)
3. database-with-pg-pool - Use pg.Pool for PostgreSQL (NEVER TypeORM in NestJS)
4. security-best-practices - Follow OWASP security guidelines
5. deployment-safety - Test in staging before production

HIGH Priority Rules (5): 6. typescript-strict-mode - Enable TypeScript strict mode 7. test-before-commit - Run tests before committing code 8. explicit-error-handling - Always handle errors explicitly 9. code-review-standards - Require code review before merging 10. accessibility-requirements - Meet WCAG 2.1 Level AA standards

MEDIUM Priority Rules (2): 11. documentation-requirements - Document public APIs and decisions 12. performance-considerations - Profile before optimizing

These rules apply to ALL projects and are inherited automatically.

Project Rules (Your Custom)

Add project-specific rules in .vibe-check/constitutional-rules.json:

{
  "extends": ["shared/base-constitutional-rules.json"],
  "rules": {
    "api-versioning": {
      "id": "api-versioning",
      "name": "REST API Versioning",
      "description": "ALWAYS version API endpoints as /api/v1/...",
      "category": "architecture",
      "severity": "CRITICAL",
      "enabled": true
    }
  }
}

Inheritance Chain:

Base Rules (12 universal)
    ↓ extends
Project Rules (your custom rules)
    ↓ loaded into
Session Constitution (runtime)

---

🛠️ MCP Tools

vibe_check - Metacognitive Review

Catch tunnel vision and prevent cascading errors:

vibe_check({
  goal: "Implement user authentication",
  plan: "1. Add JWT middleware 2. Create login endpoint 3. Test",
  uncertainties: ["Should we use OAuth or JWT?"],
  sessionId: "auth-feature-001"
})

// Returns thoughtful critique:
// "Have you considered password reset flow?
//  What about rate limiting on login attempts?"

vibe_learn - Pattern Capture

Record mistakes and solutions for future prevention:

vibe_learn({
  type: "mistake",
  mistake: "Forgot to add database indexes before deploying",
  category: "Premature Implementation",
  solution: "Always run performance validation before production"
})

check_constitution / update_constitution

Manage session-specific rules dynamically (inherited from original vibe-check).

---

🧪 Validation & Testing

Pre-Flight Validation

Catch configuration errors before runtime:

cd .vibe-check/enhanced-mcp-server
npm run validate

# Output:
# ✅ Rules File: constitutional-rules.json
# ✅ Inheritance Chain: base → project (14 rules)
# ✅ Severity: 3 CRITICAL, 6 HIGH, 5 MEDIUM
# ✅ Validation PASSED

Hot Reload (Development)

Enable file watching for live rule updates:

"VIBE_CHECK_HOT_RELOAD": "true"

Note: Use new sessionId after hot reload to get updated rules.

---

🔧 Development

Build from Source

cd .vibe-check/enhanced-mcp-server
npm install
npm run build
npm run validate

Environment Variables

Set in .mcp.json:

• GEMINI_API_KEY - Your Gemini API key (required)
• VIBE_CHECK_STORAGE_DIR - Absolute path to .vibe-check/ directory
• VIBE_CHECK_RULES_FILE - Absolute path to constitutional-rules.json
• VIBE_CHECK_HOT_RELOAD - Enable file watching (true / false)
• DEFAULT_LLM_PROVIDER - LLM provider (gemini, openai, anthropic)
• DEFAULT_MODEL - Model name (e.g., gemini-2.5-flash)

---

🚧 Troubleshooting

Issue: "Rule set file not found"

Cause: Incorrect extends path in constitutional-rules.json

Fix:

// ✅ Correct (relative to rules file):
"extends": ["shared/base-constitutional-rules.json"]

// ❌ Wrong:
"extends": [".vibe-check/shared/base-constitutional-rules.json"]

Issue: "Validation failed"

Cause: JSON syntax error or missing required fields

Fix:

npm run validate  # See detailed error with line/column

Issue: Rules not loading in Claude Code

Cause: Stale MCP server

Fix:

1. Check .mcp.json has correct absolute paths
2. Restart Claude Code
3. Run npm run validate to verify rules

---

🙏 Acknowledgments

• Original Vibe-Check MCP: pv-bhat/vibe-check-mcp-server by Pruthvi Bhat
• Constitutional AI: Anthropic's constitutional AI research
• Model Context Protocol: Anthropic's MCP specification
• CPI Research: Chain-Pattern Interrupt (MURST)

---

📄 License

MIT License - see LICENSE file for details.

---

🔗 Links

• Original vibe-check-mcp: https://github.com/PV-Bhat/vibe-check-mcp-server
• MCP Specification: https://anthropic.com/mcp
• CPI Research Paper: http://dx.doi.org/10.13140/RG.2.2.18237.93922

---

Built with ❤️ for project-agnostic Constitutional AI workflows

Enhanced for local deployment and file-based rule management