Skip to content

Development Setup

Jump to bottom
CodeGraphTheory edited this page Jan 20, 2026 · 1 revision

Development Setup

This guide will help you set up a local development environment for contributing to mcpbr.

Prerequisites

Before you begin, ensure you have:

  • ✅ Python 3.11+ installed
  • ✅ Git for version control
  • ✅ Docker for running tests
  • ✅ A text editor or IDE (VS Code, PyCharm, etc.)

Quick Setup

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/mcpbr.git
cd mcpbr

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

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

# 4. Verify setup
pytest -m "not integration"

Detailed Setup

1. Fork the Repository

  1. Navigate to https://github.com/greynewell/mcpbr
  2. Click the "Fork" button in the top right
  3. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/mcpbr.git
cd mcpbr

2. Add Upstream Remote

git remote add upstream https://github.com/greynewell/mcpbr.git
git fetch upstream

This allows you to sync with the main repository.

3. Create Virtual Environment

Using venv:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Using uv (faster):

pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Using conda:

conda create -n mcpbr python=3.11
conda activate mcpbr

4. Install Dependencies

Standard installation:

pip install -e ".[dev]"

Using uv (faster):

uv pip install -e ".[dev]"

This installs:

  • mcpbr in editable mode (-e)
  • All development dependencies ([dev])

Development dependencies include:

  • pytest - Testing framework
  • pytest-cov - Coverage reporting
  • pytest-asyncio - Async test support
  • ruff - Linting and formatting
  • mypy - Type checking
  • pre-commit - Git hooks

5. Verify Installation

# Check installation
mcpbr --version

# Run unit tests
pytest -m "not integration"

# Check linting
ruff check src/

# Check types
mypy src/

Development Tools

Code Editor Setup

VS Code

Recommended extensions:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "charliermarsh.ruff",
    "ms-azuretools.vscode-docker"
  ]
}

Settings (.vscode/settings.json):

{
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "ruff",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

PyCharm

  1. Set Python Interpreter: Settings → Project → Python Interpreter → Add → Virtualenv
  2. Enable ruff: Settings → Tools → External Tools → Add ruff
  3. Configure pytest: Settings → Tools → Python Integrated Tools → Testing → pytest

Pre-commit Hooks

Install pre-commit hooks to automatically check code before commits:

pre-commit install

This runs on every commit:

  • Code formatting (ruff)
  • Linting (ruff)
  • Type checking (mypy)
  • Test execution (pytest)

Manual run:

pre-commit run --all-files

Ruff (Linting & Formatting)

Check for issues:

ruff check src/ tests/

Auto-fix issues:

ruff check --fix src/ tests/

Format code:

ruff format src/ tests/

Configuration (already in pyproject.toml):

[tool.ruff]
line-length = 100
target-version = "py311"

MyPy (Type Checking)

Run type checker:

mypy src/

Configuration (already in pyproject.toml):

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true

Testing

Running Tests

All tests:

pytest

Only unit tests (fast):

pytest -m "not integration"

Only integration tests:

pytest -m integration

With coverage:

pytest --cov=src/mcpbr --cov-report=html
open htmlcov/index.html  # View coverage report

Verbose output:

pytest -v

Stop on first failure:

pytest -x

Run specific test:

pytest tests/test_config.py::test_load_config

Test Markers

@pytest.mark.unit          # Fast, no external dependencies
@pytest.mark.integration   # Requires Docker, API keys
@pytest.mark.slow          # Takes >10 seconds
@pytest.mark.benchmark     # Benchmark-specific tests

Writing Tests

Test file structure:

# tests/test_feature.py
import pytest
from mcpbr.feature import my_function

class TestMyFunction:
    """Tests for my_function."""

    def test_happy_path(self):
        """Test normal operation."""
        result = my_function(input="test")
        assert result == "expected"

    def test_edge_case(self):
        """Test edge case."""
        result = my_function(input="")
        assert result is None

    def test_error_handling(self):
        """Test error conditions."""
        with pytest.raises(ValueError):
            my_function(input=None)

Fixtures:

@pytest.fixture
def sample_config():
    """Create a sample configuration for testing."""
    return HarnessConfig(
        mcp_server=MCPServerConfig(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem"],
        ),
        model="sonnet",
    )

def test_with_fixture(sample_config):
    """Test using fixture."""
    assert sample_config.model == "sonnet"

Running mcpbr Locally

Setup API Keys

export ANTHROPIC_API_KEY="sk-ant-..."

Add to .env file (create at project root):

ANTHROPIC_API_KEY=sk-ant-...

Run Benchmarks

# Initialize config
mcpbr init

# Run small test
mcpbr run -c mcpbr.yaml -n 2 -v

Debugging

Use verbose logging:

mcpbr run -c mcpbr.yaml -n 1 -vv --log-dir debug-logs/

Add breakpoints in code:

import pdb; pdb.set_trace()  # Python debugger
breakpoint()  # Python 3.7+

VS Code debugging:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run mcpbr",
      "type": "python",
      "request": "launch",
      "module": "mcpbr.cli",
      "args": ["run", "-c", "mcpbr.yaml", "-n", "1", "-v"],
      "console": "integratedTerminal"
    }
  ]
}

Docker Development

Build Test Images

# Build fallback image
docker build -t mcpbr-test -f Dockerfile .

Cleanup Docker

# Remove mcpbr containers
mcpbr cleanup

# Remove all stopped containers
docker container prune -f

# Remove unused images
docker image prune -a -f

Docker Compose (Optional)

For integration testing:

# docker-compose.yml
version: '3.8'
services:
  mcpbr-test:
    build: .
    volumes:
      - .:/app
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

Git Workflow

Create Feature Branch

git checkout -b feature/my-awesome-feature

Keep Branch Updated

# Fetch latest changes
git fetch upstream

# Rebase on main
git rebase upstream/main

# Or merge
git merge upstream/main

Commit Changes

git add .
git commit -m "feat(scope): description"

See Contributing Guide for commit message format.

Push Changes

git push origin feature/my-awesome-feature

Documentation

Build Documentation Locally

cd docs
pip install -r requirements.txt
mkdocs serve

View at http://localhost:8000

Update Documentation

Documentation lives in:

  • README.md - Main project README
  • docs/ - MkDocs documentation site
  • Wiki - Community wiki (this page!)

Troubleshooting

Import Errors

Problem: ModuleNotFoundError: No module named 'mcpbr'

Solution:

pip install -e .

Test Failures

Problem: Tests fail with "Docker not running"

Solution: Ensure Docker Desktop is running

Linting Errors

Problem: ruff finds many errors

Solution:

ruff check --fix src/
ruff format src/

Type Errors

Problem: mypy reports type errors

Solution:

  • Add type hints to functions
  • Use # type: ignore for known issues
  • Update type stubs if needed

Performance Tips

Speed Up Tests

# Run tests in parallel
pytest -n auto

# Run only changed tests
pytest --lf  # Last failed
pytest --ff  # Failed first

Speed Up Docker Builds

Use build cache:

docker build --cache-from mcpbr-test .

Use BuildKit:

DOCKER_BUILDKIT=1 docker build .

Next Steps

  1. ✅ Verify setup - Run tests, check linting
  2. 📚 Read Contributing Guide - Understand workflow
  3. 🎯 Find an issue - Check good first issues
  4. 🔧 Make changes - Implement your feature/fix
  5. 🧪 Test thoroughly - Write and run tests
  6. 📝 Submit PR - Create pull request

Resources

Get Help

Stuck? We're here to help!

Happy developing! 🚀

Clone this wiki locally