commitlayer-mcp-recorder 0.1.0__tar.gz

commitlayer_mcp_recorder-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,186 @@
+# 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
+```