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. get_current_iteration — what to work on now (JSON).
3. get_iteration(version) — one iteration’s tasks and progress.
4. Mutate with add_task / complete_task / start_iteration / close_iteration.
5. show_plan is a human skim, not a dump.

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)

Versions live in pyproject.toml, powerplan/__init__.py, and server.json. Keep them equal.

PyPI uses GitHub Actions trusted publishing (no API token in the repo).

1. One-time: on PyPI publishing add a pending publisher:
   • Project name: powerplan-mcp
   • Owner: CynaCons
   • Repository: powerplan
   • Workflow name: publish.yml
   • Environment: (leave empty)
2. Tag and push: git tag v0.6.1 && git push origin v0.6.1
3. .github/workflows/publish.yml builds, uploads to PyPI, then publishes server.json to the official MCP Registry via mcp-publisher login github-oidc.

Manual registry publish (after the wheel is on PyPI):

mcp-publisher login github
mcp-publisher publish

mcp-publisher verifies mcp-name: io.github.cynacons/powerplan in the PyPI README, so that string must stay in this file.

License

MIT — see LICENSE.