golf-mcp 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

golf/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.1"
+__version__ = "0.1.3"

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/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/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/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/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/core/telemetry.py

@@ -0,0 +1,260 @@
+"""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 dotenv import load_dotenv
+
+from golf import __version__
+
+console = Console()
+
+# Load environment variables from core/.env if it exists
+core_env_path = Path(__file__).parent / ".env"
+if core_env_path.exists():
+    load_dotenv(core_env_path)
+
+# PostHog configuration
+POSTHOG_API_KEY = os.environ.get("GOLF_POSTHOG_API_KEY", "phc_YOUR_PROJECT_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 == "phc_YOUR_PROJECT_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 == "phc_YOUR_PROJECT_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/examples/basic/README.md

@@ -1,117 +1,61 @@
-# {{project_name}}
+# GolfMCP Project Boilerplate
 
-A GolfMCP project that provides MCP-compatible tools, resources, and prompts.
+This directory serves as a starting template for new GolfMCP projects. Initialize a project using the `golf init <your-project-name>` command.
+## About GolfMCP
 
-## Getting Started
+GolfMCP is a Python framework designed to build MCP servers with minimal boilerplate. It allows you to define tools, resources, and prompts as simple Python files. These components are then automatically discovered and compiled into a runnable [FastMCP](https://github.com/fastmcp/fastmcp) server.
 
-This project is built with [GolfMCP](https://github.com/yourusername/golfmcp), a Python framework for building MCP servers with zero boilerplate.
+## Getting Started (After `golf init`)
 
-To start the development server with hot reload:
+Once you've initialized your new project from this boilerplate:
 
-```bash
-golf dev
-```
+1.  **Navigate to your project directory:**
+    ```bash
+    cd your-project-name
+    ```
 
-This will watch for file changes and automatically reload the server.
+2.  **Start the development server:**
+    ```bash
+    golf build dev  # For a development build
+    # or
+    golf build prod # For a production build
+    
+    golf run
+    ```
 
 ## Project Structure
 
-- `tools/` - Tool implementations (functions an LLM can call)
-- `resources/` - Resource implementations (data an LLM can read)
-- `prompts/` - Prompt templates (conversations an LLM can use)
-- `golf.json` - Configuration file with settings like telemetry and transport
+Your initialized GolfMCP project will typically have the following structure:
 
-## Adding New Components
-
-### Tools
-
-To add a new tool, create a Python file in the `tools/` directory:
-
-```python
-# tools/my_tool.py
-from pydantic import BaseModel
-from fastmcp import Context
-
-class Input(BaseModel):
-    param1: str
-    param2: int = 42
-
-class Output(BaseModel):
-    result: str
-
-async def run(input: Input, ctx: Context) -> Output:
-    """Description of what my tool does."""
-    await ctx.info(f"Processing {input.param1}...")
-    return MyOutput(result=f"Processed {input.param1} with {input.param2}")
-```
-
-### Resources
-
-To add a new resource, create a Python file in the `resources/` directory:
+-   `tools/`: Directory for your tool implementations (Python files defining functions an LLM can call).
+-   `resources/`: Directory for your resource implementations (Python files defining data an LLM can read).
+-   `prompts/`: Directory for your prompt templates (Python files defining reusable conversation structures).
+-   `golf.json`: The main configuration file for your project, including settings like the server name, port, and transport.
+-   `pre_build.py`: (Optional) A Python script that can be used to run custom logic before the build process begins, such as configuring authentication.
+-   `.env`: File to store environment-specific variables (e.g., API keys). This is created during `golf init`.
 
-```python
-# resources/my_data.py
-resource_uri = "data://my-data"
-
-async def run() -> dict:
-    """Description of the resource."""
-    return {
-        "title": "My Data",
-        "content": "Some valuable information"
-    }
-```
-
-### Sharing Functionality with common.py
-
-For directories with multiple related components (like `tools/payments/` or `resources/weather/`), 
-use a `common.py` file to share functionality:
-
-```python
-# tools/payments/common.py
-class PaymentClient:
-    """Shared payment client implementation."""
-    # Implementation details...
-
-# Create a shared client instance
-payment_client = PaymentClient()
-```
-
-Then import and use the shared functionality in your components:
-
-```python
-# tools/payments/charge.py
-from .common import payment_client
+## Adding New Components
 
-async def run(input):
-    result = await payment_client.create_charge(...)
-    # Rest of implementation...
-```
+To add new functionalities:
 
-This pattern helps organize shared code and makes it easier to build and maintain your project.
+-   **Tools**: Create a new `.py` file in the `tools/` directory.
+-   **Resources**: Create a new `.py` file in the `resources/` directory.
+-   **Prompts**: Create a new `.py` file in the `prompts/` directory.
 
-## Telemetry
+Each Python file should generally define a single component. A module-level docstring in the file will be used as the description for the component. See the example files (e.g., `tools/hello.py`, `resources/info.py`) provided in this boilerplate for reference.
 
-This project includes OpenTelemetry integration for tracing server requests:
+For shared functionality within a component subdirectory (e.g., `tools/payments/common.py`), you can use a `common.py` file.
 
-```json
-// golf.json
-{
-  "telemetry": true,
-  "telemetry_exporter": "console"  // or "otlp_http"
-}
-```
+## Documentation
 
-You can configure it with environment variables:
-- `OTEL_SERVICE_NAME`: Set service name (defaults to app name)
-- `OTEL_TRACES_EXPORTER`: Exporter type ("console" or "otlp_http")
-- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP exporter endpoint URL
+For comprehensive details on the GolfMCP framework, including component specifications, advanced configurations, CLI commands, and more, please refer to the official documentation:
 
-## Deployment
+[https://docs.golf.dev](https://docs.golf.dev)
 
-To build the project for deployment:
+---
 
-```bash
-golf build
-```
+Happy Building! 
 
-This creates a standalone FastMCP application in the `dist/` directory. 
+<div align="center">
+Made with ❤️ in San Francisco
+</div>

golf_mcp-0.1.3.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: golf-mcp
+Version: 0.1.3
+Summary: Framework for building MCP servers
+Author-email: Antoni Gmitruk <antoni@golf.dev>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://golf.dev
+Project-URL: Repository, https://github.com/golf-mcp/golf
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+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: pydantic>=2.11.0
+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"
+Requires-Dist: opentelemetry-instrumentation-asgi>=0.40b0; extra == "telemetry"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=0.40b0; extra == "telemetry"
+Requires-Dist: wrapt>=1.17.0; extra == "telemetry"
+Dynamic: license-file
+
+<div align="center">
+  <img src="./golf-banner.png" alt="Golf Banner">
+  
+  <br>
+  
+  <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>
+    <a href="https://github.com/golf-mcp/golf/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs"></a>
+    <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"><strong>📚 Documentation</strong></a>
+  </p>
+</div>
+
+## Overview
+
+Golf is a **framework** designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—*tools*, *prompts*, and *resources*—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable FastMCP server, minimizing boilerplate and accelerating development.
+
+With Golf, you can focus on implementing your agent's logic rather than wrestling with server setup and integration complexities. It's built for developers who want a quick, organized way to build powerful MCP servers.
+
+## Quick Start
+
+Get your Golf project up and running in a few simple steps:
+
+### 1. Install Golf
+
+Ensure you have Python (3.10+ recommended) installed. Then, install Golf using pip:
+
+```bash
+pip install golf-mcp
+```
+
+### 2. Initialize Your Project
+
+Use the Golf CLI to scaffold a new project:
+
+```bash
+golf init your-project-name
+```
+This command creates a new directory (`your-project-name`) with a basic project structure, including example tools, resources, and a `golf.json` configuration file.
+
+### 3. Run the Development Server
+
+Navigate into your new project directory and start the development server:
+
+```bash
+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`).
+
+That's it! Your Golf server is running and ready for integration.
+
+## Basic Project Structure
+
+A Golf project initialized with `golf init` will have a structure similar to this:
+
+```
+<your-project-name>/
+│
+├─ golf.json          # Main project configuration
+│
+├─ tools/             # Directory for tool implementations
+│   └─ hello.py       # Example tool
+│
+├─ resources/         # Directory for resource implementations
+│   └─ info.py        # Example resource
+│
+├─ prompts/           # Directory for prompt templates
+│   └─ welcome.py     # Example prompt
+│
+├─ .env               # Environment variables (e.g., API keys, server port)
+└─ pre_build.py       # (Optional) Script for pre-build hooks (e.g., auth setup)
+```
+
+-   **`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).
+-   **`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
+
+Creating a new tool is as simple as adding a Python file to the `tools/` directory. The example `tools/hello.py` in the boilerplate looks like this:
+
+```python
+# tools/hello.py
+"""Hello World tool {{project_name}}."""
+
+from pydantic import BaseModel
+
+class Output(BaseModel):
+    """Response from the hello tool."""
+    message: str
+
+async def hello(
+    name: str = "World",
+    greeting: str = "Hello"
+) -> Output:
+    """Say hello to the given name.
+    
+    This is a simple example tool that demonstrates the basic structure
+    of a tool implementation in Golf.
+    """
+    print(f"{greeting} {name}...")
+    return Output(message=f"{greeting}, {name}!")
+
+# Designate the entry point function
+export = hello
+```
+Golf will automatically discover this file. The module docstring `"""Hello World tool {{project_name}}."""` is used as the tool's description. It infers parameters from the `hello` function's signature and uses the `Output` Pydantic model for the output schema. The tool will be registered with the ID `hello`.
+
+## Configuration (`golf.json`)
+
+The `golf.json` file is the heart of your Golf project configuration. Here's what each field controls:
+
+```jsonc
+{
+  "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)
+}
+```
+
+### 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
+
+Here are the things we are working hard on:
+
+*   **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**
+
+
+<div align="center">
+Made with ❤️ in Warsaw, Poland and SF
+</div>

{golf_mcp-0.1.1.dist-info → golf_mcp-0.1.3.dist-info}/RECORD

@@ -1,25 +1,26 @@
-golf/__init__.py,sha256=8oAxKUG747GUokmxjkrWejyJa5yPNEsoJDlXxoedxTw,21
+golf/__init__.py,sha256=R5TtpJu7Qu6sOarfDpp-5Oyy8Pi2Ir3VewCvsCQiAgo,21
 golf/auth/__init__.py,sha256=0cfMJsLsOAsA4gHynyPGDkrjB90s3xsGSFoCEWg-y6o,3999
 golf/auth/helpers.py,sha256=TqMlOzwtcQcrZ6en2WVkzH0TSQ0RsoDRObpi_rR0Ie4,1681
 golf/auth/oauth.py,sha256=MGtuKMSt77yihuZiuiEm33xAlXJynIMcFmMLZRlppdg,31525
 golf/auth/provider.py,sha256=-iIjw1XruxgpWTrwYBX9dbf_sLPlx5vZxZsM0E4Dp64,3931
 golf/cli/__init__.py,sha256=MG53_GB5QcXHJAwSUKhy3xWLWwzc3FrnFbcCg4z6M0w,45
-golf/cli/main.py,sha256=L4EmCu_CJsB42zdh1y3cnzxMZ2Bge5yb7v15durLZ4E,7299
+golf/cli/main.py,sha256=TcFTqFAcFOl2SxPxHFc6jg8OLVtr92KhVZzabpJISNI,9836
 golf/commands/__init__.py,sha256=FRehcdCr0TrH_399w-PO9OzLhE7z2FVoCFAmfqHsYWo,83
 golf/commands/build.py,sha256=yhcUrK9gHnXNuLPZ2brcmtMgR8wXMBlEBcaBgTKkanI,2295
-golf/commands/init.py,sha256=eVhHW6GIscZrGa8-EgJvKbjc47RkFq6bBc2y95VyK30,6629
-golf/commands/run.py,sha256=s0O15_wxxraDFTdjDWAXdnQzWzc2tTh76iS60wQ55Ec,1861
+golf/commands/init.py,sha256=6LMsjYUGOLrp6AVFx6c1WBFe_qE4W-26q4eMDF8nQAM,7105
+golf/commands/run.py,sha256=dLrjmpypfvInDkA-KgEUyKrTvkvp59yea5tUyxk_Ej4,1989
 golf/core/__init__.py,sha256=RDSMAkB5NDaV7W5OFJ--miqv6JmvM3rI9ashndqM3X4,52
 golf/core/builder.py,sha256=fUHLAjCxroSN_XJUYT07oC4VGvYMKyrzulDyR_VrwhY,52403
 golf/core/builder_auth.py,sha256=epc_pYcKcSaphcbJD-DHnFWFjjvQR6EhPETRfVzN4K4,9174
 golf/core/builder_telemetry.py,sha256=6ip4peRcb-RVZ6djorKW_VW6IiTCbnzOJYQm_YOMvpc,10189
-golf/core/config.py,sha256=rzUWmc9lbcEgCZR73k3PucxUb6v4X8psPD2SPXw539M,6886
-golf/core/parser.py,sha256=ZXQaNIIwQQvirTHudRPY42M9cmZUCVu5kUPrHxSpgKg,20996
+golf/core/config.py,sha256=gZ3eE8VIvDgIrLTizNq9XqkgfMkRg8Pm06gSVV51arA,6806
+golf/core/parser.py,sha256=sCVMWO7sGkSaKkU9LiHC3O9CTcrZxUbxnjdtwP7ne_o,19251
+golf/core/telemetry.py,sha256=mMqmBZm35BI8IAlRRj0jCAtzcGOprhaZzRslRhLb7dA,7355
 golf/core/transformer.py,sha256=3mr4_K4l1HZl1WQWSt9NKEhB5oi3b7kJnniseYEfrcI,5573
 golf/examples/__init__.py,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
 golf/examples/basic/.env,sha256=CRh4u1yXPCbjjgUKUMUgw51aOBdVFEgY748z7WgfkVc,156
 golf/examples/basic/.env.example,sha256=gCTFcabTvr_-Rg3kTGmi63JQtCEOwMu4U5jTa1GM66U,123
-golf/examples/basic/README.md,sha256=Hp6mQlC2pj_JKd55fO1O50zTxmqA55JldwoVOXUSCPA,2882
+golf/examples/basic/README.md,sha256=-mY3R6AAnkXT9FPkALDrJtdf9IyKDvuqjsrLAMTLRYI,2663
 golf/examples/basic/golf.json,sha256=JThi6EC93trGqECo3ryD3MhDcyR9Haub8kYvmYo4yjQ,213
 golf/examples/basic/pre_build.py,sha256=VVYtBSCy4Xjg1Ocpl8ZwEr7VCVqPSSkDEzrTfQkAQKY,1037
 golf/examples/basic/prompts/welcome.py,sha256=LgT1eQewe0J08I5WFBv4RrgDr6yn4a4ww6XQ8k3sTVk,822
@@ -33,9 +34,9 @@ golf/examples/basic/tools/hello.py,sha256=hJUMraxgi5g0gzhPbUZGOeAbiKZX4BTr1L64SE
 golf/examples/basic/tools/payments/charge.py,sha256=jLOyQmbpRm8cOIK2JXSirPmQGXDM-yHvg7ruv72j6qU,1287
 golf/examples/basic/tools/payments/common.py,sha256=z5shSOZizUEnxBmGUSYghxmNwIvuhg-yfXKIfPWgV04,1292
 golf/examples/basic/tools/payments/refund.py,sha256=_HG4dDeki8FyKCtWs5fXYeLpUsrc_SAx3vxAIS7Icf0,1302
-golf_mcp-0.1.1.dist-info/licenses/LICENSE,sha256=5_j2f6fTJmvfmUewzElhkpAaXg2grVoxKouOA8ihV6E,11348
-golf_mcp-0.1.1.dist-info/METADATA,sha256=mXLS9WPAwviBjcyjW9BRHVOlro9Uc0M90l5YVSLZtm4,2421
-golf_mcp-0.1.1.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-golf_mcp-0.1.1.dist-info/entry_points.txt,sha256=5y7rHYM8jGpU-nfwdknCm5XsApLulqsnA37MO6BUTYg,43
-golf_mcp-0.1.1.dist-info/top_level.txt,sha256=BQToHcBUufdyhp9ONGMIvPE40jMEtmI20lYaKb4hxOg,5
-golf_mcp-0.1.1.dist-info/RECORD,,
+golf_mcp-0.1.3.dist-info/licenses/LICENSE,sha256=5_j2f6fTJmvfmUewzElhkpAaXg2grVoxKouOA8ihV6E,11348
+golf_mcp-0.1.3.dist-info/METADATA,sha256=oG_C5jVawJ_ApzghOZYdbhEJKm5p4bH10b6kOZLm_kU,9390
+golf_mcp-0.1.3.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+golf_mcp-0.1.3.dist-info/entry_points.txt,sha256=5y7rHYM8jGpU-nfwdknCm5XsApLulqsnA37MO6BUTYg,43
+golf_mcp-0.1.3.dist-info/top_level.txt,sha256=BQToHcBUufdyhp9ONGMIvPE40jMEtmI20lYaKb4hxOg,5
+golf_mcp-0.1.3.dist-info/RECORD,,

golf_mcp-0.1.1.dist-info/METADATA

@@ -1,78 +0,0 @@
-Metadata-Version: 2.4
-Name: golf-mcp
-Version: 0.1.1
-Summary: Framework for building MCP servers
-Author-email: Antoni Gmitruk <antoni@golf.dev>
-License-Expression: Apache-2.0
-Project-URL: Homepage, https://golf.dev
-Project-URL: Repository, https://github.com/golf-mcp/golf
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
-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: pydantic>=2.11.0
-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
-Provides-Extra: telemetry
-Requires-Dist: opentelemetry-api>=1.33.1; extra == "telemetry"
-Requires-Dist: opentelemetry-sdk>=1.33.1; extra == "telemetry"
-Requires-Dist: opentelemetry-instrumentation-asgi>=0.40b0; extra == "telemetry"
-Requires-Dist: opentelemetry-exporter-otlp-proto-http>=0.40b0; extra == "telemetry"
-Requires-Dist: wrapt>=1.17.0; extra == "telemetry"
-Dynamic: license-file
-
-# GolfMCP
-
-A Pythonic framework for building Model Context Protocol (MCP) servers with zero boilerplate.
-
-## Features
-
-* 🚀 **Zero-to-live in under 90 seconds**: Quick setup and deployment
-* 💡 **Convention over configuration**: Minimal boilerplate
-* 🔄 **Fast feedback**: Hot-reload during development (≤ 500 ms)
-* 📂 **Nested folder support**: Organize your tools, resources, and prompts
-* 🔌 **Pluggable auth & deploy**: Built-in providers for OAuth, Vercel, Fly.io, etc.
-* 🛠️ **Delegates protocol compliance to FastMCP**: Focus on your logic, not the wire format
-
-## Installation
-
-```bash
-pip install golfmcp
-```
-
-## Quick Start
-
-Initialize a new project:
-
-```bash
-golf init my-mcp-project
-cd my-mcp-project
-```
-
-Start the development server with hot-reload:
-
-```bash
-golf dev
-```
-
-## Documentation
-
-For detailed documentation, visit [docs](https://golfmcp.docs.example.com/).
-
-## License
-
-MIT License