TaskFlow MCP 🔄✅

TaskFlow MCP 🔄✅

AI アシスタントと連携してタスクの計画と実行を行う、タスク管理用の Model Context Protocol（MCP）サーバーです。

🌟 概要

TaskFlow MCP は、AI アシスタントがユーザーのリクエストを管理しやすいタスクに分解し、その完了状況を追跡するための専用サーバーです。ユーザーの承認ステップを設けた構造化ワークフローを徹底することで、タスクを適切に追跡し、ユーザーがプロセスを管理できるようにします。

✨ 機能

• 📋 タスク計画：複雑なリクエストを管理しやすいタスクに分解します
• 🔍 サブタスク：タスクをより小さく、管理しやすいサブタスクに分割します
• 📊 進捗追跡：視覚的な進捗テーブルで、タスク、サブタスク、リクエストの状況を追跡します
• 👍 ユーザー承認：品質と管理性を確保するため、ユーザーの承認ステップを設けます
• 💾 永続化：タスクとリクエストをディスクに保存し、セッションをまたいで保持します
• 🔄 柔軟な管理：必要に応じてタスクやサブタスクを追加、更新、削除します
• 📝 詳細なレポート：タスクの詳細と進捗テーブルを表示します
• 📤 エクスポートオプション：タスク計画と状況レポートを Markdown、JSON、HTML 形式でエクスポートします
• 📦 依存関係：プロジェクトおよびタスクレベルの依存関係をバージョン情報とともに追跡します
• 📌 メモ：重要な情報や設定をプロジェクトレベルのメモとして追加します
• 📄 YAML サポート：複数行のコンテンツをより適切に扱える YAML 形式でタスクを保存します
• 🛡️ 堅牢なテキスト処理：信頼性の高いデータ永続化を実現する、包括的な改行サニタイズ
• 🎯 プロンプトシステム：一貫した LLM ガイダンスのためのグローバル指示と、タスクの接頭辞／接尾辞
• 📚 タスクのアーカイブ：完了したリクエストをアーカイブし、アクティブなタスクリストを整理された状態に保ちます
• 🗂️ アーカイブ管理：履歴をすべて保持したまま、アーカイブ済みタスクの閲覧、検索、復元ができます
• 📍 相対パスのサポート：プロジェクトベースの柔軟なワークフローに相対パスを使用できます

🚀 インストール

グローバルインストール

npm install -g @pinkpixel/taskflow-mcp

ローカルインストール

npm install @pinkpixel/taskflow-mcp

🛠️ 使用方法

サーバーの起動

グローバルインストールの場合：

taskflow-mcp

ローカルインストールの場合：

npx taskflow-mcp

設定

デフォルトでは、TaskFlow MCP は現在の作業ディレクトリにある tasks.yaml にタスクを保存します。TASK_MANAGER_FILE_PATH 環境変数を設定すると、保存先をカスタマイズできます。

ファイルパスのオプション

絶対パス（本番環境に推奨）：

TASK_MANAGER_FILE_PATH=/home/user/projects/my-tasks.yaml taskflow-mcp
# Windows
TASK_MANAGER_FILE_PATH=C:\Users\username\Documents\tasks.yaml taskflow-mcp

相対パス（プロジェクトベースのワークフローに最適）：

# Resolves to ./project-tasks.yaml in the current directory
TASK_MANAGER_FILE_PATH=project-tasks.yaml taskflow-mcp

# Resolves to ./tasks/current.yaml relative to working directory
TASK_MANAGER_FILE_PATH=tasks/current.yaml taskflow-mcp

応用：カスタムベースディレクトリ

# Use a different base directory for relative path resolution
TASK_MANAGER_BASE_DIR=/home/user/workspace TASK_MANAGER_FILE_PATH=tasks.yaml taskflow-mcp

クロスプラットフォーム互換性

TaskFlow MCP は Windows と Linux の間でパス解決を自動的に処理します：

• Node.js の path.resolve() と path.normalize() を使用し、一貫した動作を実現します
• Windows ではスラッシュ（/）とバックスラッシュ（\）の両方に対応します
• タスクの保存時に親ディレクトリを自動的に作成します
• パス解決の問題について、わかりやすいエラーメッセージを表示します

YAML 形式のサポート

TaskFlow MCP は、データの永続化に JSON と YAML の両方の形式をサポートしています。YAML 形式を使用するには、ファイルパスの拡張子に .yaml または .yml を指定します。

TASK_MANAGER_FILE_PATH=/path/to/tasks.yaml taskflow-mcp

YAML 形式は、特に次の用途に便利です：

