golf-mcp 0.1.20__tar.gz → 0.2.1__tar.gz

golf_mcp-0.2.1/.docs/fastmcp-diff.md

@@ -0,0 +1,27 @@
+**FastMCP Changes Since v2.5.1**
+
+**Breaking Changes**
+
+* **Decorator & API Refactor**: Decorators now return their created Tool/Resource object; old auto-conversion methods are deprecated.
+* **OpenAPI Routes as Tools**: All OpenAPI endpoints are treated as Tools by default, changing prior behavior.
+* **MCP Spec 1.10 (v2.10.0)**: `client.call_tool()` now returns a `CallToolResult` (with `result` property) instead of raw JSON. Requires MCP Python SDK ≥1.10.
+* **CLI Flag Rename**: `fastmcp run --server` is replaced by `--name`.
+* **Removed Custom Separators**: Support for custom nested-resource separators was dropped.
+
+**Non-Breaking Improvements & New Features**
+
+* **Built-In Authentication**
+
+  * Bearer-token support (v2.6.0)
+  * OAuth2 & WorkOS AuthProvider integration (v2.11.0)
+  * Enhanced JWT handling, scopes, and debug logging
+* **Session & State Management**
+
+  * `ctx.session_id` property for each request (v2.9.0)
+  * Persistent session-state dict via `ctx.state` (v2.11.0)
+* **Middleware System** (v2.9.0): Plug in logging, auth checks, rate limiting, etc.
+* **Tool Transforms & Tagging** (v2.8.0): Wrap, rename, enable/disable tools at runtime; filter by tags.
+* **Structured Outputs & Elicitation** (v2.10.0): JSON schemas for tool outputs; interactive parameter prompting.
+* **Hot-Reload Notifications** (v2.9.1): Clients are notified when tools/resources change at runtime.
+* **Audio Content Support** (v2.8.1): Tools can handle audio inputs/outputs.
+* **Performance & Stability**: Optimized OpenAPI parsing, concurrency fixes, standardized logging.

{golf_mcp-0.1.20/src/golf_mcp.egg-info → golf_mcp-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: golf-mcp
-Version: 0.1.20
+Version: 0.2.1
 Summary: Framework for building MCP servers
 Author-email: Antoni Gmitruk <antoni@golf.dev>
 License-Expression: Apache-2.0
@@ -21,8 +21,9 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typer>=0.15.4
 Requires-Dist: rich>=14.0.0
-Requires-Dist: fastmcp<2.6.0,>=2.0.0
+Requires-Dist: fastmcp<3.0.0,>=2.11.0
 Requires-Dist: pydantic>=2.11.0
+Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: black>=24.10.0
 Requires-Dist: pyjwt>=2.0.0
@@ -67,9 +68,9 @@ Dynamic: license-file
 
 ## Overview
 
-Golf is a **framework** designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—*tools*, *prompts*, and *resources*—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable FastMCP server, minimizing boilerplate and accelerating development.
+Golf is a **framework** designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—*tools*, *prompts*, and *resources*—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable MCP server, minimizing boilerplate and accelerating development.
 
-With Golf, you can focus on implementing your agent's logic rather than wrestling with server setup and integration complexities. It's built for developers who want a quick, organized way to build powerful MCP servers.
+With Golf v0.2.0, you get **enterprise-grade authentication** (JWT, OAuth Server, API key, development tokens), **built-in utilities** for LLM interactions, and **automatic telemetry** integration. Focus on implementing your agent's logic while Golf handles authentication, monitoring, and server infrastructure.
 
 ## Quick Start
 
@@ -101,7 +102,7 @@ cd your-project-name
 golf build dev
 golf run
 ```
-This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`).
+This will start the MCP server, typically on `http://localhost:3000` (configurable in `golf.json`).
 
 That's it! Your Golf server is running and ready for integration.
 
@@ -124,10 +125,11 @@ A Golf project initialized with `golf init` will have a structure similar to thi
 │   └─ welcome.py     # Example prompt
 │
 ├─ .env               # Environment variables (e.g., API keys, server port)
