Vibe Coder MCP Server

Vibe Coder MCP 服务

Vibe Coder 是一款 MCP（Model Context Protocol）服务，旨在通过强大的软件开发工具增强你的 AI 助手（如 Cursor、Cline AI 或 Claude Desktop）。它可以协助研究、规划、生成需求、创建入门项目等！

🆕 Version 0.3.5 新内容

🎉 最新版本 - 增强的 CLI、REPL 和参数提取

主要改进：

• ✨ 全面升级混合匹配器：全部 15 个 MCP 工具现在都具备完善的参数提取功能
• 🚀 CLI/REPL 体验：交互式确认、任务状态轮询并显示进度
• 🔧 修复关键错误：任务列表生成器会自动生成用户故事，多轮对话运行顺畅
• 📊 更好的工具匹配：采用多策略方法（关键词 35%、模式 30%、语义 15%、LLM 20%）
• ⚡ TypeScript 严格模式：零个 any 类型，全部显式声明类型，代码质量达到生产级别

用户体验改进：

• 对低置信度匹配会提示用户确认
• 为长时间运行的任务提供可视化进度指示
• 交互模式下通过 JSON 日志过滤，输出更加简洁
• 跨命令保留会话
• 增强错误消息和验证反馈

之前的重要版本

Version 0.3.1 - 全局安装与同步

• 修复全局/本地版本同步问题
• 改进安装时的清理构建流程
• 改进 NPM 发布的打包工作流

Version 0.2.8 - CLI 交互模式

• 修复交互模式下的配置持久化问题
• 改进 CLI 用户的项目根目录检测
• 改进上下文感知配置

Version 0.2.3 - 交互式 REPL 与设置向导

• 交互式 REPL 模式，提供聊天式界面并保留会话
• 增强的设置向导，可自动检测首次运行
• src/config-templates/ 中的配置模板
• 通过优化内存用量提升性能
• 统一的 CLI 二进制文件——使用单个 vibe 命令执行所有操作

🚀 快速开始

# 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

设置向导将会：

1. ✅ 配置你的 OpenRouter API 密钥
2. ✅ 设置项目目录
3. ✅ 根据模板创建配置文件
4. ✅ 验证你的环境
5. ✅ 帮你准备好使用所有功能！

📦 安装

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

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

安装方式

全局安装（推荐）

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

使用 npx 快速运行

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

本地项目安装

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

交互模式功能：

• 类聊天式对话，并保留上下文
• 实时执行工具，并显示进度
• 会话持久化和历史记录
• 支持 Markdown 渲染
• 多种主题和自定义选项
• 使用斜杠命令快速执行操作

🎯 MCP 客户端集成（Claude Desktop、Cursor、Cline AI）

快速集成指南

Vibe-Coder MCP 可与任何兼容 MCP 的客户端无缝集成。以下是配置方法：

选项 1：使用 NPX（推荐）

在 MCP 客户端的服务配置对话框中：

• 服务名称：vibe-coder-mcp
• 命令/URL：npx
• 参数：vibe-coder-mcp
• 环境变量：
  • OPENROUTER_API_KEY：你的 OpenRouter API 密钥（必需）
  • VIBE_PROJECT_ROOT：/path/to/your/project（必需）
  • LOG_LEVEL：info（可选）
  • NODE_ENV：production（可选）

选项 2：全局安装

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

然后进行配置：

• 命令/URL：vibe
• 参数：（留空）
• 环境变量：同选项 1

选项 3：使用 Node 和完整路径

• 命令/URL：node
• 参数：/path/to/node_modules/vibe-coder-mcp/build/index.js
• 环境变量：同选项 1

Claude Desktop 专用配置

Claude Desktop 用户请将以下内容添加到 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"
      }
    }
  }
}

完整示例请参阅 example_claude_desktop_config.json。

集成后可用的工具

配置完成后，你的 MCP 客户端将可使用以下工具：

• vibe-task-manager：采用 RDD 方法的 AI 原生任务管理
• research-manager：通过 Perplexity 集成进行深度研究
• map-codebase：高级代码库分析（支持 35+ 种语言）
• curate-context：面向 AI 开发的智能上下文整理
• generate-prd：产品需求文档生成器
• generate-user-stories：用户故事生成器
• generate-task-list：任务列表生成器
• generate-fullstack-starter-kit：项目脚手架工具
• run-workflow：多步骤工作流执行

测试集成

配置完成后，向你的 AI 助手提问以进行测试：

• “使用 vibe 研究 React 最佳实践”
• “为此项目绘制代码库映射”
• “为任务管理应用生成一份 PRD”

🆕 统一项目根目录配置

CLI 用户零配置

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

MCP 客户端简单配置

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

• 一个变量：VIBE_PROJECT_ROOT 可替代多个目录配置
• 自动检测：CLI 自动检测项目根目录
• 向后兼容：仍支持旧版变量

🔧 环境配置

**必需：**使用 Vibe Coder MCP 需要 OpenRouter API 密钥。

获取 OpenRouter API 密钥

1. 访问 openrouter.ai
2. 如果你还没有账户，请创建一个
3. 前往 API Keys 页面
4. 创建并复制新的 API 密钥

设置环境变量

选项 1：使用设置向导（推荐用于 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

选项 2：环境变量

# 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"

选项 3：创建 .env 文件（v0.2.3+ 提供模板） 在工作目录中创建 .env 文件（或从 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"

目录配置（统一且简化）

🆕 统一配置（推荐）

