golf-mcp 0.1.2__tar.gz → 0.1.4__tar.gz

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/.docs/docs.md

@@ -113,15 +113,13 @@ The parser SHALL fail the build if:
     \| **6 Packaging** | Copy auxiliary files (e.g. TLS certs) if declared. |
     \| **7 Completion** | Write artifact map & build log. |
 
-Build is **incremental**: SHA‑1 of each file stored; unchanged files skip parsing.
-
 ---
 
 ## 7  CLI Contract
 
 ```bash
 $ golf init [--template <repo‑url>]     # scaffold
-$ golf build [--outdir DIR] [--watch]   # compile once or watch mode
+$ golf build [--outdir DIR]             # compile once
 $ golf run   [--host HOST] [--port P]   # build if stale then exec app.py
 ```
 
@@ -203,18 +201,3 @@ mcp.tool(
 
 * **Pre‑Build Plugins** — `pre_build.py` in project root can register callbacks to mutate `Component` objects.
 * **Transport Providers** — third‑party packages can expose `golf_transport` entry‑point returning `TransportFactory` classes recognised by codegen.
-
----
-
-## 11  Compliance & Versioning
-
-* Spec version is tracked in `golf.json` under `"spec_version"` (default `0.2`).
-* Build engine MUST refuse to build projects with a higher spec\_version than supported.
-
----
-
-## 12  Open Items
-
-* Auto‑watch & hot‑reload (`golf run --watch`).
-* Injection metadata (`@inject("gmail_client")`) vs type‑based.
-* Resource URI override strategy.

{golf_mcp-0.1.2/src/golf_mcp.egg-info → golf_mcp-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: golf-mcp
-Version: 0.1.2
+Version: 0.1.4
 Summary: Framework for building MCP servers
 Author-email: Antoni Gmitruk <antoni@golf.dev>
 License-Expression: Apache-2.0
@@ -27,6 +27,7 @@ Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: black>=24.10.0
 Requires-Dist: pyjwt>=2.0.0
 Requires-Dist: httpx>=0.28.1
+Requires-Dist: posthog>=4.1.0
 Provides-Extra: telemetry
 Requires-Dist: opentelemetry-api>=1.33.1; extra == "telemetry"
 Requires-Dist: opentelemetry-sdk>=1.33.1; extra == "telemetry"
@@ -38,9 +39,19 @@ Dynamic: license-file
 <div align="center">
   <img src="./golf-banner.png" alt="Golf Banner">
   
-  <h1>Golf</h1>
+  <br>
   
-  <p><strong>Easiest framework for building MCP servers.</strong></p>
+  <h1 align="center">
+    <br>
+    <span style="font-size: 80px;">⛳ Golf</span>
+    <br>
+  </h1>
+  
+  <h3 align="center">
+    Easiest framework for building MCP servers
+  </h3>
+  
+  <br>
   
   <p>
     <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
@@ -48,7 +59,9 @@ Dynamic: license-file
     <a href="https://github.com/golf-mcp/golf/issues"><img src="https://img.shields.io/badge/support-contact%20author-purple.svg" alt="Support"></a>
   </p>
   
-  <p><a href="https://docs.golf.dev">Docs</a></p>
+  <p>
+    <a href="https://docs.golf.dev"><strong>📚 Documentation</strong></a>
+  </p>
 </div>
 
 ## Overview
@@ -87,7 +100,7 @@ cd your-project-name
 golf build dev
 golf run
 ```
-This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`). The `dev` command includes hot reloading, so changes to your component files will automatically restart the server.
+This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`).
 
 That's it! Your Golf server is running and ready for integration.
 
@@ -151,29 +164,76 @@ Golf will automatically discover this file. The module docstring `"""Hello World
 
 ## Configuration (`golf.json`)
 
-Key aspects of your Golf server are configured in `golf.json`. The boilerplate provides a starting point like this:
+The `golf.json` file is the heart of your Golf project configuration. Here's what each field controls:
 
 ```jsonc
 {
-  "name": "{{project_name}}",          // Will be replaced with your project name
-  "description": "A Golf project", // A default description
-  "host": "127.0.0.1",               // Server host address
-  "port": 3000,                      // Server port
-  "transport": "sse",                // 'sse', 'streamable-http', or 'stdio'
-  "opentelemetry_enabled": false,    // OpenTelemetry disabled by default - we're working on this as a feature
-  "opentelemetry_default_exporter": "console"
+  "name": "{{project_name}}",          // Your MCP server name (required)
+  "description": "A Golf project",     // Brief description of your server's purpose
+  "host": "127.0.0.1",                // Server host - use "0.0.0.0" to listen on all interfaces
+  "port": 3000,                       // Server port - any available port number
+  "transport": "sse",                 // Communication protocol:
+                                      // - "sse": Server-Sent Events (recommended for web clients)
+                                      // - "streamable-http": HTTP with streaming support
+                                      // - "stdio": Standard I/O (for CLI integration)
 }
 ```
-## Roadmap
 
-We are actively developing Golf. Here's what's on our current roadmap:
+### Key Configuration Options:
+
+- **`name`**: The identifier for your MCP server. This will be shown to clients connecting to your server.
+- **`transport`**: Choose based on your client needs:
+  - `"sse"` is ideal for web-based clients and real-time communication
+  - `"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.
+
+## Privacy & Telemetry
+
+Golf collects **anonymous** usage data to help us understand how the framework is being used and improve it over time. The data collected includes:
+
+- Commands run (init, build, run)
+- Success/failure status (no error details)
+- Golf version, Python version (major.minor only), and OS type
+- Template name (for init command only)
+- Build environment (dev/prod for build commands only)
 
+**No personal information, project names, code content, or error messages are ever collected.**
+
+### Opting Out
+
+You can disable telemetry in several ways:
+
+1. **Using the telemetry command** (recommended):
+   ```bash
+   golf telemetry disable
+   ```
+   This saves your preference permanently. To re-enable:
+   ```bash
+   golf telemetry enable
+   ```
+
+2. **During any command**: Add `--no-telemetry` to save your preference:
+   ```bash
+   golf init my-project --no-telemetry
+   ```
+
+3. **Environment variable** (temporary override):
+   ```bash
+   export GOLF_TELEMETRY=0
+   golf init my-project
+   ```
+
+Your telemetry preference is stored in `~/.golf/telemetry.json` and persists across all Golf commands.
+
+## Roadmap
 
-## Documentation
+Here are the things we are working hard on:
 
-For more information, please visit our official documentation:
+*   **Native OpenTelemetry implementation for tracing**
+*   **`golf deploy` command for one click deployments to Vercel, Blaxel and other providers**
+*   **Production-ready OAuth token management, to allow for persistent, encrypted token storage and client mapping**
 
-[https://docs.golf.dev](https://docs.golf.dev)
 
 <div align="center">
 Made with ❤️ in Warsaw, Poland and SF

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/README.md

@@ -1,9 +1,19 @@
 <div align="center">
   <img src="./golf-banner.png" alt="Golf Banner">
   
-  <h1>Golf</h1>
+  <br>
   
-  <p><strong>Easiest framework for building MCP servers.</strong></p>
+  <h1 align="center">
+    <br>
+    <span style="font-size: 80px;">⛳ Golf</span>
+    <br>
+  </h1>
+  
+  <h3 align="center">
+    Easiest framework for building MCP servers
+  </h3>
+  
+  <br>
   
   <p>
     <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
@@ -11,7 +21,9 @@
     <a href="https://github.com/golf-mcp/golf/issues"><img src="https://img.shields.io/badge/support-contact%20author-purple.svg" alt="Support"></a>
   </p>
   
-  <p><a href="https://docs.golf.dev">Docs</a></p>
+  <p>
+    <a href="https://docs.golf.dev"><strong>📚 Documentation</strong></a>
+  </p>
 </div>
 
 ## Overview
@@ -50,7 +62,7 @@ cd your-project-name
 golf build dev
 golf run
 ```
-This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`). The `dev` command includes hot reloading, so changes to your component files will automatically restart the server.
+This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`).
 
 That's it! Your Golf server is running and ready for integration.
 
@@ -114,29 +126,76 @@ Golf will automatically discover this file. The module docstring `"""Hello World
 
 ## Configuration (`golf.json`)
 
-Key aspects of your Golf server are configured in `golf.json`. The boilerplate provides a starting point like this:
+The `golf.json` file is the heart of your Golf project configuration. Here's what each field controls:
 
 ```jsonc
 {
-  "name": "{{project_name}}",          // Will be replaced with your project name
-  "description": "A Golf project", // A default description
-  "host": "127.0.0.1",               // Server host address
-  "port": 3000,                      // Server port
-  "transport": "sse",                // 'sse', 'streamable-http', or 'stdio'
-  "opentelemetry_enabled": false,    // OpenTelemetry disabled by default - we're working on this as a feature
-  "opentelemetry_default_exporter": "console"
+  "name": "{{project_name}}",          // Your MCP server name (required)
+  "description": "A Golf project",     // Brief description of your server's purpose
+  "host": "127.0.0.1",                // Server host - use "0.0.0.0" to listen on all interfaces
+  "port": 3000,                       // Server port - any available port number
+  "transport": "sse",                 // Communication protocol:
+                                      // - "sse": Server-Sent Events (recommended for web clients)
+                                      // - "streamable-http": HTTP with streaming support
+                                      // - "stdio": Standard I/O (for CLI integration)
 }
 ```
-## Roadmap
 
-We are actively developing Golf. Here's what's on our current roadmap:
+### Key Configuration Options:
+
+- **`name`**: The identifier for your MCP server. This will be shown to clients connecting to your server.
+- **`transport`**: Choose based on your client needs:
+  - `"sse"` is ideal for web-based clients and real-time communication
+  - `"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.
+
+## Privacy & Telemetry
+
+Golf collects **anonymous** usage data to help us understand how the framework is being used and improve it over time. The data collected includes:
+
+- Commands run (init, build, run)
+- Success/failure status (no error details)
+- Golf version, Python version (major.minor only), and OS type
+- Template name (for init command only)
+- Build environment (dev/prod for build commands only)
 
+**No personal information, project names, code content, or error messages are ever collected.**
+
+### Opting Out
+
+You can disable telemetry in several ways:
+
+1. **Using the telemetry command** (recommended):
+   ```bash
+   golf telemetry disable
+   ```
+   This saves your preference permanently. To re-enable:
+   ```bash
+   golf telemetry enable
+   ```
+
+2. **During any command**: Add `--no-telemetry` to save your preference:
+   ```bash
+   golf init my-project --no-telemetry
+   ```
+
+3. **Environment variable** (temporary override):
+   ```bash
+   export GOLF_TELEMETRY=0
+   golf init my-project
+   ```
+
+Your telemetry preference is stored in `~/.golf/telemetry.json` and persists across all Golf commands.
+
+## Roadmap
 
-## Documentation
+Here are the things we are working hard on:
 
-For more information, please visit our official documentation:
+*   **Native OpenTelemetry implementation for tracing**
+*   **`golf deploy` command for one click deployments to Vercel, Blaxel and other providers**
+*   **Production-ready OAuth token management, to allow for persistent, encrypted token storage and client mapping**
 
-[https://docs.golf.dev](https://docs.golf.dev)
 
 <div align="center">
 Made with ❤️ in Warsaw, Poland and SF

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "golf-mcp"
-version = "0.1.2"
+version = "0.1.4"
 description = "Framework for building MCP servers"
 authors = [
     {name = "Antoni Gmitruk", email = "antoni@golf.dev"}
@@ -33,7 +33,8 @@ dependencies = [
     "python-dotenv>=1.1.0",
     "black>=24.10.0",
     "pyjwt>=2.0.0",
-    "httpx>=0.28.1"
+    "httpx>=0.28.1",
+    "posthog>=4.1.0"
 ]
 
 [project.optional-dependencies]
@@ -63,7 +64,7 @@ golf = ["examples/**/*"]
 
 [tool.poetry]
 name = "golf-mcp"
-version = "0.1.0"
+version = "0.1.4"
 description = "Framework for building MCP servers with zero boilerplate"
 authors = ["Antoni Gmitruk <antoni@golf.dev>"]
 license = "Apache-2.0"

golf_mcp-0.1.4/src/golf/__init__.py

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

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/src/golf/cli/main.py

@@ -3,6 +3,7 @@
 import os
 from pathlib import Path
 from typing import Optional
+import atexit
 
 import typer
 from rich.console import Console
@@ -10,6 +11,7 @@ from rich.panel import Panel
 
 from golf import __version__
 from golf.core.config import load_settings, find_project_root
+from golf.core.telemetry import is_telemetry_enabled, shutdown, set_telemetry_enabled, track_event
 
 # Create console for rich output
 console = Console()
@@ -21,6 +23,9 @@ app = typer.Typer(
     add_completion=False,
 )
 
+# Register telemetry shutdown on exit
+atexit.register(shutdown)
+
 
 def _version_callback(value: bool) -> None:
     """Print version and exit if --version flag is used."""
@@ -43,7 +48,7 @@ def callback(
         False, "--verbose", "-v", help="Increase verbosity of output."
     ),
     no_telemetry: bool = typer.Option(
-        False, "--no-telemetry", help="Disable telemetry collection."
+        False, "--no-telemetry", help="Disable telemetry collection (persists for future commands)."
     ),
 ) -> None:
     """GolfMCP: A Pythonic framework for building MCP servers with zero boilerplate."""
@@ -51,9 +56,10 @@ def callback(
     if verbose:
         os.environ["GOLF_VERBOSE"] = "1"
     
-    # Set telemetry flag
+    # Set telemetry preference if flag is used
     if no_telemetry:
-        os.environ["GOLF_TELEMETRY"] = "0"
+        set_telemetry_enabled(False, persist=True)
+        console.print("[dim]Telemetry has been disabled. You can re-enable it with: golf telemetry enable[/dim]")
 
 
 @app.command()
@@ -78,7 +84,7 @@ def init(
     if output_dir is None:
         output_dir = Path.cwd() / project_name
     
-    # Execute the initialization command
+    # Execute the initialization command (it handles its own tracking)
     initialize_project(project_name=project_name, output_dir=output_dir, template=template)
 
 
@@ -100,6 +106,7 @@ def build_dev(
     if not project_root:
         console.print("[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]")
         console.print("Run 'golf init <project_name>' to create a new project.")
+        track_event("cli_build_failed", {"success": False, "environment": "dev"})
         raise typer.Exit(code=1)
     
     # Load settings from the found project
@@ -111,9 +118,15 @@ def build_dev(
     else:
         output_dir = Path(output_dir)
     
-    # Build the project with environment variables copied
-    from golf.commands.build import build_project
-    build_project(project_root, settings, output_dir, build_env="dev", copy_env=True)
+    try:
+        # Build the project with environment variables copied
+        from golf.commands.build import build_project
+        build_project(project_root, settings, output_dir, build_env="dev", copy_env=True)
+        # Track successful build with environment
+        track_event("cli_build_success", {"success": True, "environment": "dev"})
+    except Exception:
+        track_event("cli_build_failed", {"success": False, "environment": "dev"})
+        raise
 
 
 @build_app.command("prod")
@@ -129,6 +142,7 @@ def build_prod(
     if not project_root:
         console.print("[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]")
         console.print("Run 'golf init <project_name>' to create a new project.")
+        track_event("cli_build_failed", {"success": False, "environment": "prod"})
         raise typer.Exit(code=1)
     
     # Load settings from the found project
@@ -140,9 +154,15 @@ def build_prod(
     else:
         output_dir = Path(output_dir)
     
-    # Build the project without copying environment variables
-    from golf.commands.build import build_project
-    build_project(project_root, settings, output_dir, build_env="prod", copy_env=False)
+    try:
+        # Build the project without copying environment variables
+        from golf.commands.build import build_project
+        build_project(project_root, settings, output_dir, build_env="prod", copy_env=False)
+        # Track successful build with environment
+        track_event("cli_build_success", {"success": True, "environment": "prod"})
+    except Exception:
+        track_event("cli_build_failed", {"success": False, "environment": "prod"})
+        raise
 
 
 @app.command()
@@ -171,6 +191,7 @@ def run(
     if not project_root:
         console.print("[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]")
         console.print("Run 'golf init <project_name>' to create a new project.")
+        track_event("cli_run_failed", {"success": False})
         raise typer.Exit(code=1)
     
     # Load settings from the found project
@@ -192,21 +213,49 @@ def run(
         else:
             console.print(f"[bold red]Error: Dist directory {dist_dir} not found.[/bold red]")
             console.print("Run 'golf build' first or use --build to build automatically.")
+            track_event("cli_run_failed", {"success": False})
             raise typer.Exit(code=1)
     
-    # Import and run the server
-    from golf.commands.run import run_server
-    return_code = run_server(
-        project_path=project_root,
-        settings=settings,
-        dist_dir=dist_dir,
-        host=host,
-        port=port
-    )
-    
-    # Exit with the same code as the server
-    if return_code != 0:
-        raise typer.Exit(code=return_code)
+    try:
+        # Import and run the server
+        from golf.commands.run import run_server
+        return_code = run_server(
+            project_path=project_root,
+            settings=settings,
+            dist_dir=dist_dir,
+            host=host,
+            port=port
+        )
+        
+        # Track based on return code
+        if return_code == 0:
+            track_event("cli_run_success", {"success": True})
+        else:
+            track_event("cli_run_failed", {"success": False})
+        
+        # Exit with the same code as the server
+        if return_code != 0:
+            raise typer.Exit(code=return_code)
+    except Exception:
+        track_event("cli_run_failed", {"success": False})
+        raise
+
+
+# Add telemetry command group
+@app.command()
+def telemetry(
+    action: str = typer.Argument(..., help="Action to perform: 'enable' or 'disable'")
+):
+    """Manage telemetry settings."""
+    if action.lower() == "enable":
+        set_telemetry_enabled(True, persist=True)
+        console.print("[green]✓[/green] Telemetry enabled. Thank you for helping improve Golf!")
+    elif action.lower() == "disable":
+        set_telemetry_enabled(False, persist=True)
+        console.print("[yellow]Telemetry disabled.[/yellow] You can re-enable it anytime with: golf telemetry enable")
+    else:
+        console.print(f"[red]Unknown action '{action}'. Use 'enable' or 'disable'.[/red]")
+        raise typer.Exit(code=1)
 
 
 if __name__ == "__main__":
@@ -219,5 +268,12 @@ if __name__ == "__main__":
         )
     )
     
+    # Add telemetry notice if enabled
+    if is_telemetry_enabled():
+        console.print(
+            "[dim]📊 Anonymous usage data is collected to improve Golf. "
+            "Disable with: golf telemetry disable[/dim]\n"
+        )
+    
     # Run the CLI app
     app() 

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/src/golf/commands/init.py

@@ -1,12 +1,16 @@
 """Project initialization command implementation."""
 
+import os
 import shutil
 from pathlib import Path
+from typing import Optional
 
 from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 from rich.prompt import Confirm
 
+from golf.core.telemetry import track_event
+
 console = Console()
 
 
@@ -26,6 +30,7 @@ def initialize_project(
     if template not in ("basic", "advanced"):
         console.print(f"[bold red]Error:[/bold red] Unknown template '{template}'")
         console.print("Available templates: basic, advanced")
+        track_event("cli_init_failed", {"success": False})
         return
     
     # Check if directory exists
@@ -34,6 +39,7 @@ def initialize_project(
             console.print(
                 f"[bold red]Error:[/bold red] '{output_dir}' exists but is not a directory."
             )
+            track_event("cli_init_failed", {"success": False})
             return
         
         # Check if directory is empty
@@ -43,6 +49,7 @@ def initialize_project(
                 default=False,
             ):
                 console.print("Initialization cancelled.")
+                track_event("cli_init_cancelled", {"success": False})
                 return
     else:
         # Create the directory
@@ -59,6 +66,7 @@ def initialize_project(
         console.print(
             f"[bold red]Error:[/bold red] Could not find template '{template}'"
         )
+        track_event("cli_init_failed", {"success": False})
         return
     
     # Copy template files
@@ -77,6 +85,12 @@ def initialize_project(
     console.print(f"\nTo get started, run:")
     console.print(f"  cd {output_dir.name}")
     console.print(f"  golf build dev")
+    
+    # Track successful initialization
+    track_event("cli_init_success", {
+        "success": True,
+        "template": template
+    })
 
 
 def _copy_template(source_dir: Path, target_dir: Path, project_name: str) -> None:

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/src/golf/commands/run.py

@@ -62,7 +62,11 @@ def run_server(
             cwd=dist_dir,
             env=env,
         )
+        
         return process.returncode
     except KeyboardInterrupt:
         console.print("\n[yellow]Server stopped by user[/yellow]")
-        return 0 
+        return 0
+    except Exception as e:
+        console.print(f"\n[bold red]Error running server:[/bold red] {e}")
+        return 1 

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/src/golf/core/config.py

@@ -83,7 +83,6 @@ class Settings(BaseSettings):
     
     # Feature flags
     telemetry: bool = Field(True, description="Enable anonymous telemetry")
-    hot_reload: bool = Field(True, description="Enable hot reload in dev mode")
     
     # Project paths
     tools_dir: str = Field("tools", description="Directory containing tools")

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/src/golf/core/parser.py

@@ -6,7 +6,6 @@ from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
 from typing import Any, Dict, List, Optional
-import hashlib
 
 from rich.console import Console
 
@@ -436,47 +435,7 @@ def parse_project(project_path: Path) -> Dict[ComponentType, List[ParsedComponen
     return components
 
 
-def parse_project_incremental(project_path: Path, fingerprints: Dict[str, str]) -> Dict[ComponentType, List[ParsedComponent]]:
-    """Parse a project with incremental file checking."""
-    parser = AstParser(project_root=project_path)
-    
-    components: Dict[ComponentType, List[ParsedComponent]] = {
-        ComponentType.TOOL: [],
-        ComponentType.RESOURCE: [],
-        ComponentType.PROMPT: []
-    }
-    
-    # Process each directory
-    for comp_type, dir_name in [
-        (ComponentType.TOOL, "tools"),
-        (ComponentType.RESOURCE, "resources"),
-        (ComponentType.PROMPT, "prompts")
-    ]:
-        dir_path = project_path / dir_name
-        if not dir_path.exists() or not dir_path.is_dir():
-            continue
-            
-        # Parse only changed files using fingerprints
-        for file_path in dir_path.glob("**/*.py"):
-            if "__pycache__" in file_path.parts or file_path.name == "__init__.py":
-                continue
-                
-            # Check if file changed
-            with open(file_path, "rb") as f:
-                content = f.read()
-                file_hash = hashlib.sha1(content).hexdigest()
-            
-            rel_path = str(file_path.relative_to(project_path))
-            
-            if rel_path not in fingerprints or fingerprints[rel_path] != file_hash:
-                try:
-                    file_components = parser.parse_file(file_path)
-                    components[comp_type].extend([c for c in file_components if c.type == comp_type])
-                    fingerprints[rel_path] = file_hash
-                except Exception as e:
-                    console.print(f"[bold red]Error parsing {rel_path}: {e}[/bold red]")
-    
-    return components
+
 
 
 def parse_common_files(project_path: Path) -> Dict[str, Path]:

golf_mcp-0.1.4/src/golf/core/telemetry.py

@@ -0,0 +1,257 @@
+"""Telemetry module for anonymous usage tracking with PostHog."""
+
+import os
+import hashlib
+import platform
+from pathlib import Path
+from typing import Optional, Dict, Any
+import json
+
+import posthog
+from rich.console import Console
+
+from golf import __version__
+
+console = Console()
+
+# PostHog configuration
+# This is a client-side API key, safe to be public
+# Users can override with GOLF_POSTHOG_API_KEY environment variable
+DEFAULT_POSTHOG_API_KEY = "phc_7ccsDDxoC5tK5hodlrs2moGC74cThRzcN63flRYPWGl"  # Replace with your actual PostHog project API key
+POSTHOG_API_KEY = os.environ.get("GOLF_POSTHOG_API_KEY", DEFAULT_POSTHOG_API_KEY)
+POSTHOG_HOST = "https://us.i.posthog.com"
+
+# Telemetry state
+_telemetry_enabled: Optional[bool] = None
+_anonymous_id: Optional[str] = None
+
+
+def get_telemetry_config_path() -> Path:
+    """Get the path to the telemetry configuration file."""
+    return Path.home() / ".golf" / "telemetry.json"
+
+
+def save_telemetry_preference(enabled: bool) -> None:
+    """Save telemetry preference to persistent storage."""
+    config_path = get_telemetry_config_path()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    config = {
+        "enabled": enabled,
+        "version": 1
+    }
+    
+    try:
+        with open(config_path, "w") as f:
+            json.dump(config, f)
+    except Exception:
+        # Don't fail if we can't save the preference
+        pass
+
+
+def load_telemetry_preference() -> Optional[bool]:
+    """Load telemetry preference from persistent storage."""
+    config_path = get_telemetry_config_path()
+    
+    if not config_path.exists():
+        return None
+    
+    try:
+        with open(config_path, "r") as f:
+            config = json.load(f)
+            return config.get("enabled")
+    except Exception:
+        return None
+
+
+def is_telemetry_enabled() -> bool:
+    """Check if telemetry is enabled.
+    
+    Checks in order:
+    1. Cached value
+    2. GOLF_TELEMETRY environment variable
+    3. Persistent preference file
+    4. Default to True (opt-out model)
+    """
+    global _telemetry_enabled
+    
+    if _telemetry_enabled is not None:
+        return _telemetry_enabled
+    
+    # Check environment variables (highest priority)
+    env_telemetry = os.environ.get("GOLF_TELEMETRY", "").lower()
+    if env_telemetry in ("0", "false", "no", "off"):
+        _telemetry_enabled = False
+        return False
+    elif env_telemetry in ("1", "true", "yes", "on"):
+        _telemetry_enabled = True
+        return True
+    
+    # Check persistent preference
+    saved_preference = load_telemetry_preference()
+    if saved_preference is not None:
+        _telemetry_enabled = saved_preference
+        return saved_preference
+    
+    # Default to enabled (opt-out model)
+    _telemetry_enabled = True
+    return True
+
+
+def set_telemetry_enabled(enabled: bool, persist: bool = True) -> None:
+    """Set telemetry enabled state.
+    
+    Args:
+        enabled: Whether telemetry should be enabled
+        persist: Whether to save this preference persistently
+    """
+    global _telemetry_enabled
+    _telemetry_enabled = enabled
+    
+    if persist:
+        save_telemetry_preference(enabled)
+
+
+def get_anonymous_id() -> str:
+    """Get or create a persistent anonymous ID for this machine.
+    
+    The ID is stored in the user's home directory and is based on
+    machine characteristics to be consistent across sessions.
+    """
+    global _anonymous_id
+    
+    if _anonymous_id:
+        return _anonymous_id
+    
+    # Try to load existing ID
+    id_file = Path.home() / ".golf" / "telemetry_id"
+    
+    if id_file.exists():
+        try:
+            _anonymous_id = id_file.read_text().strip()
+            if _anonymous_id:
+                return _anonymous_id
+        except Exception:
+            pass
+    
+    # Generate new ID based on machine characteristics
+    # This ensures the same ID across sessions on the same machine
+    machine_data = f"{platform.node()}-{platform.machine()}-{platform.system()}"
+    machine_hash = hashlib.sha256(machine_data.encode()).hexdigest()[:16]
+    _anonymous_id = f"golf-{machine_hash}"
+    
+    # Try to save for next time
+    try:
+        id_file.parent.mkdir(parents=True, exist_ok=True)
+        id_file.write_text(_anonymous_id)
+    except Exception:
+        # Not critical if we can't save
+        pass
+    
+    return _anonymous_id
+
+
+def initialize_telemetry() -> None:
+    """Initialize PostHog telemetry if enabled."""
+    if not is_telemetry_enabled():
+        return
+    
+    # Skip initialization if no valid API key
+    if not POSTHOG_API_KEY or POSTHOG_API_KEY == DEFAULT_POSTHOG_API_KEY:
+        return
+    
+    try:
+        posthog.project_api_key = POSTHOG_API_KEY
+        posthog.host = POSTHOG_HOST
+        
+        # Disable PostHog's own logging to avoid noise
+        posthog.disabled = False
+        posthog.debug = False
+        
+    except Exception:
+        # Telemetry should never break the application
+        pass
+
+
+def track_event(event_name: str, properties: Optional[Dict[str, Any]] = None) -> None:
+    """Track an anonymous event with minimal data.
+    
+    Args:
+        event_name: Name of the event (e.g., "cli_init", "cli_build")
+        properties: Optional properties to include with the event
+    """
+    if not is_telemetry_enabled():
+        return
+    
+    # Skip if no valid API key
+    if not POSTHOG_API_KEY or POSTHOG_API_KEY == DEFAULT_POSTHOG_API_KEY:
+        return
+    
+    try:
+        # Initialize if needed
+        if posthog.project_api_key != POSTHOG_API_KEY:
+            initialize_telemetry()
+        
+        # Get anonymous ID
+        anonymous_id = get_anonymous_id()
+        
+        # Only include minimal, non-identifying properties
+        safe_properties = {
+            "golf_version": __version__,
+            "python_version": f"{platform.python_version_tuple()[0]}.{platform.python_version_tuple()[1]}",
+            "os": platform.system(),
+        }
+        
+        # Filter properties to only include safe ones
+        if properties:
+            # Only include specific safe properties
+            safe_keys = {"success", "environment", "template", "command_type"}
+            for key in safe_keys:
+                if key in properties:
+                    safe_properties[key] = properties[key]
+        
+        # Send event
+        posthog.capture(
+            distinct_id=anonymous_id,
+            event=event_name,
+            properties=safe_properties,
+        )
+        
+    except Exception:
+        # Telemetry should never break the application
+        pass
+
+
+def track_command(command: str, success: bool = True) -> None:
+    """Track a CLI command execution with minimal info.
+    
+    Args:
+        command: The command being executed (e.g., "init", "build", "run")
+        success: Whether the command was successful
+    """
+    # Simplify the event to just command and success
+    track_event(f"cli_{command}", {"success": success})
+
+
+def flush() -> None:
+    """Flush any pending telemetry events."""
+    if not is_telemetry_enabled():
+        return
+    
+    try:
+        posthog.flush()
+    except Exception:
+        # Ignore flush errors
+        pass
+
+
+def shutdown() -> None:
+    """Shutdown telemetry and flush pending events."""
+    if not is_telemetry_enabled():
+        return
+    
+    try:
+        posthog.shutdown()
+    except Exception:
+        # Ignore shutdown errors
+        pass 

{golf_mcp-0.1.2 → golf_mcp-0.1.4/src/golf_mcp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: golf-mcp
-Version: 0.1.2
+Version: 0.1.4
 Summary: Framework for building MCP servers
 Author-email: Antoni Gmitruk <antoni@golf.dev>
 License-Expression: Apache-2.0
@@ -27,6 +27,7 @@ Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: black>=24.10.0
 Requires-Dist: pyjwt>=2.0.0
 Requires-Dist: httpx>=0.28.1
+Requires-Dist: posthog>=4.1.0
 Provides-Extra: telemetry
 Requires-Dist: opentelemetry-api>=1.33.1; extra == "telemetry"
 Requires-Dist: opentelemetry-sdk>=1.33.1; extra == "telemetry"
@@ -38,9 +39,19 @@ Dynamic: license-file
 <div align="center">
   <img src="./golf-banner.png" alt="Golf Banner">
   
-  <h1>Golf</h1>
+  <br>
   
-  <p><strong>Easiest framework for building MCP servers.</strong></p>
+  <h1 align="center">
+    <br>
+    <span style="font-size: 80px;">⛳ Golf</span>
+    <br>
+  </h1>
+  
+  <h3 align="center">
+    Easiest framework for building MCP servers
+  </h3>
+  
+  <br>
   
   <p>
     <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
@@ -48,7 +59,9 @@ Dynamic: license-file
     <a href="https://github.com/golf-mcp/golf/issues"><img src="https://img.shields.io/badge/support-contact%20author-purple.svg" alt="Support"></a>
   </p>
   
-  <p><a href="https://docs.golf.dev">Docs</a></p>
+  <p>
+    <a href="https://docs.golf.dev"><strong>📚 Documentation</strong></a>
+  </p>
 </div>
 
 ## Overview
@@ -87,7 +100,7 @@ cd your-project-name
 golf build dev
 golf run
 ```
-This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`). The `dev` command includes hot reloading, so changes to your component files will automatically restart the server.
+This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`).
 
 That's it! Your Golf server is running and ready for integration.
 