• 複数行の説明やテキストコンテンツをより適切に保持できます
• タスクのデータファイルをより読みやすくできます
• 必要に応じて手動で簡単に編集できます

形式はファイルの拡張子に基づいて自動的に判別され、既存の JSON ファイルとの完全な後方互換性も維持されます。

アーカイブシステム

TaskFlow MCP v1.4.1 には、アクティブなタスクリストを整理しながら、完了した作業の履歴を保持する包括的なアーカイブシステムが含まれています。

# Configure archive file path (optional - defaults to [taskfile-name]-archive.[ext])
ARCHIVE_FILE_PATH=/path/to/tasks-archive.yaml taskflow-mcp

# Set archive mode (optional - defaults to 'manual')
ARCHIVE_MODE=manual taskflow-mcp  # or 'auto-on-complete'

アーカイブ機能には、次のものがあります。

• 手動アーカイブ：準備ができたら archive_completed_requests ツールを使用してアーカイブします
• 自動アーカイブ：ARCHIVE_MODE=auto-on-complete を設定すると、自動的にアーカイブされます
• アーカイブの閲覧：list_archived_requests を使用して、アーカイブされたリクエストを検索・絞り込みます
• アーカイブの復元：restore_archived_request を使用して、アーカイブされたリクエストをアクティブな状態に戻します
• 履歴の完全な保持：タスクの完全な履歴、タイムスタンプ、メタデータが保持されます

MCP の設定

TaskFlow MCP を AI アシスタントで使用するには、MCP クライアントがサーバーを使用するように設定する必要があります。次の内容で mcp_config.json ファイルを作成します。

基本設定：

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/taskflow-mcp"],
      "env": {
        "TASK_MANAGER_FILE_PATH": "/path/to/tasks.yaml"
      }
    }
  }
}

詳細設定（v1.4.1 のすべてのオプションを含む）：

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/taskflow-mcp"],
      "env": {
        "TASK_MANAGER_FILE_PATH": "./project-tasks.yaml",
        "TASK_MANAGER_BASE_DIR": "/path/to/project/root",
        "ARCHIVE_FILE_PATH": "./tasks-archive.yaml",
        "ARCHIVE_MODE": "manual"
      }
    }
  }
}

設定オプション：

• TASK_MANAGER_FILE_PATH：タスクファイルのパス（.json/.yaml、絶対パス／相対パスに対応）
• TASK_MANAGER_BASE_DIR：相対パスの解決に使用するカスタムベースディレクトリ
• ARCHIVE_FILE_PATH：アーカイブファイルのパス（任意。指定しない場合は自動生成されます）
• ARCHIVE_MODE：アーカイブモード。「manual」（デフォルト）または「auto-on-complete」

💡 ヒント： 詳細なコメントと使用例を含む完全な設定例については、examples/mcp_config_comprehensive.json を参照してください。

🔄 ワークフロー

TaskFlow MCP では、特定のワークフローが適用されます。

1. タスクを計画する：ユーザーのリクエストをタスク（任意でサブタスクを含む）に分割します
2. 次のタスクを取得する：次に保留中のタスクを取得します
3. サブタスクを完了する：タスクにサブタスクがある場合、タスクを完了としてマークする前に、各サブタスクを完了します
4. タスクを完了としてマークする：タスクを完了としてマークします（その前に、すべてのサブタスクを完了する必要があります）
5. ユーザーの確認を待つ：次に進む前に、完了したタスクをユーザーに確認してもらいます
6. 繰り返す：すべてのタスクが完了するまで、次のタスクに進みます
7. 最終確認：リクエスト全体が完了したことをユーザーに確認します

AI アシスタントにこのワークフローを一貫して実行させるには、アシスタントの指示に追加できるシステムプロンプトについて、example-system-prompt.md ファイルを参照してください。

🧰 利用可能なツール

TaskFlow MCP は、次のツールを AI アシスタントに提供します。

plan_task

新しいユーザーリクエストを登録し、関連するタスク（任意でサブタスクを含む）を計画します。

