MCPlanManager - AI Agent Task Management System

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

🚀 Quick Start (Recommended Method)

We strongly recommend using uvx to run MCPlanManager. uvx allows you to start the MCP service with one command, automatically handling dependency management and environment setup, ensuring you are always using the latest version and avoiding complex dependency conflicts. This approach also lays the foundation for seamless deployment across various hosting platforms.

1. Prerequisites: Install uv

If uv is not yet installed on your system, please execute the following command (this only needs to be done once):

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

Windows:
powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, please restart your terminal or open a new terminal window.

2. Configure Your AI Client

In the settings of MCP-supported clients like Cursor, Continue.dev, etc., add a new MCP server with the following configuration:

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

After restarting the client, the MCPlanManager tools will be available. No need to manually install dependencies or configure the Python environment! uvx intelligently downloads and runs the service from PyPI. For hosting platforms that support uvx, simply set the startup command to uvx mcplanmanager to achieve automated deployment and elastic scaling.

📚 Alternative: Using Virtual Environments and pip

If you prefer not to install uv, you can use a traditional Python virtual environment.

1. Create and activate the virtual environment
   bash
   python3 -m venv ~/.mcplanmanager-env
   source ~/.mcplanmanager-env/bin/activate # macOS / Linux

   .\mcplanmanager-env\Scripts\activate # Windows

2. Install the package
   bash
   pip install mcplanmanager

3. Configure the AI client
   You need to tell the client the specific path to the mcplanmanager command.
   json
   {
   "mcpServers": {
   "mcplanmanager": {
   // Note: The path here should be the absolute path in your virtual environment
   // Example: "/Users/yourname/.mcplanmanager-env/bin/mcplanmanager"
   "command": "<path_to_your_env>/bin/mcplanmanager"
   }
   }
   }

🛠️ Available MCP Tools

After successful installation and configuration, 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 formats)
• generateContextPrompt - Generate context prompt

📝 Development and Contribution

Local Development

bash

Clone the repository

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

Create a virtual environment and install development dependencies

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Run tests

pytest tests/

📄 License

MIT License - See LICENSE file for details.