golf-mcp 0.2.16__py3-none-any.whl

golf/core/transformer.py

@@ -0,0 +1,231 @@
+"""Transform GolfMCP components into standalone FastMCP code.
+
+This module provides utilities for transforming GolfMCP's convention-based code
+into explicit FastMCP component registrations.
+"""
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from golf.core.parser import ParsedComponent
+
+
+class ImportTransformer(ast.NodeTransformer):
+    """AST transformer for rewriting imports in component files."""
+
+    def __init__(
+        self,
+        original_path: Path,
+        target_path: Path,
+        import_map: dict[str, str],
+        project_root: Path,
+        root_file_modules: set[str] | None = None,
+    ) -> None:
+        """Initialize the import transformer.
+
+        Args:
+            original_path: Path to the original file
+            target_path: Path to the target file
+            import_map: Mapping of original module paths to generated paths
+            project_root: Root path of the project
+            root_file_modules: Set of root file module names (without .py extension)
+        """
+        self.original_path = original_path
+        self.target_path = target_path
+        self.import_map = import_map
+        self.project_root = project_root
+        self.root_file_modules = root_file_modules or set()
+
+    def _calculate_import_depth(self) -> int:
+        """Calculate the relative import depth needed to reach build root from component location."""
+        try:
+            # Get component path relative to project root
+            relative_path = self.target_path.relative_to(self.project_root)
+
+            # Count directory levels: components/tools/weather.py = 2 levels, needs level=2
+            # components/tools/api/handler.py = 3 levels, needs level=3
+            # Build root contains the root files, so depth = number of path parts
+            return len(relative_path.parts) - 1  # Subtract 1 for the filename itself
+
+        except ValueError:
+            # Fallback to level=3 if path calculation fails
+            return 3
+
+    def visit_Import(self, node: ast.Import) -> Any:
+        """Transform import statements."""
+        new_names = []
+
+        for alias in node.names:
+            module_name = alias.name
+
+            if module_name in self.root_file_modules:
+                # Keep original import unchanged - sys.path will handle resolution
+                new_names.append(alias)
+                continue
+            else:
+                new_names.append(alias)
+
+        # If no root modules, return original or modified import
+        if new_names != list(node.names):
+            return ast.Import(names=new_names)
+        return node
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> Any:
+        """Transform import from statements."""
+        if node.module is None:
+            return node
+
+        # Check if this is importing from a root file module
+        if node.level == 0 and node.module in self.root_file_modules:
+            # Keep unchanged - sys.path will handle resolution
+            return node
+
+        # Handle relative imports
+        if node.level > 0:
+            # Calculate the source module path
+            source_dir = self.original_path.parent
+            for _ in range(node.level - 1):
+                source_dir = source_dir.parent
+
+            if node.module:
+                # Handle imports like `from .helpers import utils`
+                source_module = source_dir / node.module.replace(".", "/")
+            else:
+                # Handle imports like `from . import something`
+                source_module = source_dir
+
+            try:
+                # Check if this is a shared module import
+                source_str = str(source_module.relative_to(self.project_root))
+
+                # First, try direct module path match (e.g., "tools/weather/helpers")
+                if source_str in self.import_map:
+                    new_module = self.import_map[source_str]
+                    return ast.ImportFrom(module=new_module, names=node.names, level=0)
+
+                # If direct match fails, try directory-based matching
+                # This handles cases like `from . import common` where the import_map
+                # has "tools/weather/common" but we're looking for "tools/weather"
+                source_dir_str = str(source_dir.relative_to(self.project_root))
+                if source_dir_str in self.import_map:
+                    new_module = self.import_map[source_dir_str]
+                    if node.module:
+                        new_module = f"{new_module}.{node.module}"
+                    return ast.ImportFrom(module=new_module, names=node.names, level=0)
+
+                # Check for specific module imports within the directory
+                for import_path, mapped_path in self.import_map.items():
+                    # Handle cases where we import a specific module from a directory
+                    # e.g., `from .common import something` should match "tools/weather/common"
+                    if import_path.startswith(source_dir_str + "/") and node.module:
+                        module_name = import_path.replace(source_dir_str + "/", "")
+                        if module_name == node.module:
+                            return ast.ImportFrom(module=mapped_path, names=node.names, level=0)
+
+            except ValueError:
+                # source_module is not relative to project_root, leave import unchanged
+                pass
+
+        return node
+
+
+def transform_component(
+    component: ParsedComponent | None,
+    output_file: Path,
+    project_path: Path,
+    import_map: dict[str, str],
+    source_file: Path | None = None,
+    root_file_modules: set[str] | None = None,
+) -> str:
+    """Transform a GolfMCP component into a standalone FastMCP component.
+
+    Args:
+        component: Parsed component to transform (optional if source_file provided)
+        output_file: Path to write the transformed component to
+        project_path: Path to the project root
+        import_map: Mapping of original module paths to generated paths
+        source_file: Optional path to source file (for shared files)
+        root_file_modules: Set of root file module names (without .py extension)
+
+    Returns:
+        Generated component code
+    """
+    # Read the original file
+    if source_file is not None:
+        file_path = source_file
+    elif component is not None:
+        file_path = Path(component.file_path)
+    else:
+        raise ValueError("Either component or source_file must be provided")
+
+    with open(file_path) as f:
+        source_code = f.read()
+
+    # Parse the source code into an AST
+    tree = ast.parse(source_code)
+
+    # Transform imports
+    transformer = ImportTransformer(file_path, output_file, import_map, project_path, root_file_modules)
+    tree = transformer.visit(tree)
+
+    # Get all imports and docstring
+    imports = []
+    docstring = None
+
+    # Find the module docstring if present
+    if (
+        len(tree.body) > 0
+        and isinstance(tree.body[0], ast.Expr)
+        and isinstance(tree.body[0].value, ast.Constant)
+        and isinstance(tree.body[0].value.value, str)
+    ):
+        docstring = tree.body[0].value.value
+
+    # Find imports
+    for node in tree.body:
+        if isinstance(node, ast.Import | ast.ImportFrom):
+            imports.append(node)
+
+    # Build full transformed code - start with docstring first (Python convention)
+    transformed_code = ""
+
+    # Add docstring first if present, using proper triple quotes for multi-line docstrings
+    if docstring:
+        # Check if docstring contains newlines
+        if "\n" in docstring:
+            # Use triple quotes for multi-line docstrings
+            transformed_code += f'"""{docstring}"""\n\n'
+        else:
+            # Use single quotes for single-line docstrings
+            transformed_code += f'"{docstring}"\n\n'
+
+    # Add transformed imports after docstring
+    if imports:
+        transformed_imports = ast.unparse(ast.Module(body=imports, type_ignores=[]))
+        transformed_code += transformed_imports + "\n\n"
+
+    # Add the rest of the code except imports and the original docstring
+    remaining_nodes = []
+    for node in tree.body:
+        # Skip imports
+        if isinstance(node, ast.Import | ast.ImportFrom):
+            continue
+
+        # Skip the original docstring
+        if isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant) and isinstance(node.value.value, str):
+            continue
+
+        remaining_nodes.append(node)
+
+    remaining_code = ast.unparse(ast.Module(body=remaining_nodes, type_ignores=[]))
+    transformed_code += remaining_code
+
+    # Ensure the directory exists
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write the transformed code to the output file
+    with open(output_file, "w") as f:
+        f.write(transformed_code)
+
+    return transformed_code

