golf-mcp 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

golf/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.4"
+__version__ = "0.1.6"

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/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/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/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/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/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/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/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/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/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/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/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 

golf/examples/api_key/tools/issues/list.py

@@ -0,0 +1,87 @@
+"""List issues in a GitHub repository."""
+
+from typing import Annotated, List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+import httpx
+
+from golf.auth import get_api_key
+
+
+class Output(BaseModel):
+    """List of issues from the repository."""
+    issues: List[Dict[str, Any]]
+    total_count: int
+
+
+async def list(
+    repo: Annotated[str, Field(description="Repository name in format 'owner/repo'")],
+    state: Annotated[str, Field(description="Filter by state - 'open', 'closed', or 'all'")] = "open",
+    labels: Annotated[Optional[str], Field(description="Comma-separated list of label names to filter by")] = None,
+    per_page: Annotated[int, Field(description="Number of results per page (max 100)")] = 20
+) -> Output:
+    """List issues in a repository.
+    
+    Returns issues with their number, title, state, and other metadata.
+    Pull requests are filtered out from the results.
+    """
+    github_token = get_api_key()
+    
+    # Validate repo format
+    if '/' not in repo:
+        return Output(issues=[], total_count=0)
+    
+    url = f"https://api.github.com/repos/{repo}/issues"
+    
+    # Prepare headers
+    headers = {
+        "Accept": "application/vnd.github.v3+json",
+        "User-Agent": "Golf-GitHub-MCP-Server"
+    }
+    if github_token:
+        headers["Authorization"] = f"Bearer {github_token}"
+    
+    # Build query parameters
+    params = {
+        "state": state,
+        "per_page": min(per_page, 100)
+    }
+    if labels:
+        params["labels"] = labels
+    
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers=headers,
+                params=params,
+                timeout=10.0
+            )
+            
+            response.raise_for_status()
+            issues_data = response.json()
+            
+            # Filter out pull requests and format issues
+            issues = []
+            for issue in issues_data:
+                # Skip pull requests (they appear in issues endpoint too)
+                if "pull_request" in issue:
+                    continue
+                
+                issues.append({
+                    "number": issue["number"],
+                    "title": issue["title"],
+                    "body": issue.get("body", ""),
+                    "state": issue["state"],
+                    "url": issue["html_url"],
+                    "user": issue["user"]["login"],
+                    "labels": [label["name"] for label in issue.get("labels", [])]
+                })
+            
+            return Output(issues=issues, total_count=len(issues))
+            
+    except Exception:
+        return Output(issues=[], total_count=0)
+
+
+# Export the function to be used as the tool
+export = list 

golf/examples/api_key/tools/repos/list.py

@@ -0,0 +1,90 @@
+"""List GitHub repositories for a user or organization."""
+
+from typing import Annotated, List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+import httpx
+
+from golf.auth import get_api_key
+
+
+class Output(BaseModel):
+    """List of repositories."""
+    repositories: List[Dict[str, Any]]
+    total_count: int
+
+
+async def list(
+    username: Annotated[Optional[str], Field(description="GitHub username (lists public repos, or all repos if authenticated as this user)")] = None,
+    org: Annotated[Optional[str], Field(description="GitHub organization name (lists public repos, or all repos if authenticated member)")] = None,
+    sort: Annotated[str, Field(description="How to sort results - 'created', 'updated', 'pushed', 'full_name'")] = "updated",
+    per_page: Annotated[int, Field(description="Number of results per page (max 100)")] = 20
+) -> Output:
+    """List GitHub repositories.
+    
+    If neither username nor org is provided, lists repositories for the authenticated user.
+    """
+    # Get the GitHub token from the request context
+    github_token = get_api_key()
+    
+    # Determine the API endpoint
+    if org:
+        url = f"https://api.github.com/orgs/{org}/repos"
+    elif username:
+        url = f"https://api.github.com/users/{username}/repos"
+    else:
+        # List repos for authenticated user
+        if not github_token:
+            return Output(repositories=[], total_count=0)
+        url = "https://api.github.com/user/repos"
+    
+    # Prepare headers
+    headers = {
+        "Accept": "application/vnd.github.v3+json",
+        "User-Agent": "Golf-GitHub-MCP-Server"
+    }
+    if github_token:
+        headers["Authorization"] = f"Bearer {github_token}"
+    
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers=headers,
+                params={
+                    "sort": sort,
+                    "per_page": min(per_page, 100),
+                    "type": "all" if not username and not org else None
+                },
+                timeout=10.0
+            )
+            
+            response.raise_for_status()
+            repos_data = response.json()
+            
+            # Format repositories
+            repositories = []
+            for repo in repos_data:
+                repositories.append({
+                    "name": repo["name"],
+                    "full_name": repo["full_name"],
+                    "description": repo.get("description", ""),
+                    "private": repo.get("private", False),
+                    "stars": repo.get("stargazers_count", 0),
+                    "forks": repo.get("forks_count", 0),
+                    "language": repo.get("language", ""),
+                    "url": repo["html_url"]
+                })
+            
+            return Output(repositories=repositories, total_count=len(repositories))
+            
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code in [401, 404]:
+            return Output(repositories=[], total_count=0)
+        else:
+            return Output(repositories=[], total_count=0)
+    except Exception:
+        return Output(repositories=[], total_count=0)
+
+
+# Export the function to be used as the tool
+export = list 

