# mcp-mock

mcp-mock is a lightweight synthetic mock server for the Model Context Protocol (MCP). It is designed for local testing, demos, and resilience experiments where you want a predictable MCP endpoint without depending on a real backend.

The current codebase includes:

- a `MockMCPServer` implementation for registering tools and serving responses
- a synthetic response generator powered by Faker
- a chaos layer for latency and injected failures
- a CLI entry point for running a mock server from a schema file
- a pytest suite covering the core behaviors

## Project layout

```text
mcp-mock/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── mcp_mock/
│       ├── __init__.py
│       ├── chaos.py
│       ├── cli.py
│       ├── generator.py
│       └── server.py
└── tests/
    ├── test_chaos.py
    ├── test_cli.py
    ├── test_generator.py
    └── test_server.py
```

## Installation

Install the package from the project root:

```bash
python -m pip install -e .
```

Install development dependencies as well:

```bash
python -m pip install -e ".[dev]"
```

## Usage

mcp-mock is most useful when you want a predictable MCP server for local development, test automation, or demos. You can either run it from the command line with a schema file or create a server directly in Python.

### CLI usage

The CLI entry point is `mcp-mock serve`. It reads a JSON file that describes the tools you want to expose and starts a mock MCP server over stdio.

Run a server from a schema file:

```bash
mcp-mock serve --schema ./tools_schema.json
```

Add simulated latency and failure injection:

```bash
mcp-mock serve --schema ./tools_schema.json --latency 100 --error-rate 0.1
```

#### CLI options

- `--schema` or `-s`: required path to a JSON schema file
- `--latency`: adds a delay in milliseconds before each tool response
- `--error-rate`: injects failures probabilistically, from `0.0` to `1.0`

### Python API usage

You can also create a server programmatically in Python.

```python
from mcp_mock.chaos import ChaosConfig
from mcp_mock.server import MockMCPServer

chaos = ChaosConfig(latency_ms=50, error_rate=0.05)
server = MockMCPServer(name="DemoServer", chaos=chaos)
server.register_tool(name="get_user", description="Get a user")
server.run_stdio()
```

This example does the following:

- creates a mock server named `DemoServer`
- attaches a chaos configuration with 50ms latency and a 5% error rate
- registers a tool called `get_user`
- starts the server over stdio

### Registering custom handlers

If you want more control than the built-in synthetic responses, you can provide a custom handler when registering a tool.

```python
from mcp_mock.server import MockMCPServer

server = MockMCPServer(name="DemoServer")

async def get_user_handler(user_id: str):
    return {"id": user_id, "name": "Ada Lovelace"}

server.register_tool(
    name="get_user",
    description="Return a user record",
    handler=get_user_handler,
)
```

### Schema file format

A schema file should contain a top-level object with a server name and a list of tools. A simple example is shown below:

```json
{
  "name": "ToolServer",
  "tools": [
    {
      "name": "get_user",
      "description": "Get a user by ID"
    },
    {
      "name": "execute_sql",
      "description": "Execute a SQL query"
    }
  ]
}
```

You can expand this format with additional metadata if you want to describe more complex tools, but the current implementation focuses on simple tool registration and synthetic responses.

### When to use mcp-mock

Use mcp-mock when you want to:

- test MCP integrations locally without a real backend
- simulate slow or flaky tool responses
- create demos with predictable tool outputs
- validate client behavior under latency and injected errors

## Development

Run the test suite:

```bash
pytest -q
```

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.