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)。
• 异步执行：许多长时间运行的工具（生成器、研究、工作流）现在异步运行。它们立即返回一个 Job 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     # 示例：更改为你喜欢的位置
     

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 安装所有依赖项
• 创建必要的 VibeCoderOutput/ 子目录（如脚本中所定义）。
• 构建 TypeScript 项目。
• 如果 .env 尚不存在，则将 .env.example 复制到 .env。 你需要编辑此文件。
• 设置可执行权限（在 Unix 系统上）。

步骤 4：配置环境变量 (.env)

设置脚本（来自步骤 3）通过复制 .env.example 模板自动在项目的根目录中创建一个 .env 文件，仅当 .env 尚不存在时。

1. 找到并打开 .env： 在主 vibe-coder-mcp 目录中找到 .env 文件，并使用文本编辑器打开它。

2. 添加你的 OpenRouter API 密钥（必需）：

   • 该文件包含基于 .env.example 的模板：

     # OpenRouter 配置
     ## 指定用于访问 OpenRouter 服务的唯一 API 密钥。
     ## 将“Your OPENROUTER_API_KEY here”替换为从 OpenRouter.ai 获得的实际密钥。
     OPENROUTER_API_KEY="Your OPENROUTER_API_KEY here"
     
     ## 定义 OpenRouter API 端点的基本 URL。
     ## 默认值通常是正确的，除非另有说明，否则无需更改。
     OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
     
     ## 设置要通过 OpenRouter 用于某些 AI 任务的特定 Gemini 模型。
     ## ':free' 表示如果你的密钥支持并且可用，则可能使用免费层模型。
     GEMINI_MODEL=google/gemini-2.0-flash-thinking-exp:free
     

   • 至关重要的是，将 "Your OPENROUTER_API_KEY here" 替换为你的实际 OpenRouter API 密钥。 如果你的密钥不需要引号，请删除引号。

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

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

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

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

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

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

5. 保存 .env 文件。

步骤 5：与你的 AI 助手集成（MCP 设置）

此关键步骤通过将 Vibe Coder 的配置添加到客户端的 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": {
     ## 指定用于执行服务器的命令。 如果 Node.js 在你的系统 PATH 中，则应为“node”。
     "command": "node",
     ## 提供“command”的参数。 主要参数是已编译服务器入口点 (`build/index.js`) 的绝对路径。
     ## !! 重要提示：将下面的占位符路径替换为你系统上的实际绝对路径。 即使在 Windows 上也使用正斜杠 (/)。 !!
     "args": ["/path/to/your/vibe-coder-mcp/build/index.js"],
     ## 设置服务器进程运行时的工作目录。 应该是 vibe-coder-mcp 项目目录的根目录的绝对路径。
     ## !! 重要提示：将下面的占位符路径替换为你系统上的实际绝对路径。 即使在 Windows 上也使用正斜杠 (/)。 !!
     "cwd": "/path/to/your/vibe-coder-mcp",
     ## 定义客户端和服务器之间的通信传输协议。 “stdio”（标准输入/输出）对于本地服务器是典型的。
     "transport": "stdio",
     ## 一个对象，包含在 Vibe Coder 服务器进程启动时专门传递给它的环境变量。
     ## API 密钥应位于 .env 文件中，而不是此处。
     "env": {
       ## Vibe Coder 使用的 LLM 配置文件的绝对路径。 此文件定义模型首选项。
       ## !! 重要提示：将下面的占位符路径替换为你系统上的实际绝对路径。 即使在 Windows 上也使用正斜杠 (/)。 !!
       "LLM_CONFIG_PATH": "/path/to/your/vibe-coder-mcp/llm_config.json",
       ## 设置服务器的日志记录级别。 选项通常包括“debug”、“info”、“warn”、“error”。 “debug”提供最详细的日志。
       "LOG_LEVEL": "debug",
       ## 指定运行时环境。 建议将“production”用于稳定使用，“development”可能会启用更详细的日志记录或其他行为。
       "NODE_ENV": "production",
       ## Vibe Coder 工具将保存其输出文件（例如，生成的文档、代码）的目录的绝对路径。 确保此目录存在，或者服务器有权创建它。
       ## 这也可以在 .env 文件中设置（如果两者都设置，则优先）。
       ## !! 重要提示：将下面的占位符路径替换为你系统上的实际绝对路径。 即使在 Windows 上也使用正斜杠 (/)。 !!
       "VIBE_CODER_OUTPUT_DIR": "/path/to/your/VibeCoderOutput"
     },
     ## 一个布尔标志，用于启用 (false) 或禁用 (true) 此服务器配置，而无需删除它。 设置为“false”以使用服务器。
     "disabled": false,
     ## 此服务器提供的工具名称列表，MCP 客户端允许自动执行这些工具，而无需为每次使用都要求显式用户批准。 根据你的信任和工作流程首选项添加或删除工具名称。
     "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", // 注意：如果工具名称确实是“git-summary”，则从“git-summary”更正
       "run-workflow"
     ]
   }
   

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. 检查是否响应正确：

   • 如果工作正常，你应该收到研究响应。
   • 如果没有，请检查下面的“故障排除”部分。

