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
Register a new user request and plan its associated tasks (with optional subtasks).
{
"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
