How golf-mcp/golf works
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.