taskflow

TaskFlow MCP is a dedicated server for planning, organizing, and tracking user requests as structured tasks and subtasks, with robust persistence and user approval checkpoints. It guides AI assistants through a disciplined workflow: plan a request into tasks, fetch the next pending task, handle subtasks, await user confirmation when appropriate, and repeat until completion. The server provides tools to plan tasks, manage subtasks, and export or archive completed work for history preservation. You can also configure a YAML or JSON task file, browse archives, and restore archived work as needed. Typical usage involves integrating TaskFlow MCP with your AI agent so it can generate, update, and monitor a task plan in a consistent, auditable format.

Key capabilities include: planning tasks via plan_task, managing and tracking subtasks, persisting data to disk, exporting task plans and status reports in Markdown, JSON, or HTML, and an archive system to keep active work tidy while preserving history. The workflow emphasizes user approval steps to maintain control and quality, and supports relative/absolute file paths for flexible project setups. Depending on your configuration, you can enable YAML persistence for multiline content and leverage prompts to standardize LLM guidance across tasks.

Prerequisites:

• Node.js (LTS version recommended) and npm installed on your system
• Basic familiarity with MCP configuration and JSON/YAML files

Installation steps:

1. Install the TaskFlow MCP package globally (recommended for quick start):

npm install -g @pinkpixel/taskflow-mcp

2. Alternatively, install locally in your project and use npx:

npm install @pinkpixel/taskflow-mcp

3. Start the server (if installed globally):

taskflow-mcp

Or, if installed locally, use:

npx taskflow-mcp

4. Create an MCP configuration file (mcp_config.json) to register the server under MCP:

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

5. Run the server with your configuration as part of your MCP client, or point your client at the server using the mcp_config.json you created.

6. Optional: customize persistence and archive settings by adjusting TASK_MANAGER_FILE_PATH, ARCHIVE_FILE_PATH, ARCHIVE_MODE, and related environment variables as described in the README.

Notes and tips:

• The server saves tasks to disk by default (configurable via TASK_MANAGER_FILE_PATH). Use YAML format by giving a .yaml/.yml extension to enable YAML persistence for multiline content, otherwise JSON is used.
• You can control archiving behavior with ARCHIVE_FILE_PATH and ARCHIVE_MODE (manual or auto-on-complete).
• For cross-platform use, the server handles path normalization across Windows and Linux and will create necessary parent directories when saving task files.
• If you plan to run in production, set absolute paths for file storage and consider running under a process manager (e.g., systemd, PM2) for resilience.
• The available tools include plan_task, list_archived_requests, restore_archived_request, and export options (Markdown, JSON, HTML) for reporting. Ensure your MCP client is configured to call these tools according to your workflow.