Repository avatar
Other Tools
v0.10.0
active

powerplan

io.github.CynaCons/powerplan

MCP server that makes PLAN.md the operational backbone of agentic development

Documentation

powerplan

PLAN.md as the operational backbone of agentic development.

powerplan is an MCP server that gives coordinators and worker agents a human-language API over your project’s PLAN.md: show progress, create iterations, complete tasks, keep the header truthful — without freeform file thrash.

mcp-name: io.github.CynaCons/powerplan

MCP server namepowerplan
PyPIpowerplan-mcp (powerplan is a different, unrelated package)
Registryio.github.CynaCons/powerplan
Statusv0.10.0 — miniplan turn report (PLAN.md)
SiteGitHub Pages
Pairs withPowerSpawn (optional)

Install

You need uv (provides uvx) or Python 3.10+.

uvx powerplan-mcp

That is the stdio MCP server. Point your client at it:

Claude Code / Cursor / .mcp.json

{
  "mcpServers": {
    "powerplan": {
      "command": "uvx",
      "args": ["powerplan-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Claude Desktop

Same block in claude_desktop_config.json (mcpServers).

Grok (~/.grok/config.toml or project config)

[mcp_servers.powerplan]
command = "uvx"
args = ["powerplan-mcp"]
env = { PYTHONUNBUFFERED = "1", PYTHONIOENCODING = "utf-8" }
enabled = true

pip (no uv)

pip install powerplan-mcp
{
  "mcpServers": {
    "powerplan": {
      "command": "python",
      "args": ["-m", "powerplan"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Agent guide

Prefer scoped tools. Do not read all of PLAN.md to figure out what to do.

  1. If tools fail with “no PLAN.md” → create_plan first.
  2. show_miniplan — what to work on now, in the plan's own format: the current iteration verbatim with the neighbouring headers. Start every session here.
  3. get_current_iteration — the same, as JSON.
  4. get_iteration(version) — one iteration’s tasks and progress.
  5. Mutate with add_task / add_tasks / complete_task (indexes for several) / start_iteration / close_iteration.
  6. show_plan is a human skim, not a dump.
  7. End every major turn (files changed, tasks ticked or added, a check run, an iteration closed) with a miniplan in the chat, then show_current_iteration pasted verbatim in a code block, so the user sees status and progress at a glance. The server sends this rule to every client in its MCP instructions.

A miniplan is a turn-end task report in the plan's own format, printed in the reply and never written to a file: the show_miniplan block verbatim with its checkboxes flipped, plus an ## Off-plan section for quick items the turn is tracking that are not in PLAN.md yet, each marked → plan, → backlog or → drop. Format and example: docs/MINIPLAN.md. Ships as the miniplan skill for Claude Code, Cursor, Codex and Grok (.claude/skills/, .cursor/skills/, .codex/skills/, .grok/skills/).

Every tool accepts optional plan_path (relative or absolute). Default: walk up from cwd to the nearest PLAN.md.

Optional agent on mutations writes a trailing [agent: id] tag on the touched line.


Why

Agents often edit PLAN.md by hand. Headers drift, “COMPLETE” gets stamped without proof, and multi-agent swarms step on each other. powerplan is the single writer: tolerant reader, surgical writer, optional [agent: …] tags.


Tools

ToolBehavior
create_planBootstrap ./PLAN.md (or plan_path) when missing; force to overwrite
show_miniplanSession opener — raw PLAN.md snippet: the current (or named) iteration byte-for-byte, neighbours collapsed to header lines (before/after). Also seeds the turn-end miniplan report
get_current_iterationPreferred for agents — scoped JSON for current work
get_iterationJSON for one version (tasks, progress)
list_iterations / find_task / get_backlogNavigate without full-file reads
create_major / create_iteration / add_task / add_tasksSurgical mutations (batch add in one write)
complete_task / reopen_task / remove_task / defer_taskOne or many (indexes / tasks); optional [agent: id]
start_iteration / close_iterationACTIVE/current vs COMPLETE lifecycle
check_planStructure lint
show_current_iterationTurn closer — status view (status, progress count, goal, tasks) to paste at the end of every major turn
show_planCompact human skim (not a full dump)

Managed plan format

ConstructPattern
Major## vX.Y — Title
Iteration### vX.Y.Z — Title
Goal**Goal:** …
Tasks- [ ] / - [x]
Backlog## Backlog

Phase-like headers and other prose are preserved as opaque blocks.


From source

Clone, editable install, or PowerSpawn submodule — for contributors.

git clone https://github.com/CynaCons/powerplan.git
cd powerplan
pip install -e ".[dev]"
python -m powerplan          # same stdio server
# or: powerplan-mcp

PowerSpawn can vendor this repo as a git submodule. Register both MCP servers — they do not merge:

{
  "mcpServers": {
    "powerplan": {
      "command": "uvx",
      "args": ["powerplan-mcp"]
    },
    "powerspawn": {
      "command": "python",
      "args": ["-m", "powerspawn.mcp_server"]
    }
  }
}

Path-only (no install): python /path/to/powerplan/powerplan_server.py

Landing page: cd site && npm ci && npm run dev


Releasing (maintainers)

Full procedure, identities, and failure history: docs/RELEASING.md. Agent checklist: project skill release-powerplan (/release-powerplan).

Short path: bump every version file listed in that guide → pytest -q → tag vX.Y.Z → push the tag. .github/workflows/publish.yml uploads powerplan-mcp to PyPI, then server.json to the MCP Registry as io.github.CynaCons/powerplan.


License

MIT — see LICENSE.

PYPI
powerplan-mcp
Install Command
pip install powerplan-mcp
Runtime: uvx