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 文件。