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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: golf-mcp
-Version: 0.1.4
+Version: 0.1.6
 Summary: Framework for building MCP servers
 Author-email: Antoni Gmitruk <antoni@golf.dev>
 License-Expression: Apache-2.0
@@ -139,15 +139,16 @@ Creating a new tool is as simple as adding a Python file to the `tools/` directo
 # tools/hello.py
 """Hello World tool {{project_name}}."""
 
-from pydantic import BaseModel
+from typing import Annotated
+from pydantic import BaseModel, Field
 
 class Output(BaseModel):
     """Response from the hello tool."""
     message: str
 
 async def hello(
-    name: str = "World",
-    greeting: str = "Hello"
+    name: Annotated[str, Field(description="The name of the person to greet")] = "World",
+    greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello"
 ) -> Output:
     """Say hello to the given name.
     
@@ -188,9 +189,18 @@ The `golf.json` file is the heart of your Golf project configuration. Here's wha
   - `"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.
 
+## 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**
+
+
 ## 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:
+Golf collects **anonymous** usage data on the CLI 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)
@@ -218,23 +228,8 @@ You can disable telemetry in several ways:
    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.4 → golf_mcp-0.1.6}/README.md

@@ -101,15 +101,16 @@ Creating a new tool is as simple as adding a Python file to the `tools/` directo
 # tools/hello.py
 """Hello World tool {{project_name}}."""
 
-from pydantic import BaseModel
+from typing import Annotated
+from pydantic import BaseModel, Field
 
 class Output(BaseModel):
     """Response from the hello tool."""
     message: str
 
 async def hello(
-    name: str = "World",
-    greeting: str = "Hello"
+    name: Annotated[str, Field(description="The name of the person to greet")] = "World",
+    greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello"
 ) -> Output:
     """Say hello to the given name.
     
