Agent Guidelines for mcpbr Development

Agent Guidelines for mcpbr Development

This document provides guidelines for AI agents (e.g., Claude Code agents) working on the mcpbr project. Following these guidelines ensures consistent, high-quality contributions.

Table of Contents

1. Virtual Environment Setup ← START HERE
2. Pre-Commit Checklist
3. Code Quality Requirements
4. Testing Requirements
5. Documentation Requirements
6. Pull Request Guidelines

Virtual Environment Setup

⚠️ CRITICAL: ALWAYS USE A VIRTUAL ENVIRONMENT

macOS uses system Python protection (PEP 668) which prevents installing packages globally. DO NOT use --break-system-packages or try to install packages system-wide. Instead, ALWAYS use a virtual environment or uv/uvx.

Option 1: Using uv (Recommended)

The project uses uv for dependency management. Use uvx for running commands and uv run for scripts:

# Run commands without installation
uvx ruff check src/ tests/
uvx ruff format src/ tests/

# Run Python scripts/tests
uv run pytest -m "not integration"

# Install project in development mode (if needed)
uv pip install -e ".[dev]"

This is the preferred approach as it's already configured in the project.

Option 2: Traditional Virtual Environment

If you need a traditional venv:

# Create virtual environment (one time)
python3 -m venv .venv

# Activate it (REQUIRED for every terminal session)
source .venv/bin/activate

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

# Now you can use pip and run commands normally
pip install pre-commit
pytest -m "not integration"

# Deactivate when done
deactivate

Option 3: Using pipx for Global Tools

For global tools like pre-commit, use pipx:

# Install pipx (one time)
brew install pipx

# Install global tools
pipx install pre-commit
pipx install pytest

Checking Active Environment

Before running Python commands, verify your environment:

# Check if in a virtual environment
echo $VIRTUAL_ENV

# Should show path like: /Users/you/Projects/mcpbr/.venv

# Check Python location
which python3
# Should NOT be: /usr/bin/python3 (system Python)
# Should be: .venv/bin/python3 (venv) or managed by uv

Common Errors and Solutions

Error: externally-managed-environment

# ❌ DON'T: Try to install globally
pip install something

# ✅ DO: Use uv or venv
uvx something  # for CLI tools
uv run python script.py  # for scripts
# OR activate venv first
source .venv/bin/activate && pip install something

Error: command not found: pytest

# ❌ DON'T: Install globally
pip install pytest

# ✅ DO: Use uv run or activate venv
uv run pytest  # preferred
# OR
source .venv/bin/activate && pytest

Project Setup Workflow

When starting work on this project:

# 1. Clone the repository
git clone https://github.com/greynewell/mcpbr.git
cd mcpbr

# 2. Choose your environment approach:

# Option A: Using uv (recommended)
# No setup needed! Just use `uvx` and `uv run` commands

# Option B: Using venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# 3. Install pre-commit hooks (one time)
pipx install pre-commit  # if not already installed
pre-commit install

# 4. Verify setup
uv run pytest --version  # Should work
uvx ruff --version  # Should work

Remember

• NEVER install Python packages system-wide on macOS
• ALWAYS use uv run / uvx OR activate venv first
• CHECK your environment with echo $VIRTUAL_ENV when debugging
• The project is configured to use uv - prefer uvx and uv run commands

Pre-Commit Checklist

MANDATORY: Before committing code or creating a pull request, agents MUST complete ALL of the following steps:

1. Run Linting

# Check for linting issues
uvx ruff check src/ tests/

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

# Format code
uvx ruff format src/ tests/

# Verify all issues are resolved
uvx ruff check src/ tests/

Expected output: All checks passed!

If any linting errors remain, they MUST be fixed manually before proceeding.

Quick one-liner:

uvx ruff check --fix src/ tests/ && uvx ruff format src/ tests/ && uvx ruff check src/ tests/

2. Run Type Checking

# Run mypy on source code
uv run mypy src/mcpbr/

Expected output: Success: no issues found

If any type errors remain, they MUST be fixed before proceeding.

3. Run Tests

# Run all non-integration tests
uv run pytest -m "not integration"

# For integration tests (if applicable)
uv run pytest -m integration

Expected result: All tests must pass with 0 failures.

4. Update CHANGELOG

