Clone

git clone git@git.secluded.site:planning-mcp-server.git

README

This entire project, including the README below, was largely written by LLMs. It works well enough, but I'm experiencing an odd issue in my preferred coding tool where the server seems to die and the coding tool restarts the server, wiping the in-memory-only tasks. I could fix that by implementing persistent storage, but I'm more interested in seeing how LLMs work with a completely different implementation of this idea. I don't intend to maintain this server going forward, though it should continue to function until/unless the MCP protocol changes.

I wrote formatted-commit, a CLI tool, to encourage (and force) LLMs towards well-formatted Conventional Commits and that's the kind of style I want to try for the next version of this "LLM-oriented planning system" idea. It's called, for now, nasin pali.

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

The server provides seven 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.
  • 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.
  • 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

# Download and build using the go tool
go install git.secluded.site/planning-mcp-server/cmd/planning-mcp-server@main

# Build from the cloned source code
git clone https://git.secluded.site/planning-mcp-server.git
cd planning-mcp-server
go build -o planning-mcp-server ./cmd/planning-mcp-server
mv planning-mcp-server ~/.local/bin # assuming ~/.local/bin is in your shell's PATH

Configuration

Generate an example configuration file (optional):

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 the agent first adds tasks to an empty planning session, the tool provides guidance and shows your complete plan:

  • Adds the tasks to the planning session
  • Shows helpful instructions for getting started
  • Displays the goal and current task list with status indicators

When adding tasks to an existing planning session, the tool keeps things brief:

  • Adds tasks seamlessly
  • Shows the updated task list (same format as get_tasks)
  • No repetitive instructions - just the updated plan

Tracking Progress

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

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 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
  • When modifying tasks, IDs are regenerated to reflect the new content

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.

Collaboration

Patch requests are in amolith/llm-projects on pr.pico.sh. You don't need a new account to contribute, you don't need to fork this repo, you don't need to fiddle with git send-email, you don't need to faff with your email client to get git request-pull working...

You just need:

  • Git
  • SSH
  • An SSH key
# Clone this repo, make your changes, and commit them
# Create a new patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
# After potential feedback, submit a revision to an existing patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
# List patch requests
ssh pr.pico.sh pr list amolith/llm-projects

See "How do Patch Requests work?" on pr.pico.sh's home page for a more complete example workflow.

License

AGPL-3.0-or-later