Vibe Coder MCP is a server that supercharges AI assistants with tools for software development, research, planning, and project management.
Research & Planning: Perform deep research on technical topics, generate PRDs, user stories, task lists, and development rules.
Code Generation & Refactoring: Generate code stubs and refactor existing code snippets.
Project Scaffolding: Create full-stack starter kits with custom tech stacks.
Git Integration: Summarize Git changes.
Dependency Analysis: Analyze project dependency files.
Codebase Mapping: Map and analyze codebase structure with diagrams.
Workflow Execution: Run predefined sequences of tool calls for complex tasks.
Request Processing: Route natural language requests to appropriate tools using semantic matching.
Provides Git integration through the git-summary tool to display current Git changes and status, helping with code commit preparation
Supports creation of Mermaid diagrams in documentation, used throughout planning tools for visualizing workflows and architecture
Offers Node.js project analysis including dependency examination and project scaffolding capabilities
Integrates with Perplexity Sonar for deep technical research capabilities through the research-manager tool
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
The setup wizard will:
- ✅ Configure your OpenRouter API key
- ✅ Set up project directories
- ✅ Create configuration files from templates
- ✅ Validate your environment
- ✅ Get you ready to use all features!
📦 Installation
Installation Methods
Global Installation (Recommended)
Quick Run with npx
Local Project Installation
Command Line Usage
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
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
:
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
Simple Configuration for MCP Clients
- 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
- Visit openrouter.ai
- Create an account if you don't have one
- Navigate to API Keys section
- Create a new API key and copy it
Set Up Environment Variables
Option 1: Using Setup Wizard (Recommended for v0.2.3+)
Option 2: Environment Variables
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
):
Directory Configuration (Unified & Simplified)
🆕 Unified Configuration (Recommended)
- VIBE_PROJECT_ROOT: Single variable for all project operations (automatic detection enabled by default for CLI)
- VIBE_USE_PROJECT_ROOT_AUTO_DETECTION: Enable automatic project root detection for CLI users (default:
"true"
) - VIBE_CODER_OUTPUT_DIR: Where generated files are saved (default:
./VibeCoderOutput/
)
Legacy Configuration (Still Supported)
- CODE_MAP_ALLOWED_DIR: Security boundary for code analysis (fallback if VIBE_PROJECT_ROOT not set)
- VIBE_TASK_MANAGER_READ_DIR: Security boundary for task manager operations (fallback if VIBE_PROJECT_ROOT not set)
Auto-Detection Benefits:
- Zero Configuration: CLI users get automatic project root detection
- Context Aware: Different behavior for CLI vs MCP client usage
- Intelligent Fallbacks: 5-priority resolution chain ensures reliable operation
🔌 MCP Client Setup
Configure your AI assistant to connect to Vibe Coder MCP:
For Cursor AI / Windsurf / VS Code MCP Clients
Add this to your MCP settings (usually in settings.json
):
For Claude Desktop
Add this to your claude_desktop_config.json
:
💻 CLI Usage Guide
Vibe Coder includes a powerful command-line interface with multiple modes for direct interaction with all tools.
Interactive Setup Wizard (Enhanced in v0.2.3)
Interactive REPL Mode (NEW in v0.2.3!)
REPL Features:
- 🎯 Chat Interface: Natural conversation flow with context retention
- 📝 Multi-line Input: Use
"""
for multi-line messages - 🎨 Themes: Multiple color themes with
/theme
command - 💾 Session Management: Auto-save and resume capabilities
- 📊 Markdown Rendering: Rich text formatting in responses
- ⚡ Live Progress: Real-time execution feedback
- 🔧 Slash Commands: Quick actions like
/tools
,/history
,/save
- 🎮 Auto-completion: Tab completion for commands and tools
CLI Command Examples
Research & Analysis
Project Planning
Code Analysis & Generation
Task Management
CLI Options
Interactive REPL Commands (v0.2.3+)
Once in interactive mode (vibe --interactive
), use these commands:
File Organization
Generated files are automatically organized in VibeCoderOutput/
:
🔄 Migration Guide (v0.2.3)
Breaking Changes
None! Version 0.2.3 is fully backward compatible. All existing configurations and workflows continue to work.
Technical Improvements
- Unified CLI architecture with single entry point
- Better error handling and recovery
- Improved resource cleanup
- Enhanced type safety throughout codebase
- Memory leak prevention in long-running sessions
- CI/CD Pipeline Optimization:
- 70% faster execution (~3 minutes vs ~10 minutes)
- Focused on essential checks: type-check, lint, build
- Unit tests moved to local development workflow
- See CI/CD Guide for details
- Memory usage optimized for large codebases
- Faster first-run experience with smart detection
📚 Development Setup (Advanced)
If you want to contribute to development or run from source, follow the detailed setup guide below.
Overview & Features
Vibe Coder MCP integrates with MCP-compatible clients to provide the following capabilities:
🚀 Core Architecture
- Quad Transport Support: stdio, SSE, WebSocket, and HTTP transport protocols for maximum client compatibility
- Dynamic Port Allocation: Intelligent port management with conflict resolution and graceful degradation
- Semantic Request Routing: Intelligently routes requests using embedding-based semantic matching with sequential thinking fallbacks
- Tool Registry Architecture: Centralized tool management with self-registering tools
- Unified Communication Protocol: Agent coordination across all transport mechanisms with real-time notifications
- Session State Management: Maintains context across requests within sessions
🧠 AI-Native Task Management
- Vibe Task Manager: Production-ready task management with 99.9% test success rate and comprehensive integration (Functional but actively being enhanced)
- Natural Language Processing: 21 supported intents with multi-strategy recognition (pattern matching + LLM fallback)
- Recursive Decomposition Design (RDD): Intelligent project breakdown into atomic tasks
- Agent Orchestration: Multi-agent coordination with capability mapping, load balancing, and real-time status synchronization
- Multi-Transport Agent Support: Full integration across stdio, SSE, WebSocket, and HTTP transports
- Real Storage Integration: Zero mock code policy - all production integrations
- Artifact Parsing Integration: Seamless integration with PRD Generator and Task List Generator outputs
- Session Persistence: Enhanced session tracking with orchestration workflow triggers
- Comprehensive CLI: Natural language command-line interface with extensive functionality
🔍 Advanced Code Analysis & Context Curation
- Code Map Tool: 35+ programming language support with 95-97% token reduction optimization
- Context Curation Tool: Language-agnostic project detection with 95%+ accuracy across 35+ languages
- Intelligent Codemap Caching: Configurable caching system that reuses recent codemaps to optimize workflow performance
- Enhanced Import Resolution: Third-party integration for accurate dependency mapping
- Multi-Strategy File Discovery: 4 parallel strategies for comprehensive analysis
- Memory Optimization: Sophisticated caching and resource management
- Security Boundaries: Separate read/write path validation for secure operations
📋 Research & Planning Suite
- Research Tool: Deep research using Perplexity Sonar via OpenRouter
- Context Curation: Intelligent codebase analysis with 8-phase workflow pipeline and intelligent codemap caching for AI-driven development
- Document Generators: PRDs (
prd-generator
), user stories (user-stories-generator
), task lists (task-list-generator
), development rules (rules-generator
) - Project Scaffolding: Full-stack starter kits (
fullstack-starter-kit-generator
) with dynamic template generation - Workflow Execution: Predefined sequences of tool calls defined in
workflows.json
⚡ Performance & Reliability
- Asynchronous Execution: Job-based processing with real-time status tracking
- Performance Optimized: <200ms response times, <400MB memory usage
- Comprehensive Testing: 99.9% test success rate across 2,100+ tests with full integration validation
- Production Ready: Zero mock implementations, real service integrations
- Enhanced Error Handling: Advanced error recovery with automatic retry, escalation, and pattern analysis
- Dynamic Port Management: Intelligent port allocation with conflict resolution and graceful degradation
- Real-Time Monitoring: Agent health monitoring, task execution tracking, and performance analytics
(See "Detailed Tool Documentation" and "Feature Details" sections below for more)
Development Setup Guide
For developers who want to run from source or contribute to the project.
Step 1: Prerequisites
- Check Node.js Version:
- Open a terminal or command prompt.
- Run
node -v
- Ensure the output shows v20.0.0 or higher (required).
- If not installed or outdated: Download from nodejs.org.
- Check Git Installation:
- Open a terminal or command prompt.
- Run
git --version
- If not installed: Download from git-scm.com.
- Get OpenRouter API Key:
- Visit openrouter.ai
- Create an account if you don't have one.
- Navigate to API Keys section.
- Create a new API key and copy it.
- Keep this key handy for Step 4.
Step 2: Get the Code
- Create a Project Directory (optional):
- Open a terminal or command prompt.
- Navigate to where you want to store the project:
- Clone the Repository:
- Run:(Or use your fork's URL if applicable)
- Run:
- Navigate to Project Directory:
- Run:
- Run:
Step 3: Run the Setup Script
Choose the appropriate script for your operating system:
For Windows:
- In your terminal (still in the vibe-coder-mcp directory), run:
- Wait for the script to complete (it will install dependencies, build the project, and create necessary directories).
- If you see any error messages, refer to the Troubleshooting section below.
For macOS or Linux:
- Make the script executable:
- Run the script:
- Wait for the script to complete.
- If you see any error messages, refer to the Troubleshooting section below.
The script performs these actions:
- Checks Node.js version (v20+ required)
- Installs all dependencies via npm
- Creates necessary
VibeCoderOutput/
subdirectories - Builds the TypeScript project
- Creates configuration from templates if not present (v0.2.3+)
- Sets executable permissions (on Unix systems)
Note: The setup process is now faster (v0.2.3+) with optimized dependency installation and simplified build process.
Step 4: Configure Environment Variables
New in v0.2.3: Configuration templates are provided in src/config-templates/
for easy setup.
Option A: Use the Setup Wizard (Recommended)
The wizard will guide you through configuration and create all necessary files.
Option B: Manual Configuration
- Copy templates (if not already done by setup script):
- Edit
.env
file with your configuration: - Configure Output Directory (Optional):
- To change where generated files are saved (default is
VibeCoderOutput/
inside the project), add this line to your.env
file: - Replace the path with your preferred absolute path. Use forward slashes (
/
) for paths. If this variable is not set, the default directory (VibeCoderOutput/
) will be used.
- To change where generated files are saved (default is
- 🆕 Configure Unified Project Root (Recommended):
- To set up the new unified project root configuration, add this line to your
.env
file: - Replace the path with the absolute path to your project's root directory.
- Benefits: Single configuration variable for all tools (Code Map Generator, Task Manager, Context Curator)
- Auto-Detection: For CLI users, project root is automatically detected from the current working directory
- Backward Compatibility: Legacy variables are still supported if you prefer separate configurations
- To set up the new unified project root configuration, add this line to your
- Legacy Directory Configuration (Optional):
- If you prefer separate directory configurations, you can still use the original variables:
- Note: These variables work as fallbacks if
VIBE_PROJECT_ROOT
is not set - Security: All variables work with the strict filesystem security implementation
- If you prefer separate directory configurations, you can still use the original variables:
- Review Other Settings (Optional):
- You can add other environment variables supported by the server, such as
LOG_LEVEL
(e.g.,LOG_LEVEL=debug
) orNODE_ENV
(e.g.,NODE_ENV=development
).
- You can add other environment variables supported by the server, such as
- Save the
.env
File.
Step 5: Integrate with Your AI Assistant (MCP Settings)
This crucial step connects Vibe Coder to your AI assistant by adding its configuration to the client's MCP settings file.
5.1: Locate Your Client's MCP Settings File
The location varies depending on your AI assistant:
- Cursor AI / Windsurf / RooCode (VS Code based):
- Open the application.
- Open the Command Palette (
Ctrl+Shift+P
orCmd+Shift+P
). - Type and select
Preferences: Open User Settings (JSON)
. - This opens your
settings.json
file where themcpServers
object should reside.
- Cline AI (VS Code Extension):
- Windows:
%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
- macOS:
~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Linux:
~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- (Note: If using standard VS Code instead of Cursor, replace
Cursor
withCode
in the path)
- Windows:
- Claude Desktop:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
- Windows:
5.2: Add the Vibe Coder Configuration
- Open the settings file identified above in a text editor.
- Find the
"mcpServers": { ... }
JSON object. If it doesn't exist, you may need to create it (ensure the overall file remains valid JSON). For example, an empty file might become{"mcpServers": {}}
. - Add the following configuration block inside the curly braces
{}
of themcpServers
object. If other servers are already listed, add a comma,
after the previous server's closing brace}
before pasting this block. - CRUCIAL: Replace all placeholder paths (like
/path/to/your/vibe-coder-mcp/...
) with the correct absolute paths on your system where you cloned the repository. Use forward slashes/
for paths, even on Windows (e.g.,C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js
). Incorrect paths are the most common reason the server fails to connect. - Save the settings file.
- Completely close and restart your AI assistant application (Cursor, VS Code, Claude Desktop, etc.) for the changes to take effect.
Step 6: Test Your Configuration
- Start Your AI Assistant:
- Completely restart your AI assistant application.
- Test a Simple Command:
- Type a test command like:
Research modern JavaScript frameworks
- Type a test command like:
- Check for Proper Response:
- If working correctly, you should receive a research response.
- If not, check the Troubleshooting section below.
AI Agent Integration
The Vibe Coder MCP system includes comprehensive system instructions designed to help AI agents and MCP clients effectively leverage the full ecosystem. These instructions provide detailed guidance on tool usage, integration patterns, and best practices.
System Instructions File
The VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
file contains comprehensive guidance for AI agents on how to use the Vibe Coder MCP ecosystem effectively. This file should be integrated into your AI development environment to train your agents on optimal tool usage.
Platform-Specific Integration
Claude Desktop
Place the system instructions in your project's system instructions or custom instructions:
- Open Claude Desktop
- Navigate to project settings
- Add the contents of
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
to the system instructions field - Save and restart Claude Desktop
ChatGPT
Add the system instructions to your custom instructions or project settings:
- Open ChatGPT settings
- Navigate to custom instructions or project configuration
- Paste the contents of
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
- Save the configuration
VS Code Extensions (Cline, Roo Coder, Augment)
Integrate the system instructions into your extension's configuration:
- Cline: Place in system instructions or memories section
- Roo Coder: Add to system instructions or rules folder
- Augment: Place in system instructions or memories
- Other VS Code forks: Place in system instructions or rules folder with "always active" setting
General MCP Clients
For other MCP-compatible clients:
- Locate the system instructions or rules configuration
- Add the contents of
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
- Set as "always active" or "persistent" if the option is available
- Restart the client to apply changes
Key Integration Benefits
- Comprehensive Tool Knowledge: Agents learn about all 15+ available tools and their capabilities
- Workflow Orchestration: Guidance on chaining tools together for complex development workflows
- Job Polling Protocol: Critical instructions for handling asynchronous operations correctly
- Best Practices: Performance optimization and error handling strategies
- Integration Patterns: Common workflows for research, planning, and implementation
Usage Examples
Once integrated, your AI agents will be able to:
Verification
To verify successful integration:
- Ask your AI agent about available Vibe Coder tools
- Request a workflow that uses multiple tools in sequence
- Check that the agent follows proper job polling protocols
- Confirm that outputs are saved to the correct directories
🎯 Unified CLI Architecture (v0.2.3+)
The new unified CLI (unified-cli.ts
) provides a single entry point for all Vibe Coder operations:
Benefits of Unified CLI:
- Single binary for all operations (
vibe
) - Consistent command interface
- Shared configuration management
- Seamless mode switching
- Better resource utilization
Project Architecture
The Vibe Coder MCP server follows a modular, TypeScript ESM architecture with dual transport support and comprehensive tool ecosystem:
Directory Structure
Semantic Routing System
Vibe Coder uses a sophisticated routing approach to select the right tool for each request:
Tool Registry Pattern
The Tool Registry is a central component for managing tool definitions and execution:
Sequential Thinking Process
The Sequential Thinking mechanism provides LLM-based fallback routing:
Session State Management
Workflow Execution Engine
The Workflow system enables multi-step sequences:
Workflow Configuration
Workflows are defined in the workflows.json
file located in the root directory of the project. This file contains predefined sequences of tool calls that can be executed with a single command.
File Location and Structure
- The
workflows.json
file must be placed in the project root directory (same level as package.json) - The file follows this structure:
Parameter Templates
Workflow step parameters support template strings that can reference:
- Workflow inputs:
{workflow.input.paramName}
- Previous step outputs:
{steps.stepId.output.content[0].text}
Triggering Workflows
Use the run-workflow
tool with:
Detailed Tool Documentation
Each tool in the src/tools/
directory includes comprehensive documentation in its own README.md file. These files cover:
- Tool overview and purpose
- Input/output specifications
- Workflow diagrams (Mermaid)
- Usage examples
- System prompts used
- Error handling details
Refer to these individual READMEs for in-depth information:
src/tools/fullstack-starter-kit-generator/README.md
src/tools/prd-generator/README.md
src/tools/research/README.md
src/tools/rules-generator/README.md
src/tools/task-list-generator/README.md
src/tools/user-stories-generator/README.md
src/tools/workflow-runner/README.md
src/tools/map-codebase/README.md
Tool Categories
Analysis & Information Tools
- Code Map Tool (
map-codebase
): Scans a codebase to extract semantic information (classes, functions, comments) and generates either a human-readable Markdown map with Mermaid diagrams or a structured JSON representation with absolute file paths for imports and enhanced class property information. - Context Curation Tool (
curate-context
): Intelligent codebase analysis and context package curation with 8-phase workflow pipeline, intelligent codemap caching, language-agnostic project detection supporting 35+ programming languages, and multi-strategy file discovery for AI-driven development tasks. - Research Tool (
research
): Performs deep research on technical topics using Perplexity Sonar, providing summaries and sources.
Planning & Documentation Tools
- Rules Generator (
rules-generator
): Creates project-specific development rules and guidelines. - PRD Generator (
prd-generator
): Generates comprehensive product requirements documents. - User Stories Generator (
user-stories-generator
): Creates detailed user stories with acceptance criteria. - Task List Generator (
task-list-generator
): Builds structured development task lists with dependencies.
Project Scaffolding Tool
- Fullstack Starter Kit Generator (
fullstack-starter-kit-generator
): Creates customized project starter kits with specified frontend/backend technologies, including basic setup scripts and configuration.
Workflow & Orchestration
- Workflow Runner (
run-workflow
): Executes predefined sequences of tool calls for common development tasks.
Generated File Storage
By default, outputs from the generator tools are stored for historical reference in the VibeCoderOutput/
directory within the project. This location can be overridden by setting the VIBE_CODER_OUTPUT_DIR
environment variable in your .env
file or AI assistant configuration.
Security Boundaries for Read and Write Operations
For security reasons, the Vibe Coder MCP tools maintain separate security boundaries for read and write operations with a security-by-default approach:
- Read Operations:
- Code Map Tool: Only reads from directories explicitly authorized through the
CODE_MAP_ALLOWED_DIR
environment variable - Vibe Task Manager: Only reads from directories authorized through the
VIBE_TASK_MANAGER_READ_DIR
environment variable (defaults toprocess.cwd()
) - Security Mode: The Vibe Task Manager defaults to 'strict' security mode, which prevents access to system directories like
/private/var/spool/postfix/
,/System/
, and other unauthorized paths - Filesystem Security: Comprehensive blacklist enforcement and permission checking prevent EACCES errors and unauthorized file access
- Code Map Tool: Only reads from directories explicitly authorized through the
- Write Operations: All output files are written to the
VIBE_CODER_OUTPUT_DIR
directory (or its subdirectories). This separation ensures that tools can only write to designated output locations, protecting your source code from accidental modifications. - Security Implementation: The filesystem security system includes:
- Adaptive Timeout Management: Prevents operations from hanging indefinitely with intelligent retry and cancellation
- Path Validation: Comprehensive validation of all file paths before access
- Permission Checking: Proactive permission verification to prevent access errors
- System Directory Protection: Built-in blacklist of system directories that should never be accessed
Example structure (default location):
System Instructions for MCP Clients
For optimal performance with AI assistants and MCP clients, use the comprehensive system instructions provided in VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
. This document contains detailed guidance for:
- Tool-specific usage patterns and best practices
- Natural language command structures
- Asynchronous job polling guidelines
- Integration workflows and examples
- Error handling and troubleshooting
How to Use System Instructions
For Claude Desktop:
- Open Claude Desktop settings
- Navigate to "Custom Instructions" or "System Prompt"
- Copy the entire content from
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
- Paste into the custom instructions field
- Save settings
For Augment:
- Access Augment settings/preferences
- Find "Custom Instructions" or "System Configuration"
- Copy and paste the system instructions
- Apply changes
For Claude Code/Windsurf/Other MCP Clients:
- Locate the custom instructions or system prompt configuration
- Copy the content from
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
- Paste into the appropriate field
- Save/apply the configuration
Benefits of Using System Instructions:
- 98%+ tool operation success rate
- Optimal natural language command recognition
- Proper asynchronous job handling
- Efficient workflow orchestration
- Reduced errors and improved troubleshooting
Usage Examples
Via CLI (Direct Command Line)
Via MCP Client (AI Assistant Integration)
Interact with the tools via your connected AI assistant:
- Research:
Research modern JavaScript frameworks
- Generate Rules:
Create development rules for a mobile banking application
- Generate PRD:
Generate a PRD for a task management application
- Generate User Stories:
Generate user stories for an e-commerce website
- Generate Task List:
Create a task list for a weather app based on [user stories]
- Sequential Thinking:
Think through the architecture for a microservices-based e-commerce platform
- Fullstack Starter Kit:
Create a starter kit for a React/Node.js blog application with user authentication
- Run Workflow:
Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }
- Map Codebase:
Generate a code map for the current project
,map-codebase path="./src"
, orGenerate a JSON representation of the codebase structure with output_format="json"
- Context Curation:
Curate context for adding authentication to my React app
,Generate context package for refactoring the user service
, orAnalyze this codebase for performance optimization opportunities
- Vibe Task Manager:
Create a new project for building a todo app
,List all my projects
,Run task authentication-setup
,What's the status of my React project?
Vibe Task Manager - AI-Native Task Management
The Vibe Task Manager is a comprehensive task management system designed specifically for AI agents and development workflows. It provides intelligent project decomposition, natural language command processing, and seamless integration with other Vibe Coder tools.
Status: Functional and production-ready with 99.9% test success rate, but actively being enhanced with new features and improvements.
Key Features
- Natural Language Processing: Understands commands like "Create a project for building a React app" or "Show me all pending tasks"
- Recursive Decomposition Design (RDD): Automatically breaks down complex projects into atomic, executable tasks
- Artifact Parsing Integration: Seamlessly imports PRD files from
VibeCoderOutput/prd-generator/
and task lists fromVibeCoderOutput/generated_task_lists/
- Session Persistence: Enhanced session tracking with orchestration workflow triggers for reliable multi-step operations
- Comprehensive CLI: Full command-line interface with natural language processing and structured commands
- Agent Orchestration: Coordinates multiple AI agents for parallel task execution
- Integration Ready: Works seamlessly with Code Map Tool, Research Tool, and other tools
- File Storage: All project data stored in
VibeCoderOutput/vibe-task-manager/
following established conventions
Quick Start Examples
🎯 Enhanced Project Lookup Features
- Intelligent Parsing: Automatically detects project IDs, names, or partial matches
- Comprehensive Validation: Validates project readiness before decomposition
- Enhanced Error Messages: Provides actionable guidance with available projects and usage examples
- Multiple Input Formats: Supports project IDs, quoted names, partial names, and fuzzy matching
- Confidence Scoring: Shows parsing confidence levels for better user feedback
Command Structure
The Vibe Task Manager supports both structured commands and natural language:
Structured Commands:
vibe-task-manager create project "Name" "Description" --options
vibe-task-manager list projects --status pending
vibe-task-manager run task task-id --force
vibe-task-manager status project-id --detailed
Natural Language (Recommended):
- "Create a project for [description]"
- "Show me all [status] projects"
- "Run the [task name] task"
- "What's the status of [project]?"
- "Parse PRD files for [project name]" (NEW)
- "Import task list from [file path]" (NEW)
- "Parse all PRDs and create projects automatically" (NEW)
For complete documentation, see src/tools/vibe-task-manager/README.md
and the system instructions in VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
.
Implementation Status & Performance Metrics
Current Epic Status
The Vibe Coder MCP project follows an epic-based development approach with comprehensive tracking:
Epic Completion Summary
- Epic 1-5: ✅ Complete (100% - Core infrastructure and basic tools)
- Epic 6.1: ✅ Complete (98.3% test success rate - Deep MCP Tool Integration)
- Epic 6.2: 🔄 In Progress (Performance Optimization - 75% complete)
- Epic 7.1: 📋 Planned (Security Implementation - Ready for implementation)
- Epic 8: 📋 Planned (Advanced Analytics & Monitoring - Designed)
Performance Targets & Current Metrics (v0.2.3)
Metric | Target | Current | Status |
---|---|---|---|
Test Success Rate | 98%+ | 99.9% | ✅ Exceeded |
Response Time (Task Operations) | <200ms | <150ms | ✅ Exceeded |
Response Time (Sync Operations) | <500ms | <350ms | ✅ Exceeded |
Job Completion Rate | 95%+ | 96.7% | ✅ Met |
Memory Usage (Code Map Tool) | <512MB | <400MB | ✅ Optimized |
Unit Test Coverage | >70% | 73% | ✅ Met |
CI/CD Pipeline Speed | <5min | ~3min | ✅ Optimized |
Security Overhead | <50ms | <35ms | ✅ Optimized |
Zero Mock Code Policy | 100% | 100% | ✅ Achieved |
Tool-Specific Status
Vibe Task Manager
- Status: Production Ready (Functional but actively being enhanced)
- Test Coverage: 99.9%
- Features: RDD methodology, agent orchestration, natural language processing, artifact parsing, session persistence, comprehensive CLI
- Performance: <50ms response time for task operations
- Recent Additions: PRD/task list integration, enhanced session tracking, orchestration workflows
Code Map Tool
- Status: Production Ready with Advanced Features
- Memory Optimization: 95-97% token reduction achieved
- Language Support: 35+ programming languages
- Import Resolution: Enhanced with adapter-based architecture
Context Curation Tool
- Status: Production Ready with Intelligent Codemap Caching
- Language Support: 35+ programming languages with 95%+ accuracy
- Workflow Pipeline: 8-phase intelligent analysis and curation
- Project Detection: Language-agnostic with multi-strategy file discovery
- Performance Optimization: Intelligent caching system that reuses recent codemaps (configurable 1-1440 minutes)
Research Tool
- Status: Production Ready
- Integration: Perplexity Sonar API
- Performance: <2s average research query response
Other Tools
- Fullstack Generator: Production Ready
- PRD/User Stories/Task List Generators: Production Ready
- Workflow Runner: Production Ready
Running Locally (Optional)
While the primary use is integration with an AI assistant (using stdio), you can run the server directly for testing:
Running Modes
- Production Mode (Stdio):
- Logs go to stderr (mimics AI assistant launch)
- Use NODE_ENV=production
- Development Mode (Stdio, Pretty Logs):
- Logs go to stdout with pretty formatting
- Requires
nodemon
andpino-pretty
- Use NODE_ENV=development
- SSE Mode (HTTP Interface):
- Uses HTTP instead of stdio
- Configured via PORT in .env (default: 3000)
- Access at http://localhost:3000
Detailed Troubleshooting
Connection Issues
MCP Server Not Detected in AI Assistant
- Check Configuration Path:
- Verify the absolute path in the
args
array is correct - Ensure all slashes are forward slashes
/
even on Windows - Run
node <path-to-build/index.js>
directly to test if Node can find it
- Verify the absolute path in the
- Check Configuration Format:
- Make sure JSON is valid without syntax errors
- Check that commas between properties are correct
- Verify that the
mcpServers
object contains your server
- Restart the Assistant:
- Completely close (not just minimize) the application
- Reopen and try again
Server Starts But Tools Don't Work
- Check Disabled Flag:
- Ensure
"disabled": false
is set - Remove any
//
comments as JSON doesn't support them
- Ensure
- Verify autoApprove Array:
- Check that tool names in the
autoApprove
array match exactly - Try adding
"process-request"
to the array if using hybrid routing
- Check that tool names in the
API Key Issues
- OpenRouter Key Problems:
- Double-check that the key is correctly copied
- Verify the key is active in your OpenRouter dashboard
- Check if you have sufficient credits
- Environment Variable Issues:
- Verify the key is correct in both:
- The
.env
file (for local runs) - Your AI assistant's configuration env block
- The
- Verify the key is correct in both:
Path & Permission Issues
- Build Directory Not Found:
- Run
npm run build
to ensure the build directory exists - Check if build output is going to a different directory (check tsconfig.json)
- Run
- File Permission Errors:
- Ensure your user has write access to the workflow-agent-files directory
- On Unix systems, check if build/index.js has execute permission
Log Debugging
- For Local Runs:
- Check the console output for error messages
- Try running with
LOG_LEVEL=debug
in your.env
file
- For AI Assistant Runs:
- Set
"NODE_ENV": "production"
in the env configuration - Check if the assistant has a logging console or output window
- Set
Tool-Specific Issues
- Semantic Routing Not Working:
- First run may download embedding model - check for download messages
- Try a more explicit request that mentions the tool name
Documentation
Core Documentation
- System Instructions:
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
- Complete usage guide for MCP clients - CI/CD Guide:
CI_CD_GUIDE.md
- Streamlined pipeline documentation (70% faster) - NPM Publishing Guide:
NPM_PUBLISHING_GUIDE.md
- Release and deployment process - System Architecture:
docs/ARCHITECTURE.md
- Comprehensive system architecture with Mermaid diagrams - Performance & Testing:
docs/PERFORMANCE_AND_TESTING.md
- Performance metrics, testing strategies, and quality assurance - Vibe Task Manager:
src/tools/vibe-task-manager/README.md
- Comprehensive task management documentation - Context Curation Tool:
src/tools/curate-context/README.md
- Language-agnostic codebase analysis documentation - Code Map Tool:
src/tools/map-codebase/README.md
- Advanced codebase analysis documentation
Tool Documentation
- Individual Tool READMEs: Each tool directory contains detailed documentation
- Configuration Guides: Environment setup and configuration management
- API Reference: Tool schemas and parameters documented in system instructions
- Integration Examples: Practical workflows and usage patterns
Architecture Documentation
- System Architecture: Mermaid diagrams in README and system instructions
- Tool Architecture: Individual tool architecture diagrams
- Performance Metrics: Current status and optimization strategies
- Development Guidelines: Contributing and development best practices
Contributing
We welcome contributions! Please see our contributing guidelines and ensure all tests pass before submitting pull requests.
Development Workflow
- Fork the repository
- Create a feature branch
- Make your changes with comprehensive tests
- Ensure all checks pass locally:
- Submit a pull request with detailed description
Quality Standards
- Type Safety: NO
any
types - strict TypeScript required - CI Pipeline: Must pass type-check, lint, and build (automated)
- Testing: Run unit tests locally before PR submission
- Test Coverage: Maintain >70% coverage for unit tests
- Documentation: Update relevant docs for changes
- Performance: Consider impact on CI pipeline speed (<5 min target)
Common Troubleshooting
OpenRouter API Key Issues
Problem: Tools fail with authentication errors
- Solution: Verify your OpenRouter API key is correctly set in
.env
- Check: Ensure the key has no extra spaces or quotes
- Verify: Test your key at openrouter.ai
- Credits: Ensure you have sufficient credits in your OpenRouter account
Path Configuration Problems
Problem: "Path not found" or "Access denied" errors
- Solution: Use absolute paths with forward slashes (/) in all configurations
- Windows: Convert paths like
C:\Users\name
toC:/Users/name
- Permissions: Ensure the user has read/write access to configured directories
- Environment Variables: Verify
VIBE_CODER_OUTPUT_DIR
andVIBE_PROJECT_ROOT
are set correctly (or legacy variablesCODE_MAP_ALLOWED_DIR
andVIBE_TASK_MANAGER_READ_DIR
)
Build Failures
Problem: TypeScript compilation errors
- Solution: Run
npm run clean && npm run build
- Dependencies: Delete
node_modules
andpackage-lock.json
, then runnpm install
- Node Version: Ensure Node.js v20+ is installed (
node -v
) - TypeScript: Check for syntax errors with
npm run lint
Test Failures
Problem: Tests fail locally or type-check errors in CI
- Type Errors: Run
npm run type-check
locally to catch issues early - Lint Issues: Use
npm run lint:fix
to auto-fix style problems - Environment: Ensure
.env
file exists with validOPENROUTER_API_KEY
- Memory: Tests may fail on systems with <4GB RAM
- Network: Some tests require internet connectivity
- Cleanup: Run
npm run clean
before running tests - CI Pipeline: See CI/CD Guide for pipeline details
Memory/Performance Issues
Problem: High memory usage or slow performance
- Large Codebases: Code Map Tool may consume significant memory for projects with >10,000 files
- Solution: Increase Node.js memory limit:
NODE_OPTIONS='--max-old-space-size=4096' npm start
- Caching: Clear cache directories in
VibeCoderOutput/
if they grow too large - Monitoring: Use
npm run test:memory
to identify memory leaks
MCP Client Connection Issues
Problem: Server not detected by AI assistant
- Paths: Verify all paths in MCP configuration use forward slashes and are absolute
- Restart: Completely close and restart your AI assistant application
- Logs: Check
LOG_LEVEL=debug
in configuration for detailed error messages - Transport: Ensure
"transport": "stdio"
is set correctly - Disabled: Verify
"disabled": false
in your configuration
Tool-Specific Issues
Vibe Task Manager:
- If natural language commands fail, try using structured commands
- Check
VibeCoderOutput/vibe-task-manager/
for project files - Ensure project names don't contain special characters
Code Map Tool:
- For permission errors, verify
CODE_MAP_ALLOWED_DIR
is set - Large repositories may timeout - try smaller subdirectories
- Some languages require additional setup (see tool README)
Context Curator:
- If codemap generation fails, check recent codemaps in cache
- Verify sufficient disk space for large context packages
- Check file permissions in target directories
Network and Proxy Issues
Problem: Cannot reach external services
- Proxy: Set
HTTP_PROXY
andHTTPS_PROXY
environment variables if behind a proxy - SSL: For SSL issues, try
NODE_TLS_REJECT_UNAUTHORIZED=0
(development only) - Firewall: Ensure firewall allows outbound HTTPS connections
- DNS: Try using public DNS servers if resolution fails
Getting Help
If issues persist:
- Check existing issues at GitHub Issues
- Enable debug logging:
LOG_LEVEL=debug
- Collect error messages and logs
- Create a new issue with:
- Node.js version (
node -v
) - Operating system
- Error messages
- Steps to reproduce
- Node.js version (
📅 Changelog
Version 0.3.5 (Latest)
- Enhanced Hybrid Matcher: Complete parameter extraction for all 15 tools
- CLI/REPL Improvements: Interactive confirmations, job polling with progress
- Bug Fixes: Task-list-generator auto-generates user stories, multi-turn conversations fixed
- TypeScript Strict Mode: Zero
any
types, production-grade code quality
Version 0.3.1
- Global installation synchronization fixes
- Enhanced clean build process
- Improved NPM packaging workflow
Version 0.2.8
- CLI interactive mode configuration persistence
- Enhanced project root detection
Version 0.2.7
- Added missing configuration files to npm package
- Resolved configuration loading errors
Version 0.2.3
- Interactive REPL mode with chat interface
- Enhanced setup wizard with auto-detection
- Configuration templates
- Unified CLI binary
For full release history, see GitHub Releases
License
This project is licensed under the MIT License - see the LICENSE file for details.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
An MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.
- Overview & Features
- Setup Guide
- Project Architecture
- Directory Structure
- Tool Registry Pattern
- Sequential Thinking Process
- Session State Management
- Workflow Execution Engine
- Workflow Configuration
- Detailed Tool Documentation
- Tool Categories
- Generated File Storage
- Usage Examples
- Running Locally (Optional)
- Detailed Troubleshooting
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Linear project management systems, allowing users to retrieve, create, and update issues, projects, and teams through natural language.Last updated -421,070101MIT License
- -securityAlicense-qualityAn MCP server that analyzes codebases and generates contextual prompts, making it easier for AI assistants to understand and work with code repositories.Last updated -12MIT License
- AsecurityAlicenseAqualityA MCP server that enables human-in-the-loop workflow in AI-assisted development tools by allowing users to run commands, view their output, and provide textual feedback directly to the AI assistant.Last updated -11,517MIT License
- AsecurityAlicenseAqualityA powerful MCP server that provides interactive user feedback and command execution capabilities for AI-assisted development, featuring a graphical interface with text and image support.Last updated -135MIT License