{
  "originalRequest": "Create a new website for my business",
  "outputPath": "C:/Users/username/Documents/website-project-plan.md",
  "dependencies": [
    {
      "name": "Node.js",
      "version": ">=14.0.0",
      "description": "JavaScript runtime"
    },
    {
      "name": "npm",
      "version": ">=6.0.0",
      "description": "Package manager"
    }
  ],
  "notes": [
    {
      "title": "Package Manager Preference",
      "content": "User prefers pnpm over npm for package management."
    },
    {
      "title": "Design Guidelines",
      "content": "Follow the company's brand guidelines for colors and typography."
    }
  ],
  "tasks": [
    {
      "title": "Design homepage",
      "description": "Create a design for the homepage with logo, navigation, and hero section",
      "dependencies": [
        {
          "name": "Figma",
          "description": "Design tool"
        }
      ],
      "subtasks": [
        {
          "title": "Design logo",
          "description": "Create a logo that represents the business brand"
        },
        {
          "title": "Design navigation",
          "description": "Create a user-friendly navigation menu"
        }
      ]
    },
    {
      "title": "Implement HTML/CSS",
      "description": "Convert the design to HTML and CSS",
      "dependencies": [
        {
          "name": "HTML5",
          "description": "Markup language"
        },
        {
          "name": "CSS3",
          "description": "Styling language"
        }
      ]
    }
  ]
}

get_next_task

リクエストの次に保留中のタスクを取得します。

{
  "requestId": "req-1"
}

mark_task_done

タスクを完了としてマークします。

{
  "requestId": "req-1",
  "taskId": "task-1",
  "completedDetails": "Created a modern design with a clean layout"
}

open_task_details

特定のタスクの詳細を取得します。

{
  "taskId": "task-1"
}

list_requests

システム内のすべてのリクエストを一覧表示します。

{}

add_tasks_to_request

既存のリクエストにタスクを追加します。

{
  "requestId": "req-1",
  "tasks": [
    {
      "title": "Add contact form",
      "description": "Create a contact form with validation"
    }
  ]
}

update_task

タスクのタイトルまたは説明を更新します。

{
  "requestId": "req-1",
  "taskId": "task-1",
  "title": "Design responsive homepage",
  "description": "Create a responsive design for the homepage"
}

delete_task

リクエストからタスクを削除します。

{
  "requestId": "req-1",
  "taskId": "task-1"
}

add_subtasks

既存のタスクにサブタスクを追加します。

{
  "requestId": "req-1",
  "taskId": "task-1",
  "subtasks": [
    {
      "title": "Design logo",
      "description": "Create a logo that represents the business brand"
    },
    {
      "title": "Design navigation",
      "description": "Create a user-friendly navigation menu"
    }
  ]
}

mark_subtask_done

サブタスクを完了としてマークします。

{
  "requestId": "req-1",
  "taskId": "task-1",
  "subtaskId": "subtask-1"
}

update_subtask

サブタスクのタイトルまたは説明を更新します。

{
  "requestId": "req-1",
  "taskId": "task-1",
  "subtaskId": "subtask-1",
  "title": "Design modern logo",
  "description": "Create a modern logo that represents the business brand"
}

delete_subtask

タスクからサブタスクを削除します。

{
  "requestId": "req-1",
  "taskId": "task-1",
  "subtaskId": "subtask-1"
}

export_task_status

リクエスト内のすべてのタスクの現在のステータスをファイルにエクスポートします。より確実にファイルを作成するには、絶対パスを使用することをおすすめします。

{
  "requestId": "req-1",
  "outputPath": "C:/Users/username/Documents/task-status.md",
  "format": "markdown"
}

add_note

リクエストにメモを追加します。

{
  "requestId": "req-1",
  "title": "Package Manager Preference",
  "content": "User prefers pnpm over npm for package management."
}

update_note

既存のメモを更新します。

{
  "requestId": "req-1",
  "noteId": "note-1",
  "title": "Package Manager Preference",
  "content": "User prefers pnpm over npm and yarn for package management."
}

delete_note

リクエストからメモを削除します。

{
  "requestId": "req-1",
  "noteId": "note-1"
}

add_dependency

リクエストまたはタスクに依存関係を追加します。

{
  "requestId": "req-1",
  "taskId": "task-1",
  "dependency": {
    "name": "react",
    "version": "^18.2.0",
    "description": "JavaScript library for building user interfaces",
    "url": "https://reactjs.org"
  }
}

🎯 プロンプト管理

TaskFlow MCP は、タスク間で LLM の集中力と一貫性を高めるグローバルなプロンプトシステムに対応しました。これは、ユーザーからのフィードバックで要望されていた、カスタム指示やタスクの接頭辞／接尾辞への対応を目的としています。

get_prompts

現在のプロンプト設定を取得します。

{}

戻り値： instructions、taskPrefix、taskSuffix を含む現在のプロンプト設定です。

set_prompts

プロンプトのグローバル設定を設定します（既存の設定を置き換えます）。

{
  "instructions": "You are working on a React TypeScript project. Always follow the existing patterns and ensure type safety.",
  "taskPrefix": "🎯 IMPORTANT: Review the project architecture before starting.",
  "taskSuffix": "✅ Remember to run tests and ensure all imports are properly typed."
}

