golf-mcp 0.1.19__py3-none-any.whl → 0.2.0__py3-none-any.whl

golf/auth/provider.py

@@ -1,115 +0,0 @@
-"""OAuth provider configuration for GolfMCP authentication.
-
-This module defines the ProviderConfig class used to configure
-OAuth authentication for GolfMCP servers.
-"""
-
-from typing import 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: str | None = Field(
-        None, description="OAuth client ID (resolved at runtime)"
-    )
-    client_secret: str | None = 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: str | None = Field(
-        None, description="User info endpoint URL (for OIDC providers)"
-    )
-
-    jwks_uri: str | None = 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: str | None = 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: str | None = 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/examples/api_key/.env

@@ -1,2 +0,0 @@
-OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
-OTEL_SERVICE_NAME="golf-mcp"

golf/examples/api_key/.env.example

@@ -1 +0,0 @@
-#GOLF_API_KEY=<your-api-key>

golf/examples/api_key/README.md

@@ -1,84 +0,0 @@
-# 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 ",
-    required=True  # Reject requests without a valid API key
-)
-```
-
-This configuration:
-- Handles GitHub's token format: `Authorization: Bearer ghp_xxxxxxxxxxxx`
-- **Enforces authentication**: When `required=True` (default), requests without a valid API key will be rejected with a 401 Unauthorized error
-- For optional authentication (pass-through mode), set `required=False`
-
-## How It Works
-
-1. **Client sends request** with GitHub token in the Authorization header
-2. **Golf middleware** checks if API key is required and present
-3. **If required and missing**, the request is rejected with 401 Unauthorized
-4. **If present**, the token is extracted based on your configuration
-5. **Tools retrieve token** using `get_api_key()` 
-6. **Token is forwarded** to GitHub API in the appropriate format
-7. **GitHub validates** the token and returns results
-
-## Running the Server
-
-1. Build and run:
-   ```bash
-   golf build
-   golf run
-   ```
-
-2. The server will start on `http://127.0.0.1:3000` (configurable in `golf.json`)
-
-3. Test authentication enforcement:
-   ```bash
-   # This will fail with 401 Unauthorized
-   curl http://localhost:3000/mcp
-   
-   # This will succeed
-   curl -H "Authorization: Bearer ghp_your_token_here" http://localhost:3000/mcp
-   ```
-
-## 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

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

golf/examples/api_key/pre_build.py

@@ -1,11 +0,0 @@
-"""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
-    required=True,  # Reject requests without a valid API key
-)

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

@@ -1,93 +0,0 @@
-"""Create a new issue in a GitHub repository."""
-
-from typing import Annotated
-
-import httpx
-from pydantic import BaseModel, Field
-
-from golf.auth import get_api_key
-
-
-class Output(BaseModel):
-    """Response from creating an issue."""
-
-    success: bool
-    issue_number: int | None = None
-    issue_url: str | None = None
-    error: str | None = 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[
-        list[str] | None, 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

@@ -1,92 +0,0 @@
-"""List issues in a GitHub repository."""
-
-from typing import Annotated, Any
-
-import httpx
-from pydantic import BaseModel, Field
-
-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[
-        str | None,
-        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

@@ -1,111 +0,0 @@
-"""List GitHub repositories for a user or organization."""
-
-from typing import Annotated, Any
-
-import httpx
-from pydantic import BaseModel, Field
-
-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[
-        str | None,
-        Field(
-            description="GitHub username (lists public repos, or all repos if authenticated as this user)"
-        ),
-    ] = None,
-    org: Annotated[
-        str | None,
-        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

@@ -1,106 +0,0 @@
-"""Search GitHub code."""
-
-from typing import Annotated, Any
-
-import httpx
-from pydantic import BaseModel, Field
-
-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[
-        str | None,
-        Field(
-            description="Filter by programming language (e.g., 'python', 'javascript')"
-        ),
-    ] = None,
-    repo: Annotated[
-        str | None,
-        Field(description="Search within a specific repository (format: 'owner/repo')"),
-    ] = None,
-    org: Annotated[
-        str | None,
-        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