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.

Features

The server provides four core tools that constitute a comprehensive planning workflow:

update_goal: Set or update the overarching goal for your planning session
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 current task list with status indicators and legend. Call frequently to stay organized.
update_task_status: Update the status of a specific task. Maintain your planning workflow by updating statuses regularly.

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

Tool Examples

Setting a Goal

{
  "name": "update_goal",
  "arguments": {
    "goal": "Create a comprehensive MCP server for task planning and management"
  }
}

Response: Goal "Create a comprehensive MCP server for task planning and management" saved! You probably want to add one or more tasks now.

Adding 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

Getting Task Status

{
  "name": "get_tasks",
  "arguments": {}
}

Response:

**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 Task Status

{
  "name": "update_task_status",
  "arguments": {
    "task_id": "a1b2c3d4",
    "status": "completed"
  }
}

Response:

**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]

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

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

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
No collisions for different tasks
Consistent references across sessions

License

AGPL-3.0-or-later

Author

Amolith amolith@secluded.site

README.md