MCPlanManager - AI Agent 任务管理系统
一个简洁高效的任务管理器，专为 AI Agent 的长程任务执行而设计，支持MCP (Model Context Protocol) 标准。
🎯 核心特性
- 简洁的JSON结构: 最小化复杂度，使用简单的依赖ID数组
- 完整的工具函数集: 涵盖任务生命周期的所有操作
- 循环依赖检测: 自动防止无效的依赖关系
- 可视化支持: 提供多种依赖关系可视化方式（ASCII、树形、Mermaid）
- 智能Prompt生成: 自动生成上下文感知的执行指导
- MCP标准支持: 兼容各种支持MCP的AI客户端
- 灵活的部署方式: 支持多种安装和配置方式
📁 项目结构
MCPlanManager/
├── mcplanmanager/ # 核心Python包
│ ├── __init__.py
│ ├── plan_manager.py # 核心PlanManager类
│ ├── dependency_tools.py # 可视化和Prompt工具
│ ├── mcp_wrapper.py # MCP服务包装器
│ └── mcp_server.py # MCP服务器实现
├── docs/ # 文档
│ ├── design.md
│ ├── plan_manager_design.md
│ └── DEPLOYMENT_GUIDE.md
├── tests/ # 测试文件
│ ├── test_deployment.py
│ ├── test_new_initialization.py
│ └── example_usage.py
├── examples/ # 示例文件
│ ├── example_plan.json
│ └── mcp_configs/ # MCP客户端配置
│ ├── cursor.json # Cursor IDE配置
│ ├── claude_desktop.json # Claude Desktop配置
│ ├── github_deployment.json # GitHub配置
│ ├── local_development.json # 本地开发配置
│ └── modelscope_deployment.json # 魔搭平台配置
├── server/ # HTTP服务器
│ └── api_server.py
├── setup.py # 安装配置
├── requirements.txt # 依赖文件
├── LICENSE # MIT许可证
└── README.md # 本文档
🚀 安装方法
推荐方式：源码安装
# 克隆仓库
git clone https://github.com/donway19/MCPlanManager.git
cd MCPlanManager
# 使用pip基于pyproject.toml安装
pip install .
直接从GitHub安装
pip install git+https://github.com/donway19/MCPlanManager.git
🔧 MCP客户端配置
Cursor IDE
- 安装依赖:
# 使用uv包管理器（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv ~/.mcpenv
uv pip install --directory ~/.mcpenv git+https://github.com/donway19/MCPlanManager.git
- 配置Cursor:
- 打开Cursor设置 → Extensions → MCP
- 添加以下配置到
mcp_servers.json:
{
"mcpServers": {
"mcplanmanager": {
"command": "uv",
"args": ["--directory", "~/.mcpenv", "run", "mcplanmanager"],
"env": {
"UV_PROJECT_ENVIRONMENT": "~/.mcpenv"
}
}
}
}
- 验证安装: 重启Cursor，在Chat中应该能看到MCPlanManager工具可用。
Claude Desktop
- 安装依赖:
pip install git+https://github.com/donway19/MCPlanManager.git
- 配置Claude Desktop:
- 找到Claude Desktop配置文件:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/claude/claude_desktop_config.json
- 添加以下配置:
{
"mcpServers": {
"mcplanmanager": {
"command": "python",
"args": ["-m", "mcplanmanager.mcp_wrapper"],
"env": {}
}
}
}
- 重启Claude Desktop使配置生效。
Continue.dev
- 安装依赖:
pip install git+https://github.com/donway19/MCPlanManager.git
- 配置Continue:
- 编辑
~/.continue/config.json - 添加MCP服务器配置:
{
"mcpServers": [
{
"name": "mcplanmanager",
"command": "python",
"args": ["-m", "mcplanmanager.mcp_wrapper"]
}
]
}
自定义MCP客户端
对于其他支持MCP的客户端，使用以下通用配置模板：
{
"name": "mcplanmanager",
"command": "python",
"args": ["-m", "mcplanmanager.mcp_server"],
"env": {},
"capabilities": {
"tools": true,
"resources": false,
"prompts": false
}
}
🛠️ 可用的MCP工具
安装配置成功后，您可以使用以下12个工具：
基础任务管理
initializePlan - 初始化新的任务计划getCurrentTask - 获取当前正在执行的任务startNextTask - 开始下一个可执行的任务completeTask - 标记任务为完成状态failTask - 标记任务失败skipTask - 跳过指定任务
任务操作
addTask - 添加新任务到计划中getTaskList - 获取任务列表（支持状态过滤）getExecutableTaskList - 获取当前可执行的任务列表getPlanStatus - 获取整个计划的状态
可视化和辅助
visualizeDependencies - 生成依赖关系可视化（ASCII、树形、Mermaid格式）generateContextPrompt - 生成上下文感知的执行提示词
💡 使用示例
基本用法 (MCP模式)
MCPlanManager专为AI模型设计，模型只需要提供业务内容，技术字段由工具自动维护：
AI模型只需要提供：
goal: 计划目标tasks: 任务列表，每个任务包含：name: 任务名称 reasoning: 执行理由dependencies: 依赖的任务（任务名称列表或索引列表）
工具自动维护：
id: 从1开始自动分配status: 初始为"pending"result: 初始为Nonecreated_at/updated_at: 自动设置时间戳
MCP客户端中的对话示例
用户: 帮我创建一个网上购物的任务计划
AI: 我来为您创建一个网上购物任务计划。
> 使用工具: initializePlan
> 参数: {
> "goal": "完成网上购物流程",
> "tasks": [
> {
> "name": "浏览商品",
> "reasoning": "查看可用商品和价格",
> "dependencies": []
> },
> {
> "name": "选择商品",
> "reasoning": "确定要购买的商品",
> "dependencies": ["浏览商品"]
> },
> {
> "name": "添加到购物车",
> "reasoning": "将选中的商品加入购物车",
> "dependencies": ["选择商品"]
> },
> {
> "name": "填写收货信息",
> "reasoning": "提供配送地址和联系方式",
> "dependencies": ["添加到购物车"]
> },
> {
> "name": "选择支付方式",
> "reasoning": "选择合适的支付方式",
> "dependencies": ["填写收货信息"]
> },
> {
> "name": "确认订单",
> "reasoning": "最终确认购买",
> "dependencies": ["选择支付方式"]
> }
> ]
> }
计划已创建！包含6个任务，任务间有明确的依赖关系。
用户: 开始执行第一个任务
AI: 好的，我来开始执行第一个任务。
> 使用工具: startNextTask
已开始执行任务1：浏览商品
理由：查看可用商品和价格
编程使用示例
from mcplanmanager import PlanManager
# 初始化计划管理器
pm = PlanManager("my_plan.json")
# 创建任务计划
tasks = [
{
"name": "数据收集",
"reasoning": "收集分析所需的数据",
"dependencies": []
},
{
"name": "数据清洗",
"reasoning": "清理和预处理数据",
"dependencies": ["数据收集"]
},
{
"name": "数据分析",
"reasoning": "执行数据分析",
"dependencies": ["数据清洗"]
}
]
# 初始化计划
result = pm.initializePlan("数据分析项目", tasks)
# 开始执行任务
current_task = pm.startNextTask()
print(f"当前任务: {current_task['name']}")
# 完成任务
pm.completeTask(current_task['id'], "数据收集完成")
# 查看计划状态
status = pm.getPlanStatus()
print(f"计划进度: {status['progress']:.1%}")
🔍 依赖关系可视化
MCPlanManager支持多种可视化格式：
# ASCII格式
pm.visualizeDependencies("ascii")
# 树形格式
pm.visualizeDependencies("tree")
# Mermaid格式（可在支持的工具中渲染）
pm.visualizeDependencies("mermaid")
📊 任务状态管理
支持的任务状态：
- pending: 等待执行
- in_progress: 正在执行
- completed: 已完成
- failed: 执行失败
- skipped: 已跳过
🛡️ 错误处理
MCPlanManager具有完整的错误处理机制：
- 自动检测循环依赖
- 验证任务依赖关系
- 提供详细的错误信息
- 支持任务重试机制
📝 开发和贡献
本地开发
# 克隆仓库
git clone https://github.com/donway19/MCPlanManager.git
cd MCPlanManager
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或 venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest tests/
测试MCP服务器
# 直接运行MCP服务器
python -m mcplanmanager.mcp_server
# 或使用包装器
python -m mcplanmanager.mcp_wrapper getCurrentTask
📄 许可证
MIT License - 详见 LICENSE 文件
📞 联系和支持
🎯 版本历史
- v1.0.0: 初始版本
- 完整的MCP支持
- 12个核心工具函数
- 多种可视化格式
- 完善的错误处理
MCPlanManager - 让AI Agent的任务管理变得简单高效！