MCP Tasks

🚀 MCP任务管理工具 📋

MCP任务管理工具是一款高效的任务管理工具。它旨在减少工具使用的复杂性，最大程度提高大语言模型（LLM）的预算使用效率。同时，它具备强大的搜索、过滤和组织功能，支持多种文件格式，如Markdown、JSON和YAML。

🚀 快速开始

将以下内容添加到 ~/.cursor/mcp.json（适用于Cursor）或 ~/.config/claude_desktop_config.json（适用于Claude Desktop）中。

选项1：NPX（推荐）

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"]
    }
  }
}

选项2：Docker

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-tasks"
      ]
    }
  }
}

✨ 主要特性

• ⚡ 超高效设计：仅使用5种工具，减少人工智能的混淆。
• 🎯 预算优化：通过批量操作、智能默认设置和自动操作，最大程度减少LLM API调用。
• 🚀 多格式支持：支持Markdown（.md）、JSON（.json）和YAML（.yml）任务文件。
• 🔍 强大搜索：支持不区分大小写的文本/状态过滤（使用OR逻辑），以及基于ID的查找。
• 📊 智能组织：支持基于状态的过滤，工作流状态可自定义。
• 🎯 基于位置的索引：通过基于0的插入方式，轻松对任务进行排序。
• 📁 多源支持：可同时管理多个任务文件。
• 🔄 实时更新：更改会自动保存到所选格式的文件中。
• 🤖 自动进行中任务管理：自动管理进行中任务的数量限制。
• 🚫 重复任务预防：自动防止重复任务的出现。
• 🛡️ 类型安全：完全支持TypeScript，并使用Zod进行验证。
• 🔒 超安全：人工智能无法重写或删除你的任务（除非你启用该功能），只能添加和移动任务。
• 📅 可选提醒：可以启用专门的提醒部分，人工智能可以持续查看和维护该部分。

🔧 安装示例

自定义环境的完整配置

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"],
      "env": {
        "STATUS_WIP": "In Progress",
        "STATUS_TODO": "To Do",
        "STATUS_DONE": "Done",
        "STATUS_REMINDERS": "Reminders",
        "STATUS_NOTES": "Notes",
        "STATUSES": "In Progress,To Do,Done,Backlog,Reminders,Notes",
        "AUTO_WIP": "true",
        "PREFIX_TOOLS": "true",
        "KEEP_DELETED": "true",
        "TRANSPORT": "stdio",
        "PORT": "4680",
        "INSTRUCTIONS": "Use mcp-tasks tools when the user mentions new or updated tasks"
      }
    }
  }
}

HTTP传输以实现远程访问

首先启动服务器：

TRANSPORT=http PORT=4680 npx mcp-tasks

然后：

{
  "mcpServers": {
    "mcp-tasks": {
      "type": "streamableHttp",
      "url": "http://localhost:4680/mcp"
    }
  }
}

📁 支持的文件格式

格式会根据文件扩展名自动检测。所有格式都支持相同的功能，并且可以在同一项目中混合使用。

推荐：使用Markdown（.md）格式，以便于人类阅读和编辑。

⚠️ 重要提示

建议从新文件开始使用，而不是使用现有的任务文件，以避免丢失非任务内容。

🛠️ 可用工具

当 PREFIX_TOOLS=true（默认设置）时，所有工具都会以 tasks_ 为前缀：

ID格式：source_id（来自文件路径）和任务 id（来自任务文本）都是4个字符的字母数字字符串（例如，"xK8p"、"m3Qw"）。

工具使用示例

初始化任务文件

tasks_setup({
  workspace: "/path/to/project",
  source_path: "tasks.md"  // 相对于工作空间或绝对路径
  // source_path: "tasks.json"
  // source_path: "tasks.yml"
})
// 返回: {"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":0,"inProgress":[]}
// 源ID（4个字符的字母数字字符串）将用于所有后续操作

添加任务