-└─ pre_build.py       # (Optional) Script for pre-build hooks (e.g., auth setup)
+└─ auth.py            # Authentication configuration (JWT, OAuth Server, API key, dev tokens)
 ```
 
 -   **`golf.json`**: Configures server name, port, transport, telemetry, and other build settings.
+-   **`auth.py`**: Dedicated authentication configuration file (new in v0.2.0, breaking change from v0.1.x authentication API) for JWT, OAuth Server, API key, or development authentication.
 -   **`tools/`**, **`resources/`**, **`prompts/`**: Contain your Python files, each defining a single component. These directories can also contain nested subdirectories to further organize your components (e.g., `tools/payments/charge.py`). The module docstring of each file serves as the component's description.
     -   Component IDs are automatically derived from their file path. For example, `tools/hello.py` becomes `hello`, and a nested file like `tools/payments/submit.py` would become `submit_payments` (filename, followed by reversed parent directories under the main category, joined by underscores).
 -   **`common.py`** (not shown, but can be placed in subdirectories like `tools/payments/common.py`): Used to share code (clients, models, etc.) among components in the same subdirectory.
@@ -164,118 +166,63 @@ export = hello
 ```
 Golf will automatically discover this file. The module docstring `"""Hello World tool {{project_name}}."""` is used as the tool's description. It infers parameters from the `hello` function's signature and uses the `Output` Pydantic model for the output schema. The tool will be registered with the ID `hello`.
 
-## Configuration (`golf.json`)
+## Authentication & Features
 
-The `golf.json` file is the heart of your Golf project configuration. Here's what each field controls:
+Golf includes enterprise-grade authentication, built-in utilities, and automatic telemetry:
 
-```jsonc
-{
-  "name": "{{project_name}}",          // Your MCP server name (required)
-  "description": "A Golf project",     // Brief description of your server's purpose
-  "host": "127.0.0.1",                // Server host - use "0.0.0.0" to listen on all interfaces
-  "port": 3000,                       // Server port - any available port number
-  "transport": "sse",                 // Communication protocol:
-                                      // - "sse": Server-Sent Events (recommended for web clients)
-                                      // - "streamable-http": HTTP with streaming support
-                                      // - "stdio": Standard I/O (for CLI integration)
-  
-  // HTTP Transport Configuration (optional)
-  "stateless_http": false,            // Make streamable-http transport stateless (new session per request)
-                                      // When true, server restarts won't break existing client connections
-  
-  // Health Check Configuration (optional)
-  "health_check_enabled": false,      // Enable health check endpoint for Kubernetes/load balancers
-  "health_check_path": "/health",     // HTTP path for health check endpoint
-  "health_check_response": "OK",      // Response text returned by health check
-  
-  // OpenTelemetry Configuration (optional)
-  "opentelemetry_enabled": false,     // Enable distributed tracing
-  "opentelemetry_default_exporter": "console"  // Default exporter if OTEL_TRACES_EXPORTER not set
-                                               // Options: "console", "otlp_http"
-}
-```
-
-### Key Configuration Options:
-
-- **`name`**: The identifier for your MCP server. This will be shown to clients connecting to your server.
-- **`transport`**: Choose based on your client needs:
-  - `"sse"` is ideal for web-based clients and real-time communication
-  - `"streamable-http"` provides HTTP streaming for traditional API clients
-  - `"stdio"` enables integration with command-line tools and scripts
-- **`host` & `port`**: Control where your server listens. Use `"127.0.0.1"` for local development or `"0.0.0.0"` to accept external connections.
-- **`stateless_http`**: When true, makes the streamable-http transport stateless by creating a new session for each request. This ensures that server restarts don't break existing client connections, making the server truly stateless.
-- **`health_check_enabled`**: When true, enables a health check endpoint for Kubernetes readiness/liveness probes and load balancers
-- **`health_check_path`**: Customizable path for the health check endpoint (defaults to "/health")
-- **`health_check_response`**: Customizable response text for successful health checks (defaults to "OK")
-- **`opentelemetry_enabled`**: When true, enables distributed tracing for debugging and monitoring your MCP server
-- **`opentelemetry_default_exporter`**: Sets the default trace exporter. Can be overridden by the `OTEL_TRACES_EXPORTER` environment variable
-
-## Features
-
-### 🏥 Health Check Support
-
-Golf includes built-in health check endpoint support for production deployments. When enabled, it automatically adds a custom HTTP route that can be used by:
-- Kubernetes readiness and liveness probes
-- Load balancers and reverse proxies
-- Monitoring systems
-- Container orchestration platforms
-
-#### Configuration
-
-Enable health checks in your `golf.json`:
-```json
-{
-  "health_check_enabled": true,
-  "health_check_path": "/health",
-  "health_check_response": "Service is healthy"
-}
+```python
+# auth.py - Configure authentication
+from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig
+
+# JWT authentication (production)
+configure_auth(JWTAuthConfig(
+    jwks_uri_env_var="JWKS_URI",
+    issuer_env_var="JWT_ISSUER", 
+    audience_env_var="JWT_AUDIENCE",
+    required_scopes=["read", "write"]
+))
+
+# OAuth Server mode (Golf acts as OAuth 2.0 server)
+# configure_auth(OAuthServerConfig(
+#     base_url="https://your-golf-server.com",
+#     valid_scopes=["read", "write", "admin"]
+# ))
+
+# Static tokens (development only)
+# configure_auth(StaticTokenConfig(
+#     tokens={"dev-token": {"client_id": "dev", "scopes": ["read"]}}
+# ))
+
+# Built-in utilities available in all tools
+from golf.utils import elicit, sample, get_context
 ```
 
-The generated server will include a route like:
-```python
-@mcp.custom_route('/health', methods=["GET"])
-async def health_check(request: Request) -> PlainTextResponse:
-    """Health check endpoint for Kubernetes and load balancers."""
-    return PlainTextResponse("Service is healthy")
+```bash
+# Automatic telemetry with Golf Platform
+export GOLF_API_KEY="your-key"
+golf run  # ✅ Telemetry enabled automatically
 ```
 
