Vibe Coder MCP 服务器

Vibe Coder 是一款 MCP（模型上下文协议）服务器，旨在为您的 AI 助手（例如 Cursor、Cline AI 或 Claude Desktop）提供强大的软件开发工具。它可以帮助您进行研究、规划、生成需求、创建启动项目等等！

概述和特点

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

• 语义请求路由：使用基于嵌入的语义匹配和顺序思维回退智能地路由请求。
• 工具注册架构：采用自注册工具进行集中工具管理。
• 直接 LLM 调用：生成器工具现在使用直接 LLM 调用来提高可靠性和结构化输出控制。
• 工作流执行：运行workflows.json中定义的预定义工具调用序列。
• 代码生成：创建代码存根和样板（ generate-code-stub ）。
• 代码重构：改进和修改现有的代码片段（ refactor-code ）。
• 依赖关系分析：列出清单文件中的依赖关系（ analyze-dependencies ）。
• Git 集成：总结当前的 Git 更改（ git-summary ）。
• 研究与规划：进行深入研究（ research-manager ）并生成规划文档，如 PRD（ generate-prd ）、用户故事（ generate-user-stories ）、任务列表（ generate-task-list ）和开发规则（ generate-rules ）。
• 项目脚手架：生成全栈入门套件（ generate-fullstack-starter-kit ）。
• 异步执行：许多长期运行的工具（生成器、研究、工作流）现在都支持异步运行。它们会立即返回作业 ID，并使用get-job-result工具检索最终结果。
• 会话状态管理：维护会话内各个请求的基本状态（在内存中）。
• 标准化错误处理：所有工具的错误模式一致。

（有关更多信息，请参阅下面的“详细工具文档”和“功能详细信息”部分）

设置指南

按照这些微步骤让 Vibe Coder MCP 服务器运行并连接到您的 AI 助手。

步骤 1：先决条件

1. 检查 Node.js 版本：
   • 打开终端或命令提示符。
   • 运行node -v
   • 确保输出显示 v18.0.0 或更高版本（必需）。
   • 如果未安装或已过时：从nodejs.org下载。
2. 检查 Git 安装：
   • 打开终端或命令提示符。
   • 运行git --version
   • 如果未安装：从git-scm.com下载。
3. 获取 OpenRouter API 密钥：
   • 访问openrouter.ai
   • 如果您还没有帐户，请创建一个。
   • 导航至 API 密钥部分。
   • 创建一个新的 API 密钥并复制它。
   • 保留此密钥以用于步骤 4。

第 2 步：获取代码

1. 创建项目目录（可选）：
   • 打开终端或命令提示符。
   • 导航到您想要存储项目的位置：
     cd ~/Documents # Example: Change to your preferred location
2. 克隆存储库：
   • 跑步：
     git clone https://github.com/freshtechbro/vibe-coder-mcp.git
     （或者如果适用，使用你的 fork 的 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 版本 (v18+)
• 通过 npm 安装所有依赖项
• 创建必要的 workflow-agent-files 目录
• 构建 TypeScript 项目
• 如果不存在，则创建一个默认的.env文件（接下来您将填充该文件）。
• 设置可执行权限（在 Unix 系统上）

步骤 4：配置环境变量（ .env ）

1. 找到.env文件：
   • 在主vibe-coder-mcp目录中找到安装脚本创建的.env文件。
   • 使用任何文本编辑器打开它。
2. 添加您的 OpenRouter API 密钥：
   • 找到以下行： OPENROUTER_API_KEY=your_openrouter_api_key_here
   • 将your_openrouter_api_key_here替换为您的实际 OpenRouter API 密钥。
   • 不要在密钥周围添加引号。
3. 配置输出目录（可选）：
   • 要更改生成的文件的保存位置（默认为项目内的workflow-agent-files/ ），请添加以下行：
     VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
   • 将路径替换为您首选的绝对路径。请使用正斜杠 ( / )。如果未设置此变量，则将使用默认目录。
4. 检查其他设置（可选）：
   • 检查模型名称（ GEMINI_MODEL 、 PERPLEXITY_MODEL ），确保它们在你的 OpenRouter 方案中可用。llm_config.json llm_config.json可以根据需要为每个任务提供更精细的控制。
   • 检查LOG_LEVEL （默认值：info） - 选项包括：“fatal”、“error”、“warn”、“info”、“debug”、“trace”。
5. 保存.env文件。

第五步：与你的AI助手集成

这一步至关重要，它将 Vibe Coder 连接到你的 AI 助手。每个环境的配置略有不同。

5.1：查找项目的绝对路径

您需要build/index.js文件的完整绝对路径：

对于 Windows：

1. 在您的终端中，导航到构建目录：
   cd build
2. 获取绝对路径：
   echo %cd%\index.js
3. 复制输出（例如， C:\Users\YourName\Projects\vibe-coder-mcp\build\index.js ）

对于 macOS/Linux：

1. 在您的终端中，导航到构建目录：
   cd build
2. 获取绝对路径：
   pwd
3. 将/index.js附加到输出并复制结果（例如， /Users/YourName/Projects/vibe-coder-mcp/build/index.js ）

5.2：准备配置块

通过以下方式创建配置块：

1. 复制此 JSON 模板：
   "vibe-coder-mcp": { "command": "node", "args": ["PATH_PLACEHOLDER"], "env": { "NODE_ENV": "production" // API Keys and other sensitive config are now loaded via the .env file // You can optionally set VIBE_CODER_OUTPUT_DIR here if you prefer it over .env // "VIBE_CODER_OUTPUT_DIR": "/absolute/path/to/output" }, "disabled": false, "autoApprove": [ "research", "generate-rules", "generate-prd", "generate-user-stories", "generate-task-list", "generate-fullstack-starter-kit", "generate-code-stub", "refactor-code", "analyze-dependencies", "git-summary", "run-workflow" ] }
2. 将PATH_PLACEHOLDER替换为您在步骤 5.1 中获得的绝对路径。
   • 重要提示：即使在 Windows 上也要使用正斜杠/ （例如， C:/Users/... ）
3. **重要提示：**不要再将OPENROUTER_API_KEY直接放在此配置块中。它应该放在.env文件中。

5.3：配置你的特定AI助手

A. 光标 AI / 风帆冲浪 (基于 VS 代码)

1. 打开 Cursor 或 Windsurf 应用程序。
2. 打开命令面板：
   • Windows/Linux：按Ctrl+Shift+P
   • macOS：按Cmd+Shift+P
3. 键入并选择： Preferences: Open User Settings (JSON)
4. 在 JSON 文件中，查找或添加mcpServers对象：
   • 如果不存在，则添加： "mcpServers": {}
   • 如果存在，则找到该对象的右括号
5. 在mcpServers对象内添加您的配置块：
   • 如果列出了其他服务器，请在最后一个服务器后添加逗号
   • 粘贴步骤 5.2 中的配置块
6. 保存文件（ Ctrl+S或Cmd+S ）
7. 完全关闭并重新启动 Cursor/Windsurf

完整的settings.json 部分的示例：

B. Cline AI（VS 代码扩展）

1. 找到 Cline 设置文件：
   • Windows ： C:\Users\[YourUsername]\AppData\Roaming\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
2. 使用文本编辑器打开此文件。
3. 查找或添加mcpServers对象：
   • 如果文件为空，则添加： {"mcpServers": {}}
   • 如果存在但没有mcpServers ，则将其添加到根级别
4. 在mcpServers对象内添加您的配置块：
   • 如果列出了其他服务器，请在最后一个服务器后添加逗号
   • 粘贴步骤 5.2 中的配置块
5. 保存文件。
6. 完全重启 VS Code。

C.RooCode（VS Code Fork）

1. 打开 RooCode。
2. 打开命令面板（ Ctrl+Shift+P或Cmd+Shift+P ）。
3. 搜索并选择Preferences: Open User Settings (JSON) 。
4. 按照与 Cursor AI 相同的步骤（上面的 A 部分）。
5. 保存并重新启动 RooCode。

D.Claude 桌面

1. 找到 Claude Desktop 设置文件：
   • Windows ： C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json
   • macOS ： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux ： ~/.config/Claude/claude_desktop_config.json
2. 使用文本编辑器打开此文件。
3. 在根级别查找或添加mcpServers对象：
   • 如果文件有其他内容，请找到添加mcpServers位置
   • 如果已经有mcpServers ，请找到它
4. 在mcpServers对象内添加您的配置块：
   • 如果存在其他服务器，请在最后一个服务器后添加逗号
   • 粘贴步骤 5.2 中的配置块
5. 保存文件。
6. 关闭并重新打开 Claude Desktop。

完整的 claude_desktop_config.json 示例：

步骤 6：测试您的配置

1. 启动你的AI助手：
   • 完全重启你的AI助手应用程序。
2. 测试一个简单的命令：
   • 输入测试命令，例如： Research modern JavaScript frameworks
3. 检查响应是否正确：
   • 如果工作正常，您应该会收到研究回复。
   • 如果没有，请检查下面的故障排除部分。

项目架构

Vibe Coder MCP 服务器遵循以工具注册模式为中心的模块化架构：

目录结构

语义路由系统

Vibe Coder 使用复杂的路由方法为每个请求选择正确的工具：

工具注册表模式

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

顺序思维过程

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

会话状态管理

工作流执行引擎

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

工作流配置

工作流在项目根目录中的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工具：

详细工具文档

src/tools/目录下的每个工具都包含其各自的 README.md 文件中的详尽文档。这些文件涵盖：

• 工具概述和用途
• 输入/输出规格
• 工作流程图（美人鱼）
• 使用示例
• 使用的系统提示
• 错误处理详细信息

请参阅以下单独的自述文件以获取详细信息：

• src/tools/code-refactor-generator/README.md
• src/tools/code-stub-generator/README.md
• src/tools/dependency-analyzer/README.md
• src/tools/fullstack-starter-kit-generator/README.md
• src/tools/git-summary-generator/README.md
• src/tools/prd-generator/README.md
• src/tools/research-manager/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

工具类别

代码生成和重构工具

• 代码存根生成器 ( generate-code-stub ) ：根据描述和目标语言创建样板代码（函数、类等）。有助于快速搭建新组件。
• 代码重构生成器（ refactor-code ） ：采用现有代码片段和重构指令（例如，“转换为异步/等待”、“提高可读性”、“添加错误处理”）并返回修改后的代码。

分析与信息工具

• 依赖分析器（ analyze-dependencies ） ：解析清单文件（如package.json或requirements.txt以列出项目依赖项。
• Git 摘要生成器 ( git-summary ) ：提供当前 Git 状态的摘要，显示已暂存或未暂存的更改（差异）。有助于在提交前快速检查。
• 研究经理 ( research-manager ) ：使用 Perplexity Sonar 对技术主题进行深入研究，提供摘要和来源。

规划和文档工具

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

项目脚手架工具

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

工作流程和编排

• **工作流运行器 ( run-workflow )：**执行常见开发任务的预定义工具调用序列。

生成的文件存储

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

示例结构（默认位置）：

使用示例

通过连接的 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
• Fullstack Starter Kit： Create a starter kit for a React/Node.js blog application with user authentication
• 生成代码存根： Generate a python function stub named 'calculate_discount' that takes price and percentage
• 重构代码： Refactor this code to use async/await: [paste code snippet]
• 分析依赖关系： Analyze dependencies in package.json
• Git 摘要： Show unstaged git changes
• 运行工作流： Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }

本地运行（可选）

虽然主要用途是与 AI 助手集成（使用 stdio），但您可以直接运行服务器进行测试：

运行模式

• 生产模式（Stdio）：
  npm start
  • 日志发送到 stderr（模拟 AI 助手启动）
  • 使用 NODE_ENV=production
• 开发模式（Stdio，Pretty Logs）：
  npm run dev
  • 日志以漂亮的格式输出到标准输出
  • 需要nodemon和pino-pretty
  • 使用 NODE_ENV=development
• SSE模式（HTTP接口）：
  # Production mode over HTTP npm run start:sse # Development mode over 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数组中的工具名称是否完全匹配
   • 如果使用混合路由，请尝试将"process-request"添加到数组中

API 密钥问题

1. OpenRouter 关键问题：
   • 仔细检查密钥是否正确复制
   • 验证密钥在 OpenRouter 仪表板中是否有效
   • 检查您是否有足够的积分
2. 环境变量问题：
   • 验证密钥是否正确：
     • .env文件（用于本地运行）
     • 你的AI助手的配置环境块

路径和权限问题

1. 未找到构建目录：
   • 运行npm run build以确保构建目录存在
   • 检查构建输出是否进入不同的目录（检查 tsconfig.json）
2. 文件权限错误：
   • 确保您的用户对 workflow-agent-files 目录具有写权限
   • 在 Unix 系统上，检查 build/index.js 是否具有执行权限

日志调试

1. 对于本地运行：
   • 检查控制台输出的错误消息
   • 尝试在.env文件中使用LOG_LEVEL=debug运行
2. 对于AI助手运行：
   • 在环境配置中设置"NODE_ENV": "production"
   • 检查助手是否有日志控制台或输出窗口

特定于工具的问题

1. 语义路由不起作用：
   • 首次运行可能会下载嵌入模型 - 检查下载消息
   • 尝试更明确的请求，其中提到工具名称
2. **Git 摘要工具