tasks_add({
  source_id: "xK8p", // 来自初始化响应
  texts: ["Implement authentication", "Write tests"],
  status: "To Do",
  index: 0  // 添加到顶部（可选）
})
// 返回: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":2,"In Progress":0,"Done":0,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0},{"id":"p9Lx","text":"Write tests","status":"To Do","index":1}]}

搜索和过滤

tasks_search({
  source_id: "xK8p",        // 来自初始化响应
  terms: ["auth", "deploy"],          // 搜索词（文本或状态，使用OR逻辑）
  statuses: ["To Do"],      // 按状态过滤
  ids: ["m3Qw", "p9Lx"]     // 按特定任务ID过滤
})
// 返回: [{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0}]

更新任务状态

tasks_update({
  source_id: "xK8p",        // 来自初始化响应
  ids: ["m3Qw", "p9Lx"],    // 来自添加/搜索响应的任务ID
  status: "Done"            // 使用 "Deleted" 来删除任务
})
// 返回: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":2,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"Done","index":0},{"id":"p9Lx","text":"Write tests","status":"Done","index":1}]}

获取概览信息

tasks_summary({
  source_id: "xK8p"         // 来自初始化响应
})
// 返回: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":1,"Done":2,"inProgress":[{"id":"r7Km","text":"Fix critical bug","status":"In Progress","index":0}]}

🎛️ 环境变量

高级配置示例

可选地，可以包含进行中/待办/已完成状态，以控制它们的顺序。

自定义工作流状态

{
  "env": {
    "STATUSES": "WIP,Pending,Archived,Done,To Review",
    "STATUS_WIP": "WIP",
    "STATUS_TODO": "Pending",
    "AUTO_WIP": "false"
  }
}

📊 文件格式

Markdown（.md） - 人类可读

# 任务 - 文件名

## 进行中
- [ ] 编写用户注册功能

## 待办
- [ ] 实现身份验证
- [ ] 设置CI/CD管道

## 积压
- [ ] 规划架构
- [ ] 设计数据库架构

## 已完成
- [x] 设置项目结构
- [x] 初始化仓库

## 提醒
- [ ] 在确认功能正常工作之前，不要将任务标记为已完成
- [ ] 将任务标记为已完成后，提交所有更改，并使用任务名称作为提交消息

## 备注
- [ ] 任务管理工具使用起来非常棒！

JSON（.json） - 结构化数据

{
  "groups": {
    "In Progress": [
      "Write user registration"
    ],
    "To Do": [
      "Implement authentication",
      "Set up CI/CD pipeline"
    ],
    "Backlog": [
      "Plan architecture",
      "Design database schema"
    ],
    "Done": [
      "Set up project structure",
      "Initialize repository"
    ],
    "Reminders": [
      "Don't move to Done until you verified it works",
      "After you move to Done, commit all the changes, use the task name as the commit message"
    ],
    "Notes": [
      "The task tools were really great to use!"
    ]
  }
}

YAML（.yml） - 适合配置

groups:
  "In Progress":
    - Write user registration
  "To Do":
    - Implement authentication
    - Set up CI/CD pipeline
  Backlog:
    - Plan architecture
    - Design database schema
  Done:
    - Set up project structure
    - Initialize repository
  Reminders:
    - Don't move to Done until you verified it works
    - After you move to Done, commit all the changes, use the task name as the commit message

🖥️ 服务器使用方法

# 显示帮助信息
mcp-tasks --help

# 默认：使用stdio传输
mcp-tasks

# 使用HTTP传输
TRANSPORT=http mcp-tasks
TRANSPORT=http PORT=8080 mcp-tasks

# 自定义配置
STATUS_WIP="Working" AUTO_WIP=false mcp-tasks

💻 CLI使用方法

你也可以将 mcp-tasks（或 npx mcp-tasks）作为命令行工具，进行快速任务管理：