-### 🔍 OpenTelemetry Support
+**[📚 Complete Documentation →](https://docs.golf.dev)**
 
-Golf includes built-in OpenTelemetry instrumentation for distributed tracing. When enabled, it automatically traces:
-- Tool executions with arguments and results
-- Resource reads and template expansions
-- Prompt generations
-- HTTP requests and sessions
+## Configuration
 
-#### Configuration
+Basic configuration in `golf.json`:
 
-Enable OpenTelemetry in your `golf.json`:
 ```json
 {
-  "opentelemetry_enabled": true,
-  "opentelemetry_default_exporter": "otlp_http"
+  "name": "My Golf Server",
+  "host": "localhost",
+  "port": 3000,
+  "transport": "sse",
+  "opentelemetry_enabled": false,
+  "detailed_tracing": false
 }
 ```
 
-Then configure via environment variables:
-```bash
-# For OTLP HTTP exporter (e.g., Jaeger, Grafana Tempo)
-OTEL_TRACES_EXPORTER=otlp_http
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
-OTEL_SERVICE_NAME=my-golf-server  # Optional, defaults to project name
-
-# For console exporter (debugging)
-OTEL_TRACES_EXPORTER=console
-```
-
-**Note**: When using the OTLP HTTP exporter, you must set `OTEL_EXPORTER_OTLP_ENDPOINT`. If not configured, Golf will display a warning and disable tracing to avoid errors.
-
-## Roadmap
-
-Here are the things we are working hard on:
-
-*   **`golf deploy` command for one click deployments to Vercel, Blaxel and other providers**
-*   **Production-ready OAuth token management, to allow for persistent, encrypted token storage and client mapping**
+- **`transport`**: Choose `"sse"`, `"streamable-http"`, or `"stdio"`
+- **`opentelemetry_enabled`**: Auto-enabled with `GOLF_API_KEY`
+- **`detailed_tracing`**: Capture input/output (use carefully with sensitive data)
 
 
 ## Privacy & Telemetry

{golf_mcp-0.1.20 → golf_mcp-0.2.1}/README.md

@@ -28,9 +28,9 @@
 
 ## Overview
 
-Golf is a **framework** designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—*tools*, *prompts*, and *resources*—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable FastMCP server, minimizing boilerplate and accelerating development.
+Golf is a **framework** designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—*tools*, *prompts*, and *resources*—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable MCP server, minimizing boilerplate and accelerating development.
 
-With Golf, you can focus on implementing your agent's logic rather than wrestling with server setup and integration complexities. It's built for developers who want a quick, organized way to build powerful MCP servers.
+With Golf v0.2.0, you get **enterprise-grade authentication** (JWT, OAuth Server, API key, development tokens), **built-in utilities** for LLM interactions, and **automatic telemetry** integration. Focus on implementing your agent's logic while Golf handles authentication, monitoring, and server infrastructure.
 
 ## Quick Start
 
@@ -62,7 +62,7 @@ cd your-project-name
 golf build dev
 golf run
 ```
-This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`).
+This will start the MCP server, typically on `http://localhost:3000` (configurable in `golf.json`).
 
 That's it! Your Golf server is running and ready for integration.
 
