golf-mcp 0.1.20__py3-none-any.whl → 0.2.0__py3-none-any.whl

golf/utilities/__init__.py

@@ -0,0 +1,12 @@
+"""Golf utilities for enhanced MCP tool development.
+
+This module provides convenient utilities for Golf tool authors to access
+advanced MCP features like elicitation and sampling without needing to
+manage FastMCP Context objects directly.
+"""
+
+from .elicitation import elicit, elicit_confirmation
+from .sampling import sample, sample_structured, sample_with_context
+from .context import get_current_context
+
+__all__ = ["elicit", "elicit_confirmation", "sample", "sample_structured", "sample_with_context", "get_current_context"]

golf/utilities/context.py

@@ -0,0 +1,53 @@
+"""Context utilities for Golf MCP tools.
+
+This module provides utilities to access the current FastMCP Context
+from within Golf tool functions.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastmcp.server.context import Context
+
+
+def get_current_context() -> "Context":
+    """Get the current FastMCP Context.
+
+    This function retrieves the current FastMCP Context that was injected
+    into the tool function. It works by importing the FastMCP context
+    utilities at runtime.
+
+    Returns:
+        The current FastMCP Context instance
+
+    Raises:
+        RuntimeError: If called outside of an MCP request context
+        ImportError: If FastMCP is not available
+
+    Example:
+        ```python
+        from golf.utilities import get_current_context
+
+        async def my_tool(data: str):
+            ctx = get_current_context()
+            await ctx.info(f"Processing: {data}")
+            return "done"
+        ```
+    """
+    try:
+        # Import FastMCP context utilities at runtime
+        from fastmcp.server.context import _current_context
+
+        # Get the current context from the context variable
+        context = _current_context.get(None)
+
+        if context is None:
+            raise RuntimeError(
+                "No FastMCP Context available. This function must be called "
+                "from within an MCP tool function that has context injection enabled."
+            )
+
+        return context
+
+    except ImportError as e:
+        raise ImportError("FastMCP is not available. Please ensure fastmcp>=2.11.0 is installed.") from e

golf/utilities/elicitation.py

@@ -0,0 +1,170 @@
+"""Elicitation utilities for Golf MCP tools.
+
+This module provides simplified elicitation functions that Golf tool authors
+can use without needing to manage FastMCP Context objects directly.
+"""
+
+from typing import Any, TypeVar, overload
+from collections.abc import Callable
+
+from .context import get_current_context
+
+T = TypeVar("T")
+
+# Apply telemetry instrumentation if available
+try:
+    from golf.telemetry import instrument_elicitation
+
+    _instrumentation_available = True
+except ImportError:
+    _instrumentation_available = False
+
+    def instrument_elicitation(func: Callable, elicitation_type: str = "elicit") -> Callable:
+        """No-op instrumentation when telemetry is not available."""
+        return func
+
+
+@overload
+async def elicit(
+    message: str,
+    response_type: None = None,
+) -> dict[str, Any]:
+    """Elicit with no response type returns empty dict."""
+    ...
+
+
+@overload
+async def elicit(
+    message: str,
+    response_type: type[T],
+) -> T:
+    """Elicit with response type returns typed data."""
+    ...
+
+
+@overload
+async def elicit(
+    message: str,
+    response_type: list[str],
+) -> str:
+    """Elicit with list of options returns selected string."""
+    ...
+
+
+async def elicit(
+    message: str,
+    response_type: type[T] | list[str] | None = None,
+) -> T | dict[str, Any] | str:
+    """Request additional information from the user via MCP elicitation.
+
+    This is a simplified wrapper around FastMCP's Context.elicit() method
+    that automatically handles context retrieval and response processing.
+
+    Args:
+        message: Human-readable message explaining what information is needed
+        response_type: The type of response expected:
+            - None: Returns empty dict (for confirmation prompts)
+            - type[T]: Returns validated instance of T (BaseModel, dataclass, etc.)
+            - list[str]: Returns selected string from the options
+
+    Returns:
+        The user's response in the requested format
+
+    Raises:
+        RuntimeError: If called outside MCP context or user declines/cancels
+        ValueError: If response validation fails
+
+    Examples:
+        ```python
+        from golf.utilities import elicit
+        from pydantic import BaseModel
+
+        class UserInfo(BaseModel):
+            name: str
+            email: str
+
+        async def collect_user_info():
+            # Structured elicitation
+            info = await elicit("Please provide your details:", UserInfo)
+
+            # Simple text elicitation
+            reason = await elicit("Why do you need this?", str)
+
+            # Multiple choice elicitation
+            priority = await elicit("Select priority:", ["low", "medium", "high"])
+
+            # Confirmation elicitation
+            await elicit("Proceed with the action?")
+
+            return f"User {info.name} requested {reason} with {priority} priority"
+        ```
+    """
+    try:
+        # Get the current FastMCP context
+        ctx = get_current_context()
+
+        # Call the context's elicit method
+        result = await ctx.elicit(message, response_type)
+
+        # Handle the response based on the action
+        if hasattr(result, "action"):
+            if result.action == "accept":
+                return result.data
+            elif result.action == "decline":
+                raise RuntimeError(f"User declined the elicitation request: {message}")
+            elif result.action == "cancel":
+                raise RuntimeError(f"User cancelled the elicitation request: {message}")
+            else:
+                raise RuntimeError(f"Unexpected elicitation response: {result.action}")
+        else:
+            # Direct response (shouldn't happen with current FastMCP)
+            return result
+
+    except Exception as e:
+        if isinstance(e, RuntimeError):
+            raise  # Re-raise our custom errors
+        raise RuntimeError(f"Elicitation failed: {str(e)}") from e
+
+
+async def elicit_confirmation(message: str) -> bool:
+    """Request a simple yes/no confirmation from the user.
+
+    This is a convenience function for common confirmation prompts.
+
+    Args:
+        message: The confirmation message to show the user
+
+    Returns:
+        True if user confirmed, False if declined
+
+    Raises:
+        RuntimeError: If user cancels or other error occurs
+
+    Example:
+        ```python
+        from golf.utilities import elicit_confirmation
+
+        async def delete_file(filename: str):
+            confirmed = await elicit_confirmation(
+                f"Are you sure you want to delete {filename}?"
+            )
+            if confirmed:
+                # Proceed with deletion
+                return f"Deleted {filename}"
+            else:
+                return "Deletion cancelled"
+        ```
+    """
+    try:
+        # Use elicitation with boolean choice
+        choice = await elicit(message, ["yes", "no"])
+        return choice.lower() == "yes"
+    except RuntimeError as e:
+        if "declined" in str(e):
+            return False
+        raise  # Re-raise cancellation or other errors
+
+
+# Apply instrumentation to all elicitation functions
+elicit = instrument_elicitation(elicit, "elicit")
+elicit_confirmation = instrument_elicitation(elicit_confirmation, "confirmation")

golf/utilities/sampling.py

@@ -0,0 +1,221 @@
+"""Sampling utilities for Golf MCP tools.
+
+This module provides simplified LLM sampling functions that Golf tool authors
+can use without needing to manage FastMCP Context objects directly.
+"""
+
+from typing import Any
+from collections.abc import Callable
+
+from .context import get_current_context
+
+# Apply telemetry instrumentation if available
+try:
+    from golf.telemetry import instrument_sampling
+
+    _instrumentation_available = True
+except ImportError:
+    _instrumentation_available = False
+
+    def instrument_sampling(func: Callable, sampling_type: str = "sample") -> Callable:
+        """No-op instrumentation when telemetry is not available."""
+        return func
+
+
+async def sample(
+    messages: str | list[str],
+    system_prompt: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    model_preferences: str | list[str] | None = None,
+) -> str:
+    """Request an LLM completion from the MCP client.
+
+    This is a simplified wrapper around FastMCP's Context.sample() method
+    that automatically handles context retrieval and response processing.
+
+    Args:
+        messages: The message(s) to send to the LLM:
+            - str: Single user message
+            - list[str]: Multiple user messages
+        system_prompt: Optional system prompt to guide the LLM
+        temperature: Optional temperature for sampling (0.0 to 1.0)
+        max_tokens: Optional maximum tokens to generate (default: 512)
+        model_preferences: Optional model preferences:
+            - str: Single model name hint
+            - list[str]: Multiple model name hints in preference order
+
+    Returns:
+        The LLM's response as a string
+
+    Raises:
+        RuntimeError: If called outside MCP context or sampling fails
+        ValueError: If parameters are invalid
+
+    Examples:
+        ```python
+        from golf.utilities import sample
+
+        async def analyze_data(data: str):
+            # Simple completion
+            analysis = await sample(f"Analyze this data: {data}")
+
+            # With system prompt and temperature
+            creative_response = await sample(
+                "Write a creative story about this data",
+                system_prompt="You are a creative writer",
+                temperature=0.8,
+                max_tokens=1000
+            )
+
+            # With model preferences
+            technical_analysis = await sample(
+                f"Provide technical analysis: {data}",
+                model_preferences=["gpt-4", "claude-3-sonnet"]
+            )
+
+            return {
+                "analysis": analysis,
+                "creative": creative_response,
+                "technical": technical_analysis
+            }
+        ```
+    """
+    try:
+        # Get the current FastMCP context
+        ctx = get_current_context()
+
+        # Call the context's sample method
+        result = await ctx.sample(
+            messages=messages,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            model_preferences=model_preferences,
+        )
+
+        # Extract text content from the ContentBlock response
+        if hasattr(result, "text"):
+            return result.text
+        elif hasattr(result, "content"):
+            # Handle different content block types
+            if isinstance(result.content, str):
+                return result.content
+            elif hasattr(result.content, "text"):
+                return result.content.text
+            else:
+                return str(result.content)
+        else:
+            return str(result)
+
+    except Exception as e:
+        raise RuntimeError(f"LLM sampling failed: {str(e)}") from e
+
+
+async def sample_structured(
+    messages: str | list[str],
+    format_instructions: str,
+    system_prompt: str | None = None,
+    temperature: float = 0.1,
+    max_tokens: int | None = None,
+) -> str:
+    """Request a structured LLM completion with specific formatting.
+
+    This is a convenience function for requesting structured responses
+    like JSON, XML, or other formatted output.
+
+    Args:
+        messages: The message(s) to send to the LLM
+        format_instructions: Instructions for the desired output format
+        system_prompt: Optional system prompt
+        temperature: Temperature for sampling (default: 0.1 for consistency)
+        max_tokens: Optional maximum tokens to generate
+
+    Returns:
+        The structured LLM response as a string
+
+    Example:
+        ```python
+        from golf.utilities import sample_structured
+
+        async def extract_entities(text: str):
+            entities = await sample_structured(
+                f"Extract entities from: {text}",
+                format_instructions="Return as JSON with keys: persons, "
+                "organizations, locations",
+                system_prompt="You are an expert at named entity recognition"
+            )
+            return entities
+        ```
+    """
+    # Combine the format instructions with the messages
+    if isinstance(messages, str):
+        formatted_message = f"{messages}\n\n{format_instructions}"
+    else:
+        formatted_message = messages + [format_instructions]
+
+    return await sample(
+        messages=formatted_message,
+        system_prompt=system_prompt,
+        temperature=temperature,
+        max_tokens=max_tokens,
+    )
+
+
+async def sample_with_context(
+    messages: str | list[str],
+    context_data: dict[str, Any],
+    system_prompt: str | None = None,
+    **kwargs: Any,
+) -> str:
+    """Request an LLM completion with additional context data.
+
+    This convenience function formats context data and includes it
+    in the sampling request.
+
+    Args:
+        messages: The message(s) to send to the LLM
+        context_data: Dictionary of context data to include
+        system_prompt: Optional system prompt
+        **kwargs: Additional arguments passed to sample()
+
+    Returns:
+        The LLM response as a string
+
+    Example:
+        ```python
+        from golf.utilities import sample_with_context
+
+        async def generate_report(topic: str, user_data: dict):
+            report = await sample_with_context(
+                f"Generate a report about {topic}",
+                context_data={
+                    "user_preferences": user_data,
+                    "timestamp": "2024-01-01",
+                    "format": "markdown"
+                },
+                system_prompt="You are a professional report writer"
+            )
+            return report
+        ```
+    """
+    # Format context data as a readable string
+    context_str = "\n".join([f"{k}: {v}" for k, v in context_data.items()])
+
+    # Add context to the message
+    if isinstance(messages, str):
+        contextual_message = f"{messages}\n\nContext:\n{context_str}"
+    else:
+        contextual_message = messages + [f"Context:\n{context_str}"]
+
+    return await sample(
+        messages=contextual_message,
+        system_prompt=system_prompt,
+        **kwargs,
+    )
+
+
+# Apply instrumentation to all sampling functions
+sample = instrument_sampling(sample, "sample")
+sample_structured = instrument_sampling(sample_structured, "structured")
+sample_with_context = instrument_sampling(sample_with_context, "context")

{golf_mcp-0.1.20.dist-info → golf_mcp-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: golf-mcp
-Version: 0.1.20
+Version: 0.2.0
 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