
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 name | powerplan |
| PyPI | powerplan-mcp (powerplan is a different, unrelated package) |
| Registry | io.github.CynaCons/powerplan |
| Status | v0.10.0 — miniplan turn report (PLAN.md) |
| Site | GitHub Pages |
| Pairs with | PowerSpawn (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.
- If tools fail with “no PLAN.md” →
create_planfirst. 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.get_current_iteration— the same, as JSON.get_iteration(version)— one iteration’s tasks and progress.- Mutate with
add_task/add_tasks/complete_task(indexesfor several) /start_iteration/close_iteration. show_planis a human skim, not a dump.- 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_iterationpasted 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
| Tool | Behavior |
|---|---|
create_plan | Bootstrap ./PLAN.md (or plan_path) when missing; force to overwrite |
show_miniplan | Session 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_iteration | Preferred for agents — scoped JSON for current work |
get_iteration | JSON for one version (tasks, progress) |
list_iterations / find_task / get_backlog | Navigate without full-file reads |
create_major / create_iteration / add_task / add_tasks | Surgical mutations (batch add in one write) |
complete_task / reopen_task / remove_task / defer_task | One or many (indexes / tasks); optional [agent: id] |
start_iteration / close_iteration | ACTIVE/current vs COMPLETE lifecycle |
check_plan | Structure lint |
show_current_iteration | Turn closer — status view (status, progress count, goal, tasks) to paste at the end of every major turn |
show_plan | Compact human skim (not a full dump) |
Managed plan format
| Construct | Pattern |
|---|---|
| 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.
powerplan-mcppip install powerplan-mcp