prodc 0.7.4__tar.gz → 0.9.0__tar.gz

{prodc-0.7.4 → prodc-0.9.0}/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes are documented here. Versioning is [SemVer](https://semver.o
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-11-12
+
+### Added
+
+- `prodc issue board|show|file|update|close|check|reindex` reads and writes the issue register
+  (`docs/issues/*.md`). The store moved here from cabildo, same file format.
+- MCP tools `issue_board`, `issue_show`, `issue_check`, `issue_file`, `issue_update`,
+  `issue_close`.
+
+## [0.8.0] - 2026-11-11
+
+### Added
+
+- `prodc mcp serve`: prodc as an MCP server, with the optional extra `pip install 'prodc[mcp]'`.
+  10 read tools and 5 write tools. `capture` and `add_need` refuse `primary`. `accept`,
+  `outcome`, `attest`, `withdraw` and `sync` are not exposed. See [docs/mcp.md](docs/mcp.md).
+- `prodc mcp install` writes the server into `.mcp.json` (or `--client cursor|vscode`). It changes
+  only the `prodc` entry and refuses a file it cannot parse. `prodc mcp uninstall` removes it.
+- A write's `--json` output has `sha_before` and `sha_after`, to pass as `--expect-sha`.
+
 ## [0.7.4] - 2026-11-11
 
 ### Added

{prodc-0.7.4 → prodc-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.7.4
+Version: 0.9.0
 Summary: Product management as code: roles, flows, and features traced to evidence.
 Project-URL: Homepage, https://gitlab.com/cardona-oss/prodc
 Project-URL: Repository, https://gitlab.com/cardona-oss/prodc
@@ -24,6 +24,8 @@ Requires-Dist: pyyaml>=6
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # prodc
@@ -196,6 +198,9 @@ The Python modules are not a public API. Use the CLI, `--json` and the YAML file
 - `prodc agent >> AGENTS.md` adds instructions for a coding agent to act as the project's product
   manager. An agent may record `assumption` or `secondary` sources; `primary` is only for a real
   user's own words. `prodc guide` is a short guide for people.
+- `prodc mcp install` registers prodc as an MCP server, so an agent in Claude Code, Cursor, or VS
+  Code uses it through tools. Install with `pip install 'prodc[mcp]'`. See
+  [MCP server](https://cardona-oss.gitlab.io/prodc/mcp/).
 
 prodc also has goals, releases, roles, principles, and decisions
 ([model docs](https://cardona-oss.gitlab.io/prodc/model/)), and the commands `dupes`,

{prodc-0.7.4 → prodc-0.9.0}/README.md

@@ -168,6 +168,9 @@ The Python modules are not a public API. Use the CLI, `--json` and the YAML file
 - `prodc agent >> AGENTS.md` adds instructions for a coding agent to act as the project's product
   manager. An agent may record `assumption` or `secondary` sources; `primary` is only for a real
   user's own words. `prodc guide` is a short guide for people.
+- `prodc mcp install` registers prodc as an MCP server, so an agent in Claude Code, Cursor, or VS
+  Code uses it through tools. Install with `pip install 'prodc[mcp]'`. See
+  [MCP server](https://cardona-oss.gitlab.io/prodc/mcp/).
 
 prodc also has goals, releases, roles, principles, and decisions
 ([model docs](https://cardona-oss.gitlab.io/prodc/model/)), and the commands `dupes`,

{prodc-0.7.4 → prodc-0.9.0}/pyproject.toml

@@ -31,6 +31,8 @@ dependencies = ["pyyaml>=6"]
 prodc = "prodc.cli:main"
 
 [project.optional-dependencies]
+# mcp: the optional MCP server (`prodc mcp serve`). v2 moved the server import, so pin the major.
+mcp = ["mcp>=2,<3"]
 # docs are an *extra* (not a uv dependency-group): CI's `pages` job and moon's `docs` task
 # install them with `--extra docs` to build the GitLab Pages site
 docs = [
@@ -68,7 +70,7 @@ include = ["src", "tests", "examples", "README.md", "CHANGELOG.md", "LICENSE"]
 
 [dependency-groups]
 # musil is a dev-only model checker (tests/test_models.py); prodc's runtime stays pyyaml-only.
-dev = ["ruff>=0.6", "pyright[nodejs]>=1.1.390", "pytest>=8", "types-pyyaml>=6", "musil>=0.35"]
+dev = ["ruff>=0.6", "pyright[nodejs]>=1.1.390", "pytest>=8", "types-pyyaml>=6", "musil>=0.35", "mcp>=2,<3"]
 
 [tool.ruff]
 line-length = 100

{prodc-0.7.4 → prodc-0.9.0}/src/prodc/__init__.py

@@ -1,3 +1,3 @@
 """prodc: product management as code."""
 
-__version__ = "0.7.4"  # the single source of truth; pyproject reads it via [tool.hatch.version]
+__version__ = "0.9.0"  # the single source of truth; pyproject reads it via [tool.hatch.version]

{prodc-0.7.4 → prodc-0.9.0}/src/prodc/agent.md

@@ -44,9 +44,10 @@ Decide where a thing goes before you write it.
 |---|---|---|
 | something a person wants | a need, with a source | `When an invited user opens the invite link, they can set a password` |
 | a rule that decides between wants | a principle | `We do not build per-client forks` |
-| engineering work or a bug | an issue in your tracker, not prodc | `the view generator drops links from shared components` |
+| engineering work or a bug | an issue: `prodc issue file` in `docs/issues/`, or your tracker | `the view generator drops links from shared components` |
 
-- prodc never calls a tracker. Engineering work and bugs are issues there.
+- prodc never calls a tracker. Engineering work and bugs are issues: in `docs/issues/` with
+  `prodc issue file`, or in your tracker.
 - A bug that breaks a delivered need shows up on its own: the proof turns PENDING or BROKEN. Fix
   the code. Do not edit the need.
 - A bug that shows users cannot do something at all is a missing want. Write that as a need.
@@ -132,6 +133,13 @@ boards under), and `prodc diff <snapshot.json>` (what changed since a
 saved `status --json`). `prodc status` also takes `--goal <id>`, `--columns id,state,text,warrant`,
 `--wide`, `--include-drafts`, and `--stale <days>`.
 
+## As MCP tools
+
+If your client has the prodc MCP server (`prodc mcp install`), the same commands are tools:
+`status`, `show`, `plan`, `lint`, `capture`, `set`, `add_need`, and others. The rules above
+still hold. `capture` and `add_need` accept only `secondary` and `assumption`. Chain writes by
+passing the last `sha_after` as `expect_sha`.
+
 ## Running non-interactively (CI, or no human in the loop)
 
 - **Exit codes are the contract, not the stdout.** `0` = clean; `1` = a gate failed (a BROKEN

{prodc-0.7.4 → prodc-0.9.0}/src/prodc/cli/app.py

@@ -41,9 +41,12 @@ from .commands import (
     cmd_views,
     cmd_withdraw,
 )
+from .issue import add_issue_parser
+from .mcp import add_mcp_parser
 
 
-def main(argv: list[str] | None = None) -> int:
+def build_parser() -> argparse.ArgumentParser:
+    """Return the full ``prodc`` argument parser. The MCP server builds its argv against it."""
     parser = argparse.ArgumentParser(prog="prodc", description="Product management as code.")
     parser.add_argument("--version", action="version", version=f"prodc {__version__}")
     parser.add_argument(
@@ -752,6 +755,13 @@ def main(argv: list[str] | None = None) -> int:
     )
     sy.set_defaults(func=cmd_sync)
 
+    add_issue_parser(
+        sub.add_parser("issue", help="read and write the issue register (docs/issues)")
+    )
+    add_mcp_parser(
+        sub.add_parser("mcp", help="run prodc as an MCP server, or register it with a client")
+    )
+
     ag = sub.add_parser(
         "agent",
         help="print prodc's agent playbook (teach a coding agent to run prodc as the project's PM)",
@@ -784,8 +794,11 @@ def main(argv: list[str] | None = None) -> int:
     )
     df.add_argument("snapshot", help="path to a saved `prodc status --json` file")
     df.set_defaults(func=cmd_diff)
+    return parser
+
 
-    args = parser.parse_args(argv)
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
     if args.chdir is not None:
         try:
             os.chdir(args.chdir)

{prodc-0.7.4 → prodc-0.9.0}/src/prodc/cli/common.py

@@ -79,7 +79,14 @@ def exit_code(args: argparse.Namespace, summary: Summary, orphan_total: int) ->
 
 def emit_edit(edit: Edit, dry_run: bool, as_json: bool) -> int:
     if as_json:
-        print(json.dumps({"file": edit.path.name, "dry_run": dry_run, "diff": edit.diff}, indent=2))
+        payload = {
+            "file": edit.path.name,
+            "dry_run": dry_run,
+            "diff": edit.diff,
+            "sha_before": edit.sha_before,
+            "sha_after": edit.sha_after,
+        }
+        print(json.dumps(payload, indent=2))
     else:
         print(f"{'would edit' if dry_run else 'edited'} {edit.path.name}")
         print(edit.diff, end="")

prodc-0.9.0/src/prodc/cli/issue.py

@@ -0,0 +1,238 @@
+"""``prodc issue``: read and write the issue register (``docs/issues/*.md``).
+
+The store is :mod:`prodc.issue_store`. Claiming an issue is not here: a claim is a lease between
+running agents, which cabildo's bus owns. ``update --status in-progress`` records the state.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .. import issue_store as store
+
+
+def add_issue_parser(ip: argparse.ArgumentParser) -> None:
+    """Fill ``prodc issue {board,show,file,update,close,check,reindex}``."""
+
+    def bare(_args: argparse.Namespace) -> int:
+        ip.print_help(sys.stderr)
+        return 2
+
+    ip.set_defaults(func=bare)
+    isub = ip.add_subparsers(dest="issue_command")
+
+    def sub(name: str, help: str) -> argparse.ArgumentParser:
+        p = isub.add_parser(name, help=help)
+        p.add_argument("--json", action="store_true", help="machine-readable output")
+        return p
+
+    bd = sub("board", "what is ready to pick up, and what the rest waits on")
+    bd.add_argument("--status", default=None, help="flat list filtered by status")
+    bd.add_argument("--area", default=None, help="flat list filtered by area")
+    bd.add_argument("--owner", default=None, help="flat list filtered by owner ('none': unowned)")
+    bd.set_defaults(func=cmd_issue_board)
+
+    sh = sub("show", "print one issue file")
+    sh.add_argument("name", help="a filename or an unambiguous part of the slug")
+    sh.set_defaults(func=cmd_issue_show)
+
+    fi = sub("file", "file a new issue")
+    fi.add_argument("--title", required=True)
+    fi.add_argument("--area", required=True)
+    fi.add_argument("--body", required=True, help="markdown body ('-' reads stdin)")
+    fi.add_argument("--blocked-by", action="append", default=[], metavar="SLUG")
+    fi.add_argument(
+        "--field",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="a field the folder's config.toml declares; repeat KEY for a list",
+    )
+    fi.set_defaults(func=cmd_issue_file)
+
+    up = sub("update", "change an issue's front matter; only what you pass changes")
+    up.add_argument("name")
+    up.add_argument("--title", default=None)
+    up.add_argument("--status", choices=[s.value for s in store.Status], default=None)
+    up.add_argument("--area", default=None)
+    up.add_argument("--blocked-by", action="append", default=None, metavar="SLUG")
+    up.add_argument("--clear-blocked-by", action="store_true")
+    up.add_argument("--field", action="append", default=[], metavar="KEY=VALUE")
+    up.set_defaults(func=cmd_issue_update)
+
+    cl = sub("close", "mark an issue done; the file stays, carrying fixed_in")
+    cl.add_argument("name")
+    cl.add_argument("--fixed-in", required=True, metavar="SHA", help="the sha on the mainline")
+    cl.set_defaults(func=cmd_issue_close)
+
+    ck = sub("check", "grade the folder against its config.toml (exit 1 on problems)")
+    ck.set_defaults(func=cmd_issue_check)
+
+    ri = sub("reindex", "rewrite the README index table")
+    ri.set_defaults(func=cmd_issue_reindex)
+
+
+def _folder() -> Path:
+    found = store.find_folder(Path.cwd())
+    if found is None:
+        raise store.IssueFormatError(f"no docs/issues/ at or above {Path.cwd()}")
+    return found
+
+
+def _fields(pairs: list[str]) -> dict[str, str | tuple[str, ...]]:
+    """``KEY=VALUE`` pairs to front-matter fields; a repeated key becomes a list."""
+    out: dict[str, list[str]] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            raise store.IssueFormatError(f"--field wants KEY=VALUE, got {pair!r}")
+        out.setdefault(key, []).append(value)
+    return {k: v[0] if len(v) == 1 else tuple(v) for k, v in out.items()}
+
+
+def _row(issue: store.Issue) -> dict[str, Any]:
+    return {
+        "slug": issue.slug,
+        "file": issue.path.name,
+        "title": issue.title,
+        "status": issue.status.value,
+        "area": issue.area,
+        "owner": issue.owner,
+        "blocked_by": list(issue.blocked_by),
+        "fixed_in": issue.fixed_in,
+        "fields": {k: list(v) if isinstance(v, tuple) else v for k, v in issue.extra.items()},
+    }
+
+
+def _line(issue: store.Issue) -> str:
+    owner = f" @{issue.owner}" if issue.owner else ""
+    return f"  {issue.slug}  [{issue.status.value}{owner}] {issue.area}: {issue.title}"
+
+
+def _emit(as_json: bool, data: object, text: str) -> None:
+    print(json.dumps(data, indent=2) if as_json else text)
+
+
+def _guard(func: Any) -> Any:
+    def run(args: argparse.Namespace) -> int:
+        try:
+            return int(func(args))
+        except (store.IssueFormatError, OSError) as exc:
+            print(f"prodc: {exc}", file=sys.stderr)
+            return 2
+
+    return run
+
+
+@_guard
+def cmd_issue_board(args: argparse.Namespace) -> int:
+    """Ready, waiting, done; or a flat list when a filter is given."""
+    folder = _folder()
+    if args.status or args.area or args.owner:
+        found, _ = store.load_all(folder)
+        rows = [
+            i
+            for i in found
+            if (args.status == "done" or i.open)
+            and (not args.status or i.status == args.status)
+            and (not args.area or i.area == args.area)
+            and (not args.owner or (i.owner or "none") == args.owner)
+        ]
+        _emit(args.json, [_row(i) for i in rows], "\n".join(_line(i) for i in rows) or "(none)")
+        return 0
+    b = store.board(folder)
+    data = {
+        "ready": [_row(i) for i in b.ready],
+        "waiting": [{**_row(w.issue), "reason": w.reason} for w in b.waiting],
+        "done": b.done,
+    }
+    lines = [f"READY ({len(b.ready)}):", *(_line(i) for i in b.ready)]
+    lines += [f"WAITING ({len(b.waiting)}):", *(f"  {w.issue.slug}: {w.reason}" for w in b.waiting)]
+    lines.append(f"{b.done} done")
+    _emit(args.json, data, "\n".join(lines))
+    return 0
+
+
+@_guard
+def cmd_issue_show(args: argparse.Namespace) -> int:
+    """Print one issue file."""
+    path = store.resolve(_folder(), args.name)
+    text = path.read_text(encoding="utf-8")
+    _emit(args.json, {"file": path.name, "text": text}, text.rstrip("\n"))
+    return 0
+
+
+@_guard
+def cmd_issue_file(args: argparse.Namespace) -> int:
+    """File a new issue and print its filename."""
+    body = sys.stdin.read() if args.body == "-" else args.body
+    path = store.file_issue(
+        _folder(),
+        title=args.title,
+        area=args.area,
+        body=body,
+        blocked_by=tuple(args.blocked_by),
+        extra=_fields(args.field),
+    )
+    _emit(args.json, {"file": path.name}, f"filed {path.name}")
+    return 0
+
+
+@_guard
+def cmd_issue_update(args: argparse.Namespace) -> int:
+    """Change only the front-matter keys passed."""
+    changes: dict[str, Any] = {}
+    if args.title:
+        changes["title"] = args.title
+    if args.status:
+        changes["status"] = store.Status(args.status)
+    if args.area:
+        changes["area"] = args.area
+    if args.clear_blocked_by:
+        changes["blocked_by"] = ()
+    elif args.blocked_by is not None:
+        changes["blocked_by"] = tuple(args.blocked_by)
+    if args.field:
+        changes["extra"] = _fields(args.field)
+    if not changes:
+        print("prodc: nothing to change", file=sys.stderr)
+        return 2
+    updated = store.update(_folder(), args.name, **changes)
+    _emit(args.json, _row(updated), f"updated {updated.path.name}\n{_line(updated)}")
+    return 0
+
+
+@_guard
+def cmd_issue_close(args: argparse.Namespace) -> int:
+    """Mark done with ``fixed_in``; report what it unblocked."""
+    folder = _folder()
+    updated = store.close(folder, args.name, fixed_in=args.fixed_in)
+    unblocked = [i.slug for i in store.newly_ready(folder, updated.slug)]
+    text = f"closed {updated.path.name} (fixed_in {updated.fixed_in})"
+    if unblocked:
+        text += "; unblocked: " + ", ".join(unblocked)
+    _emit(args.json, {**_row(updated), "unblocked": unblocked}, text)
+    return 0
+
+
+@_guard
+def cmd_issue_check(args: argparse.Namespace) -> int:
+    """Grade the folder; exit 1 when it has problems."""
+    folder = _folder()
+    problems = store.check(folder)
+    data = [{"file": p.path.name, "problem": p.message} for p in problems]
+    _emit(args.json, data, "\n".join(str(p) for p in problems) or f"{folder}: clean")
+    return 1 if problems else 0
+
+
+@_guard
+def cmd_issue_reindex(args: argparse.Namespace) -> int:
+    """Rewrite the README index table."""
+    folder = _folder()
+    store.reindex(folder)
+    _emit(args.json, {"folder": str(folder)}, f"reindexed {folder}")
+    return 0

prodc-0.9.0/src/prodc/cli/mcp.py

@@ -0,0 +1,132 @@
+"""``prodc mcp``: run the MCP server, or register it in an MCP client's project config."""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import sys
+from pathlib import Path
+from typing import cast
+
+from ..mcp_config import (
+    CLIENTS,
+    DEFAULT_COMMAND,
+    ClientName,
+    McpConfigError,
+    apply,
+    install,
+    manual_instructions,
+    uninstall,
+)
+
+
+def add_mcp_parser(mp: argparse.ArgumentParser) -> None:
+    """Fill ``prodc mcp {serve,install,uninstall}``. A bare ``prodc mcp`` prints help, exit 2."""
+
+    def bare(_args: argparse.Namespace) -> int:
+        mp.print_help(sys.stderr)
+        return 2
+
+    mp.set_defaults(func=bare)
+    msub = mp.add_subparsers(dest="mcp_command")
+
+    sv = msub.add_parser("serve", help="run the MCP server on stdio (the client starts this)")
+    sv.set_defaults(func=cmd_mcp_serve)
+
+    for name, func, verb in (
+        ("install", cmd_mcp_install, "add the prodc server to"),
+        ("uninstall", cmd_mcp_uninstall, "remove the prodc server from"),
+    ):
+        p = msub.add_parser(name, help=f"{verb} an MCP client's project config")
+        p.add_argument(
+            "--client",
+            choices=["claude", "cursor", "vscode", "codex"],
+            default="claude",
+            help="which client's config (default: claude, .mcp.json)",
+        )
+        p.add_argument(
+            "--scope",
+            choices=["project", "user"],
+            default="project",
+            help="project writes the repo's config file; user prints the client's own command",
+        )
+        p.add_argument("--dry-run", action="store_true", help="show the diff, write nothing")
+        p.add_argument("--json", action="store_true", help="machine-readable output")
+        if name == "install":
+            p.add_argument(
+                "--command",
+                default=None,
+                metavar="CMD",
+                help='the server command to write (default: uvx --from "prodc[mcp]" prodc mcp '
+                "serve). Use 'uv run prodc mcp serve' when the project pins prodc",
+            )
+        p.set_defaults(func=func)
+
+
+def cmd_mcp_serve(args: argparse.Namespace) -> int:
+    """Run the stdio server. Needs the ``mcp`` extra."""
+    try:
+        from ..mcp_server import serve
+    except ImportError:
+        print("prodc: install prodc[mcp] to run the MCP server", file=sys.stderr)
+        return 2
+    serve(args.chdir)
+    return 0
+
+
+def _report(edit_path: Path, old: str, new: str, dry_run: bool, as_json: bool) -> None:
+    changed = old != new
+    diff = "".join(
+        difflib.unified_diff(
+            old.splitlines(keepends=True),
+            new.splitlines(keepends=True),
+            fromfile=f"a/{edit_path}",
+            tofile=f"b/{edit_path}",
+        )
+    )
+    if as_json:
+        print(
+            json.dumps(
+                {"file": str(edit_path), "changed": changed, "dry_run": dry_run, "diff": diff},
+                indent=2,
+            )
+        )
+        return
+    if not changed:
+        print(f"{edit_path}: unchanged")
+        return
+    print(f"{'would edit' if dry_run else 'edited'} {edit_path}")
+    print(diff, end="")
+
+
+def _run(args: argparse.Namespace, installing: bool) -> int:
+    client = cast(ClientName, args.client)
+    command: str = getattr(args, "command", None) or DEFAULT_COMMAND
+    if client not in CLIENTS or args.scope == "user":
+        # prodc does not write user-scope files (~/.claude.json is live client state) or TOML.
+        if installing:
+            print(manual_instructions(client, args.scope, command), end="")
+        else:
+            print(f"remove the 'prodc' server with {client}'s own MCP command or config")
+        return 0
+    root = Path.cwd()
+    try:
+        edit = install(root, client, command) if installing else uninstall(root, client)
+    except McpConfigError as exc:
+        print(f"prodc: {exc}", file=sys.stderr)
+        return 2
+    if not args.dry_run:
+        apply(edit)
+    _report(edit.path.relative_to(root), edit.old_text, edit.new_text, args.dry_run, args.json)
+    return 0
+
+
+def cmd_mcp_install(args: argparse.Namespace) -> int:
+    """Add or update the ``prodc`` entry in the client's project config."""
+    return _run(args, installing=True)
+
+
+def cmd_mcp_uninstall(args: argparse.Namespace) -> int:
+    """Remove the ``prodc`` entry from the client's project config."""
+    return _run(args, installing=False)