TaskFlow MCP

TaskFlow MCP 🔄✅

A task management Model Context Protocol (MCP) server for planning and executing tasks with AI assistants.

🌟 Overview

TaskFlow MCP is a specialized server that helps AI assistants break down user requests into manageable tasks and track their completion. It enforces a structured workflow with user approval steps to ensure tasks are properly tracked and users maintain control over the process.

✨ Features

📋 Task Planning: Break down complex requests into manageable tasks
🔍 Subtasks: Divide tasks into smaller, more manageable subtasks
📊 Progress Tracking: Track the status of tasks, subtasks, and requests with visual progress tables
👍 User Approval: Enforce user approval steps to ensure quality and control
💾 Persistence: Save tasks and requests to disk for persistence across sessions
🔄 Flexible Management: Add, update, or delete tasks and subtasks as needed
📝 Detailed Reporting: View task details and progress tables
📤 Export Options: Export task plans and status reports in Markdown, JSON, or HTML formats
📦 Dependencies: Track project and task-level dependencies with version information
📌 Notes: Add project-level notes for important information and preferences

🚀 Installation

Global Installation

npm install -g @pinkpixel/taskflow-mcp

Local Installation

npm install @pinkpixel/taskflow-mcp

🛠️ Usage

Starting the Server

If installed globally:

taskflow-mcp

If installed locally:

npx taskflow-mcp

Configuration

By default, TaskFlow MCP saves tasks to ~/Documents/tasks.json. You can change this by setting the TASK_MANAGER_FILE_PATH environment variable:

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

MCP Configuration

To use TaskFlow MCP with AI assistants, you need to configure your MCP client to use the server. Create an mcp_config.json file with the following content:

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

🔄 Workflow

TaskFlow MCP enforces a specific workflow:

Plan Tasks: Break down a user request into tasks (with optional subtasks)
Get Next Task: Retrieve the next pending task
Complete Subtasks: If the task has subtasks, complete each subtask before marking the task as done
Mark Task Done: Mark a task as completed (requires all subtasks to be completed first)
Wait for Approval: Wait for user approval of the completed task
Repeat: Continue with the next task until all tasks are complete
Final Approval: Get user approval for the entire request

For AI assistants to consistently follow this workflow, see the example-system-prompt.md file for system prompts you can add to your assistant's instructions.

🧰 Available Tools

TaskFlow MCP exposes the following tools to AI assistants:

`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`

Retrieve the next pending task for a request.

{
  "requestId": "req-1"
}

`mark_task_done`

Mark a task as completed.

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

`approve_task_completion`

Approve a completed task.

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

`approve_request_completion`

Approve an entire request as completed.

{
  "requestId": "req-1"
}

`open_task_details`

Get details about a specific task.

{
  "taskId": "task-1"
}

`list_requests`

List all requests in the system.

{}

`add_tasks_to_request`

Add more tasks to an existing request.

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

`update_task`

Update a task's title or description.

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

`delete_task`

Delete a task from a request.

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

`add_subtasks`

Add subtasks to an existing task.

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

Mark a subtask as completed.

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

`update_subtask`

Update a subtask's title or description.

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

Delete a subtask from a task.

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

`export_task_status`

Export the current status of all tasks in a request to a file. It's recommended to use absolute paths for more reliable file creation.

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

`add_note`

Add a note to a request.

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

`update_note`

Update an existing note.

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

`delete_note`

Delete a note from a request.

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

`add_dependency`

Add a dependency to a request or task.

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

📚 Documentation

For more detailed information about the project architecture and implementation, see the OVERVIEW.md file.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines.

📜 Changelog

See the CHANGELOG.md file for a history of changes to this project.

🙏 Acknowledgements

Built with Model Context Protocol (MCP)
Created by Pink Pixel

Made with ❤️ by Pink Pixel

Integrations

TaskFlow MCP 🔄✅

🌟 Overview

✨ Features

🚀 Installation

Global Installation

Local Installation

🛠️ Usage

Starting the Server

Configuration

MCP Configuration

🔄 Workflow

🧰 Available Tools

plan_task

get_next_task

mark_task_done

approve_task_completion

approve_request_completion

open_task_details

list_requests

add_tasks_to_request

update_task

delete_task

add_subtasks

mark_subtask_done

update_subtask

delete_subtask

export_task_status

add_note

update_note

delete_note

add_dependency