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工具检索最终结果。
会话状态管理：维护会话内各个请求的基本状态（在内存中）。
标准化错误处理：所有工具的错误模式一致。

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

Related MCP server: code2prompt-mcp

设置指南

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

步骤 1：先决条件

检查 Node.js 版本：
- 打开终端或命令提示符。
- 运行node -v
- 确保输出显示 v18.0.0 或更高版本（必需）。
- 如果未安装或已过时：从nodejs.org下载。
检查 Git 安装：
- 打开终端或命令提示符。
- 运行git --version
- 如果未安装：从git-scm.com下载。
获取 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
  （或者如果适用，使用你的 fork 的 URL）
导航到项目目录：
- 跑步：
  cd vibe-coder-mcp

步骤 3：运行安装脚本

为您的操作系统选择适当的脚本：

对于 Windows：

在您的终端中（仍在 vibe-coder-mcp 目录中），运行：
```
setup.bat
```
等待脚本完成（它将安装依赖项、构建项目并创建必要的目录）。
如果您看到任何错误消息，请参阅下面的故障排除部分。

对于 macOS 或 Linux：

使脚本可执行：
```
chmod +x setup.sh
```
运行脚本：
```
./setup.sh
```
等待脚本完成。
如果您看到任何错误消息，请参阅下面的故障排除部分。

该脚本执行以下操作：

检查 Node.js 版本 (v18+)
通过 npm 安装所有依赖项
创建必要的VibeCoderOutput/子目录（如脚本中所定义）。
构建 TypeScript 项目。
**如果.env不存在，则将.env.example复制到.env文件。**您需要编辑此文件。
设置可执行权限（在 Unix 系统上）。

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

安装脚本（来自步骤 3）通过复制.env.example模板自动在项目的根目录中创建.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 ）。
保存

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

此关键步骤通过将 Vibe Coder 的配置添加到客户端的 MCP 设置文件来将其连接到您的 AI 助手。

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

位置取决于你的人工智能助手：

光标 AI / Windsurf / RooCode（基于 VS Code）：
1. 打开应用程序。
2. 打开命令面板（ Ctrl+Shift+P或Cmd+Shift+P ）。
3. 键入并选择Preferences: Open User Settings (JSON) 。
4. 这将打开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，请将路径中的
克劳德桌面：
- 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助手：
- 完全重启你的AI助手应用程序。
测试一个简单的命令：
- 输入测试命令，例如： Research modern JavaScript frameworks
检查是否正确响应：
- 如果工作正常，您应该会收到研究回复。
- 如果没有，请检查下面的故障排除部分。

项目架构

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
    │   ├── 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]

工具注册表模式

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

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 文件中的详尽文档。这些文件涵盖：

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

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

src/tools/fullstack-starter-kit-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
src/tools/code-map-generator/README.md

工具类别

分析与信息工具

代码图生成器（ ：扫描代码库以提取语义信息（类、函数、注释），并生成带有美人鱼图表的人类可读的 Markdown 地图或带有用于导入和增强类属性信息的绝对文件路径的结构化 JSON 表示。
研究经理 ( ：使用 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）：
```
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 服务器

检查配置路径：
- 验证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"
- 检查助手是否有日志控制台或输出窗口

特定于工具的问题

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