Skip to content
Back to search

Vibe-Coder-MCP

Vibe-Coder-MCP server extends AI assistants with specialized software development tools.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/freshtechbro--vibe-coder-mcp/badge.svg)](/listings/freshtechbro--vibe-coder-mcp)

HTML

<a href="/listings/freshtechbro--vibe-coder-mcp"><img src="/api/listings/freshtechbro--vibe-coder-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

# Run setup wizard on first use
vibe --setup

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

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,861 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Vibe Coder MCP Server
  2. [![npm version](https://img.shields.io/npm/v/vibe-coder-mcp?style=flat-square&logo=npm&logoColor=white&cacheSeconds=300)](https://www.npmjs.com/package/vibe-coder-mcp)
  3. [![npm downloads](https://img.shields.io/npm/dm/vibe-coder-mcp?style=flat-square&logo=npm&logoColor=white&cacheSeconds=300)](https://www.npmjs.com/package/vibe-coder-mcp)
  4. [![npm total downloads](https://img.shields.io/npm/dt/vibe-coder-mcp?style=flat-square&logo=npm&logoColor=white&cacheSeconds=300)](https://www.npmjs.com/package/vibe-coder-mcp)
  5. [![GitHub release](https://img.shields.io/github/v/release/freshtechbro/Vibe-Coder-MCP?style=flat-square&logo=github&logoColor=white&cacheSeconds=300)](https://github.com/freshtechbro/Vibe-Coder-MCP/releases)
  6. [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
  7. [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square&logo=opensourceinitiative&logoColor=white)](LICENSE)
  8. [![GitHub stars](https://img.shields.io/github/stars/freshtechbro/Vibe-Coder-MCP?style=flat-square&logo=github&logoColor=white&cacheSeconds=300)](https://github.com/freshtechbro/Vibe-Coder-MCP/stargazers)
  9. 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!
  10. ## 🆕 What's New in Version 0.3.5
  11. ### 🎉 Latest Release - Enhanced CLI, REPL, and Parameter Extraction
  12. **Major Improvements:**
  13. - **✨ Complete Hybrid Matcher Overhaul**: All 15 MCP tools now have comprehensive parameter extraction
  14. - **🚀 CLI/REPL Experience**: Interactive confirmations, job status polling with visual progress
  15. - **🔧 Fixed Critical Bugs**: Task-list-generator auto-generates user stories, multi-turn conversations work flawlessly
  16. - **📊 Better Tool Matching**: Multi-strategy approach (keyword 35%, pattern 30%, semantic 15%, LLM 20%)
  17. - **⚡ TypeScript Strict Mode**: Zero `any` types, all explicit typing, production-grade code quality
  18. **User Experience Enhancements:**
  19. - Low-confidence matches now prompt for user confirmation
  20. - Visual progress indicators for long-running jobs
  21. - Cleaner output with JSON log filtering in interactive mode
  22. - Session persistence across commands
  23. - Enhanced error messages and validation feedback
  24. ### Previous Notable Releases
  25. #### Version 0.3.1 - Global Installation & Synchronization
  26. - Fixed global/local version synchronization issues
  27. - Enhanced clean build process for installations
  28. - Improved packaging workflow for NPM publication
  29. #### Version 0.2.8 - CLI Interactive Mode
  30. - Fixed configuration persistence in interactive mode
  31. - Enhanced project root detection for CLI users
  32. - Improved context-aware configuration
  33. #### Version 0.2.3 - Interactive REPL & Setup Wizard
  34. - **Interactive REPL Mode** with chat-style interface and session persistence
  35. - **Enhanced Setup Wizard** with automatic first-run detection
  36. - **Configuration Templates** in `src/config-templates/`
  37. - **Performance Improvements** with optimized memory usage
  38. - **Unified CLI Binary** - single `vibe` command for all operations
  39. ## 🚀 Quick Start
  40. ```bash
  41. # Install globally (recommended)
  42. npm install -g vibe-coder-mcp@latest
  43. # Run setup wizard on first use
  44. vibe --setup
  45. # Or use instantly with npx (no installation)
  46. npx vibe-coder-mcp@latest --setup
  47. ```
  48. **The setup wizard will:**
  49. 1. ✅ Configure your OpenRouter API key
  50. 2. ✅ Set up project directories
  51. 3. ✅ Create configuration files from templates
  52. 4. ✅ Validate your environment
  53. 5. ✅ Get you ready to use all features!
  54. ## 📦 Installation
  55. [![npm version](https://img.shields.io/npm/v/vibe-coder-mcp)](https://www.npmjs.com/package/vibe-coder-mcp)
  56. [![npm downloads](https://img.shields.io/npm/dm/vibe-coder-mcp)](https://www.npmjs.com/package/vibe-coder-mcp)
  57. ```bash
  58. # Recommended: Install globally for the 'vibe' command
  59. npm install -g vibe-coder-mcp@latest
  60. # Or run instantly without installation
  61. npx vibe-coder-mcp@latest
  62. ```
  63. ### Installation Methods
  64. **Global Installation (Recommended)**
  65. ```bash
  66. npm install -g vibe-coder-mcp@latest
  67. # Use the 'vibe' command anywhere
  68. vibe # Start MCP server
  69. vibe "create a PRD for a todo app" # CLI mode
  70. vibe --interactive # Interactive REPL mode
  71. vibe --setup # Setup wizard
  72. ```
  73. **Quick Run with npx**
  74. ```bash
  75. # No installation needed
  76. npx vibe-coder-mcp@latest
  77. npx vibe-coder-mcp@latest "research React best practices"
  78. ```
  79. **Local Project Installation**
  80. ```bash
  81. npm install vibe-coder-mcp
  82. npx vibe-coder-mcp "map the codebase structure"
  83. ```
  84. ### Command Line Usage
  85. ```bash
  86. # MCP Server Mode (for Claude Desktop, Cursor, etc.)
  87. vibe # Start with stdio transport
  88. vibe --sse # Start with Server-Sent Events
  89. # CLI Mode - Natural Language Commands
  90. vibe "research modern JavaScript frameworks"
  91. vibe "create a PRD for an e-commerce platform"
  92. vibe "map the codebase structure" --json
  93. vibe "generate user stories for auth system"
  94. # Interactive REPL Mode
  95. vibe --interactive # Chat interface with context retention
  96. # Configuration
  97. vibe --setup # Run setup wizard
  98. vibe --help # Show all options
  99. vibe --version # Show version
  100. ```
  101. **Interactive Mode Features:**
  102. - Chat-style conversation with context retention
  103. - Live tool execution with progress indicators
  104. - Session persistence and history
  105. - Markdown rendering support
  106. - Multiple themes and customization
  107. - Slash commands for quick actions
  108. ## 🎯 MCP Client Integration (Claude Desktop, Cursor, Cline AI)
  109. ### Quick Integration Guide
  110. Vibe-Coder MCP integrates seamlessly with any MCP-compatible client. Here's how to configure it:
  111. #### Option 1: Using NPX (Recommended)
  112. In your MCP client's server configuration dialog:
  113. - **Server Name**: `vibe-coder-mcp`
  114. - **Command/URL**: `npx`
  115. - **Arguments**: `vibe-coder-mcp`
  116. - **Environment Variables**:
  117. - `OPENROUTER_API_KEY`: Your OpenRouter API key (required)
  118. - `VIBE_PROJECT_ROOT`: `/path/to/your/project` (required)
  119. - `LOG_LEVEL`: `info` (optional)
  120. - `NODE_ENV`: `production` (optional)
  121. #### Option 2: Global Installation
  122. ```bash
  123. # First install globally
  124. npm install -g vibe-coder-mcp
  125. ```
  126. Then configure:
  127. - **Command/URL**: `vibe`
  128. - **Arguments**: (leave empty)
  129. - **Environment Variables**: Same as Option 1
  130. #### Option 3: Node with Full Path
  131. - **Command/URL**: `node`
  132. - **Arguments**: `/path/to/node_modules/vibe-coder-mcp/build/index.js`
  133. - **Environment Variables**: Same as Option 1
  134. ### Claude Desktop Specific Configuration
  135. For Claude Desktop users, add this to your `claude_desktop_config.json`:
  136. ```json
  137. {
  138. "mcpServers": {
  139. "vibe-coder-mcp": {
  140. "command": "npx",
  141. "args": ["vibe-coder-mcp"],
  142. "env": {
  143. "OPENROUTER_API_KEY": "your-openrouter-api-key",
  144. "VIBE_PROJECT_ROOT": "/path/to/your/project",
  145. "LOG_LEVEL": "info",
  146. "NODE_ENV": "production"
  147. }
  148. }
  149. }
  150. }
  151. ```
  152. See `example_claude_desktop_config.json` for a complete example.
  153. ### Available Tools After Integration
  154. Once configured, your MCP client will have access to:
  155. - **vibe-task-manager**: AI-native task management with RDD methodology
  156. - **research-manager**: Deep research using Perplexity integration
  157. - **map-codebase**: Advanced codebase analysis (35+ languages)
  158. - **curate-context**: Intelligent context curation for AI development
  159. - **generate-prd**: Product requirements document generator
  160. - **generate-user-stories**: User story generator
  161. - **generate-task-list**: Task list generator
  162. - **generate-fullstack-starter-kit**: Project scaffolding tool
  163. - **run-workflow**: Multi-step workflow execution
  164. ### Testing Your Integration
  165. After configuration, test by asking your AI assistant:
  166. - "Use vibe to research React best practices"
  167. - "Map the codebase for this project"
  168. - "Generate a PRD for a task management app"
  169. ## 🆕 Unified Project Root Configuration
  170. ### Zero Configuration for CLI Users
  171. ```bash
  172. # Automatic project detection - just run from your project!
  173. cd /path/to/your/project
  174. vibe "map the codebase structure"
  175. ```
  176. ### Simple Configuration for MCP Clients
  177. ```json
  178. {
  179. "env": {
  180. "OPENROUTER_API_KEY": "your_key_here",
  181. "VIBE_PROJECT_ROOT": "/path/to/your/project"
  182. }
  183. }
  184. ```
  185. - **One Variable**: `VIBE_PROJECT_ROOT` replaces multiple directory configs
  186. - **Auto-Detection**: CLI automatically detects project root
  187. - **Backward Compatible**: Legacy variables still supported
  188. ## 🔧 Environment Configuration
  189. **Required:** You need an OpenRouter API key to use Vibe Coder MCP.
  190. ### Get Your OpenRouter API Key
  191. 1. Visit [openrouter.ai](https://openrouter.ai/)
  192. 2. Create an account if you don't have one
  193. 3. Navigate to API Keys section
  194. 4. Create a new API key and copy it
  195. ### Set Up Environment Variables
  196. **Option 1: Using Setup Wizard (Recommended for v0.2.3+)**
  197. ```bash
  198. # Run the interactive setup wizard
  199. vibe --setup
  200. # The wizard will:
  201. # • Configure your OpenRouter API key
  202. # • Set up project directories
  203. # • Create configuration files
  204. # • Validate your setup
  205. ```
  206. **Option 2: Environment Variables**
  207. ```bash
  208. # Set your OpenRouter API key
  209. export OPENROUTER_API_KEY="your_api_key_here"
  210. # Optional: Set custom directories
  211. export VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
  212. export VIBE_PROJECT_ROOT="/path/to/your/project"
  213. # Legacy variables (still supported for backward compatibility)
  214. export CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"
  215. export VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"
  216. ```
  217. **Option 3: Create .env file (templates provided in v0.2.3+)**
  218. Create a `.env` file in your working directory (or copy from `src/config-templates/.env.template`):
  219. ```dotenv
  220. # Required: Your OpenRouter API key
  221. OPENROUTER_API_KEY="your_api_key_here"
  222. # Optional: Unified project root configuration
  223. VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
  224. VIBE_PROJECT_ROOT="/path/to/your/project"
  225. VIBE_USE_PROJECT_ROOT_AUTO_DETECTION="true"
  226. # Legacy variables (still supported for backward compatibility)
  227. CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"
  228. VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"
  229. # Optional: Other settings
  230. OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
  231. GEMINI_MODEL="google/gemini-2.5-flash-preview-05-20"
  232. ```
  233. ### Directory Configuration (Unified & Simplified)
  234. **🆕 Unified Configuration (Recommended)**
  235. - **VIBE_PROJECT_ROOT**: Single variable for all project operations (automatic detection enabled by default for CLI)
  236. - **VIBE_USE_PROJECT_ROOT_AUTO_DETECTION**: Enable automatic project root detection for CLI users (default: `"true"`)
  237. - **VIBE_CODER_OUTPUT_DIR**: Where generated files are saved (default: `./VibeCoderOutput/`)
  238. **Legacy Configuration (Still Supported)**
  239. - **CODE_MAP_ALLOWED_DIR**: Security boundary for code analysis (fallback if VIBE_PROJECT_ROOT not set)
  240. - **VIBE_TASK_MANAGER_READ_DIR**: Security boundary for task manager operations (fallback if VIBE_PROJECT_ROOT not set)
  241. **Auto-Detection Benefits:**
  242. - **Zero Configuration**: CLI users get automatic project root detection
  243. - **Context Aware**: Different behavior for CLI vs MCP client usage
  244. - **Intelligent Fallbacks**: 5-priority resolution chain ensures reliable operation
  245. ## 🔌 MCP Client Setup
  246. Configure your AI assistant to connect to Vibe Coder MCP:
  247. ### For Cursor AI / Windsurf / VS Code MCP Clients
  248. Add this to your MCP settings (usually in `settings.json`):
  249. ```json
  250. {
  251. "mcpServers": {
  252. "vibe-coder-mcp": {
  253. "command": "npx",
  254. "args": ["vibe-coder-mcp"],
  255. "env": {
  256. "OPENROUTER_API_KEY": "your_api_key_here"
  257. }
  258. }
  259. }
  260. }
  261. ```
  262. ### For Claude Desktop
  263. Add this to your `claude_desktop_config.json`:
  264. ```json
  265. {
  266. "mcpServers": {
  267. "vibe-coder-mcp": {
  268. "command": "npx",
  269. "args": ["vibe-coder-mcp"],
  270. "env": {
  271. "OPENROUTER_API_KEY": "your_api_key_here",
  272. "VIBE_PROJECT_ROOT": "/path/to/your/project"
  273. }
  274. }
  275. }
  276. }
  277. ```
  278. ## 💻 CLI Usage Guide
  279. Vibe Coder includes a powerful command-line interface with multiple modes for direct interaction with all tools.
  280. ### Interactive Setup Wizard (Enhanced in v0.2.3)
  281. ```bash
  282. # First-time setup (runs automatically on first use)
  283. vibe --setup
  284. # Features:
  285. # • Smart first-run detection
  286. # • OS-specific configuration paths
  287. # • Non-interactive mode for CI/CD
  288. # • Configuration validation
  289. # • Backup system for existing configs
  290. # Reconfigure existing installation
  291. vibe --reconfigure
  292. ```
  293. ### Interactive REPL Mode (NEW in v0.2.3!)
  294. ```bash
  295. # Start interactive chat session
  296. vibe --interactive
  297. # Or with alias
  298. vibe -i
  299. # Resume a previous session
  300. vibe --resume <session-id>
  301. ```
  302. **REPL Features:**
  303. - 🎯 **Chat Interface**: Natural conversation flow with context retention
  304. - 📝 **Multi-line Input**: Use `"""` for multi-line messages
  305. - 🎨 **Themes**: Multiple color themes with `/theme` command
  306. - 💾 **Session Management**: Auto-save and resume capabilities
  307. - 📊 **Markdown Rendering**: Rich text formatting in responses
  308. - ⚡ **Live Progress**: Real-time execution feedback
  309. - 🔧 **Slash Commands**: Quick actions like `/tools`, `/history`, `/save`
  310. - 🎮 **Auto-completion**: Tab completion for commands and tools
  311. ### CLI Command Examples
  312. #### Research & Analysis
  313. ```bash
  314. vibe "research modern React patterns and best practices"
  315. vibe "analyze current trends in microservices architecture"
  316. vibe "research security best practices for Node.js APIs"
  317. ```
  318. #### Project Planning
  319. ```bash
  320. vibe "create a PRD for an e-commerce platform with user authentication"
  321. vibe "generate user stories for authentication system"
  322. vibe "create development tasks from user stories"
  323. ```
  324. #### Code Analysis & Generation
  325. ```bash
  326. vibe "map the codebase structure"
  327. vibe "create context for implementing authentication"
  328. vibe "generate a fullstack starter kit for e-commerce"
  329. vibe "create coding standards for TypeScript projects"
  330. ```
  331. #### Task Management
  332. ```bash
  333. vibe "create a new project for building a todo app"
  334. vibe "list all my projects"
  335. vibe "show project status for MyApp"
  336. vibe "create high priority task for implementing OAuth"
  337. ```
  338. ### CLI Options
  339. ```bash
  340. # Output formats
  341. vibe "research React hooks" --json
  342. vibe "create PRD for todo app" --yaml
  343. # Verbosity control
  344. vibe "create project MyApp" --verbose
  345. vibe "research Node.js patterns" --quiet
  346. # Interactive REPL mode (NEW!)
  347. vibe --interactive
  348. vibe -i
  349. # Session management (NEW!)
  350. vibe --resume <session-id>
  351. vibe --list-sessions
  352. ```
  353. ### Interactive REPL Commands (v0.2.3+)
  354. Once in interactive mode (`vibe --interactive`), use these commands:
  355. ```bash
  356. # Help and navigation
  357. /help # Show available commands
  358. /tools # List all MCP tools
  359. /status # Show session status
  360. # Session management
  361. /save # Save current session
  362. /sessions # List saved sessions
  363. /export [file] # Export session to markdown
  364. # Conversation control
  365. /clear # Clear conversation history
  366. /history # Show conversation history
  367. # Customization
  368. /theme # Change color theme
  369. /markdown # Toggle markdown rendering
  370. /config # Manage configuration
  371. # Exit
  372. /quit or /exit # Exit interactive mode
  373. ```
  374. ### File Organization
  375. Generated files are automatically organized in `VibeCoderOutput/`:
  376. ```
  377. VibeCoderOutput/
  378. ├── research/ # Research reports
  379. ├── prd-generator/ # Product requirements
  380. ├── user-stories-generator/ # User stories
  381. ├── task-list-generator/ # Development tasks
  382. ├── fullstack-starter-kit-generator/ # Project templates
  383. ├── map-codebase/ # Code analysis
  384. ├── vibe-task-manager/ # Task management data
  385. └── workflow-runner/ # Workflow outputs
  386. ```
  387. ---
  388. ## 🔄 Migration Guide (v0.2.3)
  389. ### Breaking Changes
  390. **None!** Version 0.2.3 is fully backward compatible. All existing configurations and workflows continue to work.
  391. ### Technical Improvements
  392. - Unified CLI architecture with single entry point
  393. - Better error handling and recovery
  394. - Improved resource cleanup
  395. - Enhanced type safety throughout codebase
  396. - Memory leak prevention in long-running sessions
  397. - **CI/CD Pipeline Optimization**:
  398. - 70% faster execution (~3 minutes vs ~10 minutes)
  399. - Focused on essential checks: type-check, lint, build
  400. - Unit tests moved to local development workflow
  401. - See [CI/CD Guide](./CI_CD_GUIDE.md) for details
  402. - Memory usage optimized for large codebases
  403. - Faster first-run experience with smart detection
  404. ---
  405. ## 📚 Development Setup (Advanced)
  406. If you want to contribute to development or run from source, follow the detailed setup guide below.
  407. ## Overview & Features
  408. Vibe Coder MCP integrates with MCP-compatible clients to provide the following capabilities:
  409. ### 🚀 **Core Architecture**
  410. * **Quad Transport Support**: stdio, SSE, WebSocket, and HTTP transport protocols for maximum client compatibility
  411. * **Dynamic Port Allocation**: Intelligent port management with conflict resolution and graceful degradation
  412. * **Semantic Request Routing**: Intelligently routes requests using embedding-based semantic matching with sequential thinking fallbacks
  413. * **Tool Registry Architecture**: Centralized tool management with self-registering tools
  414. * **Unified Communication Protocol**: Agent coordination across all transport mechanisms with real-time notifications
  415. * **Session State Management**: Maintains context across requests within sessions
  416. ### 🧠 **AI-Native Task Management**
  417. * **Vibe Task Manager**: Production-ready task management with 99.9% test success rate and comprehensive integration *(Functional but actively being enhanced)*
  418. * **Natural Language Processing**: 21 supported intents with multi-strategy recognition (pattern matching + LLM fallback)
  419. * **Recursive Decomposition Design (RDD)**: Intelligent project breakdown into atomic tasks
  420. * **Agent Orchestration**: Multi-agent coordination with capability mapping, load balancing, and real-time status synchronization
  421. * **Multi-Transport Agent Support**: Full integration across stdio, SSE, WebSocket, and HTTP transports
  422. * **Real Storage Integration**: Zero mock code policy - all production integrations
  423. * **Artifact Parsing Integration**: Seamless integration with PRD Generator and Task List Generator outputs
  424. * **Session Persistence**: Enhanced session tracking with orchestration workflow triggers
  425. * **Comprehensive CLI**: Natural language command-line interface with extensive functionality
  426. ### 🔍 **Advanced Code Analysis & Context Curation**
  427. * **Code Map Tool**: 35+ programming language support with 95-97% token reduction optimization
  428. * **Context Curation Tool**: Language-agnostic project detection with 95%+ accuracy across 35+ languages
  429. * **Intelligent Codemap Caching**: Configurable caching system that reuses recent codemaps to optimize workflow performance
  430. * **Enhanced Import Resolution**: Third-party integration for accurate dependency mapping
  431. * **Multi-Strategy File Discovery**: 4 parallel strategies for comprehensive analysis
  432. * **Memory Optimization**: Sophisticated caching and resource management
  433. * **Security Boundaries**: Separate read/write path validation for secure operations
  434. ### 📋 **Research & Planning Suite**
  435. * **Research Tool**: Deep research using Perplexity Sonar via OpenRouter
  436. * **Context Curation**: Intelligent codebase analysis with 8-phase workflow pipeline and intelligent codemap caching for AI-driven development
  437. * **Document Generators**: PRDs (`prd-generator`), user stories (`user-stories-generator`), task lists (`task-list-generator`), development rules (`rules-generator`)
  438. * **Project Scaffolding**: Full-stack starter kits (`fullstack-starter-kit-generator`) with dynamic template generation
  439. * **Workflow Execution**: Predefined sequences of tool calls defined in `workflows.json`
  440. ### ⚡ **Performance & Reliability**
  441. * **Asynchronous Execution**: Job-based processing with real-time status tracking
  442. * **Performance Optimized**: <200ms response times, <400MB memory usage
  443. * **Comprehensive Testing**: 99.9% test success rate across 2,100+ tests with full integration validation
  444. * **Production Ready**: Zero mock implementations, real service integrations
  445. * **Enhanced Error Handling**: Advanced error recovery with automatic retry, escalation, and pattern analysis
  446. * **Dynamic Port Management**: Intelligent port allocation with conflict resolution and graceful degradation
  447. * **Real-Time Monitoring**: Agent health monitoring, task execution tracking, and performance analytics
  448. *(See "Detailed Tool Documentation" and "Feature Details" sections below for more)*
  449. ## Development Setup Guide
  450. **For developers who want to run from source or contribute to the project.**
  451. ### Step 1: Prerequisites
  452. 1. **Check Node.js Version:**
  453. * Open a terminal or command prompt.
  454. * Run `node -v`
  455. * Ensure the output shows v20.0.0 or higher (required).
  456. * If not installed or outdated: Download from [nodejs.org](https://nodejs.org/).
  457. 2. **Check Git Installation:**
  458. * Open a terminal or command prompt.
  459. * Run `git --version`
  460. * If not installed: Download from [git-scm.com](https://git-scm.com/).
  461. 3. **Get OpenRouter API Key:**
  462. * Visit [openrouter.ai](https://openrouter.ai/)
  463. * Create an account if you don't have one.
  464. * Navigate to API Keys section.
  465. * Create a new API key and copy it.
  466. * Keep this key handy for Step 4.
  467. ### Step 2: Get the Code
  468. 1. **Create a Project Directory** (optional):
  469. * Open a terminal or command prompt.
  470. * Navigate to where you want to store the project:
  471. ```bash
  472. cd ~/Documents # Example: Change to your preferred location
  473. ```
  474. 2. **Clone the Repository:**
  475. * Run:
  476. ```bash
  477. git clone https://github.com/freshtechbro/vibe-coder-mcp.git
  478. ```
  479. (Or use your fork's URL if applicable)
  480. 3. **Navigate to Project Directory:**
  481. * Run:
  482. ```bash
  483. cd vibe-coder-mcp
  484. ```
  485. ### Step 3: Run the Setup Script
  486. Choose the appropriate script for your operating system:
  487. **For Windows:**
  488. 1. In your terminal (still in the vibe-coder-mcp directory), run:
  489. ```batch
  490. setup.bat
  491. ```
  492. 2. Wait for the script to complete (it will install dependencies, build the project, and create necessary directories).
  493. 3. If you see any error messages, refer to the Troubleshooting section below.
  494. **For macOS or Linux:**
  495. 1. Make the script executable:
  496. ```bash
  497. chmod +x setup.sh
  498. ```
  499. 2. Run the script:
  500. ```bash
  501. ./setup.sh
  502. ```
  503. 3. Wait for the script to complete.
  504. 4. If you see any error messages, refer to the Troubleshooting section below.
  505. The script performs these actions:
  506. * Checks Node.js version (v20+ required)
  507. * Installs all dependencies via npm
  508. * Creates necessary `VibeCoderOutput/` subdirectories
  509. * Builds the TypeScript project
  510. * **Creates configuration from templates** if not present (v0.2.3+)
  511. * Sets executable permissions (on Unix systems)
  512. **Note**: The setup process is now faster (v0.2.3+) with optimized dependency installation and simplified build process.
  513. ### Step 4: Configure Environment Variables
  514. **New in v0.2.3**: Configuration templates are provided in `src/config-templates/` for easy setup.
  515. #### Option A: Use the Setup Wizard (Recommended)
  516. ```bash
  517. vibe --setup
  518. ```
  519. The wizard will guide you through configuration and create all necessary files.
  520. #### Option B: Manual Configuration
  521. 1. **Copy templates** (if not already done by setup script):
  522. ```bash
  523. cp src/config-templates/.env.template .env
  524. cp src/config-templates/llm_config.template.json llm_config.json
  525. cp src/config-templates/mcp-config.template.json mcp-config.json
  526. ```
  527. 2. **Edit `.env` file** with your configuration:
  528. ```dotenv
  529. # OpenRouter Configuration (REQUIRED)
  530. OPENROUTER_API_KEY="your_actual_api_key_here"
  531. # Optional configurations
  532. OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
  533. GEMINI_MODEL=google/gemini-2.5-flash-preview-05-20
  534. # Project directories (optional - auto-detected for CLI users)
  535. VIBE_PROJECT_ROOT=/path/to/your/project
  536. VIBE_CODER_OUTPUT_DIR=/path/to/output
  537. ```
  538. 3. **Configure Output Directory (Optional):**
  539. * To change where generated files are saved (default is `VibeCoderOutput/` inside the project), add this line to your `.env` file:
  540. ```dotenv
  541. VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
  542. ```
  543. * 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.
  544. 4. **🆕 Configure Unified Project Root (Recommended):**
  545. * To set up the new unified project root configuration, add this line to your `.env` file:
  546. ```dotenv
  547. VIBE_PROJECT_ROOT=/path/to/your/project/root
  548. ```
  549. * Replace the path with the **absolute path** to your project's root directory.
  550. * **Benefits**: Single configuration variable for all tools (Code Map Generator, Task Manager, Context Curator)
  551. * **Auto-Detection**: For CLI users, project root is automatically detected from the current working directory
  552. * **Backward Compatibility**: Legacy variables are still supported if you prefer separate configurations
  553. 5. **Legacy Directory Configuration (Optional):**
  554. * If you prefer separate directory configurations, you can still use the original variables:
  555. ```dotenv
  556. CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
  557. VIBE_TASK_MANAGER_READ_DIR=/path/to/your/project/source/directory
  558. ```
  559. * **Note**: These variables work as fallbacks if `VIBE_PROJECT_ROOT` is not set
  560. * **Security**: All variables work with the strict filesystem security implementation
  561. 6. **Review Other Settings (Optional):**
  562. * 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`).
  563. 7. **Save the `.env` File.**
  564. ### Step 5: Integrate with Your AI Assistant (MCP Settings)
  565. This crucial step connects Vibe Coder to your AI assistant by adding its configuration to the client's MCP settings file.
  566. #### 5.1: Locate Your Client's MCP Settings File
  567. The location varies depending on your AI assistant:
  568. * **Cursor AI / Windsurf / RooCode (VS Code based):**
  569. 1. Open the application.
  570. 2. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`).
  571. 3. Type and select `Preferences: Open User Settings (JSON)`.
  572. 4. This opens your `settings.json` file where the `mcpServers` object should reside.
  573. * **Cline AI (VS Code Extension):**
  574. * **Windows**: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
  575. * **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  576. * **Linux**: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  577. * *(Note: If using standard VS Code instead of Cursor, replace `Cursor` with `Code` in the path)*
  578. * **Claude Desktop:**
  579. * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  580. * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  581. * **Linux**: `~/.config/Claude/claude_desktop_config.json`
  582. #### 5.2: Add the Vibe Coder Configuration
  583. 1. Open the settings file identified above in a text editor.
  584. 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": {}}`.
  585. 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.
  586. ```json
  587. // This is the unique identifier for this MCP server instance within your client's settings
  588. "vibe-coder-mcp": {
  589. // Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH
  590. "command": "node",
  591. // Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point
  592. // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
  593. "args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"],
  594. // Sets the current working directory for the server process when it runs
  595. // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
  596. "cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
  597. // Defines the communication transport protocol between the client and server
  598. "transport": "stdio",
  599. // Environment variables to be passed specifically to the Vibe Coder server process when it starts
  600. // API Keys should be in the .env file, NOT here
  601. "env": {
  602. // Absolute path to the LLM configuration file used by Vibe Coder
  603. // !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
  604. "LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json",
  605. // Sets the logging level for the server
  606. "LOG_LEVEL": "debug",
  607. // Specifies the runtime environment
  608. "NODE_ENV": "production",
  609. // Directory where Vibe Coder tools will save their output files
  610. // !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
  611. "VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput",
  612. // 🆕 Unified project root for all tools (recommended)
  613. // This single variable configures all tools with the same project boundary
  614. "VIBE_PROJECT_ROOT": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
  615. // Legacy variables (optional - used as fallbacks if VIBE_PROJECT_ROOT not set)
  616. "CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src",
  617. "VIBE_TASK_MANAGER_READ_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP"
  618. },
  619. // A boolean flag to enable (false) or disable (true) this server configuration
  620. "disabled": false,
  621. // A list of tool names that the MCP client is allowed to execute automatically
  622. "autoApprove": [
  623. "research",
  624. "rules-generator",
  625. "user-stories-generator",
  626. "task-list-generator",
  627. "prd-generator",
  628. "fullstack-starter-kit-generator",
  629. "refactor-code",
  630. "git-summary",
  631. "run-workflow",
  632. "map-codebase"
  633. ]
  634. }
  635. ```
  636. 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.
  637. 5. Save the settings file.
  638. 6. **Completely close and restart** your AI assistant application (Cursor, VS Code, Claude Desktop, etc.) for the changes to take effect.
  639. ### Step 6: Test Your Configuration
  640. 1. **Start Your AI Assistant:**
  641. * Completely restart your AI assistant application.
  642. 2. **Test a Simple Command:**
  643. * Type a test command like: `Research modern JavaScript frameworks`
  644. 3. **Check for Proper Response:**
  645. * If working correctly, you should receive a research response.
  646. * If not, check the Troubleshooting section below.
  647. ## AI Agent Integration
  648. 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.
  649. ### System Instructions File
  650. 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.
  651. ### Platform-Specific Integration
  652. #### Claude Desktop
  653. Place the system instructions in your project's system instructions or custom instructions:
  654. 1. Open Claude Desktop
  655. 2. Navigate to project settings
  656. 3. Add the contents of `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md` to the system instructions field
  657. 4. Save and restart Claude Desktop
  658. #### ChatGPT
  659. Add the system instructions to your custom instructions or project settings:
  660. 1. Open ChatGPT settings
  661. 2. Navigate to custom instructions or project configuration
  662. 3. Paste the contents of `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
  663. 4. Save the configuration
  664. #### VS Code Extensions (Cline, Roo Coder, Augment)
  665. Integrate the system instructions into your extension's configuration:
  666. 1. **Cline**: Place in system instructions or memories section
  667. 2. **Roo Coder**: Add to system instructions or rules folder
  668. 3. **Augment**: Place in system instructions or memories
  669. 4. **Other VS Code forks**: Place in system instructions or rules folder with "always active" setting
  670. #### General MCP Clients
  671. For other MCP-compatible clients:
  672. 1. Locate the system instructions or rules configuration
  673. 2. Add the contents of `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
  674. 3. Set as "always active" or "persistent" if the option is available
  675. 4. Restart the client to apply changes
  676. ### Key Integration Benefits
  677. - **Comprehensive Tool Knowledge**: Agents learn about all 15+ available tools and their capabilities
  678. - **Workflow Orchestration**: Guidance on chaining tools together for complex development workflows
  679. - **Job Polling Protocol**: Critical instructions for handling asynchronous operations correctly
  680. - **Best Practices**: Performance optimization and error handling strategies
  681. - **Integration Patterns**: Common workflows for research, planning, and implementation
  682. ### Usage Examples
  683. Once integrated, your AI agents will be able to:
  684. ```bash
  685. # Research-driven development
  686. "Research modern React patterns, then create a PRD and generate user stories"
  687. # Complete project setup
  688. "Set up a new e-commerce project with React frontend and Node.js backend"
  689. # Context-aware development
  690. "Analyze this codebase and suggest improvements with implementation tasks"
  691. # Multi-agent coordination
  692. "Register frontend and backend agents, then distribute authentication tasks"
  693. ```
  694. ### Verification
  695. To verify successful integration:
  696. 1. Ask your AI agent about available Vibe Coder tools
  697. 2. Request a workflow that uses multiple tools in sequence
  698. 3. Check that the agent follows proper job polling protocols
  699. 4. Confirm that outputs are saved to the correct directories
  700. ## 🎯 Unified CLI Architecture (v0.2.3+)
  701. The new unified CLI (`unified-cli.ts`) provides a single entry point for all Vibe Coder operations:
  702. ```mermaid
  703. flowchart TD
  704. Start[vibe command] --> Detect{First Run?}
  705. Detect -->|Yes| Setup[Setup Wizard]
  706. Detect -->|No| Parse[Parse Arguments]
  707. Setup --> Config[Save Configuration]
  708. Config --> Parse
  709. Parse --> Mode{Mode?}
  710. Mode -->|--interactive| REPL[Interactive REPL]
  711. Mode -->|"message"| CLI[CLI Execution]
  712. Mode -->|none| MCP[MCP Server]
  713. Mode -->|--setup| Setup
  714. REPL --> Session[Session Management]
  715. Session --> Chat[Chat Interface]
  716. Chat --> Tools[Tool Execution]
  717. CLI --> Router[Hybrid Router]
  718. Router --> Tools
  719. MCP --> Transport{Transport?}
  720. Transport -->|stdio| Stdio[Stdio Server]
  721. Transport -->|sse| SSE[SSE Server]
  722. ```
  723. **Benefits of Unified CLI:**
  724. - Single binary for all operations (`vibe`)
  725. - Consistent command interface
  726. - Shared configuration management
  727. - Seamless mode switching
  728. - Better resource utilization
  729. ## Project Architecture
  730. The Vibe Coder MCP server follows a modular, TypeScript ESM architecture with dual transport support and comprehensive tool ecosystem:
  731. ```mermaid
  732. flowchart TD
  733. subgraph "Core Architecture"
  734. Init[index.ts] --> Config[Configuration Loader]
  735. Config --> Transport{Transport Type}
  736. Transport --> |stdio| StdioTransport[Stdio Transport]
  737. Transport --> |sse| SSETransport[SSE Transport]
  738. StdioTransport --> Server[MCP Server]
  739. SSETransport --> Server
  740. Server --> ToolReg[Tool Registry]
  741. ToolReg --> InitEmbed[Initialize Embeddings]
  742. InitEmbed --> Ready[Server Ready]
  743. end
  744. subgraph "Request Processing"
  745. Req[Client Request] --> SessionMgr[Session Manager]
  746. SessionMgr --> Router[Hybrid Router]
  747. Router --> Semantic[Semantic Matcher]
  748. Router --> Sequential[Sequential Thinking]
  749. Semantic --> |High Confidence| Execute[Tool Execution]
  750. Sequential --> |Fallback| Execute
  751. Execute --> JobMgr[Job Manager]
  752. JobMgr --> Response[Response to Client]
  753. end
  754. subgraph "Tool Ecosystem"
  755. Execute --> Research[Research Tool]
  756. Execute --> TaskMgr[Vibe Task Manager]
  757. Execute --> CodeMap[Code Map Tool]
  758. Execute --> FullStack[Fullstack Generator]
  759. Execute --> PRDGen[PRD Generator]
  760. Execute --> UserStories[User Stories Generator]
  761. Execute --> TaskList[Task List Generator]
  762. Execute --> Rules[Rules Generator]
  763. Execute --> Workflow[Workflow Runner]
  764. end
  765. subgraph "Support Services"
  766. JobMgr --> AsyncJobs[Async Job Processing]
  767. Execute --> FileOps[File Operations]
  768. Execute --> LLMHelper[LLM Integration]
  769. Execute --> ErrorHandler[Error Handling]
  770. Execute --> StateManager[Session State]
  771. end
  772. subgraph "Configuration & Security"
  773. Config --> LLMConfig[LLM Config Mapping]
  774. Config --> MCPConfig[MCP Tool Config]
  775. Config --> EnvVars[Environment Variables]
  776. FileOps --> SecurityBoundary[Security Boundaries]
  777. SecurityBoundary --> ReadOps[Read Operations]
  778. SecurityBoundary --> WriteOps[Write Operations]
  779. end
  780. ```
  781. ## Directory Structure
  782. ```
  783. vibe-coder-mcp/
  784. ├── .env # Environment configuration
  785. ├── .env.example # Environment template
  786. ├── llm_config.json # LLM model mappings
  787. ├── mcp-config.json # MCP tool configurations
  788. ├── package.json # Project dependencies
  789. ├── README.md # This documentation
  790. ├── VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md # System prompt documentation
  791. ├── setup.bat # Windows setup script
  792. ├── setup.sh # macOS/Linux setup script
  793. ├── tsconfig.json # TypeScript configuration
  794. ├── vitest.config.ts # Vitest (testing) configuration
  795. ├── workflows.json # Workflow definitions
  796. ├── build/ # Compiled JavaScript (after build)
  797. ├── docs/ # Additional documentation
  798. │ ├── map-codebase/ # Code Map Tool docs
  799. │ ├── handover/ # Development handover docs
  800. │ └── *.md # Various documentation files
  801. ├── VibeCoderOutput/ # Tool output directory
  802. │ ├── research/ # Research reports
  803. │ ├── rules-generator/ # Development rules
  804. │ ├── prd-generator/ # Product requirements
  805. │ ├── user-stories-generator/ # User stories
  806. │ ├── task-list-generator/ # Task lists
  807. │ ├── fullstack-starter-kit-generator/ # Project templates
  808. │ ├── map-codebase/ # Code maps and diagrams
  809. │ ├── vibe-task-manager/ # Task management data
  810. │ └── workflow-runner/ # Workflow outputs
  811. └── src/ # Source code
  812. ├── index.ts # Entry point
  813. ├── logger.ts # Logging configuration (Pino)
  814. ├── server.ts # MCP server setup
  815. ├── services/ # Core services
  816. │ ├── routing/ # Semantic routing system
  817. │ │ ├── embeddingStore.ts # Embedding management
  818. │ │ ├── hybridMatcher.ts # Hybrid routing logic
  819. │ │ └── toolRegistry.ts # Tool registry
  820. │ ├── sse-notifier/ # SSE notification system
  821. │ ├── JobManager.ts # Async job management
  822. │ └── ToolService.ts # Tool execution service
  823. ├── tools/ # MCP Tools
  824. │ ├── index.ts # Tool registration
  825. │ ├── sequential-thinking.ts # Fallback routing
  826. │ ├── map-codebase/ # Code analysis tool
  827. │ │ ├── cache/ # Memory management
  828. │ │ ├── grammars/ # Tree-sitter grammars
  829. │ │ ├── importResolvers/ # Import resolution adapters
  830. │ │ └── *.ts # Core implementation
  831. │ ├── fullstack-starter-kit-generator/ # Project scaffolding
  832. │ ├── prd-generator/ # PRD creation
  833. │ ├── research/ # Research tool
  834. │ ├── rules-generator/ # Rule generation
  835. │ ├── task-list-generator/ # Task list generation
  836. │ ├── user-stories-generator/ # User story generation
  837. │ ├── vibe-task-manager/ # AI-native task management
  838. │ │ ├── __tests__/ # Comprehensive test suite
  839. │ │ ├── cli/ # Command-line interface
  840. │ │ ├── core/ # Core algorithms
  841. │ │ ├── integrations/ # Tool integrations
  842. │ │ ├── prompts/ # LLM prompts (YAML)
  843. │ │ ├── services/ # Business logic services
  844. │ │ ├── types/ # TypeScript definitions
  845. │ │ └── utils/ # Utility functions
  846. │ └── workflow-runner/ # Workflow execution engine
  847. ├── types/ # TypeScript type definitions
  848. └── utils/ # Shared utilities
  849. ├── configLoader.ts # Configuration management
  850. ├── errors.ts # Error handling
  851. └── llmHelper.ts # LLM integration helpers
  852. ```
  853. ## Semantic Routing System
  854. Vibe Coder uses a sophisticated routing approach to select the right tool for each request:
  855. ```mermaid
  856. flowchart TD
  857. Start[Client Request] --> Process[Process Request]
  858. Process --> Hybrid[Hybrid Matcher]
  859. subgraph "Primary: Semantic Routing"
  860. Hybrid --> Semantic[Semantic Matcher]
  861. Semantic --> Embeddings[Query Embeddings]
  862. Embeddings --> Tools[Tool Embeddings]
  863. Tools --> Compare[Compare via Cosine Similarity]
  864. Compare --> Score[Score & Rank Tools]
  865. Score --> Confidence{High Confidence?}
  866. end
  867. Confidence -->|Yes| Registry[Tool Registry]
  868. subgraph "Fallback: Sequential Thinking"
  869. Confidence -->|No| Sequential[Sequential Thinking]
  870. Sequential --> LLM[LLM Analysis]
  871. LLM --> ThoughtChain[Thought Chain]
  872. ThoughtChain --> Extraction[Extract Tool Name]
  873. Extraction --> Registry
  874. end
  875. Registry --> Executor[Execute Tool]
  876. Executor --> Response[Return Response]
  877. ```
  878. ## Tool Registry Pattern
  879. The Tool Registry is a central component for managing tool definitions and execution:
  880. ```mermaid
  881. flowchart TD
  882. subgraph "Tool Registration (at import)"
  883. Import[Import Tool] --> Register[Call registerTool]
  884. Register --> Store[Store in Registry Map]
  885. end
  886. subgraph "Tool Definition"
  887. Def[ToolDefinition] --> Name[Tool Name]
  888. Def --> Desc[Description]
  889. Def --> Schema[Zod Schema]
  890. Def --> Exec[Executor Function]
  891. end
  892. subgraph "Server Initialization"
  893. Init[server.ts] --> Import
  894. Init --> GetAll[getAllTools]
  895. GetAll --> Loop[Loop Through Tools]
  896. Loop --> McpReg[Register with MCP Server]
  897. end
  898. subgraph "Tool Execution"
  899. McpReg --> ExecTool[executeTool Function]
  900. ExecTool --> GetTool[Get Tool from Registry]
  901. GetTool --> Validate[Validate Input]
  902. Validate -->|Valid| ExecFunc[Run Executor Function]
  903. Validate -->|Invalid| ValidErr[Return Validation Error]
  904. ExecFunc -->|Success| SuccessResp[Return Success Response]
  905. ExecFunc -->|Error| HandleErr[Catch & Format Error]
  906. HandleErr --> ErrResp[Return Error Response]
  907. end
  908. ```
  909. ## Sequential Thinking Process
  910. The Sequential Thinking mechanism provides LLM-based fallback routing:
  911. ```mermaid
  912. flowchart TD
  913. Start[Start] --> Estimate[Estimate Number of Steps]
  914. Estimate --> Init[Initialize with System Prompt]
  915. Init --> First[Generate First Thought]
  916. First --> Context[Add to Context]
  917. Context --> Loop{Needs More Thoughts?}
  918. Loop -->|Yes| Next[Generate Next Thought]
  919. Next -->|Standard| AddStd[Add to Context]
  920. Next -->|Revision| Rev[Mark as Revision]
  921. Next -->|New Branch| Branch[Mark as Branch]
  922. Rev --> AddRev[Add to Context]
  923. Branch --> AddBranch[Add to Context]
  924. AddStd --> Loop
  925. AddRev --> Loop
  926. AddBranch --> Loop
  927. Loop -->|No| Extract[Extract Final Solution]
  928. Extract --> End[End With Tool Selection]
  929. subgraph "Error Handling"
  930. Next -->|Error| Retry[Retry with Simplified Request]
  931. Retry -->|Success| AddRetry[Add to Context]
  932. Retry -->|Failure| FallbackEx[Extract Partial Solution]
  933. AddRetry --> Loop
  934. FallbackEx --> End
  935. end
  936. ```
  937. ## Session State Management
  938. ```mermaid
  939. flowchart TD
  940. Start[Client Request] --> SessionID[Extract Session ID]
  941. SessionID --> Store{State Exists?}
  942. Store -->|Yes| Retrieve[Retrieve Previous State]
  943. Store -->|No| Create[Create New State]
  944. Retrieve --> Context[Add Context to Tool]
  945. Create --> NoContext[Execute Without Context]
  946. Context --> Execute[Execute Tool]
  947. NoContext --> Execute
  948. Execute --> SaveState[Update Session State]
  949. SaveState --> Response[Return Response to Client]
  950. subgraph "Session State Structure"
  951. State[SessionState] --> PrevCall[Previous Tool Call]
  952. State --> PrevResp[Previous Response]
  953. State --> Timestamp[Timestamp]
  954. end
  955. ```
  956. ## Workflow Execution Engine
  957. The Workflow system enables multi-step sequences:
  958. ```mermaid
  959. flowchart TD
  960. Start[Client Request] --> Parse[Parse Workflow Request]
  961. Parse --> FindFlow[Find Workflow in workflows.json]
  962. FindFlow --> Steps[Extract Steps]
  963. Steps --> Loop[Process Each Step]
  964. Loop --> PrepInput[Prepare Step Input]
  965. PrepInput --> ExecuteTool[Execute Tool via Registry]
  966. ExecuteTool --> SaveOutput[Save Step Output]
  967. SaveOutput --> NextStep{More Steps?}
  968. NextStep -->|Yes| MapOutput[Map Output to Next Input]
  969. MapOutput --> Loop
  970. NextStep -->|No| FinalOutput[Prepare Final Output]
  971. FinalOutput --> End[Return Workflow Result]
  972. subgraph "Input/Output Mapping"
  973. MapOutput --> Direct[Direct Value]
  974. MapOutput --> Extract[Extract From Previous]
  975. MapOutput --> Transform[Transform Values]
  976. end
  977. ```
  978. ## Workflow Configuration
  979. 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.
  980. ### File Location and Structure
  981. - The `workflows.json` file must be placed in the project root directory (same level as package.json)
  982. - The file follows this structure:
  983. ```json
  984. {
  985. "workflows": {
  986. "workflowName1": {
  987. "description": "Description of what this workflow does",
  988. "inputSchema": {
  989. "param1": "string",
  990. "param2": "string"
  991. },
  992. "steps": [
  993. {
  994. "id": "step1_id",
  995. "toolName": "tool-name",
  996. "params": {
  997. "param1": "{workflow.input.param1}"
  998. }
  999. },
  1000. {
  1001. "id": "step2_id",
  1002. "toolName": "another-tool",
  1003. "params": {
  1004. "paramA": "{workflow.input.param2}",
  1005. "paramB": "{steps.step1_id.output.content[0].text}"
  1006. }
  1007. }
  1008. ],
  1009. "output": {
  1010. "summary": "Workflow completed message",
  1011. "details": ["Output line 1", "Output line 2"]
  1012. }
  1013. }
  1014. }
  1015. }
  1016. ```
  1017. ### Parameter Templates
  1018. Workflow step parameters support template strings that can reference:
  1019. - Workflow inputs: `{workflow.input.paramName}`
  1020. - Previous step outputs: `{steps.stepId.output.content[0].text}`
  1021. ### Triggering Workflows
  1022. Use the `run-workflow` tool with:
  1023. ```
  1024. Run the newProjectSetup workflow with input {"productDescription": "A task manager app"}
  1025. ```
  1026. ## Detailed Tool Documentation
  1027. Each tool in the `src/tools/` directory includes comprehensive documentation in its own README.md file. These files cover:
  1028. * Tool overview and purpose
  1029. * Input/output specifications
  1030. * Workflow diagrams (Mermaid)
  1031. * Usage examples
  1032. * System prompts used
  1033. * Error handling details
  1034. Refer to these individual READMEs for in-depth information:
  1035. * `src/tools/fullstack-starter-kit-generator/README.md`
  1036. * `src/tools/prd-generator/README.md`
  1037. * `src/tools/research/README.md`
  1038. * `src/tools/rules-generator/README.md`
  1039. * `src/tools/task-list-generator/README.md`
  1040. * `src/tools/user-stories-generator/README.md`
  1041. * `src/tools/workflow-runner/README.md`
  1042. * `src/tools/map-codebase/README.md`
  1043. ## Tool Categories
  1044. ### Analysis & Information Tools
  1045. * **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.
  1046. * **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.
  1047. * **Research Tool (`research`)**: Performs deep research on technical topics using Perplexity Sonar, providing summaries and sources.
  1048. ### Planning & Documentation Tools
  1049. * **Rules Generator (`rules-generator`):** Creates project-specific development rules and guidelines.
  1050. * **PRD Generator (`prd-generator`):** Generates comprehensive product requirements documents.
  1051. * **User Stories Generator (`user-stories-generator`):** Creates detailed user stories with acceptance criteria.
  1052. * **Task List Generator (`task-list-generator`):** Builds structured development task lists with dependencies.
  1053. ### Project Scaffolding Tool
  1054. * **Fullstack Starter Kit Generator (`fullstack-starter-kit-generator`):** Creates customized project starter kits with specified frontend/backend technologies, including basic setup scripts and configuration.
  1055. ### Workflow & Orchestration
  1056. * **Workflow Runner (`run-workflow`):** Executes predefined sequences of tool calls for common development tasks.
  1057. ## Generated File Storage
  1058. 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.
  1059. ### Security Boundaries for Read and Write Operations
  1060. For security reasons, the Vibe Coder MCP tools maintain separate security boundaries for read and write operations with a **security-by-default** approach:
  1061. * **Read Operations**:
  1062. - **Code Map Tool**: Only reads from directories explicitly authorized through the `CODE_MAP_ALLOWED_DIR` environment variable
  1063. - **Vibe Task Manager**: Only reads from directories authorized through the `VIBE_TASK_MANAGER_READ_DIR` environment variable (defaults to `process.cwd()`)
  1064. - **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
  1065. - **Filesystem Security**: Comprehensive blacklist enforcement and permission checking prevent EACCES errors and unauthorized file access
  1066. * **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.
  1067. * **Security Implementation**: The filesystem security system includes:
  1068. - **Adaptive Timeout Management**: Prevents operations from hanging indefinitely with intelligent retry and cancellation
  1069. - **Path Validation**: Comprehensive validation of all file paths before access
  1070. - **Permission Checking**: Proactive permission verification to prevent access errors
  1071. - **System Directory Protection**: Built-in blacklist of system directories that should never be accessed
  1072. Example structure (default location):
  1073. ```bash
  1074. VibeCoderOutput/
  1075. ├── research/ # Research reports
  1076. │ └── TIMESTAMP-QUERY-research.md
  1077. ├── rules-generator/ # Development rules
  1078. │ └── TIMESTAMP-PROJECT-rules.md
  1079. ├── prd-generator/ # PRDs
  1080. │ └── TIMESTAMP-PROJECT-prd.md
  1081. ├── user-stories-generator/ # User stories
  1082. │ └── TIMESTAMP-PROJECT-user-stories.md
  1083. ├── task-list-generator/ # Task lists
  1084. │ └── TIMESTAMP-PROJECT-task-list.md
  1085. ├── fullstack-starter-kit-generator/ # Project templates
  1086. │ └── TIMESTAMP-PROJECT/
  1087. ├── map-codebase/ # Code maps and diagrams
  1088. │ └── TIMESTAMP-code-map/
  1089. └── workflow-runner/ # Workflow outputs
  1090. └── TIMESTAMP-WORKFLOW/
  1091. ```
  1092. ## System Instructions for MCP Clients
  1093. 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:
  1094. - Tool-specific usage patterns and best practices
  1095. - Natural language command structures
  1096. - Asynchronous job polling guidelines
  1097. - Integration workflows and examples
  1098. - Error handling and troubleshooting
  1099. ### How to Use System Instructions
  1100. **For Claude Desktop:**
  1101. 1. Open Claude Desktop settings
  1102. 2. Navigate to "Custom Instructions" or "System Prompt"
  1103. 3. Copy the entire content from `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
  1104. 4. Paste into the custom instructions field
  1105. 5. Save settings
  1106. **For Augment:**
  1107. 1. Access Augment settings/preferences
  1108. 2. Find "Custom Instructions" or "System Configuration"
  1109. 3. Copy and paste the system instructions
  1110. 4. Apply changes
  1111. **For Claude Code/Windsurf/Other MCP Clients:**
  1112. 1. Locate the custom instructions or system prompt configuration
  1113. 2. Copy the content from `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`
  1114. 3. Paste into the appropriate field
  1115. 4. Save/apply the configuration
  1116. **Benefits of Using System Instructions:**
  1117. - 98%+ tool operation success rate
  1118. - Optimal natural language command recognition
  1119. - Proper asynchronous job handling
  1120. - Efficient workflow orchestration
  1121. - Reduced errors and improved troubleshooting
  1122. ## Usage Examples
  1123. ### Via CLI (Direct Command Line)
  1124. ```bash
  1125. # Research and analysis
  1126. vibe "research modern JavaScript frameworks"
  1127. vibe "create development rules for a mobile banking application"
  1128. # Project planning
  1129. vibe "generate a PRD for a task management application"
  1130. vibe "generate user stories for an e-commerce website"
  1131. vibe "create a task list for a weather app based on user stories"
  1132. # Code generation and analysis
  1133. vibe "create a starter kit for a React/Node.js blog application with user authentication"
  1134. vibe "map the codebase structure" --json
  1135. vibe "curate context for adding authentication to my React app"
  1136. # Task management
  1137. vibe "create a new project for building a todo app"
  1138. vibe "list all my projects"
  1139. vibe "show status of my React project"
  1140. # Workflow automation
  1141. vibe "run workflow newProjectSetup with input {\"projectName\": \"my-new-app\"}"
  1142. ```
  1143. ### Via MCP Client (AI Assistant Integration)
  1144. Interact with the tools via your connected AI assistant:
  1145. * **Research:** `Research modern JavaScript frameworks`
  1146. * **Generate Rules:** `Create development rules for a mobile banking application`
  1147. * **Generate PRD:** `Generate a PRD for a task management application`
  1148. * **Generate User Stories:** `Generate user stories for an e-commerce website`
  1149. * **Generate Task List:** `Create a task list for a weather app based on [user stories]`
  1150. * **Sequential Thinking:** `Think through the architecture for a microservices-based e-commerce platform`
  1151. * **Fullstack Starter Kit:** `Create a starter kit for a React/Node.js blog application with user authentication`
  1152. * **Run Workflow:** `Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }`
  1153. * **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"`
  1154. * **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`
  1155. * **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?`
  1156. ## Vibe Task Manager - AI-Native Task Management
  1157. 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.
  1158. **Status**: Functional and production-ready with 99.9% test success rate, but actively being enhanced with new features and improvements.
  1159. ### Key Features
  1160. * **Natural Language Processing**: Understands commands like "Create a project for building a React app" or "Show me all pending tasks"
  1161. * **Recursive Decomposition Design (RDD)**: Automatically breaks down complex projects into atomic, executable tasks
  1162. * **Artifact Parsing Integration**: Seamlessly imports PRD files from `VibeCoderOutput/prd-generator/` and task lists from `VibeCoderOutput/generated_task_lists/`
  1163. * **Session Persistence**: Enhanced session tracking with orchestration workflow triggers for reliable multi-step operations
  1164. * **Comprehensive CLI**: Full command-line interface with natural language processing and structured commands
  1165. * **Agent Orchestration**: Coordinates multiple AI agents for parallel task execution
  1166. * **Integration Ready**: Works seamlessly with Code Map Tool, Research Tool, and other tools
  1167. * **File Storage**: All project data stored in `VibeCoderOutput/vibe-task-manager/` following established conventions
  1168. ### Quick Start Examples
  1169. ```
  1170. # Project Management
  1171. "Create a new project for building a todo app with React and Node.js"
  1172. "List all my projects"
  1173. "Show me the status of my web app project"
  1174. # Task Management
  1175. "Create a high priority task for implementing user authentication"
  1176. "List all pending tasks for the todo-app project"
  1177. "Run the database setup task"
  1178. # Project Analysis (Enhanced with Intelligent Lookup)
  1179. "Decompose my React project into development tasks"
  1180. "Decompose PID-TODO-APP-REACT-001 into tasks" # Using project ID
  1181. "Decompose \"Todo App with React\" into tasks" # Using exact name
  1182. "Decompose todo into tasks" # Using partial name (fuzzy matching)
  1183. "Refine the authentication task to include OAuth support"
  1184. "What's the current progress on my mobile app?"
  1185. ```
  1186. ### 🎯 Enhanced Project Lookup Features
  1187. - **Intelligent Parsing**: Automatically detects project IDs, names, or partial matches
  1188. - **Comprehensive Validation**: Validates project readiness before decomposition
  1189. - **Enhanced Error Messages**: Provides actionable guidance with available projects and usage examples
  1190. - **Multiple Input Formats**: Supports project IDs, quoted names, partial names, and fuzzy matching
  1191. - **Confidence Scoring**: Shows parsing confidence levels for better user feedback
  1192. ### Command Structure
  1193. The Vibe Task Manager supports both structured commands and natural language:
  1194. **Structured Commands:**
  1195. - `vibe-task-manager create project "Name" "Description" --options`
  1196. - `vibe-task-manager list projects --status pending`
  1197. - `vibe-task-manager run task task-id --force`
  1198. - `vibe-task-manager status project-id --detailed`
  1199. **Natural Language (Recommended):**
  1200. - "Create a project for [description]"
  1201. - "Show me all [status] projects"
  1202. - "Run the [task name] task"
  1203. - "What's the status of [project]?"
  1204. - "Parse PRD files for [project name]" *(NEW)*
  1205. - "Import task list from [file path]" *(NEW)*
  1206. - "Parse all PRDs and create projects automatically" *(NEW)*
  1207. For complete documentation, see `src/tools/vibe-task-manager/README.md` and the system instructions in `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md`.
  1208. ## Implementation Status & Performance Metrics
  1209. ### Current Epic Status
  1210. The Vibe Coder MCP project follows an epic-based development approach with comprehensive tracking:
  1211. ```mermaid
  1212. gantt
  1213. title Vibe Coder MCP Development Progress
  1214. dateFormat YYYY-MM-DD
  1215. section Core Infrastructure
  1216. Tool Registry & Routing :done, epic1, 2024-01-01, 2024-02-15
  1217. MCP Server Implementation :done, epic2, 2024-01-15, 2024-03-01
  1218. Async Job Management :done, epic3, 2024-02-15, 2024-03-15
  1219. section Tool Development
  1220. Research & Planning Tools :done, epic4, 2024-02-01, 2024-04-01
  1221. Code Map Tool :done, epic5, 2024-03-01, 2024-05-15
  1222. Vibe Task Manager Core :done, epic6, 2024-04-01, 2024-06-15
  1223. section Advanced Features
  1224. Performance Optimization :active, epic7, 2024-06-01, 2024-07-15
  1225. Security Implementation :epic8, 2024-07-01, 2024-08-15
  1226. Analytics & Monitoring :epic9, 2024-07-15, 2024-09-01
  1227. ```
  1228. ### Epic Completion Summary
  1229. * **Epic 1-5**: ✅ **Complete** (100% - Core infrastructure and basic tools)
  1230. * **Epic 6.1**: ✅ **Complete** (98.3% test success rate - Deep MCP Tool Integration)
  1231. * **Epic 6.2**: 🔄 **In Progress** (Performance Optimization - 75% complete)
  1232. * **Epic 7.1**: 📋 **Planned** (Security Implementation - Ready for implementation)
  1233. * **Epic 8**: 📋 **Planned** (Advanced Analytics & Monitoring - Designed)
  1234. ### Performance Targets & Current Metrics (v0.2.3)
  1235. | Metric | Target | Current | Status |
  1236. |--------|--------|---------|--------|
  1237. | Test Success Rate | 98%+ | 99.9% | ✅ **Exceeded** |
  1238. | Response Time (Task Operations) | <200ms | <150ms | ✅ **Exceeded** |
  1239. | Response Time (Sync Operations) | <500ms | <350ms | ✅ **Exceeded** |
  1240. | Job Completion Rate | 95%+ | 96.7% | ✅ **Met** |
  1241. | Memory Usage (Code Map Tool) | <512MB | <400MB | ✅ **Optimized** |
  1242. | Unit Test Coverage | >70% | 73% | ✅ **Met** |
  1243. | CI/CD Pipeline Speed | <5min | ~3min | ✅ **Optimized** |
  1244. | Security Overhead | <50ms | <35ms | ✅ **Optimized** |
  1245. | Zero Mock Code Policy | 100% | 100% | ✅ **Achieved** |
  1246. ### Tool-Specific Status
  1247. #### Vibe Task Manager
  1248. * **Status**: Production Ready (Functional but actively being enhanced)
  1249. * **Test Coverage**: 99.9%
  1250. * **Features**: RDD methodology, agent orchestration, natural language processing, artifact parsing, session persistence, comprehensive CLI
  1251. * **Performance**: <50ms response time for task operations
  1252. * **Recent Additions**: PRD/task list integration, enhanced session tracking, orchestration workflows
  1253. #### Code Map Tool
  1254. * **Status**: Production Ready with Advanced Features
  1255. * **Memory Optimization**: 95-97% token reduction achieved
  1256. * **Language Support**: 35+ programming languages
  1257. * **Import Resolution**: Enhanced with adapter-based architecture
  1258. #### Context Curation Tool
  1259. * **Status**: Production Ready with Intelligent Codemap Caching
  1260. * **Language Support**: 35+ programming languages with 95%+ accuracy
  1261. * **Workflow Pipeline**: 8-phase intelligent analysis and curation
  1262. * **Project Detection**: Language-agnostic with multi-strategy file discovery
  1263. * **Performance Optimization**: Intelligent caching system that reuses recent codemaps (configurable 1-1440 minutes)
  1264. #### Research Tool
  1265. * **Status**: Production Ready
  1266. * **Integration**: Perplexity Sonar API
  1267. * **Performance**: <2s average research query response
  1268. #### Other Tools
  1269. * **Fullstack Generator**: Production Ready
  1270. * **PRD/User Stories/Task List Generators**: Production Ready
  1271. * **Workflow Runner**: Production Ready
  1272. ## Running Locally (Optional)
  1273. While the primary use is integration with an AI assistant (using stdio), you can run the server directly for testing:
  1274. ### Running Modes
  1275. * **Production Mode (Stdio):**
  1276. ```bash
  1277. npm start
  1278. ```
  1279. * Logs go to stderr (mimics AI assistant launch)
  1280. * Use NODE_ENV=production
  1281. * **Development Mode (Stdio, Pretty Logs):**
  1282. ```bash
  1283. npm run dev
  1284. ```
  1285. * Logs go to stdout with pretty formatting
  1286. * Requires `nodemon` and `pino-pretty`
  1287. * Use NODE_ENV=development
  1288. * **SSE Mode (HTTP Interface):**
  1289. ```bash
  1290. # Production mode over HTTP
  1291. npm run start:sse
  1292. # Development mode over HTTP
  1293. npm run dev:sse
  1294. ```
  1295. * Uses HTTP instead of stdio
  1296. * Configured via PORT in .env (default: 3000)
  1297. * Access at http://localhost:3000
  1298. ## Detailed Troubleshooting
  1299. ### Connection Issues
  1300. #### MCP Server Not Detected in AI Assistant
  1301. 1. **Check Configuration Path:**
  1302. * Verify the absolute path in the `args` array is correct
  1303. * Ensure all slashes are forward slashes `/` even on Windows
  1304. * Run `node <path-to-build/index.js>` directly to test if Node can find it
  1305. 2. **Check Configuration Format:**
  1306. * Make sure JSON is valid without syntax errors
  1307. * Check that commas between properties are correct
  1308. * Verify that the `mcpServers` object contains your server
  1309. 3. **Restart the Assistant:**
  1310. * Completely close (not just minimize) the application
  1311. * Reopen and try again
  1312. #### Server Starts But Tools Don't Work
  1313. 1. **Check Disabled Flag:**
  1314. * Ensure `"disabled": false` is set
  1315. * Remove any `//` comments as JSON doesn't support them
  1316. 2. **Verify autoApprove Array:**
  1317. * Check that tool names in the `autoApprove` array match exactly
  1318. * Try adding `"process-request"` to the array if using hybrid routing
  1319. ### API Key Issues
  1320. 1. **OpenRouter Key Problems:**
  1321. * Double-check that the key is correctly copied
  1322. * Verify the key is active in your OpenRouter dashboard
  1323. * Check if you have sufficient credits
  1324. 2. **Environment Variable Issues:**
  1325. * Verify the key is correct in both:
  1326. * The `.env` file (for local runs)
  1327. * Your AI assistant's configuration env block
  1328. ### Path & Permission Issues
  1329. 1. **Build Directory Not Found:**
  1330. * Run `npm run build` to ensure the build directory exists
  1331. * Check if build output is going to a different directory (check tsconfig.json)
  1332. 2. **File Permission Errors:**
  1333. * Ensure your user has write access to the workflow-agent-files directory
  1334. * On Unix systems, check if build/index.js has execute permission
  1335. ### Log Debugging
  1336. 1. **For Local Runs:**
  1337. * Check the console output for error messages
  1338. * Try running with `LOG_LEVEL=debug` in your `.env` file
  1339. 2. **For AI Assistant Runs:**
  1340. * Set `"NODE_ENV": "production"` in the env configuration
  1341. * Check if the assistant has a logging console or output window
  1342. ### Tool-Specific Issues
  1343. 1. **Semantic Routing Not Working:**
  1344. * First run may download embedding model - check for download messages
  1345. * Try a more explicit request that mentions the tool name
  1346. ## Documentation
  1347. ### Core Documentation
  1348. - **System Instructions**: `VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md` - Complete usage guide for MCP clients
  1349. - **CI/CD Guide**: `CI_CD_GUIDE.md` - Streamlined pipeline documentation (70% faster)
  1350. - **NPM Publishing Guide**: `NPM_PUBLISHING_GUIDE.md` - Release and deployment process
  1351. - **System Architecture**: `docs/ARCHITECTURE.md` - Comprehensive system architecture with Mermaid diagrams
  1352. - **Performance & Testing**: `docs/PERFORMANCE_AND_TESTING.md` - Performance metrics, testing strategies, and quality assurance
  1353. - **Vibe Task Manager**: `src/tools/vibe-task-manager/README.md` - Comprehensive task management documentation
  1354. - **Context Curation Tool**: `src/tools/curate-context/README.md` - Language-agnostic codebase analysis documentation
  1355. - **Code Map Tool**: `src/tools/map-codebase/README.md` - Advanced codebase analysis documentation
  1356. ### Tool Documentation
  1357. - **Individual Tool READMEs**: Each tool directory contains detailed documentation
  1358. - **Configuration Guides**: Environment setup and configuration management
  1359. - **API Reference**: Tool schemas and parameters documented in system instructions
  1360. - **Integration Examples**: Practical workflows and usage patterns
  1361. ### Architecture Documentation
  1362. - **System Architecture**: Mermaid diagrams in README and system instructions
  1363. - **Tool Architecture**: Individual tool architecture diagrams
  1364. - **Performance Metrics**: Current status and optimization strategies
  1365. - **Development Guidelines**: Contributing and development best practices
  1366. ## Contributing
  1367. We welcome contributions! Please see our contributing guidelines and ensure all tests pass before submitting pull requests.
  1368. ### Development Workflow
  1369. 1. Fork the repository
  1370. 2. Create a feature branch
  1371. 3. Make your changes with comprehensive tests
  1372. 4. Ensure all checks pass locally:
  1373. ```bash
  1374. # Run CI checks (REQUIRED before PR - matches GitHub Actions)
  1375. npm run type-check # TypeScript validation (must pass)
  1376. npm run lint # Code quality checks (must pass)
  1377. npm run build # Build verification (must pass)
  1378. # Run tests locally (RECOMMENDED before PR)
  1379. npm run test:unit # Fast unit tests (~3 minutes)
  1380. # Optional: Thorough testing for major changes
  1381. npm run test:integration
  1382. npm test # All tests
  1383. ```
  1384. 5. Submit a pull request with detailed description
  1385. ### Quality Standards
  1386. - **Type Safety**: NO `any` types - strict TypeScript required
  1387. - **CI Pipeline**: Must pass type-check, lint, and build (automated)
  1388. - **Testing**: Run unit tests locally before PR submission
  1389. - **Test Coverage**: Maintain >70% coverage for unit tests
  1390. - **Documentation**: Update relevant docs for changes
  1391. - **Performance**: Consider impact on CI pipeline speed (<5 min target)
  1392. ## Common Troubleshooting
  1393. ### OpenRouter API Key Issues
  1394. **Problem**: Tools fail with authentication errors
  1395. - **Solution**: Verify your OpenRouter API key is correctly set in `.env`
  1396. - **Check**: Ensure the key has no extra spaces or quotes
  1397. - **Verify**: Test your key at [openrouter.ai](https://openrouter.ai)
  1398. - **Credits**: Ensure you have sufficient credits in your OpenRouter account
  1399. ### Path Configuration Problems
  1400. **Problem**: "Path not found" or "Access denied" errors
  1401. - **Solution**: Use absolute paths with forward slashes (/) in all configurations
  1402. - **Windows**: Convert paths like `C:\Users\name` to `C:/Users/name`
  1403. - **Permissions**: Ensure the user has read/write access to configured directories
  1404. - **Environment Variables**: Verify `VIBE_CODER_OUTPUT_DIR` and `VIBE_PROJECT_ROOT` are set correctly (or legacy variables `CODE_MAP_ALLOWED_DIR` and `VIBE_TASK_MANAGER_READ_DIR`)
  1405. ### Build Failures
  1406. **Problem**: TypeScript compilation errors
  1407. - **Solution**: Run `npm run clean && npm run build`
  1408. - **Dependencies**: Delete `node_modules` and `package-lock.json`, then run `npm install`
  1409. - **Node Version**: Ensure Node.js v20+ is installed (`node -v`)
  1410. - **TypeScript**: Check for syntax errors with `npm run lint`
  1411. ### Test Failures
  1412. **Problem**: Tests fail locally or type-check errors in CI
  1413. - **Type Errors**: Run `npm run type-check` locally to catch issues early
  1414. - **Lint Issues**: Use `npm run lint:fix` to auto-fix style problems
  1415. - **Environment**: Ensure `.env` file exists with valid `OPENROUTER_API_KEY`
  1416. - **Memory**: Tests may fail on systems with <4GB RAM
  1417. - **Network**: Some tests require internet connectivity
  1418. - **Cleanup**: Run `npm run clean` before running tests
  1419. - **CI Pipeline**: See [CI/CD Guide](./CI_CD_GUIDE.md) for pipeline details
  1420. ### Memory/Performance Issues
  1421. **Problem**: High memory usage or slow performance
  1422. - **Large Codebases**: Code Map Tool may consume significant memory for projects with >10,000 files
  1423. - **Solution**: Increase Node.js memory limit: `NODE_OPTIONS='--max-old-space-size=4096' npm start`
  1424. - **Caching**: Clear cache directories in `VibeCoderOutput/` if they grow too large
  1425. - **Monitoring**: Use `npm run test:memory` to identify memory leaks
  1426. ### MCP Client Connection Issues
  1427. **Problem**: Server not detected by AI assistant
  1428. - **Paths**: Verify all paths in MCP configuration use forward slashes and are absolute
  1429. - **Restart**: Completely close and restart your AI assistant application
  1430. - **Logs**: Check `LOG_LEVEL=debug` in configuration for detailed error messages
  1431. - **Transport**: Ensure `"transport": "stdio"` is set correctly
  1432. - **Disabled**: Verify `"disabled": false` in your configuration
  1433. ### Tool-Specific Issues
  1434. **Vibe Task Manager**:
  1435. - If natural language commands fail, try using structured commands
  1436. - Check `VibeCoderOutput/vibe-task-manager/` for project files
  1437. - Ensure project names don't contain special characters
  1438. **Code Map Tool**:
  1439. - For permission errors, verify `CODE_MAP_ALLOWED_DIR` is set
  1440. - Large repositories may timeout - try smaller subdirectories
  1441. - Some languages require additional setup (see tool README)
  1442. **Context Curator**:
  1443. - If codemap generation fails, check recent codemaps in cache
  1444. - Verify sufficient disk space for large context packages
  1445. - Check file permissions in target directories
  1446. ### Network and Proxy Issues
  1447. **Problem**: Cannot reach external services
  1448. - **Proxy**: Set `HTTP_PROXY` and `HTTPS_PROXY` environment variables if behind a proxy
  1449. - **SSL**: For SSL issues, try `NODE_TLS_REJECT_UNAUTHORIZED=0` (development only)
  1450. - **Firewall**: Ensure firewall allows outbound HTTPS connections
  1451. - **DNS**: Try using public DNS servers if resolution fails
  1452. ### Getting Help
  1453. If issues persist:
  1454. 1. Check existing issues at [GitHub Issues](https://github.com/freshtechbro/vibe-coder-mcp/issues)
  1455. 2. Enable debug logging: `LOG_LEVEL=debug`
  1456. 3. Collect error messages and logs
  1457. 4. Create a new issue with:
  1458. - Node.js version (`node -v`)
  1459. - Operating system
  1460. - Error messages
  1461. - Steps to reproduce
  1462. ## 📅 Changelog
  1463. ### Version 0.3.5 (Latest)
  1464. - **Enhanced Hybrid Matcher**: Complete parameter extraction for all 15 tools
  1465. - **CLI/REPL Improvements**: Interactive confirmations, job polling with progress
  1466. - **Bug Fixes**: Task-list-generator auto-generates user stories, multi-turn conversations fixed
  1467. - **TypeScript Strict Mode**: Zero `any` types, production-grade code quality
  1468. ### Version 0.3.1
  1469. - Global installation synchronization fixes
  1470. - Enhanced clean build process
  1471. - Improved NPM packaging workflow
  1472. ### Version 0.2.8
  1473. - CLI interactive mode configuration persistence
  1474. - Enhanced project root detection
  1475. ### Version 0.2.7
  1476. - Added missing configuration files to npm package
  1477. - Resolved configuration loading errors
  1478. ### Version 0.2.3
  1479. - Interactive REPL mode with chat interface
  1480. - Enhanced setup wizard with auto-detection
  1481. - Configuration templates
  1482. - Unified CLI binary
  1483. For full release history, see [GitHub Releases](https://github.com/freshtechbro/vibe-coder-mcp/releases)
  1484. ## License
  1485. This project is licensed under the MIT License - see the LICENSE file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.