vibe-coder-mcp
Version:
Production-ready MCP server with complete agent integration, multi-transport support, and comprehensive development automation tools for AI-assisted workflows.
1,157 lines (935 loc) ā¢ 64.8 kB
Markdown
# Vibe Coder MCP Server
[](https://www.npmjs.com/package/vibe-coder-mcp)
[](https://www.npmjs.com/package/vibe-coder-mcp)
[](https://www.npmjs.com/package/vibe-coder-mcp)
[](https://github.com/freshtechbro/Vibe-Coder-MCP/releases)
[](https://nodejs.org/)
[](LICENSE)
[](https://github.com/freshtechbro/Vibe-Coder-MCP/stargazers)
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!
## š¦ NPM Package
**Available on npm**: [`vibe-coder-mcp`](https://www.npmjs.com/package/vibe-coder-mcp)
```bash
# Run instantly with npx (recommended)
npx vibe-coder-mcp
# Or install globally
npm install -g vibe-coder-mcp
```
## š Quick Start (Recommended)
**The easiest way to get started:**
### Option 1: Run with npx (No Installation Required)
```bash
# Start MCP server
npx vibe-coder-mcp
# Or use the CLI directly
npx vibe-coder-mcp "research React best practices"
```
### Option 2: Install Globally
```bash
# Install globally
npm install -g vibe-coder-mcp
# Use the unified 'vibe' command
vibe # Start MCP server
vibe "create a PRD for a todo app" # CLI mode
vibe --setup # Interactive setup
```
### Option 3: Install Locally in Your Project
```bash
# Install in your project
npm install vibe-coder-mcp
# Run via npx
npx vibe-coder-mcp
npx vibe-coder-mcp "map the codebase structure"
```
### Command Line Options
#### MCP Server Mode
```bash
# Default stdio transport (for MCP clients like Claude Desktop)
vibe-coder-mcp
# Server-Sent Events transport (for web clients)
vibe-coder-mcp --sse
```
#### CLI Mode (New!)
```bash
# Interactive setup wizard
vibe-coder-mcp --setup
# Natural language commands
vibe-coder-mcp "research modern JavaScript frameworks"
vibe-coder-mcp "create a PRD for an e-commerce platform"
vibe-coder-mcp "map the codebase structure" --json
# Interactive REPL mode
vibe-coder-mcp --interactive
# Help and options
vibe-coder-mcp --help
```
#### Global Installation Benefits
After global installation (`npm install -g vibe-coder-mcp`), use the shorter `vibe` command:
```bash
vibe # Start MCP server
vibe "your request here" # CLI mode
vibe --setup # Setup wizard
vibe --help # Show all options
```
**First-time setup:**
- The setup wizard runs automatically on first use
- Or run `vibe --setup` manually to configure your environment
## š§ Environment Configuration
**Required:** You need an OpenRouter API key to use Vibe Coder MCP.
### Get Your OpenRouter API Key
1. Visit [openrouter.ai](https://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: Environment Variables (Recommended)**
```bash
# 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 CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"
export VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"
```
**Option 2: Create .env file**
Create a `.env` file in your working directory:
```dotenv
# Required: Your OpenRouter API key
OPENROUTER_API_KEY="your_api_key_here"
# Optional: Custom directories
VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"
VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"
# Optional: Other settings
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
GEMINI_MODEL="google/gemini-2.5-flash-preview-05-20"
```
### Directory Configuration (Optional)
- **VIBE_CODER_OUTPUT_DIR**: Where generated files are saved (default: `./VibeCoderOutput/`)
- **CODE_MAP_ALLOWED_DIR**: Security boundary for code analysis (default: current directory)
- **VIBE_TASK_MANAGER_READ_DIR**: Security boundary for task manager file operations (default: current directory)
## š 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`):
```json
{
"mcpServers": {
"vibe-coder-mcp": {
"command": "npx",
"args": ["vibe-coder-mcp"],
"env": {
"OPENROUTER_API_KEY": "your_api_key_here"
}
}
}
}
```
### For Claude Desktop
Add this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"vibe-coder-mcp": {
"command": "npx",
"args": ["vibe-coder-mcp"],
"env": {
"OPENROUTER_API_KEY": "your_api_key_here"
}
}
}
}
```
## š» CLI Usage Guide
Vibe Coder now includes a powerful command-line interface for direct interaction with all tools.
### Interactive Setup Wizard
```bash
# First-time setup (runs automatically on first use)
vibe --setup
# Reconfigure existing installation
vibe --reconfigure
```
### CLI Command Examples
#### Research & Analysis
```bash
vibe "research modern React patterns and best practices"
vibe "analyze current trends in microservices architecture"
vibe "research security best practices for Node.js APIs"
```
#### Project Planning
```bash
vibe "create a PRD for an e-commerce platform with user authentication"
vibe "generate user stories for authentication system"
vibe "create development tasks from user stories"
```
#### Code Analysis & Generation
```bash
vibe "map the codebase structure"
vibe "create context for implementing authentication"
vibe "generate a fullstack starter kit for e-commerce"
vibe "create coding standards for TypeScript projects"
```
#### Task Management
```bash
vibe "create a new project for building a todo app"
vibe "list all my projects"
vibe "show project status for MyApp"
vibe "create high priority task for implementing OAuth"
```
### CLI Options
```bash
# Output formats
vibe "research React hooks" --json
vibe "create PRD for todo app" --yaml
# Verbosity control
vibe "create project MyApp" --verbose
vibe "research Node.js patterns" --quiet
# Interactive mode
vibe --interactive
```
### File Organization
Generated files are automatically organized in `VibeCoderOutput/`:
```
VibeCoderOutput/
āāā research/ # Research reports
āāā prd-generator/ # Product requirements
āāā user-stories-generator/ # User stories
āāā task-list-generator/ # Development tasks
āāā fullstack-starter-kit-generator/ # Project templates
āāā map-codebase/ # Code analysis
āāā vibe-task-manager/ # Task management data
āāā workflow-runner/ # Workflow outputs
```
---
## š 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 (`generate-prd`), user stories (`generate-user-stories`), task lists (`generate-task-list`), development rules (`generate-rules`)
* **Project Scaffolding**: Full-stack starter kits (`generate-fullstack-starter-kit`) 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
1. **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](https://nodejs.org/).
2. **Check Git Installation:**
* Open a terminal or command prompt.
* Run `git --version`
* If not installed: Download from [git-scm.com](https://git-scm.com/).
3. **Get OpenRouter API Key:**
* Visit [openrouter.ai](https://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
1. **Create a Project Directory** (optional):
* Open a terminal or command prompt.
* Navigate to where you want to store the project:
```bash
cd ~/Documents # Example: Change to your preferred location
```
2. **Clone the Repository:**
* Run:
```bash
git clone https://github.com/freshtechbro/vibe-coder-mcp.git
```
(Or use your fork's URL if applicable)
3. **Navigate to Project Directory:**
* Run:
```bash
cd vibe-coder-mcp
```
### Step 3: Run the Setup Script
Choose the appropriate script for your operating system:
**For Windows:**
1. In your terminal (still in the vibe-coder-mcp directory), run:
```batch
setup.bat
```
2. Wait for the script to complete (it will install dependencies, build the project, and create necessary directories).
3. If you see any error messages, refer to the Troubleshooting section below.
**For macOS or Linux:**
1. Make the script executable:
```bash
chmod +x setup.sh
```
2. Run the script:
```bash
./setup.sh
```
3. Wait for the script to complete.
4. If you see any error messages, refer to the Troubleshooting section below.
The script performs these actions:
* Checks Node.js version (v18+)
* Installs all dependencies via npm
* Creates necessary `VibeCoderOutput/` subdirectories (as defined in the script).
* Builds the TypeScript project.
* **Copies `.env.example` to `.env` if `.env` doesn't already exist.** You will need to edit this file.
* Sets executable permissions (on Unix systems).
### Step 4: Configure Environment Variables (`.env`)
The setup script (from Step 3) automatically creates a `.env` file in the project's root directory by copying the `.env.example` template, **only if `.env` does not already exist**.
1. **Locate and Open `.env`:** Find the `.env` file in the main `vibe-coder-mcp` directory and open it with a text editor.
2. **Add Your OpenRouter API Key (Required):**
* The file contains a template based on `.env.example`:
```dotenv
# OpenRouter Configuration
## Specifies your unique API key for accessing OpenRouter services.
## Replace "Your OPENROUTER_API_KEY here" with your actual key obtained from OpenRouter.ai.
OPENROUTER_API_KEY="Your OPENROUTER_API_KEY here"
## Defines the base URL for the OpenRouter API endpoints.
## The default value is usually correct and should not need changing unless instructed otherwise.
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
## Sets the specific Gemini model to be used via OpenRouter for certain AI tasks.
## ':free' indicates potential usage of a free tier model if available and supported by your key.
GEMINI_MODEL=google/gemini-2.5-flash-preview-05-20
```
* **Crucially, replace `"Your OPENROUTER_API_KEY here"` with your actual OpenRouter API key.** Remove the quotes if your key doesn't require them.
3. **Configure Output Directory (Optional):**
* To change where generated files are saved (default is `VibeCoderOutput/` inside the project), add this line to your `.env` file:
```dotenv
VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
```
* 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.
4. **Configure Code-Map Generator Directory (Optional):**
* To specify which directory the map-codebase tool is allowed to scan, add this line to your `.env` file:
```dotenv
CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
```
* Replace the path with the **absolute path** to the directory containing the source code you want to analyze. This is a security boundary - the tool will not access files outside this directory.
5. **Configure Vibe Task Manager Read Directory (Optional):**
* To specify which directory the Vibe Task Manager is allowed to read from for security purposes, add this line to your `.env` file:
```dotenv
VIBE_TASK_MANAGER_READ_DIR=/path/to/your/project/source/directory
```
* Replace the path with the **absolute path** to the directory containing your project files that the task manager should have access to.
* **Default Value**: If not specified, defaults to `process.cwd()` (the current working directory where the server is running).
* **Security**: This variable works with the filesystem security implementation that defaults to 'strict' mode, preventing access to system directories and unauthorized paths.
* **Note**: `VIBE_TASK_MANAGER_READ_DIR` (for task manager file operations), `CODE_MAP_ALLOWED_DIR` (for code analysis), and `VIBE_CODER_OUTPUT_DIR` (for writing output files) are separate security boundaries for different tool operations.
6. **Review Other Settings (Optional):**
* You can add other environment variables supported by the server, such as `LOG_LEVEL` (e.g., `LOG_LEVEL=debug`) or `NODE_ENV` (e.g., `NODE_ENV=development`).
7. **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):**
1. Open the application.
2. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`).
3. Type and select `Preferences: Open User Settings (JSON)`.
4. This opens your `settings.json` file where the `mcpServers` 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` with `Code` in the path)*
* **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`
#### 5.2: Add the Vibe Coder Configuration
1. Open the settings file identified above in a text editor.
2. 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": {}}`.
3. Add the following configuration block **inside** the curly braces `{}` of the `mcpServers` object. If other servers are already listed, add a comma `,` after the previous server's closing brace `}` before pasting this block.
```json
// This is the unique identifier for this MCP server instance within your client's settings
"vibe-coder-mcp": {
// Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH
"command": "node",
// Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point
// !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
"args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"],
// Sets the current working directory for the server process when it runs
// !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
"cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
// Defines the communication transport protocol between the client and server
"transport": "stdio",
// Environment variables to be passed specifically to the Vibe Coder server process when it starts
// API Keys should be in the .env file, NOT here
"env": {
// Absolute path to the LLM configuration file used by Vibe Coder
// !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
"LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json",
// Sets the logging level for the server
"LOG_LEVEL": "debug",
// Specifies the runtime environment
"NODE_ENV": "production",
// Directory where Vibe Coder tools will save their output files
// !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
"VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput",
// Directory that the map-codebase tool is allowed to scan
// This is a security boundary - the tool will not access files outside this directory
"CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src",
// Directory that the Vibe Task Manager is allowed to read from for security purposes
// Defaults to process.cwd() if not specified. Works with strict security mode by default.
"VIBE_TASK_MANAGER_READ_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP"
},
// A boolean flag to enable (false) or disable (true) this server configuration
"disabled": false,
// A list of tool names that the MCP client is allowed to execute automatically
"autoApprove": [
"research",
"generate-rules",
"generate-user-stories",
"generate-task-list",
"generate-prd",
"generate-fullstack-starter-kit",
"refactor-code",
"git-summary",
"run-workflow",
"map-codebase"
]
}
```
4. **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.
5. Save the settings file.
6. **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
1. **Start Your AI Assistant:**
* Completely restart your AI assistant application.
2. **Test a Simple Command:**
* Type a test command like: `Research modern JavaScript frameworks`
3. **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:
1. Open Claude Desktop
2. Navigate to project settings
3. Add the contents of `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md` to the system instructions field
4. Save and restart Claude Desktop
#### ChatGPT
Add the system instructions to your custom instructions or project settings:
1. Open ChatGPT settings
2. Navigate to custom instructions or project configuration
3. Paste the contents of `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
4. Save the configuration
#### VS Code Extensions (Cline, Roo Coder, Augment)
Integrate the system instructions into your extension's configuration:
1. **Cline**: Place in system instructions or memories section
2. **Roo Coder**: Add to system instructions or rules folder
3. **Augment**: Place in system instructions or memories
4. **Other VS Code forks**: Place in system instructions or rules folder with "always active" setting
#### General MCP Clients
For other MCP-compatible clients:
1. Locate the system instructions or rules configuration
2. Add the contents of `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
3. Set as "always active" or "persistent" if the option is available
4. 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:
```bash
# Research-driven development
"Research modern React patterns, then create a PRD and generate user stories"
# Complete project setup
"Set up a new e-commerce project with React frontend and Node.js backend"
# Context-aware development
"Analyze this codebase and suggest improvements with implementation tasks"
# Multi-agent coordination
"Register frontend and backend agents, then distribute authentication tasks"
```
### Verification
To verify successful integration:
1. Ask your AI agent about available Vibe Coder tools
2. Request a workflow that uses multiple tools in sequence
3. Check that the agent follows proper job polling protocols
4. Confirm that outputs are saved to the correct directories
## Project Architecture
The Vibe Coder MCP server follows a modular, TypeScript ESM architecture with dual transport support and comprehensive tool ecosystem:
```mermaid
flowchart TD
subgraph "Core Architecture"
Init[index.ts] --> Config[Configuration Loader]
Config --> Transport{Transport Type}
Transport --> |stdio| StdioTransport[Stdio Transport]
Transport --> |sse| SSETransport[SSE Transport]
StdioTransport --> Server[MCP Server]
SSETransport --> Server
Server --> ToolReg[Tool Registry]
ToolReg --> InitEmbed[Initialize Embeddings]
InitEmbed --> Ready[Server Ready]
end
subgraph "Request Processing"
Req[Client Request] --> SessionMgr[Session Manager]
SessionMgr --> Router[Hybrid Router]
Router --> Semantic[Semantic Matcher]
Router --> Sequential[Sequential Thinking]
Semantic --> |High Confidence| Execute[Tool Execution]
Sequential --> |Fallback| Execute
Execute --> JobMgr[Job Manager]
JobMgr --> Response[Response to Client]
end
subgraph "Tool Ecosystem"
Execute --> Research[Research Tool]
Execute --> TaskMgr[Vibe Task Manager]
Execute --> CodeMap[Code Map Tool]
Execute --> FullStack[Fullstack Generator]
Execute --> PRDGen[PRD Generator]
Execute --> UserStories[User Stories Generator]
Execute --> TaskList[Task List Generator]
Execute --> Rules[Rules Generator]
Execute --> Workflow[Workflow Runner]
end
subgraph "Support Services"
JobMgr --> AsyncJobs[Async Job Processing]
Execute --> FileOps[File Operations]
Execute --> LLMHelper[LLM Integration]
Execute --> ErrorHandler[Error Handling]
Execute --> StateManager[Session State]
end
subgraph "Configuration & Security"
Config --> LLMConfig[LLM Config Mapping]
Config --> MCPConfig[MCP Tool Config]
Config --> EnvVars[Environment Variables]
FileOps --> SecurityBoundary[Security Boundaries]
SecurityBoundary --> ReadOps[Read Operations]
SecurityBoundary --> WriteOps[Write Operations]
end
```
## Directory Structure
```
vibe-coder-mcp/
āāā .env # Environment configuration
āāā .env.example # Environment template
āāā llm_config.json # LLM model mappings
āāā mcp-config.json # MCP tool configurations
āāā package.json # Project dependencies
āāā README.md # This documentation
āāā VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md # System prompt documentation
āāā setup.bat # Windows setup script
āāā setup.sh # macOS/Linux setup script
āāā tsconfig.json # TypeScript configuration
āāā vitest.config.ts # Vitest (testing) configuration
āāā workflows.json # Workflow definitions
āāā build/ # Compiled JavaScript (after build)
āāā docs/ # Additional documentation
ā āāā map-codebase/ # Code Map Tool docs
ā āāā handover/ # Development handover docs
ā āāā *.md # Various documentation files
āāā VibeCoderOutput/ # Tool output directory
ā āāā research/ # Research reports
ā āāā rules-generator/ # Development rules
ā āāā prd-generator/ # Product requirements
ā āāā user-stories-generator/ # User stories
ā āāā task-list-generator/ # Task lists
ā āāā fullstack-starter-kit-generator/ # Project templates
ā āāā map-codebase/ # Code maps and diagrams
ā āāā vibe-task-manager/ # Task management data
ā āāā workflow-runner/ # Workflow outputs
āāā src/ # Source code
āāā index.ts # Entry point
āāā logger.ts # Logging configuration (Pino)
āāā server.ts # MCP server setup
āāā services/ # Core services
ā āāā routing/ # Semantic routing system
ā ā āāā embeddingStore.ts # Embedding management
ā ā āāā hybridMatcher.ts # Hybrid routing logic
ā ā āāā toolRegistry.ts # Tool registry
ā āāā sse-notifier/ # SSE notification system
ā āāā JobManager.ts # Async job management
ā āāā ToolService.ts # Tool execution service
āāā tools/ # MCP Tools
ā āāā index.ts # Tool registration
ā āāā sequential-thinking.ts # Fallback routing
ā āāā map-codebase/ # Code analysis tool
ā ā āāā cache/ # Memory management
ā ā āāā grammars/ # Tree-sitter grammars
ā ā āāā importResolvers/ # Import resolution adapters
ā ā āāā *.ts # Core implementation
ā āāā fullstack-starter-kit-generator/ # Project scaffolding
ā āāā prd-generator/ # PRD creation
ā āāā research/ # Research tool
ā āāā rules-generator/ # Rule generation
ā āāā task-list-generator/ # Task list generation
ā āāā user-stories-generator/ # User story generation
ā āāā vibe-task-manager/ # AI-native task management
ā ā āāā __tests__/ # Comprehensive test suite
ā ā āāā cli/ # Command-line interface
ā ā āāā core/ # Core algorithms
ā ā āāā integrations/ # Tool integrations
ā ā āāā prompts/ # LLM prompts (YAML)
ā ā āāā services/ # Business logic services
ā ā āāā types/ # TypeScript definitions
ā ā āāā utils/ # Utility functions
ā āāā workflow-runner/ # Workflow execution engine
āāā types/ # TypeScript type definitions
āāā utils/ # Shared utilities
āāā configLoader.ts # Configuration management
āāā errors.ts # Error handling
āāā llmHelper.ts # LLM integration helpers
```
## Semantic Routing System
Vibe Coder uses a sophisticated routing approach to select the right tool for each request:
```mermaid
flowchart TD
Start[Client Request] --> Process[Process Request]
Process --> Hybrid[Hybrid Matcher]
subgraph "Primary: Semantic Routing"
Hybrid --> Semantic[Semantic Matcher]
Semantic --> Embeddings[Query Embeddings]
Embeddings --> Tools[Tool Embeddings]
Tools --> Compare[Compare via Cosine Similarity]
Compare --> Score[Score & Rank Tools]
Score --> Confidence{High Confidence?}
end
Confidence -->|Yes| Registry[Tool Registry]
subgraph "Fallback: Sequential Thinking"
Confidence -->|No| Sequential[Sequential Thinking]
Sequential --> LLM[LLM Analysis]
LLM --> ThoughtChain[Thought Chain]
ThoughtChain --> Extraction[Extract Tool Name]
Extraction --> Registry
end
Registry --> Executor[Execute Tool]
Executor --> Response[Return Response]
```
## Tool Registry Pattern
The Tool Registry is a central component for managing tool definitions and execution:
```mermaid
flowchart TD
subgraph "Tool Registration (at import)"
Import[Import Tool] --> Register[Call registerTool]
Register --> Store[Store in Registry Map]
end
subgraph "Tool Definition"
Def[ToolDefinition] --> Name[Tool Name]
Def --> Desc[Description]
Def --> Schema[Zod Schema]
Def --> Exec[Executor Function]
end
subgraph "Server Initialization"
Init[server.ts] --> Import
Init --> GetAll[getAllTools]
GetAll --> Loop[Loop Through Tools]
Loop --> McpReg[Register with MCP Server]
end
subgraph "Tool Execution"
McpReg --> ExecTool[executeTool Function]
ExecTool --> GetTool[Get Tool from Registry]
GetTool --> Validate[Validate Input]
Validate -->|Valid| ExecFunc[Run Executor Function]
Validate -->|Invalid| ValidErr[Return Validation Error]
ExecFunc -->|Success| SuccessResp[Return Success Response]
ExecFunc -->|Error| HandleErr[Catch & Format Error]
HandleErr --> ErrResp[Return Error Response]
end
```
## Sequential Thinking Process
The Sequential Thinking mechanism provides LLM-based fallback routing:
```mermaid
flowchart TD
Start[Start] --> Estimate[Estimate Number of Steps]
Estimate --> Init[Initialize with System Prompt]
Init --> First[Generate First Thought]
First --> Context[Add to Context]
Context --> Loop{Needs More Thoughts?}
Loop -->|Yes| Next[Generate Next Thought]
Next -->|Standard| AddStd[Add to Context]
Next -->|Revision| Rev[Mark as Revision]
Next -->|New Branch| Branch[Mark as Branch]
Rev --> AddRev[Add to Context]
Branch --> AddBranch[Add to Context]
AddStd --> Loop
AddRev --> Loop
AddBranch --> Loop
Loop -->|No| Extract[Extract Final Solution]
Extract --> End[End With Tool Selection]
subgraph "Error Handling"
Next -->|Error| Retry[Retry with Simplified Request]
Retry -->|Success| AddRetry[Add to Context]
Retry -->|Failure| FallbackEx[Extract Partial Solution]
AddRetry --> Loop
FallbackEx --> End
end
```
## Session State Management
```mermaid
flowchart TD
Start[Client Request] --> SessionID[Extract Session ID]
SessionID --> Store{State Exists?}
Store -->|Yes| Retrieve[Retrieve Previous State]
Store -->|No| Create[Create New State]
Retrieve --> Context[Add Context to Tool]
Create --> NoContext[Execute Without Context]
Context --> Execute[Execute Tool]
NoContext --> Execute
Execute --> SaveState[Update Session State]
SaveState --> Response[Return Response to Client]
subgraph "Session State Structure"
State[SessionState] --> PrevCall[Previous Tool Call]
State --> PrevResp[Previous Response]
State --> Timestamp[Timestamp]
end
```
## Workflow Execution Engine
The Workflow system enables multi-step sequences:
```mermaid
flowchart TD
Start[Client Request] --> Parse[Parse Workflow Request]
Parse --> FindFlow[Find Workflow in workflows.json]
FindFlow --> Steps[Extract Steps]
Steps --> Loop[Process Each Step]
Loop --> PrepInput[Prepare Step Input]
PrepInput --> ExecuteTool[Execute Tool via Registry]
ExecuteTool --> SaveOutput[Save Step Output]
SaveOutput --> NextStep{More Steps?}
NextStep -->|Yes| MapOutput[Map Output to Next Input]
MapOutput --> Loop
NextStep -->|No| FinalOutput[Prepare Final Output]
FinalOutput --> End[Return Workflow Result]
subgraph "Input/Output Mapping"
MapOutput --> Direct[Direct Value]
MapOutput --> Extract[Extract From Previous]
MapOutput --> Transform[Transform Values]
end
```
## 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:
```json
{
"workflows": {
"workflowName1": {
"description": "Description of what this workflow does",
"inputSchema": {
"param1": "string",
"param2": "string"
},
"steps": [
{
"id": "step1_id",
"toolName": "tool-name",
"params": {
"param1": "{workflow.input.param1}"
}
},
{
"id": "step2_id",
"toolName": "another-tool",
"params": {
"paramA": "{workflow.input.param2}",
"paramB": "{steps.step1_id.output.content[0].text}"
}
}
],
"output": {
"summary": "Workflow completed message",
"details": ["Output line 1", "Output line 2"]
}
}
}
}
```
### 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:
```
Run the newProjectSetup workflow with input {"productDescription": "A task manager app"}
```
## 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 (`generate-rules`):** Creates project-specific development rules and guidelines.
* **PRD Generator (`generate-prd`):** Generates comprehensive product requirements documents.
* **User Stories Generator (`generate-user-stories`):** Creates detailed user stories with acceptance criteria.
* **Task List Generator (`generate-task-list`):** Builds structured development task lists with dependencies.
### Project Scaffolding Tool
* **Fullstack Starter Kit Generator (`generate-fullstack-starter-kit`):** 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 to `process.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
* **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):
```bash
VibeCoderOutput/
āāā research/ # Research reports
ā āāā TIMESTAMP-QUERY-research.md
āāā rules-generator/ # Development rules
ā āāā TIMESTAMP-PROJECT-rules.md
āāā prd-generator/ # PRDs
ā āāā TIMESTAMP-PROJECT-prd.md
āāā user-stories-generator/ # User stories
ā āāā TIMESTAMP-PROJECT-user-stories.md
āāā task-list-generator/ # Task lists
ā āāā TIMESTAMP-PROJECT-task-list.md
āāā fullstack-starter-kit-generator/ # Project templates
ā āāā TIMESTAMP-PROJECT/
āāā map-codebase/ # Code maps and diagrams
ā āāā TIMESTAMP-code-map/
āāā workflow-runner/ # Workflow outputs
āāā TIMESTAMP-WORKFLOW/
```
## 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:**
1. Open Claude Desktop settings
2. Navigate to "Custom Instructions" or "System Prompt"
3. Copy the entire content from `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
4. Paste into the custom instructions field
5. Save settings
**For Augment:**
1. Access Augment settings/preferences
2. Find "Custom Instructions" or "System Configuration"
3. Copy and paste the system instructions
4. Apply changes
**For Claude Code/Windsurf/Other MCP Clients:**
1. Locate the custom instructions or system prompt configuration
2. Copy the content from `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
3. Paste into the appropriate field
4. 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)
```bash
# Research and analysis
vibe "research modern JavaScript frameworks"
vibe "create development rules for a mobile banking application"
# Project planning
vibe "generate a PRD for a task management application"
vibe "generate user stories for an e-commerce website"
vibe "create a task list for a weather app based on user stories"
# Code generation and analysis
vibe "create a starter kit for a React/Node.js blog application with user authentication"
vibe "map the codebase structure" --json
vibe "curate context for adding authentication to my React app"
# Task management
vibe "create a new project for building a todo app"
vibe "list all my projects"
vibe "show status of my React project"
# Workflow automation
vibe "run workflow newProjectSetup with input {\"projectName\": \"my-new-app\"}"
```
### 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"`, or `Generate 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`, or `Analyze 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 from `VibeCoderOutput/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
```
# Project Management
"Create a new project for building a todo app with React and Node.js"
"List all my projects"
"Show me the status of my web app project"
# Task Management
"Create a high priority task for implementing user authentication"
"List all pending tasks for the todo-app projec