golf/examples/basic/.env.example

@@ -0,0 +1,4 @@
+# Golf MCP Server Environment Variables
+
+# Development tokens are configured in auth.py for this example
+# Additional environment variables can be added as needed

golf/examples/basic/README.md

@@ -0,0 +1,133 @@
+# Golf MCP Project Template (Basic)
+
+This is a basic template for creating MCP servers with Golf. It includes development authentication for easy testing. Use `golf init <project-name>` to bootstrap new projects from this template.
+
+## About Golf
+
+Golf is a Python framework for building MCP (Model Context Protocol) servers with minimal boilerplate. Define your server's capabilities as simple Python files, and Golf automatically discovers and compiles them into a runnable FastMCP server.
+
+## Getting Started
+
+After initializing your project:
+
+1. **Navigate to your project directory:**
+   ```bash
+   cd your-project-name
+   ```
+
+2. **Configure authentication (optional):**
+   This template includes development authentication in `auth.py` with sample tokens. Edit the file to set up JWT, OAuth, or API key authentication for production use.
+
+3. **Build and run your server:**
+   ```bash
+   golf build dev    # Development build
+   golf run          # Start the server
+   ```
+
+## Project Structure
+
+```
+your-project/
+├── tools/           # Tool implementations (functions LLMs can call)
+├── resources/       # Resource implementations (data LLMs can read)  
+├── prompts/         # Prompt templates (conversation structures)
+├── golf.json        # Server configuration
+└── auth.py          # Authentication setup
+```
+
+## Adding Components
+
+### Tools
+Create `.py` files in `tools/` directory. Each file should export a single async function:
+
+```python
+# tools/calculator.py
+async def add(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+export = add
+```
+
+### Resources  
+Create `.py` files in `resources/` directory with a `resource_uri` and export function:
+
+```python
+# resources/status.py
+resource_uri = "status://server"
+
+async def status() -> dict:
+    """Get server status information."""
+    return {"status": "running", "timestamp": "2024-01-01T00:00:00Z"}
+
+export = status
+```
+
+### Prompts
+Create `.py` files in `prompts/` directory that return message lists:
+
+```python
+# prompts/assistant.py
+async def assistant() -> list[dict]:
+    """System prompt for a helpful assistant."""
+    return [
+        {
+            "role": "system", 
+            "content": "You are a helpful assistant for {{project_name}}."
+        }
+    ]
+
+export = assistant
+```
+
+## Authentication Examples
+
+### No Authentication (Default)
+Leave `auth.py` empty or remove it entirely.
+
+### API Key Authentication
+```python
+# auth.py
+from golf.auth import configure_api_key
+
+configure_api_key(
+    header_name="Authorization",
+    header_prefix="Bearer ",
+    required=True
+)
+```
+
+### JWT Authentication  
+```python
+# auth.py
+from golf.auth import configure_jwt_auth
+
+configure_jwt_auth(
+    jwks_uri="https://your-domain.auth0.com/.well-known/jwks.json",
+    issuer="https://your-domain.auth0.com/",
+    audience="https://your-api.example.com"
+)
+```
+
+### Development Tokens
+```python
+# auth.py  
+from golf.auth import configure_dev_auth
+
+configure_dev_auth(
+    tokens={
+        "dev-token-123": {
+            "client_id": "dev-client",
+            "scopes": ["read", "write"]
+        }
+    }
+)
+```
+
+## Documentation
+
+For comprehensive documentation, visit: [https://docs.golf.dev](https://docs.golf.dev)
+
+---
+
+Happy building! 🏌️‍♂️

golf/examples/basic/auth.py

@@ -0,0 +1,76 @@
+"""Authentication configuration for the basic Golf MCP server example.
+
+This example shows different authentication options available in Golf 0.2.x:
+- JWT authentication with static keys or JWKS endpoints (production)
+- Static token authentication (development/testing)
+- OAuth Server mode (full OAuth 2.0 server)
+- Remote Authorization Server integration
+"""
+
+# Example 1: JWT authentication with a static public key
+# from golf.auth import configure_auth, JWTAuthConfig
+#
+# configure_auth(
+#     JWTAuthConfig(
+#         public_key_env_var="JWT_PUBLIC_KEY",  # PEM-encoded public key
+#         issuer="https://your-auth-server.com",
+#         audience="https://your-golf-server.com",
+#         required_scopes=["read:data"],
+#     )
+# )
+
+# Example 2: JWT authentication with JWKS (recommended for production)
+# from golf.auth import configure_auth, JWTAuthConfig
+#
+# configure_auth(
+#     JWTAuthConfig(
+#         jwks_uri_env_var="JWKS_URI",        # e.g., "https://your-domain.auth0.com/.well-known/jwks.json"
+#         issuer_env_var="JWT_ISSUER",        # e.g., "https://your-domain.auth0.com/"
+#         audience_env_var="JWT_AUDIENCE",    # e.g., "https://your-api.example.com"
+#         required_scopes=["read:user"],
+#     )
+# )
+
+# Example 3: OAuth Server mode - Golf acts as full OAuth 2.0 authorization server
+# from golf.auth import configure_auth, OAuthServerConfig
+#
+# configure_auth(
+#     OAuthServerConfig(
+#         base_url_env_var="OAUTH_BASE_URL",          # e.g., "https://auth.example.com"
+#         valid_scopes=["read", "write", "admin"],    # Scopes clients can request
+#         default_scopes=["read"],                    # Default scopes for new clients
+#         required_scopes=["read"],                   # Scopes required for all requests
+#     )
+# )
+
+# Example 4: Remote Authorization Server integration
+# from golf.auth import configure_auth, RemoteAuthConfig, JWTAuthConfig
+#
+# configure_auth(
+#     RemoteAuthConfig(
+#         authorization_servers_env_var="AUTH_SERVERS",    # Comma-separated: "https://auth1.com,https://auth2.com"
+#         resource_server_url_env_var="RESOURCE_URL",     # This server's URL
+#         token_verifier_config=JWTAuthConfig(
+#             jwks_uri_env_var="JWKS_URI"
+#         ),
+#     )
+# )
+
+# Example 5: Static token authentication for development (NOT for production)
+from golf.auth import configure_auth, StaticTokenConfig
+
+configure_auth(
+    StaticTokenConfig(
+        tokens={
+            "dev-token-123": {
+                "client_id": "dev-client",
+                "scopes": ["read", "write"],
+            },
+            "admin-token-456": {
+                "client_id": "admin-client",
+                "scopes": ["read", "write", "admin"],
+            },
+        },
+        required_scopes=["read"],
+    )
+)

golf/examples/basic/golf.json

@@ -0,0 +1,5 @@
+{
+  "name": "basic-server-example",
+  "description": "A GolfMCP project",
+  "transport": "http"
+} 

golf/examples/basic/prompts/welcome.py

@@ -0,0 +1,27 @@
+"""Welcome prompt for new users."""
+
+
+async def welcome() -> list[dict]:
+    """Provide a welcome prompt for new users.
+
+    This is a simple example prompt that demonstrates how to define
+    a prompt template in GolfMCP.
+    """
+    return [
+        {
+            "role": "system",
+            "content": (
+                "You are an assistant for the {{project_name}} application. "
+                "You help users understand how to interact with this system and "
+                "its capabilities."
+            ),
+        },
+        {
+            "role": "user",
+            "content": ("Welcome to {{project_name}}! This is a project built with GolfMCP. How can I get started?"),
+        },
+    ]
+
+
+# Designate the entry point function
+export = welcome

golf/examples/basic/resources/current_time.py

@@ -0,0 +1,34 @@
+"""Current time resource example."""
+
+from datetime import datetime
+from typing import Any
+
+# The URI that clients will use to access this resource
+resource_uri = "system://time"
+
+
+async def current_time() -> dict[str, Any]:
+    """Provide the current time in various formats.
+
+    This is a simple resource example that returns time in all formats.
+    """
+    now = datetime.now()
+
+    # Prepare all possible formats
+    all_formats = {
+        "iso": now.isoformat(),
+        "rfc": now.strftime("%a, %d %b %Y %H:%M:%S %z"),
+        "unix": int(now.timestamp()),
+        "formatted": {
+            "date": now.strftime("%Y-%m-%d"),
+            "time": now.strftime("%H:%M:%S"),
+            "timezone": now.astimezone().tzname(),
+        },
+    }
+
+    # Return all formats
+    return all_formats
+
+
+# Designate the entry point function
+export = current_time

golf/examples/basic/resources/info.py

@@ -0,0 +1,28 @@
+"""Example resource that provides information about the project."""
+
+import platform
+from datetime import datetime
+from typing import Any
+
+resource_uri = "info://system"
+
+
+async def info() -> dict[str, Any]:
+    """Provide system information as a resource.
+
+    This is a simple example resource that demonstrates how to expose
+    data to an LLM client through the MCP protocol.
+    """
+    return {
+        "project": "{{project_name}}",
+        "timestamp": datetime.now().isoformat(),
+        "platform": {
+            "system": platform.system(),
+            "python_version": platform.python_version(),
+            "architecture": platform.machine(),
+        },
+    }
+
+
+# Designate the entry point function
+export = info

golf/examples/basic/resources/weather/city.py

@@ -0,0 +1,46 @@
+"""Weather resource template example with URI parameters."""
+
+from datetime import datetime
+from typing import Any
+
+from .client import weather_client
+
+# The URI template that clients will use to access this resource
+# The {city} parameter makes this a resource template
+resource_uri = "weather://city/{city}"
+
+
+async def get_weather_for_city(city: str) -> dict[str, Any]:
+    """Provide current weather for a specific city.
+
+    This example demonstrates:
+    1. Resource templates with URI parameters ({city})
+    2. Dynamic resource access based on parameters
+    3. Using shared client from the client.py file
+    4. FastMCP 2.11+ ResourceTemplate.from_function() usage
+
+    Args:
+        city: The city name to get weather for
+
+    Returns:
+        Weather data for the specified city
+    """
+    # Use the shared weather client from client.py
+    weather_data = await weather_client.get_current(city)
+
+    # Add some additional data
+    weather_data.update(
+        {
+            "city": city,
+            "time": datetime.now().isoformat(),
+            "source": "GolfMCP Weather API",
+            "unit": "fahrenheit",
+            "resource_type": "template",
+        }
+    )
+
+    return weather_data
+
+
+# Designate the entry point function
+export = get_weather_for_city

golf/examples/basic/resources/weather/client.py

@@ -0,0 +1,48 @@
+"""Weather shared functionality.
+
+This file demonstrates the recommended pattern for
+sharing functionality across multiple resources in a directory.
+Golf automatically discovers and includes shared Python files in builds.
+"""
+
+import os
+from typing import Any
+
+# Read configuration from environment variables
+WEATHER_API_KEY = os.environ.get("WEATHER_API_KEY", "mock_key")
+WEATHER_API_URL = os.environ.get("WEATHER_API_URL", "https://api.example.com/weather")
+TEMPERATURE_UNIT = os.environ.get("WEATHER_TEMP_UNIT", "fahrenheit")
+
+
+class WeatherApiClient:
+    """Mock weather API client."""
+
+    def __init__(self, api_key: str = WEATHER_API_KEY, api_url: str = WEATHER_API_URL) -> None:
+        self.api_key = api_key
+        self.api_url = api_url
+        self.unit = TEMPERATURE_UNIT
+
+    async def get_forecast(self, city: str, days: int = 3) -> dict[str, Any]:
+        """Get weather forecast for a city (mock implementation)."""
+        # This would make an API call in a real implementation
+        return {
+            "city": city,
+            "unit": self.unit,
+            "forecast": [{"day": i, "temp": 70 + i} for i in range(days)],
+        }
+
+    async def get_current(self, city: str) -> dict[str, Any]:
+        """Get current weather for a city (mock implementation)."""
+        return {
+            "city": city,
+            "unit": self.unit,
+            "temperature": 72,
+            "conditions": "Sunny",
+        }
+
+
+# Create a shared weather client that can be imported by all resources in this directory
+weather_client = WeatherApiClient()
+
+# This could also define shared models or other utilities
+# that would be common across weather-related resources

golf/examples/basic/resources/weather/current.py

@@ -0,0 +1,36 @@
+"""Current weather resource example."""
+
+from datetime import datetime
+from typing import Any
+
+from .client import weather_client
+
+# The URI that clients will use to access this resource
+resource_uri = "weather://current"
+
+
+async def current_weather() -> dict[str, Any]:
+    """Provide current weather for a default city.
+
+    This example demonstrates:
+    1. Nested resource organization (resources/weather/current.py)
+    2. Resource without URI parameters
+    3. Using shared client from the client.py file
+    """
+    # Use the shared weather client from client.py
+    weather_data = await weather_client.get_current("New York")
+
+    # Add some additional data
+    weather_data.update(
+        {
+            "time": datetime.now().isoformat(),
+            "source": "GolfMCP Weather API",
+            "unit": "fahrenheit",
+        }
+    )
+
+    return weather_data
+
+
+# Designate the entry point function
+export = current_weather