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
  7The server provides six essential planning tools:
  8
  9- **`set_goal`**: Set the initial goal for your planning session (title and description required). Returns error if goal already exists.
 10- **`change_goal`**: Change an existing goal with a required reason for the change. Only used when operator explicitly requests clearing/changing the goal.
 11- **`add_tasks`**: Add one or more tasks to work on. Break tasks down into the smallest units of work possible and track progress. Each task requires a title (and optional description).
 12- **`get_tasks`**: Get task list with optional status filtering and indicators. Call frequently to stay organized.
 13- **`update_task_statuses`**: Update the status of one or more tasks. Maintain your planning workflow by updating statuses regularly.
 14- **`delete_tasks`**: Delete one or more tasks by their IDs and return the updated task list. Only use if the operator explicitly requests clearing the board.
 15
 16## Installation
 17
 18```bash
 19go build -o planning-mcp-server ./cmd/planning-mcp-server
 20```
 21
 22## Configuration
 23
 24Generate an example configuration file:
 25
 26```bash
 27./planning-mcp-server --generate-config
 28```
 29
 30This creates `planning-mcp-server.toml` with default settings:
 31
 32```toml
 33[server]
 34mode = 'stdio'  # or 'http'
 35host = 'localhost'
 36port = 8080
 37
 38[logging]
 39level = 'info'  # debug, info, warn, error
 40format = 'text'  # text, json
 41
 42[planning]
 43max_tasks = 100
 44max_goal_length = 1000
 45max_task_length = 500
 46history_enabled = true
 47```
 48
 49## Usage
 50
 51### STDIO Mode (Default)
 52
 53For use with MCP clients like Claude Desktop:
 54
 55```bash
 56./planning-mcp-server --mode stdio
 57```
 58
 59### HTTP Mode
 60
 61For web-based integrations:
 62
 63```bash
 64./planning-mcp-server --mode http --port 8080
 65```
 66
 67### CLI Options
 68
 69```bash
 70./planning-mcp-server --help
 71```
 72
 73- `--config, -c`: Configuration file path
 74- `--mode, -m`: Server mode (stdio or http)
 75- `--port, -p`: HTTP server port
 76- `--host`: HTTP server host
 77- `--log-level`: Log level (debug, info, warn, error)
 78- `--generate-config`: Generate example configuration
 79- `--version, -v`: Show version
 80
 81## How your AI assistant uses this
 82
 83### Setting Goals
 84
 85Your AI assistant can establish clear objectives that stay visible throughout the current planning session, helping maintain focus on the overall purpose.
 86
 87### Planning Tasks
 88
 89When the agent first adds tasks to an empty planning session, the tool provides guidance and shows your complete plan:
 90
 91- Adds the tasks to the planning session
 92- Shows helpful instructions for getting started
 93- Displays the goal and current task list with status indicators
 94
 95When adding tasks to an existing planning session, the tool keeps things brief:
 96
 97- Adds tasks seamlessly
 98- Shows the updated task list (same format as `get_tasks`)
 99- No repetitive instructions - just the updated plan
100
101### Tracking Progress
102
103The LLM gets a clear view of all tasks with visual status indicators. It uses Unicode characters for statuses because they each count as one token, while Markdown checkboxes and other representations take up multiple tokens.
104The task list includes a legend showing the status indicators. The failed icon (☒) and cancelled icon (⊗) are only shown in the legend if there are actually failed or cancelled tasks in the list.
105
106```
107**Goal:** Create a comprehensive MCP server for task planning and management
108
109Legend: ☐ pending  ⟳ in progress  ☑ completed
110☐ Set up project structure [a1b2c3d4]
111  Create Go module, directories, and basic files
112☐ Implement core planning logic [e5f6g7h8]
113  Create Goal and Task data structures with deterministic IDs
114☐ Build MCP server integration [i9j0k1l2]
115```
116
117## Task IDs
118
119Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
120
121- Same task content always gets the same ID within a session
122- No collisions for different tasks
123- Consistent references during the current session
124
125## Data Storage
126
127**Important**: This server currently uses in-memory storage only. All goals and tasks are lost when the server restarts. Session management and persistence are planned for future releases.
128
129## License
130
131AGPL-3.0-or-later