@@ -85,10 +85,11 @@ A Golf project initialized with `golf init` will have a structure similar to thi
 │   └─ welcome.py     # Example prompt
 │
 ├─ .env               # Environment variables (e.g., API keys, server port)
-└─ pre_build.py       # (Optional) Script for pre-build hooks (e.g., auth setup)
+└─ auth.py            # Authentication configuration (JWT, OAuth Server, API key, dev tokens)
 ```
 
 -   **`golf.json`**: Configures server name, port, transport, telemetry, and other build settings.
+-   **`auth.py`**: Dedicated authentication configuration file (new in v0.2.0, breaking change from v0.1.x authentication API) for JWT, OAuth Server, API key, or development authentication.
 -   **`tools/`**, **`resources/`**, **`prompts/`**: Contain your Python files, each defining a single component. These directories can also contain nested subdirectories to further organize your components (e.g., `tools/payments/charge.py`). The module docstring of each file serves as the component's description.
     -   Component IDs are automatically derived from their file path. For example, `tools/hello.py` becomes `hello`, and a nested file like `tools/payments/submit.py` would become `submit_payments` (filename, followed by reversed parent directories under the main category, joined by underscores).
 -   **`common.py`** (not shown, but can be placed in subdirectories like `tools/payments/common.py`): Used to share code (clients, models, etc.) among components in the same subdirectory.
@@ -125,118 +126,63 @@ export = hello
 ```
 Golf will automatically discover this file. The module docstring `"""Hello World tool {{project_name}}."""` is used as the tool's description. It infers parameters from the `hello` function's signature and uses the `Output` Pydantic model for the output schema. The tool will be registered with the ID `hello`.
 
-## Configuration (`golf.json`)
+## Authentication & Features
 
-The `golf.json` file is the heart of your Golf project configuration. Here's what each field controls:
+Golf includes enterprise-grade authentication, built-in utilities, and automatic telemetry:
 
