golf-mcp 0.1.14__tar.gz → 0.1.17__tar.gz

{golf_mcp-0.1.14 → golf_mcp-0.1.17}/.docs/docs.md

@@ -49,7 +49,7 @@ Given a component file `C` with absolute path
 let `PathRev = [pₙ, …, p₁]` (reverse order of parent dirs under the category). The **ID** is
 
 ```
-<filename> + ("-" + "-".join(PathRev) if PathRev else "")
+<filename> + ("_" + "_".join(PathRev) if PathRev else "")
 ```
 
 ### Formal Definition (BNF)
@@ -190,7 +190,7 @@ def run(charge_id: str, amount: int) -> dict:
 from tools.payments.refund import submit as _submit
 
 mcp.tool(
-    name="submit-refund-payments",
+    name="submit_refund_payments",
     description="Submit a refund request to Stripe."
 )(_submit.run)
 ```

{golf_mcp-0.1.14/src/golf_mcp.egg-info → golf_mcp-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: golf-mcp
-Version: 0.1.14
+Version: 0.1.17
 Summary: Framework for building MCP servers
 Author-email: Antoni Gmitruk <antoni@golf.dev>
 License-Expression: Apache-2.0
@@ -21,7 +21,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typer>=0.15.4
 Requires-Dist: rich>=14.0.0
-Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: fastmcp<2.6.0,>=2.0.0
 Requires-Dist: pydantic>=2.11.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: black>=24.10.0
@@ -128,7 +128,7 @@ A Golf project initialized with `golf init` will have a structure similar to thi
 
 -   **`golf.json`**: Configures server name, port, transport, telemetry, and other build settings.
 -   **`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 hyphens).
+    -   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.
 
 ## Example: Defining a Tool
@@ -178,6 +178,15 @@ The `golf.json` file is the heart of your Golf project configuration. Here's wha
                                       // - "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
@@ -193,11 +202,42 @@ The `golf.json` file is the heart of your Golf project configuration. Here's wha
   - `"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"
+}
+```
+
+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")
+```
+
 ### 🔍 OpenTelemetry Support
 
 Golf includes built-in OpenTelemetry instrumentation for distributed tracing. When enabled, it automatically traces:

{golf_mcp-0.1.14 → golf_mcp-0.1.17}/README.md

@@ -90,7 +90,7 @@ A Golf project initialized with `golf init` will have a structure similar to thi
 
 -   **`golf.json`**: Configures server name, port, transport, telemetry, and other build settings.
 -   **`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 hyphens).
+    -   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.
 
 ## Example: Defining a Tool
@@ -140,6 +140,15 @@ The `golf.json` file is the heart of your Golf project configuration. Here's wha
                                       // - "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
@@ -155,11 +164,42 @@ The `golf.json` file is the heart of your Golf project configuration. Here's wha
   - `"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"
+}
+```
+
+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")
+```
+
 ### 🔍 OpenTelemetry Support
 
 Golf includes built-in OpenTelemetry instrumentation for distributed tracing. When enabled, it automatically traces:

{golf_mcp-0.1.14 → golf_mcp-0.1.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "golf-mcp"
-version = "0.1.14"
+version = "0.1.17"
 description = "Framework for building MCP servers"
 authors = [
     {name = "Antoni Gmitruk", email = "antoni@golf.dev"}
@@ -28,7 +28,7 @@ classifiers = [
 dependencies = [
     "typer>=0.15.4",
     "rich>=14.0.0",
-    "fastmcp>=2.0.0",
+    "fastmcp>=2.0.0,<2.6.0",
     "pydantic>=2.11.0",
     "python-dotenv>=1.1.0",
     "black>=24.10.0",
@@ -64,7 +64,7 @@ golf = ["examples/**/*"]
 
 [tool.poetry]
 name = "golf-mcp"
-version = "0.1.14"
+version = "0.1.17"
 description = "Framework for building MCP servers with zero boilerplate"
 authors = ["Antoni Gmitruk <antoni@golf.dev>"]
 license = "Apache-2.0"
@@ -86,7 +86,7 @@ classifiers = [
 
 [tool.poetry.dependencies]
 python = ">=3.8" # Match requires-python
-fastmcp = ">=2.0.0"
+fastmcp = ">=2.0.0,<2.6.0"
 typer = {extras = ["all"], version = ">=0.15.4"}
 pydantic = ">=2.11.0"
 rich = ">=14.0.0"

golf_mcp-0.1.17/src/golf/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.17"

{golf_mcp-0.1.14 → golf_mcp-0.1.17}/src/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_mcp-0.1.14 → golf_mcp-0.1.17}/src/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_mcp-0.1.14 → golf_mcp-0.1.17}/src/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: