golf-mcp 0.2.16__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")