powerplan

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

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

Managed plan format

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