golf-mcp 0.1.0__py3-none-any.whl

golf/examples/basic/README.md

@@ -0,0 +1,117 @@
+# {{project_name}}
+
+A GolfMCP project that provides MCP-compatible tools, resources, and prompts.
+
+## Getting Started
+
+This project is built with [GolfMCP](https://github.com/yourusername/golfmcp), a Python framework for building MCP servers with zero boilerplate.
+
+To start the development server with hot reload:
+
+```bash
+golf dev
+```
+
+This will watch for file changes and automatically reload the server.
+
+## Project Structure
+
+- `tools/` - Tool implementations (functions an LLM can call)
+- `resources/` - Resource implementations (data an LLM can read)
+- `prompts/` - Prompt templates (conversations an LLM can use)
+- `golf.json` - Configuration file with settings like telemetry and transport
+
+## Adding New Components
+
+### Tools
+
+To add a new tool, create a Python file in the `tools/` directory:
+
+```python
+# tools/my_tool.py
+from pydantic import BaseModel
+from fastmcp import Context
+
+class Input(BaseModel):
+    param1: str
+    param2: int = 42
+
+class Output(BaseModel):
+    result: str
+
+async def run(input: Input, ctx: Context) -> Output:
+    """Description of what my tool does."""
+    await ctx.info(f"Processing {input.param1}...")
+    return MyOutput(result=f"Processed {input.param1} with {input.param2}")
+```
+
+### Resources
+
+To add a new resource, create a Python file in the `resources/` directory:
+
+```python
+# resources/my_data.py
+resource_uri = "data://my-data"
+
+async def run() -> dict:
+    """Description of the resource."""
+    return {
+        "title": "My Data",
+        "content": "Some valuable information"
+    }
+```
+
+### Sharing Functionality with common.py
+
+For directories with multiple related components (like `tools/payments/` or `resources/weather/`), 
+use a `common.py` file to share functionality:
+
+```python
+# tools/payments/common.py
+class PaymentClient:
+    """Shared payment client implementation."""
+    # Implementation details...
+
+# Create a shared client instance
+payment_client = PaymentClient()
+```
+
+Then import and use the shared functionality in your components:
+
+```python
+# tools/payments/charge.py
+from .common import payment_client
+
+async def run(input):
+    result = await payment_client.create_charge(...)
+    # Rest of implementation...
+```
+
+This pattern helps organize shared code and makes it easier to build and maintain your project.
+
+## Telemetry
+
+This project includes OpenTelemetry integration for tracing server requests:
+
+```json
+// golf.json
+{
+  "telemetry": true,
+  "telemetry_exporter": "console"  // or "otlp_http"
+}
+```
+
+You can configure it with environment variables:
+- `OTEL_SERVICE_NAME`: Set service name (defaults to app name)
+- `OTEL_TRACES_EXPORTER`: Exporter type ("console" or "otlp_http")
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP exporter endpoint URL
+
+## Deployment
+
+To build the project for deployment:
+
+```bash
+golf build
+```
+
+This creates a standalone FastMCP application in the `dist/` directory. 

golf/examples/basic/golf.json

@@ -0,0 +1,9 @@
+{
+  "name": "{{project_name}}",
+  "description": "A GolfMCP project",
+  "host": "127.0.0.1",
+  "port": 3000,
+  "transport": "sse",
+  "opentelemetry_enabled": false,
+  "opentelemetry_default_exporter": "console"
+} 

golf/examples/basic/pre_build.py

@@ -0,0 +1,28 @@
+"""Pre-build configuration for the basic example.
+
+This file is executed before the build process starts.
+It configures GitHub OAuth authentication for the example.
+"""
+
+from golf.auth import ProviderConfig, configure_auth
+
+# Create GitHub OAuth provider configuration
+github_provider = ProviderConfig(
+    provider="github",
+    client_id_env_var="GITHUB_CLIENT_ID",
+    client_secret_env_var="GITHUB_CLIENT_SECRET",
+    jwt_secret_env_var="JWT_SECRET",
+    authorize_url="https://github.com/login/oauth/authorize",
+    token_url="https://github.com/login/oauth/access_token",
+    userinfo_url="https://api.github.com/user",
+    scopes=["read:user", "user:email"],
+    issuer_url="http://127.0.0.1:3000", # This should be your Golf server's accessible URL
+    callback_path="/auth/callback",     # Golf's callback path
+    token_expiration=3600  # 1 hour
+)
+
+# Configure authentication with the provider
+configure_auth(
+    provider=github_provider,
+    required_scopes=["read:user"],  # Require read:user scope for protected endpoints
+)

golf/examples/basic/prompts/welcome.py

@@ -0,0 +1,30 @@
+"""Welcome prompt for new users."""
+
+from typing import List, Dict
+
+
+async def welcome() -> List[Dict]:
+    """Provide a welcome prompt for new users.
+    
+    This is a simple example prompt that demonstrates how to define
+    a prompt template in GolfMCP.
+    """
+    return [
+        {
+            "role": "system",
+            "content": (
+                "You are an assistant for the {{project_name}} application. "
+                "You help users understand how to interact with this system and its capabilities."
+            )
+        },
+        {
+            "role": "user",
+            "content": (
+                "Welcome to {{project_name}}! This is a project built with GolfMCP. "
+                "How can I get started?"
+            )
+        },
+    ]
+
+# Designate the entry point function
+export = welcome 

golf/examples/basic/resources/current_time.py

@@ -0,0 +1,41 @@
+"""Current time resource example."""
+
+from datetime import datetime
+from typing import Dict, Any
+
+# The URI that clients will use to access this resource
+resource_uri = "system://time/{format}"
+
+
+async def current_time(format: str = "full") -> Dict[str, Any]:
+    """Provide the current time in various formats.
+    
+    This is a simple resource example that accepts a format parameter.
+    
+    Args:
+        format: The format to return ('full', 'iso', 'unix' or 'rfc')
+    """
+    now = datetime.now()
+    
+    # Prepare all possible formats
+    all_formats = {
+        "iso": now.isoformat(),
+        "rfc": now.strftime("%a, %d %b %Y %H:%M:%S %z"),
+        "unix": int(now.timestamp()),
+        "formatted": {
+            "date": now.strftime("%Y-%m-%d"),
+            "time": now.strftime("%H:%M:%S"),
+            "timezone": now.astimezone().tzname()
+        }
+    }
+    
+    # Return specific format or all formats
+    if format == "full":
+        return all_formats
+    elif format in all_formats:
+        return {format: all_formats[format]}
+    else:
+        return {"error": f"Unknown format: {format}"}
+
+# Designate the entry point function
+export = current_time 

golf/examples/basic/resources/info.py

@@ -0,0 +1,27 @@
+"""Example resource that provides information about the project."""
+
+import platform
+from datetime import datetime
+from typing import Dict, Any
+
+resource_uri = "info://system"
+
+
+async def info() -> Dict[str, Any]:
+    """Provide system information as a resource.
+    
+    This is a simple example resource that demonstrates how to expose
+    data to an LLM client through the MCP protocol.
+    """
+    return {
+        "project": "{{project_name}}",
+        "timestamp": datetime.now().isoformat(),
+        "platform": {
+            "system": platform.system(),
+            "python_version": platform.python_version(),
+            "architecture": platform.machine(),
+        }
+    }
+
+# Designate the entry point function
+export = info 

golf/examples/basic/resources/weather/common.py

@@ -0,0 +1,48 @@
+"""Weather shared functionality.
+
+This common.py file demonstrates the recommended pattern for 
+sharing functionality across multiple resources in a directory.
+"""
+
+import os
+
+# Read configuration from environment variables
+WEATHER_API_KEY = os.environ.get("WEATHER_API_KEY", "mock_key")
+WEATHER_API_URL = os.environ.get("WEATHER_API_URL", "https://api.example.com/weather")
+TEMPERATURE_UNIT = os.environ.get("WEATHER_TEMP_UNIT", "fahrenheit")
+
+
+class WeatherApiClient:
+    """Mock weather API client."""
+    
+    def __init__(self, api_key: str = WEATHER_API_KEY, api_url: str = WEATHER_API_URL):
+        self.api_key = api_key
+        self.api_url = api_url
+        self.unit = TEMPERATURE_UNIT
+    
+    async def get_forecast(self, city: str, days: int = 3):
+        """Get weather forecast for a city (mock implementation)."""
+        # This would make an API call in a real implementation
+        print(f"Would call {self.api_url}/forecast/{city} with API key {self.api_key[:4]}...")
+        return {
+            "city": city,
+            "unit": self.unit,
+            "forecast": [{"day": i, "temp": 70 + i} for i in range(days)]
+        }
+    
+    async def get_current(self, city: str):
+        """Get current weather for a city (mock implementation)."""
+        print(f"Would call {self.api_url}/current/{city} with API key {self.api_key[:4]}...")
+        return {
+            "city": city,
+            "unit": self.unit,
+            "temperature": 72,
+            "conditions": "Sunny"
+        }
+
+
+# Create a shared weather client that can be imported by all resources in this directory
+weather_client = WeatherApiClient()
+
+# This could also define shared models or other utilities
+# that would be common across weather-related resources 

golf/examples/basic/resources/weather/current.py

@@ -0,0 +1,32 @@
+"""Current weather resource example."""
+
+from datetime import datetime
+from typing import Dict, Any
+from .common import weather_client
+
+# The URI that clients will use to access this resource
+resource_uri = "weather://current/{city}"
+
+
+async def current_weather(city: str) -> Dict[str, Any]:
+    """Provide current weather for the specified city.
+    
+    This example demonstrates:
+    1. Nested resource organization (resources/weather/current.py)
+    2. Dynamic URI parameters (city in this case)
+    3. Using shared client from the common.py file
+    """
+    # Use the shared weather client from common.py
+    weather_data = await weather_client.get_current(city)
+    
+    # Add some additional data
+    weather_data.update({
+        "time": datetime.now().isoformat(),
+        "source": "GolfMCP Weather API",
+        "unit": "fahrenheit"
+    })
+    
+    return weather_data
+
+# Designate the entry point function
+export = current_weather 

golf/examples/basic/resources/weather/forecast.py

@@ -0,0 +1,32 @@
+"""Weather forecast resource example demonstrating nested resources."""
+
+from datetime import datetime
+from typing import Dict, Any
+from .common import weather_client
+
+# The URI that clients will use to access this resource
+resource_uri = "weather://forecast/{city}"
+
+
+async def forecast_weather(city: str) -> Dict[str, Any]:
+    """Provide a weather forecast for the specified city.
+    
+    This example demonstrates:
+    1. Nested resource organization (resources/weather/forecast.py)
+    2. Dynamic URI parameters (city in this case)
+    3. Using shared client from the common.py file
+    """
+    # Use the shared weather client from common.py
+    forecast_data = await weather_client.get_forecast(city, days=5)
+    
+    # Add some additional data
+    forecast_data.update({
+        "updated_at": datetime.now().isoformat(),
+        "source": "GolfMCP Weather API",
+        "unit": "fahrenheit"
+    })
+    
+    return forecast_data
+
+# Designate the entry point function
+export = forecast_weather 

golf/examples/basic/tools/github_user.py

@@ -0,0 +1,67 @@
+"""Tool for fetching GitHub user information."""
+
+from typing import Optional
+from pydantic import BaseModel
+import httpx
+from golf.auth import get_provider_token
+
+
+class GitHubUserResponse(BaseModel):
+    """Response model for GitHub user information."""
+    
+    login: str
+    id: int
+    name: Optional[str] = None
+    email: Optional[str] = None
+    avatar_url: Optional[str] = None
+    location: Optional[str] = None
+    bio: Optional[str] = None
+    public_repos: int = 0
+    followers: int = 0
+    following: int = 0
+    message: Optional[str] = None
+
+
+async def get_github_user() -> GitHubUserResponse:
+    """Fetch authenticated user's GitHub profile information."""
+    try:
+        # Get GitHub token using our abstraction
+        github_token = get_provider_token()
+        
+        if not github_token:
+            return GitHubUserResponse(
+                login="anonymous",
+                id=0,
+                message="Not authenticated. Please login first."
+            )
+        
+        # Call GitHub API to get user info
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                "https://api.github.com/user",
+                headers={
+                    "Authorization": f"Bearer {github_token}",
+                    "Accept": "application/vnd.github.v3+json"
+                }
+            )
+            
+            if response.status_code == 200:
+                data = response.json()
+                return GitHubUserResponse(**data)
+            else:
+                return GitHubUserResponse(
+                    login="error",
+                    id=0,
+                    message=f"GitHub API error: {response.status_code} - {response.text[:100]}"
+                )
+    
+    except Exception as e:
+        return GitHubUserResponse(
+            login="error",
+            id=0,
+            message=f"Error fetching GitHub data: {str(e)}"
+        )
+
+
+# Export the tool
+export = get_github_user 