项目架构

Vibe Coder MCP 服务器遵循围绕工具注册表模式的模块化架构：

flowchart TD
    subgraph Initialization
        Init[index.ts] --> Config[加载配置]
        Config --> Server[创建 MCP 服务器]
        Server --> ToolReg[注册工具]
        ToolReg --> InitEmbed[初始化嵌入]
        InitEmbed --> Ready[服务器准备就绪]
    end

    subgraph Request_Flow
        Req[客户端请求] --> ReqProc[请求处理器]
        ReqProc --> Route[路由系统]
        Route --> Execute[工具执行]
        Execute --> Response[响应客户端]
    end

    subgraph Routing_System ["路由系统 (混合匹配器)"]
        Route --> Semantic[语义匹配器]
        Semantic --> |高置信度| Registry[工具注册表]
        Semantic --> |低置信度| SeqThink[顺序思考]
        SeqThink --> Registry
    end

    subgraph Tool_Execution
        Registry --> |获取定义| Definition[工具定义]
        Definition --> |验证输入| ZodSchema[Zod 验证]
        ZodSchema --> |执行| Executor[工具执行器]
        Executor --> |可能使用| Helper[实用程序助手]
        Helper --> |研究| Research[研究助手]
        Helper --> |文件操作| File[文件 I/O]
        Helper --> |嵌入| Embed[嵌入助手]
        Helper --> |Git| Git[Git 助手]
        Executor --> ReturnResult[返回结果]
    end

    subgraph Error_Handling
        ReturnResult --> |成功| Success[成功响应]
        ReturnResult --> |错误| ErrorHandler[错误处理程序]
        ErrorHandler --> CustomErr[自定义错误类型]
        CustomErr --> FormattedErr[格式化错误响应]
    end

    Execute --> |会话状态| State[会话状态]
    State --> |在调用之间持久化| ReqProc

目录结构

