MCP Tasks

MCP 任务 📋

一款高效的任务管理器。旨在减少工具使用上的混淆并最大限度提升大模型预算效率，同时支持跨多种文件格式（Markdown、JSON、YAML）进行强大的搜索、筛选和组织。

📚 目录

• ✨ 功能
• 🚀 快速开始
• 🤖 AI 集成技巧
• 🔧 安装示例
• 📁 支持的文件格式
• 🛠️ 可用工具
• 🎛️ 环境变量
• 📊 文件格式
• 🖥️ 服务用法
• 💻 CLI 用法
• 🧪 开发
• 🛠️ 故障排除
• 为什么不让 AI 直接编辑文件？
• 🤝 贡献
• 📄 许可证
• 🔗 链接

✨ 功能

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

🚀 快速开始

将以下内容添加到 Cursor 的 ~/.cursor/mcp.json，或 Claude Desktop 的 ~/.config/claude_desktop_config.json。

选项 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"
      ]
    }
  }
}

🤖 AI 集成技巧

你可以从如下提示词开始，鼓励 AI 使用这些工具；路径可任选，文件扩展名为 .md（推荐）、.json 或 .yml：

Use mcp-tasks tools to track our work in path/to/tasks.md

如果你要告知 AI 新任务或更新后的任务，可以将以下内容附加到提示词末尾：

use mcp-tasks

**AI 工作时添加任务：**要在不干扰 AI 操作的情况下安全添加任务，请在另一个终端中使用 CLI：

npx mcp-tasks add "Your new task text" "To Do" 0

🔧 安装示例

使用自定义环境的完整配置：

{
  "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"
    }
  }
}

📁 支持的文件格式

扩展名	格式	最适合	自动创建
.md	Markdown	人类可读的任务列表	✅
.json	JSON	结构化数据、API	✅
.yml	YAML	配置文件	✅

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

推荐：使用 Markdown（.md），便于阅读和编辑

⚠️ 警告：请使用新文件，而非已有的任务文件，以免丢失非任务内容。

🛠️ 可用工具

当 PREFIX_TOOLS=true（默认值）时，所有工具名称均带有 tasks_ 前缀：

工具	描述	参数
tasks_setup	初始化任务文件（如果文件不存在则创建，支持 .md、.json、.yml）	source_path、workspace?
tasks_search	搜索任务并筛选	source_id、statuses?、terms?、ids?
tasks_add	将新任务添加到指定状态	source_id、texts[]、status、index?
tasks_update	按 ID 更新任务	source_id、ids[]、status、index?
tasks_summary	获取任务数量和进行中的工作	source_id

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

工具示例

设置任务文件：

tasks_setup({
  workspace: "/path/to/project",
  source_path: "tasks.md"  // relative to workspace or absolute
  // source_path: "tasks.json"
  // source_path: "tasks.yml"
})
// Returns: {"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":0,"inProgress":[]}
// Source ID (4-char alphanumeric) is used for all subsequent operations

添加任务：

tasks_add({
  source_id: "xK8p", // From setup response
  texts: ["Implement authentication", "Write tests"],
  status: "To Do",
  index: 0  // Add at top (optional)
})
// Returns: {"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",        // From setup response
  terms: ["auth", "deploy"],          // Search terms (text or status, OR logic)
  statuses: ["To Do"],      // Filter by status
  ids: ["m3Qw", "p9Lx"]     // Filter by specific task IDs
})
// Returns: [{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0}]

更新任务状态：

tasks_update({
  source_id: "xK8p",        // From setup response
  ids: ["m3Qw", "p9Lx"],    // Task IDs from add/search responses
  status: "Done"            // Use "Deleted" to remove
})
// Returns: {"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"         // From setup response
})
// Returns: {"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}]}

🎛️ 环境变量

