# wiremock-mcp

A lightweight MCP server that lets coding agents manage a local or remote WireMock instance through the WireMock Admin API.

The project is designed around a simple rule: **WireMock remains the source of truth**. The MCP server does not own or migrate your existing mappings; it connects to the WireMock instance you already use.

## Package

```text
@erivelto_muller/wiremock-mcp
```

The package is published to the public npm registry.

## MVP architecture

```text
Codex / Claude / Cursor / MCP client
                 |
                 | MCP stdio
                 v
       @erivelto_muller/wiremock-mcp
                 |
                 | HTTP
                 v
       WIREMOCK_URL/__admin/*
                 |
                 v
             WireMock 3.x
```

The MVP connects to **one WireMock instance** configured by `WIREMOCK_URL`.

Default:

```text
http://localhost:8080
```

## Requirements

- Node.js 22 or newer
- a running WireMock 3.x instance
- an MCP client with stdio server support

Docker is optional. It is only needed if you want an easy way to start WireMock locally.

## Quick start

### 1. Start WireMock if you do not already have one

Using the official WireMock Docker image:

```bash
docker run --rm -it \
  --name wiremock \
  -p 8080:8080 \
  wiremock/wiremock:3.13.2
```

Verify it:

```bash
curl http://localhost:8080/__admin/health
```

If you already have WireMock running with existing mappings, keep using it. You do not need to migrate them.

### 2. Configure the MCP server

Generic process-spawned MCP configuration:

```json
{
  "mcpServers": {
    "wiremock": {
      "command": "npx",
      "args": ["-y", "@erivelto_muller/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:8080"
      }
    }
  }
}
```

For an existing WireMock on another port:

```json
{
  "mcpServers": {
    "wiremock": {
      "command": "npx",
      "args": ["-y", "@erivelto_muller/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:9090"
      }
    }
  }
}
```

The server can also be started directly:

```bash
WIREMOCK_URL=http://localhost:9090 \
npx -y @erivelto_muller/wiremock-mcp
```

No repository clone is required for normal use.

## Tools

The server exposes the following MCP tools:

| Tool | Purpose |
|---|---|
| `wiremock_status` | Check connectivity, health and WireMock version |
| `mock_list` | List registered stub mappings |
| `mock_get` | Get one mapping by ID |
| `mock_create` | Create a WireMock mapping |
| `mock_update` | Update a mapping by ID, enforcing namespace ownership when configured |
| `mock_delete` | Delete a mapping by ID, enforcing namespace ownership when configured |
| `mock_adopt` | Explicitly adopt an unmanaged legacy mapping into the current namespace |
| `mock_delete_owned` | Delete only mappings owned by the current namespace |
| `mock_reset` | Reset runtime mappings to the backing-store defaults |
| `request_list` | List requests from the request journal |
| `request_get` | Get one journal request by ID |
| `request_unmatched` | List requests that matched no stub |
| `request_count` | Count journal requests matching a WireMock request pattern |
| `request_clear` | Clear the request journal without deleting mappings |

The create/update/count tools intentionally preserve WireMock's advanced request/mapping structure instead of reducing WireMock to a small custom schema.

## Namespace ownership

By default the server runs in unscoped compatibility mode. This keeps existing
WireMock workflows working: mappings are not automatically tagged, and
`mock_update`, `mock_delete`, `mock_reset` and `request_clear` behave globally.

For multi-agent use, run one MCP process per agent with a distinct namespace:

```json
{
  "mcpServers": {
    "wiremock-agent-a": {
      "command": "npx",
      "args": ["-y", "@erivelto_muller/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:8080",
        "WIREMOCK_MCP_NAMESPACE": "agent-a"
      }
    }
  }
}
```

When `WIREMOCK_MCP_NAMESPACE` is set, mappings created by this MCP process are
tagged in WireMock metadata:

```json
{
  "metadata": {
    "wiremockMcp": {
      "managed": true,
      "namespace": "agent-a"
    }
  }
}
```

The reserved key is `metadata.wiremockMcp`. Other metadata is preserved.

Ownership classifications:

| Classification | Meaning |
|---|---|
| `OWNED` | Managed by this MCP process namespace |
| `FOREIGN` | Managed by another MCP namespace |
| `UNMANAGED` | No valid WireMock MCP ownership metadata |
| `UNSCOPED` | No namespace configured, compatibility mode |

Reads are never blocked by ownership. Agents can still list and inspect
foreign or unmanaged mappings for diagnosis.

Writes are guarded when namespace mode is active:

- `mock_update` and `mock_delete` allow `OWNED` mappings;
- `FOREIGN` mappings are always refused;
- `UNMANAGED` mappings are refused by default;
- pass `allowUnmanaged: true` to `mock_update` or `mock_delete` for an explicit
  opt-in operation on a legacy mapping.

`allowUnmanaged` does not adopt a mapping. To mark a legacy mapping as owned by
the current namespace, use:

```text
mock_adopt(id="...")
```

`mock_adopt` is idempotent for `OWNED` mappings, refuses `FOREIGN` mappings and
preserves request/response fields plus non-reserved metadata.

To clean up only this namespace, use:

```text
mock_delete_owned()
```

`mock_delete_owned` does not remove foreign or unmanaged mappings.

`mock_reset` and `request_clear` are global operations. When namespace mode is
active, both are blocked by default. You can explicitly allow them for a process:

