Task Manager MCP Server

Task Manager MCP Server

这是一个 MCP 服务，专为集成 Cursor 等 AI 代码编辑器而构建。主要目标是在绕过 Cursor 极为有限的上下文窗口的同时，最大限度地发挥 Cursor 的 Agent 能力和 Gemini 2.5 出色的架构设计能力。这主要受到了 Roo Code 的 Boomerang 模式启发，但我发现它非常昂贵，因为唯一能与其 apply bot 配合使用的模型是 Claude 3.7 Sonnet。使用此服务，你可以两全其美：只需订阅 Cursor 的 20 美元/月套餐，即可获得无限上下文窗口和无限使用量。

此外，它还包含一个 Svelte UI，可用于查看任务列表和进度、手动调整计划以及审查更改。

Svelte UI

核心功能

• 复杂功能规划： 提供功能描述后，它会通过 repomix 获取项目上下文，并使用大模型生成分步编码计划，供 AI Agent 执行；对于高工作量任务，还会递归拆解任务。
• 集成 UI 服务： 运行 Express 服务以提供静态前端文件，并为 UI 提供基本 API 端点。规划完成或需要澄清时，会在默认浏览器中打开 UI，并显示任务列表和进度。
• 无限上下文窗口： 使用 Gemini 2.5 的 100 万 token 上下文窗口，并在需要时通过 repomix 截断内容。
• 对话历史： 将每项功能的对话历史记录在 .mcp/features/ 中各自独立的 JSON 文件里，以便用户要求调整计划时，Gemini 2.5 能获取上下文。
• 澄清工作流： 在大模型需要更多信息时暂停规划，并通过 WebSockets 与已连接的 UI 交互。
• 任务 CRUD： 支持通过 UI 创建、读取、更新和删除任务。
• 代码审查： 使用大模型分析 git diff HEAD 输出，并在需要时创建新任务。
• 自动审查（可选）： 如果已配置（AUTO_REVIEW_ON_COMPLETION=true），则在某项功能的最后一个原始任务完成后自动运行代码审查流程。
• 计划调整： 允许在计划创建后通过 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-flash-preview:thinking
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

# === Auto Review ===
# If true, the agent will automatically run the 'review_changes' tool after the last task is completed.
# Defaults to false.
AUTO_REVIEW_ON_COMPLETION=false

避免成本

重要： 强烈建议将你自己的 Google AI API 密钥接入 OpenRouter，以避免触及免费模型的速率限制。请参阅下文。

使用 OpenRouter 的免费套餐： 使用 OpenRouter 上标记为“免费”的模型（例如，在本文撰写时的 google/gemini-2.5-flash-preview:thinking），同时连接你自己的 Google AI API 密钥，可以大幅降低或免除成本。更多信息请参阅此 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 中使用（任务管理器模式）

这是此服务预期的主要使用方式。我还没有在其他 AI 代码编辑器中测试过。如果你尝试了，请告诉我效果如何，我会更新 README。

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-flash-preview:thinking",
        //   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. 前往 Cursor Settings -> Features -> Chat -> Enable Custom modes。
2. 返回聊天视图，点击模式选择器（左下角），然后点击 Add custom mode。
3. 为其命名（例如，“MCP Planner”或“Task Dev”），并选择图标或快捷键。
4. 启用工具：确保此服务提供的工具（plan_feature、mark_task_complete、get_next_task、review_changes、adjust_plan）可供此模式使用，并已启用。你也可以根据工作流启用 Codebase、Terminal 等其他工具。
5. 推荐的 Agent 指令：将以下规则原样粘贴到“Custom Instructions”文本框中：

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. The review_changes tool will generate new tasks for you to follow, just like plan_feature. After a review, follow the same one-at-a-time task completion workflow: complete each review-generated task, mark it complete, and call get_next_task until all are done.

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.

6. 保存自定义模式。

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

1. 在 Cursor 中选择新的自定义模式。
2. 向 Cursor 提出功能需求（例如，“使用 JWT 添加身份验证”）。
3. Cursor 将按照说明调用 plan_feature 工具。
4. 服务会规划并保存数据，然后向 Cursor 返回 JSON 响应（位于文本内容中）。
   • 如果成功：响应包含 status: "completed"，且 message 字段中包含第一个任务的描述。如果 UI 正在运行，则会启动或更新 UI。
   • 如果需要澄清：响应包含 status: "awaiting_clarification"、featureId、uiUrl，以及让 Agent 稍后等待并调用 get_next_task 的说明。UI 会启动或更新，并显示问题。
5. 如果有任务描述，Cursor 仅实现该任务。
6. 如果需要澄清，用户会在 UI 中回答，服务恢复规划，并通过 WebSocket 更新 UI。然后，Agent 按照说明使用 featureId 调用 get_next_task。
7. 如果任务已完成，Cursor 会调用 mark_task_complete（传入 taskId 和 featureId）。
8. 服务会将任务标记为已完成，并在响应消息中返回下一个待处理任务。
9. Cursor 重复步骤 4-8。
10. 如果用户要求 Cursor“审查”，它会调用 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）。