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 seven 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- **`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.
21- **`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.
22
23## Installation
24
25```bash
26# Download and build using the go tool
27go install git.secluded.site/planning-mcp-server/cmd/planning-mcp-server@main
28
29# Build from the cloned source code
30git clone https://git.secluded.site/planning-mcp-server.git
31cd planning-mcp-server
32go build -o planning-mcp-server ./cmd/planning-mcp-server
33mv planning-mcp-server ~/.local/bin # assuming ~/.local/bin is in your shell's PATH
34```
35
36## Configuration
37
38Generate an example configuration file (optional):
39
40```bash
41planning-mcp-server --generate-config
42```
43
44This creates `planning-mcp-server.toml` with default settings:
45
46```toml
47[server]
48mode = 'stdio' # or 'http'
49host = 'localhost'
50port = 8080
51
52[logging]
53level = 'info' # debug, info, warn, error
54format = 'text' # text, json
55
56[planning]
57max_tasks = 100
58max_goal_length = 1000
59max_task_length = 500
60history_enabled = true
61```
62
63## Usage
64
65### STDIO Mode (Default)
66
67For use with MCP clients like Claude Desktop:
68
69```bash
70planning-mcp-server --mode stdio
71```
72
73### HTTP Mode
74
75For web-based integrations:
76
77```bash
78planning-mcp-server --mode http --port 8080
79```
80
81### CLI Options
82
83```bash
84planning-mcp-server --help
85```
86
87- `--config, -c`: Configuration file path
88- `--mode, -m`: Server mode (stdio or http)
89- `--port, -p`: HTTP server port
90- `--host`: HTTP server host
91- `--log-level`: Log level (debug, info, warn, error)
92- `--generate-config`: Generate example configuration
93- `--version, -v`: Show version
94
95## How your AI assistant uses this
96
97### Setting Goals
98
99Your AI assistant can establish clear objectives that stay visible throughout the current planning session, helping maintain focus on the overall purpose.
100
101### Planning Tasks
102
103When the agent first adds tasks to an empty planning session, the tool provides guidance and shows your complete plan:
104
105- Adds the tasks to the planning session
106- Shows helpful instructions for getting started
107- Displays the goal and current task list with status indicators
108
109When adding tasks to an existing planning session, the tool keeps things brief:
110
111- Adds tasks seamlessly
112- Shows the updated task list (same format as `get_tasks`)
113- No repetitive instructions - just the updated plan
114
115### Tracking Progress
116
117The 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.
118The 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.
119
120```
121**Goal:** Create a comprehensive MCP server for task planning and management
122
123Legend: ☐ pending ⟳ in progress ☑ completed
124☐ Set up project structure [a1b2c3d4]
125 Create Go module, directories, and basic files
126☐ Implement core planning logic [e5f6g7h8]
127 Create Goal and Task data structures with deterministic IDs
128☐ Build MCP server integration [i9j0k1l2]
129```
130
131## Task IDs
132
133Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
134
135- Same task content always gets the same ID within a session
136- No collisions for different tasks
137- Consistent references during the current session
138- When modifying tasks, IDs are regenerated to reflect the new content
139
140## Data Storage
141
142**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.
143
144
145## Collaboration
146
147Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
148new account to contribute, you don't need to fork this repo, you don't need to
149fiddle with `git send-email`, you don't need to faff with your email client to
150get `git request-pull` working...
151
152You just need:
153
154- Git
155- SSH
156- An SSH key
157
158```sh
159# Clone this repo, make your changes, and commit them
160# Create a new patch request with
161git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
162# After potential feedback, submit a revision to an existing patch request with
163git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
164# List patch requests
165ssh pr.pico.sh pr list amolith/llm-projects
166```
167
168See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
169complete example workflow.
170
171[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
172[pr.pico.sh]: https://pr.pico.sh
173
174## License
175
176AGPL-3.0-or-later