golf-mcp 0.1.14__py3-none-any.whl → 0.1.17__py3-none-any.whl

golf/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.14"
+__version__ = "0.1.17"

golf/cli/main.py

@@ -121,7 +121,11 @@ def build_dev(
         None, "--output-dir", "-o", help="Directory to output the built project"
     ),
 ) -> None:
-    """Build a development version with environment variables copied."""
+    """Build a development version with app environment variables copied.
+
+    Golf credentials (GOLF_*) are always loaded from .env for build operations.
+    All environment variables are copied to the built project for development.
+    """
     # Find project root directory
     project_root, config_path = find_project_root()
 
@@ -162,7 +166,7 @@ def build_dev(
             e,
             context="Development build with environment variables",
             operation="build_dev",
-            additional_props={"environment": "dev", "copy_env": True}
+            additional_props={"environment": "dev", "copy_env": True},
         )
         raise
 
@@ -173,7 +177,14 @@ def build_prod(
         None, "--output-dir", "-o", help="Directory to output the built project"
     ),
 ) -> None:
-    """Build a production version without copying environment variables."""
+    """Build a production version for deployment.
+
+    Golf credentials (GOLF_*) are always loaded from .env for build operations
+    (platform registration, resource updates). App environment variables are
+    NOT copied for security - provide them in your deployment environment.
+
+    Your production deployment must include GOLF_* vars for runtime telemetry.
+    """
     # Find project root directory
     project_root, config_path = find_project_root()
 
@@ -214,7 +225,7 @@ def build_prod(
             e,
             context="Production build without environment variables",
             operation="build_prod",
-            additional_props={"environment": "prod", "copy_env": False}
+            additional_props={"environment": "prod", "copy_env": False},
         )
         raise
 
