commitlayer-mcp-recorder 0.1.0__py3-none-any.whl

commitlayer_mcp_recorder/__init__.py

@@ -0,0 +1,468 @@
+"""CommitLayer MCP Recorder: a stdio proxy that records an agent's MCP tool calls as CommitLayer actions.
+
+The recorder sits between an MCP client (Claude Desktop, Claude Code, Cursor, an agent framework) and any
+downstream MCP server. Every JSON-RPC message is forwarded unchanged in both directions. When the client
+calls a tool that the mapping file names (``tools/call``), the intent is recorded as a CommitLayer action
+**before** the call is forwarded, so the request time precedes every effect::
+
+    commitlayer-mcp-recorder --map mapping.json -- npx -y @stripe/mcp --tools=all
+
+The downstream result is never treated as proof: CommitLayer verifies from the systems of record. Recording
+is fail-open by default: if the API cannot be reached the call is forwarded anyway and a warning goes to
+stderr. The recorder never blocks, reorders or alters the agent's traffic.
+
+Standard library only. ``load_mapping`` reads the mapping file, ``build_action`` turns one ``tools/call`` into
+an action body and ``Recorder`` holds the policy (key, URL, fail-open) and the request ids still waiting for
+a downstream answer.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "DEFAULT_API_URL",
+    "JSONRPC_RECORDING_FAILED",
+    "LOG_PREFIX",
+    "Decision",
+    "Mapping",
+    "MappingError",
+    "Recorder",
+    "RecordingError",
+    "ToolMapping",
+    "UnresolvedPath",
+    "__version__",
+    "build_action",
+    "load_mapping",
+    "log_to_stderr",
+    "post_action",
+    "resolve_path",
+]
+__version__ = "0.1.0"
+
+DEFAULT_API_URL = "https://api.commitlayer.ai"
+LOG_PREFIX = "commitlayer-recorder: "
+JSONRPC_RECORDING_FAILED = -32000
+
+Logger = Callable[[str], None]
+Transport = Callable[[dict[str, Any]], dict[str, Any]]
+
+_TEMPLATE_FIELD = re.compile(r"\{([^{}]+)\}")
+_TOOL_STRING_FIELDS = ("action_type", "subject_kind", "action_id", "compensates")
+
+
+def log_to_stderr(message: str) -> None:
+    """Write one diagnostic line to stderr. Every line the recorder emits carries ``LOG_PREFIX``."""
+    sys.stderr.write(f"{LOG_PREFIX}{message}\n")
+    sys.stderr.flush()
+
+
+class MappingError(ValueError):
+    """The mapping file is missing, unreadable or does not describe tools the recorder can use."""
+
+
+class UnresolvedPath(LookupError):
+    """A path the mapping needs (the subject, a template field) is absent from the ``tools/call`` params."""
+
+    def __init__(self, path: str):
+        super().__init__(path)
+        self.path = path
+
+    def __str__(self) -> str:
+        return self.path
+
+
+class RecordingError(RuntimeError):
+    """The API refused the action (HTTP 4xx/5xx) or could not be reached."""
+
+
+# ---------------- mapping ----------------
+
+
+@dataclass(frozen=True)
+class ToolMapping:
+    """How one MCP tool becomes an action. Paths are dotted paths into the ``tools/call`` params object
+    (``arguments.order_id``, ``name``, ``_meta.progressToken``)."""
+
+    contract_id: str
+    subject: str
+    action_type: str | None = None
+    subject_kind: str | None = None
+    contract_version: int | None = None
+    params: dict[str, str] = field(default_factory=dict)
+    action_id: str | None = None
+    compensates: str | None = None
+
+
+@dataclass(frozen=True)
+class Mapping:
+    tools: dict[str, ToolMapping]
+    agent_id: str | None = None
+    workflow_id: str | None = None
+
+    def lookup(self, tool_name: str) -> ToolMapping | None:
+        """The mapping for ``tool_name``: an exact key first, then a key carrying a server prefix
+        (``stripe.refund_payment`` matches ``refund_payment``). Unmapped tools return ``None``."""
+        exact = self.tools.get(tool_name)
+        if exact is not None:
+            return exact
+        for key, tool in self.tools.items():
+            _prefix, sep, bare = key.rpartition(".")
+            if sep and bare == tool_name:
+                return tool
+        return None
+
+
+def _optional_str(value: Any, where: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value:
+        raise MappingError(f"{where} must be a non-empty string")
+    return value
+
+
+def _required_str(obj: dict[str, Any], key: str, where: str) -> str:
+    if key not in obj:
+        raise MappingError(f"{where} is missing required key {key!r}")
+    value = obj[key]
+    if not isinstance(value, str) or not value:
+        raise MappingError(f"{where}.{key} must be a non-empty string")
+    return value
+
+
+def _tool_mapping(name: str, spec: Any) -> ToolMapping:
+    where = f"tools.{name}"
+    if not isinstance(spec, dict):
+        raise MappingError(f"{where} must be an object")
+    params_spec = spec.get("params") or {}
+    if not isinstance(params_spec, dict):
+        raise MappingError(f"{where}.params must be an object of name -> path")
+    params: dict[str, str] = {}
+    for param_name, path in params_spec.items():
+        if not isinstance(path, str) or not path:
+            raise MappingError(f"{where}.params.{param_name} must be a non-empty path string")
+        params[param_name] = path
+    version = spec.get("contract_version")
+    if version is not None and (not isinstance(version, int) or isinstance(version, bool)):
+        raise MappingError(f"{where}.contract_version must be an integer")
+    strings = {key: _optional_str(spec.get(key), f"{where}.{key}") for key in _TOOL_STRING_FIELDS}
+    return ToolMapping(
+        contract_id=_required_str(spec, "contract_id", where),
+        subject=_required_str(spec, "subject", where),
+        contract_version=version,
+        params=params,
+        **strings,
+    )
+
+
+def _read_mapping_file(path: Path) -> Any:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise MappingError(f"cannot read mapping file {path}: {e.strerror or e}") from e
+    if path.suffix.lower() in (".yaml", ".yml"):
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ImportError as e:
+            raise MappingError("YAML mappings need PyYAML (pip install pyyaml); JSON works without it") from e
+        try:
+            return yaml.safe_load(text)
+        except yaml.YAMLError as e:
+            raise MappingError(f"mapping file {path} is not valid YAML: {e}") from e
+    try:
+        return json.loads(text)
+    except ValueError as e:
+        raise MappingError(f"mapping file {path} is not valid JSON: {e}") from e
+
+
+def load_mapping(source: str | Path | dict[str, Any]) -> Mapping:
+    """Load and validate a mapping from a JSON file, a YAML file (when PyYAML is installed) or a dict.
+
+    Unknown keys are allowed. Every tool needs ``contract_id`` and ``subject``; ``params`` is an object of
+    parameter name to path; ``action_id`` is a template with ``{path}`` placeholders.
+    """
+    raw = source if isinstance(source, dict) else _read_mapping_file(Path(source))
+    if not isinstance(raw, dict):
+        raise MappingError("mapping must be an object with a 'tools' key")
+    tools_spec = raw.get("tools")
+    if not isinstance(tools_spec, dict) or not tools_spec:
+        raise MappingError("mapping needs a non-empty 'tools' object")
+    tools = {str(name): _tool_mapping(str(name), spec) for name, spec in tools_spec.items()}
+    return Mapping(
+        tools=tools,
+        agent_id=_optional_str(raw.get("agent_id"), "agent_id"),
+        workflow_id=_optional_str(raw.get("workflow_id"), "workflow_id"),
+    )
+
+
+# ---------------- action bodies ----------------
+
+
+def resolve_path(obj: Any, path: str) -> Any:
+    """Follow a dotted path through nested objects and lists. Raises ``UnresolvedPath`` when any step is
+    missing; a present ``null`` is returned as ``None``."""
+    current = obj
+    for part in path.split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        elif isinstance(current, list) and part.isdigit() and int(part) < len(current):
+            current = current[int(part)]
+        else:
+            raise UnresolvedPath(path)
+    return current
+
+
+def _render_template(template: str, call_params: dict[str, Any]) -> str:
+    def substitute(match: re.Match[str]) -> str:
+        value = resolve_path(call_params, match.group(1))
+        if value is None:
+            raise UnresolvedPath(match.group(1))
+        return str(value)
+
+    return _TEMPLATE_FIELD.sub(substitute, template)
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def build_action(
+    tool_name: str,
+    call_params: dict[str, Any],
+    tool: ToolMapping,
+    *,
+    request_id: Any,
+    agent_id: str | None = None,
+    workflow_id: str | None = None,
+    requested_at: str | None = None,
+) -> dict[str, Any]:
+    """The ``POST /v1/actions`` body for one ``tools/call``.
+
+    ``call_params`` is the ``params`` object of the JSON-RPC request (``name``, ``arguments``, ``_meta``).
+    ``params`` always carries ``mcp_tool`` and ``mcp_request_id``. The default ``action_id`` is
+    ``mcp:{tool}:{request id}``, so a retried request updates one record instead of creating two. Raises
+    ``UnresolvedPath`` when the subject or an ``action_id`` placeholder is absent from the call.
+    """
+    subject = resolve_path(call_params, tool.subject)
+    if subject is None or str(subject) == "":
+        raise UnresolvedPath(tool.subject)
+    params: dict[str, Any] = {}
+    for name, path in tool.params.items():
+        try:
+            params[name] = resolve_path(call_params, path)
+        except UnresolvedPath:
+            continue
+    params["mcp_tool"] = tool_name
+    params["mcp_request_id"] = str(request_id)
+    if tool.action_id is not None:
+        action_id = _render_template(tool.action_id, call_params)
+    else:
+        action_id = f"mcp:{tool_name}:{request_id}"
+    body: dict[str, Any] = {
+        "action_id": action_id,
+        "contract_id": tool.contract_id,
+        "subject_id": str(subject),
+        "requested_at": requested_at or _now(),
+        "params": params,
+        "channel": "mcp",
+    }
+    compensates: Any = None
+    if tool.compensates is not None:
+        try:
+            compensates = resolve_path(call_params, tool.compensates)
+        except UnresolvedPath:
+            compensates = None
+    for key, value in (
+        ("contract_version", tool.contract_version),
+        ("workflow_id", workflow_id),
+        ("agent_id", agent_id),
+        ("action_type", tool.action_type),
+        ("subject_kind", tool.subject_kind),
+        ("compensates", None if compensates is None else str(compensates)),
+    ):
+        if value is not None:
+            body[key] = value
+    return body
+
+
+# ---------------- transport ----------------
+
+
+def post_action(api_url: str, api_key: str, body: dict[str, Any], *, timeout: float = 5.0) -> dict[str, Any]:
+    """``POST {api_url}/v1/actions``. Returns the decoded response; raises ``RecordingError`` on HTTP 4xx/5xx
+    or when the API cannot be reached. The key is sent in ``x-api-key`` and never logged."""
+    req = urllib.request.Request(
+        api_url.rstrip("/") + "/v1/actions",
+        data=json.dumps(body).encode(),
+        method="POST",
+        headers={
+            "x-api-key": api_key,
+            "content-type": "application/json",
+            "accept": "application/json",
+            "user-agent": f"commitlayer-mcp-recorder/{__version__}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as response:  # noqa: S310 - operator-configured URL
+            raw = response.read()
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode(errors="replace")[:300]
+        raise RecordingError(f"HTTP {e.code} from {req.full_url}: {detail or e.reason}") from e
+    except (urllib.error.URLError, OSError, TimeoutError) as e:
+        reason = getattr(e, "reason", None) or e
+        raise RecordingError(f"cannot reach {req.full_url}: {reason}") from e
+    try:
+        return json.loads(raw) if raw else {}
+    except ValueError:
+        return {}
+
+
+# ---------------- recorder ----------------
+
+
+@dataclass(frozen=True)
+class Decision:
+    """What to do with one client message: forward it, or (fail-closed only) answer the client with
+    ``error`` instead. ``action_id`` is set when an action was recorded for the message."""
+
+    forward: bool = True
+    action_id: str | None = None
+    error: dict[str, Any] | None = None
+
+
+def _id_key(request_id: Any) -> str:
+    # JSON-RPC ids may be numbers or strings and ``1`` is not ``"1"``; key on the JSON encoding.
+    return json.dumps(request_id, sort_keys=True)
+
+
+class Recorder:
+    """Records mapped ``tools/call`` requests and matches downstream answers back to them.
+
+    ``before_forward`` is called with every parsed client message before it is sent downstream and
+    ``after_response`` with every parsed server message before it is sent back to the client. Both accept
+    anything ``json.loads`` can return and ignore what is not a JSON-RPC object. Without an API key the
+    recorder is a passthrough: nothing is posted. CLI flags for ``agent_id``/``workflow_id`` override the
+    mapping file.
+    """
+
+    def __init__(
+        self,
+        mapping: Mapping,
+        *,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        agent_id: str | None = None,
+        workflow_id: str | None = None,
+        timeout: float = 5.0,
+        fail_open: bool = True,
+        warn_unmapped: bool = False,
+        transport: Transport | None = None,
+        log: Logger = log_to_stderr,
+    ):
+        self.mapping = mapping
+        self.api_key = api_key or ""
+        self.api_url = (api_url or DEFAULT_API_URL).rstrip("/")
+        self.agent_id = agent_id or mapping.agent_id
+        self.workflow_id = workflow_id or mapping.workflow_id
+        self.timeout = timeout
+        self.fail_open = fail_open
+        self.warn_unmapped = warn_unmapped
+        self._transport = transport or self._post
+        self._has_custom_transport = transport is not None
+        self._log = log
+        self._lock = threading.Lock()
+        self._pending: dict[str, str] = {}
+        self._warned_unmapped: set[str] = set()
+
+    @property
+    def enabled(self) -> bool:
+        """``False`` without an API key: every call is forwarded and nothing is recorded."""
+        return bool(self.api_key) or self._has_custom_transport
+
+    def _post(self, body: dict[str, Any]) -> dict[str, Any]:
+        return post_action(self.api_url, self.api_key, body, timeout=self.timeout)
+
+    def before_forward(self, message: Any) -> Decision:
+        """Record the message if it is a mapped ``tools/call``; say whether to forward it."""
+        if not isinstance(message, dict) or message.get("method") != "tools/call":
+            return Decision()
+        call_params = message.get("params")
+        if not isinstance(call_params, dict) or not isinstance(call_params.get("name"), str):
+            return Decision()
+        tool_name: str = call_params["name"]
+        tool = self.mapping.lookup(tool_name)
+        if tool is None:
+            if self.warn_unmapped and tool_name not in self._warned_unmapped:
+                self._warned_unmapped.add(tool_name)
+                self._log(f"unmapped tool {tool_name!r} forwarded without recording")
+            return Decision()
+        if "id" not in message:
+            self._log(f"tools/call for {tool_name!r} has no JSON-RPC id; forwarded without recording")
+            return Decision()
+        if not self.enabled:
+            return Decision()
+        try:
+            body = build_action(
+                tool_name,
+                call_params,
+                tool,
+                request_id=message["id"],
+                agent_id=self.agent_id,
+                workflow_id=self.workflow_id,
+            )
+        except UnresolvedPath as e:
+            self._log(f"tool {tool_name!r} forwarded without recording: path {e} not found in the call")
+            return Decision()
+        action_id = body["action_id"]
+        try:
+            self._transport(body)
+        except Exception as e:  # noqa: BLE001 - any failure to record is handled by the fail-open policy
+            if self.fail_open:
+                self._log(f"action {action_id} not recorded ({e}); forwarding anyway")
+                return Decision()
+            self._log(f"action {action_id} not recorded ({e}); call refused because fail-open is off")
+            return Decision(
+                forward=False,
+                action_id=action_id,
+                error={
+                    "jsonrpc": "2.0",
+                    "id": message["id"],
+                    "error": {
+                        "code": JSONRPC_RECORDING_FAILED,
+                        "message": f"CommitLayer recording failed: {e}",
+                    },
+                },
+            )
+        with self._lock:
+            self._pending[_id_key(message["id"])] = action_id
+        self._log(f"recorded {action_id} for tool {tool_name!r}")
+        return Decision(action_id=action_id)
+
+    def after_response(self, message: Any) -> str | None:
+        """Match a downstream answer to a recorded request and log its ``isError`` flag. The result itself is
+        never sent to the API: a tool's own report of success is not evidence."""
+        if not isinstance(message, dict) or "id" not in message or "method" in message:
+            return None
+        with self._lock:
+            action_id = self._pending.pop(_id_key(message["id"]), None)
+        if action_id is None:
+            return None
+        result = message.get("result")
+        is_error = bool(result.get("isError")) if isinstance(result, dict) else "error" in message
+        self._log(f"recorded {action_id} → tool result isError={'true' if is_error else 'false'}")
+        return action_id
+
+    def pending(self) -> dict[str, str]:
+        """Recorded requests still waiting for a downstream answer: JSON-RPC id (encoded) → action id."""
+        with self._lock:
+            return dict(self._pending)

commitlayer_mcp_recorder/__main__.py

@@ -0,0 +1,201 @@
+"""``commitlayer-mcp-recorder``: the stdio proxy.
+
+    commitlayer-mcp-recorder --map mapping.json [--agent-id ID] [--workflow-id ID] [--api-url URL]
+        [--timeout 5] [--no-fail-open] [--warn-unmapped] -- <downstream command and args>
+
+Client stdin is pumped line by line to the downstream server's stdin and the server's stdout back to the
+client's stdout, in order and unchanged. The server's stderr is relayed to our stderr. The proxy exits when
+the client closes stdin or the server exits, with the server's exit code.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import threading
+from typing import Any, BinaryIO
+
+from . import (
+    DEFAULT_API_URL,
+    MappingError,
+    Recorder,
+    __version__,
+    load_mapping,
+    log_to_stderr,
+)
+
+GRACE_SECONDS = 5.0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="commitlayer-mcp-recorder",
+        description=(
+            "Forward MCP stdio traffic to a downstream server and record mapped tools/call requests as "
+            "CommitLayer actions before they are forwarded. The downstream command follows '--'."
+        ),
+        epilog=(
+            "Environment: COMMITLAYER_API_KEY (required to record; without it the proxy is a passthrough), "
+            f"COMMITLAYER_API_URL (default {DEFAULT_API_URL}), COMMITLAYER_RECORDER_MAP (default for --map)."
+        ),
+    )
+    parser.add_argument(
+        "--map",
+        default=os.environ.get("COMMITLAYER_RECORDER_MAP"),
+        help="mapping file (JSON, or YAML when PyYAML is installed); default $COMMITLAYER_RECORDER_MAP",
+    )
+    parser.add_argument("--agent-id", help="overrides agent_id from the mapping file")
+    parser.add_argument("--workflow-id", help="overrides workflow_id from the mapping file")
+    parser.add_argument(
+        "--api-url",
+        default=os.environ.get("COMMITLAYER_API_URL") or DEFAULT_API_URL,
+        help=f"CommitLayer API base URL; default $COMMITLAYER_API_URL or {DEFAULT_API_URL}",
+    )
+    parser.add_argument("--timeout", type=float, default=5.0, help="seconds to wait for the API (default 5)")
+    parser.add_argument(
+        "--no-fail-open",
+        action="store_true",
+        help="when recording fails, answer the client with a JSON-RPC error instead of forwarding the call",
+    )
+    parser.add_argument(
+        "--warn-unmapped",
+        action="store_true",
+        help="log each tool name that is called but not in the mapping, once",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def _parse(line: bytes) -> Any:
+    try:
+        return json.loads(line)
+    except ValueError:
+        return None
+
+
+def run_proxy(
+    command: list[str],
+    recorder: Recorder,
+    *,
+    stdin: BinaryIO | None = None,
+    stdout: BinaryIO | None = None,
+    log: Any = log_to_stderr,
+) -> int:
+    """Run ``command`` as the downstream server and pump traffic until the client or the server is done.
+    Returns the exit code to leave with (the server's)."""
+    client_in = stdin or sys.stdin.buffer
+    client_out = stdout or sys.stdout.buffer
+    try:
+        child = subprocess.Popen(
+            command,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+    except OSError as e:
+        log(f"cannot start downstream server {command[0]!r}: {e.strerror or e}")
+        return 127
+    assert child.stdin is not None and child.stdout is not None and child.stderr is not None
+    child_in, child_out, child_err = child.stdin, child.stdout, child.stderr
+    out_lock = threading.Lock()
+
+    def emit(data: bytes) -> None:
+        with out_lock:
+            client_out.write(data)
+            client_out.flush()
+
+    def pump_client() -> None:
+        try:
+            for line in iter(client_in.readline, b""):
+                decision = recorder.before_forward(_parse(line))
+                if decision.forward:
+                    child_in.write(line)
+                    child_in.flush()
+                elif decision.error is not None:
+                    emit(json.dumps(decision.error, separators=(",", ":")).encode() + b"\n")
+        except (OSError, ValueError):
+            pass  # the server went away; the main thread collects its exit code
+        finally:
+            try:
+                child_in.close()
+            except OSError:
+                pass
+            try:
+                child.wait(timeout=GRACE_SECONDS)
+            except subprocess.TimeoutExpired:
+                log("downstream server did not exit after the client closed stdin; terminating it")
+                child.terminate()
+
+    def pump_server() -> None:
+        try:
+            for line in iter(child_out.readline, b""):
+                recorder.after_response(_parse(line))
+                emit(line)
+        except OSError:
+            pass  # the client went away
+
+    def pump_stderr() -> None:
+        try:
+            for chunk in iter(lambda: child_err.read1(65536), b""):
+                sys.stderr.buffer.write(chunk)
+                sys.stderr.buffer.flush()
+        except OSError:
+            pass
+
+    threads = [
+        threading.Thread(target=pump_client, name="client->server", daemon=True),
+        threading.Thread(target=pump_server, name="server->client", daemon=True),
+        threading.Thread(target=pump_stderr, name="server-stderr", daemon=True),
+    ]
+    for t in threads:
+        t.start()
+    try:
+        child.wait()
+    except KeyboardInterrupt:
+        child.terminate()
+        child.wait()
+    for t in threads[1:]:
+        t.join(timeout=GRACE_SECONDS)
+    code = child.returncode
+    return code if code >= 0 else 128 - code
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_in = list(sys.argv[1:] if argv is None else argv)
+    if "--" in args_in:
+        split = args_in.index("--")
+        options, command = args_in[:split], args_in[split + 1 :]
+    else:
+        options, command = args_in, []
+    parser = build_parser()
+    args = parser.parse_args(options)
+    if not command:
+        parser.error("the downstream server command is required after '--'")
+    if not args.map:
+        parser.error("--map is required (or set COMMITLAYER_RECORDER_MAP)")
+    try:
+        mapping = load_mapping(args.map)
+    except MappingError as e:
+        log_to_stderr(f"invalid mapping {args.map}: {e}")
+        return 2
+    api_key = os.environ.get("COMMITLAYER_API_KEY") or ""
+    if not api_key:
+        log_to_stderr("COMMITLAYER_API_KEY is not set; running as a passthrough, nothing will be recorded")
+    recorder = Recorder(
+        mapping,
+        api_key=api_key,
+        api_url=args.api_url,
+        agent_id=args.agent_id,
+        workflow_id=args.workflow_id,
+        timeout=args.timeout,
+        fail_open=not args.no_fail_open,
+        warn_unmapped=args.warn_unmapped,
+    )
+    return run_proxy(command, recorder)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

commitlayer_mcp_recorder-0.1.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: commitlayer-mcp-recorder
+Version: 0.1.0
+Summary: CommitLayer MCP Recorder: a stdio proxy that records an agent's MCP tool calls as CommitLayer actions
+Author-email: "Asterfold Labs, Inc." <hello@commitlayer.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://commitlayer.ai
+Project-URL: Documentation, https://commitlayer.ai/docs
+Project-URL: Changelog, https://commitlayer.ai/changelog
+Project-URL: Source, https://github.com/kobikwelu/stateprf-svcs/tree/main/recorder/python
+Keywords: ai-agents,verification,audit,mcp,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Dynamic: license-file
+
+# CommitLayer MCP Recorder (Python)
+
+A small stdio proxy that sits between an MCP client (Claude Desktop, Claude Code, Cursor, an agent framework)
+and any downstream MCP server (a Stripe or Zendesk MCP server, your own). It forwards every JSON-RPC message
+unchanged in both directions, and when the client calls a mapped tool it records the intent as a CommitLayer
+action **before** forwarding the call. Standard library only; Python 3.10+.
+
+> The agent may declare its intent. It may read the verdict. It must never control the independent facts, the governing contract, or the final evidence.
+
+The recorder only does the first of those three. It never blocks, reorders or alters the agent's traffic, and
+the downstream tool's result is never sent to CommitLayer: a tool answering "refund issued" is a claim, not
+evidence. Verification reads the systems of record.
+
+```bash
+pip install ./recorder/python           # from this repository; `pip install pyyaml` for .yaml mappings
+export COMMITLAYER_API_KEY=spk_...      # a workspace API key; without it the proxy is a passthrough
+commitlayer-mcp-recorder --map mapping.json -- npx -y @stripe/mcp --tools=all
+```
+
+## Wiring it into a client
+
+Wherever the client is told how to start the server, put the recorder in front and move the real command
+after `--`.
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "stripe": {
+      "command": "commitlayer-mcp-recorder",
+      "args": ["--map", "/etc/commitlayer/stripe.json", "--agent-id", "support-bot", "--", "npx", "-y", "@stripe/mcp", "--tools=all"],
+      "env": {"COMMITLAYER_API_KEY": "spk_..."}
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add stripe -e COMMITLAYER_API_KEY=spk_... -- commitlayer-mcp-recorder --map stripe.json -- npx -y @stripe/mcp --tools=all
+```
+
+Cursor and other clients use the same `command` / `args` / `env` shape. The downstream server does not know
+the recorder is there; it sees the same bytes it would have seen.
+
+## CLI
+
+```
+commitlayer-mcp-recorder --map mapping.json [--agent-id ID] [--workflow-id ID] [--api-url URL]
+    [--timeout 5] [--no-fail-open] [--warn-unmapped] -- <downstream command and args>
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--map` | Mapping file, JSON or YAML (YAML needs PyYAML). Default `$COMMITLAYER_RECORDER_MAP`. |
+| `--agent-id`, `--workflow-id` | Override `agent_id` / `workflow_id` from the mapping file. |
+| `--api-url` | Default `$COMMITLAYER_API_URL`, then `https://api.commitlayer.ai`. |
+| `--timeout` | Seconds to wait for the API per call (default 5). |
+| `--no-fail-open` | When recording fails, refuse the call instead of forwarding it (see below). |
+| `--warn-unmapped` | Log each tool that is called but not mapped, once per tool name. |
+
+Environment: `COMMITLAYER_API_KEY` (required to record; without it the recorder warns once at startup and
+runs as a pure passthrough), `COMMITLAYER_API_URL`, `COMMITLAYER_RECORDER_MAP`. The key is never logged. All
+diagnostics go to stderr, one line each, prefixed `commitlayer-recorder:`. The downstream server's own stderr
+is relayed as is.
+
+The proxy exits when the client closes stdin or the downstream server exits, with the server's exit code.
+
+## Mapping file
+
+```json
+{
+  "agent_id": "support-bot",
+  "workflow_id": "refunds",
+  "tools": {
+    "refund_payment": {
+      "contract_id": "refund_workflow",
+      "action_type": "refund_order",
+      "subject": "arguments.order_id",
+      "subject_kind": "order",
+      "params": {"amount": "arguments.amount", "currency": "arguments.currency"},
+      "action_id": "refund:{arguments.order_id}",
+      "compensates": "arguments.original_action_id"
+    }
+  }
+}
+```
+
+- Keys under `tools` are MCP tool names. An exact match wins; a key with a server prefix
+  (`stripe.refund_payment`) also matches the bare name (`refund_payment`).
+- `contract_id` and `subject` are required per tool. Unknown keys are allowed and ignored.
+- `subject`, each `params` value and `compensates` are dotted paths into the `tools/call` params object:
+  `arguments.order_id`, `name`, `_meta.progressToken`, `arguments.items.0`.
+- `action_id` is a template with `{path}` placeholders. Without it the id is `mcp:{tool}:{request id}`, so a
+  retried request updates one record instead of creating two.
+- `contract_version` (integer), `action_type` and `subject_kind` are passed through.
+- A `params` path that is absent from the call is skipped; an absent `compensates` path is omitted. An absent
+  `subject` (or `action_id` placeholder) means the call is forwarded **but not recorded**, with a warning.
+
+The mapping is validated on load; an invalid file stops the proxy with exit code 2 and a message naming the
+tool and key.
+
+### Example: the Coinbase MCP server
+
+[`examples/coinbase.json`](examples/coinbase.json) maps `orders_create` (the order tool of the Coinbase MCP
+server behind Coinbase for Agents) to the `coinbase_agent_trade` library contract: the subject is the
+product id the agent passes, `amount` is its quote size, `side` and `client_order_id` ride along, and the
+action id is derived from the client order id so a retried call updates one record. The paths follow the
+create-order request; run the recorder once with `--warn-unmapped` against the server's own `tools/list`
+and adjust them if the argument names differ. The Coinbase server is remote (HTTP), and the recorder is a
+stdio proxy: put it in front of whatever stdio bridge the client uses to reach the remote server, so the
+bridge is the "downstream command". Verification then reads the order and its fills from Coinbase through
+the Coinbase connector; the tool's own answer is never evidence.
+
+## What is recorded
+
+For each client → server `tools/call` whose `params.name` is mapped, the recorder posts one action to
+`POST {api_url}/v1/actions` (`x-api-key`, `content-type: application/json`) and then forwards the original
+line unchanged:
+
+```json
+{
+  "action_id": "refund:order_10231",
+  "contract_id": "refund_workflow",
+  "subject_id": "order_10231",
+  "subject_kind": "order",
+  "action_type": "refund_order",
+  "agent_id": "support-bot",
+  "workflow_id": "refunds",
+  "requested_at": "2026-10-15T12:00:00Z",
+  "params": {"amount": 180.0, "currency": "USD", "mcp_tool": "refund_payment", "mcp_request_id": "7"},
+  "channel": "mcp"
+}
+```
+
+`params` always carries `mcp_tool` and `mcp_request_id`. `requested_at` is taken when the call is seen, so
+it precedes every effect. Unmapped tools, notifications, `initialize`, `tools/list` and everything else pass
+straight through.
+
+When the downstream answer for a recorded request comes back, the recorder logs one line:
+
+```
+commitlayer-recorder: recorded refund:order_10231 → tool result isError=false
+```
+
+That is all it does with the result. **The tool's own "success" is never evidence.** It is not sent to the
+API and it does not change the verdict; CommitLayer settles the action from the facts the systems of record
+report, under the governing contract. Read the verdict with the SDK or `GET /v1/actions/{action_id}`.
+
+## Fail-open, and the alternative
+
+By default recording is fail-open: if the API answers 4xx/5xx, times out or cannot be reached, a warning is
+written to stderr and the call is forwarded anyway. A verifier that is down must not stop the business
+action; the gap shows up as an action that was never recorded rather than one that never happened.
+
+With `--no-fail-open` a call whose recording fails is **not** forwarded. The client receives a JSON-RPC
+error for that request id (`code -32000`, message `CommitLayer recording failed: …`) and the downstream
+server never sees it. Other traffic is unaffected.
+
+## Library use
+
+```python
+from commitlayer_mcp_recorder import Recorder, build_action, load_mapping
+
+mapping = load_mapping("mapping.json")
+recorder = Recorder(mapping, api_key="spk_...", agent_id="support-bot")
+decision = recorder.before_forward(message)  # a parsed client message; .forward, .action_id, .error
+recorder.after_response(message)  # a parsed server message; logs the isError flag
+```
+
+`build_action(tool_name, call_params, tool_mapping, request_id=...)` returns the body shown above.
+
+## Limits
+
+- Stdio transport only, newline-delimited JSON-RPC. Lines that are not JSON are forwarded untouched.
+- JSON-RPC batch arrays are forwarded untouched and not inspected.
+- A `tools/call` without a JSON-RPC id is forwarded without recording (there is nothing to match the answer
+  to).
+
+## Tests
+
+```bash
+python -m pytest recorder/python/tests -q
+```

commitlayer_mcp_recorder-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+commitlayer_mcp_recorder/__init__.py,sha256=KIslkmfQvpLzX-1TY9Nv69OP7ba69s3PeqMQv-poS8g,18122
+commitlayer_mcp_recorder/__main__.py,sha256=BK4dJ_UW4-OBgNWo51r4dsBHpdtnqL-ZKrW1_Nam57Y,7031
+commitlayer_mcp_recorder-0.1.0.dist-info/licenses/LICENSE,sha256=0vhmIhIFNhgH1c9Yg3fPGr0tYr606CAcOisVbgKTbb8,1077
+commitlayer_mcp_recorder-0.1.0.dist-info/METADATA,sha256=-DtQGgaj791URu2hKatYb3AGyXfzsAjGaCbcLm_VHeI,9637
+commitlayer_mcp_recorder-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+commitlayer_mcp_recorder-0.1.0.dist-info/entry_points.txt,sha256=MmdYoTsIv7Ngu998m32LqEcErrk-SdC2PDr0GnrrqxA,84
+commitlayer_mcp_recorder-0.1.0.dist-info/top_level.txt,sha256=hKCwcVoNT2In6eRdGe5cRFc8hj6HeW-SwF5VWXoHW6Q,25
+commitlayer_mcp_recorder-0.1.0.dist-info/RECORD,,

commitlayer_mcp_recorder-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

commitlayer_mcp_recorder-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+commitlayer-mcp-recorder = commitlayer_mcp_recorder.__main__:main

commitlayer_mcp_recorder-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asterfold Labs, Inc.
+
+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.

commitlayer_mcp_recorder-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+commitlayer_mcp_recorder