1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7This entire project, including the README below, was largely written by LLMs.
  8It works well enough, but I'm experiencing an odd issue in my preferred coding
  9tool where the server seems to die and the coding tool restarts the server,
 10wiping the in-memory-only tasks. I could fix that by implementing persistent
 11storage, but I'm more interested in seeing how LLMs work with a completely
 12different implementation of this idea. I don't intend to maintain this server
 13going forward, though it should continue to function until/unless the MCP
 14protocol changes.
 15
 16I wrote [formatted-commit](https://git.secluded.site/formatted-commit), a CLI
 17tool, to encourage (and force) LLMs towards well-formatted Conventional Commits
 18and that's the kind of style I want to try for the next version of this
 19"LLM-oriented planning system" idea. It's called, for now, [nasin
 20pali](https://git.secluded.site/nasin-pali).
 21
 22---
 23
 24# planning-mcp-server
 25
 26A 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.
 27
 28## What this gives your AI assistant
 29
 30The server provides seven essential planning tools:
 31
 32- **`set_goal`**: Set the initial goal for your planning session (title and description required). Returns error if goal already exists.
 33- **`change_goal`**: Change an existing goal with a required reason for the change. Only used when operator explicitly requests clearing/changing the goal.
 34- **`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).
 35- **`get_tasks`**: Get task list with optional status filtering and indicators. Call frequently to stay organized.
 36- **`update_task_statuses`**: Update the status of one or more tasks. Maintain your planning workflow by updating statuses regularly.
 37- **`modify_task`**: Modify the title and/or description of a task. ID and at least one of title/description are required. When one or the other is omitted, that field will not be modified.
 38- **`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.
 39
 40## Installation
 41
 42```bash
 43# Download and build using the go tool
 44go install git.secluded.site/planning-mcp-server/cmd/planning-mcp-server@main
 45
 46# Build from the cloned source code
 47git clone https://git.secluded.site/planning-mcp-server.git
 48cd planning-mcp-server
 49go build -o planning-mcp-server ./cmd/planning-mcp-server
 50mv planning-mcp-server ~/.local/bin # assuming ~/.local/bin is in your shell's PATH
 51```
 52
 53## Configuration
 54
 55Generate an example configuration file (optional):
 56
 57```bash
 58planning-mcp-server --generate-config
 59```
 60
 61This creates `planning-mcp-server.toml` with default settings:
 62
 63```toml
 64[server]
 65mode = 'stdio'  # or 'http'
 66host = 'localhost'
 67port = 8080
 68
 69[logging]
 70level = 'info'  # debug, info, warn, error
 71format = 'text'  # text, json
 72
 73[planning]
 74max_tasks = 100
 75max_goal_length = 1000
 76max_task_length = 500
 77history_enabled = true
 78```
 79
 80## Usage
 81
 82### STDIO Mode (Default)
 83
 84For use with MCP clients like Claude Desktop:
 85
 86```bash
 87planning-mcp-server --mode stdio
 88```
 89
 90### HTTP Mode
 91
 92For web-based integrations:
 93
 94```bash
 95planning-mcp-server --mode http --port 8080
 96```
 97
 98### CLI Options
 99
100```bash
101planning-mcp-server --help
102```
103
104- `--config, -c`: Configuration file path
105- `--mode, -m`: Server mode (stdio or http)
106- `--port, -p`: HTTP server port
107- `--host`: HTTP server host
108- `--log-level`: Log level (debug, info, warn, error)
109- `--generate-config`: Generate example configuration
110- `--version, -v`: Show version
111
112## How your AI assistant uses this
113
114### Setting Goals
115
116Your AI assistant can establish clear objectives that stay visible throughout the current planning session, helping maintain focus on the overall purpose.
117
118### Planning Tasks
119
120When the agent first adds tasks to an empty planning session, the tool provides guidance and shows your complete plan:
121
122- Adds the tasks to the planning session
123- Shows helpful instructions for getting started
124- Displays the goal and current task list with status indicators
125
126When adding tasks to an existing planning session, the tool keeps things brief:
127
128- Adds tasks seamlessly
129- Shows the updated task list (same format as `get_tasks`)
130- No repetitive instructions - just the updated plan
131
132### Tracking Progress
133
134The 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.
135The 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.
136
137```
138**Goal:** Create a comprehensive MCP server for task planning and management
139
140Legend: ☐ pending  ⟳ in progress  ☑ completed
141☐ Set up project structure [a1b2c3d4]
142  Create Go module, directories, and basic files
143☐ Implement core planning logic [e5f6g7h8]
144  Create Goal and Task data structures with deterministic IDs
145☐ Build MCP server integration [i9j0k1l2]
146```
147
148## Task IDs
149
150Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
151
152- Same task content always gets the same ID within a session
153- No collisions for different tasks
154- Consistent references during the current session
155- When modifying tasks, IDs are regenerated to reflect the new content
156
157## Data Storage
158
159**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.
160
161
162## Collaboration
163
164Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
165new account to contribute, you don't need to fork this repo, you don't need to
166fiddle with `git send-email`, you don't need to faff with your email client to
167get `git request-pull` working...
168
169You just need:
170
171- Git
172- SSH
173- An SSH key
174
175```sh
176# Clone this repo, make your changes, and commit them
177# Create a new patch request with
178git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
179# After potential feedback, submit a revision to an existing patch request with
180git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
181# List patch requests
182ssh pr.pico.sh pr list amolith/llm-projects
183```
184
185See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
186complete example workflow.
187
188[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
189[pr.pico.sh]: https://pr.pico.sh
190
191## License
192
193AGPL-3.0-or-later