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 Keys 部分。
   • 创建一个新的 API 密钥并复制它。
   • 保留此密钥以备第 4 步使用。

第 2 步：获取代码

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

   • 打开终端或命令提示符。
   • 导航到你想要存储项目的目录：

     cd ~/Documents     # 示例：更改为你的首选位置
     

2. 克隆仓库:

   • 运行：

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

     （如果适用，请使用你的分叉仓库的URL）

3. 导航到项目目录:

   • 运行：

     cd vibe-coder-mcp
     

第三步：运行设置脚本

选择适合你操作系统的脚本：

对于 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 系统上）

第四步：配置环境变量（.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 文件提供了每项任务的更细粒度控制（如有需要）。
   • 检查 LOG_LEVEL（默认：info）- 可选项包括：'fatal', 'error', 'warn', 'info', 'debug', 'trace'。

5. 保存 .env 文件。

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

这一步至关重要，它将 Vibe Coder 与您的 AI 助手连接起来。每个环境都需要稍微不同的配置。

5.1: 查找项目的绝对路径

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

对于 Windows:

1. 在终端中，导航到 build 目录：

   cd build
   

2. 获取绝对路径：

   echo %cd%\index.js
   

3. 复制输出（例如：C:\Users\YourName\Projects\vibe-coder-mcp\build\index.js）

对于 macOS/Linux:

1. 在终端中，导航到 build 目录：

   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 密钥和其他敏感配置现在通过 .env 文件加载
       // 如果你更喜欢在这里设置 VIBE_CODER_OUTPUT_DIR 而不是在 .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. 用你在步骤 5.1 中获得的绝对路径替换 PATH_PLACEHOLDER。

   • 注意：即使在 Windows 上也要使用正斜杠 /（例如，C:/Users/...）。

3. 重要提示： 不要将你的 OPENROUTER_API_KEY 直接放在这个配置块中。它应该只存在于 .env 文件中。

5.3: 配置特定的 AI 助手

A. Cursor AI / Windsurf（基于 VS Code）

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 部分示例：

"mcpServers": {
  "some-existing-server": {
    // existing configuration...
  },
  "vibe-coder-mcp": {
    "command": "node",
    "args": ["C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js"],
    // Rest of your configuration...
  }
}

B. Cline AI（VS Code 扩展）

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 分支)

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

D. Claude Desktop

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 示例：

{
  "theme": "system",
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "node",
      "args": ["/Users/YourName/Projects/vibe-coder-mcp/build/index.js"],
      "env": {
        "NODE_ENV": "production",
        "OPENROUTER_API_KEY": "your-openrouter-api-key",
        // Rest of your configuration...
      },
      "disabled": false,
      "autoApprove": [
        // Your auto-approve tools...
      ]
    }
  }
}

步骤 6: 测试您的配置

1. 启动您的 AI 助手：

   • 完全重启您的 AI 助手应用程序。

2. 测试一个简单命令：

   • 输入一个测试命令，例如：Research modern JavaScript frameworks

3. 检查正确的响应：

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

项目架构

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

flowchart TD
    subgraph Initialization
        Init[index.ts] --> Config[Load Configuration]
        Config --> Server[Create MCP Server]
        Server --> ToolReg[Register Tools]
        ToolReg --> InitEmbed[Initialize Embeddings]
        InitEmbed --> Ready[Server Ready]
    end

    subgraph Request_Flow
        Req[Client Request] --> ReqProc[Request Processor]
        ReqProc --> Route[Routing System]
        Route --> Execute[Tool Execution]
        Execute --> Response[Response to Client]
    end

    subgraph Routing_System ["Routing System (Hybrid Matcher)"]
        Route --> Semantic[Semantic Matcher]
        Semantic --> |High Confidence| Registry[Tool Registry]
        Semantic --> |Low Confidence| SeqThink[Sequential Thinking]
        SeqThink --> Registry
    end

    subgraph Tool_Execution
        Registry --> |Get Definition| Definition[Tool Definition]
        Definition --> |Validate Input| ZodSchema[Zod Validation]
        ZodSchema --> |Execute| Executor[Tool Executor]
        Executor --> |May Use| Helper[Utility Helpers]
        Helper --> |Research| Research[Research Helper]
        Helper --> |File Ops| File[File I/O]
        Helper --> |Embeddings| Embed[Embedding Helper]
        Helper --> |Git| Git[Git Helper]
        Executor --> ReturnResult[Return Result]
    end

    subgraph Error_Handling
        ReturnResult --> |Success| Success[Success Response]
        ReturnResult --> |Error| ErrorHandler[Error Handler]
        ErrorHandler --> CustomErr[Custom Error Types]
        CustomErr --> FormattedErr[Formatted Error Response]
    end

    Execute --> |Session State| State[Session State]
    State --> |Persists Between Calls| ReqProc

目录结构

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
    │   ├── hybrid-matcher/    # Request routing orchestration
    │   ├── request-processor/ # Handles incoming requests
    │   ├── routing/           # Semantic routing & registry
    │   │   ├── embeddingStore.ts    # Tool embedding storage
    │   │   ├── semanticMatcher.ts   # Semantic matching
    │   │   └── toolRegistry.ts      # Tool registration/execution
    │   ├── state/               # Session state management
    │   │   └── sessionState.ts  # In-memory state storage
    │   └── workflows/           # Workflow execution
    │       └── workflowExecutor.ts  # Workflow engine
    ├── testUtils/        # Testing utilities
    │   └── mockLLM.ts    # Mock LLM for tests
    ├── tools/            # Tool implementations
    │   ├── index.ts      # Tool registration
    │   ├── sequential-thinking.ts  # Fallback routing
    │   ├── code-refactor-generator/  # Code refactoring
    │   ├── code-stub-generator/      # Code stub creation
    │   ├── dependency-analyzer/      # Dependency analysis
    │   ├── fullstack-starter-kit-generator/  # Project gen
    │   ├── git-summary-generator/    # Git integration
    │   ├── prd-generator/            # PRD creation
    │   ├── research-manager/         # Research tool
    │   ├── rules-generator/          # Rules creation
    │   ├── task-list-generator/      # Task lists
    │   ├── user-stories-generator/   # User stories
    │   └── workflow-runner/          # Workflow execution
    ├── types/            # TypeScript definitions
    │   ├── globals.d.ts
    │   ├── sequentialThought.ts
    │   ├── tools.ts
    │   └── workflow.ts
    └── utils/            # Shared utilities
        ├── embeddingHelper.ts  # Embedding generation
        ├── errors.ts           # Custom error classes
        ├── fileReader.ts       # File I/O
        ├── gitHelper.ts        # Git operations
        └── researchHelper.ts   # Research functionality

语义路由系统

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": "描述此工作流的功能",
        "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/         # 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/
  └── 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
• 全栈启动工具包: 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. 找不到构建目录:

   • 运行 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. 语义路由不工作:

   • 第一次运行可能会下载嵌入模型 - 检查下载消息
   • 尝试一个更明确的请求，其中提到工具名称

2. **Git 摘要工具