```json
{
  "mcpServers": {
    "wiremock-agent-a": {
      "command": "npx",
      "args": ["-y", "@erivelto_muller/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:8080",
        "WIREMOCK_MCP_NAMESPACE": "agent-a",
        "WIREMOCK_MCP_ALLOW_GLOBAL_DESTRUCTIVE": "true"
      }
    }
  }
}
```

Only enable this for isolated WireMock instances or when the agent is expected
to affect every mapping/request journal entry in the configured WireMock.
Request journal ownership is not tracked in this version.

## Example agent requests

Once the MCP is configured, examples include:

```text
Create a GET /products/123 mock returning HTTP 200 with this JSON body: ...
```

```text
List the existing WireMock mappings and show me which one handles /payments.
```

```text
Update this mapping so that it returns HTTP 503 with a 500 ms delay.
```

```text
Show the requests received by WireMock that did not match any mock.
```

```text
Check whether my application called POST /orders and how many times.
```

## Existing WireMock environments

Using an existing instance is a primary use case.

For example, if your WireMock already runs at:

```text
http://localhost:9090
```

with a collection of existing mappings, configure only:

```text
WIREMOCK_URL=http://localhost:9090
```

The MCP operates on the mappings and request journal already present in that WireMock instance.

## Safety

The configured MCP server has permission to modify the WireMock instance pointed to by `WIREMOCK_URL`.

Some tools are intentionally destructive:

- `mock_delete` removes a mapping;
- `mock_delete_owned` removes all mappings owned by the current namespace;
- `mock_reset` resets runtime mappings;
- `request_clear` clears the request journal.

Use a development/test WireMock instance unless you explicitly intend the agent to manage another environment.

The MVP does not expose WireMock shutdown operations.

The MVP does not implement authentication, credential storage, request
redaction, multi-tenant authorization or environment allowlists. If your
WireMock Admin API is reachable from this server, an MCP client can create,
update and delete mappings and clear the request journal through the tools
listed above. Prefer isolated development/test instances and avoid pointing
`WIREMOCK_URL` at shared or production-like environments unless that access is
intentional.

HTTPS URLs are accepted, but no custom CA, client certificate or authorization
header configuration is included in the MVP.

## Development

Clone the repository:

```bash
git clone https://github.com/Erivelto47/wiremock-mcp.git
cd wiremock-mcp
```

Install dependencies:

```bash
npm ci
```

Build:

```bash
npm run build
```

Run the server from a local build:

```bash
WIREMOCK_URL=http://localhost:8080 node dist/index.js
```

Run unit tests:

```bash
npm test
```

Run the real WireMock integration/E2E suite:

```bash
npm run test:integration
```

The integration suite starts an isolated WireMock Docker container on port
`18080`, exercises the MCP through stdio and cleans the container afterward.

## Test the package before publishing

Inspect the files that would be included in the npm package:

```bash
npm pack --dry-run
```

A local tarball can also be generated with:

```bash
npm pack
```

This makes it possible to smoke-test the installable package before publishing it.

## npm distribution

The primary distribution target is the public npm registry so users can run the MCP with `npx` and do not need to clone this repository.

Target package:

```text
@erivelto_muller/wiremock-mcp
```

Releases are intended to be published by GitHub Actions from SemVer tags after
Trusted Publishing is configured on npmjs.com.

Manual publishing, when needed, uses:

```bash
npm publish --access public
```

Publishing is a release-maintainer action and is not performed by normal
development/test commands.

## CI and releases

Continuous integration runs on pushes and pull requests to `master`:

- `npm ci`
- `npm run typecheck`
- `npm run build`
- `npm test`
- `npm run test:integration`
- `npm pack --dry-run`

The publish workflow runs only when a tag matching `v*` is pushed. Before
publishing, it repeats the same gates and verifies that the tag version matches
`package.json` exactly:

```text
v0.2.0 -> package.json version 0.2.0
```

The workflow uses npm Trusted Publishing with GitHub Actions OIDC. It does not
use long-lived npm publish tokens, publish secrets or OTP values.

After `.github/workflows/publish.yml` exists on the default branch, the
maintainer must configure the npm package Trusted Publisher with:

```text
Provider: GitHub Actions
GitHub user/org: Erivelto47
Repository: wiremock-mcp
Workflow filename: publish.yml
Allowed action: npm publish
Environment: empty
```

The workflow filename is `publish.yml`, not `.github/workflows/publish.yml`.
Each npm package supports one Trusted Publisher at a time. Do not create a
release tag until this npm package setting has been configured.

## Roadmap

### MVP — one external WireMock

- TypeScript / Node.js
- MCP over stdio
- one `WIREMOCK_URL`
- mapping CRUD
- namespace ownership for concurrent agents
- request-journal inspection
- npm distribution
- CI and Trusted Publishing workflow
- real WireMock Docker E2E tests

### Next functional step — multiple WireMock instances

A later release can support named instances while keeping the current single-URL configuration as the default.

Conceptually:

```text
mock_list(instance="payments")
mock_create(instance="legacy", ...)
```

Possible configuration:

```yaml
instances:
  payments: http://localhost:9091
  legacy: http://localhost:9092
```

This is intentionally outside the first MVP so the initial server stays small and predictable.

### Future distribution — all-in-one Docker image

A later release can provide an OCI/Docker image that bundles:

```text
MCP server + WireMock
```

for zero-config local onboarding.

That convenience image must not remove the ability to connect the MCP to an existing external WireMock instance.

### Other possible extensions

- Streamable HTTP transport
- OpenAPI-assisted mock creation
- recording/proxy workflows
- richer request verification helpers
- per-namespace request-journal isolation

These are not part of the MVP.

## License

MIT. See [LICENSE](LICENSE).