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
get_tasks: Get current task list with status indicators and legend
update_task_status: Update the status of a specific task

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

{
  "name": "add_tasks", 
  "arguments": {
    "tasks": [
      {
        "title": "Set up project structure",
        "description": "Create Go module, directories, and basic files"
      },
      {
        "title": "Implement core planning logic",
        "description": "Create Goal and Task data structures with deterministic IDs"
      },
      {
        "title": "Build MCP server integration"
      }
    ]
  }
}

Response: Tasks added successfully! Get started on your first one once you're ready, and call get_tasks frequently to remind yourself where you are in the process. Reminder that your overarching goal is "Create a comprehensive MCP server for task planning and management".

Getting Task Status

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

Response:

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:

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