golf-mcp 0.2.16__py3-none-any.whl

golf/core/builder_auth.py

@@ -0,0 +1,209 @@
+"""Authentication integration for the Golf MCP build process.
+
+This module adds support for injecting authentication configuration
+into the generated FastMCP application during the build process using
+FastMCP 2.11+ built-in auth providers.
+"""
+
+from golf.auth import get_auth_config, is_auth_configured
+from golf.auth.api_key import get_api_key_config
+from golf.auth.providers import AuthConfig
+
+
+def generate_auth_code(
+    server_name: str,
+    host: str = "localhost",
+    port: int = 3000,
+    https: bool = False,
+    opentelemetry_enabled: bool = False,
+    transport: str = "streamable-http",
+) -> dict:
+    """Generate authentication components for the FastMCP app using modern
+    auth providers.
+
+    Returns a dictionary with:
+        - imports: List of import statements
+        - setup_code: Auth setup code (provider configuration, etc.)
+        - fastmcp_args: Dict of arguments to add to FastMCP constructor
+        - has_auth: Whether auth is configured
+    """
+    # Check for API key configuration first
+    api_key_config = get_api_key_config()
+    if api_key_config:
+        return generate_api_key_auth_components(server_name, opentelemetry_enabled, transport)
+
+    # Check for modern auth configuration
+    auth_config = get_auth_config()
+    if not auth_config:
+        # If no auth config, return empty components
+        return {"imports": [], "setup_code": [], "fastmcp_args": {}, "has_auth": False}
+
+    # Validate that we have a modern auth config
+    if not isinstance(auth_config, AuthConfig):
+        raise ValueError(
+            f"Invalid auth configuration type: {type(auth_config).__name__}. "
+            "Golf 0.2.x requires modern auth configurations (JWTAuthConfig, "
+            "StaticTokenConfig, OAuthServerConfig, or RemoteAuthConfig). "
+            "Please update your auth.py file."
+        )
+
+    # Generate modern auth components with embedded configuration
+    auth_imports = [
+        "import os",
+        "import sys",
+        "from golf.auth.factory import create_auth_provider",
+        "from golf.auth.providers import RemoteAuthConfig, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig, OAuthProxyConfig",
+    ]
+
+    # Embed the auth configuration directly in the generated code
+    # Convert the auth config to its string representation for embedding
+    auth_config_repr = repr(auth_config)
+
+    setup_code_lines = [
+        "# Modern FastMCP 2.11+ authentication setup with embedded configuration",
+        f"auth_config = {auth_config_repr}",
+        "try:",
+        "    auth_provider = create_auth_provider(auth_config)",
+        "    # Authentication configured with {auth_config.provider_type} provider",
+        "except Exception as e:",
+        "    print(f'Authentication setup failed: {e}', file=sys.stderr)",
+        "    auth_provider = None",
+        "",
+    ]
+
+    # FastMCP constructor arguments - FastMCP 2.11+ uses auth parameter
+    fastmcp_args = {"auth": "auth_provider"}
+
+    return {
+        "imports": auth_imports,
+        "setup_code": setup_code_lines,
+        "fastmcp_args": fastmcp_args,
+        "has_auth": True,
+    }
+
+
+def generate_api_key_auth_components(
+    server_name: str,
+    opentelemetry_enabled: bool = False,
+    transport: str = "streamable-http",
+) -> dict:
+    """Generate authentication components for API key authentication.
+
+    Returns a dictionary with:
+        - imports: List of import statements
+        - setup_code: Auth setup code (middleware setup)
+        - fastmcp_args: Dict of arguments to add to FastMCP constructor
+        - has_auth: Whether auth is configured
+    """
+    api_key_config = get_api_key_config()
+    if not api_key_config:
+        return {"imports": [], "setup_code": [], "fastmcp_args": {}, "has_auth": False}
+
+    auth_imports = [
+        "# API key authentication setup",
+        "from golf.auth.api_key import get_api_key_config, configure_api_key",
+        "from golf.auth import set_api_key",
+        "from starlette.middleware.base import BaseHTTPMiddleware",
+        "from starlette.requests import Request",
+        "from starlette.responses import JSONResponse",
+        "import os",
+    ]
+
+    setup_code_lines = [
+        "# Recreate API key configuration from auth.py",
+        "configure_api_key(",
+        f"    header_name={repr(api_key_config.header_name)},",
+        f"    header_prefix={repr(api_key_config.header_prefix)},",
+        f"    required={repr(api_key_config.required)}",
+        ")",
+        "",
+        "# Simplified API key middleware that validates presence",
+        "class ApiKeyMiddleware(BaseHTTPMiddleware):",
+        "    async def dispatch(self, request: Request, call_next):",
+        "        # Debug mode from environment",
+        "        debug = os.environ.get('API_KEY_DEBUG', '').lower() == 'true'",
+        "        ",
+        "        # Skip auth for monitoring endpoints",
+        "        path = request.url.path",
+        "        if path in ['/metrics', '/health']:",
+        "            return await call_next(request)",
+        "        ",
+        "        api_key_config = get_api_key_config()",
+        "        ",
+        "        if api_key_config:",
+        "            # Extract API key from the configured header",
+        "            header_name = api_key_config.header_name",
+        "            header_prefix = api_key_config.header_prefix",
+        "            ",
+        "            # Case-insensitive header lookup",
+        "            api_key = None",
+        "            for k, v in request.headers.items():",
+        "                if k.lower() == header_name.lower():",
+        "                    api_key = v",
+        "                    break",
+        "            ",
+        "            # Process the API key if found",
+        "            if api_key:",
+        "                # Strip prefix if configured",
+        "                if header_prefix and api_key.startswith(header_prefix):",
+        "                    api_key = api_key[len(header_prefix):]",
+        "                ",
+        "                # Store the API key in request state for tools to access",
+        "                request.state.api_key = api_key",
+        "                ",
+        "                # Also store in context variable for tools",
+        "                set_api_key(api_key)",
+        "            ",
+        "            # Check if API key is required but missing",
+        "            if api_key_config.required and not api_key:",
+        "                return JSONResponse(",
+        "                    {'error': 'unauthorized', "
+        "'detail': f'Missing required {header_name} header'},"
+        "                    status_code=401,",
+        "                    headers={'WWW-Authenticate': f'{header_name} realm=\"MCP Server\"'}",
+        "                )",
+        "        ",
+        "        # Continue with the request",
+        "        return await call_next(request)",
+        "",
+    ]
+
+    # API key auth is handled via middleware, not FastMCP constructor args
+    fastmcp_args = {}
+
+    return {
+        "imports": auth_imports,
+        "setup_code": setup_code_lines,
+        "fastmcp_args": fastmcp_args,
+        "has_auth": True,
+    }
+
+
+def generate_auth_routes() -> str:
+    """Generate code for auth routes in the FastMCP app.
+
+    Auth providers (RemoteAuthProvider, OAuthProvider) provide OAuth metadata routes
+    that need to be added to the server.
+    """
+    # API key auth doesn't need special routes
+    api_key_config = get_api_key_config()
+    if api_key_config:
+        return ""
+
+    # Check if auth is configured
+    if not is_auth_configured():
+        return ""
+
+    # Auth providers provide OAuth metadata routes that need to be added to the server
+    return """
+# Add OAuth metadata routes from auth provider
+if auth_provider and hasattr(auth_provider, 'get_routes'):
+    auth_routes = auth_provider.get_routes()
+    if auth_routes:
+        # Add routes to FastMCP's additional HTTP routes list
+        try:
+            mcp._additional_http_routes.extend(auth_routes)
+            # Added {len(auth_routes)} OAuth metadata routes
+        except Exception as e:
+            print(f"Warning: Failed to add OAuth routes: {e}")
+"""

