golf-mcp 0.1.0__py3-none-any.whl

golf/auth/provider.py

@@ -0,0 +1,110 @@
+"""OAuth provider configuration for GolfMCP authentication.
+
+This module defines the ProviderConfig class used to configure
+OAuth authentication for GolfMCP servers.
+"""
+
+from typing import Dict, List, Optional, Any
+from pydantic import BaseModel, Field, field_validator
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for an OAuth2 provider.
+    
+    This class defines the configuration for an OAuth2 provider,
+    including the endpoints, credentials, and other settings needed
+    to authenticate with the provider.
+    """
+    
+    # Provider identification
+    provider: str = Field(
+        ..., 
+        description="Provider type (e.g., 'github', 'google', 'custom')"
+    )
+    
+    # OAuth credentials - names of environment variables to read at runtime
+    client_id_env_var: str = Field(..., description="Name of environment variable for Client ID")
+    client_secret_env_var: str = Field(..., description="Name of environment variable for Client Secret")
+    
+    # These fields will store the actual values read at runtime in dist/server.py
+    # They are made optional here as they are resolved in the generated code.
+    client_id: Optional[str] = Field(None, description="OAuth client ID (resolved at runtime)")
+    client_secret: Optional[str] = Field(None, description="OAuth client secret (resolved at runtime)")
+
+    # OAuth endpoints (can be baked in)
+    authorize_url: str = Field(..., description="Authorization endpoint URL")
+    token_url: str = Field(..., description="Token endpoint URL")
+    userinfo_url: Optional[str] = Field(
+        None, 
+        description="User info endpoint URL (for OIDC providers)"
+    )
+    
+    jwks_uri: Optional[str] = Field(
+        None, 
+        description="JSON Web Key Set URI (for token validation)"
+    )
+    
+    scopes: List[str] = Field(
+        default_factory=list, 
+        description="OAuth scopes to request from the provider"
+    )
+    
+    issuer_url: Optional[str] = Field(
+        None, 
+        description="OIDC issuer URL for discovery (if using OIDC) - will be overridden by runtime value in server.py"
+    )
+    
+    callback_path: str = Field(
+        "/auth/callback", 
+        description="Path on this server where the IdP should redirect after authentication"
+    )
+    
+    # JWT configuration
+    jwt_secret_env_var: str = Field(..., description="Name of environment variable for JWT Secret")
+    jwt_secret: Optional[str] = Field(None, description="Secret key for signing JWT tokens (resolved at runtime)")
+    token_expiration: int = Field(
+        3600, 
+        description="JWT token expiration time in seconds",
+        ge=60, 
+        le=86400
+    )
+    
+    settings: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional provider-specific settings"
+    )
+    
+    @field_validator('provider')
+    @classmethod
+    def validate_provider(cls, value: str) -> str:
+        """Validate the provider type.
+        
+        Ensures the provider type is a valid, supported provider.
+        
+        Args:
+            value: The provider type
+            
+        Returns:
+            The validated provider type
+            
+        Raises:
+            ValueError: If the provider type is not supported
+        """
+        known_providers = {'custom', 'github', 'google', 'jwks'}
+        
+        if value not in known_providers and not value.startswith('custom:'):
+            raise ValueError(
+                f"Unknown provider: '{value}'. Must be one of {known_providers} "
+                "or start with 'custom:'"
+            )
+        return value
+    
+    def get_provider_name(self) -> str:
+        """Get a clean provider name for display purposes.
+        
+        Returns:
+            A human-readable provider name
+        """
+        if self.provider.startswith('custom:'):
+            return self.provider[7:]  # Remove 'custom:' prefix
+        return self.provider.capitalize() 

golf/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for the GolfMCP framework.""" 

golf/cli/main.py

