项目介绍
MCP任务管理器 📋
一个高效的任务管理器。设计用于最小化工具混淆并最大化LLM预算效率，同时提供强大的搜索、过滤和组织功能，支持多种文件格式（Markdown、JSON、YAML）。
📚 目录
- ✨ 特性
- 🚀 快速开始
- 🤖 AI集成提示
- 🔧 安装示例
- 📁 支持的文件格式
- 🛠️ 可用工具
- 🎛️ 环境变量
- 📊 文件格式
- 🖥️ 服务器使用
- 💻 CLI使用
- 🧪 开发
- 🛠️ 故障排除
- 为什么不让AI直接编辑任务文件？
- 🤝 贡献
- 📄 许可证
- 🔗 链接
✨ 特性
- ⚡ 超高效设计：最少工具数量（5个工具）以减少AI混淆
- 🎯 预算优化：批量操作、智能默认值和自动操作最小化LLM API调用
- 🚀 多格式支持：Markdown（
.md）、JSON（.json）和YAML（.yml）任务文件 - 🔍 强大的搜索：不区分大小写的文本/状态过滤，以及基于OR逻辑和ID查找
- 📊 智能组织：基于状态的过滤，具有可定制的工作流状态
- 🎯 基于位置的索引：通过0基础插入轻松排序任务
- 📁 多源支持：同时管理多个任务文件
- 🔄 实时更新：更改会自动持久到您选择的格式
- 🤖 自动WIP管理：自动管理正在进行的任务限制
- 🚫 防止重复：自动防止重复任务
- 🛡️ 类型安全：完全支持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：
使用mcp-tasks工具跟踪我们在path/to/tasks.md中的工作
如果您正在告诉它新的或更新的任务，可以在提示的末尾追加：
使用mcp-tasks
在AI工作时添加任务：为了安全地添加任务而不干扰AI操作，请从单独的终端使用CLI：
npx mcp-tasks add "您的新任务文本" "待办事项" 0
🔧 安装示例
带有自定义环境的完整配置：
{
"mcpServers": {
"mcp-tasks": {
"command": "npx",
"args": ["-y", "mcp-tasks"],
"env": {
"STATUS_WIP": "进行中",
"STATUS_TODO": "待办事项",
"STATUS_DONE": "已完成",
"STATUS_REMINDERS": "提醒",
"STATUS_NOTES": "笔记",
"STATUSES": "进行中,待办事项,已完成,待办事项,提醒,笔记",
"AUTO_WIP": "true",
"PREFIX_TOOLS": "true",
"KEEP_DELETED": "true",
"TRANSPORT": "stdio",
"PORT": "4680",
"INSTRUCTIONS": "当用户提到新任务或更新任务时，使用mcp-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" // 相对于workspace或绝对路径
// source_path: "tasks.json"
// source_path: "tasks.yml"
})
// 返回：{"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"待办事项":0,"进行中":0,"已完成":0,"待办事项":0,"进行中":[]}
// 源ID（4位字母数字）用于后续的所有操作
添加任务：
tasks_add({
source_id: "xK8p", // 来自setup响应
texts: ["实现身份验证", "编写测试"],
status: "待办事项",
index: 0 // 添加到顶部（可选）
})
// 返回：{"source":{"id":"xK8p","path":"/绝对路径/to/tasks.md"},"待办事项":0,"进行中":0,"已完成":0,"待办事项":2,"进行中":[],"任务":[{"id":"m3Qw","text":"实现身份验证","status":"待办事项","index":0},{"id":"p9Lx","text":"编写测试","status":"待办事项","index":1}]}
搜索和过滤：
tasks_search({
source_id: "xK8p", // 来自setup响应
terms: ["认证", "部署"], // 搜索词（文本或状态，OR逻辑）
statuses: ["待办事项"], // 按状态过滤
ids: ["m3Qw", "p9Lx"] // 按特定任务ID过滤
})
// 返回：[{"id":"m3Qw","text":"实现身份验证","status":"待办事项","index":0}]
更新任务状态：
tasks_update({
source_id: "xK8p", // 来自setup响应
ids: ["m3Qw", "p9Lx"], // 来自add/search响应的任务ID
status: "已完成" // 使用“已删除”来移除
})
// 返回：{"source":{"id":"xK8p","path":"/绝对路径/to/tasks.md"},"待办事项":0,"进行中":0,"已完成":2,"待办事项":0,"进行中":[],"任务":[{"id":"m3Qw","text":"实现身份验证","status":"已完成","index":0},{"id":"p9Lx","text":"编写测试","status":"已完成","index":1}]}
获取概览：
tasks_summary({
source_id: "xK8p" // 来自setup响应
})
// 返回：{"source":{"id":"xK8p","path":"/绝对路径/to/tasks.md"},"待办事项":0,"进行中":1,"已完成":2,"待办事项":0,"进行中":[{"id":"r7Km","text":"修复关键错误","status":"进行中","index":0}]}
🎛️ 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
TRANSPORT | stdio | 传输模式：stdio 或 http |
PORT | 4680 | HTTP服务器端口（当TRANSPORT=http时） |
PREFIX_TOOLS | true | 工具名称前缀为tasks_ |
STATUS_WIP | 进行中 | 进行中的状态名称 |
STATUS_TODO | 待办事项 | 待办事项状态名称 |
STATUS_DONE | 已完成 | 完成的状态名称 |
STATUS_REMINDERS | 提醒 | AI的提醒（空字符串禁用） |
STATUS_NOTES | 笔记 | 笔记/非行动项任务（空字符串禁用） |
STATUSES | 待办事项 | 逗号分隔的附加状态 |
AUTO_WIP | true | 一个WIP移动其余到待办事项，第一个待办事项到WIP，如果没有WIP |
KEEP_DELETED | true | 保留已删除的任务（AI不能丢失您的任务！） |
INSTRUCTIONS | ... | 包含在所有工具响应中，供AI遵循 |
SOURCES_PATH | ./sources.json | 存储源注册表的文件（内部） |
DEBUG | false | 如果为真，则启用tasks_debug工具 |
高级配置示例
可选，WIP/待办事项/已完成状态可以包含以控制其顺序。
自定义工作流程状态：
{
"env": {
"STATUSES": "WIP,待处理,存档,已完成,待审核",
"STATUS_WIP": "WIP",
"STATUS_TODO": "待处理",
"AUTO_WIP": "false"
}
}
📊 文件格式
Markdown（.md）- 人类可读
# 任务 - 文件名
## 进行中
- [ ] 编写用户注册
## 待办事项
- [ ] 实现身份验证
- [ ] 设置CI/CD管道
## 待办事项
- [ ] 规划架构
- [ ] 设计数据库模式
## 已完成
- [x] 设置项目结构
- [x] 初始化仓库
## 提醒
- [ ] 在确认有效之前不要移到已完成
- [ ] 移到已完成后，提交所有更改，使用任务名称作为提交消息
## 笔记
- [ ] 任务工具真的很好用！
JSON（.json）- 结构化数据
{
"groups": {
"进行中": [
"编写用户注册"
],
"待办事项": [
"实现身份验证",
"设置CI/CD管道"
],
"待办事项": [
"规划架构",
"设计数据库模式"
],
"已完成": [
"设置项目结构",
"初始化仓库"
],
"提醒": [
"在确认有效之前不要移到已完成",
"移到已完成后，提交所有更改，使用任务名称作为提交消息"
],
"笔记": [
"任务工具真的很好用！"
]
}
}
YAML（.yml）- 配置友好
groups:
"进行中":
- 编写用户注册
"待办事项":
- 实现身份验证
- 设置CI/CD管道
待办事项:
- 规划架构
- 设计数据库模式
已完成:
- 设置项目结构
- 初始化仓库
提醒:
- 在确认有效之前不要移到已完成
- 移到已完成后，提交所有更改，使用任务名称作为提交消息
🖥️ 服务器使用
# 显示帮助
mcp-tasks --help
# 默认：stdio传输
mcp-tasks
# HTTP传输
TRANSPORT=http mcp-tasks
TRANSPORT=http PORT=8080 mcp-tasks
# 自定义配置
STATUS_WIP="进行中" AUTO_WIP=false mcp-tasks
💻 CLI使用
您还可以使用mcp-tasks（或npx mcp-tasks）作为命令行工具进行快速任务管理：
# 设置任务文件
mcp-tasks setup tasks.md $PWD # 使用workspace设置
# 添加任务
mcp-tasks add "实现身份验证" # 默认为"待办事项"状态
mcp-tasks add "编写测试" "待办事项" # 使用特定状态添加
mcp-tasks add "修复关键错误" "进行中" 0 # 添加到顶部（索引0）
# 搜索任务
mcp-tasks search # 所有任务
mcp-tasks search "" "认证,登录" # 搜索特定术语
mcp-tasks search "待办事项,已完成" "" # 按状态过滤
mcp-tasks search "进行中" "错误" # 按状态和搜索词过滤
# 更新任务状态（逗号分隔的ID）
mcp-tasks update m3Qw,p9Lx 已完成
# 获取概览
mcp-tasks summary
# 添加提醒（必须启用REMINDERS=true）
mcp-tasks add "在确认有效之前不要移到已完成" 提醒
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时出现类似无法找到模块 '@modelcontextprotocol/sdk/dist/esm/server/index.js'的错误 - 原因：损坏或不完整的npx缓存阻止了正确的依赖解析
- 解决方案：清除npx缓存并再次尝试：
npx clear-npx-cache npx mcp-tasks - 注意：此问题可能出现在Node.js v20和v22上，清除缓存可以解决
我的任务存储在哪里？
- 任务存储在AI指定的文件路径中，在
tasks_setup