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## What This Gives Your AI Assistant
6
7This MCP server enables your AI assistant to:
8
9- **Set clear goals** for complex tasks and keep them visible throughout the session
10- **Break down work** into manageable, trackable tasks with progress indicators
11- **Stay organized** with structured task lists during the current session
12- **Track progress** with visual status indicators (☐ pending, ⟳ in progress, ☑ completed, ☒ failed)
13- **Adapt plans** by adding tasks, updating status, and pivoting when needed
14
15## Core Capabilities
16
17The server provides six essential planning tools:
18
19- **`project_management__set_goal`**: Set the initial goal for your planning session (title and description required)
20- **`project_management__change_goal`**: Change an existing goal with a required reason for the change
21- **`project_management__add_tasks`**: Add one or more tasks to work on. Break tasks down into the smallest units of work possible and track progress.
22- **`project_management__get_tasks`**: Get task list with optional status filtering and indicators. Call frequently to stay organized.
23- **`project_management__update_task_statuses`**: Update the status of one or more tasks. Maintain your planning workflow by updating statuses regularly.
24- **`project_management__delete_tasks`**: Delete one or more tasks by their IDs and return the updated task list.
25
26## Installation
27
28```bash
29go build -o planning-mcp-server ./cmd/planning-mcp-server
30```
31
32## Configuration
33
34Generate an example configuration file:
35
36```bash
37./planning-mcp-server --generate-config
38```
39
40This creates `planning-mcp-server.toml` with default settings:
41
42```toml
43[server]
44mode = 'stdio' # or 'http'
45host = 'localhost'
46port = 8080
47
48[logging]
49level = 'info' # debug, info, warn, error
50format = 'text' # text, json
51
52[planning]
53max_tasks = 100
54max_goal_length = 1000
55max_task_length = 500
56history_enabled = true
57```
58
59## Usage
60
61### STDIO Mode (Default)
62
63For use with MCP clients like Claude Desktop:
64
65```bash
66./planning-mcp-server --mode stdio
67```
68
69### HTTP Mode
70
71For web-based integrations:
72
73```bash
74./planning-mcp-server --mode http --port 8080
75```
76
77### CLI Options
78
79```bash
80./planning-mcp-server --help
81```
82
83- `--config, -c`: Configuration file path
84- `--mode, -m`: Server mode (stdio or http)
85- `--port, -p`: HTTP server port
86- `--host`: HTTP server host
87- `--log-level`: Log level (debug, info, warn, error)
88- `--generate-config`: Generate example configuration
89- `--version, -v`: Show version
90
91## How Your AI Assistant Uses This
92
93### Setting Goals
94
95Your AI assistant can establish clear objectives that stay visible throughout the current planning session, helping maintain focus on the overall purpose.
96
97### Planning Tasks
98
99When you first add tasks to an empty planning session, the tool provides guidance and shows your complete plan:
100
101- Adds your tasks to the planning session
102- Shows helpful instructions for getting started
103- Displays your goal and current task list with status indicators
104
105When adding tasks to an existing planning session, the tool keeps things brief:
106
107- Adds your tasks seamlessly
108- Shows your updated task list (same format as `project_management__get_tasks`)
109- No repetitive instructions - just your updated plan
110
111### Tracking Progress
112
113Your AI assistant gets a clear view of all tasks with visual status indicators:
114
115```
116**Goal:** Create a comprehensive MCP server for task planning and management
117
118Legend: ☐ pending ⟳ in progress ☑ completed
119☐ Set up project structure [a1b2c3d4]
120 Create Go module, directories, and basic files
121☐ Implement core planning logic [e5f6g7h8]
122 Create Goal and Task data structures with deterministic IDs
123☐ Build MCP server integration [i9j0k1l2]
124```
125
126### Updating Status
127
128As work progresses, your AI assistant can update task statuses and immediately see the updated plan with all changes reflected.
129
130## Task Status Indicators
131
132- ☐ **pending**: Task is ready to be worked on
133- ⟳ **in_progress**: Task is currently being worked on
134- ☑ **completed**: Task has been finished successfully
135- ☒ **failed**: Task encountered an error or failed
136- ⊗ **cancelled**: Task was cancelled and won't be completed
137
138The 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.
139
140## Task IDs
141
142Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
143
144- Same task content always gets the same ID within a session
145- No collisions for different tasks
146- Consistent references during the current session
147
148## Data Storage
149
150**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.
151
152## License
153
154AGPL-3.0-or-later
155
156## Author
157
158Amolith <amolith@secluded.site>