Mcplanmanager

🚀 MCPlanManager - AI Agent 任务管理系统

MCPlanManager 是一个简洁高效的任务管理器，专为 AI Agent 的长程任务执行而设计。它支持 MCP (Model Context Protocol) 标准，同时提供 uvx 和 Docker 两种部署方式，能满足不同场景的需求。

✨ 主要特性

版本 1.2.0 更新亮点：

• 新增计划持久化工具：引入 dumpPlan 和 loadPlan 工具，可对任务计划进行完整的导出和恢复。
• 优化工具文档：为使用 Pydantic 模型的工具（如 initializePlan, editDependencies）补充了参数结构描述，提升部分客户端的兼容性。
• 增强测试套件：添加了针对持久化功能的完整测试用例，并优化了测试运行流程。

🚀 快速开始

我们提供两种推荐的部署方式，请根据您的需求选择。

📦 安装指南

方式一：使用 uvx (轻量级 & 快速启动)

uvx 允许您以一行命令轻松启动 MCP 服务，它会自动处理依赖管理和环境设置。

1. 先决条件：安装 uv 如果您的系统中还没有 uv，请先执行以下命令安装：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 配置您的AI客户端 在 Cursor、Continue.dev 等客户端中，使用以下配置即可自动下载并运行服务（通过标准输入输出进行通信）：

   {
     "mcpServers": {
       "mcplanmanager": {
         "command": "uvx",
         "args": ["mcplanmanager"]
       }
     }
   }
   

方式二：使用 Docker (生产环境 & 隔离部署)

Docker 提供了最佳的环境一致性和隔离性，是生产环境部署的首选方案。服务将以 SSE (Server-Sent Events) 模式运行。

1. 拉取或构建镜像 从 Docker Hub 拉取最新镜像：

   docker pull donway19/mcplanmanager:latest
   

   或者在项目根目录本地构建：

   docker-compose build
   

2. 运行容器 您可以通过 docker run 或 docker-compose 来启动服务。 使用 docker run:

   docker run -d --name mcplanmanager_service -p 8080:8080 donway19/mcplanmanager:latest
   

   使用 docker-compose (推荐): 项目根目录下的 docker-compose.yml 文件已为您配置好：

   services:
     mcplanmanager:
       build: .
       container_name: mcplanmanager_service
       ports:
         - "8080:8080"
       restart: unless-stopped
   

   然后运行 docker-compose up -d。
3. 配置您的AI客户端 使用以下配置通过 SSE 连接到 Docker 容器中运行的服务：

   {
     "mcpServers": {
       "mcplanmanager-docker": {
         "transport": "sse",
         "url": "http://localhost:8080/sse"
       }
     }
   }
   

   ⚠️ 重要提示

   如果部署在云服务器上，请将 localhost 替换为服务器的公网 IP 或域名。

🧪 运行测试

我们提供了一套完整的测试套件来保证代码质量。

1. 启动服务 确保您的 MCP 服务正在运行（通过 uvx 或 Docker）。
2. 运行所有测试 在项目根目录执行以下命令：

   # 推荐使用 SSE 模式测试 Docker 部署
   python test/run_all_tests.py --mode sse
   
   # 或者使用 uvx 模式测试本地服务
   # python test/run_all_tests.py --mode uvx
   

   该脚本会自动运行所有功能测试和边界情况测试，并输出详细报告。

💻 使用示例

基础用法

MCPlanManager 提供了丰富的工具来管理任务计划，以下是部分工具的使用示例：

# 初始化新的任务计划
initializePlan()

# 添加新任务到计划中
addTask(new_task)

# 开始下一个可执行的任务
startNextTask()

📚 详细文档

🛠️ MCP 工具列表

本项目提供以下 15 个工具：

• initializePlan：初始化新的任务计划
• loadPlan：从一个完整的计划对象加载并替换当前计划
• dumpPlan：导出当前完整的计划数据为一个字典对象
• getCurrentTask：获取当前正在执行的任务
• startNextTask：开始下一个可执行的任务
• completeTask：标记任务为完成状态
• failTask：标记任务失败
• skipTask：跳过指定任务
• addTask：添加新任务到计划中
• getTaskList：获取任务列表（支持状态过滤）
• getExecutableTaskList：获取当前可执行的任务列表
• getPlanStatus：获取整个计划的状态
• editDependencies：修改任务间的依赖关系
• visualizeDependencies：生成依赖关系可视化（支持 ascii, tree, mermaid 格式）
• generateContextPrompt：生成上下文提示词

🧑‍💻 本地开发

如果您希望贡献代码或进行二次开发，请遵循以下步骤：

1. 克隆仓库并设置环境

   git clone https://github.com/donway19/MCPlanManager.git
   cd MCPlanManager
   uv venv
   source .venv/bin/activate
   uv pip install -e .
   

2. 在 Cursor 中进行本地调试 为了实现修改代码后实时生效的热重载调试，请在 Cursor 的 mcp.server.configFiles 设置中指向项目中的 examples/mcp_configs/local_development.json 文件。该文件已为您配置好了本地开发所需的环境变量。 启动 Cursor 后，您就可以在聊天窗口中使用 @mcplanmanager-local-dev 来调用和测试您本地的最新代码了。

📄 许可证

本项目基于 MIT License - 详见 LICENSE 文件。