Lockstep MCP Server

Copy Markdown View Source

Model Context Protocol server that exposes Lockstep's controlled-concurrency testing to AI agents. Wraps mix commands so an agent can:

  • Run a Lockstep test file and get parsed results
  • Replay a saved counterexample trace
  • Minimize (shrink) a counterexample
  • Dump trace contents

Install

cd mcp_server
npm install

Configure for Claude Code

Add to ~/.claude/claude_desktop_config.json or your project's MCP config:

{
  "mcpServers": {
    "lockstep": {
      "command": "node",
      "args": ["/path/to/lockstep/mcp_server/server.js"]
    }
  }
}

After restarting Claude Code, the tools become available:

  • mcp__lockstep__lockstep_test
  • mcp__lockstep__lockstep_replay
  • mcp__lockstep__lockstep_shrink
  • mcp__lockstep__lockstep_dump_trace

Use it

From an agent prompt:

Run the Lockstep test at test/foo_test.exs in the project at /Users/me/myproject. If it finds a bug, replay the trace to show me the schedule.

The agent calls lockstep_test, parses the response, and (if a bug was found) calls lockstep_replay with the returned trace_path.

API

lockstep_test

Inputs:

  • project_dir (string, required) — absolute path to project root
  • test_file (string, required) — path to test file
  • seed (number, optional) — for deterministic runs
  • max_failures (number, optional)

Returns JSON with:

  • exit_code — 0 on success
  • passed — boolean
  • tests_run, failures — parsed from mix test output
  • bug_found — null OR {iteration, seed, strategy, trace_path}
  • raw_output — first 8KB of stdout+stderr

lockstep_replay

Inputs:

  • project_dir (string, required)
  • trace_path (string, required)
  • run (string, optional) — Module.function to replay against
  • file (string, optional) — test file to load before replay

Returns JSON with exit_code and output.

lockstep_shrink

Inputs:

  • project_dir (string, required)
  • trace_path (string, required)

Returns JSON with exit_code and output.

lockstep_dump_trace

Inputs:

  • project_dir (string, required)
  • trace_path (string, required)

Returns JSON with exit_code and output.

Local development

node server.js
# Server listens on stdio per MCP spec.
# Test with `npx @modelcontextprotocol/inspector node server.js`.

License

Apache 2.0.