ssot-mcp 0.1.1.dev2__tar.gz

ssot_mcp-0.1.1.dev2/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: ssot-mcp
+Version: 0.1.1.dev2
+Summary: MCP server for optional SSOT pull-worker control-plane coordination.
+Author-email: Jacob Stewart <jacob@swarmauri.com>
+License-Expression: Apache-2.0
+Keywords: ssot,mcp,workers,leases,control-plane
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: ssot-core<0.3.0,>=0.2.19.dev2
+
+# ssot-mcp
+
+Optional MCP server for SSOT pull-worker coordination. Workers still pull work
+through `claim_next_maturation_slice`; pushed update notifications only wake,
+pause, refresh, or stop workers.
+
+The core `ssot` CLI and `.ssot/registry.json` workflows do not require this
+package. Deploy `ssot-mcp` only when a Codex/MCP client should coordinate
+campaigns, leases, worker events, and registry writes through MCP tools.
+
+Run one pinned server per repository in normal use:
+
+```powershell
+ssot-mcp --transport stdio --repo E:\swarmauri_github\ssot-registry
+```
+
+Run global/dev mode only when callers must pass an explicit `repo` argument on
+every tool/resource call:
+
+```powershell
+ssot-mcp --transport stdio --repo-mode explicit
+```
+
+See [Codex MCP configuration](../../docs/coordination/codex-mcp.md) for Codex
+`config.toml` examples.
+
+## Registry write authority
+
+Workers must not hand-edit `.ssot/registry.json`. When a worker needs SSOT
+entity changes, it asks `ssot-mcp` to perform the mutation through one of the
+registry tools:
+
+- `get_blocked_transitions`
+- `scaffold_target_claim_wiring`
+- `repair_blocked_transition`
+- `registry_entity_get`
+- `registry_entity_list`
+- `registry_entity_search`
+- `registry_entity_upsert`
+- `registry_entity_delete`
+- `registry_entity_link`
+- `registry_entity_unlink`
+- `get_ssot_cli_surface`
+- `run_ssot_cli`
+
+The structured entity tools use the same core registry mutation APIs as the
+CLI, validate the registry before saving, and emit `registry_updated` events.
+`run_ssot_cli` delegates to the repo-local CLI parser in-process for command
+coverage that is not yet exposed as a dedicated MCP tool. It supports global
+flags, help/version requests, commands, subcommands, command flags, and
+subcommand flags as argv tokens. `get_ssot_cli_surface` returns the live CLI
+surface (`global_flags`, `top_level_commands`, `subcommand_paths`, and
+`flags_by_path`) so workers can discover the exact supported command shape
+before calling `run_ssot_cli`. Help and invalid-argument parser exits are
+captured as normal tool results; they must not close the MCP transport.
+
+Campaign claims can also be scoped instead of running over every active
+in-bounds feature. `claim_next_maturation_slice` accepts `feature_ids`,
+`profile_ids`, and `boundary_ids`; unscoped campaigns consider 25 in-bounds
+active features by default, and operators can raise `feature_limit` explicitly
+for broader campaigns. Out-of-bounds features are filtered from assignment and
+campaign status output. It caps blocker discovery with `max_blockers_per_claim`;
+and auto-scaffolding is enabled by default so
+`ssot-mcp` attempts target-tier claim/test/evidence scaffolding before returning
+a blocked result. Pass `auto_scaffold=false` only when intentionally testing or
+observing raw blocked-transition behavior. When a claim response returns
+`kind="blocked"`, it includes a top-level `reason` and a structured
+`problem_detail` with blocker rows and recommended MCP tool calls such as
+`repair_blocked_transition` or `scaffold_target_claim_wiring`; workers should
+perform those repairs and then pull again.

ssot_mcp-0.1.1.dev2/README.md

