任务管理 MCP 服务器

这是一个为与 Cursor 等 AI 代码编辑器集成而构建的 MCP 服务器。主要目标是最大化 Cursor 的代理能力以及 Gemini 2.5 出色的架构能力，同时解决 Cursor 极其有限的上下文窗口问题。这在很大程度上受到了 Roo Code 的 Boomerang 模式的启发，但我发现它非常昂贵，因为唯一能与其应用机器人配合使用的模型是 Claude 3.7 Sonnet。通过这个服务器，你可以以 Cursor 每月 20 美元订阅的价格获得两全其美的效果：无限的上下文窗口和无限的使用量。

此外，它还包括一个 Svelte UI，允许你查看任务列表和进度、手动调整计划并审查更改。

Svelte UI

核心功能

• 复杂功能规划： 提供功能描述，它将通过 repomix 使用具有项目上下文的 LLM 生成详细的编码计划，供 AI 代理遵循，并对高工作量的任务进行递归任务分解。
• 集成的 UI 服务器： 运行一个 Express 服务器来提供静态前端文件，并为 UI 提供基本的 API 端点。在规划完成后或需要澄清时，在默认浏览器中打开 UI 并显示任务列表和进度。
• 无限上下文窗口： 在需要时使用 Gemini 2.5 的 100 万 token 上下文窗口和 repomix 的截断功能。
• 对话历史记录： 为每个功能在 .mcp/features/ 目录下的单独 JSON 文件中跟踪对话历史记录，以便当用户要求调整计划时，Gemini 2.5 能够拥有上下文。
• 澄清工作流程： 处理 LLM 需要更多信息的情况，暂停规划并通过 WebSockets 与连接的 UI 交互。
• 任务 CRUD： 允许通过 UI 创建、读取、更新和删除任务。
• 代码审查： 使用 LLM 分析 git diff HEAD 输出，并根据需要创建新任务。
• 计划调整： 允许通过 adjust_plan 工具在创建计划后进行调整。

设置

前提条件：

• Node.js
• npm
• Git

安装与构建：

1. 克隆：

   git clone https://github.com/jhawkins11/task-manager-mcp.git
   cd task-manager-mcp
   

2. 安装后端依赖：

   npm install
   

3. 配置： 你将在 Cursor 的 MCP 设置中直接配置 API 密钥（请参阅使用部分），但为了手动测试，你可能仍希望有一个本地的 .env 文件（请参阅配置部分）。

4. 构建： 此命令会构建后端和前端服务器，并将 Svelte UI 复制到 dist/frontend-ui/ 目录中。

   npm run build
   

运行服务器（手动）：

对于不使用 Cursor 的本地测试，你可以直接使用 Node 或 npm 脚本来运行服务器。此方法将使用 .env 文件进行配置。

直接使用 Node（使用绝对路径）：

node /full/path/to/your/task-manager-mcp/dist/server.js

使用 npm start：

npm start

这将启动MCP服务器（stdio）、WebSocket服务器以及用于UI的HTTP服务器。UI应该可以通过http://localhost:<UI_PORT>（默认为3000）访问。

配置（手动运行时的.env文件）：

如果手动运行（不是通过Cursor），请在项目根目录下创建一个.env文件以存放API密钥和端口。注意：当通过Cursor运行时，这些配置应设置在Cursor的mcp.json配置中（参见使用部分）。

# .env - USED ONLY FOR MANUAL `npm start` or `node dist/server.js`
# === OpenRouter (Recommended) ===

# Get key: https://openrouter.ai/keys
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENROUTER_MODEL=google/gemini-2.5-pro-exp-03-25:free
FALLBACK_OPENROUTER_MODEL=google/gemini-2.5-flash-preview:thinking

# === Google AI API (Alternative) ===
# GEMINI_API_KEY=your_google_ai_api_key
# GEMINI_MODEL=gemini-1.5-flash-latest
# FALLBACK_GEMINI_MODEL=gemini-1.5-flash-latest

# === UI / WebSocket Ports ===
# Default is 4999 if not set.
UI_PORT=4999
WS_PORT=4999

避免成本

**重要：**强烈建议您将自己的Google AI API密钥集成到OpenRouter，以避免免费模型的速率限制。详情如下。

使用OpenRouter的免费层级： 通过连接您自己的Google AI API密钥，并使用OpenRouter上标记为“免费”的模型（例如，在撰写本文时google/gemini-2.5-pro-exp-03-25:free），您可以显著减少或完全消除费用。更多信息请参考此Reddit帖子：https://www.reddit.com/r/ChatGPTCoding/comments/1jrp1tj/a_simple_guide_to_setting_up_gemini_25_pro_free/

回退成本： 如果主模型达到速率限制，服务器会自动尝试使用回退模型重试。默认的回退模型（FALLBACK_OPENROUTER_MODEL）通常是速度更快、更便宜的模型，如Gemini Flash，但根据OpenRouter当前的价格/层级可能仍然会产生相关费用。请检查他们的网站，并根据需要调整您的配置中的回退模型。

