MCP Tasks

MCP任务📋

高效的任务管理器。旨在最大限度地减少工具混淆，最大限度地提高LLM预算效率，同时跨多种文件格式（Markdown、JSON、YAML）提供强大的搜索、过滤和组织功能

📚 目录

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

✨ 特性

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

🚀 快速开始

将此添加到 ~/.cursor/mcp.json 对于光标， ~/.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集成提示

为了鼓励人工智能使用这些工具，您可以从以下提示开始，使用.md（推荐）、.json、.yml的任何路径：

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

如果你告诉它新的或更新的任务，你可以将其附加到提示的末尾：

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

📁 支持的文件格式

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

推荐：Markdown(.md)便于人类阅读和编辑

⚠️ 警告：从新文件开始，而不是使用预先存在的任务文件，以避免丢失非任务内容。

🛠️ 可用工具

当 PREFIX_TOOLS=true （默认），所有工具都以前缀 tasks_:

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}]}

🎛️ 环境变量

高级配置示例

可选地，可以包括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

💻 CLI使用情况

您还可以使用 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

CLI功能：

• 直接访问所有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或更高版本

常见问题

运行时出现ERR_MODULE_NOT_FOUND npx-tasks

• 问题：类似错误 Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' 跑步时 npx mcp-tasks
• 原因：npx缓存损坏或不完整，无法正确解析依赖关系
• 解决方案：清除npx缓存，然后重试：

  npx clear-npx-cache
  npx mcp-tasks

• 备注：此问题可能发生在Node.js v20和v22上，缓存清除可以解决此问题

我的任务存储在哪里？

• 任务存储在AI在中指定的文件路径中 tasks_setup
• 在下的每个工具调用响应中返回绝对路径 source.path
• 如果您忘记了位置，请检查任何工具响应或要求AI向您显示

Markdown文件中丢失的内容：

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

为什么不让人工智能直接编辑任务文件呢？

• 文件解析复杂性： 人工智能必须读取整个文件，解析markdown结构，并了解当前状态——代价高昂且容易出错
• 多步操作： 将任务从“进行中”移动到“完成”需要多个 read_file, grep_search, sed 调用以定位和修改正确的部分
• 上下文丢失： 由于令牌限制，大型任务文件迫使人工智能处理不完整的块，并失去对整体结构的跟踪
• 状态理解： 人工智能在读取零碎的文件部分时很难理解真实的项目状态——哪些任务实际上正在进行中？
• 编辑精度： 手动编辑有损坏markdown格式、丢失任务或意外修改错误部分的风险
• 并发编辑冲突： 当人工智能直接编辑文件时，人类无法在不产生冲突或覆盖的情况下安全地进行手动更改
• 令牌效率低下： 读取+解析+编辑周期消耗的令牌比具有清晰输入/输出的结构化工具调用多得多
• 安全： 人工智能在直接编辑文件时可能会意外更改或删除任务，但使用这些工具，它无法重写或删除您的任务

🤝 贡献

我们欢迎捐款！拜托：

1. 分叉存储库
2. 创建要素分支： git checkout -b feature-name
3. 通过测试进行更改
4. 运行： npm run lint:full
5. 提交拉取请求

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

🔗 链接

• 📦 ****
• 🐙 ****
• 🐛 报告问题
• 📚 MCP规范
• ⚡ FastMCP框架