@@ -0,0 +1,70 @@
+# ssot-mcp
+
+Optional MCP server for SSOT pull-worker coordination. Workers still pull work
+through `claim_next_maturation_slice`; pushed update notifications only wake,
+pause, refresh, or stop workers.
+
+The core `ssot` CLI and `.ssot/registry.json` workflows do not require this
+package. Deploy `ssot-mcp` only when a Codex/MCP client should coordinate
+campaigns, leases, worker events, and registry writes through MCP tools.
+
+Run one pinned server per repository in normal use:
+
+```powershell
+ssot-mcp --transport stdio --repo E:\swarmauri_github\ssot-registry
+```
+
+Run global/dev mode only when callers must pass an explicit `repo` argument on
+every tool/resource call:
+
+```powershell
+ssot-mcp --transport stdio --repo-mode explicit
+```
+
+See [Codex MCP configuration](../../docs/coordination/codex-mcp.md) for Codex
+`config.toml` examples.
+
+## Registry write authority
+
+Workers must not hand-edit `.ssot/registry.json`. When a worker needs SSOT
+entity changes, it asks `ssot-mcp` to perform the mutation through one of the
+registry tools:
+
+- `get_blocked_transitions`
+- `scaffold_target_claim_wiring`
+- `repair_blocked_transition`
+- `registry_entity_get`
+- `registry_entity_list`
+- `registry_entity_search`
+- `registry_entity_upsert`
+- `registry_entity_delete`
+- `registry_entity_link`
+- `registry_entity_unlink`
+- `get_ssot_cli_surface`
+- `run_ssot_cli`
+
+The structured entity tools use the same core registry mutation APIs as the
+CLI, validate the registry before saving, and emit `registry_updated` events.
+`run_ssot_cli` delegates to the repo-local CLI parser in-process for command
+coverage that is not yet exposed as a dedicated MCP tool. It supports global
+flags, help/version requests, commands, subcommands, command flags, and
+subcommand flags as argv tokens. `get_ssot_cli_surface` returns the live CLI
+surface (`global_flags`, `top_level_commands`, `subcommand_paths`, and
+`flags_by_path`) so workers can discover the exact supported command shape
+before calling `run_ssot_cli`. Help and invalid-argument parser exits are
+captured as normal tool results; they must not close the MCP transport.
+
+Campaign claims can also be scoped instead of running over every active
+in-bounds feature. `claim_next_maturation_slice` accepts `feature_ids`,
+`profile_ids`, and `boundary_ids`; unscoped campaigns consider 25 in-bounds
+active features by default, and operators can raise `feature_limit` explicitly
+for broader campaigns. Out-of-bounds features are filtered from assignment and
+campaign status output. It caps blocker discovery with `max_blockers_per_claim`;
+and auto-scaffolding is enabled by default so
+`ssot-mcp` attempts target-tier claim/test/evidence scaffolding before returning
+a blocked result. Pass `auto_scaffold=false` only when intentionally testing or
+observing raw blocked-transition behavior. When a claim response returns
+`kind="blocked"`, it includes a top-level `reason` and a structured
+`problem_detail` with blocker rows and recommended MCP tool calls such as
+`repair_blocked_transition` or `scaffold_target_claim_wiring`; workers should
+perform those repairs and then pull again.

ssot_mcp-0.1.1.dev2/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ssot-mcp"
+version = "0.1.1.dev2"
+description = "MCP server for optional SSOT pull-worker control-plane coordination."
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "Apache-2.0"
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
+dependencies = [
+  "mcp>=1.0",
+  "ssot-core>=0.2.19.dev2,<0.3.0",
+]
+keywords = ["ssot", "mcp", "workers", "leases", "control-plane"]
+
+[project.scripts]
+ssot-mcp = "ssot_mcp.server:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

ssot_mcp-0.1.1.dev2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ssot_mcp-0.1.1.dev2/src/ssot_mcp/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

ssot_mcp-0.1.1.dev2/src/ssot_mcp/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .server import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ssot_mcp-0.1.1.dev2/src/ssot_mcp/resources.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ssot_registry.api.load import load_registry
+from ssot_registry.control.service import ControlPlane
+from ssot_registry.maturation.selector import next_maturation_slice
+
+from .tools import resolve_repo
+
+
+def registry_resource(repo: str | None = None) -> dict[str, Any]:
+    _registry_path, _repo_root, registry = load_registry(resolve_repo(repo))
+    return registry
+
+
+def campaign_status_resource(repo: str | None = None, campaign_id: str = "") -> dict[str, Any]:
+    return ControlPlane(resolve_repo(repo)).get_campaign_status(campaign_id, target_tier="T2")
+
+
+def maturation_queue_resource(repo: str | None = None) -> dict[str, Any]:
+    _registry_path, repo_root, registry = load_registry(resolve_repo(repo))
+    return {"next_slice": next_maturation_slice(registry, target_tier="T2", repo_root=repo_root)}

