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