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

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