ssot_mcp-0.1.1.dev2/src/ssot_mcp/server.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from . import resources, tools
+
+
+def build_server() -> Any:
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ModuleNotFoundError as exc:  # pragma: no cover - exercised when optional dependency is absent.
+        raise RuntimeError("ssot-mcp requires the official `mcp` Python package. Install the ssot-mcp extra/package.") from exc
+
+    mcp = FastMCP("ssot-mcp")
+
+    mcp.tool()(tools.claim_next_maturation_slice)
+    mcp.tool()(tools.renew_lease)
+    mcp.tool()(tools.get_slice_context)
+    mcp.tool()(tools.complete_slice)
+    mcp.tool()(tools.abandon_slice)
+    mcp.tool()(tools.get_campaign_status)
+    mcp.tool()(tools.get_ssot_cli_surface)
+    mcp.tool()(tools.get_worker_events)
+    mcp.tool()(tools.ack_worker_events)
+    mcp.tool()(tools.get_conflicts)
+    mcp.tool()(tools.get_blocked_transitions)
+    mcp.tool()(tools.scaffold_target_claim_wiring)
+    mcp.tool()(tools.repair_blocked_transition)
+    mcp.tool()(tools.repair_blocked_transitions)
+    mcp.tool()(tools.registry_entity_get)
+    mcp.tool()(tools.registry_entity_list)
+    mcp.tool()(tools.registry_entity_search)
+    mcp.tool()(tools.registry_entity_upsert)
+    mcp.tool()(tools.registry_entity_delete)
+    mcp.tool()(tools.registry_entity_link)
+    mcp.tool()(tools.registry_entity_unlink)
+    mcp.tool()(tools.run_ssot_cli)
+
+    mcp.resource("ssot://registry/{repo}")(resources.registry_resource)
+    mcp.resource("ssot://campaign/{repo}/{campaign_id}")(resources.campaign_status_resource)
+    mcp.resource("ssot://maturation-queue/{repo}")(resources.maturation_queue_resource)
+
+    return mcp
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run the optional SSOT pull-worker MCP server.")
+    parser.add_argument("--transport", default="stdio", choices=["stdio", "sse"])
+    parser.add_argument("--repo", default=None, help="Pin this MCP server instance to one SSOT repository root.")
+    parser.add_argument(
+        "--repo-mode",
+        choices=["explicit"],
+        default=None,
+        help="Run as a global/dev server where every tool call must pass an explicit repo argument.",
+    )
+    args = parser.parse_args(argv)
+    if args.repo is not None and args.repo_mode is not None:
+        parser.error("--repo and --repo-mode explicit are mutually exclusive")
+    if args.repo is None and args.repo_mode != "explicit":
+        parser.error("choose either --repo <path> for a pinned server or --repo-mode explicit for dev/testing")
+    tools.configure_repo(args.repo)
+    server = build_server()
+    server.run(transport=args.transport)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ssot_mcp-0.1.1.dev2/src/ssot_mcp/tools.py

