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框架