{"id":28579642,"url":"https://github.com/pinkpixel-dev/taskflow-mcp","last_synced_at":"2025-07-04T10:34:08.228Z","repository":{"id":292438759,"uuid":"980871649","full_name":"pinkpixel-dev/taskflow-mcp","owner":"pinkpixel-dev","description":"A task management Model Context Protocol (MCP) server that helps AI assistants break down user requests into manageable tasks with subtasks, dependencies, and notes. Enforces a structured workflow with user approval steps.","archived":false,"fork":false,"pushed_at":"2025-05-31T18:24:38.000Z","size":1163,"stargazers_count":11,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-09T23:03:16.002Z","etag":null,"topics":["ai-assistant","claude","cursor","dependencies-manager","mcp","mcp-server","model-context-protocol","model-context-protocol-servers","nodejs","notes-manager","npm-package","project-management","subtasks","taskflow","typescript","workflow"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pinkpixel-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-09T21:34:17.000Z","updated_at":"2025-05-31T18:24:42.000Z","dependencies_parsed_at":"2025-05-10T01:20:54.293Z","dependency_job_id":"052ea442-bbf1-4a47-8f49-95e366aea4e9","html_url":"https://github.com/pinkpixel-dev/taskflow-mcp","commit_stats":null,"previous_names":["pinkpixel-dev/taskflow-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pinkpixel-dev/taskflow-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Ftaskflow-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Ftaskflow-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Ftaskflow-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Ftaskflow-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinkpixel-dev","download_url":"https://codeload.github.com/pinkpixel-dev/taskflow-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Ftaskflow-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263493378,"owners_count":23475184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","claude","cursor","dependencies-manager","mcp","mcp-server","model-context-protocol","model-context-protocol-servers","nodejs","notes-manager","npm-package","project-management","subtasks","taskflow","typescript","workflow"],"created_at":"2025-06-11T02:09:10.481Z","updated_at":"2025-07-04T10:34:08.197Z","avatar_url":"https://github.com/pinkpixel-dev.png","language":"JavaScript","funding_links":[],"categories":["📚 Projects (1974 total)","Other Tools and Integrations","🌐 Web Development"],"sub_categories":["MCP Servers","How to Submit"],"readme":"[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/pinkpixel-dev-taskflow-mcp-badge.png)](https://mseep.ai/app/pinkpixel-dev-taskflow-mcp)\n\n# TaskFlow MCP 🔄✅\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"taskflow.png\" alt=\"TaskFlow MCP\"\u003e\n\u003c/p\u003e\n\nA task management Model Context Protocol (MCP) server for planning and executing tasks with AI assistants.\n\n\u003ca href=\"https://glama.ai/mcp/servers/@pinkpixel-dev/taskflow-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@pinkpixel-dev/taskflow-mcp/badge\" alt=\"TaskFlow MCP server\" /\u003e\n\u003c/a\u003e\n\n![Version](https://img.shields.io/badge/version-1.2.1-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n## 🌟 Overview\n\nTaskFlow 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.\n\n## ✨ Features\n\n- 📋 **Task Planning**: Break down complex requests into manageable tasks\n- 🔍 **Subtasks**: Divide tasks into smaller, more manageable subtasks\n- 📊 **Progress Tracking**: Track the status of tasks, subtasks, and requests with visual progress tables\n- 👍 **User Approval**: Enforce user approval steps to ensure quality and control\n- 💾 **Persistence**: Save tasks and requests to disk for persistence across sessions\n- 🔄 **Flexible Management**: Add, update, or delete tasks and subtasks as needed\n- 📝 **Detailed Reporting**: View task details and progress tables\n- 📤 **Export Options**: Export task plans and status reports in Markdown, JSON, or HTML formats\n- 📦 **Dependencies**: Track project and task-level dependencies with version information\n- 📌 **Notes**: Add project-level notes for important information and preferences\n\n## 🚀 Installation\n\n### Global Installation\n\n```bash\nnpm install -g @pinkpixel/taskflow-mcp\n```\n\n### Local Installation\n\n```bash\nnpm install @pinkpixel/taskflow-mcp\n```\n\n## 🛠️ Usage\n\n### Starting the Server\n\nIf installed globally:\n\n```bash\ntaskflow-mcp\n```\n\nIf installed locally:\n\n```bash\nnpx taskflow-mcp\n```\n\n### Configuration\n\nBy default, TaskFlow MCP saves tasks to `~/Documents/tasks.json`. You can change this by setting the `TASK_MANAGER_FILE_PATH` environment variable:\n\n```bash\nTASK_MANAGER_FILE_PATH=/path/to/tasks.json taskflow-mcp\n```\n\n### MCP Configuration\n\nTo 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"taskflow\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pinkpixel/taskflow-mcp\"],\n      \"env\": {\n        \"TASK_MANAGER_FILE_PATH\": \"/path/to/tasks.json\"\n      }\n    }\n  }\n}\n```\n\n## 🔄 Workflow\n\nTaskFlow MCP enforces a specific workflow:\n\n1. **Plan Tasks**: Break down a user request into tasks (with optional subtasks)\n2. **Get Next Task**: Retrieve the next pending task\n3. **Complete Subtasks**: If the task has subtasks, complete each subtask before marking the task as done\n4. **Mark Task Done**: Mark a task as completed (requires all subtasks to be completed first)\n5. **Wait for Approval**: Wait for user approval of the completed task\n6. **Repeat**: Continue with the next task until all tasks are complete\n7. **Final Approval**: Get user approval for the entire request\n\nFor AI assistants to consistently follow this workflow, see the [example-system-prompt.md](./example-system-prompt.md) file for system prompts you can add to your assistant's instructions.\n\n## 🧰 Available Tools\n\nTaskFlow MCP exposes the following tools to AI assistants:\n\n### `plan_task`\n\nRegister a new user request and plan its associated tasks (with optional subtasks).\n\n```json\n{\n  \"originalRequest\": \"Create a new website for my business\",\n  \"outputPath\": \"C:/Users/username/Documents/website-project-plan.md\",\n  \"dependencies\": [\n    {\n      \"name\": \"Node.js\",\n      \"version\": \"\u003e=14.0.0\",\n      \"description\": \"JavaScript runtime\"\n    },\n    {\n      \"name\": \"npm\",\n      \"version\": \"\u003e=6.0.0\",\n      \"description\": \"Package manager\"\n    }\n  ],\n  \"notes\": [\n    {\n      \"title\": \"Package Manager Preference\",\n      \"content\": \"User prefers pnpm over npm for package management.\"\n    },\n    {\n      \"title\": \"Design Guidelines\",\n      \"content\": \"Follow the company's brand guidelines for colors and typography.\"\n    }\n  ],\n  \"tasks\": [\n    {\n      \"title\": \"Design homepage\",\n      \"description\": \"Create a design for the homepage with logo, navigation, and hero section\",\n      \"dependencies\": [\n        {\n          \"name\": \"Figma\",\n          \"description\": \"Design tool\"\n        }\n      ],\n      \"subtasks\": [\n        {\n          \"title\": \"Design logo\",\n          \"description\": \"Create a logo that represents the business brand\"\n        },\n        {\n          \"title\": \"Design navigation\",\n          \"description\": \"Create a user-friendly navigation menu\"\n        }\n      ]\n    },\n    {\n      \"title\": \"Implement HTML/CSS\",\n      \"description\": \"Convert the design to HTML and CSS\",\n      \"dependencies\": [\n        {\n          \"name\": \"HTML5\",\n          \"description\": \"Markup language\"\n        },\n        {\n          \"name\": \"CSS3\",\n          \"description\": \"Styling language\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### `get_next_task`\n\nRetrieve the next pending task for a request.\n\n```json\n{\n  \"requestId\": \"req-1\"\n}\n```\n\n### `mark_task_done`\n\nMark a task as completed.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\",\n  \"completedDetails\": \"Created a modern design with a clean layout\"\n}\n```\n\n### `approve_task_completion`\n\nApprove a completed task.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\"\n}\n```\n\n### `approve_request_completion`\n\nApprove an entire request as completed.\n\n```json\n{\n  \"requestId\": \"req-1\"\n}\n```\n\n### `open_task_details`\n\nGet details about a specific task.\n\n```json\n{\n  \"taskId\": \"task-1\"\n}\n```\n\n### `list_requests`\n\nList all requests in the system.\n\n```json\n{}\n```\n\n### `add_tasks_to_request`\n\nAdd more tasks to an existing request.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"tasks\": [\n    {\n      \"title\": \"Add contact form\",\n      \"description\": \"Create a contact form with validation\"\n    }\n  ]\n}\n```\n\n### `update_task`\n\nUpdate a task's title or description.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\",\n  \"title\": \"Design responsive homepage\",\n  \"description\": \"Create a responsive design for the homepage\"\n}\n```\n\n### `delete_task`\n\nDelete a task from a request.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\"\n}\n```\n\n### `add_subtasks`\n\nAdd subtasks to an existing task.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\",\n  \"subtasks\": [\n    {\n      \"title\": \"Design logo\",\n      \"description\": \"Create a logo that represents the business brand\"\n    },\n    {\n      \"title\": \"Design navigation\",\n      \"description\": \"Create a user-friendly navigation menu\"\n    }\n  ]\n}\n```\n\n### `mark_subtask_done`\n\nMark a subtask as completed.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\",\n  \"subtaskId\": \"subtask-1\"\n}\n```\n\n### `update_subtask`\n\nUpdate a subtask's title or description.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\",\n  \"subtaskId\": \"subtask-1\",\n  \"title\": \"Design modern logo\",\n  \"description\": \"Create a modern logo that represents the business brand\"\n}\n```\n\n### `delete_subtask`\n\nDelete a subtask from a task.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\",\n  \"subtaskId\": \"subtask-1\"\n}\n```\n\n### `export_task_status`\n\nExport the current status of all tasks in a request to a file. It's recommended to use absolute paths for more reliable file creation.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"outputPath\": \"C:/Users/username/Documents/task-status.md\",\n  \"format\": \"markdown\"\n}\n```\n\n### `add_note`\n\nAdd a note to a request.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"title\": \"Package Manager Preference\",\n  \"content\": \"User prefers pnpm over npm for package management.\"\n}\n```\n\n### `update_note`\n\nUpdate an existing note.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"noteId\": \"note-1\",\n  \"title\": \"Package Manager Preference\",\n  \"content\": \"User prefers pnpm over npm and yarn for package management.\"\n}\n```\n\n### `delete_note`\n\nDelete a note from a request.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"noteId\": \"note-1\"\n}\n```\n\n### `add_dependency`\n\nAdd a dependency to a request or task.\n\n```json\n{\n  \"requestId\": \"req-1\",\n  \"taskId\": \"task-1\",\n  \"dependency\": {\n    \"name\": \"react\",\n    \"version\": \"^18.2.0\",\n    \"description\": \"JavaScript library for building user interfaces\",\n    \"url\": \"https://reactjs.org\"\n  }\n}\n```\n\n## 📚 Documentation\n\nFor more detailed information about the project architecture and implementation, see the [OVERVIEW.md](./OVERVIEW.md) file.\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) file for guidelines.\n\n## 📜 Changelog\n\nSee the [CHANGELOG.md](./CHANGELOG.md) file for a history of changes to this project.\n\n## 🙏 Acknowledgements\n\n- Built with [Model Context Protocol (MCP)](https://github.com/anthropics/model-context-protocol)\n- Created by [Pink Pixel](https://pinkpixel.dev)\n\n---\n\nMade with ❤️ by Pink Pixel","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Ftaskflow-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinkpixel-dev%2Ftaskflow-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Ftaskflow-mcp/lists"}