golf/core/builder_metrics.py

@@ -0,0 +1,221 @@
+"""Metrics integration for the GolfMCP build process.
+
+This module provides functions for generating Prometheus metrics initialization
+and collection code for FastMCP servers built with GolfMCP.
+"""
+
+
+def generate_metrics_imports() -> list[str]:
+    """Generate import statements for metrics collection.
+
+    Returns:
+        List of import statements for metrics
+    """
+    return [
+        "# Prometheus metrics imports",
+        "from golf.metrics import init_metrics, get_metrics_collector",
+        "from prometheus_client import generate_latest, CONTENT_TYPE_LATEST",
+        "from starlette.responses import Response",
+        "from starlette.middleware.base import BaseHTTPMiddleware",
+        "from starlette.requests import Request",
+        "import time",
+    ]
+
+
+def generate_metrics_initialization(server_name: str) -> list[str]:
+    """Generate metrics initialization code.
+
+    Args:
+        server_name: Name of the MCP server
+
+    Returns:
+        List of code lines for metrics initialization
+    """
+    return [
+        "# Initialize metrics collection",
+        "init_metrics(enabled=True)",
+        "",
+    ]
+
+
+def generate_metrics_route(metrics_path: str) -> list[str]:
+    """Generate the metrics endpoint route code.
+
+    Args:
+        metrics_path: Path for the metrics endpoint (e.g., "/metrics")
+
+    Returns:
+        List of code lines for the metrics route
+    """
+    return [
+        "# Add metrics endpoint",
+        f'@mcp.custom_route("{metrics_path}", methods=["GET"])',
+        "async def metrics_endpoint(request):",
+        '    """Prometheus metrics endpoint for monitoring."""',
+        "    # Update uptime before returning metrics",
+        "    update_uptime()",
+        "    return Response(generate_latest(), media_type=CONTENT_TYPE_LATEST)",
+        "",
+    ]
+
+
+def generate_metrics_instrumentation() -> list[str]:
+    """Generate metrics instrumentation wrapper functions.
+
+    Returns:
+        List of code lines for metrics instrumentation
+    """
+    return [
+        "# Metrics instrumentation wrapper functions",
+        "import time",
+        "import functools",
+        "from typing import Any, Callable",
+        "",
+        "def instrument_tool(func: Callable, tool_name: str) -> Callable:",
+        '    """Wrap a tool function with metrics collection."""',
+        "    @functools.wraps(func)",
+        "    async def wrapper(*args, **kwargs) -> Any:",
+        "        collector = get_metrics_collector()",
+        "        start_time = time.time()",
+        "        status = 'success'",
+        "        try:",
+        "            result = await func(*args, **kwargs)",
+        "            return result",
+        "        except Exception as e:",
+        "            status = 'error'",
+        "            collector.increment_error('tool', type(e).__name__)",
+        "            raise",
+        "        finally:",
+        "            duration = time.time() - start_time",
+        "            collector.increment_tool_execution(tool_name, status)",
+        "            collector.record_tool_duration(tool_name, duration)",
+        "    return wrapper",
+        "",
+        "def instrument_resource(func: Callable, resource_name: str) -> Callable:",
+        '    """Wrap a resource function with metrics collection."""',
+        "    @functools.wraps(func)",
+        "    async def wrapper(*args, **kwargs) -> Any:",
+        "        collector = get_metrics_collector()",
+        "        try:",
+        "            result = await func(*args, **kwargs)",
+        "            # Extract URI from args if available for resource_reads metric",
+        "            if args and len(args) > 0:",
+        "                uri = str(args[0]) if args[0] else resource_name",
+        "            else:",
+        "                uri = resource_name",
+        "            collector.increment_resource_read(uri)",
+        "            return result",
+        "        except Exception as e:",
+        "            collector.increment_error('resource', type(e).__name__)",
+        "            raise",
+        "    return wrapper",
+        "",
+        "def instrument_prompt(func: Callable, prompt_name: str) -> Callable:",
+        '    """Wrap a prompt function with metrics collection."""',
+        "    @functools.wraps(func)",
+        "    async def wrapper(*args, **kwargs) -> Any:",
+        "        collector = get_metrics_collector()",
+        "        try:",
+        "            result = await func(*args, **kwargs)",
+        "            collector.increment_prompt_generation(prompt_name)",
+        "            return result",
+        "        except Exception as e:",
+        "            collector.increment_error('prompt', type(e).__name__)",
+        "            raise",
+        "    return wrapper",
+        "",
+        "# HTTP Request Metrics Middleware",
+        "class MetricsMiddleware(BaseHTTPMiddleware):",
+        '    """Middleware to collect HTTP request metrics."""',
+        "",
+        "    async def dispatch(self, request: Request, call_next):",
+        "        collector = get_metrics_collector()",
+        "        start_time = time.time()",
+        "        ",
+        "        # Extract path and method",
+        "        method = request.method",
+        "        path = request.url.path",
+        "        ",
+        "        try:",
+        "            response = await call_next(request)",
+        "            status_code = response.status_code",
+        "        except Exception as e:",
+        "            status_code = 500",
+        "            collector.increment_error('http', type(e).__name__)",
+        "            raise",
+        "        finally:",
+        "            duration = time.time() - start_time",
+        "            collector.increment_http_request(method, status_code, path)",
+        "            collector.record_http_duration(method, path, duration)",
+        "        ",
+        "        return response",
+        "",
+        "# Session tracking helpers",
+        "import atexit",
+        "from contextlib import asynccontextmanager",
+        "",
+        "# Global server start time for uptime tracking",
+        "_server_start_time = time.time()",
+        "",
+        "def track_session_start():",
+        '    """Track when a new session starts."""',
+        "    collector = get_metrics_collector()",
+        "    collector.increment_session()",
+        "",
+        "def track_session_end(start_time: float):",
+        '    """Track when a session ends."""',
+        "    collector = get_metrics_collector()",
+        "    duration = time.time() - start_time",
+        "    collector.record_session_duration(duration)",
+        "",
+        "def update_uptime():",
+        '    """Update the uptime metric."""',
+        "    collector = get_metrics_collector()",
+        "    uptime = time.time() - _server_start_time",
+        "    collector.set_uptime(uptime)",
+        "",
+        "# Initialize uptime tracking",
+        "update_uptime()",
+        "",
+    ]
+
+
+def generate_session_tracking() -> list[str]:
+    """Generate session tracking integration code.
+
+    Returns:
+        List of code lines for session tracking
+    """
+    return [
+        "# Session tracking integration",
+        "import asyncio",
+        "from typing import Dict",
+        "",
+        "# Track active sessions",
+        "_active_sessions: Dict[str, float] = {}",
+        "",
+        "# Hook into FastMCP's session lifecycle if available",
+        "try:",
+        "    from fastmcp.server import SessionManager",
+        "    ",
+        "    # Monkey patch session creation if possible",
+        "    _original_create_session = getattr(mcp, '_create_session', None)",
+        "    if _original_create_session:",
+        "        async def _patched_create_session(*args, **kwargs):",
+        "            session_id = str(id(args)) if args else 'unknown'",
+        "            _active_sessions[session_id] = time.time()",
+        "            track_session_start()",
+        "            try:",
+        "                return await _original_create_session(*args, **kwargs)",
+        "            except Exception:",
+        "                # If session creation fails, clean up",
+        "                if session_id in _active_sessions:",
+        "                    del _active_sessions[session_id]",
+        "                raise",
+        "        ",
+        "        mcp._create_session = _patched_create_session",
+        "except (ImportError, AttributeError):",
+        "    # Fallback: track sessions via request patterns",
+        "    pass",
+        "",
+    ]

