Skip to content
Back to search

mcp-cassette

Deterministic record-and-replay mock server and regression harness for MCP stdio servers with pre-disk secret redaction

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pie527645-cloud--mcp-cassette/badge.svg)](/listings/pie527645-cloud--mcp-cassette)

HTML

<a href="/listings/pie527645-cloud--mcp-cassette"><img src="/api/listings/pie527645-cloud--mcp-cassette/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/pie527645-cloud/mcp-cassette.git
cd mcp-cassette
npm install
npm run build
node dist/cli.js --help

Optional local symlink for shell usage:

npm link
mcp-cassette --version

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines
  1. # @pie527645-cloud/mcp-cassette
  2. Deterministic **Model Context Protocol (MCP)** stdio traffic recorder, secret-redacting cassette serializer, and zero-network offline CI replay mock server.
  3. `mcp-cassette` sits transparently between any MCP client and stdio MCP server during recording, captures exact bidirectional JSON-RPC 2.0 interactions with turn latency metrics, scrubs credentials into deterministic placeholders (`<REDACTED_TOKEN_1>`) **before** writing canonical sorted-key JSON to disk, and replays those interactions offline in CI with zero network access and zero downstream server dependencies.
  4. ---
  5. ## Architecture & Workflow
  6. ```mermaid
  7. sequenceDiagram
  8. autonumber
  9. participant Client as MCP Client / Test Suite
  10. participant Proxy as mcp-cassette (record)
  11. participant Server as Live MCP Server (stdio)
  12. participant Disk as session.mcp-cassette.json
  13. participant Mock as mcp-cassette (replay --strict)
  14. rect rgb(235, 245, 255)
  15. Note over Client,Disk: Phase 1: Local Recording & Pre-Disk Secret Scrubbing
  16. Client->>Proxy: JSON-RPC Request (initialize, tools/list, tools/call)
  17. Proxy->>Server: Forward Request (shell: false)
  18. Server-->>Proxy: JSON-RPC Response / Notification
  19. Proxy-->>Client: Forward Live Response (unmodified)
  20. Proxy->>Disk: Scrub secrets + canonical sorted-key JSON (Cassette v1)
  21. end
  22. rect rgb(235, 255, 240)
  23. Note over Client,Mock: Phase 2: Zero-Network Deterministic CI Replay
  24. Mock->>Disk: Load & validate cassette (<= 20 MB cap)
  25. Client->>Mock: JSON-RPC Request (method + canonicalized params)
  26. Mock-->>Client: Deterministic Recorded Response (or -32001 on strict mismatch)
  27. Client->>Mock: notifications/initialized
  28. Note right of Mock: Silent no-op (strict JSON-RPC 2.0)
  29. end
  30. ```
  31. ---
  32. ## Key Capabilities
  33. - **Transparent Bidirectional Stdio Proxy (`record`):** Spawns any downstream MCP server safely (`shell: false`), forwards newline-delimited JSON-RPC 2.0 frames with sub-millisecond overhead, tracks per-request turn latency (`latencyMs`), captures `protocolVersion` and `serverInfo`, and cleanly reaps the entire child + grandchild process tree on EOF, `SIGINT`/`SIGTERM`, or `--timeout`.
  34. - **Automatic Pre-Disk Secret Redaction:** Scrubs OpenAI/Anthropic keys (`sk-...`), GitHub tokens (`gh[pousr]_...`, `github_pat_...`), AWS access keys (`AKIA...`, `ASIA...`), Apify tokens (`apify_api_...`), Slack/npm/HuggingFace tokens, JWTs, `Bearer` credentials, and `Authorization` / `Proxy-Authorization` headers—plus optional `--redact-env` scrubbing for sensitive environment variables (`*KEY*`, `*TOKEN*`, `*SECRET*`, `*PASS*` with length `>= 8`)—replacing identical secrets with deterministic `<REDACTED_TOKEN_N>` placeholders before touching disk.
  35. - **Canonical Sorted-Key Cassette Format v1:** Every nested JSON object key is sorted lexicographically so cassettes produce clean, reproducible Git diffs and match incoming `params` regardless of key insertion order.
  36. - **Stateful Zero-Network CI Replay (`replay`):** Matches `initialize`, `tools/list`, `tools/call`, `resources/list`, `prompts/list`, and custom MCP requests by `method` + canonicalized `params`, maintaining a per-bucket sequence cursor when identical calls repeat statefully.
  37. - **Regression-Catching `--strict` Mode:** Immediately returns JSON-RPC error `-32001` when an unrecorded method, unrecorded argument payload, or extra repeat call occurs in CI. Handles `notifications/initialized` and other JSON-RPC 2.0 notifications silently with zero stdout frames.
  38. - **Token & Latency Analytics (`inspect`):** Reports interaction counts, unique MCP methods and tool names, request/response byte totals, estimated token footprint (`Math.ceil(chars / 4)`), `p50`/`p95` latencies, and redacted secret counts in `pretty`, `json`, or `markdown` formats.
  39. - **Zero Runtime Dependencies:** Built exclusively on Node.js `>=20.18.1` standard library modules.
  40. ---
  41. ## Setup from Source
  42. ```bash
  43. git clone https://github.com/pie527645-cloud/mcp-cassette.git
  44. cd mcp-cassette
  45. npm install
  46. npm run build
  47. node dist/cli.js --help
  48. ```
  49. Optional local symlink for shell usage:
  50. ```bash
  51. npm link
  52. mcp-cassette --version
  53. ```
  54. ---
  55. ## CLI Usage
  56. ### 1. Record a Live MCP Session
  57. ```bash
  58. node dist/cli.js record \
  59. --stdio "node ./path/to/my-mcp-server.js --mode production" \
  60. --out ./cassettes/weather-tools.mcp-cassette.json \
  61. --redact-env \
  62. --timeout 30000
  63. ```
  64. | Flag | Description |
  65. | --- | --- |
  66. | `--stdio "<cmd>"` | Downstream MCP server command tokenized with quote awareness (`shell: false`). |
  67. | `--out <path>` | Output path for the redacted, sorted-key `.mcp-cassette.json` file. |
  68. | `--redact-env` | Scrub values of sensitive `process.env` variables (`>= 8` chars matching `*KEY*`, `*TOKEN*`, `*SECRET*`, `*PASS*`). |
  69. | `--timeout <ms>` | Optional session ceiling in milliseconds; reaps child + grandchild process tree on expiry. |
  70. ### 2. Replay Offline as an MCP Mock Server
  71. Point your MCP client, agent harness, or integration test runner at `replay` instead of the live server command:
  72. ```bash
  73. node dist/cli.js replay \
  74. --cassette ./cassettes/weather-tools.mcp-cassette.json \
  75. --strict \
  76. --latency-ms 0
  77. ```
  78. | Flag | Description |
  79. | --- | --- |
  80. | `--cassette <path>` | Recorded `.mcp-cassette.json` file (`<= 20 MB`). |
  81. | `--strict` | Return JSON-RPC `-32001` error immediately on any unrecorded method, parameter mismatch, or exhausted repeat sequence. |
  82. | `--latency-ms <n>` | Optional fixed artificial response delay in milliseconds (defaults to `0` for instant CI execution). |
  83. ### 3. Inspect Cassette Footprint & Latency
  84. ```bash
  85. node dist/cli.js inspect ./cassettes/weather-tools.mcp-cassette.json --format pretty
  86. node dist/cli.js inspect ./cassettes/weather-tools.mcp-cassette.json --format json
  87. node dist/cli.js inspect ./cassettes/weather-tools.mcp-cassette.json --format markdown
  88. ```
  89. ---
  90. ## GitHub Actions Offline CI Replay Example
  91. Commit sanitized `.mcp-cassette.json` fixtures into your repository and run full MCP agent/tool integration suites in GitHub Actions with zero API keys and zero external network calls:
  92. ```yaml
  93. name: MCP Offline Integration Suite
  94. on:
  95. push:
  96. branches: [main]
  97. pull_request:
  98. permissions:
  99. contents: read
  100. jobs:
  101. verify-mcp-workflows:
  102. runs-on: ubuntu-latest
  103. steps:
  104. - name: Checkout project
  105. uses: actions/checkout@v4
  106. - name: Setup Node.js 20
  107. uses: actions/setup-node@v4
  108. with:
  109. node-version: 20.x
  110. - name: Build mcp-cassette from source
  111. run: |
  112. git clone https://github.com/pie527645-cloud/mcp-cassette.git .tools/mcp-cassette
  113. cd .tools/mcp-cassette
  114. npm ci
  115. npm run build
  116. - name: Publish cassette telemetry to Job Summary
  117. run: |
  118. node .tools/mcp-cassette/dist/cli.js inspect \
  119. ./tests/cassettes/agent-smoke.mcp-cassette.json \
  120. --format markdown >> "$GITHUB_STEP_SUMMARY"
  121. - name: Run integration tests against strict offline MCP replay server
  122. env:
  123. MCP_SERVER_CMD: "node .tools/mcp-cassette/dist/cli.js replay --cassette ./tests/cassettes/agent-smoke.mcp-cassette.json --strict"
  124. run: npm test
  125. ```
  126. ---
  127. ## Cassette Format v1 Specification
  128. Cassettes are serialized with deterministically sorted keys across every object level:
  129. ```json
  130. {
  131. "interactions": [
  132. {
  133. "index": 0,
  134. "kind": "request",
  135. "latencyMs": 3.412,
  136. "method": "initialize",
  137. "params": {
  138. "capabilities": {},
  139. "clientInfo": {
  140. "name": "ci-agent",
  141. "version": "1.0.0"
  142. },
  143. "protocolVersion": "2024-11-05"
  144. },
  145. "requestId": 1,
  146. "response": {
  147. "result": {
  148. "capabilities": {
  149. "tools": {}
  150. },
  151. "protocolVersion": "2024-11-05",
  152. "serverInfo": {
  153. "name": "example-mcp",
  154. "version": "1.2.0"
  155. }
  156. }
  157. }
  158. },
  159. {
  160. "index": 1,
  161. "kind": "client_notification",
  162. "latencyMs": 0,
  163. "method": "notifications/initialized"
  164. },
  165. {
  166. "index": 2,
  167. "kind": "request",
  168. "latencyMs": 18.75,
  169. "method": "tools/call",
  170. "params": {
  171. "arguments": {
  172. "query": "status"
  173. },
  174. "name": "check_upstream"
  175. },
  176. "requestId": 2,
  177. "response": {
  178. "result": {
  179. "Authorization": "Bearer <REDACTED_TOKEN_1>",
  180. "content": [
  181. {
  182. "text": "Upstream healthy",
  183. "type": "text"
  184. }
  185. ]
  186. }
  187. }
  188. }
  189. ],
  190. "protocolVersion": "2024-11-05",
  191. "recordedAt": "2026-11-21T09:05:00.000Z",
  192. "redactionCount": 1,
  193. "serverCommand": [
  194. "node",
  195. "./server.js"
  196. ],
  197. "serverInfo": {
  198. "name": "example-mcp",
  199. "version": "1.2.0"
  200. },
  201. "version": 1
  202. }
  203. ```
  204. ---
  205. ## Programmatic API
  206. ```ts
  207. import {
  208. recordSession,
  209. replayCassette,
  210. inspectCassette,
  211. redactValue,
  212. loadCassette,
  213. } from '@pie527645-cloud/mcp-cassette';
  214. // 1. Scrub arbitrary JSON payloads deterministically
  215. const scrubbed = redactValue(
  216. { headers: { Authorization: 'Bearer example_credential_value' } },
  217. { redactEnv: true },
  218. );
  219. // 2. Inspect a saved cassette programmatically
  220. const stats = inspectCassette('./cassettes/session.mcp-cassette.json');
  221. console.log(stats.uniqueToolNames, stats.estimatedTokens, stats.latencyMs.p95);
  222. // 3. Load a validated cassette (enforces <= 20 MB ceiling)
  223. const { cassette } = loadCassette('./cassettes/session.mcp-cassette.json');
  224. ```
  225. ---
  226. ## Security & Reliability Invariants
  227. - **Zero Shell Injection:** `--stdio` commands are parsed by a quote-aware tokenizer and executed via `spawn(executable, args, { shell: false })`.
  228. - **Full Process-Tree Reaping:** On Windows (`taskkill /T /F` plus `Win32_Process` orphan fallback) and POSIX (`detached` process group `-pid` `SIGTERM` -> `SIGKILL`), both child and detached grandchild processes are reaped on EOF, signals, or `--timeout`.
  229. - **Bounded Memory:** Cassette loading and single JSON-RPC line framing strictly enforce a `20 MB` (`20,971,520` byte) ceiling.
  230. - **ReDoS & Prototype-Pollution Hardened:** All token matchers use linear bounded character classes with zero nested quantifiers or lazy dot-all patterns; all lookup tables use `Object.create(null)` and `Object.hasOwn`.
  231. ---
  232. ## Development
  233. ```bash
  234. npm run lint
  235. npm run build
  236. npm test
  237. ```
  238. ## License
  239. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.