TaskFlow MCP 🔄✅

TaskFlow MCP 🔄✅

用于规划和执行任务的任务管理 Model Context Protocol（MCP）服务，可与 AI 助手配合使用。

🌟 概述

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 现在支持全局提示词系统，可增强大模型在各项任务中的专注度和一致性。此功能旨在满足用户反馈中提出的自定义指令以及任务前缀/后缀需求。

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 文件。

🤝 参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 文件了解指南。

📜 更新日志

请参阅 CHANGELOG.md 文件，了解本项目的更改历史。

🙏 致谢

• 基于 Model Context Protocol（MCP） 构建
• 由 Pink Pixel 创建

---

Pink Pixel 倾情打造 ❤️