golf: Instructions file for Claude Code

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

# 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