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. Break tasks down into the smallest units of work possible and track progress.
11- **`get_tasks`**: Get current task list with status indicators and legend. Call frequently to stay organized.
12- **`update_task_status`**: Update the status of a specific task. Maintain your planning workflow by updating statuses regularly.
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
96When you first add tasks to an empty planning session, the tool provides guidance and shows your complete plan:
97
98- Adds your tasks to the planning session
99- Shows helpful instructions for getting started
100- Displays your goal and current task list with status indicators
101
102When adding tasks to an existing planning session, the tool keeps things brief:
103
104- Adds your tasks seamlessly
105- Shows your updated task list (same format as `get_tasks`)
106- No repetitive instructions - just your updated plan
107
108### Getting Task Status
109
110```json
111{
112 "name": "get_tasks",
113 "arguments": {}
114}
115```
116
117Response:
118```
119**Goal:** Create a comprehensive MCP server for task planning and management
120
121Legend: ☐ pending ⟳ in progress ☑ completed
122☐ Set up project structure [a1b2c3d4]
123 Create Go module, directories, and basic files
124☐ Implement core planning logic [e5f6g7h8]
125 Create Goal and Task data structures with deterministic IDs
126☐ Build MCP server integration [i9j0k1l2]
127```
128
129### Updating Task Status
130
131```json
132{
133 "name": "update_task_status",
134 "arguments": {
135 "task_id": "a1b2c3d4",
136 "status": "completed"
137 }
138}
139```
140
141Response:
142```
143**Goal:** Create a comprehensive MCP server for task planning and management
144
145Legend: ☐ pending ⟳ in progress ☑ completed
146☑ Set up project structure [a1b2c3d4]
147 Create Go module, directories, and basic files
148⟳ Implement core planning logic [e5f6g7h8]
149 Create Goal and Task data structures with deterministic IDs
150☐ Build MCP server integration [i9j0k1l2]
151```
152
153## Task Status Indicators
154
155- ☐ **pending**: Task is ready to be worked on
156- ⟳ **in_progress**: Task is currently being worked on
157- ☑ **completed**: Task has been finished successfully
158- ☒ **failed**: Task encountered an error or failed
159
160The 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.
161
162## Task IDs
163
164Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
165
166- Same task content always gets the same ID
167- No collisions for different tasks
168- Consistent references across sessions
169
170## License
171
172AGPL-3.0-or-later
173
174## Author
175
176Amolith <amolith@secluded.site>