MCP Tasks

🚀 MCP Tasks 📋

MCP Tasksは、複数のファイル形式（Markdown、JSON、YAML）に対応した強力な検索、フィルタリング、整理機能を備えた、効率的なタスクマネージャーです。ツールの混乱を最小限に抑え、LLMの予算効率を最大化します。

🚀 クイックスタート

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

✨ 主な機能

• ⚡ 超効率的な設計：ツール数を最小限（5つのツール）に抑え、AIの混乱を減らします。
• 🎯 予算最適化：バッチ操作、スマートなデフォルト設定、自動操作により、LLM API呼び出しを最小限に抑えます。
• 🚀 複数フォーマット対応：Markdown（.md）、JSON（.json）、YAML（.yml）のタスクファイルをサポートします。
• 🔍 強力な検索機能：大文字小文字を区別しないテキスト/ステータスフィルタリング（OR論理）とIDベースの検索が可能です。
• 📊 スマートな整理機能：カスタマイズ可能なワークフロー状態に基づくステータスフィルタリングができます。
• 🎯 位置ベースのインデックス：0ベースの挿入により、タスクの順序付けが簡単です。
• 📁 複数ソースサポート：複数のタスクファイルを同時に管理できます。
• 🔄 リアルタイム更新：選択したフォーマットに自動的に変更が保存されます。
• 🤖 自動WIP管理：作業中のタスク制限を自動的に管理します。
• 🚫 重複防止：自動的に重複タスクを防止します。
• 🛡️ 型安全：Zodバリデーションを備えた完全なTypeScriptサポートです。
• 🔒 超安全：AIはタスクを書き換えたり削除することはできません（有効にしない限り）。追加と移動のみ可能です。
• 📅 オプションのリマインダー：AIが常に参照できる専用のリマインダーセクションを有効にできます。

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

📁 サポートされるファイル形式

フォーマットはファイル拡張子から自動検出されます。すべてのフォーマットが同じ機能をサポートし、同じプロジェクト内で混合使用することができます。

推奨：人間が読みやすく編集しやすい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", // setupのレスポンスから取得
  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",        // setupのレスポンスから取得
  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",        // setupのレスポンスから取得
  ids: ["m3Qw", "p9Lx"],    // add/searchのレスポンスから取得したタスク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"         // setupのレスポンスから取得
})
// 戻り値: {"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/ToDo/Doneのステータスを含めて、それらの順序を制御することができます。

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

🖥️ サーバーの使用方法

# ヘルプを表示する
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         # ポート4680でHTTPトランスポート

# ビルドとテスト
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の両方で発生する可能性があり、キャッシュをクリアすることで解決されます。

タスクはどこに保存されていますか？

• タスクは、tasks_setupでAIが指定したファイルパスに保存されます。
• 絶対パスは、すべてのツール呼び出しのレスポンスのsource.pathに含まれています。
• 場所を忘れた場合は、任意のツールのレスポンスを確認するか、AIに表示させることができます。

Markdownファイルの内容が失われた場合

• ⚠️ ツールはファイル全体を書き換え、認識されたステータスセクション内のタスクのみを保持します。
• 非タスクコンテンツ（メモ、ドキュメント）は、ツールがファイルを変更する際に失われる可能性があります。
• 他のコンテンツとタスクを混在させるのではなく、専用のタスクファイルを使用することをおすすめします。

なぜAIにタスクファイルを直接編集させないのですか？

• ファイル解析の複雑さ：AIはファイル全体を読み、Markdown構造を解析し、現在の状態を理解する必要があります。これはコストがかかり、エラーが発生しやすいです。
• 多段階操作：タスクを「作業中」から「完了」に移動するには、read_file、grep_search、sedの複数の呼び出しが必要で、正しいセクションを見つけて変更する必要があります。
• コンテキストの喪失：大きなタスクファイルの場合、トークン制限のためにAIが不完全なチャンクで作業する必要があり、全体の構造を把握できなくなります。
• 状態の理解：AIは、断片的なファイルセクションを読むだけでは、実際のプロジェクトの状態を理解するのが難しいです。どのタスクが実際に作業中なのかを把握するのが困難です。
• 編集の精度：手動で編集すると、Markdownの書式が破損したり、タスクが失われたり、誤って間違ったセクションを変更するリスクがあります。
• 同時編集の競合：AIが直接ファイルを編集する場合、人間が手動で変更を加えると、競合や上書きが発生する可能性があります。
• トークンの非効率性：読み取り+解析+編集のサイクルは、明確な入力/出力を持つ構造化ツール呼び出しよりもはるかに多くのトークンを消費します。
• 安全性：AIが直接ファイルを編集すると、誤ってタスクを変更または削除する可能性がありますが、これらのツールを使用すると、AIはタスクを書き換えたり削除することはできません。

🤝 コントリビューション

コントリビューションを歓迎します！以下の手順に従ってください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します：git checkout -b feature-name
3. テストを含めて変更を加えます。
4. npm run lint:fullを実行します。
5. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEを参照してください。

🔗 リンク

• 📦 NPMパッケージ
• 🐙 GitHubリポジトリ
• 🐛 問題を報告する
• 📚 MCP仕様
• ⚡ FastMCPフレームワーク