MCPlanManager - AI Agent Task Management System

A concise and efficient task manager designed for long-term task execution by AI Agents, supporting the MCP (Model Context Protocol) standard.

🎯 Core Features

• Simplified JSON Structure: Minimizes complexity with a simple array of dependency IDs
• Comprehensive Set of Utility Functions: Covers all operations throughout the task lifecycle
• Circular Dependency Detection: Automatically prevents invalid dependency relationships
• Visualization Support: Offers multiple ways to visualize dependencies (ASCII, tree, Mermaid)
• Intelligent Prompt Generation: Automatically generates context-aware execution guidance
• MCP Standard Support: Compatible with various MCP-supported AI clients
• Flexible Deployment Options: Supports multiple installation and configuration methods

📁 Project Structure

MCPlanManager/
├── mcplanmanager/ # Core Python package
│ ├── init.py
│ ├── plan_manager.py # Core PlanManager class
│ ├── dependency_tools.py # Visualization and prompt tools
│ ├── mcp_wrapper.py # MCP service wrapper
│ └── mcp_server.py # MCP server implementation
├── docs/ # Documentation
│ ├── design.md
│ ├── plan_manager_design.md
│ └── DEPLOYMENT_GUIDE.md
├── tests/ # Test files
│ ├── test_deployment.py
│ ├── test_new_initialization.py
│ └── example_usage.py
├── examples/ # Example files
│ ├── example_plan.json
│ └── mcp_configs/ # MCP client configurations
│ ├── cursor.json # Cursor IDE configuration
│ ├── claude_desktop.json # Claude Desktop configuration
│ ├── github_deployment.json # GitHub configuration
│ ├── local_development.json # Local development configuration
│ └── modelscope_deployment.json # ModelScope platform configuration
├── server/ # HTTP server
│ └── api_server.py
├── setup.py # Installation configuration
├── requirements.txt # Dependency file
├── LICENSE # MIT license
└── README.md # This document

🚀 Installation Methods

Recommended: Source Code Installation

bash

Clone the repository

git clone https://github.com/donway19/MCPlanManager.git
cd MCPlanManager

Install using pip based on pyproject.toml

pip install .

Directly from GitHub

bash
pip install git+https://github.com/donway19/MCPlanManager.git

🔧 MCP Client Configuration

Cursor IDE

1. Install Dependencies:
   bash

Using uv package manager (recommended)

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv ~/.mcpenv
uv pip install --directory ~/.mcpenv git+https://github.com/donway19/MCPlanManager.git

1. Configure Cursor:
   • Open Cursor settings → Extensions → MCP
   • Add the following configuration to mcp_servers.json:

json
{
"mcpServers": {
"mcplanmanager": {
"command": "uv",
"args": ["--directory", "~/.mcpenv", "run", "mcplanmanager"],
"env": {
"UV_PROJECT_ENVIRONMENT": "~/.mcpenv"
}
}
}
}

1. Verify Installation: Restart Cursor; you should see the MCPlanManager tool available in Chat.

Claude Desktop

1. Install Dependencies:
   bash
   pip install git+https://github.com/donway19/MCPlanManager.git

2. Configure Claude Desktop:

   • Locate the Claude Desktop configuration file:
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json
     • Linux: ~/.config/claude/claude_desktop_config.json
   • Add the following configuration:

json
{
"mcpServers": {
"mcplanmanager": {
"command": "python",
"args": ["-m", "mcplanmanager.mcp_wrapper"],
"env": {}
}
}
}

1. Restart Claude Desktop to apply the configuration.

Continue.dev

1. Install Dependencies:
   bash
   pip install git+https://github.com/donway19/MCPlanManager.git

2. Configure Continue:

   • Edit ~/.continue/config.json
   • Add the MCP server configuration:

json
{
"mcpServers": [
{
"name": "mcplanmanager",
"command": "python",
"args": ["-m", "mcplanmanager.mcp_wrapper"]
}
]
}### Custom MCP Client

For other MCP-supported clients, use the following general configuration template:

json
{
"name": "mcplanmanager",
"command": "python",
"args": ["-m", "mcplanmanager.mcp_server"],
"env": {},
"capabilities": {
"tools": true,
"resources": false,
"prompts": false
}
}

🛠️ Available MCP Tools

After successfully installing and configuring, you can use the following 12 tools:

Basic Task Management

• initializePlan - Initialize a new task plan
• getCurrentTask - Get the currently executing task
• startNextTask - Start the next executable task
• completeTask - Mark a task as completed
• failTask - Mark a task as failed
• skipTask - Skip a specified task

Task Operations