golf/examples/api_key/tools/search/code.py

@@ -0,0 +1,93 @@
+"""Search GitHub code."""
+
+from typing import Annotated, List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+import httpx
+
+from golf.auth import get_api_key
+
+
+class Output(BaseModel):
+    """Code search results."""
+    results: List[Dict[str, Any]]
+    total_count: int
+
+
+async def search(
+    query: Annotated[str, Field(description="Search query (e.g., 'addClass', 'TODO', etc.)")],
+    language: Annotated[Optional[str], Field(description="Filter by programming language (e.g., 'python', 'javascript')")] = None,
+    repo: Annotated[Optional[str], Field(description="Search within a specific repository (format: 'owner/repo')")] = None,
+    org: Annotated[Optional[str], Field(description="Search within repositories of a specific organization")] = None,
+    per_page: Annotated[int, Field(description="Number of results per page (max 100)")] = 10
+) -> Output:
+    """Search for code on GitHub.
+    
+    Without authentication, you're limited to 10 requests per minute.
+    With authentication, you can make up to 30 requests per minute.
+    """
+    github_token = get_api_key()
+    
+    # Build the search query
+    search_parts = [query]
+    if language:
+        search_parts.append(f"language:{language}")
+    if repo:
+        search_parts.append(f"repo:{repo}")
+    if org:
+        search_parts.append(f"org:{org}")
+    
+    search_query = " ".join(search_parts)
+    
+    url = "https://api.github.com/search/code"
+    
+    # Prepare headers
+    headers = {
+        "Accept": "application/vnd.github.v3+json",
+        "User-Agent": "Golf-GitHub-MCP-Server"
+    }
+    if github_token:
+        headers["Authorization"] = f"Bearer {github_token}"
+    
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers=headers,
+                params={
+                    "q": search_query,
+                    "per_page": min(per_page, 100)
+                },
+                timeout=10.0
+            )
+            
+            if response.status_code == 403:
+                # Rate limit exceeded
+                return Output(results=[], total_count=0)
+            
+            response.raise_for_status()
+            data = response.json()
+            
+            # Format results
+            results = []
+            for item in data.get("items", []):
+                results.append({
+                    "name": item["name"],
+                    "path": item["path"],
+                    "repository": item["repository"]["full_name"],
+                    "url": item["html_url"],
+                    "score": item.get("score", 0.0)
+                })
+            
+            return Output(
+                results=results,
+                total_count=data.get("total_count", 0)
+            )
+            
+    except httpx.HTTPStatusError:
+        return Output(results=[], total_count=0)
+    except Exception:
+        return Output(results=[], total_count=0)
+
+
+# Export the function to be used as the tool
+export = search 

golf/examples/api_key/tools/users/get.py