• VIBE_PROJECT_ROOT：所有项目操作使用的单一变量（默认启用 CLI 自动检测）
• VIBE_USE_PROJECT_ROOT_AUTO_DETECTION：为 CLI 用户启用项目根目录自动检测（默认值："true"）
• VIBE_CODER_OUTPUT_DIR：生成文件的保存位置（默认值：./VibeCoderOutput/）

旧版配置（仍受支持）

• CODE_MAP_ALLOWED_DIR：代码分析的安全边界（未设置 VIBE_PROJECT_ROOT 时的回退选项）
• VIBE_TASK_MANAGER_READ_DIR：任务管理器操作的安全边界（未设置 VIBE_PROJECT_ROOT 时的回退选项）

自动检测的优势：

• 零配置：CLI 用户可自动检测项目根目录
• 上下文感知：CLI 与 MCP 客户端的使用行为不同
• 智能回退：5 级优先级解析链确保可靠运行

🔌 MCP 客户端设置

配置 AI 助手以连接到 Vibe Coder MCP：

适用于 Cursor AI / Windsurf / VS Code MCP 客户端

将以下内容添加到 MCP 设置中（通常位于 settings.json）：

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here"
      }
    }
  }
}

适用于 Claude Desktop

将以下内容添加到 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"
      }
    }
  }
}

💻 CLI 使用指南

Vibe Coder 提供功能强大的命令行界面，包含多种模式，可直接与所有工具交互。

交互式设置向导（在 v0.2.3 中增强）

# 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

交互式 REPL 模式（v0.2.3 新增！）

# Start interactive chat session
vibe --interactive

# Or with alias
vibe -i

# Resume a previous session
vibe --resume <session-id>

REPL 功能：

