powerplan-mcp 0.6.0__tar.gz

powerplan_mcp-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CynaCons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

powerplan_mcp-0.6.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: powerplan-mcp
+Version: 0.6.0
+Summary: MCP server that makes PLAN.md the operational backbone of agentic development
+Author: CynaCons
+License: MIT
+Project-URL: Homepage, https://github.com/CynaCons/powerplan
+Project-URL: Repository, https://github.com/CynaCons/powerplan
+Project-URL: Documentation, https://cynacons.github.io/powerplan/
+Project-URL: Issues, https://github.com/CynaCons/powerplan/issues
+Project-URL: Changelog, https://github.com/CynaCons/powerplan/blob/main/CHANGELOG.md
+Keywords: mcp,mcp-server,plan,agents,PLAN.md,orchestration
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.cynacons/powerplan -->
+
+# powerplan
+
+**PLAN.md as the operational backbone of agentic development.**
+
+`powerplan` is an [MCP](https://modelcontextprotocol.io) 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`](https://pypi.org/project/powerplan-mcp/) (`powerplan` is a different, unrelated package) |
+| **Registry** | `io.github.cynacons/powerplan` |
+| **Status** | v0.6.0 — public package + registry listing ([PLAN.md](PLAN.md)) |
+| **Site** | [GitHub Pages](https://cynacons.github.io/powerplan/) |
+| **Pairs with** | [PowerSpawn](https://github.com/CynaCons/PowerSpawn) (optional) |
+
+---
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/) (provides `uvx`) or Python 3.10+.
+
+```bash
+uvx powerplan-mcp
+```
+
+That is the stdio MCP server. Point your client at it:
+
+### Claude Code / Cursor / `.mcp.json`
+
+```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)
+
+```toml
+[mcp_servers.powerplan]
+command = "uvx"
+args = ["powerplan-mcp"]
+env = { PYTHONUNBUFFERED = "1", PYTHONIOENCODING = "utf-8" }
+enabled = true
+```
+
+### pip (no uv)
+
+```bash
+pip install powerplan-mcp
+```
+
+```json
+{
+  "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
+
+| Tool | Behavior |
+|------|----------|
+| `create_plan` | Bootstrap `./PLAN.md` (or `plan_path`) when missing; `force` to overwrite |
+| `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` / … | Surgical mutations |
+| `complete_task` / `reopen_task` | Checkbox updates; optional `[agent: id]` |
+| `start_iteration` / `close_iteration` | ACTIVE/current vs COMPLETE lifecycle |
+| `check_plan` | Structure lint |
+| `show_plan` / `show_current_iteration` | 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.
+
+```bash
+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:
+
+```json
+{
+  "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](https://pypi.org/manage/account/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):
+
+```bash
+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](LICENSE).

powerplan_mcp-0.6.0/README.md

@@ -0,0 +1,212 @@
+<!-- mcp-name: io.github.cynacons/powerplan -->
+
+# powerplan
+
+**PLAN.md as the operational backbone of agentic development.**
+
+`powerplan` is an [MCP](https://modelcontextprotocol.io) 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`](https://pypi.org/project/powerplan-mcp/) (`powerplan` is a different, unrelated package) |
+| **Registry** | `io.github.cynacons/powerplan` |
+| **Status** | v0.6.0 — public package + registry listing ([PLAN.md](PLAN.md)) |
+| **Site** | [GitHub Pages](https://cynacons.github.io/powerplan/) |
+| **Pairs with** | [PowerSpawn](https://github.com/CynaCons/PowerSpawn) (optional) |
+
+---
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/) (provides `uvx`) or Python 3.10+.
+
+```bash
+uvx powerplan-mcp
+```
+
+That is the stdio MCP server. Point your client at it:
+
+### Claude Code / Cursor / `.mcp.json`
+
+```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)
+
+```toml
+[mcp_servers.powerplan]
+command = "uvx"
+args = ["powerplan-mcp"]
+env = { PYTHONUNBUFFERED = "1", PYTHONIOENCODING = "utf-8" }
+enabled = true
+```
+
+### pip (no uv)
+
+```bash
+pip install powerplan-mcp
+```
+
+```json
+{
+  "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
+
+| Tool | Behavior |
+|------|----------|
+| `create_plan` | Bootstrap `./PLAN.md` (or `plan_path`) when missing; `force` to overwrite |
+| `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` / … | Surgical mutations |
+| `complete_task` / `reopen_task` | Checkbox updates; optional `[agent: id]` |
+| `start_iteration` / `close_iteration` | ACTIVE/current vs COMPLETE lifecycle |
+| `check_plan` | Structure lint |
+| `show_plan` / `show_current_iteration` | 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.
+
+```bash
+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:
+
+```json
+{
+  "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](https://pypi.org/manage/account/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):
+
+```bash
+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](LICENSE).

powerplan_mcp-0.6.0/powerplan/__init__.py

@@ -0,0 +1,37 @@
+"""
+powerplan — PLAN.md as the operational backbone of agentic development.
+
+This package provides a tolerant parser, byte-preserving writer, discovery,
+and (via powerplan_server.py) an MCP server named ``powerplan``.
+"""
+
+from .plan_model import (
+    BacklogItem,
+    BacklogSection,
+    Iteration,
+    MajorSection,
+    Plan,
+    ProseBlock,
+    Task,
+)
+from .plan_parser import parse_plan, parse_plan_file
+from .plan_writer import write_plan, write_plan_file
+from .discovery import find_plan_md, load_plan
+
+__version__ = "0.6.0"
+__all__ = [
+    "BacklogItem",
+    "BacklogSection",
+    "Iteration",
+    "MajorSection",
+    "Plan",
+    "ProseBlock",
+    "Task",
+    "parse_plan",
+    "parse_plan_file",
+    "write_plan",
+    "write_plan_file",
+    "find_plan_md",
+    "load_plan",
+    "__version__",
+]

powerplan_mcp-0.6.0/powerplan/__main__.py

@@ -0,0 +1,7 @@
+"""python -m powerplan — run the powerplan MCP server on stdio."""
+
+from powerplan.server import main
+import asyncio
+
+if __name__ == "__main__":
+    asyncio.run(main())

powerplan_mcp-0.6.0/powerplan/discovery.py

@@ -0,0 +1,77 @@
+"""PLAN.md discovery: walk up from cwd (or start) to the nearest PLAN.md."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Union
+
+from .plan_parser import parse_plan_file
+from .plan_model import Plan
+
+
+def resolve_plan_path(
+    plan_path: Optional[Union[str, Path]] = None,
+    *,
+    start: Optional[Union[str, Path]] = None,
+    must_exist: bool = True,
+    default_name: str = "PLAN.md",
+) -> Path:
+    """
+    Resolve which PLAN.md path a tool should use.
+
+    - If ``plan_path`` is set: expand/resolve relative to cwd (or absolute).
+      When ``must_exist`` is True, the file must already exist.
+      When False, parent directory must exist (file may be created).
+    - If omitted: walk up from ``start`` (default cwd) for nearest ``PLAN.md``.
+      If none found and ``must_exist`` is False, return ``cwd / default_name``.
+    """
+    if plan_path is not None and str(plan_path).strip() != "":
+        p = Path(plan_path).expanduser()
+        if not p.is_absolute():
+            p = (Path.cwd() / p).resolve()
+        else:
+            p = p.resolve()
+        if must_exist:
+            if not p.is_file():
+                raise FileNotFoundError(
+                    f"plan_path does not exist: {p}. "
+                    "Use create_plan(plan_path=...) to bootstrap a new plan."
+                )
+            return p
+        # Creating: parent must exist
+        if not p.parent.is_dir():
+            raise FileNotFoundError(f"Parent directory does not exist: {p.parent}")
+        return p
+
+    cur = Path(start).expanduser().resolve() if start is not None else Path.cwd().resolve()
+    if cur.is_file():
+        cur = cur.parent
+
+    for directory in [cur, *cur.parents]:
+        candidate = directory / default_name
+        if candidate.is_file():
+            return candidate
+
+    if must_exist:
+        raise FileNotFoundError(
+            f"No PLAN.md found walking up from {cur}. "
+            "Pass plan_path= to override, or call create_plan first."
+        )
+    return cur / default_name
+
+
+def find_plan_md(
+    start: Optional[Union[str, Path]] = None,
+    plan_path: Optional[Union[str, Path]] = None,
+) -> Path:
+    """Resolve an existing PLAN.md (must exist)."""
+    return resolve_plan_path(plan_path, start=start, must_exist=True)
+
+
+def load_plan(
+    start: Optional[Union[str, Path]] = None,
+    plan_path: Optional[Union[str, Path]] = None,
+) -> Plan:
+    """Discover PLAN.md and parse it into a Plan model."""
+    path = find_plan_md(start=start, plan_path=plan_path)
+    return parse_plan_file(path)