MANDATORY: If your changes are user-visible, update CHANGELOG.md:

# Edit CHANGELOG.md and add entry under [Unreleased]
# Example:
# ### Fixed
# - Fixed XYZ issue (#123)

# Verify entry is properly formatted
cat CHANGELOG.md | head -30

5. Verify Changes

• Review all modified files
• Ensure no unintended changes were introduced
• Confirm all new code follows project conventions
• Check that imports are properly organized
• Verify CHANGELOG.md is updated (if applicable)

Code Quality Requirements

Linting Rules

The project uses Ruff for linting with the following configuration:

• Line length: 100 characters (E501 is ignored)
• Target Python version: 3.11+
• Enabled rules: E (pycodestyle), F (pyflakes), I (isort), N (pep8-naming), W (warnings), B (bugbear), UP (pyupgrade), SIM (simplify), RUF (ruff-specific), C4 (comprehensions), PIE (misc), PT (pytest-style), ASYNC (async bugs), S (security/bandit), T20 (print detection)
• Type checking: mypy with Pydantic plugin, strict mode on core modules

Common Linting Issues to Avoid

1. Unused imports - Remove all unused imports
2. Import sorting - Imports must be sorted (stdlib → third-party → local)
3. Undefined names - All variables and functions must be defined before use
4. Line too long - While E501 is ignored, try to keep lines under 100 chars when reasonable
5. Trailing whitespace - Remove trailing whitespace from all lines
6. Mutable default args (B006) - Don't use [] or {} as default arguments
7. Exception chaining (B904) - Use raise X from err inside except blocks
8. Modern Python (UP) - Use Python 3.11+ patterns (e.g., X | Y unions, match statements)
9. Simplifications (SIM) - Collapse nested with/if statements, use contextlib.suppress()

Code Style

• Use type hints for function signatures
• Use descriptive variable names
• Follow PEP 8 naming conventions:
  • snake_case for functions and variables
  • PascalCase for classes
  • UPPER_CASE for constants
• Add docstrings for public functions and classes

Testing Requirements

Test Coverage

• New features must have comprehensive test coverage
• Bug fixes should include regression tests
• Aim for at least 80% code coverage on new code

Test Organization

• Place tests in tests/ directory
• Mirror source file structure (e.g., src/mcpbr/foo.py → tests/test_foo.py)
• Use pytest fixtures for common setup
• Mark integration tests with @pytest.mark.integration

Test Naming

• Test files: test_*.py
• Test classes: Test*
• Test functions: test_*
• Use descriptive names that explain what is being tested

Running Tests

# Run all non-integration tests
uv run pytest -m "not integration"

# Run specific test file
uv run pytest tests/test_foo.py

# Run with coverage
uv run pytest --cov=src/mcpbr --cov-report=html

# Run integration tests (requires setup)
uv run pytest -m integration

Documentation Requirements

Code Documentation

• Add docstrings to all public functions, classes, and modules
• Use Google-style docstrings
• Include type hints in function signatures

Example:

def calculate_cost(tokens_in: int, tokens_out: int, model: str) -> float:
    """Calculate the cost of an API call.

    Args:
        tokens_in: Number of input tokens
        tokens_out: Number of output tokens
        model: Model identifier (e.g., 'claude-sonnet-4-5-20250929')

    Returns:
        Total cost in USD

    Raises:
        ValueError: If model is not supported
    """
    ...

README Updates

If your changes affect:

• CLI commands
• Configuration format
• Features or capabilities
• Installation or setup

Then you MUST update the README.md accordingly.

Changelog Maintenance

CRITICAL RULE: The CHANGELOG.md MUST be updated with EVERY user-facing change, AUTOMATICALLY, WITHOUT BEING ASKED.

When to Update CHANGELOG

Update CHANGELOG.md for ANY of these changes:

• ✅ New features or functionality
• ✅ Bug fixes
• ✅ Breaking changes
• ✅ Deprecations
• ✅ Security fixes
• ✅ Performance improvements that users will notice
• ✅ Changes to CLI commands or configuration
• ✅ Changes to output formats or APIs
• ❌ Internal refactoring with no user impact
• ❌ Test additions (unless they expose new testing capabilities)
• ❌ Documentation fixes (unless significant new documentation)

How to Update CHANGELOG