@@ -151,29 +164,76 @@ Golf will automatically discover this file. The module docstring `"""Hello World
 
 ## Configuration (`golf.json`)
 
-Key aspects of your Golf server are configured in `golf.json`. The boilerplate provides a starting point like this:
+The `golf.json` file is the heart of your Golf project configuration. Here's what each field controls:
 
 ```jsonc
 {
-  "name": "{{project_name}}",          // Will be replaced with your project name
-  "description": "A Golf project", // A default description
-  "host": "127.0.0.1",               // Server host address
-  "port": 3000,                      // Server port
-  "transport": "sse",                // 'sse', 'streamable-http', or 'stdio'
-  "opentelemetry_enabled": false,    // OpenTelemetry disabled by default - we're working on this as a feature
-  "opentelemetry_default_exporter": "console"
+  "name": "{{project_name}}",          // Your MCP server name (required)
+  "description": "A Golf project",     // Brief description of your server's purpose
+  "host": "127.0.0.1",                // Server host - use "0.0.0.0" to listen on all interfaces
+  "port": 3000,                       // Server port - any available port number
+  "transport": "sse",                 // Communication protocol:
+                                      // - "sse": Server-Sent Events (recommended for web clients)
+                                      // - "streamable-http": HTTP with streaming support
+                                      // - "stdio": Standard I/O (for CLI integration)
 }
 ```
-## Roadmap
 
-We are actively developing Golf. Here's what's on our current roadmap:
+### Key Configuration Options:
+
+- **`name`**: The identifier for your MCP server. This will be shown to clients connecting to your server.
+- **`transport`**: Choose based on your client needs:
+  - `"sse"` is ideal for web-based clients and real-time communication
+  - `"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.
+
+## Privacy & Telemetry
+
+Golf collects **anonymous** usage data to help us understand how the framework is being used and improve it over time. The data collected includes:
+
+- Commands run (init, build, run)
+- Success/failure status (no error details)
+- Golf version, Python version (major.minor only), and OS type
+- Template name (for init command only)
+- Build environment (dev/prod for build commands only)
 
