Contributing¶

Thank you for your interest in contributing to mcpbr! This guide covers everything you need to get started.

Ways to Contribute¶

• Bug Reports: Found a bug? Open an issue
• Feature Requests: Have an idea? Start a discussion
• Code Contributions: Submit a pull request
• Documentation: Improve docs, fix typos, add examples
• Testing: Write tests, report edge cases

Reporting Bugs¶

Before creating a bug report, check existing issues to avoid duplicates.

Include:

• Clear, descriptive title
• Steps to reproduce
• Expected vs. actual behavior
• Environment details (OS, Python version, Docker version)
• Relevant logs or error messages

Development Setup¶

Prerequisites¶

• Python 3.11+
• Docker (running)
• An Anthropic API key

Installation¶

# Clone your fork
git clone https://github.com/YOUR_USERNAME/mcpbr.git
cd mcpbr

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running Tests¶

# Run unit tests only (no Docker or API keys required)
pytest -m "not integration"

# Run all tests (requires Docker and API keys)
pytest

# Run with coverage
pytest --cov=mcpbr

Code Style¶

mcpbr uses ruff for linting and formatting.

Before Submitting¶

# Check for issues
ruff check src/ tests/

# Auto-fix issues
ruff check --fix src/ tests/

# Format code
ruff format src/ tests/

Type Hints¶

All functions should have type hints:

# Good
def process_task(task: dict[str, Any], timeout: int = 300) -> TaskResult:
    ...

# Missing type hints
def process_task(task, timeout=300):
    ...

Pull Request Process¶

1. Fork and Branch¶

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/mcpbr.git
cd mcpbr

# Create a feature branch
git checkout -b feature/my-feature

2. Make Changes¶

• Write clear, focused commits
• Add tests for new functionality
• Update documentation as needed

3. Test¶

# Run tests
pytest -m "not integration"

# Check linting
ruff check src/ tests/

# Format code
ruff format src/ tests/

4. Submit¶

git push origin feature/my-feature

Then open a pull request on GitHub.

PR Guidelines¶

• Clear, descriptive title
• Reference related issues
• Describe what changed and why
• Include test results
• Update docs if needed

Commit Messages¶

• Use clear, descriptive messages
• Start with a verb in imperative mood (e.g., "Add", "Fix", "Update")
• Keep the first line under 72 characters
• Reference issues when applicable (e.g., "Fix #123")

# Good
git commit -m "Add timeout parameter to evaluation runner"
git commit -m "Fix container cleanup on SIGTERM"
git commit -m "Update CLI help text for --verbose flag"

# Bad
git commit -m "fixed stuff"
git commit -m "WIP"

Project Structure¶

mcpbr/
├── src/mcpbr/          # Main package
│   ├── cli.py          # CLI commands
│   ├── config.py       # Configuration models
│   ├── harness.py      # Main orchestrator
│   ├── harnesses.py    # Agent implementations
│   ├── providers.py    # LLM provider abstractions
│   ├── docker_env.py   # Docker management
│   ├── evaluation.py   # Patch testing
│   └── ...
├── tests/              # Test suite
├── docs/               # Documentation
└── config/             # Example configurations

Adding New Features¶

Adding a New Provider¶

1. Create a class in src/mcpbr/providers.py implementing the ModelProvider protocol
2. Add it to PROVIDER_REGISTRY
3. Update VALID_PROVIDERS in config.py
4. Add tests in tests/test_providers.py
5. Update documentation

class MyProvider:
    """My custom provider implementation."""

    def chat(
        self,
        messages: list[dict[str, Any]],
        max_tokens: int = 4096,
    ) -> ChatResponse:
        ...

# Register in PROVIDER_REGISTRY
PROVIDER_REGISTRY["myprovider"] = MyProvider

Adding a New Agent Harness¶

1. Create a class in src/mcpbr/harnesses.py implementing the AgentHarness protocol
2. Add it to HARNESS_REGISTRY
3. Update VALID_HARNESSES in config.py
4. Add tests
5. Update documentation

class MyHarness:
    """My custom agent harness."""

    async def solve(
        self,
        task: dict[str, Any],
        workdir: str,
        timeout: int = 300,
        verbose: bool = False,
        task_id: str | None = None,
        env: TaskEnvironment | None = None,
    ) -> AgentResult:
        ...

# Register in HARNESS_REGISTRY
HARNESS_REGISTRY["myharness"] = MyHarness

Testing Guidelines¶

Unit Tests¶

Test individual components in isolation:

def test_config_validation():
    """Test configuration validation."""
    config = HarnessConfig(
        mcp_server=MCPServerConfig(command="echo", args=["hello"]),
        provider="anthropic",
    )
    assert config.provider == "anthropic"

Integration Tests¶

Mark tests that require external resources:

import pytest

@pytest.mark.integration
async def test_docker_environment():
    """Test Docker environment creation."""
    manager = DockerEnvironmentManager()
    env = await manager.create_environment(task)
    ...

Run integration tests separately:

pytest -m integration

Documentation¶

Building Docs Locally¶

# Install docs dependencies
pip install -e ".[docs]"

# Build and serve
mkdocs serve

Visit http://127.0.0.1:8000 to preview.

Documentation Style¶

• Clear, concise writing
• Code examples for all features
• FAQ structured data in frontmatter
• Cross-links between related pages

Questions?¶

• Open an issue for bugs or feature requests
• Start a discussion for questions

License¶

By contributing, you agree that your contributions will be licensed under the MIT License.