1. Add entries to the [Unreleased] section - This is where all in-progress changes go
2. Use the correct category:
   • Added - New features, capabilities, configuration options
   • Changed - Changes to existing functionality
   • Deprecated - Features marked for removal
   • Removed - Removed features
   • Fixed - Bug fixes
   • Security - Security-related changes
   • Infrastructure - Build, release, or infrastructure changes
   • Documentation - Significant documentation additions (not fixes)
3. Write clear, user-focused descriptions:
   • Start with what changed, not how
   • Include issue/PR numbers: (#123) or (closes #123)
   • Use past tense
   • Add sub-bullets for important details
4. Format consistently:

   ## [Unreleased]
   
   ### Added
   
   - **Feature Name** (#123): Brief description
     - Additional detail about the feature
     - Another important detail
   

Example Workflow

# 1. Make code changes
# ... edit files ...

# 2. Update CHANGELOG.md (REQUIRED - don't skip this!)
# Add entry under [Unreleased] section:
# ### Fixed
# - Fixed bug in git diff detection (#335)
#   - Now detects newly created files correctly
#   - Applied fallback pattern to both Docker and local modes

# 3. Commit both together
git add src/ CHANGELOG.md
git commit -m "fix: Resolve git diff detection for new files (#335)"

Version Management on Main Branch

IMPORTANT: The version in pyproject.toml on the main branch is ALWAYS the version for the NEXT release, not the current released version.

• After releasing v0.4.1, main is automatically bumped to v0.4.2
• All changes on main are being prepared for v0.4.2
• When you update CHANGELOG, add entries under [Unreleased]
• When a release is published, unreleased changes move to the new version section

Release Process and CHANGELOG

The release process works like this:

1. Development Phase:

   • Changes accumulate under [Unreleased] section
   • Version in pyproject.toml reflects the upcoming release (e.g., 0.4.3)

2. Release Phase:

   • Maintainer manually publishes release in GitHub UI (e.g., v0.4.3)
   • Post-release workflow automatically bumps version to next patch (e.g., 0.4.4)
   • Maintainer moves [Unreleased] changes to ## [0.4.3] - YYYY-MM-DD section
   • Adds version link at bottom: [0.4.3]: https://github.com/greynewell/mcpbr/releases/tag/v0.4.3

3. Post-Release:

   • [Unreleased] section is now empty, ready for next changes
   • Version on main is 0.4.4
   • Next changes go under [Unreleased] for eventual 0.4.4 release

CRITICAL: Always add your changes to [Unreleased]. The maintainer will move them to the versioned section during release.

Before Creating a PR

Checklist for CHANGELOG:

• All user-visible changes are documented under [Unreleased]
• Entries are in the correct category (Added/Fixed/Changed/etc.)
• Descriptions are clear and user-focused
• Issue/PR numbers are included: (#123)
• Format matches existing entries

Pull Request Guidelines

Before Creating a PR

1. ✅ All linting checks pass (uvx ruff check src/ tests/)
2. ✅ Code is formatted (uvx ruff format src/ tests/)
3. ✅ Type checking passes (uv run mypy src/mcpbr/)
4. ✅ All tests pass (uv run pytest -m "not integration")
5. ✅ CHANGELOG.md is updated (for user-visible changes)
6. ✅ Code is documented
7. ✅ README is updated (if applicable)
8. ✅ Changes are committed with descriptive commit messages

PR Title Format

Use conventional commit format:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• test: - Test additions or changes
• refactor: - Code refactoring
• chore: - Maintenance tasks

Examples:

• feat: add YAML export for results
• fix: resolve linting issues
• docs: update installation instructions

PR Description

Include:

1. Summary - What does this PR do?
2. Changes - Detailed list of changes
3. Testing - How was this tested?
4. Related Issues - Link to issues using fixes #123 or closes #123

Linking Issues

Use GitHub keywords in PR description to auto-close issues:

• fixes #123
• closes #123
• resolves #123

Responding to CodeRabbit Reviews

REQUIRED: When CodeRabbit posts review comments on your PR, you MUST acknowledge and respond to them.

When You Fix a CodeRabbit Comment

If you push a commit that addresses a CodeRabbit comment:

1. Add a comment to the PR explaining what you fixed:

   ✅ **Resolved CodeRabbit comment about XYZ (commit abc1234)**
   
   Fixed the issue by:
   - Specific change 1
   - Specific change 2
   
   The corrected code now [explanation of fix].
   

2. Reference the specific comment if there are multiple:

   ✅ **Resolved: CLI override documentation issue**
   
   Fixed in commit 8185e60:
   - Removed incorrect `--thinking-budget` CLI override examples
   - Added warning that thinking_budget is YAML-only
   - Documented correct way to disable (omit field or set to null)
   

3. Be specific - Don't just say "fixed", explain what you changed

When You Disagree with CodeRabbit

If you believe a CodeRabbit suggestion is incorrect or not applicable:

1. Explain your reasoning in a comment:

   ❌ **CodeRabbit suggestion not applicable**
   
   The suggestion to [X] doesn't apply here because:
   - Reason 1
   - Reason 2
   
   The current implementation is correct as-is.
   

2. Ask for maintainer input if uncertain:

   ❓ **Need guidance on CodeRabbit suggestion**
   
   CodeRabbit suggests [X], but I'm not sure if this is the right approach.
   Current approach: [Y]
   CodeRabbit approach: [X]
   
   @maintainer - Which approach should I take?
   

Why This Matters

• Shows you're responsive to code review feedback
• Helps maintainers track which issues are resolved
• Creates a clear audit trail of what changed and why
• Prevents CodeRabbit comments from being ignored or forgotten
• Makes PR review faster (maintainers don't have to re-check everything)

Common Pitfalls for Agents

❌ DON'T: Skip Linting

# Bad: Committing without checking linting
git commit -m "feat: add new feature"
git push

✅ DO: Check Linting First

# Good: Check linting and types before commit
uvx ruff check --fix src/ tests/
uvx ruff format src/ tests/
uv run mypy src/mcpbr/
uv run pytest -m "not integration"
git commit -m "feat: add new feature"
git push

❌ DON'T: Create PRs with Failing Tests

Always verify tests pass locally before pushing.

✅ DO: Run Full Test Suite

# Run tests before creating PR
uv run pytest -m "not integration"
# Verify all tests pass, then push

❌ DON'T: Ignore Import Order

Ruff will fail if imports are not properly sorted.

✅ DO: Let Ruff Fix Import Order

# Ruff will automatically fix import sorting
uvx ruff check --fix src/ tests/

Workflow Example

Here's a complete workflow for implementing a feature:

# 1. Create a branch
git checkout -b feature/my-new-feature

# 2. Implement the feature
# ... edit files ...

# 3. Update CHANGELOG.md (REQUIRED for user-visible changes)
# Add entry under [Unreleased] section:
# ### Added
# - **New Feature**: Description of feature (#123)
#   - Additional details

# 4. Check linting and format
uvx ruff check --fix src/ tests/
uvx ruff format src/ tests/
uvx ruff check src/ tests/  # Verify all fixed

# 5. Run type checking
uv run mypy src/mcpbr/

# 6. Run tests
uv run pytest -m "not integration"

# 7. Commit changes (include CHANGELOG.md)
git add src/ tests/ CHANGELOG.md
git commit -m "feat: add my new feature"

# 8. Push and create PR
git push -u origin feature/my-new-feature
gh pr create --title "feat: add my new feature" --body "Implements #123"

Questions?

If you encounter issues or have questions:

• Check existing issues: https://github.com/greynewell/mcpbr/issues
• Review CI/CD logs for failed checks
• Consult the main README.md for setup instructions

CI/CD Pipeline

The project uses GitHub Actions for CI/CD. All PRs must pass:

1. Lint Check - uvx ruff check src/ tests/
2. Format Check - uvx ruff format --check src/ tests/
3. Type Check - mypy src/mcpbr/
4. Build Check - Package builds successfully
5. Test (Python 3.11) - All tests pass on Python 3.11
6. Test (Python 3.12) - All tests pass on Python 3.12

You can view check results on any PR:

gh pr checks <PR_NUMBER>

Summary

Remember: The most important rule is to run linting, formatting, type checking, and tests BEFORE committing. This ensures high code quality and prevents CI/CD failures.

Pre-commit command:

uvx ruff check --fix src/ tests/ && uvx ruff format src/ tests/ && uv run mypy src/mcpbr/ && uv run pytest -m "not integration"

Happy coding! 🚀