vibe-coder-mcp/
├── .env                  # 环境变量配置
├── mcp-config.json       # MCP 配置示例
├── package.json          # 项目依赖项
├── README.md             # 此文档
├── setup.bat             # Windows 设置脚本
├── setup.sh              # macOS/Linux 设置脚本
├── tsconfig.json         # TypeScript 配置
├── vitest.config.ts      # Vitest (测试) 配置
├── workflows.json        # 工作流定义
├── build/                # 已编译的 JavaScript (构建后)
├── docs/                 # 其他文档
├── VibeCoderOutput/      # 工具输出目录
│   ├── research-manager/
│   ├── rules-generator/
│   ├── prd-generator/
│   ├── user-stories-generator/
│   ├── task-list-generator/
│   ├── fullstack-starter-kit-generator/
│   └── workflow-runner/
└── src/                  # 源代码
    ├── index.ts          # 入口点
    ├── logger.ts         # 日志记录配置 (Pino)
    ├── server.ts         # MCP 服务器设置
    ├── services/         # 核心服务
    │   ├── hybrid-matcher/    # 请求路由编排
    │   ├── request-processor/ # 处理传入请求
    │   ├── routing/           # 语义路由 & 注册表
    │   │   ├── embeddingStore.ts    # 工具嵌入存储
    │   │   ├── semanticMatcher.ts   # 语义匹配
    │   │   └── toolRegistry.ts      # 工具注册/执行
    │   ├── state/               # 会话状态管理
    │   │   └── sessionState.ts  # 内存中状态存储
    │   └── workflows/           # 工作流执行
    │       └── workflowExecutor.ts  # 工作流引擎
    ├── testUtils/        # 测试实用程序
    │   └── mockLLM.ts    # 用于测试的模拟 LLM
    ├── tools/            # 工具实现
    │   ├── index.ts      # 工具注册
    │   ├── sequential-thinking.ts  # 回退路由
    │   ├── code-refactor-generator/  # 代码重构
    │   ├── code-stub-generator/      # 代码存根创建
    │   ├── dependency-analyzer/      # 依赖分析
    │   ├── fullstack-starter-kit-generator/  # 项目生成
    │   ├── git-summary-generator/    # Git 集成
    │   ├── prd-generator/            # PRD 创建
    │   ├── research-manager/         # 研究工具
    │   ├── rules-generator/          # 规则创建
    │   ├── task-list-generator/      # 任务列表
    │   ├── user-stories-generator/   # 用户故事
    │   └── workflow-runner/          # 工作流执行
    ├── types/            # TypeScript 定义
    │   ├── globals.d.ts
    │   ├── sequentialThought.ts
    │   ├── tools.ts
    │   └── workflow.ts
    └── utils/            # 共享实用程序
        ├── embeddingHelper.ts  # 嵌入生成
        ├── errors.ts           # 自定义错误类
        ├── fileReader.ts       # 文件 I/O
        ├── gitHelper.ts        # Git 操作
        └── researchHelper.ts   # 研究功能

语义路由系统

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

flowchart TD
    Start[客户端请求] --> Process[处理请求]
    Process --> Hybrid[混合匹配器]
    
    subgraph "主要：语义路由"
        Hybrid --> Semantic[语义匹配器]
        Semantic --> Embeddings[查询嵌入]
        Embeddings --> Tools[工具嵌入]
        Tools --> Compare[通过余弦相似度比较]
        Compare --> Score[评分 & 排名工具]
        Score --> Confidence{高置信度？}
    end
    
    Confidence -->|是| Registry[工具注册表]
    
    subgraph "回退：顺序思考"
        Confidence -->|否| Sequential[顺序思考]
        Sequential --> LLM[LLM 分析]
        LLM --> ThoughtChain[思维链]
        ThoughtChain --> Extraction[提取工具名称]
        Extraction --> Registry
    end
    
    Registry --> Executor[执行工具]
    Executor --> Response[返回响应]

工具注册表模式

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

flowchart TD
    subgraph "工具注册 (在导入时)"
        Import[导入工具] --> Register[调用 registerTool]
        Register --> Store[存储在注册表映射中]
    end
    
    subgraph "工具定义"
        Def[ToolDefinition] --> Name[工具名称]
        Def --> Desc[描述]
        Def --> Schema[Zod 架构]
        Def --> Exec[执行器函数]
    end
    
    subgraph "服务器初始化"
        Init[server.ts] --> Import
        Init --> GetAll[getAllTools]
        GetAll --> Loop[循环遍历工具]
        Loop --> McpReg[向 MCP 服务器注册]
    end
    
    subgraph "工具执行"
        McpReg --> ExecTool[executeTool 函数]
        ExecTool --> GetTool[从注册表获取工具]
        GetTool --> Validate[验证输入]
        Validate -->|有效| ExecFunc[运行执行器函数]
        Validate -->|无效| ValidErr[返回验证错误]
        ExecFunc -->|成功| SuccessResp[返回成功响应]
        ExecFunc -->|错误| HandleErr[捕获 & 格式化错误]
        HandleErr --> ErrResp[返回错误响应]
    end

顺序思考过程

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