变量	默认值	描述
TRANSPORT	stdio	传输模式：stdio 或 http
PORT	4680	HTTP 服务端口（当 TRANSPORT=http 时）
PREFIX_TOOLS	true	为工具名称添加 tasks_ 前缀
STATUS_WIP	In Progress	进行中状态名称
STATUS_TODO	To Do	待办状态名称
STATUS_DONE	Done	已完成状态名称
STATUS_REMINDERS	Reminders	给 AI 的提醒（设为空字符串可禁用）
STATUS_NOTES	Notes	备注/不可执行任务（设为空字符串可禁用）
STATUSES	Backlog	以逗号分隔的其他状态
AUTO_WIP	true	只有一个 WIP 时，将其余任务移至待办；没有 WIP 时，将第一个待办移至 WIP
KEEP_DELETED	true	保留已删除的任务（AI 不会丢失你的任务！）
INSTRUCTIONS	...	包含在所有工具响应中，供 AI 遵循
SOURCES_PATH	./sources.json	存储源注册表的文件（内部使用）
DEBUG	false	若为 true，则启用 tasks_debug 工具

高级配置示例

可选：可包含 WIP/待办/已完成状态，以控制其顺序。

自定义工作流状态：

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

📊 文件格式

Markdown（.md）— 人类可读

# Tasks - File Name

## In Progress
- [ ] Write user registration

## To Do
- [ ] Implement authentication
- [ ] Set up CI/CD pipeline

## Backlog
- [ ] Plan architecture
- [ ] Design database schema

## Done
- [x] Set up project structure
- [x] 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!

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

🖥️ 服务用法

# Show help
mcp-tasks --help

# Default: stdio transport
mcp-tasks

# HTTP transport
TRANSPORT=http mcp-tasks
TRANSPORT=http PORT=8080 mcp-tasks

# Custom configuration
STATUS_WIP="Working" AUTO_WIP=false mcp-tasks

💻 命令行用法

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

# Setup a task file
mcp-tasks setup tasks.md $PWD                      # Setup with workspace

# Add tasks
mcp-tasks add "Implement authentication"           # Defaults to "To Do" status
mcp-tasks add "Write tests" "Backlog"              # Add with specific status
mcp-tasks add "Fix critical bug" "In Progress" 0   # Add at top (index 0)

# Search tasks
mcp-tasks search                                    # All tasks
mcp-tasks search "" "auth,login"                   # Search for specific terms
mcp-tasks search "To Do,Done" ""                   # Filter by statuses
mcp-tasks search "In Progress" "bug"               # Filter by status and search terms

# Update task status (comma-separated IDs)
mcp-tasks update m3Qw,p9Lx Done

# Get summary
mcp-tasks summary

# Add a reminder (feature must be enabled with REMINDERS=true)
mcp-tasks add "Don't move to Done until you verified it works" Reminders

命令行功能：

• 直接使用所有 MCP 工具功能
• 以 JSON 格式输出，便于解析和编写脚本
• 与 MCP 工具一样可靠，并能防止重复
• 非常适合自动化脚本和 CI/CD 流水线

🧪 开发

# Clone and setup
git clone https://github.com/flesler/mcp-tasks
cd mcp-tasks
npm install

# Development mode (auto-restart)
npm run dev              # STDIO transport
npm run dev:http         # HTTP transport on port 4680

# Build and test
npm run build           # Compile TypeScript
npm run lint            # Check code style
npm run lint:full       # Build + lint

🛠️ 故障排除

要求

• 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 结构并了解当前状态，成本高且容易出错
• **多步操作：**将任务从“In Progress”移至“Done”，需要多次调用 read_file、grep_search、sed，才能找到并修改正确的章节
• **上下文丢失：**任务文件过大时，受令牌限制，AI 只能处理不完整的片段，容易丢失对整体结构的把握
• **状态理解：**阅读被拆分的文件片段时，AI 难以理解项目的真实状态——哪些任务实际上正在进行？
• **编辑精度：**手动编辑可能破坏 Markdown 格式、丢失任务，或意外修改错误的章节
• **并发编辑冲突：**AI 直接编辑文件时，人类无法安全地手动修改，否则可能产生冲突或覆盖内容
• **令牌效率低：**读取、解析和编辑的循环会消耗远多于输入输出明确的结构化工具调用的令牌
• **安全性：**AI 直接编辑文件时可能意外更改或删除任务；但使用这些工具时，它无法重写或删除你的任务

🤝 参与贡献

欢迎贡献！请按以下步骤操作：

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

📄 许可证

MIT 许可证——详情请参阅 LICENSE。

🔗 链接

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