Mcplanmanager

🚀 MCPlanManager - AI Agent Task Management System

A concise and efficient task manager designed specifically for long-range task execution of AI Agents. It supports the MCP (Model Context Protocol) standard and offers two deployment methods: uvx and Docker.

✨ Features

Highlights of Version 1.2.0 Update:

• New Plan Persistence Tools: Introduced dumpPlan and loadPlan tools, allowing for complete export and restoration of task plans.
• Optimized Tool Documentation: Added parameter structure descriptions for tools using Pydantic models (e.g., initializePlan, editDependencies) to improve compatibility with some clients.
• Enhanced Test Suite: Added comprehensive test cases for the persistence feature and optimized the test execution process.

🚀 Quick Start

We offer two recommended deployment methods. Please choose according to your needs.

Method 1: Using uvx (Lightweight & Quick Startup)

uvx enables you to start the MCP service with a single command. It automatically handles dependency management and environment setup.

1. Prerequisite: Install uv If uv is not installed on your system, run the following command to install it:

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

2. Configure Your AI Client In clients such as Cursor and Continue.dev, use the following configuration to automatically download and run the service (communicate via standard input and output):

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

Method 2: Using Docker (Production Environment & Isolated Deployment)

Docker provides the best environment consistency and isolation, making it the preferred choice for production environment deployment. The service will run in SSE (Server-Sent Events) mode.

1. Pull or Build the Image Pull the latest image from Docker Hub:

   docker pull donway19/mcplanmanager:latest
   

   Or build the image locally in the project root directory:

   docker-compose build
   

2. Run the Container You can start the service using either docker run or docker-compose.

   Using docker run:

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

   Using docker-compose (Recommended): The docker-compose.yml file in the project root directory is already configured for you:

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

   Then run docker-compose up -d.

3. Configure Your AI Client Use the following configuration to connect to the service running in the Docker container via SSE:

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

   Note: If deploying on a cloud server, replace localhost with the public IP address or domain name of the server.

🧪 Running Tests

We provide a complete test suite to ensure code quality.

1. Start the Service Make sure your MCP service is running (either via uvx or Docker).

2. Run All Tests Execute the following command in the project root directory:

   # It is recommended to test the Docker deployment in SSE mode
   python test/run_all_tests.py --mode sse
   
   # Or test the local service in uvx mode
   # python test/run_all_tests.py --mode uvx
   

   This script will automatically run all functional tests and boundary case tests and output a detailed report.

🛠️ MCP Tool List

This project provides the following 15 tools:

• initializePlan: Initialize a new task plan.
• loadPlan: Load and replace the current plan from a complete plan object.
• dumpPlan: Export the current complete plan data as a dictionary object.
• 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.
• addTask: Add a new task to the plan.
• getTaskList: Get the task list (supports status filtering).
• getExecutableTaskList: Get the list of currently executable tasks.
• getPlanStatus: Get the status of the entire plan.
• editDependencies: Modify the dependencies between tasks.
• visualizeDependencies: Generate a visualization of dependencies (supports ascii, tree, mermaid formats).
• generateContextPrompt: Generate a context prompt.

🧑‍💻 Local Development

If you wish to contribute code or perform secondary development, please follow these steps:

1. Clone the repository and set up the environment

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

2. Perform local debugging in Cursor To enable hot-reload debugging where code changes take effect immediately, point the mcp.server.configFiles setting in Cursor to the examples/mcp_configs/local_development.json file in the project. This file is already configured with the environment variables required for local development.

   After starting Cursor, you can use @mcplanmanager-local-dev in the chat window to call and test your latest local code.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.