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## Features
6
7The server provides four core tools that constitute a comprehensive planning workflow:
8
9- **`update_goal`**: Set or update the overarching goal for your planning session
10- **`add_tasks`**: Add one or more tasks to work on
11- **`get_tasks`**: Get current task list with status indicators and legend
12- **`update_task_status`**: Update the status of a specific task
13
14## Installation
15
16```bash
17go build -o planning-mcp-server ./cmd/planning-mcp-server
18```
19
20## Configuration
21
22Generate an example configuration file:
23
24```bash
25./planning-mcp-server --generate-config
26```
27
28This creates `planning-mcp-server.toml` with default settings:
29
30```toml
31[server]
32mode = 'stdio' # or 'http'
33host = 'localhost'
34port = 8080
35
36[logging]
37level = 'info' # debug, info, warn, error
38format = 'text' # text, json
39
40[planning]
41max_tasks = 100
42max_goal_length = 1000
43max_task_length = 500
44history_enabled = true
45```
46
47## Usage
48
49### STDIO Mode (Default)
50
51For use with MCP clients like Claude Desktop:
52
53```bash
54./planning-mcp-server --mode stdio
55```
56
57### HTTP Mode
58
59For web-based integrations:
60
61```bash
62./planning-mcp-server --mode http --port 8080
63```
64
65### CLI Options
66
67```bash
68./planning-mcp-server --help
69```
70
71- `--config, -c`: Configuration file path
72- `--mode, -m`: Server mode (stdio or http)
73- `--port, -p`: HTTP server port
74- `--host`: HTTP server host
75- `--log-level`: Log level (debug, info, warn, error)
76- `--generate-config`: Generate example configuration
77- `--version, -v`: Show version
78
79## Tool Examples
80
81### Setting a Goal
82
83```json
84{
85 "name": "update_goal",
86 "arguments": {
87 "goal": "Create a comprehensive MCP server for task planning and management"
88 }
89}
90```
91
92Response: `Goal "Create a comprehensive MCP server for task planning and management" saved! You probably want to add one or more tasks now.`
93
94### Adding Tasks
95
96```json
97{
98 "name": "add_tasks",
99 "arguments": {
100 "tasks": [
101 {
102 "title": "Set up project structure",
103 "description": "Create Go module, directories, and basic files"
104 },
105 {
106 "title": "Implement core planning logic",
107 "description": "Create Goal and Task data structures with deterministic IDs"
108 },
109 {
110 "title": "Build MCP server integration"
111 }
112 ]
113 }
114}
115```
116
117Response: `Tasks added successfully! Get started on your first one once you're ready, and call get_tasks frequently to remind yourself where you are in the process. Reminder that your overarching goal is "Create a comprehensive MCP server for task planning and management".`
118
119### Getting Task Status
120
121```json
122{
123 "name": "get_tasks",
124 "arguments": {}
125}
126```
127
128Response:
129```
130**Goal:** Create a comprehensive MCP server for task planning and management
131
132Legend: ☐ pending ⟳ in progress ☑ completed
133☐ Set up project structure [a1b2c3d4]
134 Create Go module, directories, and basic files
135☐ Implement core planning logic [e5f6g7h8]
136 Create Goal and Task data structures with deterministic IDs
137☐ Build MCP server integration [i9j0k1l2]
138```
139
140### Updating Task Status
141
142```json
143{
144 "name": "update_task_status",
145 "arguments": {
146 "task_id": "a1b2c3d4",
147 "status": "completed"
148 }
149}
150```
151
152Response:
153```
154**Goal:** Create a comprehensive MCP server for task planning and management
155
156Legend: ☐ pending ⟳ in progress ☑ completed
157☑ Set up project structure [a1b2c3d4]
158 Create Go module, directories, and basic files
159⟳ Implement core planning logic [e5f6g7h8]
160 Create Goal and Task data structures with deterministic IDs
161☐ Build MCP server integration [i9j0k1l2]
162```
163
164## Task Status Indicators
165
166- ☐ **pending**: Task is ready to be worked on
167- ⟳ **in_progress**: Task is currently being worked on
168- ☑ **completed**: Task has been finished successfully
169- ☒ **failed**: Task encountered an error or failed
170
171The 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.
172
173## Task IDs
174
175Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
176
177- Same task content always gets the same ID
178- No collisions for different tasks
179- Consistent references across sessions
180
181## License
182
183AGPL-3.0-or-later
184
185## Author
186
187Amolith <amolith@secluded.site>