# 初始化任务文件
mcp-tasks setup tasks.md $PWD                      # 带工作空间的初始化
# 添加任务
mcp-tasks add "Implement authentication"           # 默认添加到 "To Do" 状态
mcp-tasks add "Write tests" "Backlog"              # 添加到指定状态
mcp-tasks add "Fix critical bug" "In Progress" 0   # 添加到顶部（索引为0）
# 搜索任务
mcp-tasks search                                    # 搜索所有任务
mcp-tasks search "" "auth,login"                   # 搜索特定关键词
mcp-tasks search "To Do,Done" ""                   # 按状态过滤
mcp-tasks search "In Progress" "bug"               # 按状态和关键词过滤
# 更新任务状态（ID以逗号分隔）
mcp-tasks update m3Qw,p9Lx Done
# 获取概览信息
mcp-tasks summary
# 添加提醒（必须启用提醒功能，设置 REMINDERS=true）
mcp-tasks add "Don't move to Done until you verified it works" Reminders

CLI特性

• 可以直接访问所有MCP工具的功能。
• 以JSON格式输出，便于解析和脚本编写。
• 与MCP工具具有相同的可靠性和重复任务预防功能。
• 非常适合自动化脚本和CI/CD管道。

🧪 开发

# 克隆并设置项目
git clone https://github.com/flesler/mcp-tasks
cd mcp-tasks
npm install
# 开发模式（自动重启）
npm run dev              # 使用STDIO传输
npm run dev:http         # 使用HTTP传输，端口为4680
# 构建和测试
npm run build           # 编译TypeScript代码
npm run lint            # 检查代码风格
npm run lint:full       # 构建 + 检查代码风格

🛠️ 故障排除

要求

• Node.js ≥20 - 此包需要Node.js 20或更高版本。

常见问题

运行 npx-tasks 时出现 ERR_MODULE_NOT_FOUND 错误

• 问题：运行 npx mcp-tasks 时出现类似 Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' 的错误。
• 原因：npx缓存损坏或不完整，导致无法正确解析依赖项。
• 解决方案：清除npx缓存并重新尝试：

npx clear-npx-cache
npx mcp-tasks

• 注意：此问题在Node.js v20和v22上都可能出现，清除缓存可以解决该问题。

我的任务存储在哪里？

• 任务存储在你通过AI在 tasks_setup 中指定的文件路径中。
• 绝对路径会在每个工具调用的响应中以 source.path 的形式返回。
• 如果你忘记了存储位置，可以查看任何工具的响应，或要求AI显示给你。

Markdown文件中的内容丢失

• ⚠️ 工具会重写整个文件，仅保留识别状态部分下的任务。
• 当工具修改文件时，非任务内容（备注、文档）可能会丢失。
• 建议使用专门的任务文件，而不是将任务与其他内容混合。

为什么不让AI直接编辑任务文件？

• 文件解析复杂性：AI需要读取整个文件，解析Markdown结构，并理解当前状态，这既昂贵又容易出错。
• 多步骤操作：将任务从“进行中”移动到“已完成”需要多次调用 read_file、grep_search、sed 来定位和修改正确的部分。
• 上下文丢失：由于令牌限制，大型任务文件会迫使AI处理不完整的文件块，从而失去对整体结构的跟踪。
• 状态理解：当AI读取碎片化的文件部分时，很难理解项目的真实状态 - 哪些任务实际上正在进行中？
• 编辑精度：手动编辑可能会破坏Markdown格式，丢失任务，或意外修改错误的部分。
• 并发编辑冲突：当AI直接编辑文件时，人类无法安全地进行手动更改，否则会产生冲突或覆盖。
• 令牌效率低下：读取+解析+编辑循环消耗的令牌比具有清晰输入/输出的结构化工具调用要多得多。
• 安全性：AI在直接编辑文件时可能会意外更改或删除任务，但使用这些工具时，它无法重写或删除你的任务。

🤝 贡献代码

我们欢迎贡献！请按照以下步骤进行：

1. 分叉仓库
2. 创建一个功能分支：git checkout -b feature-name
3. 进行更改并编写测试
4. 运行：npm run lint:full
5. 提交拉取请求

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

🔗 链接

• 📦 NPM包
• 🐙 GitHub仓库
• 🐛 报告问题
• 📚 MCP规范
• ⚡ FastMCP框架