mcp-mock-sim (repository: fury-r/mcp-sim)

CLI for running, recording, replaying, and validating MCP tool-call scenarios.

Install

npm install
npm run build
npm link

Run locally from source:

npm run start -- --help

Or run the built CLI:

node dist/cli.js --help

Commands

run <scenario>

Run a scenario file against a live MCP server.

mcp-mock-sim run examples/scenario.yaml --server stdio --cmd "node server.js"

Options:

• --server <type>: stdio or http (default: stdio)
• --cmd <command>: command used to launch the server in stdio mode
• --url <url>: MCP server URL in http mode
• --format <format>: pretty or json (default: pretty)

record

Record tool calls from a live server into fixtures.

mcp-mock-sim record \
  --server http \
  --url http://localhost:3000 \
  --out fixtures \
  --tools 'github_get_issue:{"repo":"my-org/my-repo","issue_number":1}'

Options:

• --server <type> (required): stdio or http
• --cmd <command>: command used to launch the server in stdio mode
• --url <url>: MCP server URL in http mode
• --out <dir> (required): output fixture directory
• --tools <tools>: comma-separated tool:jsonArgs calls to record

replay <scenario>

Replay a scenario using fixture files (no network calls).

mcp-mock-sim replay examples/scenario.yaml --fixtures fixtures --mode strict

Options:

• --fixtures <dir> (required): fixture directory
• --mode <mode>: strict or lenient (default: strict)
• --format <format>: pretty or json (default: pretty)

validate <scenario>

Validate scenario YAML syntax/schema.

mcp-mock-sim validate examples/scenario.yaml

Scenario file basics

See /examples/scenario.yaml for a complete example. A scenario supports:

• top-level metadata: version, name, optional description
• vars and ${vars.*} interpolation
• runtime environment interpolation with ${env.*}
• per-step MCP calls with tool, input, optional expect, save_as, retries, timeout_ms
• optional redact rules (pattern and/or pointer) for sanitized logs and fixtures

Release and Publish Flow

Flow diagram:

1. Code is pushed to master (including merged PRs).
2. Release Tag workflow runs.
3. Version is bumped and committed.
4. A Git tag vX.Y.Z is created and pushed.
5. Publish to npm workflow runs.
6. Package is published to npm registry.

Mermaid workflow:

flowchart TD
  A[Push or Merge to master] --> B[GitHub Action: Release Tag]
  B --> C[Determine Next Version]
  C --> D[Commit package.json and package-lock.json]
  D --> E[Create and Push Tag vX.Y.Z]
  E --> F[GitHub Action: Publish to npm]
  F --> G[Verify Version and Install Dependencies]
  G --> H[npm publish --access public --provenance]

Development

npm run lint
npm run build
npm test