@@ -0,0 +1,445 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import argparse
+from pathlib import Path
+from threading import RLock
+from typing import Any
+
+from ssot_cli.main import build_parser, main as ssot_cli_main
+from ssot_registry.version import __version__ as SSOT_CORE_VERSION
+from ssot_registry.api.entity_ops import (
+    SECTIONS,
+    create_entity,
+    delete_entity,
+    get_entity,
+    link_entities,
+    list_entities,
+    unlink_entities,
+    update_entity,
+)
+from ssot_registry.control.service import ControlPlane
+
+_PINNED_REPO: Path | None = None
+_CLI_LOCK = RLock()
+
+
+def configure_repo(repo: str | Path | None) -> None:
+    global _PINNED_REPO
+    _PINNED_REPO = Path(repo).resolve() if repo is not None else None
+
+
+def resolve_repo(repo: str | None = None) -> Path:
+    if _PINNED_REPO is None:
+        if repo is None:
+            raise ValueError("repo is required unless ssot-mcp is started with --repo")
+        return Path(repo).resolve()
+    if repo is not None and Path(repo).resolve() != _PINNED_REPO:
+        raise ValueError(f"ssot-mcp is pinned to {_PINNED_REPO}; refusing repo {Path(repo).resolve()}")
+    return _PINNED_REPO
+
+
+def _plane(repo: str | None = None) -> ControlPlane:
+    return ControlPlane(resolve_repo(repo))
+
+
+def _notify_registry_updated(repo_root: Path, payload: dict[str, Any]) -> None:
+    ControlPlane(repo_root).notify_registry_updated(payload=payload)
+
+
+def _section_name(section: str) -> str:
+    normalized = section.strip().lower().replace("-", "_")
+    aliases = {
+        "feature": "features",
+        "profile": "profiles",
+        "test": "tests",
+        "claim": "claims",
+        "evidence": "evidence",
+        "issue": "issues",
+        "risk": "risks",
+        "boundary": "boundaries",
+        "release": "releases",
+    }
+    normalized = aliases.get(normalized, normalized)
+    if normalized not in SECTIONS:
+        raise ValueError(f"unsupported registry section: {section}")
+    return normalized
+
+
+def _matches_query(row: dict[str, Any], query: str) -> bool:
+    needle = query.lower()
+    haystack = json.dumps(row, sort_keys=True, default=str).lower()
+    return needle in haystack
+
+
+def _cli_root_command(args: list[str]) -> str:
+    skip_value_for = {"--output-format", "--output-file"}
+    skip_next = False
+    for token in args:
+        if skip_next:
+            skip_next = False
+            continue
+        if token in skip_value_for:
+            skip_next = True
+            continue
+        if token.startswith("-"):
+            continue
+        return token
+    return ""
+
+
+def _option_flags(parser: argparse.ArgumentParser) -> list[str]:
+    flags: list[str] = []
+    for action in parser._actions:
+        if isinstance(action, argparse._HelpAction):
+            continue
+        for option in action.option_strings:
+            if option not in flags:
+                flags.append(option)
+    return sorted(flags)
+
+
+def _walk_parser(
+    parser: argparse.ArgumentParser,
+    path: list[str],
+    subcommand_paths: list[str],
+    flags_by_path: dict[str, list[str]],
+) -> None:
+    if path:
+        path_key = " ".join(path)
+        subcommand_paths.append(path_key)
+        flags_by_path[path_key] = _option_flags(parser)
+
+    for action in parser._actions:
+        if not isinstance(action, argparse._SubParsersAction):
+            continue
+        for name, child_parser in sorted(action.choices.items()):
+            _walk_parser(child_parser, [*path, name], subcommand_paths, flags_by_path)
+
+
+def _cli_surface() -> dict[str, Any]:
+    parser = build_parser(prog="ssot-registry")
+    top_level_commands: list[str] = []
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            top_level_commands = sorted(action.choices.keys())
+            break
+
+    subcommand_paths: list[str] = []
+    flags_by_path: dict[str, list[str]] = {}
+    _walk_parser(parser, [], subcommand_paths, flags_by_path)
+    return {
+        "top_level_commands": top_level_commands,
+        "subcommand_paths": sorted(subcommand_paths),
+        "global_flags": _option_flags(parser),
+        "flags_by_path": {key: flags_by_path[key] for key in sorted(flags_by_path)},
+    }
+
+
+def _is_cli_metadata_request(args: list[str]) -> bool:
+    return not args or any(token in {"-h", "--help", "--version"} for token in args)
+
+
+def _resolve_repo_for_cli(repo: str | None, args: list[str]) -> Path:
+    if repo is not None or _PINNED_REPO is not None:
+        return resolve_repo(repo)
+    if _is_cli_metadata_request(args):
+        return Path.cwd()
+    return resolve_repo(repo)
+
+
+def _normalize_mcp_cli_args(args: list[str]) -> tuple[list[str], list[str]]:
+    """Normalize delegated CLI calls that are unsafe or ambiguous for MCP workers."""
+
+    if _cli_root_command(args) != "upgrade":
+        return list(args), []
+
+    normalized: list[str] = []
+    warnings: list[str] = []
+    skip_next = False
+    saw_sync_docs = False
+    for token in args:
+        if skip_next:
+            skip_next = False
+            warnings.append(
+                "MCP upgrade ignores --target-version and uses the currently running ssot-mcp binary/runtime instead."
+            )
+            continue
+        if token == "--target-version":
+            skip_next = True
+            continue
+        if token.startswith("--target-version="):
+            warnings.append(
+                "MCP upgrade ignores --target-version and uses the currently running ssot-mcp binary/runtime instead."
+            )
+            continue
+        if token == "--sync-docs":
+            saw_sync_docs = True
+        normalized.append(token)
+
+    if not saw_sync_docs:
+        normalized.append("--sync-docs")
+        warnings.append("MCP upgrade added --sync-docs so packaged ADR/SPEC documents are refreshed with the current runtime.")
+
+    warnings.append(f"MCP upgrade is running with installed ssot-core version {SSOT_CORE_VERSION}.")
+    return normalized, warnings
+
+
+@contextlib.contextmanager
+def _cwd(path: Path):
+    previous = Path.cwd()
+    os.chdir(path)
+    try:
+        yield
+    finally:
+        os.chdir(previous)
+
+
+def claim_next_maturation_slice(
+    repo: str | None = None,
+    worker_id: str = "",
+    campaign_id: str = "",
+    target_tier: str = "T2",
+    os_user: str | None = None,
+    ttl_seconds: int = 1800,
+    feature_ids: list[str] | None = None,
+    profile_ids: list[str] | None = None,
+    boundary_ids: list[str] | None = None,
+    max_blockers_per_claim: int = 5,
+    auto_scaffold: bool = True,
+    feature_limit: int | None = 25,
+) -> dict[str, Any]:
+    return _plane(repo).claim_next_maturation_slice(
+        worker_id=worker_id,
+        campaign_id=campaign_id,
+        target_tier=target_tier,
+        os_user=os_user,
+        ttl_seconds=ttl_seconds,
+        feature_ids=feature_ids,
+        profile_ids=profile_ids,
+        boundary_ids=boundary_ids,
+        max_blockers_per_claim=max_blockers_per_claim,
+        auto_scaffold=auto_scaffold,
+        feature_limit=feature_limit,
+    )
+
+
+def renew_lease(repo: str | None = None, worker_id: str = "", lease_id: str = "", fencing_token: int = 0, ttl_seconds: int = 1800) -> dict[str, Any]:
+    return _plane(repo).renew_lease(
+        worker_id=worker_id,
+        lease_id=lease_id,
+        fencing_token=fencing_token,
+        ttl_seconds=ttl_seconds,
+    )
+
+
+def get_slice_context(repo: str | None = None, lease_id: str = "") -> dict[str, Any]:
+    return _plane(repo).get_slice_context(lease_id)
+
+
+def complete_slice(repo: str | None = None, worker_id: str = "", lease_id: str = "", fencing_token: int = 0, result: dict[str, Any] | None = None) -> dict[str, Any]:
+    if result is None:
+        result = {}
+    return _plane(repo).complete_slice(worker_id=worker_id, lease_id=lease_id, fencing_token=fencing_token, result=result)
+
+
+def abandon_slice(repo: str | None = None, worker_id: str = "", lease_id: str = "", fencing_token: int = 0, reason: str = "") -> dict[str, Any]:
+    return _plane(repo).abandon_slice(worker_id=worker_id, lease_id=lease_id, fencing_token=fencing_token, reason=reason)
+
+
+def get_campaign_status(repo: str | None = None, campaign_id: str = "", target_tier: str = "T2", feature_limit: int | None = None) -> dict[str, Any]:
+    return _plane(repo).get_campaign_status(campaign_id, target_tier=target_tier, feature_limit=feature_limit)
+
+
+def get_worker_events(
+    repo: str | None = None,
+    worker_id: str | None = None,
+    campaign_id: str | None = None,
+    after_event_id: int = 0,
+    limit: int = 100,
+) -> dict[str, Any]:
+    return _plane(repo).get_worker_events(
+        worker_id=worker_id,
+        campaign_id=campaign_id,
+        after_event_id=after_event_id,
+        limit=limit,
+    )
+
+
+def ack_worker_events(repo: str | None = None, worker_id: str = "", event_ids: list[int] | None = None, action: str = "processed") -> dict[str, Any]:
+    if event_ids is None:
+        event_ids = []
+    return _plane(repo).ack_worker_events(worker_id=worker_id, event_ids=event_ids, action=action)
+
+
+def get_conflicts(repo: str | None = None, status: str | None = "open") -> dict[str, Any]:
+    return _plane(repo).get_conflicts(status=status)
+
+
+def get_ssot_cli_surface(repo: str | None = None) -> dict[str, Any]:
+    if repo is not None or _PINNED_REPO is not None:
+        _resolve_repo_for_cli(repo, ["--help"])
+    surface = _cli_surface()
+    return {"passed": True, **surface}
+
+
+def get_blocked_transitions(repo: str | None = None, campaign_id: str | None = None, status: str | None = "open") -> dict[str, Any]:
+    return {"passed": True, "blocked_transitions": _plane(repo).store.get_blocked_transitions(campaign_id=campaign_id, status=status)}
+
+
+def scaffold_target_claim_wiring(repo: str | None = None, feature_id: str = "", target_tier: str = "T1") -> dict[str, Any]:
+    return _plane(repo).scaffold_target_claim_wiring(feature_id=feature_id, target_tier=target_tier)
+
+
+def repair_blocked_transition(repo: str | None = None, blocked_id: str = "") -> dict[str, Any]:
+    return _plane(repo).repair_blocked_transition(blocked_id=blocked_id)
+
+
+def repair_blocked_transitions(
+    repo: str | None = None,
+    campaign_id: str | None = None,
+    feature_ids: list[str] | None = None,
+    limit: int = 25,
+) -> dict[str, Any]:
+    return _plane(repo).repair_blocked_transitions(campaign_id=campaign_id, feature_ids=feature_ids, limit=limit)
+
+
+def registry_entity_get(repo: str | None = None, section: str = "", entity_id: str = "") -> dict[str, Any]:
+    repo_root = resolve_repo(repo)
+    resolved_section = _section_name(section)
+    return {"passed": True, "section": resolved_section, "entity": get_entity(repo_root, resolved_section, entity_id)}
+
+
+def registry_entity_list(
+    repo: str | None = None,
+    section: str = "",
+    ids: list[str] | None = None,
+    origin: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+) -> dict[str, Any]:
+    repo_root = resolve_repo(repo)
+    resolved_section = _section_name(section)
+    rows = list_entities(repo_root, resolved_section, ids=ids, origin=origin)
+    total = len(rows)
+    limited = rows[max(offset, 0) : max(offset, 0) + max(limit, 0)]
+    return {"passed": True, "section": resolved_section, "total": total, "offset": offset, "limit": limit, "entities": limited}
+
+
+def registry_entity_search(repo: str | None = None, section: str = "", query: str = "", limit: int = 100, offset: int = 0) -> dict[str, Any]:
+    repo_root = resolve_repo(repo)
+    resolved_section = _section_name(section)
+    rows = [row for row in list_entities(repo_root, resolved_section) if _matches_query(row, query)]
+    total = len(rows)
+    limited = rows[max(offset, 0) : max(offset, 0) + max(limit, 0)]
+    return {"passed": True, "section": resolved_section, "query": query, "total": total, "offset": offset, "limit": limit, "entities": limited}
+
+
+def registry_entity_upsert(repo: str | None = None, section: str = "", entity: dict[str, Any] | None = None) -> dict[str, Any]:
+    if entity is None:
+        entity = {}
+    repo_root = resolve_repo(repo)
+    resolved_section = _section_name(section)
+    entity_id = entity.get("id")
+    if not isinstance(entity_id, str) or not entity_id:
+        raise ValueError("entity.id is required")
+    try:
+        existing = get_entity(repo_root, resolved_section, entity_id)
+    except ValueError:
+        result = create_entity(repo_root, resolved_section, entity)
+        action = "create"
+    else:
+        result = update_entity(repo_root, resolved_section, entity_id, entity)
+        action = "update"
+        result["previous_entity"] = existing
+    _notify_registry_updated(repo_root, {"source": "ssot-mcp", "tool": "registry_entity_upsert", "section": resolved_section, "entity_id": entity_id, "action": action})
+    return result
+
+
+def registry_entity_delete(repo: str | None = None, section: str = "", entity_id: str = "") -> dict[str, Any]:
+    repo_root = resolve_repo(repo)
+    resolved_section = _section_name(section)
+    result = delete_entity(repo_root, resolved_section, entity_id)
+    _notify_registry_updated(repo_root, {"source": "ssot-mcp", "tool": "registry_entity_delete", "section": resolved_section, "entity_id": entity_id})
+    return result
+
+
+def registry_entity_link(repo: str | None = None, section: str = "", entity_id: str = "", links: dict[str, list[str]] | None = None) -> dict[str, Any]:
+    repo_root = resolve_repo(repo)
+    resolved_section = _section_name(section)
+    result = link_entities(repo_root, resolved_section, entity_id, links or {})
+    _notify_registry_updated(repo_root, {"source": "ssot-mcp", "tool": "registry_entity_link", "section": resolved_section, "entity_id": entity_id, "links": links or {}})
+    return result
+
+
+def registry_entity_unlink(repo: str | None = None, section: str = "", entity_id: str = "", links: dict[str, list[str]] | None = None) -> dict[str, Any]:
+    repo_root = resolve_repo(repo)
+    resolved_section = _section_name(section)
+    result = unlink_entities(repo_root, resolved_section, entity_id, links or {})
+    _notify_registry_updated(repo_root, {"source": "ssot-mcp", "tool": "registry_entity_unlink", "section": resolved_section, "entity_id": entity_id, "links": links or {}})
+    return result
+
+
+def run_ssot_cli(repo: str | None = None, args: list[str] | None = None) -> dict[str, Any]:
+    """Run the SSOT CLI in-process against the resolved repo root.
+
+    The server changes cwd to the target repo for the duration of the call so
+    normal CLI commands using the default `.` path operate on the MCP-selected
+    registry. Arguments are argv tokens after `ssot`.
+    """
+
+    original_args = list(args or [])
+    normalized_args, normalization_warnings = _normalize_mcp_cli_args(original_args)
+    repo_root = _resolve_repo_for_cli(repo, normalized_args)
+    argv = list(normalized_args)
+    metadata_request = _is_cli_metadata_request(argv)
+    if "--output-format" not in argv and not metadata_request:
+        argv = ["--output-format", "json", *argv]
+    stdout = io.StringIO()
+    stderr = io.StringIO()
+    with _CLI_LOCK:
+        with _cwd(repo_root), contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            try:
+                exit_code = ssot_cli_main(argv)
+            except SystemExit as exc:
+                code = exc.code
+                exit_code = int(code) if isinstance(code, int) else 1
+    stdout_text = stdout.getvalue()
+    stderr_text = stderr.getvalue()
+    try:
+        payload: Any = json.loads(stdout_text) if stdout_text.strip() else None
+    except json.JSONDecodeError:
+        payload = stdout_text
+    mutating_roots = {
+        "init",
+        "upgrade",
+        "config",
+        "adr",
+        "spec",
+        "feature",
+        "profile",
+        "test",
+        "issue",
+        "claim",
+        "evidence",
+        "risk",
+        "boundary",
+        "release",
+        "registry",
+    }
+    command = _cli_root_command(original_args)
+    if exit_code == 0 and command in mutating_roots:
+        _notify_registry_updated(repo_root, {"source": "ssot-mcp", "tool": "run_ssot_cli", "args": original_args, "normalized_args": normalized_args})
+    return {
+        "passed": exit_code == 0,
+        "exit_code": exit_code,
+        "args": original_args,
+        "normalized_args": normalized_args,
+        "warnings": normalization_warnings,
+        "output": payload,
+        "stdout": stdout_text,
+        "stderr": stderr_text,
+    }