@@ -0,0 +1,81 @@
+"""Get GitHub user information."""
+
+from typing import Annotated, Optional, Dict, Any
+from pydantic import BaseModel, Field
+import httpx
+
+from golf.auth import get_api_key
+
+
+class Output(BaseModel):
+    """User information result."""
+    found: bool
+    user: Optional[Dict[str, Any]] = None
+
+
+async def get(
+    username: Annotated[Optional[str], Field(description="GitHub username (if not provided, gets authenticated user)")] = None
+) -> Output:
+    """Get information about a GitHub user.
+    
+    If no username is provided, returns information about the authenticated user.
+    This is useful for testing if authentication is working correctly.
+    """
+    github_token = get_api_key()
+    
+    # Determine the API endpoint
+    if username:
+        url = f"https://api.github.com/users/{username}"
+    else:
+        # Get authenticated user - requires token
+        if not github_token:
+            return Output(found=False)
+        url = "https://api.github.com/user"
+    
+    # Prepare headers
+    headers = {
+        "Accept": "application/vnd.github.v3+json",
+        "User-Agent": "Golf-GitHub-MCP-Server"
+    }
+    if github_token:
+        headers["Authorization"] = f"Bearer {github_token}"
+    
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers=headers,
+                timeout=10.0
+            )
+            
+            response.raise_for_status()
+            user_data = response.json()
+            
+            return Output(
+                found=True,
+                user={
+                    "login": user_data["login"],
+                    "name": user_data.get("name", ""),
+                    "email": user_data.get("email", ""),
+                    "bio": user_data.get("bio", ""),
+                    "company": user_data.get("company", ""),
+                    "location": user_data.get("location", ""),
+                    "public_repos": user_data.get("public_repos", 0),
+                    "followers": user_data.get("followers", 0),
+                    "following": user_data.get("following", 0),
+                    "created_at": user_data["created_at"],
+                    "url": user_data["html_url"]
+                }
+            )
+            
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code in [401, 404]:
+            return Output(found=False)
+        else:
+            return Output(found=False)
+    except Exception:
+        return Output(found=False)
+
+
+# Export the function to be used as the tool
+export = get 

golf/examples/basic/golf.json

@@ -3,7 +3,5 @@
   "description": "A GolfMCP project",
   "host": "127.0.0.1",
   "port": 3000,
-  "transport": "sse",
-  "opentelemetry_enabled": false,
-  "opentelemetry_default_exporter": "console"
+  "transport": "sse"
 } 

golf/examples/basic/tools/hello.py

@@ -1,6 +1,7 @@
 """Hello World tool {{project_name}}."""
 
-from pydantic import BaseModel
+from typing import Annotated
+from pydantic import BaseModel, Field
 
 
 class Output(BaseModel):
@@ -10,8 +11,8 @@ class Output(BaseModel):
 
 
 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.
     

golf/examples/basic/tools/payments/charge.py

@@ -1,6 +1,7 @@
 """Charge payment tool"""
 
-from pydantic import BaseModel
+from typing import Annotated
+from pydantic import BaseModel, Field
 from .common import payment_client
 
 
@@ -13,9 +14,19 @@ class Output(BaseModel):
 
 
 async def charge(
-    amount: float,
-    card_token: str,
-    description: str = ""
+    amount: Annotated[float, Field(
+        description="Amount to charge in USD",
+        gt=0,  # Must be greater than 0
+        le=10000  # Maximum charge limit
+    )],
+    card_token: Annotated[str, Field(
+        description="Tokenized payment card identifier",
+        pattern=r"^tok_[a-zA-Z0-9]+$"  # Validate token format
+    )],
+    description: Annotated[str, Field(
+        description="Optional payment description for the charge",
+        max_length=200
+    )] = ""
 ) -> Output:
     """Process a payment charge.
     

golf/examples/basic/tools/payments/refund.py

@@ -1,6 +1,7 @@
 """Refund payment tool"""
 
-from pydantic import BaseModel
+from typing import Annotated, Optional
+from pydantic import BaseModel, Field
 from .common import payment_client
 
 
@@ -13,9 +14,20 @@ class Output(BaseModel):
 
 
 async def refund(
-    charge_id: str,
-    amount: float,
-    reason: str = "customer_request"
+    charge_id: Annotated[str, Field(
+        description="The ID of the charge to refund",
+        pattern=r"^ch_[a-zA-Z0-9]+$"
+    )],
+    amount: Annotated[Optional[float], Field(
+        description="Amount to refund in USD. If not specified, refunds the full charge amount",
+        gt=0,
+        default=None
+    )] = None,
+    reason: Annotated[str, Field(
+        description="Reason for the refund",
+        min_length=3,
+        max_length=200
+    )] = "Customer request"
 ) -> Output:
     """Process a payment refund.
     
