Vibe Coder MCP 服务器
Vibe Coder 是一款 MCP（模型上下文协议）服务器，旨在为您的 AI 助手（例如 Cursor、Cline AI 或 Claude Desktop）提供强大的软件开发工具。它可以帮助您进行研究、规划、生成需求、创建启动项目等等！
概述和特点
Vibe Coder MCP 与 MCP 兼容客户端集成，提供以下功能：
- 语义请求路由：使用基于嵌入的语义匹配和顺序思维回退智能地路由请求。
- 工具注册架构：采用自注册工具进行集中工具管理。
- 直接 LLM 调用：生成器工具现在使用直接 LLM 调用来提高可靠性和结构化输出控制。
- 工作流执行：运行
workflows.json中定义的预定义工具调用序列。 - 研究与规划：进行深入研究（
research-manager ）并生成规划文档，如 PRD（ generate-prd ）、用户故事（ generate-user-stories ）、任务列表（ generate-task-list ）和开发规则（ generate-rules ）。 - 项目脚手架：生成全栈入门套件（
generate-fullstack-starter-kit ）。 - 代码图生成器：递归扫描代码库，提取语义信息，并使用 Mermaid 图表生成标记高效、上下文密集的 Markdown 索引，或生成具有导入绝对文件路径和增强类属性信息的结构化 JSON 表示（
map-codebase ）。 - 异步执行：许多长期运行的工具（生成器、研究、工作流）现在都支持异步运行。它们会立即返回作业 ID，并使用
get-job-result工具检索最终结果。 - 会话状态管理：维护会话内各个请求的基本状态（在内存中）。
- 标准化错误处理：所有工具的错误模式一致。
（有关更多信息，请参阅下面的“详细工具文档”和“功能详细信息”部分）
设置指南
按照这些微步骤让 Vibe Coder MCP 服务器运行并连接到您的 AI 助手。
步骤 1：先决条件
- 检查 Node.js 版本：
- 打开终端或命令提示符。
- 运行
node -v - 确保输出显示 v18.0.0 或更高版本（必需）。
- 如果未安装或已过时：从nodejs.org下载。
- 检查 Git 安装：
- 获取 OpenRouter API 密钥：
- 访问openrouter.ai
- 如果您还没有帐户，请创建一个。
- 导航至 API 密钥部分。
- 创建一个新的 API 密钥并复制它。
- 保留此密钥以用于步骤 4。
第 2 步：获取代码
- 创建项目目录（可选）：
- 打开终端或命令提示符。
- 导航到您想要存储项目的位置：
cd ~/Documents # Example: Change to your preferred location
- 克隆存储库：
- 跑步：
git clone https://github.com/freshtechbro/vibe-coder-mcp.git
- 导航到项目目录：
步骤 3：运行安装脚本
为您的操作系统选择适当的脚本：
对于 Windows：
- 在您的终端中（仍在 vibe-coder-mcp 目录中），运行：
- 等待脚本完成（它将安装依赖项、构建项目并创建必要的目录）。
- 如果您看到任何错误消息，请参阅下面的故障排除部分。
对于 macOS 或 Linux：
- 使脚本可执行：
- 运行脚本：
- 等待脚本完成。
- 如果您看到任何错误消息，请参阅下面的故障排除部分。
该脚本执行以下操作：
- 检查 Node.js 版本 (v18+)
- 通过 npm 安装所有依赖项
- 创建必要的
VibeCoderOutput/子目录（如脚本中所定义）。 - 构建 TypeScript 项目。
- **如果
.env不存在，则将.env.example复制到.env文件。**您需要编辑此文件。 - 设置可执行权限（在 Unix 系统上）。
步骤 4：配置环境变量（ .env ）
安装脚本（来自步骤 3）通过复制.env.example模板自动在项目的根目录中创建.env文件，但前提是.env不存在。
- **找到并打开
.env ：**在主vibe-coder-mcp目录中找到.env文件并使用文本编辑器打开它。 - 添加您的 OpenRouter API 密钥（必需）：
- 该文件包含基于
.env.example的模板：# OpenRouter Configuration
## Specifies your unique API key for accessing OpenRouter services.
## Replace "Your OPENROUTER_API_KEY here" with your actual key obtained from OpenRouter.ai.
OPENROUTER_API_KEY="Your OPENROUTER_API_KEY here"
## Defines the base URL for the OpenRouter API endpoints.
## The default value is usually correct and should not need changing unless instructed otherwise.
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
## Sets the specific Gemini model to be used via OpenRouter for certain AI tasks.
## ':free' indicates potential usage of a free tier model if available and supported by your key.
GEMINI_MODEL=google/gemini-2.0-flash-thinking-exp:free
- **至关重要的是，将
"Your OPENROUTER_API_KEY here"替换为您的实际 OpenRouter API 密钥。**如果您的密钥不需要引号，请删除引号。
- 配置输出目录（可选）：
- 要更改生成的文件的保存位置（默认为项目内的
VibeCoderOutput/ ），请将此行添加到您的.env文件中：VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
- 将路径替换为您首选的绝对路径。路径使用正斜杠 (
/ )。如果未设置此变量，则将使用默认目录 ( VibeCoderOutput/ )。
- 配置代码图生成器目录（可选）：
- 要指定 code-map-generator 工具允许扫描哪个目录，请将此行添加到您的
.env文件中：CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
- 将路径替换为包含要分析的源代码的目录的绝对路径。这是一个安全边界 - 该工具不会访问此目录之外的文件。
- 请注意，出于安全考虑，
CODE_MAP_ALLOWED_DIR （用于读取源代码）和VIBE_CODER_OUTPUT_DIR （用于写入输出文件）是分开的。code-map-generator 工具对读取和写入操作使用单独的验证。
- 检查其他设置（可选）：
- 您可以添加服务器支持的其他环境变量，例如
LOG_LEVEL （例如， LOG_LEVEL=debug ）或NODE_ENV （例如， NODE_ENV=development ）。
- 保存
.env文件。
步骤 5：与您的 AI 助手集成（MCP 设置）
此关键步骤通过将 Vibe Coder 的配置添加到客户端的 MCP 设置文件来将其连接到您的 AI 助手。
5.1：找到客户端的 MCP 设置文件
位置取决于你的人工智能助手：
- 光标 AI / Windsurf / RooCode（基于 VS Code）：
- 打开应用程序。
- 打开命令面板（
Ctrl+Shift+P或Cmd+Shift+P ）。 - 键入并选择
Preferences: Open User Settings (JSON) 。 - 这将打开
mcpServers对象所在的settings.json文件。
- Cline AI（VS 代码扩展）：
- 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 ）
- 克劳德桌面：
- 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配置
- 在文本编辑器中打开上面确定的设置文件。
- 找到
"mcpServers": { ... } JSON 对象。如果它不存在，您可能需要创建它（确保整个文件保持有效的 JSON 格式）。例如，一个空文件可能变成{"mcpServers": {}} 。 - 在
mcpServers对象的花括号{}内添加以下配置块。如果已列出其他服务器，请在粘贴此块之前,在上一个服务器的右括号}后添加逗号 ,。// This is the unique identifier for this MCP server instance within your client's settings
"vibe-coder-mcp": {
// Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH
"command": "node",
// Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point
// !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
"args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"],
// Sets the current working directory for the server process when it runs
// !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
"cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
// Defines the communication transport protocol between the client and server
"transport": "stdio",
// Environment variables to be passed specifically to the Vibe Coder server process when it starts
// API Keys should be in the .env file, NOT here
"env": {
// Absolute path to the LLM configuration file used by Vibe Coder
// !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
"LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json",
// Sets the logging level for the server
"LOG_LEVEL": "debug",
// Specifies the runtime environment
"NODE_ENV": "production",
// Directory where Vibe Coder tools will save their output files
// !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
"VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput",
// Directory that the code-map-generator tool is allowed to scan
// This is a security boundary - the tool will not access files outside this directory
"CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src"
},
// A boolean flag to enable (false) or disable (true) this server configuration
"disabled": false,
// A list of tool names that the MCP client is allowed to execute automatically
"autoApprove": [
"research",
"generate-rules",
"generate-user-stories",
"generate-task-list",
"generate-prd",
"generate-fullstack-starter-kit",
"refactor-code",
"git-summary",
"run-workflow",
"map-codebase"
]
}
- 关键：将所有占位符路径（例如
/path/to/your/vibe-coder-mcp/... ）替换为您克隆仓库的系统上的正确绝对路径。即使在 Windows 上，也要使用正斜杠/表示路径（例如C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js ）。路径错误是服务器连接失败的最常见原因。 - 保存设置文件。
- 完全关闭并重新启动您的 AI 助手应用程序（Cursor、VS Code、Claude Desktop 等），以使更改生效。
步骤 6：测试您的配置
- 启动你的AI助手：
- 测试一个简单的命令：
- 输入测试命令，例如：
Research modern JavaScript frameworks
- 检查是否正确响应：
- 如果工作正常，您应该会收到研究回复。
- 如果没有，请检查下面的故障排除部分。
项目架构
Vibe Coder MCP 服务器遵循以工具注册模式为中心的模块化架构：
目录结构
vibe-coder-mcp/
├── .env # Environment configuration
├── mcp-config.json # Example MCP configuration
├── package.json # Project dependencies
├── README.md # This 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
├── VibeCoderOutput/ # Tool output directory
│ ├── research-manager/
│ ├── rules-generator/
│ ├── prd-generator/
│ ├── user-stories-generator/
│ ├── task-list-generator/
│ ├── fullstack-starter-kit-generator/
│ └── workflow-runner/
└── src/ # Source code
├── index.ts # Entry point
├── logger.ts # Logging configuration (Pino)
├── server.ts # MCP server setup
├── services/ # Core services
│ ├── AIService.ts # AI model interaction (OpenRouter)
│ ├── JobManager.ts # Manages async jobs
│ └── ToolService.ts# Tool registration and routing
├── tools/ # MCP Tools
│ ├── index.ts # Tool registration
│ ├── sequential-thinking.ts # Fallback routing
│ ├── fullstack-starter-kit-generator/ # Project gen
│ ├── prd-generator/ # PRD creation
│ ├── research-manager/ # Research tool
│ ├── rules-generator/ # Rule generation
│ ├── task-list-generator/ # Task list generation
│ ├── user-stories-generator/ # User story generation
│ └── workflow-runner/ # Workflow execution engine
├── types/ # TypeScript type definitions
{{ ... }}
## Semantic Routing System
Vibe Coder uses a sophisticated routing approach to select the right tool for each request:
```mermaid
flowchart TD
Start[Client Request] --> Process[Process Request]
Process --> Hybrid[Hybrid Matcher]
subgraph "Primary: Semantic Routing"
Hybrid --> Semantic[Semantic Matcher]
Semantic --> Embeddings[Query Embeddings]
Embeddings --> Tools[Tool Embeddings]
Tools --> Compare[Compare via Cosine Similarity]
Compare --> Score[Score & Rank Tools]
Score --> Confidence{High Confidence?}
end
Confidence -->|Yes| Registry[Tool Registry]
subgraph "Fallback: Sequential Thinking"
Confidence -->|No| Sequential[Sequential Thinking]
Sequential --> LLM[LLM Analysis]
LLM --> ThoughtChain[Thought Chain]
ThoughtChain --> Extraction[Extract Tool Name]
Extraction --> Registry
end
Registry --> Executor[Execute Tool]
Executor --> Response[Return Response]
工具注册表模式
工具注册表是管理工具定义和执行的核心组件：
顺序思维过程
顺序思维机制提供了基于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工具：
Run the newProjectSetup workflow with input {"productDescription": "A task manager app"}
详细工具文档
src/tools/目录下的每个工具都包含其各自的 README.md 文件中的详尽文档。这些文件涵盖：
- 工具概述和用途
- 输入/输出规格
- 工作流程图（美人鱼）
- 使用示例
- 使用的系统提示
- 错误处理详细信息
请参阅以下单独的自述文件以获取详细信息：
src/tools/fullstack-starter-kit-generator/README.mdsrc/tools/prd-generator/README.mdsrc/tools/research-manager/README.mdsrc/tools/rules-generator/README.mdsrc/tools/task-list-generator/README.mdsrc/tools/user-stories-generator/README.mdsrc/tools/workflow-runner/README.mdsrc/tools/code-map-generator/README.md
工具类别
分析与信息工具
- 代码图生成器（
map-codebase ） ：扫描代码库以提取语义信息（类、函数、注释），并生成带有美人鱼图表的人类可读的 Markdown 地图或带有用于导入和增强类属性信息的绝对文件路径的结构化 JSON 表示。 - 研究经理 (
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环境变量来覆盖此位置。
读写操作的安全边界
出于安全原因，Vibe Coder MCP 工具为读取和写入操作维护单独的安全边界：
- 读取操作：像 code-map-generator 这样的工具仅从通过
CODE_MAP_ALLOWED_DIR环境变量明确授权的目录中读取数据。这创建了清晰的安全边界，并防止未经授权访问允许目录之外的文件。 - 写入操作：所有输出文件均写入
VIBE_CODER_OUTPUT_DIR目录（或其子目录）。这种隔离确保工具只能写入指定的输出位置，从而保护您的源代码免遭意外修改。
示例结构（默认位置）：
VibeCoderOutput/
├── research-manager/ # 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/
├── code-map-generator/ # Code maps and diagrams
│ └── TIMESTAMP-code-map/
└── workflow-runner/ # Workflow outputs
└── TIMESTAMP-WORKFLOW/
使用示例
通过连接的 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 - 运行工作流：
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"
本地运行（可选）
虽然主要用途是与 AI 助手集成（使用 stdio），但您可以直接运行服务器进行测试：
运行模式
- 生产模式（Stdio）：
- 日志发送到 stderr（模拟 AI 助手启动）
- 使用 NODE_ENV=production
- 开发模式（Stdio，Pretty Logs）：
- 日志以漂亮的格式输出到标准输出
- 需要
nodemon和pino-pretty - 使用 NODE_ENV=development
- SSE模式（HTTP接口）：
# Production mode over HTTP
npm run start:sse
# Development mode over HTTP
npm run dev:sse
详细故障排除
连接问题
AI 助手未检测到 MCP 服务器
- 检查配置路径：
- 验证
args数组中的绝对路径是否正确 - 确保所有斜杠都是正斜杠
/即使在 Windows 上 - 直接运行
node <path-to-build/index.js>来测试 Node 是否可以找到它
- 检查配置格式：
- 确保 JSON 有效且无语法错误
- 检查属性之间的逗号是否正确
- 验证
mcpServers对象是否包含你的服务器
- 重启助手：
服务器启动但工具不起作用
- 检查禁用标志：
- 确保设置了
"disabled": false - 删除所有
//注释，因为 JSON 不支持它们
- 验证自动批准数组：
- 检查
autoApprove数组中的工具名称是否完全匹配 - 如果使用混合路由，请尝试将
"process-request"添加到数组中
API 密钥问题
- OpenRouter 关键问题：
- 仔细检查密钥是否正确复制
- 验证密钥在 OpenRouter 仪表板中是否有效
- 检查您是否有足够的积分
- 环境变量问题：
- 验证密钥是否正确：
.env文件（用于本地运行）- 你的AI助手的配置环境块
路径和权限问题
- 未找到构建目录：
- 运行
npm run build以确保构建目录存在 - 检查构建输出是否进入不同的目录（检查 tsconfig.json）
- 文件权限错误：
- 确保您的用户对 workflow-agent-files 目录具有写权限
- 在 Unix 系统上，检查 build/index.js 是否具有执行权限
日志调试
- 对于本地运行：
- 检查控制台输出的错误消息
- 尝试在
.env文件中使用LOG_LEVEL=debug运行
- 对于AI助手运行：
- 在环境配置中设置
"NODE_ENV": "production" - 检查助手是否有日志控制台或输出窗口
特定于工具的问题
- 语义路由不起作用：
- 首次运行可能会下载嵌入模型 - 检查下载消息
- 尝试更明确的请求，其中提到工具名称