golf/core/builder_telemetry.py

@@ -0,0 +1,99 @@
+"""OpenTelemetry integration for the GolfMCP build process.
+
+This module provides functions for generating OpenTelemetry initialization
+and instrumentation code for FastMCP servers built with GolfMCP.
+"""
+
+
+def generate_telemetry_imports() -> list[str]:
+    """Generate import statements for telemetry instrumentation.
+
+    Returns:
+        List of import statements for telemetry
+    """
+    return [
+        "# OpenTelemetry instrumentation imports",
+        "from golf.telemetry import (",
+        "    instrument_tool,",
+        "    instrument_resource,",
+        "    instrument_prompt,",
+        "    telemetry_lifespan,",
+        ")",
+    ]
+
+
+def generate_component_registration_with_telemetry(
+    component_type: str,
+    component_name: str,
+    module_path: str,
+    entry_function: str,
+    docstring: str = "",
+    uri_template: str = None,
+    is_template: bool = False,
+) -> str:
+    """Generate component registration code with telemetry instrumentation.
+
+    Args:
+        component_type: Type of component ('tool', 'resource', 'prompt')
+        component_name: Name of the component
+        module_path: Full module path to the component
+        entry_function: Entry function name
+        docstring: Component description
+        uri_template: URI template for resources (optional)
+        is_template: Whether the resource is a template (has URI parameters)
+
+    Returns:
+        Python code string for registering the component with instrumentation
+    """
+    func_ref = f"{module_path}.{entry_function}"
+    escaped_docstring = docstring.replace('"', '\\"') if docstring else ""
+
+    if component_type == "tool":
+        wrapped_func = f"instrument_tool({func_ref}, '{component_name}')"
+        return (
+            f"_tool = Tool.from_function({wrapped_func}, "
+            f'name="{component_name}", description="{escaped_docstring}")\n'
+            f"mcp.add_tool(_tool)"
+        )
+
+    elif component_type == "resource":
+        wrapped_func = f"instrument_resource({func_ref}, '{uri_template}')"
+        if is_template:
+            return (
+                f"_resource = ResourceTemplate.from_function({wrapped_func}, "
+                f'uri_template="{uri_template}", name="{component_name}", '
+                f'description="{escaped_docstring}")\n'
+                f"mcp.add_template(_resource)"
+            )
+        else:
+            return (
+                f"_resource = Resource.from_function({wrapped_func}, "
+                f'uri="{uri_template}", name="{component_name}", '
+                f'description="{escaped_docstring}")\n'
+                f"mcp.add_resource(_resource)"
+            )
+
+    elif component_type == "prompt":
+        wrapped_func = f"instrument_prompt({func_ref}, '{component_name}')"
+        return (
+            f"_prompt = Prompt.from_function({wrapped_func}, "
+            f'name="{component_name}", description="{escaped_docstring}")\n'
+            f"mcp.add_prompt(_prompt)"
+        )
+
+    else:
+        raise ValueError(f"Unknown component type: {component_type}")
+
+
+def get_otel_dependencies() -> list[str]:
+    """Get list of OpenTelemetry dependencies to add to pyproject.toml.
+
+    Returns:
+        List of package requirements strings
+    """
+    return [
+        "opentelemetry-api>=1.18.0",
+        "opentelemetry-sdk>=1.18.0",
+        "opentelemetry-instrumentation-asgi>=0.40b0",
+        "opentelemetry-exporter-otlp-proto-http>=0.40b0",
+    ]