flowchart TD
    Start[开始] --> Estimate[估计步骤数]
    Estimate --> Init[使用系统提示初始化]
    Init --> First[生成第一个想法]
    First --> Context[添加到上下文]
    Context --> Loop{需要更多想法？}
    
    Loop -->|是| Next[生成下一个想法]
    Next -->|标准| AddStd[添加到上下文]
    Next -->|修订| Rev[标记为修订]
    Next -->|新分支| Branch[标记为分支]
    Rev --> AddRev[添加到上下文]
    Branch --> AddBranch[添加到上下文]
    AddStd --> Loop
    AddRev --> Loop
    AddBranch --> Loop
    
    Loop -->|否| Extract[提取最终解决方案]
    Extract --> End[以工具选择结束]
    
    subgraph "错误处理"
        Next -->|错误| Retry[使用简化的请求重试]
        Retry -->|成功| AddRetry[添加到上下文]
        Retry -->|失败| FallbackEx[提取部分解决方案]
        AddRetry --> Loop
        FallbackEx --> End
    end

会话状态管理

flowchart TD
    Start[客户端请求] --> SessionID[提取会话 ID]
    SessionID --> Store{状态存在？}
    
    Store -->|是| Retrieve[检索以前的状态]
    Store -->|否| Create[创建新状态]
    
    Retrieve --> Context[将上下文添加到工具]
    Create --> NoContext[在没有上下文的情况下执行]
    
    Context --> Execute[执行工具]
    NoContext --> Execute
    
    Execute --> SaveState[更新会话状态]
    SaveState --> Response[将响应返回给客户端]
    
    subgraph "会话状态结构"
        State[SessionState] --> PrevCall[以前的工具调用]
        State --> PrevResp[以前的响应]
        State --> Timestamp[时间戳]
    end

工作流执行引擎

工作流系统启用多步骤序列：

flowchart TD
    Start[客户端请求] --> Parse[解析工作流请求]
    Parse --> FindFlow[在 workflows.json 中查找工作流]
    FindFlow --> Steps[提取步骤]
    
    Steps --> Loop[处理每个步骤]
    Loop --> PrepInput[准备步骤输入]
    PrepInput --> ExecuteTool[通过注册表执行工具]
    ExecuteTool --> SaveOutput[保存步骤输出]
    SaveOutput --> NextStep{更多步骤？}
    
    NextStep -->|是| MapOutput[将输出映射到下一个输入]
    MapOutput --> Loop
    
    NextStep -->|否| FinalOutput[准备最终输出]
    FinalOutput --> End[返回工作流结果]
    
    subgraph "输入/输出映射"
        MapOutput --> Direct[直接值]
        MapOutput --> Extract[从以前的提取]
        MapOutput --> Transform[转换值]
    end

工作流配置

工作流在项目根目录中的 workflows.json 文件中定义。 此文件包含可以使用单个命令执行的预定义工具调用序列。

文件位置和结构

• workflows.json 文件必须放置在项目根目录中（与 package.json 位于同一级别）
• 该文件遵循以下结构：

  {
    "workflows": {
      "workflowName1": {
        "description": "此工作流的作用的描述",
        "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": "工作流完成消息",
          "details": ["输出行 1", "输出行 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/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)：获取现有代码片段和重构指令（例如，“转换为 async/await”、“提高可读性”、“添加错误处理”），并返回修改后的代码。

分析 & 信息工具

• 依赖分析器 (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 环境变量来覆盖此位置。

示例结构（默认位置）：

VibeCoderOutput/
  ├── research-manager/         # 研究报告
  │   └── TIMESTAMP-QUERY-research.md
  ├── rules-generator/          # 开发规则
  │   └── TIMESTAMP-PROJECT-rules.md
  ├── prd-generator/            # PRD
  │   └── TIMESTAMP-PROJECT-prd.md
  ├── user-stories-generator/   # 用户故事
  │   └── TIMESTAMP-PROJECT-user-stories.md
  ├── task-list-generator/      # 任务列表
  │   └── TIMESTAMP-PROJECT-task-list.md
  ├── fullstack-starter-kit-generator/  # 项目模板
  │   └── TIMESTAMP-PROJECT/
  └── workflow-runner/          # 工作流输出
      └── 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
• 全栈入门套件： 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, 漂亮日志)：

  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. 找不到 Build 目录：

   • 运行 npm run build 以确保 build 目录存在
   • 检查 build 输出是否转到其他目录（检查 tsconfig.json）

2. 文件权限错误：

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

日志调试

1. 对于本地运行：

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

2. 对于 AI 助手运行：

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

工具特定问题