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

golf/core/transformer.py

@@ -51,35 +51,62 @@ class ImportTransformer(ast.NodeTransformer):
                 source_dir = source_dir.parent
 
             if node.module:
+                # Handle imports like `from .helpers import utils`
                 source_module = source_dir / node.module.replace(".", "/")
             else:
+                # Handle imports like `from . import something`
                 source_module = source_dir
 
-            # Check if this is a common module import
-            source_str = str(source_module.relative_to(self.project_root))
-            if source_str in self.import_map:
-                # Replace with absolute import
-                new_module = self.import_map[source_str]
-                return ast.ImportFrom(module=new_module, names=node.names, level=0)
+            try:
+                # Check if this is a shared module import
+                source_str = str(source_module.relative_to(self.project_root))
+
+                # First, try direct module path match (e.g., "tools/weather/helpers")
+                if source_str in self.import_map:
+                    new_module = self.import_map[source_str]
+                    return ast.ImportFrom(module=new_module, names=node.names, level=0)
+
+                # If direct match fails, try directory-based matching
+                # This handles cases like `from . import common` where the import_map
+                # has "tools/weather/common" but we're looking for "tools/weather"
+                source_dir_str = str(source_dir.relative_to(self.project_root))
+                if source_dir_str in self.import_map:
+                    new_module = self.import_map[source_dir_str]
+                    if node.module:
+                        new_module = f"{new_module}.{node.module}"
+                    return ast.ImportFrom(module=new_module, names=node.names, level=0)
+
+                # Check for specific module imports within the directory
+                for import_path, mapped_path in self.import_map.items():
+                    # Handle cases where we import a specific module from a directory
+                    # e.g., `from .common import something` should match "tools/weather/common"
+                    if import_path.startswith(source_dir_str + "/") and node.module:
+                        module_name = import_path.replace(source_dir_str + "/", "")
+                        if module_name == node.module:
+                            return ast.ImportFrom(module=mapped_path, names=node.names, level=0)
+
+            except ValueError:
+                # source_module is not relative to project_root, leave import unchanged
+                pass
 
         return node
 
 
 def transform_component(
-    component: ParsedComponent,
+    component: ParsedComponent | None,
     output_file: Path,
     project_path: Path,
     import_map: dict[str, str],
-    source_file: Path = None,
+    source_file: Path | None = None,
 ) -> str:
     """Transform a GolfMCP component into a standalone FastMCP component.
 
     Args:
-        component: Parsed component to transform
+        component: Parsed component to transform (optional if source_file provided)
         output_file: Path to write the transformed component to
         project_path: Path to the project root
         import_map: Mapping of original module paths to generated paths
-        source_file: Optional path to source file (for common.py files)
+        source_file: Optional path to source file (for shared files)
 
     Returns:
         Generated component code
@@ -144,11 +171,7 @@ def transform_component(
             continue
 
         # Skip the original docstring
-        if (
-            isinstance(node, ast.Expr)
-            and isinstance(node.value, ast.Constant)
-            and isinstance(node.value.value, str)
-        ):
+        if isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant) and isinstance(node.value.value, str):
             continue
 
         remaining_nodes.append(node)

golf/examples/basic/.env.example

@@ -1,4 +1,8 @@
-GITHUB_CLIENT_ID="default-client-id"
-GITHUB_CLIENT_SECRET="default-secret"
-JWT_SECRET="example-jwt-secret-for-development-only"
-#GOLF_API_KEY=<your-api-key>
+# Golf MCP Server Environment Variables
+
+# Golf platform integration
+GOLF_API_KEY="your-golf-api-key"
+GOLF_SERVER_ID="your-server-id"
+
+# Development tokens are configured in auth.py for this example
+# Additional environment variables can be added as needed

golf/examples/basic/README.md

@@ -1,61 +1,133 @@
-# GolfMCP Project Boilerplate
+# Golf MCP Project Template (Basic)
 
-This directory serves as a starting template for new GolfMCP projects. Initialize a project using the `golf init <your-project-name>` command.
-## About GolfMCP
+This is a basic template for creating MCP servers with Golf. It includes development authentication for easy testing. Use `golf init <project-name>` to bootstrap new projects from this template.
 
-GolfMCP is a Python framework designed to build MCP servers with minimal boilerplate. It allows you to define tools, resources, and prompts as simple Python files. These components are then automatically discovered and compiled into a runnable [FastMCP](https://github.com/fastmcp/fastmcp) server.
+## About Golf
 
-## Getting Started (After `golf init`)
+Golf is a Python framework for building MCP (Model Context Protocol) servers with minimal boilerplate. Define your server's capabilities as simple Python files, and Golf automatically discovers and compiles them into a runnable FastMCP server.
 
-Once you've initialized your new project from this boilerplate:
+## Getting Started
 
-1.  **Navigate to your project directory:**
-    ```bash
-    cd your-project-name
-    ```
+After initializing your project:
 
-2.  **Start the development server:**
-    ```bash
-    golf build dev  # For a development build
-    # or
-    golf build prod # For a production build
-    
-    golf run
-    ```
+1. **Navigate to your project directory:**
+   ```bash
+   cd your-project-name
+   ```
 
-## Project Structure
-
-Your initialized GolfMCP project will typically have the following structure:
-
--   `tools/`: Directory for your tool implementations (Python files defining functions an LLM can call).
--   `resources/`: Directory for your resource implementations (Python files defining data an LLM can read).
--   `prompts/`: Directory for your prompt templates (Python files defining reusable conversation structures).
--   `golf.json`: The main configuration file for your project, including settings like the server name, port, and transport.
--   `pre_build.py`: (Optional) A Python script that can be used to run custom logic before the build process begins, such as configuring authentication.
--   `.env`: File to store environment-specific variables (e.g., API keys). This is created during `golf init`.
-
-## Adding New Components
+2. **Configure authentication (optional):**
+   This template includes development authentication in `auth.py` with sample tokens. Edit the file to set up JWT, OAuth, or API key authentication for production use.
 
-To add new functionalities:
+3. **Build and run your server:**
+   ```bash
+   golf build dev    # Development build
+   golf run          # Start the server
+   ```
 
--   **Tools**: Create a new `.py` file in the `tools/` directory.
--   **Resources**: Create a new `.py` file in the `resources/` directory.
--   **Prompts**: Create a new `.py` file in the `prompts/` directory.
-
-Each Python file should generally define a single component. A module-level docstring in the file will be used as the description for the component. See the example files (e.g., `tools/hello.py`, `resources/info.py`) provided in this boilerplate for reference.
+## Project Structure
 
-For shared functionality within a component subdirectory (e.g., `tools/payments/common.py`), you can use a `common.py` file.
+```
+your-project/
+├── tools/           # Tool implementations (functions LLMs can call)
+├── resources/       # Resource implementations (data LLMs can read)  
+├── prompts/         # Prompt templates (conversation structures)
+├── golf.json        # Server configuration
+└── auth.py          # Authentication setup
+```
+
+## Adding Components
+
+### Tools
+Create `.py` files in `tools/` directory. Each file should export a single async function:
+
+```python
+# tools/calculator.py
+async def add(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+export = add
+```
+
+### Resources  
+Create `.py` files in `resources/` directory with a `resource_uri` and export function:
+
+```python
+# resources/status.py
+resource_uri = "status://server"
+
+async def status() -> dict:
+    """Get server status information."""
+    return {"status": "running", "timestamp": "2024-01-01T00:00:00Z"}
+
+export = status
+```
+
+### Prompts
+Create `.py` files in `prompts/` directory that return message lists:
+
+```python
+# prompts/assistant.py
+async def assistant() -> list[dict]:
+    """System prompt for a helpful assistant."""
+    return [
+        {
+            "role": "system", 
+            "content": "You are a helpful assistant for {{project_name}}."
+        }
+    ]
+
+export = assistant
+```
+
+## Authentication Examples
+
+### No Authentication (Default)
+Leave `auth.py` empty or remove it entirely.
+
+### API Key Authentication
+```python
+# auth.py
+from golf.auth import configure_api_key
+
+configure_api_key(
+    header_name="Authorization",
+    header_prefix="Bearer ",
+    required=True
+)
+```
+
+### JWT Authentication  
+```python
+# auth.py
+from golf.auth import configure_jwt_auth
+
+configure_jwt_auth(
+    jwks_uri="https://your-domain.auth0.com/.well-known/jwks.json",
+    issuer="https://your-domain.auth0.com/",
+    audience="https://your-api.example.com"
+)
+```
+
+### Development Tokens
+```python
+# auth.py  
+from golf.auth import configure_dev_auth
+
+configure_dev_auth(
+    tokens={
+        "dev-token-123": {
+            "client_id": "dev-client",
+            "scopes": ["read", "write"]
+        }
+    }
+)
+```
 
 ## Documentation
 
-For comprehensive details on the GolfMCP framework, including component specifications, advanced configurations, CLI commands, and more, please refer to the official documentation:
-
-[https://docs.golf.dev](https://docs.golf.dev)
+For comprehensive documentation, visit: [https://docs.golf.dev](https://docs.golf.dev)
 
 ---
 
-Happy Building! 
-
-<div align="center">
-Made with ❤️ in San Francisco
-</div>
+Happy building! 🏌️‍♂️

golf/examples/basic/auth.py

@@ -0,0 +1,76 @@
+"""Authentication configuration for the basic Golf MCP server example.
+
+This example shows different authentication options available in Golf 0.2.x:
+- JWT authentication with static keys or JWKS endpoints (production)
+- Static token authentication (development/testing)
+- OAuth Server mode (full OAuth 2.0 server)
+- Remote Authorization Server integration
+"""
+
+# Example 1: JWT authentication with a static public key
+# from golf.auth import configure_auth, JWTAuthConfig
+#
+# configure_auth(
+#     JWTAuthConfig(
+#         public_key_env_var="JWT_PUBLIC_KEY",  # PEM-encoded public key
+#         issuer="https://your-auth-server.com",
+#         audience="https://your-golf-server.com",
+#         required_scopes=["read:data"],
+#     )
+# )
+
+# Example 2: JWT authentication with JWKS (recommended for production)
+# from golf.auth import configure_auth, JWTAuthConfig
+#
+# configure_auth(
+#     JWTAuthConfig(
+#         jwks_uri_env_var="JWKS_URI",        # e.g., "https://your-domain.auth0.com/.well-known/jwks.json"
+#         issuer_env_var="JWT_ISSUER",        # e.g., "https://your-domain.auth0.com/"
+#         audience_env_var="JWT_AUDIENCE",    # e.g., "https://your-api.example.com"
+#         required_scopes=["read:user"],
+#     )
+# )
+
+# Example 3: OAuth Server mode - Golf acts as full OAuth 2.0 authorization server
+# from golf.auth import configure_auth, OAuthServerConfig
+#
+# configure_auth(
+#     OAuthServerConfig(
+#         base_url_env_var="OAUTH_BASE_URL",          # e.g., "https://auth.example.com"
+#         valid_scopes=["read", "write", "admin"],    # Scopes clients can request
+#         default_scopes=["read"],                    # Default scopes for new clients
+#         required_scopes=["read"],                   # Scopes required for all requests
+#     )
+# )
+
+# Example 4: Remote Authorization Server integration
+# from golf.auth import configure_auth, RemoteAuthConfig, JWTAuthConfig
+#
+# configure_auth(
+#     RemoteAuthConfig(
+#         authorization_servers_env_var="AUTH_SERVERS",    # Comma-separated: "https://auth1.com,https://auth2.com"
+#         resource_server_url_env_var="RESOURCE_URL",     # This server's URL
+#         token_verifier_config=JWTAuthConfig(
+#             jwks_uri_env_var="JWKS_URI"
+#         ),
+#     )
+# )
+
+# Example 5: Static token authentication for development (NOT for production)
+from golf.auth import configure_auth, StaticTokenConfig
+
+configure_auth(
+    StaticTokenConfig(
+        tokens={
+            "dev-token-123": {
+                "client_id": "dev-client",
+                "scopes": ["read", "write"],
+            },
+            "admin-token-456": {
+                "client_id": "admin-client",
+                "scopes": ["read", "write", "admin"],
+            },
+        },
+        required_scopes=["read"],
+    )
+)

golf/examples/basic/golf.json

@@ -1,8 +1,5 @@
 {
-  "name": "{{project_name}}",
+  "name": "basic-server-example",
   "description": "A GolfMCP project",
-  "host": "127.0.0.1",
-  "port": 3000,
-  "transport": "sse",
-  "opentelemetry_enabled": false
+  "transport": "http"
 } 

golf/examples/basic/htmlcov/.gitignore

@@ -0,0 +1,2 @@
+# Created by coverage.py
+*