mcp-wringer

@stackql/mcp-wringer is a protocol robustness fuzzer for Model Context Protocol (MCP) servers over stdio and Streamable HTTP, with a focus on deterministic, replayable findings.

It is provided as both:

• an npm CLI (mcp-wringer)
• a GitHub Action

Use it only on servers you own or are explicitly authorised to test.

This repository is currently implementing Work order 001. See AGENTS.md for project scope and design rules.

Run a stdio test

Use run to start a local server, generate scenarios, and write reports:

npx mcp-wringer run --spec 2025-11-25 --profile quick --seed 12345 -- node path/to/server.js

The built-in profiles are quick (18 cases), standard (256 cases), and deep (2,000 cases). The default profile is quick. Reports and response-novelty corpus entries are written under .mcp-wringer/ unless their directories are overridden. findings.json includes the root seed and is stable for repeated runs against a deterministic server.

The target receives a minimal environment by default. Pass individual variables with repeated --env NAME=VALUE options; --inherit-env opts into passing the caller's environment. Tool calls are limited to tools advertising readOnlyHint: true. Use --allow-tool NAME to explicitly permit a tool without that annotation. Destructive tools require an exact-name allow entry.

Use mcp-wringer init to create a starter config, mcp-wringer list to view registered components, and mcp-wringer run --show-config to inspect resolved values and their origins. Configuration can set plugin modules, generator weights, enabled oracles and reporters, and a finding baseline. See the quick start, configuration reference, oracle and report catalogue, reproducer format, plugin guide, and safety notes.

Replay a report reproducer with the same target environment when needed:

npx mcp-wringer replay .mcp-wringer/reports/reproducers/<finding-id>.repro.json --env NAME=VALUE

replay writes the captured trace as JSON to stdout. To minimize a reproducer while confirming the finding on fresh targets:

npx mcp-wringer minimize .mcp-wringer/reports/reproducers/<finding-id>.repro.json --env NAME=VALUE

Experimental coverage feedback

Coverage-guided scheduling is disabled by default. Enable it in the config file for a spawned stdio target:

{
  "coverageFeedback": {
    "enabled": true,
    "provider": "node-v8",
    "batchSize": 8
  },
  "workers": 1,
  "restartPolicy": "per-case"
}

The built-in providers are node-v8 and go-cover; mcp-wringer list coverage-providers lists registered providers. Node targets must run under Node. Go targets must be built with go build -cover, and the Go tool must be on PATH so coverage data can be converted. Coverage is collected after each generator batch, and newly covered ranges influence later generator selection. This mode requires a spawned stdio target, one worker, and restartPolicy: "per-case". A target that fails before writing coverage still has its findings processed, but that batch may contribute no feedback. Coverage providers can also be registered by trusted plugins; see the plugin guide.

Run a Streamable HTTP test

Attach to a local endpoint with --url:

npx mcp-wringer run --url http://127.0.0.1:3000/mcp --spec 2025-11-25 --profile quick

To start a fixture or server process that listens on a known URL, provide both --url and the command:

npx mcp-wringer run --transport streamable-http --url http://127.0.0.1:3000/mcp --spec 2025-11-25 -- node server.js

Attach mode refuses non-loopback hosts unless --allow-non-loopback is supplied. Use that flag only for a target you own or are explicitly authorised to test. Reproducers can be replayed over the other transport with --transport and, for HTTP, --url.

For --spec 2026-07-28, the HTTP adapter sends the Mcp-Method header on every request and the Mcp-Name header for tools/call, prompts/get and resources/read, as that revision requires. It does not yet mirror tool parameters declared with x-mcp-header. A server that rejects the selected revision during inspection, for example a stateful server asked for 2026-07-28, ends the run with exit code 3.

Run the tool only against fixtures, the reference server, or a server you own or are authorised to test. Isolate the target and do not provide it with real credentials.

Use the GitHub Action

The Action runs on Node 24 supplied by the GitHub runner. It needs no token or GitHub permissions. It writes reports and a job summary; uploading artifacts or SARIF is a separate workflow step. See the example workflows for report upload examples.

After the first release and its moving v0 tag are published, use the following step in a job that has already checked out and prepared your local target. @v0 follows releases within major version 0:

- name: Fuzz the local MCP server
  uses: stackql/mcp-wringer@v0
  with:
    command: node
    args: '["path/to/server.js"]'
    profile: quick
    seed: "12345"
    fail_on: high
    report_directory: .mcp-wringer/reports