# golf-mcp/golf architecture

> Architecture diagram of the GitHub repository golf-mcp/golf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/golf-mcp/golf
- Repository: https://github.com/golf-mcp/golf

## Overview

##### Project Type and Purpose
- Golf is neither a monolithic web app nor a simple library—it’s a **framework + CLI tool** for scaffolding, building, and running “MCP” servers.
- It discovers user‐defined *tools*, *prompts*, and *resources* in a conventional directory layout and compiles them into a FastMCP server with minimal boilerplate.

##### High-Level Architecture: Main Components
a. **CLI Frontend (“golf” command)**
- Commands: `golf init`, `golf build [dev|prod]`, `golf run`, `golf telemetry [enable|disable]`.
- Built on Python (likely using Click or Typer).
- Entry point: `src/golf/cli/main.py` → dispatches to `src/golf/commands/*`.
b. **Core Library**
- **Config Loader** (`core/config.py`): reads `golf.json` and `.env`.
- **Parser** (`core/parser.py`): scans project folder for `tools/`, `resources/`, `prompts/`.
- **Transformer** (`core/transformer.py`): compiles discovered Python modules into internal metadata.
- **Builder** (`core/builder.py` + `builder_auth.py` + `builder_telemetry.py`): assembles metadata, wires in auth and telemetry instrumentation.
- **Telemetry** (`telemetry/instrumentation.py` + `core/telemetry.py`): optional OpenTelemetry tracing.
- **Auth** (`auth/*`): API‐key and OAuth providers, helpers to inject credentials.
c. **Runtime Server**
- Underlying FastMCP server (external dependency).
- Supports transports: SSE, HTTP (streaming), or STDIO.
- Hosted on configured host/port.
d. **Examples & Templates** (`src/golf/examples/*`)
- Directory conventions, pre-build hooks, sample tools, resources, prompts.
e. **External Services**
- OpenTelemetry Collector / OTLP HTTP endpoint (optional).
- Third-party APIs used by user’s tools/resources (via auth providers).

##### Relationships & Data Flows
- User invokes **CLI** (e.g. `golf init` → scaffolding; `golf build` → builder pipeline; `golf run` → start server).
- **Builder pipeline**:
1. **Config Loader** reads `golf.json` & environment.
2. **Parser** performs file discovery.
3. **Transformer** generates in-memory representations (component IDs, schemas).
4. **Auth** and **Telemetry** builders instrument the components.
5. Baked metadata is emitted as a FastMCP app.
- **Run** spins up the FastMCP server:
- Incoming client requests → transport layer → matching component handler → executes user’s Python function → returns payload via SSE/HTTP/STDIO.
- **Telemetry** collectors record trace spans and export to console or OTLP endpoint.
- **Auth** modules supply credentials to tools that call external APIs.

##### Architectural Patterns
- **Plugin / Discovery**: automatic file system scanning of user code.
- **Builder Pattern**: incremental assembly of the server from discrete builder steps.
- **Pipeline**: config → parse → transform → instrument → output.
- **Modular**: clear separation between CLI, core logic, auth, telemetry, and runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Frontend"
        direction TB
        CLI_Main["main.py"]:::cli
        CLI_Init["init.py"]:::cli
        CLI_Build["build.py"]:::cli
        CLI_Run["run.py"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        Config["Config Loader"]:::core
        Parser["Parser"]:::core
        Transformer["Transformer"]:::core
        subgraph "Builder Pipeline"
            direction TB
            Builder_Core["builder.py"]:::core
            Builder_Auth["builder_auth.py"]:::core
            Builder_Telemetry["builder_telemetry.py"]:::core
        end
        subgraph "Telemetry Modules"
            direction TB
            Core_Telemetry["core/telemetry.py"]:::core
            Instr["instrumentation.py"]:::core
        end
        subgraph "Auth Modules"
            direction TB
            APIKey["api_key.py"]:::core
            OAuth["oauth.py"]:::core
            Helpers["helpers.py"]:::core
            Provider["provider.py"]:::core
        end
    end

    %% Runtime Server
    subgraph "Runtime Server"
        direction TB
        FastMCP["FastMCP Server"]:::runtime
        SSE["SSE/HTTP/STDIO Transport"]:::runtime
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OTLP["OTLP HTTP Endpoint"]:::external
        ThirdParty["Third-Party APIs"]:::external
    end

    %% Flows
    CLI_Init -->|"scaffolding"| Examples
    CLI_Build -->|"reads config"| Config
    Config -->|"discovers files"| Parser
    Parser -->|"generates metadata"| Transformer
    Transformer -->|"assembles core"| Builder_Core
    Builder_Core -->|"inject auth"| Builder_Auth
    Builder_Core -->|"inject telemetry"| Builder_Telemetry
    Builder_Auth -->|"uses auth modules"| APIKey & OAuth & Helpers & Provider
    Builder_Telemetry -->|"uses telemetry modules"| Core_Telemetry & Instr
    Builder_Telemetry -->|"exports traces"| OTLP
    Builder_Auth -->|"supplies creds"| ThirdParty
    Builder_Telemetry --> FastMCP
    CLI_Run --> FastMCP
    FastMCP -->|"listens on transport"| SSE
    SSE -->|"invokes handler"| Transformer
    Transformer -->|"executes function"| SSE
    SSE -->|"returns response"| Client

    %% Examples Node
    Examples["Examples & Templates"]:::core

    %% Click events
    click CLI_Main "https://github.com/golf-mcp/golf/blob/main/src/golf/cli/main.py"
    click CLI_Init "https://github.com/golf-mcp/golf/blob/main/src/golf/commands/init.py"
    click CLI_Build "https://github.com/golf-mcp/golf/blob/main/src/golf/commands/build.py"
    click CLI_Run "https://github.com/golf-mcp/golf/blob/main/src/golf/commands/run.py"
    click Config "https://github.com/golf-mcp/golf/blob/main/src/golf/core/config.py"
    click Parser "https://github.com/golf-mcp/golf/blob/main/src/golf/core/parser.py"
    click Transformer "https://github.com/golf-mcp/golf/blob/main/src/golf/core/transformer.py"
    click Builder_Core "https://github.com/golf-mcp/golf/blob/main/src/golf/core/builder.py"
    click Builder_Auth "https://github.com/golf-mcp/golf/blob/main/src/golf/core/builder_auth.py"
    click Builder_Telemetry "https://github.com/golf-mcp/golf/blob/main/src/golf/core/builder_telemetry.py"
    click Core_Telemetry "https://github.com/golf-mcp/golf/blob/main/src/golf/core/telemetry.py"
    click Instr "https://github.com/golf-mcp/golf/blob/main/src/golf/telemetry/instrumentation.py"
    click APIKey "https://github.com/golf-mcp/golf/blob/main/src/golf/auth/api_key.py"
    click OAuth "https://github.com/golf-mcp/golf/blob/main/src/golf/auth/oauth.py"
    click Helpers "https://github.com/golf-mcp/golf/blob/main/src/golf/auth/helpers.py"
    click Provider "https://github.com/golf-mcp/golf/blob/main/src/golf/auth/provider.py"
    click Examples "https://github.com/golf-mcp/golf/tree/main/src/golf/examples/basic"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085
    classDef core fill:#d4edda,stroke:#155724,color:#155724
    classDef runtime fill:#ffe5b4,stroke:#c77600,color:#c77600
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
