# mcp-mock-server

**A zero-dependency, configurable mock MCP server for testing MCP clients and harnesses.**

When you build an MCP client, an agent, or a testing tool, you need a server to
point it at. Spinning up a real one (with real credentials and side effects) just
to check that your client speaks the protocol correctly is heavy and flaky.
`mcp-mock-server` is a tiny stand-in: describe your tools and their canned
responses in a JSON file, and it serves a correct MCP handshake over stdio.

Part of the AAIF (Agentic AI Innovation Foundation) open-source toolset for the
agentic AI ecosystem. It pairs naturally with MCP conformance, audit, and
load-testing tools: use the mock as the target while you test the tester.

## Highlights

- Speaks JSON-RPC 2.0 over stdio: `initialize`, `notifications/initialized`,
  `ping`, `tools/list`, `tools/call`.
- Tools, schemas, and responses are fully driven by a JSON config.
- Simulates error responses and missing-argument handling for testing sad paths.
- Simple `{argument}` templating in responses.
- Standard library only. No pip dependencies.

## Install

```bash
pip install -e .
```

Requires Python 3.9 or newer.

## Quick start

Serve the built-in `echo` tool:

```bash
mcp-mock-server
```

Print the default config to use as a starting point:

```bash
mcp-mock-server --print-default-config > my-tools.json
```

Serve your own tools:

```bash
mcp-mock-server --config examples/weather.json
```

## Config format

```json
{
  "name": "weather-mock",
  "version": "1.0.0",
  "tools": [
    {
      "name": "get_forecast",
      "description": "Return a canned weather forecast for a city.",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      },
      "response": { "text": "Forecast for {city}: 30C, clear skies." }
    }
  ]
}
```

- `inputSchema` is standard JSON Schema. Listed `required` fields are enforced.
- `response.text` supports `{argument}` templating from the call arguments.
- Set `response.isError` to `true` to simulate a tool that fails.
- If `response.text` is omitted, the server echoes the arguments back.

## Try it by hand

Send a request on stdin (each message is one JSON line):

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"message":"hello"}}}' \
  | mcp-mock-server
```

## Wiring into an MCP client

Most clients accept a command to launch a server. Point them at:

```json
{
  "mcpServers": {
    "mock": { "command": "mcp-mock-server", "args": ["--config", "my-tools.json"] }
  }
}
```

## Development

```bash
pip install -e .
pytest
```

## License

MIT. See [LICENSE](LICENSE).