golf/examples/basic/tools/hello.py

@@ -0,0 +1,29 @@
+"""Hello World tool {{project_name}}."""
+
+from pydantic import BaseModel
+
+
+class Output(BaseModel):
+    """Response from the hello tool."""
+    
+    message: str
+
+
+async def hello(
+    name: str = "World",
+    greeting: str = "Hello"
+) -> Output:
+    """Say hello to the given name.
+    
+    This is a simple example tool that demonstrates the basic structure
+    of a tool implementation in GolfMCP.
+    """
+    # The framework will add a context object automatically
+    # You can log using regular print during development
+    print(f"{greeting} {name}...")
+    
+    # Create and return the response
+    return Output(message=f"{greeting}, {name}!")
+
+# Designate the entry point function
+export = hello 

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

@@ -0,0 +1,50 @@
+"""Charge payment tool"""
+
+from pydantic import BaseModel
+from .common import payment_client
+
+
+class Output(BaseModel):
+    """Response from the charge payment tool."""
+    
+    success: bool
+    charge_id: str
+    message: str
+
+
+async def charge(
+    amount: float,
+    card_token: str,
+    description: str = ""
+) -> Output:
+    """Process a payment charge.
+    
+    This example demonstrates nested directory organization where related tools
+    are grouped in subdirectories (tools/payments/charge.py).
+    
+    The resulting tool ID will be: charge-payments
+    
+    Args:
+        amount: Amount to charge in USD
+        card_token: Tokenized payment card
+        description: Optional payment description
+    """
+    # The framework will add a context object automatically
+    # You can log using regular print during development
+    print(f"Processing charge for ${amount:.2f}...")
+    
+    # Use the shared payment client from common.py
+    charge_result = await payment_client.create_charge(
+        amount=amount,
+        token=card_token,
+        description=description
+    )
+    
+    # Create and return the response
+    return Output(
+        success=True,
+        charge_id=charge_result["id"],
+        message=f"Successfully charged ${amount:.2f}"
+    ) 
+
+export = charge

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