@@ -0,0 +1,223 @@
+"""CLI entry points for GolfMCP."""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from golf import __version__
+from golf.core.config import load_settings, find_project_root
+
+# Create console for rich output
+console = Console()
+
+# Create the typer app instance
+app = typer.Typer(
+    name="golf",
+    help="GolfMCP: A Pythonic framework for building MCP servers with zero boilerplate",
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Print version and exit if --version flag is used."""
+    if value:
+        console.print(f"GolfMCP v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def callback(
+    version: bool = typer.Option(
+        None,
+        "--version",
+        "-V",
+        help="Show the version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Increase verbosity of output."
+    ),
+    no_telemetry: bool = typer.Option(
+        False, "--no-telemetry", help="Disable telemetry collection."
+    ),
+) -> None:
+    """GolfMCP: A Pythonic framework for building MCP servers with zero boilerplate."""
+    # Set verbosity in environment for other components to access
+    if verbose:
+        os.environ["GOLF_VERBOSE"] = "1"
+    
+    # Set telemetry flag
+    if no_telemetry:
+        os.environ["GOLF_TELEMETRY"] = "0"
+
+
+@app.command()
+def init(
+    project_name: str = typer.Argument(..., help="Name of the project to create"),
+    output_dir: Optional[Path] = typer.Option(
+        None, "--output-dir", "-o", help="Directory to create the project in"
+    ),
+    template: str = typer.Option(
+        "basic", "--template", "-t", help="Template to use (basic or advanced)"
+    ),
+) -> None:
+    """Initialize a new GolfMCP project.
+    
+    Creates a new directory with the project scaffold, including
+    examples for tools, resources, and prompts.
+    """
+    # Import here to avoid circular imports
+    from golf.commands.init import initialize_project
+    
+    # Use the current directory if no output directory is specified
+    if output_dir is None:
+        output_dir = Path.cwd() / project_name
+    
+    # Execute the initialization command
+    initialize_project(project_name=project_name, output_dir=output_dir, template=template)
+
+
+# Create a build group with subcommands
+build_app = typer.Typer(help="Build a standalone FastMCP application")
+app.add_typer(build_app, name="build")
+
+
+@build_app.command("dev")
+def build_dev(
+    output_dir: Optional[str] = typer.Option(
+        None, "--output-dir", "-o", help="Directory to output the built project"
+    )
+):
+    """Build a development version with environment variables copied."""
+    # Find project root directory
+    project_root, config_path = find_project_root()
+    
+    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.")
+        raise typer.Exit(code=1)
+    
+    # Load settings from the found project
+    settings = load_settings(project_root)
+    
+    # Set default output directory if not specified
+    if output_dir is None:
+        output_dir = project_root / "dist"
+    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)
+
+
+@build_app.command("prod")
+def build_prod(
+    output_dir: Optional[str] = typer.Option(
+        None, "--output-dir", "-o", help="Directory to output the built project"
+    )
+):
+    """Build a production version without copying environment variables."""
+    # Find project root directory
+    project_root, config_path = find_project_root()
+    
+    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.")
+        raise typer.Exit(code=1)
+    
+    # Load settings from the found project
+    settings = load_settings(project_root)
+    
+    # Set default output directory if not specified
+    if output_dir is None:
+        output_dir = project_root / "dist"
+    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)
+
+
+@app.command()
+def run(
+    dist_dir: Optional[str] = typer.Option(
+        None, "--dist-dir", "-d", help="Directory containing the built server"
+    ),
+    host: Optional[str] = typer.Option(
+        None, "--host", "-h", help="Host to bind to (overrides settings)"
+    ),
+    port: Optional[int] = typer.Option(
+        None, "--port", "-p", help="Port to bind to (overrides settings)"
+    ),
+    build_first: bool = typer.Option(
+        True, "--build/--no-build", help="Build the project before running"
+    ),
+):
+    """Run the built FastMCP server.
+    
+    This command runs the built server from the dist directory.
+    By default, it will build the project first if needed.
+    """
+    # Find project root directory
+    project_root, config_path = find_project_root()
+    
+    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.")
+        raise typer.Exit(code=1)
+    
+    # Load settings from the found project
+    settings = load_settings(project_root)
+    
+    # Set default dist directory if not specified
+    if dist_dir is None:
+        dist_dir = project_root / "dist"
+    else:
+        dist_dir = Path(dist_dir)
+    
+    # Check if dist directory exists
+    if not dist_dir.exists():
+        if build_first:
+            console.print(f"[yellow]Dist directory {dist_dir} not found. Building first...[/yellow]")
+            # Build the project
+            from golf.commands.build import build_project
+            build_project(project_root, settings, dist_dir)
+        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.")
+            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)
+
+
+if __name__ == "__main__":
+    # Show welcome banner when run directly
+    console.print(
+        Panel.fit(
+            f"[bold green]GolfMCP[/bold green] v{__version__}\n"
+            "[dim]A Pythonic framework for building MCP servers[/dim]",
+            border_style="green",
+        )
+    )
+    
+    # Run the CLI app
+    app() 

golf/commands/__init__.py

@@ -0,0 +1,3 @@
+"""GolfMCP command implementations."""
+
+from golf.commands import init, build, run 

golf/commands/build.py

@@ -0,0 +1,78 @@
+"""Build command for GolfMCP.
+
+This module implements the `golf build` command which generates a standalone
+FastMCP application from a GolfMCP project.
+"""
+
+from pathlib import Path
+import argparse
+
+from rich.console import Console
+
+from golf.core.config import Settings, load_settings
+from golf.core.builder import build_project as core_build_project
+
+console = Console()
+
+
+def build_project(
+    project_path: Path, 
+    settings: Settings, 
+    output_dir: Path,
+    build_env: str = "prod",
+    copy_env: bool = False
+) -> None:
+    """Build a standalone FastMCP application from a GolfMCP project.
+    
+    Args:
+        project_path: Path to the project root
+        settings: Project settings
+        output_dir: Directory to output the built project
+        build_env: Build environment ('dev' or 'prod')
+        copy_env: Whether to copy environment variables to the built app
+    """
+    # Call the centralized build function from core.builder
+    core_build_project(project_path, settings, output_dir, build_env=build_env, copy_env=copy_env)
+
+
+# Add a main section to run the build_project function when this module is executed directly
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Build a standalone FastMCP application")
+    parser.add_argument(
+        "--project-path", "-p", 
+        type=Path, 
+        default=Path.cwd(),
+        help="Path to the project root (default: current directory)"
+    )
+    parser.add_argument(
+        "--output-dir", "-o", 
+        type=Path, 
+        default=Path.cwd() / "dist",
+        help="Directory to output the built project (default: ./dist)"
+    )
+    parser.add_argument(
+        "--build-env",
+        type=str,
+        default="prod",
+        choices=["dev", "prod"],
+        help="Build environment to use (default: prod)"
+    )
+    parser.add_argument(
+        "--copy-env",
+        action="store_true",
+        help="Copy environment variables to the built application"
+    )
+    
+    args = parser.parse_args()
+    
+    # Load settings from the project path
+    settings = load_settings(args.project_path)
+    
+    # Execute the build
+    build_project(
+        args.project_path, 
+        settings, 
+        args.output_dir, 
+        build_env=args.build_env, 
+        copy_env=args.copy_env
+    ) 

golf/commands/init.py

@@ -0,0 +1,197 @@
+"""Project initialization command implementation."""
+
+import shutil
+from pathlib import Path
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.prompt import Confirm
+
+console = Console()
+
+
+def initialize_project(
+    project_name: str,
+    output_dir: Path,
+    template: str = "basic",
+) -> None:
+    """Initialize a new GolfMCP project with the specified template.
+    
+    Args:
+        project_name: Name of the project
+        output_dir: Directory where the project will be created
+        template: Template to use (basic or advanced)
+    """
+    # Validate template
+    if template not in ("basic", "advanced"):
+        console.print(f"[bold red]Error:[/bold red] Unknown template '{template}'")
+        console.print("Available templates: basic, advanced")
+        return
+    
+    # Check if directory exists
+    if output_dir.exists():
+        if not output_dir.is_dir():
+            console.print(
+                f"[bold red]Error:[/bold red] '{output_dir}' exists but is not a directory."
+            )
+            return
+        
+        # Check if directory is empty
+        if any(output_dir.iterdir()):
+            if not Confirm.ask(
+                f"Directory '{output_dir}' is not empty. Continue anyway?",
+                default=False,
+            ):
+                console.print("Initialization cancelled.")
+                return
+    else:
+        # Create the directory
+        output_dir.mkdir(parents=True)
+    
+    # Find template directory within the installed package
+    import golf
+    package_init_file = Path(golf.__file__)
+    # The 'examples' directory is now inside the 'golf' package directory
+    # e.g. golf/examples/basic, so go up one from __init__.py to get to 'golf'
+    template_dir = package_init_file.parent / "examples" / template
+    
+    if not template_dir.exists():
+        console.print(
+            f"[bold red]Error:[/bold red] Could not find template '{template}'"
+        )
+        return
+    
+    # Copy template files
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[bold green]Creating project structure...[/bold green]"),
+        transient=True,
+    ) as progress:
+        progress.add_task("copying", total=None)
+        
+        # Copy directory structure
+        _copy_template(template_dir, output_dir, project_name)
+    
+    # Create virtual environment
+    console.print("[bold green]Project initialized successfully![/bold green]")
+    console.print(f"\nTo get started, run:")
+    console.print(f"  cd {output_dir.name}")
+    console.print(f"  golf build dev")
+
+
+def _copy_template(source_dir: Path, target_dir: Path, project_name: str) -> None:
+    """Copy template files to the target directory, with variable substitution.
+    
+    Args:
+        source_dir: Source template directory
+        target_dir: Target project directory
+        project_name: Name of the project (for substitutions)
+    """
+    # Create standard directory structure
+    (target_dir / "tools").mkdir(exist_ok=True)
+    (target_dir / "resources").mkdir(exist_ok=True)
+    (target_dir / "prompts").mkdir(exist_ok=True)
+    
+    # Copy all files from the template
+    for source_path in source_dir.glob("**/*"):
+        # Skip if directory (we'll create directories as needed)
+        if source_path.is_dir():
+            continue
+        
+        # Compute relative path
+        rel_path = source_path.relative_to(source_dir)
+        target_path = target_dir / rel_path
+        
+        # Create parent directories if needed
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Copy and substitute content for text files
+        if _is_text_file(source_path):
+            with open(source_path, "r", encoding="utf-8") as f:
+                content = f.read()
+            
+            # Replace template variables
+            content = content.replace("{{project_name}}", project_name)
+            content = content.replace("{{project_name_lowercase}}", project_name.lower())
+            
+            with open(target_path, "w", encoding="utf-8") as f:
+                f.write(content)
+        else:
+            # Binary file, just copy
+            shutil.copy2(source_path, target_path)
+    
+    # Create .env file
+    env_file = target_dir / ".env"
+    with open(env_file, "w", encoding="utf-8") as f:
+        f.write(f"GOLF_NAME={project_name}\n")
+        f.write("GOLF_HOST=127.0.0.1\n")
+        f.write("GOLF_PORT=3000\n")
+    
+    # Create a .gitignore if it doesn't exist
+    gitignore_file = target_dir / ".gitignore"
+    if not gitignore_file.exists():
+        with open(gitignore_file, "w", encoding="utf-8") as f:
+            f.write("# Python\n")
+            f.write("__pycache__/\n")
+            f.write("*.py[cod]\n")
+            f.write("*$py.class\n")
+            f.write("*.so\n")
+            f.write(".Python\n")
+            f.write("env/\n")
+            f.write("build/\n")
+            f.write("develop-eggs/\n")
+            f.write("dist/\n")
+            f.write("downloads/\n")
+            f.write("eggs/\n")
+            f.write(".eggs/\n")
+            f.write("lib/\n")
+            f.write("lib64/\n")
+            f.write("parts/\n")
+            f.write("sdist/\n")
+            f.write("var/\n")
+            f.write("*.egg-info/\n")
+            f.write(".installed.cfg\n")
+            f.write("*.egg\n\n")
+            f.write("# Environment\n")
+            f.write(".env\n")
+            f.write(".venv\n")
+            f.write("env/\n")
+            f.write("venv/\n")
+            f.write("ENV/\n")
+            f.write("env.bak/\n")
+            f.write("venv.bak/\n\n")
+            f.write("# GolfMCP\n")
+            f.write(".golf/\n")
+            f.write("dist/\n")
+
+
+def _is_text_file(path: Path) -> bool:
+    """Check if a file is a text file that needs variable substitution.
+    
+    Args:
+        path: Path to check
+        
+    Returns:
+        True if the file is a text file
+    """
+    # List of known text file extensions
+    text_extensions = {
+        ".py", ".md", ".txt", ".html", ".css", ".js", ".json", 
+        ".yml", ".yaml", ".toml", ".ini", ".cfg", ".env", ".example"
+    }
+    
+    # Check if the file has a text extension
+    if path.suffix in text_extensions:
+        return True
+    
+    # Check specific filenames without extensions
+    if path.name in {".gitignore", "README", "LICENSE"}:
+        return True
+    
+    # Try to detect if it's a text file by reading a bit of it
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            f.read(1024)
+        return True
+    except UnicodeDecodeError:
+        return False 

golf/commands/run.py

@@ -0,0 +1,68 @@
+"""Command to run the built FastMCP server."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+
+from golf.core.config import Settings
+
+console = Console()
+
+
+def run_server(
+    project_path: Path,
+    settings: Settings,
+    dist_dir: Optional[Path] = None,
+    host: Optional[str] = None,
+    port: Optional[int] = None,
+) -> int:
+    """Run the built FastMCP server.
+    
+    Args:
+        project_path: Path to the project root
+        settings: Project settings
+        dist_dir: Path to the directory containing the built server (defaults to project_path/dist)
+        host: Host to bind the server to (overrides settings)
+        port: Port to bind the server to (overrides settings)
+        
+    Returns:
+        Process return code
+    """
+    # Set default dist directory if not specified
+    if dist_dir is None:
+        dist_dir = project_path / "dist"
+    
+    # Check if server file exists
+    server_path = dist_dir / "server.py"
+    if not server_path.exists():
+        console.print(f"[bold red]Error: Server file {server_path} not found.[/bold red]")
+        return 1
+    
+    # Prepare environment variables
+    env = os.environ.copy()
+    if host is not None:
+        env["HOST"] = host
+    elif settings.host:
+        env["HOST"] = settings.host
+        
+    if port is not None:
+        env["PORT"] = str(port)
+    elif settings.port:
+        env["PORT"] = str(settings.port)
+    
+    # Run the server
+    try:
+        # Using subprocess to properly handle signals (Ctrl+C)
+        process = subprocess.run(
+            [sys.executable, str(server_path)],
+            cwd=dist_dir,
+            env=env,
+        )
+        return process.returncode
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Server stopped by user[/yellow]")
+        return 0 

golf/core/__init__.py

@@ -0,0 +1 @@
+"""Core functionality for the GolfMCP framework."""