与Cursor一起使用（任务管理器模式）

这是该服务器预期的主要使用方式。

1. 在Cursor中配置MCP服务器：

构建服务器后（npm run build），你需要告诉Cursor如何运行它。

找到Cursor的MCP配置文件。它可以是：

• 项目特定： 在你的项目根目录内创建/编辑.cursor/mcp.json文件。
• 全局： 在用户主目录下的~/.cursor/mcp.json创建/编辑文件（适用于所有项目）。

向该JSON文件内的mcpServers对象添加以下条目：

{
  "mcpServers": {
    "task-manager-mcp": {
      "command": "node",
      "args": ["/full/path/to/your/task-manager-mcp/dist/server.js"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxxxxxx"
        //   optional: my recommended model for MCP is Gemini 2.5 Pro Free which is already set by default
        //   "OPENROUTER_MODEL": "google/gemini-2.5-pro-exp-03-25:free",
        //   also optional
        //   "FALLBACK_OPENROUTER_MODEL": "google/gemini-2.5-flash-preview:thinking",
        //   optional: the default port for the UI is 4999 if not set
        //   "UI_PORT": "4999",
        //   optional: the default port for the WebSocket server is 4999 if not set
        //   "WS_PORT": "4999"
        // Add GEMINI_API_KEY here instead if using Google directly
        // Add any other necessary env vars here
      }
    }
    // Add other MCP servers here if you have them
  }
}

重要：

• 将/full/path/to/your/task-manager-mcp/dist/server.js替换为你机器上编译后的服务器脚本的绝对路径。
• 将sk-or-v1-xxxxxxxxxxxxxxxxxxxx替换为您的实际OpenRouter API密钥（或者如果您直接使用Google AI，则设置GEMINI_API_KEY）。
• 这里定义的环境变量将在Cursor启动服务器进程时传递给它，覆盖任何.env文件。

2. 创建自定义Cursor模式：

1. 转到光标设置 -> 功能 -> 聊天 -> 启用自定义模式。
2. 返回聊天视图，点击模式选择器（左下角），然后点击添加自定义模式。
3. 为它命名（例如，“MCP Planner”，“Task Dev”），选择一个图标/快捷方式。
4. 启用工具：确保此服务器提供的工具（plan_feature、mark_task_complete、get_next_task、review_changes、adjust_plan）对此模式可用并已启用。根据您的工作流程，您可能还需要启用其他工具，如代码库、终端等。
5. 推荐的代理指令：将以下规则准确粘贴到“自定义指令”文本框中：

Always use plan_feature mcp tool when getting feature request before doing anything else. ALWAYS!!!!!!!! It will return the first step of the implementation. DO NOT IMPLEMENT MORE THAN WHAT THE TASK STATES. After you're done run mark_task_complete which will give you the next task. If the user says "review" use the review_changes tool.

If clarification is required at any step, you will not receive the next task and will have to run get_next_task manually after the user answers the clarification question through the UI.

IMPORTANT: Your job is to complete the tasks one at a time. DO NOT DO ANY OTHER CHANGES, ONLY WHAT THE CURRENT TASK SAYS TO DO.

1. 保存自定义模式。

预期工作流（使用自定义模式）：

1. 在光标中选择您的新自定义模式。
2. 给光标一个功能请求（例如，“使用 JWT 添加认证”）。
3. 光标按照指示调用 plan_feature 工具。
4. 服务器进行规划，保存数据，并返回 JSON 响应（在文本内容内）给光标。
   • 如果成功：响应包括 status: "completed" 和第一个任务的描述在 message 字段中。如果 UI 正在运行，则启动/更新 UI。
   • 如果需要澄清：响应包括 status: "awaiting_clarification"、featureId、uiUrl 以及代理等待并在稍后调用 get_next_task 的说明。UI 会以问题的形式启动/更新。
5. 光标仅实现所描述的任务（如果提供的话）。
6. 如果需要澄清，用户在 UI 中回答，服务器继续规划并通过 WebSocket 更新 UI。然后代理根据指示调用带有 featureId 的 get_next_task。
7. 如果任务完成，光标调用 mark_task_complete（带 taskId 和 featureId）。
8. 服务器标记任务已完成，并在响应消息中返回下一个待处理任务。
9. 光标重复步骤 4-8。
10. 如果用户要求光标“审查”，则它调用 review_changes。

API 端点（用于 UI）

集成的 Express 服务器为前端提供了这些基本端点：

• GET /api/features: 返回现有功能 ID 列表。
• GET /api/tasks/:featureId: 返回特定功能的任务列表。
• GET /api/tasks: 返回最近创建/修改的功能的任务。
• GET /api/features/:featureId/pending-question: 检查该功能是否有活跃的澄清问题。
• POST /api/tasks: 为某个功能创建新任务。
• PUT /api/tasks/:taskId: 更新现有任务。
• DELETE /api/tasks/:taskId: 删除任务。
• (静态文件): 从 dist/frontend-ui/ 提供文件（例如，index.html）。