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.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](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.