-```jsonc
-{
-  "name": "{{project_name}}",          // Your MCP server name (required)
-  "description": "A Golf project",     // Brief description of your server's purpose
-  "host": "127.0.0.1",                // Server host - use "0.0.0.0" to listen on all interfaces
-  "port": 3000,                       // Server port - any available port number
-  "transport": "sse",                 // Communication protocol:
-                                      // - "sse": Server-Sent Events (recommended for web clients)
-                                      // - "streamable-http": HTTP with streaming support
-                                      // - "stdio": Standard I/O (for CLI integration)
-  
-  // HTTP Transport Configuration (optional)
-  "stateless_http": false,            // Make streamable-http transport stateless (new session per request)
-                                      // When true, server restarts won't break existing client connections
-  
-  // Health Check Configuration (optional)
-  "health_check_enabled": false,      // Enable health check endpoint for Kubernetes/load balancers
-  "health_check_path": "/health",     // HTTP path for health check endpoint
-  "health_check_response": "OK",      // Response text returned by health check
-  
-  // OpenTelemetry Configuration (optional)
-  "opentelemetry_enabled": false,     // Enable distributed tracing
-  "opentelemetry_default_exporter": "console"  // Default exporter if OTEL_TRACES_EXPORTER not set
-                                               // Options: "console", "otlp_http"
-}
-```
-
-### Key Configuration Options:
-
-- **`name`**: The identifier for your MCP server. This will be shown to clients connecting to your server.
-- **`transport`**: Choose based on your client needs:
-  - `"sse"` is ideal for web-based clients and real-time communication
-  - `"streamable-http"` provides HTTP streaming for traditional API clients
-  - `"stdio"` enables integration with command-line tools and scripts
-- **`host` & `port`**: Control where your server listens. Use `"127.0.0.1"` for local development or `"0.0.0.0"` to accept external connections.
-- **`stateless_http`**: When true, makes the streamable-http transport stateless by creating a new session for each request. This ensures that server restarts don't break existing client connections, making the server truly stateless.
-- **`health_check_enabled`**: When true, enables a health check endpoint for Kubernetes readiness/liveness probes and load balancers
-- **`health_check_path`**: Customizable path for the health check endpoint (defaults to "/health")
-- **`health_check_response`**: Customizable response text for successful health checks (defaults to "OK")
-- **`opentelemetry_enabled`**: When true, enables distributed tracing for debugging and monitoring your MCP server
-- **`opentelemetry_default_exporter`**: Sets the default trace exporter. Can be overridden by the `OTEL_TRACES_EXPORTER` environment variable
-
-## Features
-
-### 🏥 Health Check Support
-
-Golf includes built-in health check endpoint support for production deployments. When enabled, it automatically adds a custom HTTP route that can be used by:
-- Kubernetes readiness and liveness probes
-- Load balancers and reverse proxies
-- Monitoring systems
-- Container orchestration platforms
-
-#### Configuration
-
-Enable health checks in your `golf.json`:
-```json
-{
-  "health_check_enabled": true,
-  "health_check_path": "/health",
-  "health_check_response": "Service is healthy"
-}
+```python
+# auth.py - Configure authentication
+from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig
+
+# JWT authentication (production)
+configure_auth(JWTAuthConfig(
+    jwks_uri_env_var="JWKS_URI",
+    issuer_env_var="JWT_ISSUER", 
+    audience_env_var="JWT_AUDIENCE",
+    required_scopes=["read", "write"]
+))
+
+# OAuth Server mode (Golf acts as OAuth 2.0 server)
+# configure_auth(OAuthServerConfig(
+#     base_url="https://your-golf-server.com",
+#     valid_scopes=["read", "write", "admin"]
+# ))
+
+# Static tokens (development only)
+# configure_auth(StaticTokenConfig(
+#     tokens={"dev-token": {"client_id": "dev", "scopes": ["read"]}}
+# ))
+
+# Built-in utilities available in all tools
+from golf.utils import elicit, sample, get_context
 ```
 
-The generated server will include a route like:
-```python
-@mcp.custom_route('/health', methods=["GET"])
-async def health_check(request: Request) -> PlainTextResponse:
-    """Health check endpoint for Kubernetes and load balancers."""
-    return PlainTextResponse("Service is healthy")
+```bash
+# Automatic telemetry with Golf Platform
+export GOLF_API_KEY="your-key"
+golf run  # ✅ Telemetry enabled automatically
 ```
 
