prodc 0.7.4__tar.gz → 0.8.0__tar.gz

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

@@ -4,6 +4,17 @@ All notable changes are documented here. Versioning is [SemVer](https://semver.o
 
 ## [Unreleased]
 
+## [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.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.7.4
+Version: 0.8.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.8.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.8.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.8.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.8.0"  # the single source of truth; pyproject reads it via [tool.hatch.version]

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

@@ -132,6 +132,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.8.0}/src/prodc/cli/app.py

@@ -41,9 +41,11 @@ from .commands import (
     cmd_views,
     cmd_withdraw,
 )
+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 +754,10 @@ def main(argv: list[str] | None = None) -> int:
     )
     sy.set_defaults(func=cmd_sync)
 
+    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 +790,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.8.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.8.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)

prodc-0.8.0/src/prodc/mcp_config.py

@@ -0,0 +1,147 @@
+"""Register the prodc MCP server in an MCP client's project config (``prodc mcp install``).
+
+The write touches only the ``prodc`` entry, keeps every other server and key in order, and
+refuses a file it cannot parse (for example JSON with comments) instead of overwriting it.
+Codex (TOML) and user-scope configs are not written: prodc prints the client's own command.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, cast
+
+ClientName = Literal["claude", "cursor", "vscode", "codex"]
+
+DEFAULT_COMMAND = 'uvx --from "prodc[mcp]" prodc mcp serve'
+"""The command written by default: runs the latest prodc[mcp] in its own isolated env."""
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Where one client keeps its project MCP config and how an entry looks there."""
+
+    path: str  # relative to the project root
+    key: str  # the top-level object that holds the servers
+    needs_type: bool  # the client requires "type": "stdio"
+
+
+CLIENTS: dict[str, ClientConfig] = {
+    "claude": ClientConfig(".mcp.json", "mcpServers", needs_type=False),
+    "cursor": ClientConfig(".cursor/mcp.json", "mcpServers", needs_type=True),
+    "vscode": ClientConfig(".vscode/mcp.json", "servers", needs_type=True),
+}
+
+
+class McpConfigError(Exception):
+    """The config file exists but cannot be safely rewritten."""
+
+
+def entry(client: ClientName, command: str = DEFAULT_COMMAND) -> dict[str, Any]:
+    """The server entry for ``client``: ``{command, args}`` plus ``type`` where required."""
+    cmd, *args = shlex.split(command)
+    out: dict[str, Any] = {}
+    if CLIENTS[client].needs_type:
+        out["type"] = "stdio"
+    out["command"] = cmd
+    out["args"] = args
+    return out
+
+
+def manual_instructions(client: ClientName, scope: str, command: str = DEFAULT_COMMAND) -> str:
+    """The client's own command for what prodc does not write (Codex, user scope)."""
+    if client == "codex":
+        cmd, *args = shlex.split(command)
+        toml_args = ", ".join(json.dumps(a) for a in args)
+        return (
+            f"codex mcp add prodc -- {command}\n\nor add to ~/.codex/config.toml:\n\n"
+            f'[mcp_servers.prodc]\ncommand = "{cmd}"\nargs = [{toml_args}]\n'
+        )
+    if client == "claude":
+        return f"claude mcp add --scope {scope} prodc -- {command}\n"
+    if client == "vscode":
+        return f"code --add-mcp '{json.dumps({'name': 'prodc', **entry(client, command)})}'\n"
+    return f"add to ~/.cursor/mcp.json under mcpServers:\n{json.dumps({'prodc': entry(client, command)}, indent=2)}\n"
+
+
+@dataclass(frozen=True)
+class ConfigEdit:
+    """A proposed change to one client config file."""
+
+    path: Path
+    old_text: str  # "" when the file does not exist
+    new_text: str  # "" when the file should be deleted
+
+    @property
+    def changed(self) -> bool:
+        return self.old_text != self.new_text
+
+
+def _load(path: Path) -> tuple[str, dict[str, Any]]:
+    if not path.exists():
+        return "", {}
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        return text, {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise McpConfigError(
+            f"{path} is not plain JSON ({exc.msg}, line {exc.lineno}); prodc will not rewrite it. "
+            "Add the entry by hand."
+        ) from exc
+    if not isinstance(data, dict):
+        raise McpConfigError(f"{path}: the top level is not a JSON object")
+    return text, cast(dict[str, Any], data)
+
+
+def _dump(data: dict[str, Any]) -> str:
+    return json.dumps(data, indent=2) + "\n"
+
+
+def install(root: Path, client: ClientName, command: str = DEFAULT_COMMAND) -> ConfigEdit:
+    """Return the edit that adds or updates the ``prodc`` entry. Writes nothing."""
+    cc = CLIENTS[client]
+    path = root / cc.path
+    old, data = _load(path)
+    raw = data.get(cc.key, {})
+    if not isinstance(raw, dict):
+        raise McpConfigError(f"{path}: {cc.key!r} is not a JSON object")
+    servers = cast(dict[str, Any], raw)
+    new_servers = dict(servers)
+    new_servers["prodc"] = entry(client, command)
+    new = dict(data)
+    new[cc.key] = new_servers
+    return ConfigEdit(path, old, old if new == data else _dump(new))
+
+
+def uninstall(root: Path, client: ClientName) -> ConfigEdit:
+    """Return the edit that removes only the ``prodc`` entry. Writes nothing.
+
+    The file is deleted only when nothing but an empty servers object would be left.
+    """
+    cc = CLIENTS[client]
+    path = root / cc.path
+    old, data = _load(path)
+    raw = data.get(cc.key)
+    if not isinstance(raw, dict) or "prodc" not in raw:
+        return ConfigEdit(path, old, old)
+    servers = cast(dict[str, Any], raw)
+    new_servers = {k: v for k, v in servers.items() if k != "prodc"}
+    new: dict[str, Any] = {**data, cc.key: new_servers}
+    if new == {cc.key: {}}:
+        return ConfigEdit(path, old, "")
+    return ConfigEdit(path, old, _dump(new))
+
+
+def apply(edit: ConfigEdit) -> None:
+    """Write (or delete) the file the edit describes."""
+    if not edit.changed:
+        return
+    if edit.new_text == "":
+        edit.path.unlink()
+        return
+    edit.path.parent.mkdir(parents=True, exist_ok=True)
+    edit.path.write_text(edit.new_text, encoding="utf-8")