1# planning-mcp-server
  2
  3A Model Context Protocol (MCP) server that provides planning tools for LLMs to thoroughly plan their actions before getting started and pivot during execution when needed.
  4
  5## What This Gives Your AI Assistant
  6
  7This MCP server enables your AI assistant to:
  8
  9- **Set clear goals** for complex tasks and keep them visible throughout the work
 10- **Break down work** into manageable, trackable tasks with progress indicators  
 11- **Stay organized** with persistent task lists that survive across conversations
 12- **Track progress** with visual status indicators (☐ pending, ⟳ in progress, ☑ completed, ☒ failed)
 13- **Adapt plans** by adding tasks, updating status, and pivoting when needed
 14
 15## Core Capabilities
 16
 17The server provides five essential planning tools:
 18
 19- **`update_goal`**: Set or update the overarching goal for your planning session
 20- **`add_tasks`**: Add one or more tasks to work on. Break tasks down into the smallest units of work possible and track progress.
 21- **`get_tasks`**: Get current task list with status indicators and legend. Call frequently to stay organized.
 22- **`update_tasks`**: Update the status of one or more tasks. Maintain your planning workflow by updating statuses regularly.
 23- **`delete_tasks`**: Delete one or more tasks by their IDs and return the updated task list.
 24
 25## Installation
 26
 27```bash
 28go build -o planning-mcp-server ./cmd/planning-mcp-server
 29```
 30
 31## Configuration
 32
 33Generate an example configuration file:
 34
 35```bash
 36./planning-mcp-server --generate-config
 37```
 38
 39This creates `planning-mcp-server.toml` with default settings:
 40
 41```toml
 42[server]
 43mode = 'stdio'  # or 'http'
 44host = 'localhost'
 45port = 8080
 46
 47[logging]
 48level = 'info'  # debug, info, warn, error
 49format = 'text'  # text, json
 50
 51[planning]
 52max_tasks = 100
 53max_goal_length = 1000
 54max_task_length = 500
 55history_enabled = true
 56```
 57
 58## Usage
 59
 60### STDIO Mode (Default)
 61
 62For use with MCP clients like Claude Desktop:
 63
 64```bash
 65./planning-mcp-server --mode stdio
 66```
 67
 68### HTTP Mode
 69
 70For web-based integrations:
 71
 72```bash
 73./planning-mcp-server --mode http --port 8080
 74```
 75
 76### CLI Options
 77
 78```bash
 79./planning-mcp-server --help
 80```
 81
 82- `--config, -c`: Configuration file path
 83- `--mode, -m`: Server mode (stdio or http)
 84- `--port, -p`: HTTP server port
 85- `--host`: HTTP server host
 86- `--log-level`: Log level (debug, info, warn, error)
 87- `--generate-config`: Generate example configuration
 88- `--version, -v`: Show version
 89
 90## How Your AI Assistant Uses This
 91
 92### Setting Goals
 93
 94Your AI assistant can establish clear objectives that stay visible throughout the planning session, helping maintain focus on the overall purpose.
 95
 96### Planning Tasks
 97
 98When you first add tasks to an empty planning session, the tool provides guidance and shows your complete plan:
 99
100- Adds your tasks to the planning session
101- Shows helpful instructions for getting started
102- Displays your goal and current task list with status indicators
103
104When adding tasks to an existing planning session, the tool keeps things brief:
105
106- Adds your tasks seamlessly 
107- Shows your updated task list (same format as `get_tasks`)
108- No repetitive instructions - just your updated plan
109
110### Tracking Progress
111
112Your AI assistant gets a clear view of all tasks with visual status indicators:
113
114```
115**Goal:** Create a comprehensive MCP server for task planning and management
116
117Legend: ☐ pending  ⟳ in progress  ☑ completed
118☐ Set up project structure [a1b2c3d4]
119  Create Go module, directories, and basic files
120☐ Implement core planning logic [e5f6g7h8]
121  Create Goal and Task data structures with deterministic IDs
122☐ Build MCP server integration [i9j0k1l2]
123```
124
125### Updating Status
126
127As work progresses, your AI assistant can update task statuses and immediately see the updated plan with all changes reflected.
128
129## Task Status Indicators
130
131- ☐ **pending**: Task is ready to be worked on
132- ⟳ **in_progress**: Task is currently being worked on  
133- ☑ **completed**: Task has been finished successfully
134- ☒ **failed**: Task encountered an error or failed
135
136The task list includes a legend showing the status indicators. The failed icon (☒) is only shown in the legend if there are actually failed tasks in the list.
137
138## Task IDs
139
140Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
141
142- Same task content always gets the same ID
143- No collisions for different tasks
144- Consistent references across sessions
145
146## License
147
148AGPL-3.0-or-later
149
150## Author
151
152Amolith <amolith@secluded.site>