-### 🔍 OpenTelemetry Support
+**[📚 Complete Documentation →](https://docs.golf.dev)**
 
-Golf includes built-in OpenTelemetry instrumentation for distributed tracing. When enabled, it automatically traces:
-- Tool executions with arguments and results
-- Resource reads and template expansions
-- Prompt generations
-- HTTP requests and sessions
+## Configuration
 
-#### Configuration
+Basic configuration in `golf.json`:
 
-Enable OpenTelemetry in your `golf.json`:
 ```json
 {
-  "opentelemetry_enabled": true,
-  "opentelemetry_default_exporter": "otlp_http"
+  "name": "My Golf Server",
+  "host": "localhost",
+  "port": 3000,
+  "transport": "sse",
+  "opentelemetry_enabled": false,
+  "detailed_tracing": false
 }
 ```
 
-Then configure via environment variables:
-```bash
-# For OTLP HTTP exporter (e.g., Jaeger, Grafana Tempo)
-OTEL_TRACES_EXPORTER=otlp_http
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
-OTEL_SERVICE_NAME=my-golf-server  # Optional, defaults to project name
-
-# For console exporter (debugging)
-OTEL_TRACES_EXPORTER=console
-```
-
-**Note**: When using the OTLP HTTP exporter, you must set `OTEL_EXPORTER_OTLP_ENDPOINT`. If not configured, Golf will display a warning and disable tracing to avoid errors.
-
-## Roadmap
-
-Here are the things we are working hard on:
-
-*   **`golf deploy` command for one click deployments to Vercel, Blaxel and other providers**
-*   **Production-ready OAuth token management, to allow for persistent, encrypted token storage and client mapping**
+- **`transport`**: Choose `"sse"`, `"streamable-http"`, or `"stdio"`
+- **`opentelemetry_enabled`**: Auto-enabled with `GOLF_API_KEY`
+- **`detailed_tracing`**: Capture input/output (use carefully with sensitive data)
 
 
 ## Privacy & Telemetry

{golf_mcp-0.1.20 → golf_mcp-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "golf-mcp"
-version = "0.1.20"
+version = "0.2.1"
 description = "Framework for building MCP servers"
 authors = [
     {name = "Antoni Gmitruk", email = "antoni@golf.dev"}
@@ -28,8 +28,9 @@ classifiers = [
 dependencies = [
     "typer>=0.15.4",
     "rich>=14.0.0",
-    "fastmcp>=2.0.0,<2.6.0",
+    "fastmcp>=2.11.0,<3.0.0",
     "pydantic>=2.11.0",
+    "pydantic-settings>=2.0.0",
     "python-dotenv>=1.1.0",
     "black>=24.10.0",
     "pyjwt>=2.0.0",
@@ -65,7 +66,7 @@ golf = ["examples/**/*"]
 
 [tool.poetry]
 name = "golf-mcp"
-version = "0.1.20"
+version = "0.2.1"
 description = "Framework for building MCP servers with zero boilerplate"
 authors = ["Antoni Gmitruk <antoni@golf.dev>"]
 license = "Apache-2.0"
@@ -87,9 +88,10 @@ classifiers = [
 
 [tool.poetry.dependencies]
 python = ">=3.8" # Match requires-python
-fastmcp = ">=2.0.0,<2.6.0"
+fastmcp = ">=2.11.0,<3.0.0"
 typer = {extras = ["all"], version = ">=0.15.4"}
 pydantic = ">=2.11.0"
+pydantic-settings = ">=2.0.0"
 rich = ">=14.0.0"
 python-dotenv = ">=1.1.0"
 black = ">=24.10.0"
@@ -114,15 +116,18 @@ mypy = "^1.6.0"
 pytest-cov = "^4.1.0"
 
 [tool.black]
-line-length = 88
+line-length = 120
 
 [tool.ruff]
-line-length = 88
+line-length = 120
 target-version = "py311"
 
 [tool.ruff.lint]
 select = ["E", "F", "B", "C4", "C90", "UP", "N", "ANN", "SIM", "TID"]
-ignore = ["ANN401"]
+ignore = [
+    "ANN401",  # Disallow Any (too strict for dynamic code)
+    "B008",    # Function call in defaults (common in CLI frameworks like Typer)
+]
 
 [tool.ruff.format]
 # Use Black-compatible formatting
@@ -150,6 +155,7 @@ python_files = ["test_*.py", "*_test.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
 asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
 addopts = [
     "-v",
     "--strict-markers",

golf_mcp-0.2.1/setup.py

@@ -0,0 +1,87 @@
+"""Custom setup.py for golf-mcp with URL injection."""
+
+from setuptools import setup
+from setuptools.command.build_py import build_py as _build_py
+from setuptools.command.develop import develop as _develop
+import os
+import pathlib
+import sys
+
+TEMPLATE_REL = "src/golf/_endpoints.py.in"
+PACKAGE_OUT_REL = "golf/_endpoints.py"
+
+
+def render_endpoints(require_env_vars: bool = True):
+    """Render the endpoints template with environment variables."""
+    tpl_path = pathlib.Path(TEMPLATE_REL)
+    if not tpl_path.exists():
+        raise FileNotFoundError(f"Template not found: {tpl_path}")
+
+    # Get environment variables
+    platform_url = os.environ.get("GOLF_PLATFORM_API_URL")
+    otel_url = os.environ.get("GOLF_OTEL_ENDPOINT")
+
+    # For production builds, require environment variables
+    # For development/editable installs, use fallback values
+    if require_env_vars and (not platform_url or not otel_url):
+        raise SystemExit(
+            "Missing required environment variables for URL injection:\n"
+            "  GOLF_PLATFORM_API_URL\n"
+            "  GOLF_OTEL_ENDPOINT\n"
+            "Set these before building the package."
+        )
+
+    # Use environment variables if available, otherwise fallback to development URLs
+    values = {
+        "PLATFORM_API_URL": platform_url or "http://localhost:8000/api/resources",
+        "OTEL_ENDPOINT": otel_url or "http://localhost:4318/v1/traces",
+    }
+
+    try:
+        rendered = tpl_path.read_text(encoding="utf-8").format(**values)
+    except KeyError as e:
+        raise SystemExit(f"Missing template key: {e}") from e
+
+    return rendered
+
+
+class build_py(_build_py):
+    """Custom build_py that renders endpoints into the build_lib (wheel contents)."""
+
+    def run(self):
+        # First run the normal build
+        super().run()
+
+        # Then render endpoints into the build_lib
+        # Skip env var requirement if in CI environment or if this looks like a test install
+        is_ci = os.environ.get("CI") or os.environ.get("GITHUB_ACTIONS")
+        rendered = render_endpoints(require_env_vars=not is_ci)
+        out_file = pathlib.Path(self.build_lib) / PACKAGE_OUT_REL
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+        out_file.write_text(rendered, encoding="utf-8")
+        print(f"Generated {PACKAGE_OUT_REL} with injected URLs", file=sys.stderr)
+
+
+class develop(_develop):
+    """Custom develop for editable installs - generates endpoints file in source tree."""
+
+    def run(self):
+        # Run normal develop command first
+        super().run()
+
+        # Generate a working copy file for editable installs (use fallback URLs if env vars missing)
+        rendered = render_endpoints(require_env_vars=False)
+        # For editable installs, write into the source tree so imports work
+        src_file = pathlib.Path("src") / PACKAGE_OUT_REL
+        src_file.parent.mkdir(parents=True, exist_ok=True)
+        src_file.write_text(rendered, encoding="utf-8")
+        print(f"Generated dev-time {PACKAGE_OUT_REL} in source tree", file=sys.stderr)
+        print(f"Note: {src_file} is gitignored and should not be committed", file=sys.stderr)
+
+
+setup(
+    cmdclass={
+        "build_py": build_py,
+        "develop": develop,
+    }
+)

golf_mcp-0.2.1/src/golf/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "0.2.1"
+
+# Import endpoints with fallback for dev mode
+try:
+    # In built wheels, this exists (generated from _endpoints.py.in)
+    from . import _endpoints
+except ImportError:
+    # In editable/dev installs, fall back to env-based values
+    from . import _endpoints_fallback as _endpoints

golf_mcp-0.2.1/src/golf/_endpoints_fallback.py

@@ -0,0 +1,10 @@
+"""Fallback endpoints for development/editable installs."""
+
+import os
+
+# These are used when the generated _endpoints.py doesn't exist (dev mode)
+# or when environment variables override the built-in values
+
+PLATFORM_API_URL = os.getenv("GOLF_PLATFORM_API_URL", "http://localhost:8000/api/resources")
+
+OTEL_ENDPOINT = os.getenv("GOLF_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")