MCP 任务管理器

MCP 任务管理器 (npm 包: taskqueue-mcp) 是一个用于 AI 任务管理的模型上下文协议 (MCP) 服务器。此工具帮助 AI 助手以结构化的方式处理多步骤任务，并提供可选的用户审批检查点。

功能

• 多步骤任务规划
• 进度跟踪
• 用户审批已完成的任务
• 项目完成审批
• 任务详情可视化
• 任务状态管理
• 增强的 CLI，用于任务检查和管理

基本设置

通常，您将在 Claude Desktop、Cursor 或其他 MCP 客户端中设置工具配置，如下所示：

{
  "tools": {
    "taskqueue": {
      "command": "npx",
      "args": ["-y", "taskqueue-mcp"]
    }
  }
}

要使用 CLI 实用程序，您可以使用以下命令：

npx taskqueue --help

这将显示可用的命令和选项。

高级配置

任务管理器支持多个 LLM 提供商来生成项目计划。您可以根据要使用的提供商配置以下一个或多个环境变量：

• OPENAI_API_KEY: 使用 OpenAI 模型（例如 GPT-4）所必需
• GOOGLE_GENERATIVE_AI_API_KEY: 使用 Google 的 Gemini 模型所必需
• DEEPSEEK_API_KEY: 使用 Deepseek 模型所必需

要使用 CLI 生成项目计划，请在您的 shell 中设置这些环境变量：

export OPENAI_API_KEY="your-api-key"
export GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"
export DEEPSEEK_API_KEY="your-api-key"

或者，您可以将它们包含在您的 MCP 客户端配置中，以使用 MCP 工具调用生成项目计划：

{
  "tools": {
    "taskqueue": {
      "command": "npx",
      "args": ["-y", "taskqueue-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "GOOGLE_GENERATIVE_AI_API_KEY": "your-api-key",
        "DEEPSEEK_API_KEY": "your-api-key"
      }
    }
  }
}

可用的 MCP 工具

任务管理器现在使用直接工具接口，为每个操作提供特定的、专门构建的工具：

项目管理工具

• list_projects: 列出系统中的所有项目
• read_project: 获取有关特定项目的详细信息
• create_project: 创建一个包含初始任务的新项目
• delete_project: 删除一个项目
• add_tasks_to_project: 将新任务添加到现有项目
• finalize_project: 在所有任务完成后完成项目

任务管理工具

• list_tasks: 列出特定项目的所有任务
• read_task: 获取特定任务的详细信息
• create_task: 在项目中创建一个新任务
• update_task: 修改任务的属性（标题、描述、状态）
• delete_task: 从项目中删除一个任务
• approve_task: 批准已完成的任务
• get_next_task: 获取项目中下一个待处理的任务
• mark_task_done: 将任务标记为已完成，并提供详细信息

任务状态和工作流程

任务有一个状态字段，可以是以下之一：

• not started: 任务尚未开始
• in progress: 任务正在进行中
• done: 任务已完成（需要 completedDetails）

状态转换规则

系统强制执行以下任务状态转换规则：

• 任务遵循特定的工作流程，并定义了有效的转换：
  • 从 not started: 只能移动到 in progress
  • 从 in progress: 可以移动到 done 或返回到 not started
  • 从 done: 如果需要额外的工作，可以返回到 in progress
• 当任务被标记为“done”时，必须提供 completedDetails 字段来记录已完成的内容
• 批准的任务无法修改
• 只有当所有任务都已完成并获得批准时，才能批准项目

这些规则有助于维护任务进度的完整性，并确保正确记录已完成的工作。

使用工作流程

LLM 使用此任务管理器的典型工作流程如下：

1. create_project: 启动一个包含初始任务的项目
2. get_next_task: 获取第一个待处理的任务
3. 处理任务
4. mark_task_done: 将任务标记为已完成，并提供详细信息
5. 等待批准（用户必须通过 CLI 调用 approve_task）
6. get_next_task: 获取下一个待处理的任务
7. 重复步骤 3-6，直到所有任务都完成
8. finalize_project: 完成项目（需要用户批准）

CLI 命令

要使用 CLI，您需要全局安装该软件包：

npm install -g taskqueue-mcp

或者，您可以使用 npx 运行 CLI，并使用 --package=taskqueue-mcp 标志来告诉 npx 它来自哪个软件包。

npx --package=taskqueue-mcp taskqueue --help

任务审批

任务审批完全由人类用户通过 CLI 控制：

npx taskqueue approve-task -- <projectId> <taskId>

选项：

• -f, --force: 强制批准，即使任务未标记为已完成

注意：任务必须标记为“done”并提供已完成的详细信息，然后才能获得批准（除非使用 --force）。

列出任务和项目

CLI 提供了一个命令来列出所有项目和任务：

npx taskqueue list-tasks

要查看特定项目的详细信息：

npx taskqueue list-tasks -- -p <projectId>

此命令显示有关系统中所有项目或特定项目的信息，包括：

• 项目 ID 和初始提示
• 完成状态
• 任务详细信息（标题、描述、状态、批准）
• 进度指标（已批准/已完成/总任务数）

数据模式和存储

文件位置

任务管理器将数据存储在一个 JSON 文件中，该文件必须可供服务器和 CLI 访问。

默认的平台特定位置是：

• Linux: ~/.local/share/taskqueue-mcp/tasks.json
• macOS: ~/Library/Application Support/taskqueue-mcp/tasks.json
• Windows: %APPDATA%\taskqueue-mcp\tasks.json

不建议使用自定义文件路径来存储任务数据，因为您必须记住为 MCP 服务器和 CLI 设置相同的路径，否则它们将无法相互协调。但是，如果您确实想使用自定义路径，则可以在 MCP 客户端配置中设置 TASK_MANAGER_FILE_PATH 环境变量：

{
  "tools": {
    "taskqueue": {
      "command": "npx",
      "args": ["-y", "taskqueue-mcp"],
      "env": {
        "TASK_MANAGER_FILE_PATH": "/path/to/tasks.json"
      }
    }
  }
}

然后，在运行 CLI 之前，您应该在 shell 中导出相同的路径：

export TASK_MANAGER_FILE_PATH="/path/to/tasks.json"

数据模式

JSON 文件使用以下结构：

TaskManagerFile
├── projects: Project[]
    ├── projectId: string            # 格式: "proj-{number}"
    ├── initialPrompt: string        # 原始用户请求文本
    ├── projectPlan: string          # 其他项目详情
    ├── completed: boolean           # 项目完成状态
    └── tasks: Task[]                # 任务数组
        ├── id: string               # 格式: "task-{number}"
        ├── title: string            # 简短的任务标题
        ├── description: string      # 详细的任务描述
        ├── status: string           # 任务状态: "not started", "in progress", 或 "done"
        ├── approved: boolean        # 任务批准状态
        ├── completedDetails: string # 完成信息 (当状态为 "done" 时是必需的)
        ├── toolRecommendations: string # 可能对该任务有帮助的建议工具
        └── ruleRecommendations: string # 建议遵循的规则/指南

许可证

MIT