Metadata-Version: 2.4
Name: mcp-mock
Version: 0.1.0
Summary: Synthetic mock server and testing suite for Model Context Protocol (MCP)
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: faker>=20.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pytest-asyncio>=0.23.0
Requires-Dist: pytest>=9.1.1
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

### CLI

Run a mock server from a JSON schema file:

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

Add chaos behavior:

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

### Python API

```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()
```

### Schema file format

A simple schema file can look like this:

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

## Development

Run the test suite:

```bash
pytest -q
```

## License

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