Vibe Coder MCP Server

Vibe Coder is an MCP (Model Context Protocol) server designed to supercharge your AI assistant (like Cursor, Cline AI, or Claude Desktop) with powerful tools for software development. It helps with research, planning, generating requirements, creating starter projects, and more!

🆕 What's New in Version 0.3.5

🎉 Latest Release - Enhanced CLI, REPL, and Parameter Extraction

Major Improvements:

• ✨ Complete Hybrid Matcher Overhaul: All 15 MCP tools now have comprehensive parameter extraction
• 🚀 CLI/REPL Experience: Interactive confirmations, job status polling with visual progress
• 🔧 Fixed Critical Bugs: Task-list-generator auto-generates user stories, multi-turn conversations work flawlessly
• 📊 Better Tool Matching: Multi-strategy approach (keyword 35%, pattern 30%, semantic 15%, LLM 20%)
• ⚡ TypeScript Strict Mode: Zero any types, all explicit typing, production-grade code quality

User Experience Enhancements:

• Low-confidence matches now prompt for user confirmation
• Visual progress indicators for long-running jobs
• Cleaner output with JSON log filtering in interactive mode
• Session persistence across commands
• Enhanced error messages and validation feedback

Previous Notable Releases

Version 0.3.1 - Global Installation & Synchronization

• Fixed global/local version synchronization issues
• Enhanced clean build process for installations
• Improved packaging workflow for NPM publication

Version 0.2.8 - CLI Interactive Mode

• Fixed configuration persistence in interactive mode
• Enhanced project root detection for CLI users
• Improved context-aware configuration

Version 0.2.3 - Interactive REPL & Setup Wizard

• Interactive REPL Mode with chat-style interface and session persistence
• Enhanced Setup Wizard with automatic first-run detection
• Configuration Templates in src/config-templates/
• Performance Improvements with optimized memory usage
• Unified CLI Binary - single vibe command for all operations

🚀 Quick Start

# Install globally (recommended)
npm install -g vibe-coder-mcp@latest

# Run setup wizard on first use
vibe --setup

# Or use instantly with npx (no installation)
npx vibe-coder-mcp@latest --setup

The setup wizard will:

1. ✅ Configure your OpenRouter API key
2. ✅ Set up project directories
3. ✅ Create configuration files from templates
4. ✅ Validate your environment
5. ✅ Get you ready to use all features!

📦 Installation

# Recommended: Install globally for the 'vibe' command
npm install -g vibe-coder-mcp@latest

# Or run instantly without installation
npx vibe-coder-mcp@latest

Installation Methods

Global Installation (Recommended)

npm install -g vibe-coder-mcp@latest

# Use the 'vibe' command anywhere
vibe                                    # Start MCP server
vibe "create a PRD for a todo app"     # CLI mode
vibe --interactive                     # Interactive REPL mode
vibe --setup                           # Setup wizard

Quick Run with npx

# No installation needed
npx vibe-coder-mcp@latest
npx vibe-coder-mcp@latest "research React best practices"

Local Project Installation

npm install vibe-coder-mcp
npx vibe-coder-mcp "map the codebase structure"

Command Line Usage

# MCP Server Mode (for Claude Desktop, Cursor, etc.)
vibe                                    # Start with stdio transport
vibe --sse                             # Start with Server-Sent Events

# CLI Mode - Natural Language Commands
vibe "research modern JavaScript frameworks"
vibe "create a PRD for an e-commerce platform"
vibe "map the codebase structure" --json
vibe "generate user stories for auth system"

# Interactive REPL Mode
vibe --interactive                     # Chat interface with context retention

# Configuration
vibe --setup                           # Run setup wizard
vibe --help                            # Show all options
vibe --version                         # Show version

Interactive Mode Features:

• Chat-style conversation with context retention
• Live tool execution with progress indicators
• Session persistence and history
• Markdown rendering support
• Multiple themes and customization
• Slash commands for quick actions

🎯 MCP Client Integration (Claude Desktop, Cursor, Cline AI)

Quick Integration Guide

Vibe-Coder MCP integrates seamlessly with any MCP-compatible client. Here's how to configure it:

Option 1: Using NPX (Recommended)

In your MCP client's server configuration dialog:

• Server Name: vibe-coder-mcp
• Command/URL: npx
• Arguments: vibe-coder-mcp
• Environment Variables:
  • OPENROUTER_API_KEY: Your OpenRouter API key (required)
  • VIBE_PROJECT_ROOT: /path/to/your/project (required)
  • LOG_LEVEL: info (optional)
  • NODE_ENV: production (optional)

Option 2: Global Installation

# First install globally
npm install -g vibe-coder-mcp

Then configure:

• Command/URL: vibe
• Arguments: (leave empty)
• Environment Variables: Same as Option 1

Option 3: Node with Full Path

• Command/URL: node
• Arguments: /path/to/node_modules/vibe-coder-mcp/build/index.js
• Environment Variables: Same as Option 1

Claude Desktop Specific Configuration

For Claude Desktop users, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key",
        "VIBE_PROJECT_ROOT": "/path/to/your/project",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

See example_claude_desktop_config.json for a complete example.

Available Tools After Integration

Once configured, your MCP client will have access to:

• vibe-task-manager: AI-native task management with RDD methodology
• research-manager: Deep research using Perplexity integration
• map-codebase: Advanced codebase analysis (35+ languages)
• curate-context: Intelligent context curation for AI development
• generate-prd: Product requirements document generator
• generate-user-stories: User story generator
• generate-task-list: Task list generator
• generate-fullstack-starter-kit: Project scaffolding tool
• run-workflow: Multi-step workflow execution

Testing Your Integration

After configuration, test by asking your AI assistant:

• "Use vibe to research React best practices"
• "Map the codebase for this project"
• "Generate a PRD for a task management app"

🆕 Unified Project Root Configuration

Zero Configuration for CLI Users

# Automatic project detection - just run from your project!
cd /path/to/your/project
vibe "map the codebase structure"

Simple Configuration for MCP Clients

{
  "env": {
    "OPENROUTER_API_KEY": "your_key_here",
    "VIBE_PROJECT_ROOT": "/path/to/your/project"
  }
}

• One Variable: VIBE_PROJECT_ROOT replaces multiple directory configs
• Auto-Detection: CLI automatically detects project root
• Backward Compatible: Legacy variables still supported

🔧 Environment Configuration

Required: You need an OpenRouter API key to use Vibe Coder MCP.

Get Your OpenRouter API Key

1. Visit openrouter.ai
2. Create an account if you don't have one
3. Navigate to API Keys section
4. Create a new API key and copy it

Set Up Environment Variables

Option 1: Using Setup Wizard (Recommended for v0.2.3+)

# Run the interactive setup wizard
vibe --setup

# The wizard will:
# • Configure your OpenRouter API key
# • Set up project directories
# • Create configuration files
# • Validate your setup

Option 2: Environment Variables

# Set your OpenRouter API key
export OPENROUTER_API_KEY="your_api_key_here"

# Optional: Set custom directories
export VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
export VIBE_PROJECT_ROOT="/path/to/your/project"

# Legacy variables (still supported for backward compatibility)
export CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"
export VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"

Option 3: Create .env file (templates provided in v0.2.3+) Create a .env file in your working directory (or copy from src/config-templates/.env.template):

# Required: Your OpenRouter API key
OPENROUTER_API_KEY="your_api_key_here"