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
 26go build -o planning-mcp-server ./cmd/planning-mcp-server
 27```
 28
 29## Configuration
 30
 31Generate an example configuration file:
 32
 33```bash
 34./planning-mcp-server --generate-config
 35```
 36
 37This creates `planning-mcp-server.toml` with default settings:
 38
 39```toml
 40[server]
 41mode = 'stdio'  # or 'http'
 42host = 'localhost'
 43port = 8080
 44
 45[logging]
 46level = 'info'  # debug, info, warn, error
 47format = 'text'  # text, json
 48
 49[planning]
 50max_tasks = 100
 51max_goal_length = 1000
 52max_task_length = 500
 53history_enabled = true
 54```
 55
 56## Usage
 57
 58### STDIO Mode (Default)
 59
 60For use with MCP clients like Claude Desktop:
 61
 62```bash
 63./planning-mcp-server --mode stdio
 64```
 65
 66### HTTP Mode
 67
 68For web-based integrations:
 69
 70```bash
 71./planning-mcp-server --mode http --port 8080
 72```
 73
 74### CLI Options
 75
 76```bash
 77./planning-mcp-server --help
 78```
 79
 80- `--config, -c`: Configuration file path
 81- `--mode, -m`: Server mode (stdio or http)
 82- `--port, -p`: HTTP server port
 83- `--host`: HTTP server host
 84- `--log-level`: Log level (debug, info, warn, error)
 85- `--generate-config`: Generate example configuration
 86- `--version, -v`: Show version
 87
 88## How your AI assistant uses this
 89
 90### Setting Goals
 91
 92Your AI assistant can establish clear objectives that stay visible throughout the current planning session, helping maintain focus on the overall purpose.
 93
 94### Planning Tasks
 95
 96When the agent first adds tasks to an empty planning session, the tool provides guidance and shows your complete plan:
 97
 98- Adds the tasks to the planning session
 99- Shows helpful instructions for getting started
100- Displays the 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 tasks seamlessly
105- Shows the updated task list (same format as `get_tasks`)
106- No repetitive instructions - just the updated plan
107
108### Tracking Progress
109
110The 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.
111The 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.
112
113```
114**Goal:** Create a comprehensive MCP server for task planning and management
115
116Legend: ☐ pending  ⟳ in progress  ☑ completed
117☐ Set up project structure [a1b2c3d4]
118  Create Go module, directories, and basic files
119☐ Implement core planning logic [e5f6g7h8]
120  Create Goal and Task data structures with deterministic IDs
121☐ Build MCP server integration [i9j0k1l2]
122```
123
124## Task IDs
125
126Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
127
128- Same task content always gets the same ID within a session
129- No collisions for different tasks
130- Consistent references during the current session
131- When modifying tasks, IDs are regenerated to reflect the new content
132
133## Data Storage
134
135**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.
136
137## License
138
139AGPL-3.0-or-later