@@ -0,0 +1,34 @@
+"""Payments shared functionality.
+
+This common.py file demonstrates the recommended pattern for 
+sharing functionality across multiple tools in a directory.
+"""
+
+import os
+
+# Read configuration from environment variables
+PAYMENT_API_KEY = os.environ.get("PAYMENT_API_KEY", "mock_key")
+PAYMENT_API_URL = os.environ.get("PAYMENT_API_URL", "https://api.example.com/payments")
+
+
+class PaymentClient:
+    """Mock payment provider client."""
+    
+    def __init__(self, api_key: str = PAYMENT_API_KEY, api_url: str = PAYMENT_API_URL):
+        self.api_key = api_key
+        self.api_url = api_url
+    
+    async def create_charge(self, amount: float, token: str, **kwargs):
+        """Create a charge (mock implementation)."""
+        # In a real implementation, this would make an API request
+        # using the configured API key and URL
+        return {"id": f"ch_{int(amount * 100)}_{hash(token) % 10000:04d}"}
+    
+    async def create_refund(self, charge_id: str, amount: float, **kwargs):
+        """Create a refund (mock implementation)."""
+        # In a real implementation, this would make an API request
+        return {"id": f"ref_{charge_id}_{int(amount * 100)}"}
+
+
+# Create a shared payment client that can be imported by all tools in this directory
+payment_client = PaymentClient()

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

@@ -0,0 +1,50 @@
+"""Refund payment tool"""
+
+from pydantic import BaseModel
+from .common import payment_client
+
+
+class Output(BaseModel):
+    """Response from the refund payment tool."""
+    
+    success: bool
+    refund_id: str
+    message: str
+
+
+async def refund(
+    charge_id: str,
+    amount: float,
+    reason: str = "customer_request"
+) -> Output:
+    """Process a payment refund.
+    
+    This example demonstrates nested directory organization where related tools
+    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}...")
+    
+    # Use the shared payment client from common.py
+    refund_result = await payment_client.create_refund(
+        charge_id=charge_id,
+        amount=amount,
+        reason=reason
+    )
+    
+    # Create and return the response
+    return Output(
+        success=True,
+        refund_id=refund_result["id"],
+        message=f"Successfully refunded ${amount:.2f}"
+    ) 
+
+export = refund

golf_mcp-0.1.0.dist-info/METADATA

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