ssot_mcp-0.1.1.dev2/src/ssot_mcp.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: ssot-mcp
+Version: 0.1.1.dev2
+Summary: MCP server for optional SSOT pull-worker control-plane coordination.
+Author-email: Jacob Stewart <jacob@swarmauri.com>
+License-Expression: Apache-2.0
+Keywords: ssot,mcp,workers,leases,control-plane
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: ssot-core<0.3.0,>=0.2.19.dev2
+
+# ssot-mcp
+
+Optional MCP server for SSOT pull-worker coordination. Workers still pull work
+through `claim_next_maturation_slice`; pushed update notifications only wake,
+pause, refresh, or stop workers.
+
+The core `ssot` CLI and `.ssot/registry.json` workflows do not require this
+package. Deploy `ssot-mcp` only when a Codex/MCP client should coordinate
+campaigns, leases, worker events, and registry writes through MCP tools.
+
+Run one pinned server per repository in normal use:
+
+```powershell
+ssot-mcp --transport stdio --repo E:\swarmauri_github\ssot-registry
+```
+
+Run global/dev mode only when callers must pass an explicit `repo` argument on
+every tool/resource call:
+
+```powershell
+ssot-mcp --transport stdio --repo-mode explicit
+```
+
+See [Codex MCP configuration](../../docs/coordination/codex-mcp.md) for Codex
+`config.toml` examples.
+
+## Registry write authority
+
+Workers must not hand-edit `.ssot/registry.json`. When a worker needs SSOT
+entity changes, it asks `ssot-mcp` to perform the mutation through one of the
+registry tools:
+
+- `get_blocked_transitions`
+- `scaffold_target_claim_wiring`
+- `repair_blocked_transition`
+- `registry_entity_get`
+- `registry_entity_list`
+- `registry_entity_search`
+- `registry_entity_upsert`
+- `registry_entity_delete`
+- `registry_entity_link`
+- `registry_entity_unlink`
+- `get_ssot_cli_surface`
+- `run_ssot_cli`
+
+The structured entity tools use the same core registry mutation APIs as the
+CLI, validate the registry before saving, and emit `registry_updated` events.
+`run_ssot_cli` delegates to the repo-local CLI parser in-process for command
+coverage that is not yet exposed as a dedicated MCP tool. It supports global
+flags, help/version requests, commands, subcommands, command flags, and
+subcommand flags as argv tokens. `get_ssot_cli_surface` returns the live CLI
+surface (`global_flags`, `top_level_commands`, `subcommand_paths`, and
+`flags_by_path`) so workers can discover the exact supported command shape
+before calling `run_ssot_cli`. Help and invalid-argument parser exits are
+captured as normal tool results; they must not close the MCP transport.
+
+Campaign claims can also be scoped instead of running over every active
+in-bounds feature. `claim_next_maturation_slice` accepts `feature_ids`,
+`profile_ids`, and `boundary_ids`; unscoped campaigns consider 25 in-bounds
+active features by default, and operators can raise `feature_limit` explicitly
+for broader campaigns. Out-of-bounds features are filtered from assignment and
+campaign status output. It caps blocker discovery with `max_blockers_per_claim`;
+and auto-scaffolding is enabled by default so
+`ssot-mcp` attempts target-tier claim/test/evidence scaffolding before returning
+a blocked result. Pass `auto_scaffold=false` only when intentionally testing or
+observing raw blocked-transition behavior. When a claim response returns
+`kind="blocked"`, it includes a top-level `reason` and a structured
+`problem_detail` with blocker rows and recommended MCP tool calls such as
+`repair_blocked_transition` or `scaffold_target_claim_wiring`; workers should
+perform those repairs and then pull again.

ssot_mcp-0.1.1.dev2/src/ssot_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/ssot_mcp/__init__.py
+src/ssot_mcp/__main__.py
+src/ssot_mcp/resources.py
+src/ssot_mcp/server.py
+src/ssot_mcp/tools.py
+src/ssot_mcp.egg-info/PKG-INFO
+src/ssot_mcp.egg-info/SOURCES.txt
+src/ssot_mcp.egg-info/dependency_links.txt
+src/ssot_mcp.egg-info/entry_points.txt
+src/ssot_mcp.egg-info/requires.txt
+src/ssot_mcp.egg-info/top_level.txt

ssot_mcp-0.1.1.dev2/src/ssot_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ssot_mcp-0.1.1.dev2/src/ssot_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ssot-mcp = ssot_mcp.server:main

ssot_mcp-0.1.1.dev2/src/ssot_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp>=1.0
+ssot-core<0.3.0,>=0.2.19.dev2

ssot_mcp-0.1.1.dev2/src/ssot_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+ssot_mcp