golf

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Golf is a Python framework for building MCP (Model Context Protocol) servers with zero boilerplate. It automatically discovers, parses, and compiles Python files containing tools, resources, and prompts into a runnable FastMCP server.

## Authentication Compatibility

Golf 0.3.x targets FastMCP 4.0.0 and MCP 2026-07-28 while retaining
FastMCP's legacy-client compatibility:

- **Authentication System**: Complete rewrite using FastMCP's built-in auth providers (JWT, OAuth, Static tokens)
- **Legacy OAuth Removed**: Custom OAuth implementation replaced with standards-compliant FastMCP providers  
- **Configuration Changes**: `auth.py` configuration must be updated to use new auth configs (legacy `pre_build.py` supported)
- **Dependency Updates**: Requires exactly FastMCP 4.0.0, Python >=3.10, and Pydantic >=2.12
- **Removed Files**: Legacy `oauth.py` and `provider.py` files removed from auth module
- **Deprecated Functions**: `get_provider_token()` and OAuth-related helpers return None (legacy compatibility)

## Key Architecture

- **Component Discovery**: Golf automatically scans `tools/`, `resources/`, and `prompts/` directories for Python files
- **Code Generation**: The `ManifestBuilder` in `src/golf/core/builder.py` generates FastMCP server code from parsed components
- **CLI Interface**: Entry point is `src/golf/cli/main.py` with commands: `init`, `build`, `run`
- **Configuration**: Project settings managed via `golf.json` files, parsed by `src/golf/core/config.py`
- **Authentication**: JWT/OAuth auth using FastMCP 4.0.0 providers in `src/golf/auth/`
- **Telemetry**: Anonymous usage tracking with OpenTelemetry support in `src/golf/telemetry/`

## Common Development Commands

### Testing
```bash
# Run all tests with coverage
make test
# OR directly:
python -m pytest tests/ -v --cov=golf --cov-report=term-missing --cov-report=html

# Run tests without coverage (faster)
make test-fast
# OR directly:
python -m pytest tests/ -v
```

### Code Quality
```bash
# Run linting (ruff)
python -m ruff check src/

# Format code (ruff format only)
python -m ruff format src/ tests/
```

### Installation
```bash
# Install in development mode with telemetry dependencies
make install-dev

# Test CLI installation
golf --version
```

## Project Structure

- `src/golf/cli/` - CLI commands and entry points
- `src/golf/core/` - Core framework logic (builder, parser, config)
- `src/golf/auth/` - Authentication providers (OAuth, API keys)
- `src/golf/telemetry/` - Usage tracking and OpenTelemetry instrumentation
- `src/golf/metrics/` - Prometheus metrics collection
- `src/golf/examples/` - Example projects (basic template)
- `tests/` - Test suite with pytest

## Testing Framework

Uses pytest with these key configurations:
- Test discovery: `test_*.py` files in `tests/` directory
- Async support: `asyncio_mode = "auto"`
- Coverage reporting: HTML reports in `htmlcov/`
- Markers: `slow` and `integration` for test categorization
- Configuration in `pyproject.toml` under `[tool.pytest.ini_options]`

## Code Style

- **Black** formatting (88 char line length)
- **Ruff** linting with strict rules
- **Mypy** type checking with strict settings
- Configuration in `pyproject.toml`

## Git Commit Guidelines

Follow these commit message patterns when making changes:

- `fix[component]: description` - Bug fixes (e.g., `fix[parser]: handle edge case in import resolution`)
- `feat[component]: description` - New features (e.g., `feat[builder]: add shared file support`)
- `refactor[component]: description` - Code refactoring (e.g., `refactor[auth]: simplify provider creation`)
- `test[component]: description` - Test additions/changes (e.g., `test[core]: add integration tests`)
- `docs[component]: description` - Documentation updates (e.g., `docs[api]: update authentication guide`)
- `style[component]: description` - Code formatting (e.g., `style[core]: format with ruff`)

Examples from recent commits:
- `fix[parser]: add shared file discovery for enhanced imports`
- `fix[builder]: enhance import mapping for any shared file`
- `fix[transformer]: improve import transformation patterns`

## Component System

Golf projects have this structure:
```
project/
├── golf.json          # Configuration
├── tools/            # Tool implementations
├── resources/        # Resource implementations
├── prompts/          # Prompt templates
└── auth.py           # Optional authentication configuration
```

Component IDs are derived from file paths: `tools/payments/charge.py` becomes `charge_payments`.

## Authentication in Golf 0.3.x

Golf 0.3.x uses FastMCP 4.0.0's built-in authentication providers. JWT
configurations require an audience/resource binding; inbound MCP resource
tokens must never be forwarded to upstream APIs.

### JWT Authentication (Production)
```python
# In auth.py
from golf.auth import configure_jwt_auth

configure_jwt_auth(
    jwks_uri_env_var="JWKS_URI",  # JWKS endpoint
    issuer_env_var="JWT_ISSUER",
    audience_env_var="JWT_AUDIENCE", 
    required_scopes=["read:user"],
)
```

### Development Authentication
```python
# In auth.py
from golf.auth import configure_dev_auth

configure_dev_auth(
    tokens={
        "dev-token-123": {
            "client_id": "dev-client",
            "scopes": ["read", "write"],
        }
    },
    required_scopes=["read"],
)
```

### API Key header extraction (deprecated)
`configure_api_key()` is not MCP authentication. It only extracts a
caller-provided header for `get_api_key()` so tools can forward that
credential to an upstream API, which validates it. Golf does not check
the key value. Use JWT, OAuth, or development tokens to authenticate
MCP clients. This helper will be removed in a future release.