@@ -2,6 +2,17 @@
This file provides guidance to AI coding assistants when working with code in this repository.
+## planning-mcp-server capabilities
+
+The server provides six essential planning tools:
+
+- **`set_goal`**: Set the initial goal for your planning session (title and description required). Returns error if goal already exists.
+- **`change_goal`**: Change an existing goal with a required reason for the change. Only used when operator explicitly requests clearing/changing the goal.
+- **`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).
+- **`get_tasks`**: Get task list with optional status filtering and indicators. Call frequently to stay organized.
+- **`update_task_statuses`**: Update the status of one or more tasks. Maintain your planning workflow by updating statuses regularly.
+- **`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.
+
## Development Commands
This project uses `just` as the build tool. Essential commands:
@@ -63,6 +74,8 @@ The project requires license headers (SPDX format) on all source files and uses
**Task List Legend**: The `get_tasks()` method includes a legend showing status indicators. The legend format is "Legend: ☐ pending ⟳ in progress ☑ completed" and only includes the cancelled icon (⊗) and failed icon (☒) if there are actually cancelled or failed tasks in the current list.
+The server uses in-memory storage only. All goals and tasks are lost when the server restarts. Session management and persistence are planned for future releases.
+
### MCP Tool Implementation
The server exposes six MCP tools that map directly to planning manager methods:
@@ -119,6 +132,8 @@ Note: Test files (`*_test.go`) will be added in future releases to ensure robust
**Current Storage Model**: In-memory storage only - all data is lost on server restart. Session management and persistence are planned for future releases to enable task continuity across sessions.
+The server uses Unicode characters for statuses because they each count as one token, while Markdown checkboxes and other representations take up multiple tokens.
+
**Deterministic IDs**: Task IDs must remain consistent. Never change the ID generation algorithm without migration strategy.
**MCP Compliance**: All tool responses must follow MCP schema. Responses include both success messages and full task lists where appropriate.
@@ -2,26 +2,16 @@
A 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.
-## What This Gives Your AI Assistant
-
-This MCP server enables your AI assistant to:
-
-- **Set clear goals** for complex tasks and keep them visible throughout the session
-- **Break down work** into manageable, trackable tasks with progress indicators
-- **Stay organized** with structured task lists during the current session
-- **Track progress** with visual status indicators (☐ pending, ⟳ in progress, ☑ completed, ☒ failed)
-- **Adapt plans** by adding tasks, updating status, and pivoting when needed
-
-## Core Capabilities
+## What this gives your AI assistant
The server provides six essential planning tools:
-- **`set_goal`**: Set the initial goal for your planning session (title and description required)
-- **`change_goal`**: Change an existing goal with a required reason for the change
-- **`add_tasks`**: Add one or more tasks to work on. Break tasks down into the smallest units of work possible and track progress.
+- **`set_goal`**: Set the initial goal for your planning session (title and description required). Returns error if goal already exists.
+- **`change_goal`**: Change an existing goal with a required reason for the change. Only used when operator explicitly requests clearing/changing the goal.
+- **`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).
- **`get_tasks`**: Get task list with optional status filtering and indicators. Call frequently to stay organized.
- **`update_task_statuses`**: Update the status of one or more tasks. Maintain your planning workflow by updating statuses regularly.
-- **`delete_tasks`**: Delete one or more tasks by their IDs and return the updated task list.
+- **`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.
## Installation
@@ -88,7 +78,7 @@ For web-based integrations:
- `--generate-config`: Generate example configuration
- `--version, -v`: Show version
-## How Your AI Assistant Uses This
+## How your AI assistant uses this
### Setting Goals
@@ -96,21 +86,22 @@ Your AI assistant can establish clear objectives that stay visible throughout th
### Planning Tasks
-When you first add tasks to an empty planning session, the tool provides guidance and shows your complete plan:
+When the agent first adds tasks to an empty planning session, the tool provides guidance and shows your complete plan:
-- Adds your tasks to the planning session
+- Adds the tasks to the planning session
- Shows helpful instructions for getting started
-- Displays your goal and current task list with status indicators
+- Displays the goal and current task list with status indicators
When adding tasks to an existing planning session, the tool keeps things brief:
-- Adds your tasks seamlessly
-- Shows your updated task list (same format as `get_tasks`)
-- No repetitive instructions - just your updated plan
+- Adds tasks seamlessly
+- Shows the updated task list (same format as `get_tasks`)
+- No repetitive instructions - just the updated plan
### Tracking Progress
-Your AI assistant gets a clear view of all tasks with visual status indicators:
+The 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.
+The 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.
```
**Goal:** Create a comprehensive MCP server for task planning and management
@@ -123,20 +114,6 @@ Legend: ☐ pending ⟳ in progress ☑ completed
☐ Build MCP server integration [i9j0k1l2]
```
-### Updating Status
-
-As work progresses, your AI assistant can update task statuses and immediately see the updated plan with all changes reflected.
-
-## Task Status Indicators
-
-- ☐ **pending**: Task is ready to be worked on
-- ⟳ **in_progress**: Task is currently being worked on
-- ☑ **completed**: Task has been finished successfully
-- ☒ **failed**: Task encountered an error or failed
-- ⊗ **cancelled**: Task was cancelled and won't be completed
-
-The 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.
-
## Task IDs
Task IDs are deterministically generated based on the task title and description using SHA-256 hashing (8 hex characters). This ensures:
@@ -152,7 +129,3 @@ Task IDs are deterministically generated based on the task title and description
## License
AGPL-3.0-or-later
-
-## Author
-
-Amolith <amolith@secluded.site>