+**No personal information, project names, code content, or error messages are ever collected.**
+
+### Opting Out
+
+You can disable telemetry in several ways:
+
+1. **Using the telemetry command** (recommended):
+   ```bash
+   golf telemetry disable
+   ```
+   This saves your preference permanently. To re-enable:
+   ```bash
+   golf telemetry enable
+   ```
+
+2. **During any command**: Add `--no-telemetry` to save your preference:
+   ```bash
+   golf init my-project --no-telemetry
+   ```
+
+3. **Environment variable** (temporary override):
+   ```bash
+   export GOLF_TELEMETRY=0
+   golf init my-project
+   ```
+
+Your telemetry preference is stored in `~/.golf/telemetry.json` and persists across all Golf commands.
+
+## Roadmap
 
-## Documentation
+Here are the things we are working hard on:
 
-For more information, please visit our official documentation:
+*   **Native OpenTelemetry implementation for tracing**
+*   **`golf deploy` command for one click deployments to Vercel, Blaxel and other providers**
+*   **Production-ready OAuth token management, to allow for persistent, encrypted token storage and client mapping**
 
-[https://docs.golf.dev](https://docs.golf.dev)
 
 <div align="center">
 Made with ❤️ in Warsaw, Poland and SF

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/src/golf_mcp.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ src/golf/core/builder_auth.py
 src/golf/core/builder_telemetry.py
 src/golf/core/config.py
 src/golf/core/parser.py
+src/golf/core/telemetry.py
 src/golf/core/transformer.py
 src/golf/examples/__init__.py
 src/golf/examples/basic/.env

{golf_mcp-0.1.2 → golf_mcp-0.1.4}/src/golf_mcp.egg-info/requires.txt

@@ -6,6 +6,7 @@ python-dotenv>=1.1.0
 black>=24.10.0
 pyjwt>=2.0.0
 httpx>=0.28.1
+posthog>=4.1.0
 
 [telemetry]
 opentelemetry-api>=1.33.1

golf_mcp-0.1.2/src/golf/__init__.py

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