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 four 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
 24## Installation
 25
 26```bash
 27go build -o planning-mcp-server ./cmd/planning-mcp-server
 28```
 29
 30## Configuration
 31
 32Generate an example configuration file:
 33
 34```bash
 35./planning-mcp-server --generate-config
 36```
 37
 38This creates `planning-mcp-server.toml` with default settings:
 39
 40```toml
 41[server]
 42mode = 'stdio'  # or 'http'
 43host = 'localhost'
 44port = 8080
 45
 46[logging]
 47level = 'info'  # debug, info, warn, error
 48format = 'text'  # text, json
 49
 50[planning]
 51max_tasks = 100
 52max_goal_length = 1000
 53max_task_length = 500
 54history_enabled = true
 55```
 56
 57## Usage
 58
 59### STDIO Mode (Default)
 60
 61For use with MCP clients like Claude Desktop:
 62
 63```bash
 64./planning-mcp-server --mode stdio
 65```
 66
 67### HTTP Mode
 68
 69For web-based integrations:
 70
 71```bash
 72./planning-mcp-server --mode http --port 8080
 73```
 74
 75### CLI Options
 76
 77```bash
 78./planning-mcp-server --help
 79```
 80
 81- `--config, -c`: Configuration file path
 82- `--mode, -m`: Server mode (stdio or http)
 83- `--port, -p`: HTTP server port
 84- `--host`: HTTP server host
 85- `--log-level`: Log level (debug, info, warn, error)
 86- `--generate-config`: Generate example configuration
 87- `--version, -v`: Show version
 88
 89## How Your AI Assistant Uses This
 90
 91### Setting Goals
 92
 93Your AI assistant can establish clear objectives that stay visible throughout the planning session, helping maintain focus on the overall purpose.
 94
 95### Planning Tasks
 96
 97When you first add tasks to an empty planning session, the tool provides guidance and shows your complete plan:
 98
 99- Adds your tasks to the planning session
100- Shows helpful instructions for getting started
101- Displays your goal and current task list with status indicators
102
103When adding tasks to an existing planning session, the tool keeps things brief:
104
105- Adds your tasks seamlessly 
106- Shows your updated task list (same format as `get_tasks`)
107- No repetitive instructions - just your updated plan
108
109### Tracking Progress
110
111Your AI assistant gets a clear view of all tasks with visual status indicators:
112
113```
114**Goal:** Create a comprehensive MCP server for task planning and management
115
116Legend: ☐ pending  ⟳ in progress  ☑ completed
117☐ Set up project structure [a1b2c3d4]
118  Create Go module, directories, and basic files
119☐ Implement core planning logic [e5f6g7h8]
120  Create Goal and Task data structures with deterministic IDs
121☐ Build MCP server integration [i9j0k1l2]
122```
123
124### Updating Status
125
126As work progresses, your AI assistant can update task statuses and immediately see the updated plan with all changes reflected.
127
128## Task Status Indicators
129
130- ☐ **pending**: Task is ready to be worked on
131- ⟳ **in_progress**: Task is currently being worked on  
132- ☑ **completed**: Task has been finished successfully
133- ☒ **failed**: Task encountered an error or failed
134
135The 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.
136
137## Task IDs
138
139Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
140
141- Same task content always gets the same ID
142- No collisions for different tasks
143- Consistent references across sessions
144
145## License
146
147AGPL-3.0-or-later
148
149## Author
150
151Amolith <amolith@secluded.site>