planning-mcp-server

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

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.
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.

Installation

go build -o planning-mcp-server ./cmd/planning-mcp-server

Configuration

Generate an example configuration file:

./planning-mcp-server --generate-config

This creates planning-mcp-server.toml with default settings:

[server]
mode = 'stdio'  # or 'http'
host = 'localhost'
port = 8080

[logging]
level = 'info'  # debug, info, warn, error
format = 'text'  # text, json

[planning]
max_tasks = 100
max_goal_length = 1000
max_task_length = 500
history_enabled = true

Usage

STDIO Mode (Default)

For use with MCP clients like Claude Desktop:

./planning-mcp-server --mode stdio

HTTP Mode

For web-based integrations:

./planning-mcp-server --mode http --port 8080

CLI Options

./planning-mcp-server --help

--config, -c: Configuration file path
--mode, -m: Server mode (stdio or http)
--port, -p: HTTP server port
--host: HTTP server host
--log-level: Log level (debug, info, warn, error)
--generate-config: Generate example configuration
--version, -v: Show version

How Your AI Assistant Uses This

Setting Goals

Your AI assistant can establish clear objectives that stay visible throughout the current planning session, helping maintain focus on the overall purpose.

Planning Tasks

When you first add tasks to an empty planning session, the tool provides guidance and shows your complete plan:

Adds your tasks to the planning session
Shows helpful instructions for getting started
Displays your 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

Tracking Progress

Your AI assistant gets a clear view of all tasks with visual status indicators:

**Goal:** Create a comprehensive MCP server for task planning and management

Legend: ☐ pending  ⟳ in progress  ☑ completed
☐ Set up project structure [a1b2c3d4]
  Create Go module, directories, and basic files
☐ Implement core planning logic [e5f6g7h8]
  Create Goal and Task data structures with deterministic IDs
☐ 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:

Same task content always gets the same ID within a session
No collisions for different tasks
Consistent references during the current session

Data Storage

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.

License

AGPL-3.0-or-later

Author

Amolith amolith@secluded.site

README.md