# Contributing to mcp-forge

Thanks for wanting to contribute! Here's how to get started.

## Development Setup

```bash
git clone https://github.com/ioteverythin/forgemcp.git
cd mcp-forge
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
```

## Running Tests

```bash
pytest tests/ -v
```

The test suite includes a bundled echo MCP server (`tests/servers/echo_server.py`)
that tests use to validate the client, assertions, and snapshot engine.

## Code Style

We use `ruff` for linting and formatting:

```bash
ruff check src/ tests/
ruff format src/ tests/
```

## Project Structure

```
src/mcp_forge/
├── __init__.py          # Public API
├── _types.py            # Data classes (ToolInfo, ToolResult, etc.)
├── client.py            # MCPTestClient
├── transport/
│   ├── stdio.py         # STDIO subprocess transport
│   └── inmemory.py      # FastMCP in-memory transport
├── assertions.py        # assert_* helpers
├── snapshot.py          # Snapshot engine
├── schema.py            # JSON Schema validation
├── fixtures.py          # Test file & fixture generator
├── cli.py               # `forge` CLI
└── pytest_plugin.py     # Auto-registered pytest plugin
```

## Adding a New Transport

1. Create `src/mcp_forge/transport/your_transport.py`
2. Implement `start()`, `send_request()`, `send_notification()`, `stop()`
3. Add a factory method to `MCPTestClient`
4. Add tests in `tests/`

## Adding New Assertions

1. Add the function to `src/mcp_forge/assertions.py`
2. Add tests in `tests/test_assertions.py`
3. Export from `__init__.py` if it's part of the public API

## Pull Request Process

1. Fork the repo and create a feature branch
2. Write tests for your changes
3. Ensure `pytest` and `ruff check` pass
4. Submit a PR with a clear description

## Releasing

Releases are triggered by pushing a git tag:

```bash
git tag v0.1.1
git push origin v0.1.1
```

The GitHub Action will build and publish to PyPI automatically.
