Taskqueue

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

此命令会显示可用的命令和选项。

高级配置

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

• 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 工具

TaskManager 现在采用直接工具接口，为每项操作提供专用工具：

项目管理工具

• 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

任务批准

默认情况下，AI Agent 将任务和项目标记为“完成”时，系统会自动批准。若要要求人工手动批准任务，请在创建项目时将 autoApprove 设为 false。

任务只能由人类用户通过 CLI 批准：

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

选项：

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

注意：任务必须先由 AI Agent 标记为“完成”并填写完成详情，之后才能批准（使用 --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            # Format: "proj-{number}"
    ├── initialPrompt: string        # Original user request text
    ├── projectPlan: string          # Additional project details
    ├── completed: boolean           # Project completion status
    ├── autoApprove: boolean         # Set `false` to require manual user approval
    └── tasks: Task[]                # Array of tasks
        ├── id: string               # Format: "task-{number}"
        ├── title: string            # Short task title
        ├── description: string      # Detailed task description
        ├── status: string           # Task status: "not started", "in progress", or "done"
        ├── approved: boolean        # Task approval status
        ├── completedDetails: string # Completion information (required when status is "done")
        ├── toolRecommendations: string # Suggested tools that might be helpful for this task
        └── ruleRecommendations: string # Suggested rules/guidelines to follow for this task

许可证

MIT