• addTask - Add a new task to the plan
• getTaskList - Get the list of tasks (supports status filtering)
• getExecutableTaskList - Get the list of currently executable tasks
• getPlanStatus - Get the status of the entire plan

Visualization and Assistance

• visualizeDependencies - Generate dependency visualization (ASCII, tree, Mermaid format)
• generateContextPrompt - Generate context-aware execution prompts

💡 Usage Examples

Basic Usage (MCP Mode)

MCPlanManager is designed specifically for AI models, where the model only needs to provide business content, and technical fields are automatically maintained by the tool:

AI model only needs to provide:

• goal: The goal of the plan
• tasks: A list of tasks, each containing:
  • name: Task name
  • reasoning: Reason for execution
  • dependencies: Dependent tasks (list of task names or indices)

Fields automatically maintained by the tool:

• id: Automatically assigned starting from 1
• status: Initially set to "pending"
• result: Initially set to None
• created_at/updated_at: Timestamps are automatically set

Example Conversation in MCP Client

User: Help me create a task plan for online shopping.

AI: I will create an online shopping task plan for you.

Tool used: initializePlan
Parameters: {
"goal": "Complete the online shopping process",
"tasks": [
{
"name": "Browse products",
"reasoning": "View available products and prices",
"dependencies": []
},
{
"name": "Select product",
"reasoning": "Determine the product to purchase",
"dependencies": ["Browse products"]
},
{
"name": "Add to cart",
"reasoning": "Add the selected product to the cart",
"dependencies": ["Select product"]
},
{
"name": "Fill in delivery information",
"reasoning": "Provide delivery address and contact information",
"dependencies": ["Add to cart"]
},
{
"name": "Choose payment method",
"reasoning": "Select an appropriate payment method",
"dependencies": ["Fill in delivery information"]
},
{
"name": "Confirm order",
"reasoning": "Final confirmation of purchase",
"dependencies": ["Choose payment method"]
}
]
}

The plan has been created! It includes 6 tasks with clear dependencies.

User: Start executing the first task.

AI: Alright, I will start executing the first task.

Tool used: startNextTask

Task 1 has started: Browse products
Reason: View available products and prices

Programming Usage Example

python
from mcplanmanager import PlanManager

Initialize the plan manager

pm = PlanManager("my_plan.json")

Create a task plan

tasks = [
{
"name": "Data collection",
"reasoning": "Collect data needed for analysis",
"dependencies": []
},
{
"name": "Data cleaning",
"reasoning": "Clean and preprocess the data",
"dependencies": ["Data collection"]
},
{
"name": "Data analysis",
"reasoning": "Perform data analysis",
"dependencies": ["Data cleaning"]
}
]

Initialize the plan

result = pm.initializePlan("Data analysis project", tasks)

Start executing tasks

current_task = pm.startNextTask()
print(f"Current task: {current_task['name']}")

Complete the task

pm.completeTask(current_task['id'], "Data collection completed")

Check the plan status

status = pm.getPlanStatus()
print(f"Plan progress: {status['progress']:.1%}")## 🔍 Dependency Visualization

MCPlanManager supports multiple visualization formats:

python

ASCII format

pm.visualizeDependencies("ascii")

Tree format

pm.visualizeDependencies("tree")

Mermaid format (renderable in supported tools)

pm.visualizeDependencies("mermaid")

📊 Task Status Management

Supported task statuses:

• pending: Awaiting execution
• in_progress: In progress
• completed: Completed
• failed: Execution failed
• skipped: Skipped

🛡️ Error Handling

MCPlanManager has a comprehensive error handling mechanism:

• Automatic detection of circular dependencies
• Validation of task dependencies
• Provision of detailed error messages
• Support for task retry mechanisms

📝 Development and Contribution

Local Development

bash

Clone the repository

git clone https://github.com/donway19/MCPlanManager.git
cd MCPlanManager

Create a virtual environment

python -m venv venv
source venv/bin/activate # Linux/Mac

or venv\Scripts\activate # Windows

Install development dependencies

pip install -e ".[dev]"

Run tests

pytest tests/

Testing MCP Server

bash

Run the MCP server directly

python -m mcplanmanager.mcp_server

Or use the wrapper

python -m mcplanmanager.mcp_wrapper getCurrentTask

📄 License

MIT License - see LICENSE file for details

📞 Contact and Support

• Author: Donwaydoom
• Email: Donwaydoom@gmail.com
• GitHub: https://github.com/donway19/MCPlanManager
• Issues: https://github.com/donway19/MCPlanManager/issues

🎯 Version History

• v1.0.0: Initial release
  • Full MCP support
  • 12 core utility functions
  • Multiple visualization formats
  • Robust error handling

---

MCPlanManager - Making task management for AI Agents simple and efficient!