@@ -23,15 +35,10 @@ async def refund(
     are grouped in subdirectories (tools/payments/refund.py).
     
     The resulting tool ID will be: refund-payments
-    
-    Args:
-        charge_id: Original charge ID to refund
-        amount: Amount to refund in USD
-        reason: Reason for refund
     """
     # The framework will add a context object automatically
     # You can log using regular print during development
-    print(f"Processing refund of ${amount:.2f} for charge {charge_id}...")
+    print(f"Processing refund for charge {charge_id}...")
     
     # Use the shared payment client from common.py
     refund_result = await payment_client.create_refund(
@@ -44,7 +51,7 @@ async def refund(
     return Output(
         success=True,
         refund_id=refund_result["id"],
-        message=f"Successfully refunded ${amount:.2f}"
-    ) 
+        message=f"Successfully refunded charge {charge_id}"
+    )
 
 export = refund

{golf_mcp-0.1.4.dist-info → golf_mcp-0.1.6.dist-info}/METADATA

@@ -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.6.dist-info/RECORD

@@ -0,0 +1,51 @@
+golf/__init__.py,sha256=l1lWRV5fzx6-C3xpWdEYCx3Y5TNykf_HgoEs12q6cfQ,21
+golf/auth/__init__.py,sha256=nh22WdganrEtp0YnxX1dmk6euuUFu8zh1BWxi1LGZnI,4107
+golf/auth/api_key.py,sha256=5UKmWZTs7sQ6bZ8baJjd-IITZNBwiExES0pVpq0-DEs,2049
+golf/auth/helpers.py,sha256=eKUIhdsaxa9bBtU6BaVZszTtS1ZV1v1fzvCkXV__9pM,2965
+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=yCgBe9aWKwBmPGOLDPFlkwKKc0U7_ULDK7Y8_WytAow,9835
+golf/commands/__init__.py,sha256=FRehcdCr0TrH_399w-PO9OzLhE7z2FVoCFAmfqHsYWo,83
+golf/commands/build.py,sha256=yhcUrK9gHnXNuLPZ2brcmtMgR8wXMBlEBcaBgTKkanI,2295
+golf/commands/init.py,sha256=I-fe7PBDX0vfKCLGXMppD7Uo03LzRbx-bCM2Mt3UzdU,7155
+golf/commands/run.py,sha256=dLrjmpypfvInDkA-KgEUyKrTvkvp59yea5tUyxk_Ej4,1989
+golf/core/__init__.py,sha256=RDSMAkB5NDaV7W5OFJ--miqv6JmvM3rI9ashndqM3X4,52
+golf/core/builder.py,sha256=SXJ4f4zAPlVtzreq9sQd0fMPWlLy8WkAUdfPY-aqG78,52798
+golf/core/builder_auth.py,sha256=y7cVqwbOqvhBOU67xCwtV5L-85b1E_Q3Khu91ilpUpU,11800
+golf/core/builder_telemetry.py,sha256=6ip4peRcb-RVZ6djorKW_VW6IiTCbnzOJYQm_YOMvpc,10189
+golf/core/config.py,sha256=gZ3eE8VIvDgIrLTizNq9XqkgfMkRg8Pm06gSVV51arA,6806
+golf/core/parser.py,sha256=sCVMWO7sGkSaKkU9LiHC3O9CTcrZxUbxnjdtwP7ne_o,19251
+golf/core/telemetry.py,sha256=mjkr6VaHABiu1SLyaFG6T8EfdvWjyNZVWY6FEWp-WHU,7385
+golf/core/transformer.py,sha256=3mr4_K4l1HZl1WQWSt9NKEhB5oi3b7kJnniseYEfrcI,5573
+golf/examples/__init__.py,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
+golf/examples/api_key/README.md,sha256=DIVcGwfs4FVXpk9R5gz1R-AvkzcLlNCZYEPTKlvWjCg,2235
+golf/examples/api_key/golf.json,sha256=iBSQWsazl6k7xdg1GhSJkzx4dANDjUp0WGFrI8M9Bug,180
+golf/examples/api_key/pre_build.py,sha256=N7q77CZwLnL8mgaPI6hXonjD-KX7RveaNMOHhzJ5EqY,407
+golf/examples/api_key/tools/issues/create.py,sha256=b58IadolStcuRxpRdTC_78Kfa4KCvMJSMvAlCouz-Y0,2832
+golf/examples/api_key/tools/issues/list.py,sha256=k2TGEgVCCTs0flHQFRqKQIA2zL39JTlTiUgAymW2gVg,2777
+golf/examples/api_key/tools/repos/list.py,sha256=4Z9ISphjhSZdJ3xqxmwbSo7UvkT368ZiSdyckOZqZnQ,3272
+golf/examples/api_key/tools/search/code.py,sha256=eXpJAmKq0am4oiCZm8vfz9d5NmyxjpnMPcEwrCf8vNo,3025
+golf/examples/api_key/tools/users/get.py,sha256=ifzqLxUr0dX00xscyjwuXCB3n48znu28DQU8MGUor50,2577
+golf/examples/basic/.env,sha256=CRh4u1yXPCbjjgUKUMUgw51aOBdVFEgY748z7WgfkVc,156
+golf/examples/basic/.env.example,sha256=gCTFcabTvr_-Rg3kTGmi63JQtCEOwMu4U5jTa1GM66U,123
+golf/examples/basic/README.md,sha256=-mY3R6AAnkXT9FPkALDrJtdf9IyKDvuqjsrLAMTLRYI,2663
+golf/examples/basic/golf.json,sha256=IcorojR67GaOZRrOj_XB6gyRXha7Jrwyc8IHtJM13DU,132
+golf/examples/basic/pre_build.py,sha256=VVYtBSCy4Xjg1Ocpl8ZwEr7VCVqPSSkDEzrTfQkAQKY,1037
+golf/examples/basic/prompts/welcome.py,sha256=LgT1eQewe0J08I5WFBv4RrgDr6yn4a4ww6XQ8k3sTVk,822
+golf/examples/basic/resources/current_time.py,sha256=KG28G5tpFGtGH2T5DHFAc-CwbYsFzE115xmGMVpi7fs,1176
+golf/examples/basic/resources/info.py,sha256=w4eLMapn9M4TN2dvXga5fudAnesFIyst-WgImxeApRQ,735
+golf/examples/basic/resources/weather/common.py,sha256=fmbeUm8DNSg4X48G9krPuv9WK7q42LRvbR4FTn2H3PU,1749
+golf/examples/basic/resources/weather/current.py,sha256=YC3QW5PQxFEWlEQid3pkowrhyqTF0coQDBj7V-M-WeQ,943
+golf/examples/basic/resources/weather/forecast.py,sha256=FpYmgUHjj8bDeWdaX0Lph_XE0QnXOOcI6nwMwB3zhBo,1000
+golf/examples/basic/tools/github_user.py,sha256=hLJ9C4ase7i8nUetLWvEVni8EOvsXZS0Ilhr-Ec0lcw,1975
+golf/examples/basic/tools/hello.py,sha256=wJjCYtWfRpTAcNKrlrRibm0UFKLnHFB1sGjR-q90GGk,867
+golf/examples/basic/tools/payments/charge.py,sha256=BxgHtVfZA3Z_QhT3OJisKyfGr3ZWBzd-jlgdwkvZaYM,1736
+golf/examples/basic/tools/payments/common.py,sha256=z5shSOZizUEnxBmGUSYghxmNwIvuhg-yfXKIfPWgV04,1292
+golf/examples/basic/tools/payments/refund.py,sha256=3auhKzuwPLgpoyUDz0p8lUWUY_fXNe0RYadQBxEvpB4,1603
+golf_mcp-0.1.6.dist-info/licenses/LICENSE,sha256=5_j2f6fTJmvfmUewzElhkpAaXg2grVoxKouOA8ihV6E,11348
+golf_mcp-0.1.6.dist-info/METADATA,sha256=8hibJN6yAw3457LxWZFwHSCIP95eTgQ2GfoWMO9GdRo,9442
+golf_mcp-0.1.6.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+golf_mcp-0.1.6.dist-info/entry_points.txt,sha256=5y7rHYM8jGpU-nfwdknCm5XsApLulqsnA37MO6BUTYg,43
+golf_mcp-0.1.6.dist-info/top_level.txt,sha256=BQToHcBUufdyhp9ONGMIvPE40jMEtmI20lYaKb4hxOg,5
+golf_mcp-0.1.6.dist-info/RECORD,,

golf_mcp-0.1.4.dist-info/RECORD

@@ -1,42 +0,0 @@
-golf/__init__.py,sha256=JMD28FXYHc_TM03visyUSd3UA9FZAaJMRStnfZoq50Y,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=TcFTqFAcFOl2SxPxHFc6jg8OLVtr92KhVZzabpJISNI,9836
-golf/commands/__init__.py,sha256=FRehcdCr0TrH_399w-PO9OzLhE7z2FVoCFAmfqHsYWo,83
-golf/commands/build.py,sha256=yhcUrK9gHnXNuLPZ2brcmtMgR8wXMBlEBcaBgTKkanI,2295
-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=gZ3eE8VIvDgIrLTizNq9XqkgfMkRg8Pm06gSVV51arA,6806
-golf/core/parser.py,sha256=sCVMWO7sGkSaKkU9LiHC3O9CTcrZxUbxnjdtwP7ne_o,19251
-golf/core/telemetry.py,sha256=KMp75b3hzHmE0PBcCZdsCihRi5c3zB8p6M16flY2As4,7399
-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=-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
-golf/examples/basic/resources/current_time.py,sha256=KG28G5tpFGtGH2T5DHFAc-CwbYsFzE115xmGMVpi7fs,1176
-golf/examples/basic/resources/info.py,sha256=w4eLMapn9M4TN2dvXga5fudAnesFIyst-WgImxeApRQ,735
-golf/examples/basic/resources/weather/common.py,sha256=fmbeUm8DNSg4X48G9krPuv9WK7q42LRvbR4FTn2H3PU,1749
-golf/examples/basic/resources/weather/current.py,sha256=YC3QW5PQxFEWlEQid3pkowrhyqTF0coQDBj7V-M-WeQ,943
-golf/examples/basic/resources/weather/forecast.py,sha256=FpYmgUHjj8bDeWdaX0Lph_XE0QnXOOcI6nwMwB3zhBo,1000
-golf/examples/basic/tools/github_user.py,sha256=hLJ9C4ase7i8nUetLWvEVni8EOvsXZS0Ilhr-Ec0lcw,1975
-golf/examples/basic/tools/hello.py,sha256=hJUMraxgi5g0gzhPbUZGOeAbiKZX4BTr1L64SE8ZZlw,706
-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.4.dist-info/licenses/LICENSE,sha256=5_j2f6fTJmvfmUewzElhkpAaXg2grVoxKouOA8ihV6E,11348
-golf_mcp-0.1.4.dist-info/METADATA,sha256=wcqXjcA6kPuNASE-OFzcLtvt9_g3S71mhqKfXZv5RFU,9390
-golf_mcp-0.1.4.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-golf_mcp-0.1.4.dist-info/entry_points.txt,sha256=5y7rHYM8jGpU-nfwdknCm5XsApLulqsnA37MO6BUTYg,43
-golf_mcp-0.1.4.dist-info/top_level.txt,sha256=BQToHcBUufdyhp9ONGMIvPE40jMEtmI20lYaKb4hxOg,5
-golf_mcp-0.1.4.dist-info/RECORD,,