使用说明

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

📁 支持的文件格式

扩展	格式	最适合	自动创建
`.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`	如果为真，则启用 `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

💻 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格式、丢失任务或意外修改错误部分的风险
并发编辑冲突： 当人工智能直接编辑文件时，人类无法在不产生冲突或覆盖的情况下安全地进行手动更改
令牌效率低下： 读取+解析+编辑周期消耗的令牌比具有清晰输入/输出的结构化工具调用多得多
安全： 人工智能在直接编辑文件时可能会意外更改或删除任务，但使用这些工具，它无法重写或删除您的任务

🤝 贡献

我们欢迎捐款！拜托：

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

📄 许可证

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

🔗 链接

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