• 🎯 聊天界面：自然对话流程，并保留上下文
• 📝 多行输入：使用 """ 输入多行消息
• 🎨 主题：通过 /theme 命令使用多种颜色主题
• 💾 会话管理：支持自动保存和恢复
• 📊 Markdown 渲染：在回复中使用富文本格式
• ⚡ 实时进度：实时反馈执行情况
• 🔧 斜杠命令：使用 /tools、/history、/save 等快捷操作
• 🎮 自动补全：支持补全命令和工具

CLI 命令示例

研究与分析

vibe "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"

CLI 选项

# 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

交互式 REPL 命令（v0.2.3+）

进入交互模式（vibe --interactive）后，可使用以下命令：

# 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

文件整理

生成的文件会自动整理到 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

---

🔄 迁移指南（v0.2.3）

破坏性变更

无！ 0.2.3 版本完全向后兼容。所有现有配置和工作流均可继续使用。

技术改进

• 采用统一的 CLI 架构和单一入口点
• 改进错误处理和恢复机制
• 改进资源清理
• 增强整个代码库的类型安全性
• 防止长时间运行的会话发生内存泄漏
• CI/CD 流水线优化：
  • 执行速度提升 70%（约 3 分钟，而非约 10 分钟）
  • 专注于必要检查：类型检查、代码检查、构建
  • 单元测试移至本地开发工作流
  • 详情请参阅 CI/CD 指南
• 优化大规模代码库的内存使用
• 通过智能检测加快首次运行体验

---

📚 开发环境设置（进阶）

如果你想参与开发或从源代码运行，请按照下方的详细设置指南操作。

概述与功能

Vibe Coder MCP 与兼容 MCP 的客户端集成，可提供以下功能：

🚀 核心架构

• 四种传输方式支持：支持 stdio、SSE、WebSocket 和 HTTP 传输协议，最大限度兼容各类客户端
• 动态端口分配：智能端口管理，支持冲突解决和优雅降级
• 语义请求路由：使用基于嵌入的语义匹配智能路由请求，并提供顺序思考回退机制
• 工具注册表架构：集中管理工具，支持工具自行注册
• 统一通信协议：通过所有传输机制协调 Agent，并支持实时通知
• 会话状态管理：在会话内的多个请求之间保留上下文

🧠 AI 原生任务管理

• Vibe Task Manager：生产就绪的任务管理功能，测试成功率达 99.9%，并具备全面的集成能力（功能可用，仍在持续增强）
• 自然语言处理：支持 21 种意图，并采用多策略识别（模式匹配 + 大模型回退）
• 递归分解设计（RDD）：智能地将项目拆解为原子任务
• Agent 编排：支持多 Agent 协调、能力映射、负载均衡和实时状态同步
• 多传输方式 Agent 支持：全面集成 stdio、SSE、WebSocket 和 HTTP 传输方式
• 真实存储集成：坚持零模拟代码策略，所有集成均用于生产环境
• 工件解析集成：与 PRD 生成器和任务列表生成器的输出无缝集成
• 会话持久化：增强会话跟踪，并支持触发编排工作流
• 全面的命令行界面：功能丰富的自然语言命令行界面

🔍 高级代码分析与上下文整理

• 代码映射工具：支持 35 种以上编程语言，优化后可减少 95–97% 的令牌用量
• 上下文整理工具：与语言无关的项目检测，在 35 种以上语言中准确率超过 95%
• 智能 Codemap 缓存：可配置的缓存系统，可复用近期 codemap，优化工作流性能
• 增强的导入解析：通过第三方集成准确映射依赖关系
• 多策略文件发现：采用 4 种并行策略进行全面分析
• 内存优化：先进的缓存和资源管理
• 安全边界：分别验证读写路径，确保操作安全

📋 研究与规划套件

• 研究工具：通过 OpenRouter 使用 Perplexity Sonar 进行深入研究
• 上下文整理：通过 8 阶段工作流流水线智能分析代码库，并利用智能 codemap 缓存支持 AI 驱动的开发
• 文档生成器：PRD（prd-generator）、用户故事（user-stories-generator）、任务列表（task-list-generator）、开发规则（rules-generator）
• 项目脚手架：提供全栈入门套件（fullstack-starter-kit-generator），支持动态模板生成
• 工作流执行：执行 workflows.json 中定义的预设工具调用序列

⚡ 性能与可靠性

• 异步执行：基于作业的处理，支持实时状态跟踪
• 性能优化：响应时间低于 200ms，内存用量低于 400MB
• 全面测试：在 2,100 多项测试中，测试成功率达 99.9%，并经过完整的集成验证
• 生产就绪：不含模拟实现，均为真实服务集成
• 增强的错误处理：高级错误恢复机制，支持自动重试、升级处理和模式分析
• 动态端口管理：智能分配端口，支持冲突解决和优雅降级
• 实时监控：监控 Agent 健康状态、任务执行情况和性能分析

（更多内容请参阅下方的“详细工具文档”和“功能详情”部分）

开发环境设置指南

适用于希望从源代码运行或为项目做出贡献的开发者。

第 1 步：先决条件

1. 检查 Node.js 版本：

   • 打开终端或命令提示符。
   • 运行 node -v
   • 确认输出显示 v20.0.0 或更高版本（必需）。
   • 如果未安装或版本过旧：从 nodejs.org 下载。

2. 检查 Git 是否已安装：

   • 打开终端或命令提示符。
   • 运行 git --version
   • 如果未安装：从 git-scm.com 下载。

3. 获取 OpenRouter API 密钥：

   • 访问 openrouter.ai
   • 如果还没有账号，请创建一个。
   • 前往 API Keys 部分。
   • 创建新的 API 密钥并复制。
   • 将此密钥准备好，在第 4 步使用。

第 2 步：获取代码

1. 创建项目目录（可选）：

   • 打开终端或命令提示符。
   • 导航到要存放项目的位置：

     cd ~/Documents     # 示例：切换到你偏好的位置
     

2. 克隆代码仓库：

   • 运行：

     git clone https://github.com/freshtechbro/vibe-coder-mcp.git
     

     （如果适用，也可以使用你自己的派生仓库 URL）

3. 导航到项目目录：

   • 运行：

     cd vibe-coder-mcp
     

第 3 步：运行设置脚本

根据你的操作系统选择相应的脚本：

Windows：

1. 在终端中（仍位于 vibe-coder-mcp 目录下）运行：

   setup.bat
   

2. 等待脚本完成（它会安装依赖项、构建项目并创建所需目录）。
3. 如果看到任何错误消息，请参阅下方的故障排除部分。

macOS 或 Linux：

1. 将脚本设为可执行：

   chmod +x setup.sh
   

2. 运行脚本：

   ./setup.sh
   

3. 等待脚本完成。
4. 如果看到任何错误消息，请参阅下方的故障排除部分。

脚本会执行以下操作：

• 检查 Node.js 版本（需要 v20+）
• 通过 npm 安装所有依赖项
• 创建所需的 VibeCoderOutput/ 子目录
• 构建 TypeScript 项目
• 如果配置尚不存在，则根据模板创建配置（v0.2.3+）
• 设置可执行权限（在 Unix 系统上）

注意：通过优化依赖项安装和简化构建流程，设置过程现在更快了（v0.2.3+）。

第 4 步：配置环境变量

v0.2.3 新增：src/config-templates/ 中提供了配置模板，方便设置。

选项 A：使用设置向导（推荐）

vibe --setup

该向导将引导你完成配置，并创建所有必需的文件。

选项 B：手动配置

1. 复制模板（如果设置脚本尚未完成此操作）：

   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
   

2. 编辑 .env 文件，添加你的配置：

   # 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
   

3. 配置输出目录（可选）：

   • 若要更改生成文件的保存位置（默认为项目内的 VibeCoderOutput/），请在 .env 文件中添加以下内容：

     VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
     

   • 将路径替换为你首选的绝对路径。路径请使用正斜杠（/）。如果未设置此变量，将使用默认目录（VibeCoderOutput/）。

4. 🆕 配置统一项目根目录（推荐）：

   • 若要设置新的统一项目根目录配置，请在 .env 文件中添加以下内容：

     VIBE_PROJECT_ROOT=/path/to/your/project/root
     

   • 将路径替换为项目根目录的绝对路径。
   • 优点：所有工具（Code Map Generator、Task Manager、Context Curator）共用一个配置变量
   • 自动检测：对于 CLI 用户，系统会根据当前工作目录自动检测项目根目录
   • 向后兼容：如果你更倾向于分别配置，仍支持旧版变量

5. 旧版目录配置（可选）：

   • 如果你更倾向于分别配置目录，仍可使用原始变量：

     CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
     VIBE_TASK_MANAGER_READ_DIR=/path/to/your/project/source/directory
     

   • 注意：如果未设置 VIBE_PROJECT_ROOT，这些变量将作为备用配置
   • 安全性：所有变量均采用严格的文件系统安全实现

6. 查看其他设置（可选）：

   • 你可以添加服务支持的其他环境变量，例如 LOG_LEVEL（如 LOG_LEVEL=debug）或 NODE_ENV（如 NODE_ENV=development）。

7. 保存 .env 文件。

第 5 步：与 AI 助手集成（MCP 设置）

这个关键步骤会将其配置添加到客户端的 MCP 设置文件中，从而将 Vibe Coder 连接到你的 AI 助手。

5.1：查找客户端的 MCP 设置文件

文件位置因 AI 助手而异：

• Cursor AI / Windsurf / RooCode（基于 VS Code）：

  1. 打开应用。
  2. 打开命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）。
  3. 输入并选择 Preferences: Open User Settings (JSON)。
  4. 这会打开 settings.json 文件，mcpServers 对象应位于其中。

• Cline AI（VS Code 扩展）：

  • Windows：%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • macOS：~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Linux：~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • （注意：如果使用标准版 VS Code 而非 Cursor，请将路径中的 Cursor 替换为 Code）

• Claude Desktop：

  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json

5.2：添加 Vibe Coder 配置

1. 在文本编辑器中打开上文找到的设置文件。

2. 找到 "mcpServers": { ... } JSON 对象。如果该对象不存在，你可能需要创建它（确保整个文件仍为有效的 JSON）。例如，空文件可以改为 {"mcpServers": {}}。

3. 将以下配置块添加到 mcpServers 对象的花括号 {} 内部。如果已经列出了其他服务，请在前一个服务的右花括号 } 后添加逗号 ,，再粘贴此配置块。

   // 这是此 MCP 服务实例在客户端设置中的唯一标识符
   "vibe-coder-mcp": {
     // 指定用于运行服务的命令。如果系统 PATH 中包含 Node.js，则应为 'node'
     "command": "node",
     // 提供传递给 'command' 的参数。主要参数是已编译服务入口点的绝对路径
     // !! 重要：替换为你系统上的实际绝对路径。即使在 Windows 上，也请使用正斜杠 (/)！！
     "args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"],
     // 设置服务进程运行时的当前工作目录
     // !! 重要：替换为你系统上的实际绝对路径。即使在 Windows 上，也请使用正斜杠 (/)！！
     "cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
     // 定义客户端与服务之间的通信传输协议
     "transport": "stdio",
     // 服务启动时专门传递给 Vibe Coder 服务进程的环境变量
     // API 密钥应放在 .env 文件中，而不是这里
     "env": {
       // Vibe Coder 使用的 LLM 配置文件的绝对路径
       // !! 重要：替换为你系统上的实际绝对路径！！
       "LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json",
       // 设置服务的日志级别
       "LOG_LEVEL": "debug",
       // 指定运行环境
       "NODE_ENV": "production",
       // Vibe Coder 工具保存输出文件的目录
       // !! 重要：替换为你系统上的实际绝对路径！！
       "VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput",
       // 🆕 所有工具共用的统一项目根目录（推荐）
       // 此变量会为所有工具配置相同的项目边界
       "VIBE_PROJECT_ROOT": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
       // 旧版变量（可选——如果未设置 VIBE_PROJECT_ROOT，则用作回退）
       "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"
     },
     // 用于启用 (false) 或禁用 (true) 此服务配置的布尔标志
     "disabled": false,
     // MCP 客户端允许自动执行的工具名称列表
     "autoApprove": [
       "research",
       "rules-generator",
       "user-stories-generator",
       "task-list-generator",
       "prd-generator",
       "fullstack-starter-kit-generator",
       "refactor-code",
       "git-summary",
       "run-workflow",
       "map-codebase"
     ]
   }
   

4. 至关重要：将所有占位符路径（如 /path/to/your/vibe-coder-mcp/...）替换为系统上克隆仓库位置的正确绝对路径。即使在 Windows 上，路径也请使用正斜杠 /（例如，C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js）。路径不正确是服务连接失败最常见的原因。

5. 保存设置文件。

6. 完全关闭并重新启动 AI 助手应用（Cursor、VS Code、Claude Desktop 等），使更改生效。

第 6 步：测试配置

1. 启动 AI 助手：

   • 完全重启 AI 助手应用。

2. 测试简单命令：

   • 输入类似以下内容的测试命令：Research modern JavaScript frameworks

3. 检查响应是否正常：

   • 如果运行正常，你应该会收到一条研究结果。
   • 如果没有，请查看下方的故障排除部分。

AI Agent 集成

Vibe Coder MCP 系统包含全面的系统指令，旨在帮助 AI Agent 和 MCP 客户端有效利用整个生态系统。这些指令详细介绍了工具用法、集成模式和最佳实践。

系统指令文件

VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 文件包含全面的指导，帮助 AI Agent 有效使用 Vibe Coder MCP 生态系统。应将此文件集成到你的 AI 开发环境中，以便训练 Agent 优化工具用法。

平台专属集成

Claude Desktop

将系统指令放入项目的系统指令或自定义指令中：

1. 打开 Claude Desktop
2. 转到项目设置
3. 将 VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 的内容添加到系统指令字段
4. 保存并重启 Claude Desktop

ChatGPT

将系统指令添加到自定义指令或项目设置中：

1. 打开 ChatGPT 设置
2. 转到自定义指令或项目配置
3. 粘贴 VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 的内容
4. 保存配置

VS Code 扩展（Cline、Roo Coder、Augment）

将系统指令集成到扩展配置中：

1. Cline：放入系统指令或记忆部分
2. Roo Coder：添加到系统指令或规则文件夹
3. Augment：放入系统指令或记忆部分
4. 其他 VS Code 分支版本：放入系统指令或规则文件夹，并设置为“始终启用”

通用 MCP 客户端

对于其他兼容 MCP 的客户端：

1. 找到系统指令或规则配置
2. 添加 VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 的内容
3. 如果有此选项，请设为“始终启用”或“持久”
4. 重启客户端以应用更改

主要集成优势

• 全面的工具知识：Agent 可了解所有 15+ 个可用工具及其功能
• 工作流编排：了解如何将工具串联起来，以完成复杂的开发工作流
• 作业轮询协议：正确处理异步操作的关键指令
• 最佳实践：性能优化和错误处理策略
• 集成模式：用于研究、规划和实现的常见工作流

使用示例

集成后，你的 AI Agent 将能够：

# 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"

验证

若要验证是否成功集成：

1. 询问你的 AI Agent 有哪些可用的 Vibe Coder 工具
2. 请求一个按顺序使用多个工具的工作流
3. 检查 Agent 是否遵循正确的作业轮询协议
4. 确认输出已保存到正确的目录

🎯 统一 CLI 架构（v0.2.3+）

全新的统一 CLI（unified-cli.ts）为所有 Vibe Coder 操作提供单一入口：

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]

统一 CLI 的优势：

• 所有操作共用一个二进制文件（vibe）
• 命令接口一致
• 配置管理共享
• 模式切换无缝衔接
• 更高效地利用资源

项目架构

Vibe Coder MCP 服务采用模块化 TypeScript ESM 架构，支持双传输方式并提供全面的工具生态系统：

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 使用高级路由方法，为每个请求选择合适的工具：

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]

工具注册表模式

工具注册表是用于管理工具定义和执行的核心组件：

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

顺序思考流程

顺序思考机制提供基于 LLM 的回退路由：

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

工作流执行引擎

工作流系统支持执行多步骤序列：

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.json 文件内。该文件包含预定义的工具调用序列，可通过单条命令执行。

文件位置和结构

• workflows.json 文件必须放在项目根目录中（与 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.input.paramName}
• 上一步的输出：{steps.stepId.output.content[0].text}

触发工作流

使用 run-workflow 工具，并提供：

Run the newProjectSetup workflow with input {"productDescription": "A task manager app"}

工具详细文档

src/tools/ 目录中的每个工具都在自己的 README.md 文件中附有全面的文档。这些文件涵盖：

• 工具概览和用途
• 输入／输出规范
• 工作流图（Mermaid）
• 使用示例
• 使用的系统提示词
• 错误处理详情

如需深入了解，请参阅以下各 README 文件：

• src/tools/fullstack-starter-kit-generator/README.md
• src/tools/prd-generator/README.md
• src/tools/research/README.md
• src/tools/rules-generator/README.md
• src/tools/task-list-generator/README.md
• src/tools/user-stories-generator/README.md
• src/tools/workflow-runner/README.md
• src/tools/map-codebase/README.md

工具类别

分析与信息工具

• 代码映射工具（map-codebase）：扫描代码库以提取语义信息（类、函数、注释），并生成易读的 Markdown 映射（含 Mermaid 图），或生成结构化 JSON 表示，其中包含导入项的绝对文件路径和增强的类属性信息。
• 上下文整理工具（curate-context）：通过 8 阶段工作流流水线进行智能代码库分析和上下文包整理，支持智能代码映射缓存、适配多种语言的项目检测（支持 35 种以上编程语言），并通过多策略文件发现服务 AI 驱动的开发任务。
• 研究工具（research）：使用 Perplexity Sonar 对技术主题开展深入研究，并提供摘要和来源。

规划与文档工具

• **规则生成器（rules-generator）：**创建项目专属的开发规则和指南。
• **PRD 生成器（prd-generator）：**生成全面的产品需求文档。
• **用户故事生成器（user-stories-generator）：**创建包含验收标准的详细用户故事。
• **任务列表生成器（task-list-generator）：**构建包含依赖项的结构化开发任务列表。

项目脚手架工具

• **全栈入门套件生成器（fullstack-starter-kit-generator）：**根据指定的前端／后端技术创建定制的项目入门套件，其中包括基本设置脚本和配置。

工作流与编排

• **工作流运行器（run-workflow）：**执行预定义的工具调用序列，以完成常见开发任务。

生成文件存储

默认情况下，生成器工具的输出会存储在项目中的 VibeCoderOutput/ 目录内，以供历史参考。可以通过在 .env 文件或 AI 助手配置中设置 VIBE_CODER_OUTPUT_DIR 环境变量来更改此位置。

读写操作的安全边界

出于安全考虑，Vibe Coder MCP 工具采用默认安全方式，为读写操作设置了独立的安全边界：

• 读取操作：

  • 代码地图工具：仅从通过 CODE_MAP_ALLOWED_DIR 环境变量明确授权的目录读取
  • Vibe Task Manager：仅从通过 VIBE_TASK_MANAGER_READ_DIR 环境变量授权的目录读取（默认为 process.cwd()）
  • 安全模式：Vibe Task Manager 默认采用“严格”安全模式，禁止访问 /private/var/spool/postfix/、/System/ 等系统目录及其他未经授权的路径
  • 文件系统安全：全面执行黑名单检查并进行权限校验，防止出现 EACCES 错误和未经授权的文件访问

• 写入操作：所有输出文件都写入 VIBE_CODER_OUTPUT_DIR 目录（或其子目录）。这种隔离确保工具只能写入指定的输出位置，避免源代码被意外修改。

• 安全实现：文件系统安全系统包括：

  • 自适应超时管理：通过智能重试和取消机制，防止操作无限期挂起
  • 路径验证：访问前全面验证所有文件路径
  • 权限检查：主动验证权限，防止访问错误
  • 系统目录保护：内置不应被访问的系统目录黑名单

示例结构（默认位置）：

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/

MCP 客户端的系统指令

为确保 AI 助手和 MCP 客户端发挥最佳性能，请使用 VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 中提供的完整系统指令。该文档包含以下方面的详细指南：

• 工具专属的用法模式和最佳实践
• 自然语言命令结构
• 异步任务轮询指南
• 集成工作流和示例
• 错误处理与故障排除

如何使用系统指令

对于 Claude Desktop：

1. 打开 Claude Desktop 设置
2. 导航至“自定义指令”或“系统提示词”
3. 复制 VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 中的全部内容
4. 粘贴到自定义指令字段
5. 保存设置

对于 Augment：

1. 打开 Augment 设置/偏好设置
2. 找到“自定义指令”或“系统配置”
3. 复制并粘贴系统指令
4. 应用更改

对于 Claude Code/Windsurf/其他 MCP 客户端：

1. 找到自定义指令或系统提示词配置
2. 复制 VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 中的内容
3. 粘贴到相应字段
4. 保存/应用配置

使用系统指令的优势：

• 工具操作成功率达 98% 以上
• 更准确地识别自然语言命令
• 妥善处理异步任务
• 高效编排工作流
• 减少错误并改进故障排除

使用示例

通过 CLI（直接使用命令行）

# 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\"}"

通过 MCP 客户端（AI 助手集成）

通过已连接的 AI 助手使用这些工具：

• 研究： Research modern JavaScript frameworks
• 生成规则： Create development rules for a mobile banking application
• 生成 PRD： Generate a PRD for a task management application
• 生成用户故事： Generate user stories for an e-commerce website
• 生成任务列表： Create a task list for a weather app based on [user stories]
• 顺序思考： Think through the architecture for a microservices-based e-commerce platform
• 全栈入门套件： Create a starter kit for a React/Node.js blog application with user authentication
• 运行工作流： Run 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"，或 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，或 Analyze this codebase for performance optimization opportunities
• Vibe Task Manager： Create a new project for building a todo app、List all my projects、Run task authentication-setup、What's the status of my React project?

Vibe Task Manager - AI 原生任务管理

Vibe Task Manager 是一套全面的任务管理系统，专为 AI Agent 和开发工作流设计。它支持智能项目拆解、自然语言命令处理，并可与其他 Vibe Coder 工具无缝集成。

状态：功能完备，可用于生产环境，测试成功率达 99.9%；同时仍在积极增强功能并持续改进。

主要功能

• 自然语言处理：理解“为构建 React 应用创建项目”或“显示所有待处理任务”等命令
• 递归拆解设计（RDD）：自动将复杂项目拆解为原子化、可执行的任务
• 制品解析集成：无缝导入 VibeCoderOutput/prd-generator/ 中的 PRD 文件，以及 VibeCoderOutput/generated_task_lists/ 中的任务列表
• 会话持久化：增强的会话跟踪，支持触发编排工作流，确保多步骤操作可靠执行
• 全面的 CLI：功能齐全的命令行界面，支持自然语言处理和结构化命令
• Agent 编排：协调多个 AI Agent 并行执行任务
• 支持集成：可与 Code Map Tool、Research Tool 及其他工具无缝协作
• 文件存储：所有项目数据均存储在 VibeCoderOutput/vibe-task-manager/ 中，并遵循既定规范

快速入门示例

# 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?"

🎯 增强型项目查找功能

• 智能解析：自动识别项目 ID、名称或部分匹配项
• 全面验证：拆解前验证项目是否已准备就绪
• 增强的错误消息：提供可操作的指导，包括可用项目和用法示例
• 多种输入格式：支持项目 ID、加引号的名称、部分名称和模糊匹配
• 置信度评分：显示解析置信度，便于更好地向用户提供反馈

命令结构

Vibe Task Manager 同时支持结构化命令和自然语言：

结构化命令：

• vibe-task-manager create project "Name" "Description" --options
• vibe-task-manager list projects --status pending
• vibe-task-manager run task task-id --force
• vibe-task-manager status project-id --detailed

自然语言（推荐）：

• “为[描述]创建一个项目”
• “显示所有[状态]项目”
• “运行[任务名称]任务”
• “[项目]的状态是什么？”
• “解析[项目名称]的 PRD 文件” （新增）
• “从[文件路径]导入任务列表” （新增）
• “解析所有 PRD 并自动创建项目” （新增）

完整文档请参阅 src/tools/vibe-task-manager/README.md 和 VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md 中的系统说明。

实施状态与性能指标

当前 Epic 状态

Vibe Coder MCP 项目采用基于 Epic 的开发方式，并进行全面跟踪：

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

Epic 完成摘要

• Epic 1-5：✅ 已完成（100%——核心基础设施和基础工具）
• Epic 6.1：✅ 已完成（测试成功率 98.3%——深入的 MCP 工具集成）
• Epic 6.2：🔄 进行中（性能优化——完成 75%）
• Epic 7.1：📋 计划中（安全实现——已准备就绪）
• Epic 8：📋 计划中（高级分析与监控——已设计）

性能目标与当前指标（v0.2.3）

指标	目标	当前值	状态
测试成功率	98%+	99.9%	✅ 超出目标
响应时间（任务操作）	<200ms	<150ms	✅ 超出目标
响应时间（同步操作）	<500ms	<350ms	✅ 超出目标
作业完成率	95%+	96.7%	✅ 达标
内存用量（Code Map 工具）	<512MB	<400MB	✅ 已优化
单元测试覆盖率	>70%	73%	✅ 达标
CI/CD 流水线速度	<5min	~3min	✅ 已优化
安全开销	<50ms	<35ms	✅ 已优化
零模拟代码策略	100%	100%	✅ 已实现

各工具状态

Vibe Task Manager

• 状态：已可用于生产（功能完善，但仍在积极增强）
• 测试覆盖率：99.9%
• 功能：RDD 方法、Agent 编排、自然语言处理、制品解析、会话持久化、全面的 CLI
• 性能：任务操作的响应时间 <50ms
• 近期新增：PRD/任务列表集成、增强的会话跟踪、编排工作流

Code Map Tool

• 状态：已可用于生产，具备高级功能
• 内存优化：已实现 95-97% 的令牌缩减
• 语言支持：35+ 种编程语言
• 导入解析：通过基于适配器的架构得到增强

Context Curation Tool

• 状态：已可用于生产，具备智能 Codemap 缓存
• 语言支持：35+ 种编程语言，准确率达 95%+
• 工作流流水线：8 阶段智能分析与整理
• 项目检测：语言无关，支持多策略文件发现
• 性能优化：智能缓存系统，可复用近期 Codemap（可配置为 1-1440 分钟）

Research Tool

• 状态：已可用于生产
• 集成：Perplexity Sonar API
• 性能：研究查询的平均响应时间 <2s

其他工具

• 全栈生成器：已可用于生产
• PRD/用户故事/任务列表生成器：已可用于生产
• 工作流运行器：已可用于生产

本地运行（可选）

主要用途是通过 stdio 与 AI 助手集成；你也可以直接运行服务进行测试：

运行模式

• 生产模式（Stdio）：

  npm start
  

  • 日志输出到 stderr（模拟 AI 助手启动）
  • 使用 NODE_ENV=production

• 开发模式（Stdio，美化日志）：

  npm run dev
  

  • 日志以美化格式输出到 stdout
  • 需要 nodemon 和 pino-pretty
  • 使用 NODE_ENV=development

• SSE 模式（HTTP 接口）：

  # 生产模式，通过 HTTP 运行
  npm run start:sse
  
  # 开发模式，通过 HTTP 运行
  npm run dev:sse
  

  • 使用 HTTP，而非 stdio
  • 通过 .env 中的 PORT 配置（默认值：3000）
  • 访问地址：http://localhost:3000

详细故障排除

连接问题

AI 助手未检测到 MCP 服务

1. 检查配置路径：

   • 确认 args 数组中的绝对路径正确
   • 确保所有斜杠都是正斜杠 /，即使在 Windows 上也是如此
   • 直接运行 node <path-to-build/index.js>，测试 Node 是否能找到它

2. 检查配置格式：

   • 确保 JSON 有效且没有语法错误
   • 检查属性之间的逗号是否正确
   • 确认 mcpServers 对象中包含你的服务

3. 重启助手：

   • 完全关闭应用（不要只是最小化）
   • 重新打开并重试

服务已启动，但工具无法使用

1. 检查禁用标记：

   • 确保设置了 "disabled": false
   • 删除所有 // 注释，因为 JSON 不支持注释

2. 检查 autoApprove 数组：

   • 确认 autoApprove 数组中的工具名称完全匹配
   • 如果使用混合路由，尝试将 "process-request" 添加到数组中

API 密钥问题

1. OpenRouter 密钥问题：

   • 仔细检查密钥是否复制正确
   • 确认密钥在 OpenRouter 控制面板中处于有效状态
   • 检查是否有足够的余额

2. 环境变量问题：

   • 确认以下两处的密钥均正确：
     • .env 文件（用于本地运行）
     • AI 助手配置的 env 区块

路径和权限问题

1. 未找到构建目录：

   • 运行 npm run build，确保构建目录存在
   • 检查构建输出是否指向其他目录（查看 tsconfig.json）

2. 文件权限错误：

   • 确保你的用户对 workflow-agent-files 目录有写入权限
   • 在 Unix 系统上，检查 build/index.js 是否具有执行权限

日志调试

1. 本地运行时：

   • 检查控制台输出中的错误消息
   • 尝试在 .env 文件中设置 LOG_LEVEL=debug 后运行

2. 通过 AI 助手运行时：

   • 在 env 配置中设置 "NODE_ENV": "production"
   • 检查助手是否提供日志控制台或输出窗口

特定工具的问题

1. 语义路由无法正常工作：
   • 首次运行时可能会下载嵌入模型，请留意下载消息
   • 尝试使用更明确的请求，并提及工具名称

文档

核心文档

• 系统说明：VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md - MCP 客户端完整使用指南
• CI/CD 指南：CI_CD_GUIDE.md - 精简的流水线文档（速度提升 70%）
• NPM 发布指南：NPM_PUBLISHING_GUIDE.md - 发布与部署流程
• 系统架构：docs/ARCHITECTURE.md - 全面的系统架构说明，包含 Mermaid 图表
• 性能与测试：docs/PERFORMANCE_AND_TESTING.md - 性能指标、测试策略和质量保证
• Vibe Task Manager：src/tools/vibe-task-manager/README.md - 全面的任务管理文档
• Context Curation Tool：src/tools/curate-context/README.md - 与语言无关的代码库分析文档
• Code Map Tool：src/tools/map-codebase/README.md - 高级代码库分析文档

工具文档

• 各工具的 README：每个工具目录都包含详细文档
• 配置指南：环境设置和配置管理
• API 参考：工具的架构和参数记录在系统说明中
• 集成示例：实用工作流和使用模式

架构文档

• 系统架构：README 和系统说明中的 Mermaid 图表
• 工具架构：各工具的架构图
• 性能指标：当前状态和优化策略
• 开发指南：贡献和开发最佳实践

贡献

欢迎贡献！请参阅我们的贡献指南，并确保提交拉取请求前所有测试均通过。

开发工作流

1. Fork 此仓库
2. 创建功能分支
3. 进行更改并编写全面的测试
4. 确保所有检查在本地均通过：

   # 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
   

5. 提交拉取请求，并附上详细说明

质量标准

• 类型安全：禁止使用 any 类型——必须使用严格的 TypeScript
• CI 流水线：必须通过类型检查、Lint 和构建（自动化）
• 测试：提交 PR 前在本地运行单元测试
• 测试覆盖率：单元测试覆盖率须保持在 70% 以上
• 文档：针对更改更新相关文档
• 性能：考虑对 CI 流水线速度的影响（目标：<5 min）

常见问题排查

OpenRouter API 密钥问题

问题：工具因身份验证错误而失败

• 解决方案：确认 .env 中已正确设置 OpenRouter API 密钥
• 检查：确保密钥中没有多余空格或引号
• 验证：在 openrouter.ai 测试密钥
• 额度：确保 OpenRouter 账户中有足够的额度

路径配置问题

问题：出现“找不到路径”或“拒绝访问”错误

• 解决方案：在所有配置中使用带正斜杠（/）的绝对路径
• Windows：将 C:\Users\name 之类的路径转换为 C:/Users/name
• 权限：确保用户对配置的目录具有读写权限
• 环境变量：确认已正确设置 VIBE_CODER_OUTPUT_DIR 和 VIBE_PROJECT_ROOT（或旧版变量 CODE_MAP_ALLOWED_DIR 和 VIBE_TASK_MANAGER_READ_DIR）

构建失败

问题：TypeScript 编译错误

• 解决方案：运行 npm run clean && npm run build
• 依赖项：删除 node_modules 和 package-lock.json，然后运行 npm install
• Node 版本：确保已安装 Node.js v20+（node -v）
• TypeScript：运行 npm run lint 检查语法错误

测试失败

问题：测试在本地失败，或 CI 中出现类型检查错误

• 类型错误：在本地运行 npm run type-check，尽早发现问题
• Lint 问题：使用 npm run lint:fix 自动修复样式问题
• 环境：确保 .env 文件存在且包含有效的 OPENROUTER_API_KEY
• 内存：内存小于 4GB 的系统可能无法通过测试
• 网络：部分测试需要互联网连接
• 清理：运行测试前执行 npm run clean
• CI 流水线：有关流水线详情，请参阅 CI/CD 指南

内存／性能问题

问题：内存使用率高或性能缓慢

• 大型代码库：对于文件数超过 10,000 的项目，Code Map Tool 可能会占用大量内存
• 解决方案：提高 Node.js 内存限制：NODE_OPTIONS='--max-old-space-size=4096' npm start
• 缓存：如果 VibeCoderOutput/ 中的缓存目录过大，请清除这些目录
• 监控：使用 npm run test:memory 查找内存泄漏

MCP 客户端连接问题

问题：AI 助手未检测到服务

• 路径：确认 MCP 配置中的所有路径均使用正斜杠，且为绝对路径
• 重启：完全关闭并重启 AI 助手应用
• 日志：在配置中设置 LOG_LEVEL=debug，查看详细错误消息
• 传输：确保正确设置 "transport": "stdio"
• 已禁用：确认配置中设置了 "disabled": false

特定工具问题

Vibe Task Manager：

• 如果自然语言命令无法使用，请尝试使用结构化命令
• 检查 VibeCoderOutput/vibe-task-manager/ 中的项目文件
• 确保项目名称不包含特殊字符

Code Map Tool：

• 如果出现权限错误，请确认已设置 CODE_MAP_ALLOWED_DIR
• 大型代码库可能会超时——请尝试使用较小的子目录
• 某些语言需要额外设置（请参阅工具 README）

Context Curator：

• 如果生成 codemap 失败，请检查缓存中的近期 codemap
• 确保有足够的磁盘空间来存放大型上下文包
• 检查目标目录中的文件权限

网络和代理问题

问题：无法访问外部服务

• 代理：如果使用代理，请设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量
• SSL：如果遇到 SSL 问题，请尝试设置 NODE_TLS_REJECT_UNAUTHORIZED=0（仅限开发环境）
• 防火墙：确保防火墙允许出站 HTTPS 连接
• DNS：如果解析失败，请尝试使用公共 DNS 服务器

获取帮助

如果问题仍然存在：

1. 查看 GitHub Issues 中的现有问题
2. 启用调试日志：LOG_LEVEL=debug
3. 收集错误消息和日志
4. 创建新问题并附上：
   • Node.js 版本（node -v）
   • 操作系统
   • 错误消息
   • 复现步骤

📅 更新日志

Version 0.3.5 (Latest)

• 增强型混合匹配器：为全部 15 个工具完整提取参数
• CLI/REPL 改进：交互式确认、带进度显示的作业轮询
• 错误修复：Task-list-generator 自动生成用户故事，修复多轮对话问题
• TypeScript 严格模式：无 any 类型，达到生产级代码质量

Version 0.3.1

• 修复全局安装同步问题
• 改进清理构建流程
• 改进 NPM 打包工作流

Version 0.2.8

• CLI 交互模式配置持久化
• 增强项目根目录检测

Version 0.2.7

• 将缺失的配置文件添加到 npm 包
• 解决配置加载错误

Version 0.2.3

• 带聊天界面的交互式 REPL 模式
• 增强设置向导，支持自动检测
• 配置模板
• 统一的 CLI 二进制文件

完整的发布历史请参阅 GitHub Releases

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。