> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

> Understand GolfMCP project layout and component naming conventions.

GolfMCP uses a convention-based project structure.

```
<project-root>/
├── golf.json
├── auth.py               # Authentication configuration (v0.2.0)
├── startup.py            # Optional initialization script (v0.2.10)
├── health.py             # Optional health check endpoint (v0.2.11)
├── readiness.py          # Optional readiness check endpoint (v0.2.11)
├── prompts/
│   └── example_prompt.py
├── resources/
│   └── example_resource.py
│   └── sub_category/
│       └── nested_resource.py
│       └── common.py
└── tools/
    └── example_tool.py
    └── payments/
        └── common.py
        └── get_balance.py
        └── transaction/
            └── submit.py
```

* **`golf.json`**: The main configuration file (see [Configuration](/golf-mcp-framework/configuration)).
* **`auth.py`**: Dedicated authentication configuration file (see [Authentication](/golf-mcp-framework/authentication)).
* **`startup.py`**: Optional initialization script for environment setup and server startup configuration.
* **`health.py`**: Optional custom health check endpoint with sophisticated monitoring logic (see [Telemetry & Monitoring](/golf-mcp-framework/telemetry-monitoring)).
* **`readiness.py`**: Optional custom readiness check endpoint for Kubernetes-style probes (see [Telemetry & Monitoring](/golf-mcp-framework/telemetry-monitoring)).
* **`tools/`**: Contains Python files defining your server's tools (see [Component Specification](/golf-mcp-framework/component-specification)).
* **`resources/`**: Contains Python files defining data resources the LLM can read (see [Component Specification](/golf-mcp-framework/component-specification)).
* **`prompts/`**: Contains Python files defining reusable prompt templates (see [Component Specification](/golf-mcp-framework/component-specification)).

<Note>
  **Deprecated:** Authentication configuration in `pre_build.py` is deprecated. Use the dedicated `auth.py` file instead for cleaner organization and better maintainability.
</Note>

### Component discovery

* Each `.py` file within `tools/`, `resources/`, or `prompts/` (and their subdirectories) is treated as a single component.
* Files named `__init__.py` are ignored for direct component definition but are essential for Python's packaging if you structure your components as modules.
* Files named `common.py` are special and used for shared code (see [Shared Logic documentation](/golf-mcp-framework/shared-logic-common-py)).
* The `auth.py` file is treated specially for authentication configuration and is not considered a component.
* The `startup.py` file is treated specially for server initialization and is not considered a component.
* The `health.py` and `readiness.py` files are treated specially for health check endpoints and are not considered components.

### Component ID derivation

The unique ID for each component is derived from its file path relative to the category directory (`tools`, `resources`, `prompts`).

**Examples:**

* `tools/hello.py`                 -> ID: `hello`
* `tools/payments/transaction/submit.py` -> ID: `submit-transaction-payments`
* `resources/weather/current.py`   -> ID: `current-weather`

ID collisions will result in a build-time error.

## Authentication configuration

### The `auth.py` file (new in v0.2.0)

Golf v0.2.0 introduces a dedicated `auth.py` file for authentication configuration, providing better organization and cleaner separation from other build logic.

**Example `auth.py` configurations** (for full details, see [Authentication](/golf-mcp-framework/authentication)):

```python theme={null}
# auth.py - API Key Authentication
from golf.auth import configure_api_key

configure_api_key(
    header_name="Authorization",
    header_prefix="Bearer "
)
```

```python theme={null}
# auth.py - JWT Authentication
from golf.auth import configure_auth, JWTAuthConfig

configure_auth(
    JWTAuthConfig(
        jwks_uri_env_var="JWKS_URI",
        issuer_env_var="JWT_ISSUER",
        audience_env_var="JWT_AUDIENCE",
        required_scopes=["read:user"]
    )
)
```

```python theme={null}
# auth.py - Development Authentication
from golf.auth import configure_auth, StaticTokenConfig

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

## Runtime initialization

### The `startup.py` file (optional)

The `startup.py` file is an **optional initialization script** that allows projects to execute custom code before the FastMCP server starts. It's designed for setting environment variables, loading secrets, and performing project-specific setup.

**Key characteristics:**

* **Optional**: Projects work without it
* **Runtime execution**: Runs when the server starts, not during build
* **Environment focused**: Primarily used for secrets, API keys, and configuration

#### Core implementation

The startup script functionality is automatically detected during build and executed at server runtime with robust error handling.

#### Common usage patterns

**Basic Environment Setup:**

```python theme={null}
# startup.py
import os

os.environ.setdefault("GOLF_DEBUG", "true")
os.environ["DATABASE_URL"] = "sqlite:///app.db"
print("Startup script executed successfully")
```

**API Key and Secrets Loading:**

```python theme={null}
# startup.py
import os

# Configure API keys
os.environ["OPENAI_API_KEY"] = "test-openai-key"
os.environ["ANTHROPIC_API_KEY"] = "test-anthropic-key"

print("Environment configured successfully")
```