mcpbr AGENTS.md

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