@@ -150,9 +151,18 @@ The `golf.json` file is the heart of your Golf project configuration. Here's wha
   - `"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.
 
+## 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**
+
+
 ## 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:
+Golf collects **anonymous** usage data on the CLI 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)
@@ -180,23 +190,8 @@ You can disable telemetry in several ways:
    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.4 → golf_mcp-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "golf-mcp"
-version = "0.1.4"
+version = "0.1.6"
 description = "Framework for building MCP servers"
 authors = [
     {name = "Antoni Gmitruk", email = "antoni@golf.dev"}
@@ -64,7 +64,7 @@ golf = ["examples/**/*"]
 
 [tool.poetry]
 name = "golf-mcp"
-version = "0.1.4"
+version = "0.1.6"
 description = "Framework for building MCP servers with zero boilerplate"
 authors = ["Antoni Gmitruk <antoni@golf.dev>"]
 license = "Apache-2.0"

golf_mcp-0.1.6/src/golf/__init__.py

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

{golf_mcp-0.1.4 → golf_mcp-0.1.6}/src/golf/auth/__init__.py

@@ -11,7 +11,8 @@ from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
 
 from .provider import ProviderConfig
 from .oauth import GolfOAuthProvider, create_callback_handler
-from .helpers import get_access_token, get_provider_token, extract_token_from_header
+from .helpers import get_access_token, get_provider_token, extract_token_from_header, get_api_key, set_api_key
+from .api_key import configure_api_key, get_api_key_config, is_api_key_configured
 
 class AuthConfig:
     """Configuration for OAuth authentication in GolfMCP."""

golf_mcp-0.1.6/src/golf/auth/api_key.py

@@ -0,0 +1,73 @@
+"""API Key authentication support for Golf MCP servers.
+
+This module provides a simple API key pass-through mechanism for Golf servers,
+allowing tools to access API keys from request headers and forward them to
+upstream services.
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class ApiKeyConfig(BaseModel):
+    """Configuration for API key authentication."""
+    
+    header_name: str = Field(
+        "X-API-Key",
+        description="Name of the header containing the API key"
+    )
+    header_prefix: str = Field(
+        "",
+        description="Optional prefix to strip from the header value (e.g., 'Bearer ')"
+    )
+
+
+# Global configuration storage
+_api_key_config: Optional[ApiKeyConfig] = None
+
+
+def configure_api_key(
+    header_name: str = "X-API-Key",
+    header_prefix: str = ""
+) -> None:
+    """Configure API key extraction from request headers.
+    
+    This function should be called in pre_build.py to set up API key handling.
+    
+    Args:
+        header_name: Name of the header containing the API key (default: "X-API-Key")
+        header_prefix: Optional prefix to strip from the header value (e.g., "Bearer ")
+        case_sensitive: Whether header name matching should be case-sensitive
+        
+    Example:
+        # In pre_build.py
+        from golf.auth.api_key import configure_api_key
+        
+        configure_api_key(
+            header_name="Authorization",
+            header_prefix="Bearer "
+        )
+    """
+    global _api_key_config
+    _api_key_config = ApiKeyConfig(
+        header_name=header_name,
+        header_prefix=header_prefix
+    )
+
+
+def get_api_key_config() -> Optional[ApiKeyConfig]:
+    """Get the current API key configuration.
+    
+    Returns:
+        The API key configuration if set, None otherwise
+    """
+    return _api_key_config
+
+
+def is_api_key_configured() -> bool:
+    """Check if API key authentication is configured.
+    
+    Returns:
+        True if API key authentication is configured, False otherwise
+    """
+    return _api_key_config is not None 

{golf_mcp-0.1.4 → golf_mcp-0.1.6}/src/golf/auth/helpers.py

@@ -1,19 +1,26 @@
 """Helper functions for working with authentication in MCP context."""
 
 from typing import Optional
+from contextvars import ContextVar
 
 # Re-export get_access_token from the MCP SDK
 from mcp.server.auth.middleware.auth_context import get_access_token
 
-_active_golf_oauth_provider = None
+from .oauth import GolfOAuthProvider
 
-def _set_active_golf_oauth_provider(provider_instance) -> None:
+# Context variable to store the active OAuth provider
+_active_golf_oauth_provider: Optional[GolfOAuthProvider] = None
+
+# Context variable to store the current request's API key
+_current_api_key: ContextVar[Optional[str]] = ContextVar('current_api_key', default=None)
+
+def _set_active_golf_oauth_provider(provider: GolfOAuthProvider) -> None:
     """
     Sets the active GolfOAuthProvider instance.
     Should only be called once during server startup.
     """
     global _active_golf_oauth_provider
-    _active_golf_oauth_provider = provider_instance
+    _active_golf_oauth_provider = provider
 
 def get_provider_token() -> Optional[str]:
     """
@@ -53,4 +60,38 @@ def extract_token_from_header(auth_header: str) -> Optional[str]:
     if len(parts) != 2 or parts[0].lower() != 'bearer':
         return None
 
-    return parts[1] 
+    return parts[1]
+
+def set_api_key(api_key: Optional[str]) -> None:
+    """Set the API key for the current request context.
+    
+    This is an internal function used by the middleware.
+    
+    Args:
+        api_key: The API key to store in the context
+    """
+    _current_api_key.set(api_key)
+
+def get_api_key() -> Optional[str]:
+    """Get the API key from the current request context.
+    
+    This function should be used in tools to retrieve the API key
+    that was sent in the request headers.
+    
+    Returns:
+        The API key if available, None otherwise
+        
+    Example:
+        # In a tool file
+        from golf.auth import get_api_key
+        
+        async def call_api():
+            api_key = get_api_key()
+            if not api_key:
+                return {"error": "No API key provided"}
+            
+            # Use the API key in your request
+            headers = {"Authorization": f"Bearer {api_key}"}
+            ...
+    """
+    return _current_api_key.get() 

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

@@ -69,7 +69,7 @@ def init(
         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)"
+        "basic", "--template", "-t", help="Template to use (basic or api_key)"
     ),
 ) -> None:
     """Initialize a new GolfMCP project.

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

@@ -24,12 +24,13 @@ def initialize_project(
     Args:
         project_name: Name of the project
         output_dir: Directory where the project will be created
-        template: Template to use (basic or advanced)
+        template: Template to use (basic or api_key)
     """
     # Validate template
-    if template not in ("basic", "advanced"):
+    valid_templates = ("basic", "api_key")
+    if template not in valid_templates:
         console.print(f"[bold red]Error:[/bold red] Unknown template '{template}'")
-        console.print("Available templates: basic, advanced")
+        console.print(f"Available templates: {', '.join(valid_templates)}")
         track_event("cli_init_failed", {"success": False})
         return
     

{golf_mcp-0.1.4 → golf_mcp-0.1.6}/src/golf/core/builder.py

@@ -624,7 +624,10 @@ class CodeGenerator:
                         registration += f"\nmcp.add_tool({full_module_path}.{component.entry_function}"
                     else:
                         registration += f"\nmcp.add_tool({full_module_path}.export"
-                        
+                    
+                    # Add the name parameter
+                    registration += f", name=\"{component.name}\""
+                    
                     # Add description from docstring
                     if component.docstring:
                         # Escape any quotes in the docstring
@@ -640,6 +643,9 @@ class CodeGenerator:
                         registration += f"\nmcp.add_resource_fn({full_module_path}.{component.entry_function}, uri=\"{component.uri_template}\""
                     else:
                         registration += f"\nmcp.add_resource_fn({full_module_path}.export, uri=\"{component.uri_template}\""
+                    
+                    # Add the name parameter
+                    registration += f", name=\"{component.name}\""
                         
                     # Add description from docstring
                     if component.docstring:
@@ -656,6 +662,9 @@ class CodeGenerator:
                         registration += f"\nmcp.add_prompt({full_module_path}.{component.entry_function}"
                     else:
                         registration += f"\nmcp.add_prompt({full_module_path}.export"
+                    
+                    # Add the name parameter
+                    registration += f", name=\"{component.name}\""
                         
                     # Add description from docstring
                     if component.docstring:

{golf_mcp-0.1.4 → golf_mcp-0.1.6}/src/golf/core/builder_auth.py

@@ -5,12 +5,19 @@ into the generated FastMCP application during the build process.
 """
 
 from golf.auth import get_auth_config
+from golf.auth.api_key import get_api_key_config
 
 
 def generate_auth_code(server_name: str, host: str = "127.0.0.1", port: int = 3000, https: bool = False) -> str:
     """Generate code for setting up authentication in the FastMCP app.
     This code string will be injected into the generated server.py and executed at its runtime.
     """
+    # Check for API key configuration first
+    api_key_config = get_api_key_config()
+    if api_key_config:
+        return generate_api_key_auth_code(server_name)
+    
+    # Otherwise check for OAuth configuration
     original_provider_config, required_scopes_from_config = get_auth_config()
     
     if not original_provider_config:
@@ -114,10 +121,67 @@ def generate_auth_code(server_name: str, host: str = "127.0.0.1", port: int = 30
     return "\n".join(generated_code_lines)
 
 
+def generate_api_key_auth_code(server_name: str) -> str:
+    """Generate code for API key authentication middleware."""
+    api_key_config = get_api_key_config()
+    if not api_key_config:
+        return f"mcp = FastMCP({repr(server_name)}) # No API key authentication configured"
+    
+    generated_code_lines = []
+    
+    # Imports
+    generated_code_lines.extend([
+        "# API key authentication setup",
+        "from golf.auth.helpers import set_api_key",
+        "from golf.auth.api_key import get_api_key_config",
+        "from starlette.middleware.base import BaseHTTPMiddleware",
+        "from starlette.requests import Request",
+        "",
+        f"mcp = FastMCP({repr(server_name)})",
+        "",
+        "# Middleware to extract API key from headers",
+        "class ApiKeyMiddleware(BaseHTTPMiddleware):",
+        "    async def dispatch(self, request: Request, call_next):",
+        "        api_key_config = get_api_key_config()",
+        "        if api_key_config:",
+        "            # Extract API key from the configured header",
+        "            header_name = api_key_config.header_name",
+        "            header_prefix = api_key_config.header_prefix",
+        "            ",
+        "            # Case-insensitive header lookup",
+        "            api_key = None",
+        "            for k, v in request.headers.items():",
+        "                if k.lower() == header_name.lower():",
+        "                    api_key = v",
+        "                    break",
+        "            ",
+        "            # Strip prefix if configured and present",
+        "            if api_key and header_prefix and api_key.startswith(header_prefix):",
+        "                api_key = api_key[len(header_prefix):]",
+        "            ",
+        "            # Store the API key in context for tools to access",
+        "            set_api_key(api_key)",
+        "        ",
+        "        # Continue with the request",
+        "        response = await call_next(request)",
+        "        return response",
+        "",
+        "# Add the middleware to the FastMCP app",
+        "mcp.app.add_middleware(ApiKeyMiddleware)",
+    ])
+    
+    return "\n".join(generated_code_lines)
+
+
 def generate_auth_routes() -> str:
     """Generate code for OAuth routes in the FastMCP app.
     These routes are added to the FastMCP instance (`mcp`) created by `generate_auth_code`.
     """
+    # API key auth doesn't need special routes
+    api_key_config = get_api_key_config()
+    if api_key_config:
+        return ""
+    
     provider_config, _ = get_auth_config() # Used to check if auth is enabled generally
     if not provider_config:
         return ""

{golf_mcp-0.1.4 → golf_mcp-0.1.6}/src/golf/core/telemetry.py

@@ -17,7 +17,7 @@ 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
+DEFAULT_POSTHOG_API_KEY = "phc_7ccsDDxoC5tK5hodlrs2moGC74cThRzcN63flRYPWGl"
 POSTHOG_API_KEY = os.environ.get("GOLF_POSTHOG_API_KEY", DEFAULT_POSTHOG_API_KEY)
 POSTHOG_HOST = "https://us.i.posthog.com"
 
@@ -156,8 +156,8 @@ def initialize_telemetry() -> None:
     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:
+    # Skip initialization if no valid API key (empty or placeholder)
+    if not POSTHOG_API_KEY or POSTHOG_API_KEY.startswith("phc_YOUR"):
         return
     
     try:
@@ -183,8 +183,8 @@ def track_event(event_name: str, properties: Optional[Dict[str, Any]] = None) ->
     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:
+    # Skip if no valid API key (empty or placeholder)
+    if not POSTHOG_API_KEY or POSTHOG_API_KEY.startswith("phc_YOUR"):
         return
     
     try:

golf_mcp-0.1.6/src/golf/examples/api_key/README.md

@@ -0,0 +1,70 @@
+# GitHub MCP Server with API Key Authentication
+
+This example demonstrates how to build a GitHub API MCP server using Golf's API key authentication feature. The server wraps common GitHub operations and passes through authentication tokens from MCP clients to the GitHub API.
+
+## Features
+
+This MCP server provides tools for:
+
+- **Repository Management** 
+  - `list-repos` - List repositories for users, organizations, or the authenticated user
+  
+- **Issue Management** 
+  - `create-issues` - Create new issues with labels
+  - `list-issues` - List and filter issues by state and labels
+  
+- **Code Search**
+  - `code-search` - Search for code across GitHub with language and repository filters
+  
+- **User Information**
+  - `get-users` - Get user profiles or verify authentication
+
+## Tool Naming Convention
+
+Golf automatically derives tool names from the file structure:
+- `tools/issues/create.py` → `create-issues`
+- `tools/issues/list.py` → `list-issues`
+- `tools/repos/list.py` → `list-repos`
+- `tools/search/code.py` → `code-search`
+- `tools/users/get.py` → `get-users`
+
+## Configuration
+
+The server is configured in `pre_build.py` to extract GitHub tokens from the `Authorization` header:
+
+```python
+configure_api_key(
+    header_name="Authorization",
+    header_prefix="Bearer "
+)
+```
+
+This configuration handles GitHub's token format: `Authorization: Bearer ghp_xxxxxxxxxxxx`
+
+## How It Works
+
+1. **Client sends request** with GitHub token in the Authorization header
+2. **Golf middleware** extracts the token based on your configuration
+3. **Tools retrieve token** using `get_api_key()` 
+4. **Token is forwarded** to GitHub API in the appropriate format
+5. **GitHub validates** the token and returns results
+
+## Running the Server
+
+1. Build and run:
+   ```bash
+   golf build dev
+   golf run
+   ```
+
+2. The server will start on `http://127.0.0.1:3000` (configurable in `golf.json`)
+
+
+## GitHub Token Permissions
+
+Depending on which tools you use, you'll need different token permissions:
+
+- **Public repositories**: No token needed for read-only access
+- **Private repositories**: Token with `repo` scope
+- **Creating issues**: Token with `repo` or `public_repo` scope
+- **User information**: Token with `user` scope

golf_mcp-0.1.6/src/golf/examples/api_key/golf.json

@@ -0,0 +1,7 @@
+{
+  "name": "github-mcp-server",
+  "description": "MCP server for GitHub API operations with API key authentication",
+  "host": "127.0.0.1",
+  "port": 3000,
+  "transport": "sse"
+} 

golf_mcp-0.1.6/src/golf/examples/api_key/pre_build.py

@@ -0,0 +1,10 @@
+"""Configure API key authentication for GitHub MCP server."""
+
+from golf.auth import configure_api_key
+
+# Configure Golf to extract GitHub personal access tokens from the Authorization header
+# GitHub expects: Authorization: Bearer ghp_xxxx or Authorization: token ghp_xxxx
+configure_api_key(
+    header_name="Authorization",
+    header_prefix="Bearer "  # Will handle both "Bearer " and "token " prefixes
+)

golf_mcp-0.1.6/src/golf/examples/api_key/tools/issues/create.py

@@ -0,0 +1,94 @@
+"""Create a new issue in a GitHub repository."""
+
+from typing import Annotated, List, Optional
+from pydantic import BaseModel, Field
+import httpx
+
+from golf.auth import get_api_key
+
+
+class Output(BaseModel):
+    """Response from creating an issue."""
+    success: bool
+    issue_number: Optional[int] = None
+    issue_url: Optional[str] = None
+    error: Optional[str] = None
+
+
+async def create(
+    repo: Annotated[str, Field(description="Repository name in format 'owner/repo'")],
+    title: Annotated[str, Field(description="Issue title")],
+    body: Annotated[str, Field(description="Issue description/body (supports Markdown)")] = "",
+    labels: Annotated[Optional[List[str]], Field(description="List of label names to apply")] = None
+) -> Output:
+    """Create a new issue.
+    
+    Requires authentication with appropriate permissions.
+    """
+    github_token = get_api_key()
+    
+    if not github_token:
+        return Output(
+            success=False,
+            error="Authentication required. Please provide a GitHub token."
+        )
+    
+    # Validate repo format
+    if '/' not in repo:
+        return Output(
+            success=False,
+            error="Repository must be in format 'owner/repo'"
+        )
+    
+    url = f"https://api.github.com/repos/{repo}/issues"
+    
+    # Build request payload
+    payload = {
+        "title": title,
+        "body": body
+    }
+    if labels:
+        payload["labels"] = labels
+    
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url,
+                headers={
+                    "Authorization": f"Bearer {github_token}",
+                    "Accept": "application/vnd.github.v3+json",
+                    "User-Agent": "Golf-GitHub-MCP-Server"
+                },
+                json=payload,
+                timeout=10.0
+            )
+            
+            response.raise_for_status()
+            issue_data = response.json()
+            
+            return Output(
+                success=True,
+                issue_number=issue_data["number"],
+                issue_url=issue_data["html_url"]
+            )
+            
+    except httpx.HTTPStatusError as e:
+        error_messages = {
+            401: "Invalid or missing authentication token",
+            403: "Insufficient permissions to create issues in this repository",
+            404: "Repository not found",
+            422: "Invalid request data"
+        }
+        return Output(
+            success=False,
+            error=error_messages.get(e.response.status_code, f"GitHub API error: {e.response.status_code}")
+        )
+    except Exception as e:
+        return Output(
+            success=False,
+            error=f"Failed to create issue: {str(e)}"
+        )
+
+
+# Export the function to be used as the tool
+export = create