# Lockstep MCP Server

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

```sh
cd mcp_server
npm install
```

## Configure for Claude Code

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

```json
{
  "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

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

## License

Apache 2.0.