Vibe Coder
STDIOSoftware development MCP server with tools for research, planning, coding, and project management.
Software development MCP server with tools for research, planning, coding, and project management.
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!
Major Improvements:
any types, all explicit typing, production-grade code qualityUser Experience Enhancements:
src/config-templates/vibe command for all operations# 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:
# Recommended: Install globally for the 'vibe' command npm install -g vibe-coder-mcp@latest # Or run instantly without installation npx vibe-coder-mcp@latest
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"
# 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:
Vibe-Coder MCP integrates seamlessly with any MCP-compatible client. Here's how to configure it:
In your MCP client's server configuration dialog:
vibe-coder-mcpnpxvibe-coder-mcpOPENROUTER_API_KEY: Your OpenRouter API key (required)VIBE_PROJECT_ROOT: /path/to/your/project (required)LOG_LEVEL: info (optional)NODE_ENV: production (optional)# First install globally npm install -g vibe-coder-mcp
Then configure:
vibenode/path/to/node_modules/vibe-coder-mcp/build/index.jsFor 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.
Once configured, your MCP client will have access to:
After configuration, test by asking your AI assistant:
# Automatic project detection - just run from your project! cd /path/to/your/project vibe "map the codebase structure"
{ "env": { "OPENROUTER_API_KEY": "your_key_here", "VIBE_PROJECT_ROOT": "/path/to/your/project" } }
VIBE_PROJECT_ROOT replaces multiple directory configsRequired: You need an OpenRouter API key to use Vibe Coder MCP.
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" # Optional: Unified project root configuration VIBE_CODER_OUTPUT_DIR="/path/to/output/directory" VIBE_PROJECT_ROOT="/path/to/your/project" VIBE_USE_PROJECT_ROOT_AUTO_DETECTION="true" # Legacy variables (still supported for backward compatibility) 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"
🆕 Unified Configuration (Recommended)
"true")./VibeCoderOutput/)Legacy Configuration (Still Supported)
Auto-Detection Benefits:
Configure your AI assistant to connect to Vibe Coder MCP:
Add this to your MCP settings (usually in settings.json):
{ "mcpServers": { "vibe-coder-mcp": { "command": "npx", "args": ["vibe-coder-mcp"], "env": { "OPENROUTER_API_KEY": "your_api_key_here" } } } }
Add this to your claude_desktop_config.json:
{ "mcpServers": { "vibe-coder-mcp": { "command": "npx", "args": ["vibe-coder-mcp"], "env": { "OPENROUTER_API_KEY": "your_api_key_here", "VIBE_PROJECT_ROOT": "/path/to/your/project" } } } }
Vibe Coder includes a powerful command-line interface with multiple modes for direct interaction with all tools.
# First-time setup (runs automatically on first use) vibe --setup # Features: # • Smart first-run detection # • OS-specific configuration paths # • Non-interactive mode for CI/CD # • Configuration validation # • Backup system for existing configs # Reconfigure existing installation vibe --reconfigure
# Start interactive chat session vibe --interactive # Or with alias vibe -i # Resume a previous session vibe --resume <session-id>
REPL Features:
""" for multi-line messages/theme command/tools, /history, /savevibe "research modern React patterns and best practices" vibe "analyze current trends in microservices architecture" vibe "research security best practices for Node.js APIs"
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"
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"
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"
# 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 REPL mode (NEW!) vibe --interactive vibe -i # Session management (NEW!) vibe --resume <session-id> vibe --list-sessions
Once in interactive mode (vibe --interactive), use these commands:
# Help and navigation /help # Show available commands /tools # List all MCP tools /status # Show session status # Session management /save # Save current session /sessions # List saved sessions /export [file] # Export session to markdown # Conversation control /clear # Clear conversation history /history # Show conversation history # Customization /theme # Change color theme /markdown # Toggle markdown rendering /config # Manage configuration # Exit /quit or /exit # Exit interactive mode
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
None! Version 0.2.3 is fully backward compatible. All existing configurations and workflows continue to work.
If you want to contribute to development or run from source, follow the detailed setup guide below.
Vibe Coder MCP integrates with MCP-compatible clients to provide the following capabilities:
prd-generator), user stories (user-stories-generator), task lists (task-list-generator), development rules (rules-generator)fullstack-starter-kit-generator) with dynamic template generationworkflows.json(See "Detailed Tool Documentation" and "Feature Details" sections below for more)
For developers who want to run from source or contribute to the project.
Check Node.js Version:
node -vCheck Git Installation:
git --versionGet OpenRouter API Key:
Create a Project Directory (optional):
cd ~/Documents # Example: Change to your preferred location
Clone the Repository:
(Or use your fork's URL if applicable)git clone https://github.com/freshtechbro/vibe-coder-mcp.git
Navigate to Project Directory:
cd vibe-coder-mcp
Choose the appropriate script for your operating system:
For Windows:
setup.bat
For macOS or Linux:
chmod +x setup.sh
./setup.sh
The script performs these actions:
VibeCoderOutput/ subdirectoriesNote: The setup process is now faster (v0.2.3+) with optimized dependency installation and simplified build process.
New in v0.2.3: Configuration templates are provided in src/config-templates/ for easy setup.
vibe --setup
The wizard will guide you through configuration and create all necessary files.
Copy templates (if not already done by setup script):
cp src/config-templates/.env.template .env cp src/config-templates/llm_config.template.json llm_config.json cp src/config-templates/mcp-config.template.json mcp-config.json
Edit .env file with your configuration:
# OpenRouter Configuration (REQUIRED) OPENROUTER_API_KEY="your_actual_api_key_here" # Optional configurations OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 GEMINI_MODEL=google/gemini-2.5-flash-preview-05-20 # Project directories (optional - auto-detected for CLI users) VIBE_PROJECT_ROOT=/path/to/your/project VIBE_CODER_OUTPUT_DIR=/path/to/output
Configure Output Directory (Optional):
VibeCoderOutput/ inside the project), add this line to your .env file:
VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
/) for paths. If this variable is not set, the default directory (VibeCoderOutput/) will be used.🆕 Configure Unified Project Root (Recommended):
.env file:
VIBE_PROJECT_ROOT=/path/to/your/project/root
Legacy Directory Configuration (Optional):
CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory VIBE_TASK_MANAGER_READ_DIR=/path/to/your/project/source/directory
VIBE_PROJECT_ROOT is not setReview Other Settings (Optional):
LOG_LEVEL (e.g., LOG_LEVEL=debug) or NODE_ENV (e.g., NODE_ENV=development).Save the .env File.
This crucial step connects Vibe Coder to your AI assistant by adding its configuration to the client's MCP settings file.
The location varies depending on your AI assistant:
Cursor AI / Windsurf / RooCode (VS Code based):
Ctrl+Shift+P or Cmd+Shift+P).Preferences: Open User Settings (JSON).settings.json file where the mcpServers object should reside.Cline AI (VS Code Extension):
%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.jsonCursor with Code in the path)Claude Desktop:
%APPDATA%\Claude\claude_desktop_config.json~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonOpen 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 the mcpServers object. If other servers are already listed, add a comma , after the previous server's closing brace } before pasting this block.
// 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", // 🆕 Unified project root for all tools (recommended) // This single variable configures all tools with the same project boundary "VIBE_PROJECT_ROOT": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP", // Legacy variables (optional - used as fallbacks if VIBE_PROJECT_ROOT not set) "CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src", "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", "rules-generator", "user-stories-generator", "task-list-generator", "prd-generator", "fullstack-starter-kit-generator", "refactor-code", "git-summary", "run-workflow", "map-codebase" ] }
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.
Start Your AI Assistant:
Test a Simple Command:
Research modern JavaScript frameworksCheck for Proper Response:
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.
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.
Place the system instructions in your project's system instructions or custom instructions:
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md to the system instructions fieldAdd the system instructions to your custom instructions or project settings:
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.mdIntegrate the system instructions into your extension's configuration:
For other MCP-compatible clients:
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.mdOnce integrated, your AI agents will be able to:
# 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"
To verify successful integration:
The new unified CLI (unified-cli.ts) provides a single entry point for all Vibe Coder operations:
flowchart TD Start[vibe command] --> Detect{First Run?} Detect -->|Yes| Setup[Setup Wizard] Detect -->|No| Parse[Parse Arguments] Setup --> Config[Save Configuration] Config --> Parse Parse --> Mode{Mode?} Mode -->|--interactive| REPL[Interactive REPL] Mode -->|"message"| CLI[CLI Execution] Mode -->|none| MCP[MCP Server] Mode -->|--setup| Setup REPL --> Session[Session Management] Session --> Chat[Chat Interface] Chat --> Tools[Tool Execution] CLI --> Router[Hybrid Router] Router --> Tools MCP --> Transport{Transport?} Transport -->|stdio| Stdio[Stdio Server] Transport -->|sse| SSE[SSE Server]
Benefits of Unified CLI:
vibe)The Vibe Coder MCP server follows a modular, TypeScript ESM architecture with dual transport support and comprehensive tool ecosystem:
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
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
Vibe Coder uses a sophisticated routing approach to select the right tool for each request:
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]
The Tool Registry is a central component for managing tool definitions and execution:
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
The Sequential Thinking mechanism provides LLM-based fallback routing:
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
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
The Workflow system enables multi-step sequences:
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
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.
workflows.json file must be placed in the project root directory (same level as package.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"] } } } }
Workflow step parameters support template strings that can reference:
{workflow.input.paramName}{steps.stepId.output.content[0].text}Use the run-workflow tool with:
Run the newProjectSetup workflow with input {"productDescription": "A task manager app"}
Each tool in the src/tools/ directory includes comprehensive documentation in its own README.md file. These files cover:
Refer to these individual READMEs for in-depth information:
src/tools/fullstack-starter-kit-generator/README.mdsrc/tools/prd-generator/README.mdsrc/tools/research/README.mdsrc/tools/rules-generator/README.mdsrc/tools/task-list-generator/README.mdsrc/tools/user-stories-generator/README.mdsrc/tools/workflow-runner/README.mdsrc/tools/map-codebase/README.mdmap-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.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): Performs deep research on technical topics using Perplexity Sonar, providing summaries and sources.rules-generator): Creates project-specific development rules and guidelines.prd-generator): Generates comprehensive product requirements documents.user-stories-generator): Creates detailed user stories with acceptance criteria.task-list-generator): Builds structured development task lists with dependencies.fullstack-starter-kit-generator): Creates customized project starter kits with specified frontend/backend technologies, including basic setup scripts and configuration.run-workflow): Executes predefined sequences of tool calls for common development tasks.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.
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_ALLOWED_DIR environment variableVIBE_TASK_MANAGER_READ_DIR environment variable (defaults to process.cwd())/private/var/spool/postfix/, /System/, and other unauthorized pathsWrite 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:
Example structure (default location):
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/
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:
For Claude Desktop:
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.mdFor Augment:
For Claude Code/Windsurf/Other MCP Clients:
VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.mdBenefits of Using System Instructions:
# 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\"}"
Interact with the tools via your connected AI assistant:
Research modern JavaScript frameworksCreate development rules for a mobile banking applicationGenerate a PRD for a task management applicationGenerate user stories for an e-commerce websiteCreate a task list for a weather app based on [user stories]Think through the architecture for a microservices-based e-commerce platformCreate a starter kit for a React/Node.js blog application with user authenticationRun workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }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"Curate context for adding authentication to my React app, Generate context package for refactoring the user service, or Analyze this codebase for performance optimization opportunitiesCreate a new project for building a todo app, List all my projects, Run task authentication-setup, What's the status of my React project?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.
VibeCoderOutput/prd-generator/ and task lists from VibeCoderOutput/generated_task_lists/VibeCoderOutput/vibe-task-manager/ following established conventions# 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 project"
"Run the database setup task"
# Project Analysis (Enhanced with Intelligent Lookup)
"Decompose my React project into development tasks"
"Decompose PID-TODO-APP-REACT-001 into tasks" # Using project ID
"Decompose \"Todo App with React\" into tasks" # Using exact name
"Decompose todo into tasks" # Using partial name (fuzzy matching)
"Refine the authentication task to include OAuth support"
"What's the current progress on my mobile app?"
The Vibe Task Manager supports both structured commands and natural language:
Structured Commands:
vibe-task-manager create project "Name" "Description" --optionsvibe-task-manager list projects --status pendingvibe-task-manager run task task-id --forcevibe-task-manager status project-id --detailedNatural Language (Recommended):
For complete documentation, see src/tools/vibe-task-manager/README.md and the system instructions in VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md.
The Vibe Coder MCP project follows an epic-based development approach with comprehensive tracking:
gantt title Vibe Coder MCP Development Progress dateFormat YYYY-MM-DD section Core Infrastructure Tool Registry & Routing :done, epic1, 2024-01-01, 2024-02-15 MCP Server Implementation :done, epic2, 2024-01-15, 2024-03-01 Async Job Management :done, epic3, 2024-02-15, 2024-03-15 section Tool Development Research & Planning Tools :done, epic4, 2024-02-01, 2024-04-01 Code Map Tool :done, epic5, 2024-03-01, 2024-05-15 Vibe Task Manager Core :done, epic6, 2024-04-01, 2024-06-15 section Advanced Features Performance Optimization :active, epic7, 2024-06-01, 2024-07-15 Security Implementation :epic8, 2024-07-01, 2024-08-15 Analytics & Monitoring :epic9, 2024-07-15, 2024-09-01
| 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 |
While the primary use is integration with an AI assistant (using stdio), you can run the server directly for testing:
Production Mode (Stdio):
npm start
Development Mode (Stdio, Pretty Logs):
npm run dev
nodemon and pino-prettySSE Mode (HTTP Interface):
# Production mode over HTTP npm run start:sse # Development mode over HTTP npm run dev:sse
Check Configuration Path:
args array is correct/ even on Windowsnode <path-to-build/index.js> directly to test if Node can find itCheck Configuration Format:
mcpServers object contains your serverRestart the Assistant:
Check Disabled Flag:
"disabled": false is set// comments as JSON doesn't support themVerify autoApprove Array:
autoApprove array match exactly"process-request" to the array if using hybrid routingOpenRouter Key Problems:
Environment Variable Issues:
.env file (for local runs)Build Directory Not Found:
npm run build to ensure the build directory existsFile Permission Errors:
For Local Runs:
LOG_LEVEL=debug in your .env fileFor AI Assistant Runs:
"NODE_ENV": "production" in the env configurationVIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md - Complete usage guide for MCP clientsCI_CD_GUIDE.md - Streamlined pipeline documentation (70% faster)NPM_PUBLISHING_GUIDE.md - Release and deployment processdocs/ARCHITECTURE.md - Comprehensive system architecture with Mermaid diagramsdocs/PERFORMANCE_AND_TESTING.md - Performance metrics, testing strategies, and quality assurancesrc/tools/vibe-task-manager/README.md - Comprehensive task management documentationsrc/tools/curate-context/README.md - Language-agnostic codebase analysis documentationsrc/tools/map-codebase/README.md - Advanced codebase analysis documentationWe welcome contributions! Please see our contributing guidelines and ensure all tests pass before submitting pull requests.
# Run CI checks (REQUIRED before PR - matches GitHub Actions) npm run type-check # TypeScript validation (must pass) npm run lint # Code quality checks (must pass) npm run build # Build verification (must pass) # Run tests locally (RECOMMENDED before PR) npm run test:unit # Fast unit tests (~3 minutes) # Optional: Thorough testing for major changes npm run test:integration npm test # All tests
any types - strict TypeScript requiredProblem: Tools fail with authentication errors
.envProblem: "Path not found" or "Access denied" errors
C:\Users\name to C:/Users/nameVIBE_CODER_OUTPUT_DIR and VIBE_PROJECT_ROOT are set correctly (or legacy variables CODE_MAP_ALLOWED_DIR and VIBE_TASK_MANAGER_READ_DIR)Problem: TypeScript compilation errors
npm run clean && npm run buildnode_modules and package-lock.json, then run npm installnode -v)npm run lintProblem: Tests fail locally or type-check errors in CI
npm run type-check locally to catch issues earlynpm run lint:fix to auto-fix style problems.env file exists with valid OPENROUTER_API_KEYnpm run clean before running testsProblem: High memory usage or slow performance
NODE_OPTIONS='--max-old-space-size=4096' npm startVibeCoderOutput/ if they grow too largenpm run test:memory to identify memory leaksProblem: Server not detected by AI assistant
LOG_LEVEL=debug in configuration for detailed error messages"transport": "stdio" is set correctly"disabled": false in your configurationVibe Task Manager:
VibeCoderOutput/vibe-task-manager/ for project filesCode Map Tool:
CODE_MAP_ALLOWED_DIR is setContext Curator:
Problem: Cannot reach external services
HTTP_PROXY and HTTPS_PROXY environment variables if behind a proxyNODE_TLS_REJECT_UNAUTHORIZED=0 (development only)If issues persist:
LOG_LEVEL=debugnode -v)any types, production-grade code qualityFor full release history, see GitHub Releases
This project is licensed under the MIT License - see the LICENSE file for details.