@@ -275,15 +286,13 @@ def run(
 
                 build_project(project_root, settings, dist_dir)
             except Exception as e:
-                console.print(
-                    f"[bold red]Error building project:[/bold red] {str(e)}"
-                )
+                console.print(f"[bold red]Error building project:[/bold red] {str(e)}")
                 track_detailed_error(
                     "cli_run_failed",
                     e,
                     context="Auto-build before running server",
                     operation="auto_build_before_run",
-                    additional_props={"auto_build": True}
+                    additional_props={"auto_build": True},
                 )
                 raise
         else:
@@ -326,11 +335,11 @@ def run(
             # 2: General interrupt/graceful shutdown
             shutdown_type = {
                 130: "UserInterrupt",
-                143: "GracefulShutdown", 
+                143: "GracefulShutdown",
                 137: "ForcedShutdown",
-                2: "Interrupt"
+                2: "Interrupt",
             }.get(return_code, "GracefulShutdown")
-            
+
             track_event(
                 "cli_run_shutdown",
                 {
@@ -362,7 +371,7 @@ def run(
             e,
             context="Server execution or startup failure",
             operation="run_server_execution",
-            additional_props={"has_dist_dir": dist_dir.exists() if dist_dir else False}
+            additional_props={"has_dist_dir": dist_dir.exists() if dist_dir else False},
         )
         raise
 

golf/commands/init.py

@@ -7,7 +7,12 @@ from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 from rich.prompt import Confirm
 
-from golf.core.telemetry import track_command, track_event
+from golf.core.telemetry import (
+    track_command,
+    track_event,
+    set_telemetry_enabled,
+    load_telemetry_preference,
+)
 
 console = Console()
 
@@ -95,6 +100,9 @@ def initialize_project(
             # Copy directory structure
             _copy_template(template_dir, output_dir, project_name)
 
+        # Ask for telemetry consent
+        _prompt_for_telemetry_consent()
+
         # Create virtual environment
         console.print("[bold green]Project initialized successfully![/bold green]")
         console.print("\nTo get started, run:")
@@ -207,6 +215,60 @@ def _copy_template(source_dir: Path, target_dir: Path, project_name: str) -> Non
             f.write("dist/\n")
 
 
+def _prompt_for_telemetry_consent() -> None:
+    """Prompt user for telemetry consent and save their preference."""
+    import os
+
+    # Skip prompt in test mode, when telemetry is explicitly disabled, or if preference already exists
+    if os.environ.get("GOLF_TEST_MODE", "").lower() in ("1", "true", "yes", "on"):
+        return
+
+    # Skip if telemetry is explicitly disabled in environment
+    if os.environ.get("GOLF_TELEMETRY", "").lower() in ("0", "false", "no", "off"):
+        return
+
+    # Check if user already has a saved preference
+    existing_preference = load_telemetry_preference()
+    if existing_preference is not None:
+        return  # User already made a choice
+
+    console.print()
+    console.rule("[bold blue]Anonymous usage analytics[/bold blue]", style="blue")
+    console.print()
+    console.print(
+        "Golf can collect [bold]anonymous usage analytics[/bold] to help improve the tool."
+    )
+    console.print()
+    console.print("[dim]What we collect:[/dim]")
+    console.print("  • Command usage (init, build, run)")
+    console.print("  • Error types (to fix bugs)")
+    console.print("  • Golf version and Python version")
+    console.print("  • Operating system type")
+    console.print()
+    console.print("[dim]What we DON'T collect:[/dim]")
+    console.print("  • Your code or project content")
+    console.print("  • File paths or project names")
+    console.print("  • Personal information")
+    console.print("  • IP addresses")
+    console.print()
+    console.print(
+        "You can change this anytime by setting GOLF_TELEMETRY=0 in your environment."
+    )
+    console.print()
+
+    enable_telemetry = Confirm.ask(
+        "[bold]Enable anonymous usage analytics?[/bold]", default=False
+    )
+
+    set_telemetry_enabled(enable_telemetry, persist=True)
+
+    if enable_telemetry:
+        console.print("[green]✓[/green] Anonymous analytics enabled")
+    else:
+        console.print("[yellow]○[/yellow] Anonymous analytics disabled")
+    console.print()
+
+
 def _is_text_file(path: Path) -> bool:
     """Check if a file is a text file that needs variable substitution.
 

golf/commands/run.py

@@ -70,13 +70,21 @@ def run_server(
         elif process.returncode == 130:
             console.print("[yellow]Server stopped by user interrupt (Ctrl+C)[/yellow]")
         elif process.returncode == 143:
-            console.print("[yellow]Server stopped by SIGTERM (graceful shutdown)[/yellow]")
+            console.print(
+                "[yellow]Server stopped by SIGTERM (graceful shutdown)[/yellow]"
+            )
         elif process.returncode == 137:
-            console.print("[yellow]Server stopped by SIGKILL (forced shutdown)[/yellow]")
+            console.print(
+                "[yellow]Server stopped by SIGKILL (forced shutdown)[/yellow]"
+            )
         elif process.returncode in [1, 2]:
-            console.print(f"[red]Server exited with error code {process.returncode}[/red]")
+            console.print(
+                f"[red]Server exited with error code {process.returncode}[/red]"
+            )
         else:
-            console.print(f"[orange]Server exited with code {process.returncode}[/orange]")
+            console.print(
+                f"[orange]Server exited with code {process.returncode}[/orange]"
+            )
 
         return process.returncode
     except KeyboardInterrupt:

golf/core/builder.py

@@ -97,6 +97,11 @@ class ManifestBuilder:
             if required_fields:
                 tool_schema["inputSchema"]["required"] = required_fields
 
+            # Add tool annotations if present
+            if component.annotations:
+                # Merge with existing annotations (keeping title)
+                tool_schema["annotations"].update(component.annotations)
+
             # Add the tool to the manifest
             self.manifest["tools"].append(tool_schema)
 
@@ -556,14 +561,15 @@ class CodeGenerator:
         # Add OpenTelemetry imports if enabled
         if self.settings.opentelemetry_enabled:
             imports.extend(generate_telemetry_imports())
-            imports.append("")
 
-        # Add imports section for different transport methods
-        if self.settings.transport == "sse" or self.settings.transport in [
-            "streamable-http",
-            "http",
-        ]:
-            imports.append("import uvicorn")
+        # Add health check imports if enabled
+        if self.settings.health_check_enabled:
+            imports.extend(
+                [
+                    "from starlette.requests import Request",
+                    "from starlette.responses import PlainTextResponse",
+                ]
+            )
 
         # Get transport-specific configuration
         transport_config = self._get_transport_config(self.settings.transport)
@@ -650,7 +656,10 @@ class CodeGenerator:
                 # Add code to register this component
                 if self.settings.opentelemetry_enabled:
                     # Use telemetry instrumentation
-                    registration = f"# Register the {component_type.value} '{component.name}' with telemetry"
+                    registration = (
+                        f"# Register the {component_type.value} "
+                        f"'{component.name}' with telemetry"
+                    )
                     entry_func = (
                         component.entry_function
                         if hasattr(component, "entry_function")
@@ -658,15 +667,31 @@ class CodeGenerator:
                         else "export"
                     )
 
-                    # Debug: Add logging to verify wrapping
-                    registration += f"\n_wrapped_func = instrument_{component_type.value}({full_module_path}.{entry_func}, '{component.name}')"
+                    registration += (
+                        f"\n_wrapped_func = instrument_{component_type.value}("
+                        f"{full_module_path}.{entry_func}, '{component.name}')"
+                    )
 
                     if component_type == ComponentType.TOOL:
-                        registration += f'\nmcp.add_tool(_wrapped_func, name="{component.name}", description="{component.docstring or ""}")'
+                        registration += (
+                            f'\nmcp.add_tool(_wrapped_func, name="{component.name}", '
+                            f'description="{component.docstring or ""}"'
+                        )
+                        # Add annotations if present
+                        if hasattr(component, "annotations") and component.annotations:
+                            registration += f", annotations={component.annotations}"
+                        registration += ")"
                     elif component_type == ComponentType.RESOURCE:
-                        registration += f'\nmcp.add_resource_fn(_wrapped_func, uri="{component.uri_template}", name="{component.name}", description="{component.docstring or ""}")'
+                        registration += (
+                            f"\nmcp.add_resource_fn(_wrapped_func, "
+                            f'uri="{component.uri_template}", name="{component.name}", '
+                            f'description="{component.docstring or ""}")'
+                        )
                     else:  # PROMPT
-                        registration += f'\nmcp.add_prompt(_wrapped_func, name="{component.name}", description="{component.docstring or ""}")'
+                        registration += (
+                            f'\nmcp.add_prompt(_wrapped_func, name="{component.name}", '
+                            f'description="{component.docstring or ""}")'
+                        )
                 else:
                     # Standard registration without telemetry
                     if component_type == ComponentType.TOOL:
@@ -689,6 +714,11 @@ class CodeGenerator:
                             # Escape any quotes in the docstring
                             escaped_docstring = component.docstring.replace('"', '\\"')
                             registration += f', description="{escaped_docstring}"'
+
+                        # Add annotations if present
+                        if hasattr(component, "annotations") and component.annotations:
+                            registration += f", annotations={component.annotations}"
+
                         registration += ")"
 
                     elif component_type == ComponentType.RESOURCE:
@@ -711,6 +741,7 @@ class CodeGenerator:
                             # Escape any quotes in the docstring
                             escaped_docstring = component.docstring.replace('"', '\\"')
                             registration += f', description="{escaped_docstring}"'
+
                         registration += ")"
 
                     else:  # PROMPT
@@ -735,6 +766,7 @@ class CodeGenerator:
                             # Escape any quotes in the docstring
                             escaped_docstring = component.docstring.replace('"', '\\"')
                             registration += f', description="{escaped_docstring}"'
+
                         registration += ")"
 
                 component_registrations.append(registration)
@@ -770,6 +802,10 @@ class CodeGenerator:
             for key, value in auth_components["fastmcp_args"].items():
                 mcp_constructor_args.append(f"{key}={value}")
 
+        # Add stateless HTTP parameter if enabled
+        if self.settings.stateless_http:
+            mcp_constructor_args.append("stateless_http=True")
+
         # Add OpenTelemetry parameters if enabled
         if self.settings.opentelemetry_enabled:
             mcp_constructor_args.append("lifespan=telemetry_lifespan")
@@ -778,6 +814,18 @@ class CodeGenerator:
         server_code_lines.append(mcp_instance_line)
         server_code_lines.append("")
 
+        # Add early telemetry initialization if enabled (before component registration)
+        early_telemetry_init = []
+        if self.settings.opentelemetry_enabled:
+            early_telemetry_init.extend(
+                [
+                    "# Initialize telemetry early to ensure instrumentation works",
+                    "from golf.telemetry.instrumentation import init_telemetry",
+                    f'init_telemetry("{self.settings.name}")',
+                    "",
+                ]
+            )
+
         # Main entry point with transport-specific app initialization
         main_code = [
             'if __name__ == "__main__":',
@@ -805,86 +853,115 @@ class CodeGenerator:
 
         # Transport-specific run methods
         if self.settings.transport == "sse":
-            # Check if we need to add API key middleware for SSE
+            # Check if we need middleware for SSE
+            middleware_setup = []
+            middleware_list = []
+
             api_key_config = get_api_key_config()
             if auth_components.get("has_auth") and api_key_config:
-                main_code.extend(
-                    [
-                        "    # For SSE with API key auth, we need to get the app and add middleware",
-                        '    app = mcp.http_app(transport="sse")',
-                        "    app.add_middleware(ApiKeyMiddleware)",
-                    ]
+                middleware_setup.append(
+                    "    from starlette.middleware import Middleware"
                 )
-            else:
+                middleware_list.append("Middleware(ApiKeyMiddleware)")
+
+            # Add OpenTelemetry middleware if enabled
+            if self.settings.opentelemetry_enabled:
+                middleware_setup.append(
+                    "    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware"
+                )
+                middleware_setup.append(
+                    "    from starlette.middleware import Middleware"
+                )
+                middleware_list.append("Middleware(OpenTelemetryMiddleware)")
+
+            if middleware_setup:
+                main_code.extend(middleware_setup)
+                main_code.append(f"    middleware = [{', '.join(middleware_list)}]")
+                main_code.append("")
                 main_code.extend(
                     [
-                        "    # For SSE, get the app to add middleware",
-                        '    app = mcp.http_app(transport="sse")',
+                        "    # Run SSE server with middleware using FastMCP's run method",
+                        '    mcp.run(transport="sse", host=host, port=port, log_level="info", middleware=middleware)',
                     ]
                 )
-
-            # Add OpenTelemetry middleware to the SSE app if enabled
-            if self.settings.opentelemetry_enabled:
+            else:
                 main_code.extend(
                     [
-                        "    # Apply OpenTelemetry middleware to the SSE app",
-                        "    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware",
-                        "    app = OpenTelemetryMiddleware(app)",
+                        "    # Run SSE server using FastMCP's run method",
+                        '    mcp.run(transport="sse", host=host, port=port, log_level="info")',
                     ]
                 )
 
-            main_code.extend(
-                [
-                    "    # Run with the configured app",
-                    '    uvicorn.run(app, host=host, port=port, log_level="info")',
-                ]
-            )
         elif self.settings.transport in ["streamable-http", "http"]:
-            main_code.extend(
-                [
-                    "    # Create HTTP app and run with uvicorn",
-                    "    app = mcp.http_app()",
-                ]
-            )
+            # Check if we need middleware for streamable-http
+            middleware_setup = []
+            middleware_list = []
 
-            # Check if we need to add API key middleware
             api_key_config = get_api_key_config()
             if auth_components.get("has_auth") and api_key_config:
+                middleware_setup.append(
+                    "    from starlette.middleware import Middleware"
+                )
+                middleware_list.append("Middleware(ApiKeyMiddleware)")
+
+            # Add OpenTelemetry middleware if enabled
+            if self.settings.opentelemetry_enabled:
+                middleware_setup.append(
+                    "    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware"
+                )
+                middleware_setup.append(
+                    "    from starlette.middleware import Middleware"
+                )
+                middleware_list.append("Middleware(OpenTelemetryMiddleware)")
+
+            if middleware_setup:
+                main_code.extend(middleware_setup)
+                main_code.append(f"    middleware = [{', '.join(middleware_list)}]")
+                main_code.append("")
                 main_code.extend(
                     [
-                        "    # Add API key middleware",
-                        "    app.add_middleware(ApiKeyMiddleware)",
+                        "    # Run HTTP server with middleware using FastMCP's run method",
+                        '    mcp.run(transport="streamable-http", host=host, port=port, log_level="info", middleware=middleware)',
                     ]
                 )
-
-            # Add OpenTelemetry middleware to the HTTP app if enabled
-            if self.settings.opentelemetry_enabled:
+            else:
                 main_code.extend(
                     [
-                        "    # Apply OpenTelemetry middleware to the HTTP app",
-                        "    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware",
-                        "    app = OpenTelemetryMiddleware(app)",
+                        "    # Run HTTP server using FastMCP's run method",
+                        '    mcp.run(transport="streamable-http", host=host, port=port, log_level="info")',
                     ]
                 )
-
-            main_code.extend(
-                ['    uvicorn.run(app, host=host, port=port, log_level="info")']
-            )
         else:
             # For stdio transport, use mcp.run()
             main_code.extend(
                 ["    # Run with stdio transport", '    mcp.run(transport="stdio")']
             )
 
+        # Add health check route if enabled
+        health_check_code = []
+        if self.settings.health_check_enabled:
+            health_check_code = [
+                "# Add health check route",
+                "@mcp.custom_route('"
+                + self.settings.health_check_path
+                + '\', methods=["GET"])',
+                "async def health_check(request: Request) -> PlainTextResponse:",
+                '    """Health check endpoint for Kubernetes and load balancers."""',
+                f'    return PlainTextResponse("{self.settings.health_check_response}")',
+                "",
+            ]
+
         # Combine all sections
         # Order: imports, env_section, auth_setup, server_code (mcp init),
-        # post_init (API key middleware), component_registrations, main_code (run block)
+        # early_telemetry_init, component_registrations, health_check_code, main_code (run block)
         code = "\n".join(
             imports
             + env_section
             + auth_setup_code
             + server_code_lines
+            + early_telemetry_init
             + component_registrations
+            + health_check_code
             + main_code
         )
 
@@ -915,6 +992,21 @@ def build_project(
         build_env: Build environment ('dev' or 'prod')
         copy_env: Whether to copy environment variables to the built app
     """
+    # Load Golf credentials from .env for build operations (platform registration, etc.)
+    # This happens regardless of copy_env setting to ensure build process works
+    from dotenv import load_dotenv
+
+    project_env_file = project_path / ".env"
+    if project_env_file.exists():
+        # Load GOLF_* variables for build process
+        load_dotenv(project_env_file, override=False)
+
+        # Only log if we actually found the specific Golf platform credentials
+        has_api_key = "GOLF_API_KEY" in os.environ
+        has_server_id = "GOLF_SERVER_ID" in os.environ
+        if has_api_key and has_server_id:
+            console.print("[dim]Loaded Golf credentials for build operations[/dim]")
+
     # Execute pre_build.py if it exists
     pre_build_path = project_path / "pre_build.py"
     if pre_build_path.exists():
@@ -950,10 +1042,11 @@ def build_project(
             import traceback
 
             console.print(f"[red]{traceback.format_exc()}[/red]")
-            
+
             # Track detailed error for pre_build.py execution failures
             try:
                 from golf.core.telemetry import track_detailed_error
+
                 track_detailed_error(
                     "build_pre_build_failed",
                     e,
@@ -962,7 +1055,7 @@ def build_project(
                     additional_props={
                         "file_path": str(pre_build_path.relative_to(project_path)),
                         "build_env": build_env,
-                    }
+                    },
                 )
             except Exception:
                 # Don't let telemetry errors break the build
@@ -1015,9 +1108,6 @@ def build_project(
             env_vars_to_write["OTEL_TRACES_EXPORTER"] = (
                 settings.opentelemetry_default_exporter
             )
-            console.print(
-                f"[info]Setting OTEL_TRACES_EXPORTER to '{settings.opentelemetry_default_exporter}' from golf.json in built app's .env[/info]"
-            )
 
     # 3. Apply Golf's project name as OTEL_SERVICE_NAME if not already set
     # (Ensures service name defaults to project name if not specified in user's .env)
@@ -1069,6 +1159,36 @@ def build_project(
     )
     generator.generate()
 
+    # Platform registration (only for prod builds)
+    if build_env == "prod":
+        console.print(
+            "[dim]Registering with Golf platform and updating resources...[/dim]"
+        )
+        import asyncio
+
+        try:
+            from golf.core.platform import register_project_with_platform
+
+            asyncio.run(
+                register_project_with_platform(
+                    project_path=project_path,
+                    settings=settings,
+                    components=generator.components,
+                )
+            )
+            console.print("[green]✓ Platform registration completed[/green]")
+        except ImportError:
+            console.print(
+                "[yellow]Warning: Platform registration module not available[/yellow]"
+            )
+        except Exception as e:
+            console.print(
+                f"[yellow]Warning: Platform registration failed: {e}[/yellow]"
+            )
+            console.print(
+                "[yellow]Tip: Ensure GOLF_API_KEY and GOLF_SERVER_ID are available in your .env file[/yellow]"
+            )
+
     # Create a simple README
     readme_content = f"""# {settings.name}
 
@@ -1089,7 +1209,7 @@ This is a standalone FastMCP server generated by GolfMCP.
 
     # Copy pyproject.toml with required dependencies
     base_dependencies = [
-        "fastmcp>=2.0.0",
+        "fastmcp>=2.0.0,<2.6.0",
         "uvicorn>=0.20.0",
         "pydantic>=2.0.0",
         "python-dotenv>=1.0.0",

golf/core/config.py

@@ -102,6 +102,19 @@ class Settings(BaseSettings):
         "console", description="Default OpenTelemetry exporter type"
     )
 
+    # Health check configuration
+    health_check_enabled: bool = Field(
+        False, description="Enable health check endpoint"
+    )
+    health_check_path: str = Field("/health", description="Health check endpoint path")
+    health_check_response: str = Field("OK", description="Health check response text")
+
+    # HTTP session behaviour
+    stateless_http: bool = Field(
+        False,
+        description="Make Streamable-HTTP transport stateless (new session per request)",
+    )
+
 
 def find_config_path(start_path: Path | None = None) -> Path | None:
     """Find the golf config file by searching upwards from the given path.