{
  "markdown": "# ResiliReplay\n\n## Break an MCP server on purpose. Replay the failure. Ship the regression.\n\nResiliReplay is the MCP reliability engine behind proof-carrying recovery changes: inspect one reviewed target, inject a deterministic fault, bound retries and duplicate effects, preserve evidence, and turn the failure into an executable regression.\n\n[![CI](https://github.com/aliengineering-byte/resilireplay/actions/workflows/ci.yml/badge.svg)](https://github.com/aliengineering-byte/resilireplay/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/resilireplay)](https://www.npmjs.com/package/resilireplay)\n[![License](https://img.shields.io/github/license/aliengineering-byte/resilireplay)](LICENSE)\n\n```console\nnpx --yes resilireplay@0.7.1 mcp demo\n```\n\n```text\nResiliReplay MCP demo\n\n✓ Clean MCP tool call\n✓ Deterministic failure reproduced\n✓ Recovery bounded to one retry\n✓ Duplicate effects observed: 0\n✓ Regression generated\n✓ Regression executed\n\nMCP reliability check passed.\nEvidence: sha256:4d2479b98453732d6011c699c061d023353c8d5cf4159bdf6c5b096961f94c06\n```\n\nThe demo is local, deterministic, credential-free, and cleaned up after it runs. It needs Node.js\n22 or 24—no repository checkout, configuration, account, API key, paid model, or remote MCP server.\nThis quickstart pins the released `0.7.1` artifact for reproducibility. Later `@latest` examples are\nconvenient for following current documentation; pin an exact version in CI and retained evidence.\n\n[Product site](https://aliengineering-byte.github.io/resilireplay/) ·\n[npm package](https://www.npmjs.com/package/resilireplay) ·\n[real MCP CI example](examples/mcp-reliability-ci/README.md) ·\n[machine-readable capabilities](aeb-capabilities.json)\n\n## Ten-second before and after\n\n| Before                      | After ResiliReplay                  |\n| --------------------------- | ----------------------------------- |\n| ✓ Clean tool call           | ✓ Clean control                     |\n| ? Recovery behavior unknown | ✓ Deterministic failure reproduced  |\n| ? Duplicate effect unknown  | ✓ Recovery bounded                  |\n| ? No regression             | ✓ Duplicate effects: 0              |\n|                             | ✓ Regression generated and executed |\n\n## What it does\n\n- Inject deterministic MCP failures.\n- Verify bounded recovery and duplicate-effect behavior.\n- Generate executable regressions for CI.\n\n## Try your MCP server\n\nStart with an Inspector-compatible `mcp.json`. A dry-run reads and sanitizes the selected entry but\nstarts no process, opens no socket, calls no tool, and writes nothing.\n\n```console\nnpx --yes resilireplay@latest mcp test --config ./mcp.json --server my-server --tool echo --safety inert --dry-run\n```\n\nReview the selected server, transport, tool, fault, retry/time bounds, and plan SHA-256. Execution\nrequires that exact digest:\n\n```console\nnpx --yes resilireplay@latest mcp test --config ./mcp.json --server my-server --tool echo --safety inert --approve <plan-sha256>\n```\n\nUse the same approved plan in CI and request concise machine-readable evidence:\n\n```console\nnpx --yes resilireplay@latest mcp test --config ./mcp.json --server my-server --tool echo --safety inert --approve <plan-sha256> --json\n```\n\n`mcp test` connects with the MCP SDK, discovers only the reviewed operation, runs a clean call,\ninjects one declared result-boundary fault, applies the bounded retry, counts duplicate effects,\ngenerates a causal regression, executes it, and closes owned resources. `mcp audit` remains available\nwith its existing options for compatibility.\n\n## CI\n\nThe repository contains a complete packed-package example using the official MCP Everything\nreference server:\n\n```yaml\nname: MCP reliability\non: [pull_request]\npermissions:\n  contents: read\njobs:\n  test:\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/checkout@v6\n      - uses: actions/setup-node@v6\n        with:\n          node-version: 24\n          package-manager-cache: false\n      - run: node scripts/verify-packed-mcp-example.mjs\n```\n\nSee [the standalone example](examples/mcp-reliability-ci/README.md) for its exact package integrity,\nSDK/runtime, protocol revision, inert `echo` operation, expected output, and generated regression.\nIt installs the packed CLI in a clean temporary npm project on Windows and Linux CI. This is\nproduct-owned field validation, not an independent adopter claim.\n\n## Safety boundaries\n\n- Local demo: no network target, telemetry, credentials, account, or paid model.\n- Real targets: one reviewed config entry and one explicit tool allowlist entry.\n- Execution: an exact plan digest, finite timeouts, and at most 10 retries; examples use one.\n- Evidence: metadata and hashes replace tool arguments and result bodies before persistence.\n- Filesystem: contained paths, link-escape rejection, exclusive regression publication, and cleanup.\n\nResiliReplay is a reliability tester, not a security certification, sandbox, authorization layer, or\nclaim that every recovery is safe. Only invoke tools whose effects and retry semantics you own and\nunderstand. Remote targets require the existing explicit ownership controls.\n\n## MCP support\n\n| MCP surface                                         | Evidence                                  | Boundary                                                                   |\n| --------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------- |\n| Bundled deterministic fixture                       | `FIXTURE_VERIFIED`                        | Local, zero-network demo; clean call, fault, retry, regression, cleanup    |\n| Inspector-compatible stdio config                   | `LIVE_VERIFIED`                           | Real SDK transport, allowlisted tool call, bounded recovery                |\n| Streamable HTTP config                              | `LIVE_VERIFIED`                           | Loopback/authenticated fixture coverage; remote ownership remains explicit |\n| SSE config                                          | `PROTOCOL_VERIFIED`                       | Imported and audited through the supported SDK transport                   |\n| `@modelcontextprotocol/server-everything@2026.8.18` | `INSTALLATION_VERIFIED` + `LIVE_VERIFIED` | Pinned local stdio package, inert `echo`, packed ResiliReplay CLI          |\n| ResiliReplay MCP server                             | `LIVE_VERIFIED`                           | Local stdio server with annotated reliability tools                        |\n\nEvidence labels describe what was executed; they do not imply vendor endorsement. Read the\n[MCP test guide](docs/mcp-reliability/FIVE_MINUTE_MCP_TEST.md),\n[Inspector compatibility guide](docs/MCP_INSPECTOR.md), and\n[limitations](docs/LIMITATIONS.md).\n\n## MCP-RES v0.2\n\n[MCP-RES v0.2](docs/standards/mcp-res/v0.2.0/MCP_RES.md) is the project-defined, open reliability\nevidence standard behind the result vocabulary. Its versioned profiles cover identity, bounded\nrecovery, duplicate effects, cleanup, integrity, and executable causal evidence. ResiliReplay is a\nreference implementation, not a required dependency.\n\nMCP-RES is independent of the official MCP specification. It is not an official MCP standard,\nsecurity certification, or endorsement. The immutable [v0.1](docs/standards/mcp-res/v0.1.0/) and\n[v0.2](docs/standards/mcp-res/v0.2.0/) trees, schemas, vectors, conformance tools, governance, and\nlimitations remain available from the [standards landing page](docs/standards/mcp-res/README.md).\n\n## Secondary agent-runtime support\n\nResiliReplay can also capture sanitized failures from supported agent runtimes and compile them into\nregressions. This is a secondary workflow; it does not change the MCP-first product path.\n\nGenuine local runtime coverage exists for LangGraph 1.4.9 and OpenAI Agents SDK 0.14.3 using\ndeterministic, no-key models. Claude Code and Codex integrations are installation- and\nfixture-verified; Hermes is installation-verified. Other named surfaces are documented only.\nNo authenticated hosted model, billed provider call, production API behavior, or vendor endorsement\nis claimed.\n\nRead [framework evidence](docs/FRAMEWORKS.md), [agent compatibility](docs/COMPATIBILITY.md),\n[plugin operations](docs/PLUGINS.md), and the [framework support policy](docs/product/FRAMEWORK_SUPPORT_POLICY.md).\n\n## CLI map\n\nMCP reliability appears first in `resilireplay --help`:\n\n```text\nmcp demo       Try a deterministic local MCP reliability test\nmcp test       Test one reviewed MCP tool with bounded recovery\nmcp validate   Validate a test configuration without starting it\nmcp serve      Run ResiliReplay as a local stdio MCP server\nmcp audit      Preserve the existing lower-level audit workflow\n```\n\nExisting campaign, replay, reporting, adapter, agent capture, and Studio commands remain available.\nThe root `demo` command is retained as a hidden compatibility alias for `mcp demo`; `mcp audit` is\nnot removed or weakened.\n\n## Artifact behavior\n\nBy default, `mcp demo` runs in an isolated temporary directory, executes its regression, removes the\ndirectory, and prints one evidence digest. Retain a deterministic bundle only when requested:\n\n```console\nnpx --yes resilireplay@latest mcp demo --keep\nnpx --yes resilireplay@latest mcp demo --output ./my-evidence\nnpx --yes resilireplay@latest mcp demo --json\n```\n\n`--keep` writes `.resilireplay/demo/`. Explicit output must stay inside the current project. An\nidentical existing bundle is accepted; a mismatch fails without changing it. The completion manifest\nis written last, and JSON output contains only relative artifact paths.\n\n## Exit codes\n\n| Code | Meaning                                                     |\n| ---: | ----------------------------------------------------------- |\n|  `0` | Reliability check or side-effect-free validation passed     |\n|  `1` | Reliability findings or a failed regression                 |\n|  `2` | Invalid command use or missing approval                     |\n| `10` | Invalid MCP configuration                                   |\n| `11` | Remote target lacks explicit authorization                  |\n| `12` | MCP connection or protocol failure                          |\n| `13` | Credential-shaped output detected                           |\n| `30` | Demo execution failure                                      |\n| `31` | Demo artifact containment, conflict, or publication failure |\n\nCampaign-specific codes remain documented in the [campaign schema guide](docs/CAMPAIGN_SCHEMA.md).\n\n## Installation\n\nRun without a global install:\n\n```console\nnpx --yes resilireplay@latest --version\n```\n\nSupported runtimes are Node.js 22 and 24 on current Ubuntu and Windows GitHub-hosted runners. The npm\npackage is Apache-2.0 licensed and published from a protected GitHub release through npm trusted\npublishing with OIDC and provenance; no long-lived npm token is accepted by the release workflow.\n\n## Security and privacy\n\nCapture is off by default. ResiliReplay sends no telemetry and persists no raw prompt, transcript,\nenvironment value, authorization header, token, or unrestricted tool body by default. Review\n[SECURITY.md](SECURITY.md), [THREAT_MODEL.md](THREAT_MODEL.md), and\n[docs/LIMITATIONS.md](docs/LIMITATIONS.md) before testing a stateful tool.\n\nPlease report vulnerabilities through the repository's private security-reporting path, not a public\nissue. Reliability failures and compatibility gaps can use the public issue templates.\n\n## Contributing\n\nFocused bug fixes, MCP compatibility evidence, and bounded reliability cases are welcome. Read\n[CONTRIBUTING.md](CONTRIBUTING.md) and the\n[case contribution rules](docs/mcp-reliability/CONTRIBUTING_CASES.md). Do not submit credentials,\nprivate traces, production tool bodies, or evidence you are not authorized to publish.\n\n## Development\n\nMaintainer development uses the repository-pinned toolchain:\n\n```console\npnpm install --frozen-lockfile\npnpm quality\npnpm mcp:example:verify\n```\n\nThe first-time user path never requires a checkout or pnpm. Release gates additionally inspect the\npacked tarball, test clean installs, scan generated evidence, exercise the cross-platform matrix, and\nverify immutable MCP-RES v0.1/v0.2 content.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n",
  "bytes": 12358,
  "sha": "8e8bb649230547e5a397a113c0888ca200dcb954d12230a89c9c2b1bbe252e32",
  "repo_slug": "aliengineering-byte/resilireplay",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aliengineering_byte_resilirepl_9b2d956e/readme"
}