update_prompts

すべてを置き換えずに、プロンプト設定の一部を更新します。

{
  "instructions": "Updated project context: Now using Next.js 14 with App Router.",
  "taskPrefix": "🚀 NEW APPROACH: Consider server components first."
}

remove_prompts

プロンプト設定全体、または特定のフィールドを削除します。

{
  "fields": ["taskPrefix", "taskSuffix"]
}

すべてのプロンプトを削除するには、空のままにします：

{}

プロンプトの仕組み

プロンプトが設定されている場合：

1. Instructions は各タスクのコンテキストとして表示されます
2. Task Prefix はすべてのタスクの説明の先頭に追加されます
3. Task Suffix はすべてのタスクの説明の末尾に追加されます
4. これらは、get_next_task または open_task_details を通じてタスクを取得する際に自動的に適用されます

プロンプトを含むタスクファイルの例：

prompts:
  instructions: "Follow the company coding standards and review architecture docs"
  taskPrefix: "📋 Before starting: Check dependencies and read recent changes"
  taskSuffix: "🔍 After completion: Verify all tests pass and code is properly documented"
  createdAt: "2024-03-15T10:30:00Z"
  updatedAt: "2024-03-15T11:45:00Z"

requests:
  - requestId: req-1
    originalRequest: "Add user authentication"
    # ... rest of tasks

📦 アーカイブ管理

TaskFlow MCP には、完了したリクエストを別のアーカイブファイルに移動して、アクティブなタスクファイルを整理された状態に保つための包括的なアーカイブシステムが含まれています。これにより、完了済みタスクが多い大規模プロジェクトでタスクファイルが煩雑になる問題に対処できます。

環境変数

アーカイブ設定：

# Optional: Custom archive file path (defaults to tasks-archive.yaml in same directory as task file)
ARCHIVE_FILE_PATH=/path/to/custom-archive.yaml

# Optional: Archive mode (manual or auto-on-complete, defaults to manual)
ARCHIVE_MODE=manual

archive_completed_requests

アクティブなタスクファイルを整理された状態に保つため、完了したリクエストをアーカイブします。

{
  "requestIds": ["req-1", "req-2"]
}

完了したすべてのリクエストをアーカイブする：

{}

list_archived_requests

オプションの検索とフィルタリングを指定して、アーカイブ済みのリクエストを一覧表示します。

{
  "searchTerm": "website project",
  "limit": 10
}

restore_archived_request

アーカイブ済みのリクエストをアクティブなタスクに戻します。

{
  "requestId": "req-1"
}

アーカイブファイルの形式

アーカイブ済みのリクエストは、タスクファイルと同じ形式（JSON/YAML）で保存されます：

archiveInfo:
  createdAt: "2024-03-15T10:00:00Z"
  lastArchivedAt: "2024-03-15T15:30:00Z"
  totalArchivedRequests: 5
  version: "1.0.0"

archivedRequests:
  - requestId: req-1
    originalRequestId: req-1
    originalRequest: "Build user authentication system"
    archivedAt: "2024-03-15T15:30:00Z"
    completedAt: "2024-03-15T15:25:00Z"
    tasks:
      - # ... completed tasks
    # ... other request data

アーカイブのワークフロー

1. タスクを完了する - リクエスト内のすべてのタスクを完了します
2. 完了したリクエストをアーカイブする - archive_completed_requests を使用してアーカイブに移動します
3. アーカイブを閲覧する - list_archived_requests を使用してアーカイブ済みの作業を確認します
4. 必要に応じて復元する - restore_archived_request を使用してアーカイブ済みのリクエストを戻します

メリット：

• ✅ アクティブファイルを整理 - 作業中のタスクファイルを、焦点が定まり、煩雑にならない状態に保てます
• ✅ 履歴を保持 - 完了したすべての作業がタイムスタンプとともに安全に保存されます
• ✅ 簡単に復元 - 再確認が必要な場合、アーカイブ済みのリクエストを復元できます
• ✅ 検索可能なアーカイブ - 名前または ID でアーカイブ済みのリクエストを検索できます
• ✅ 自動管理 - リクエストの完了時に自動アーカイブするオプションがあります

📚 ドキュメント

プロジェクトのアーキテクチャと実装について詳しくは、OVERVIEW.md ファイルを参照してください。

📝 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

🤝 コントリビューション

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.md ファイルを参照してください。

📜 変更履歴

このプロジェクトの変更履歴については、CHANGELOG.md ファイルを参照してください。

🙏 謝辞

• Model Context Protocol (MCP) を使用して構築
• Pink Pixel が作成

---

❤️ を込めて Pink Pixel が作成