golf-mcp 0.1.0__py3-none-any.whl

golf/core/parser.py

@@ -0,0 +1,509 @@
+"""Python file parser for extracting tools, resources, and prompts using AST."""
+
+import ast
+import re
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import hashlib
+
+from rich.console import Console
+
+console = Console()
+
+
+class ComponentType(str, Enum):
+    """Type of component discovered by the parser."""
+    
+    TOOL = "tool"
+    RESOURCE = "resource"
+    PROMPT = "prompt"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class ParsedComponent:
+    """Represents a parsed MCP component (tool, resource, or prompt)."""
+    
+    name: str  # Derived from file path or explicit name
+    type: ComponentType
+    file_path: Path
+    module_path: str
+    docstring: Optional[str] = None
+    input_schema: Optional[Dict[str, Any]] = None
+    output_schema: Optional[Dict[str, Any]] = None
+    uri_template: Optional[str] = None  # For resources
+    parameters: Optional[List[str]] = None  # For resources with URI params
+    parent_module: Optional[str] = None  # For nested components
+    entry_function: Optional[str] = None  # Store the name of the function to use
+
+
+class AstParser:
+    """AST-based parser for extracting MCP components from Python files."""
+    
+    def __init__(self, project_root: Path):
+        """Initialize the parser.
+        
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root
+        self.components: Dict[str, ParsedComponent] = {}
+    
+    def parse_directory(self, directory: Path) -> List[ParsedComponent]:
+        """Parse all Python files in a directory recursively."""
+        components = []
+        
+        for file_path in directory.glob("**/*.py"):
+            # Skip __pycache__ and other hidden directories
+            if "__pycache__" in file_path.parts or any(part.startswith('.') for part in file_path.parts):
+                continue
+            
+            try:
+                file_components = self.parse_file(file_path)
+                components.extend(file_components)
+            except Exception as e:
+                relative_path = file_path.relative_to(self.project_root)
+                console.print(f"[bold red]Error parsing {relative_path}:[/bold red] {e}")
+        
+        return components
+    
+    def parse_file(self, file_path: Path) -> List[ParsedComponent]:
+        """Parse a single Python file using AST to extract MCP components."""
+        # Handle common.py files
+        if file_path.name == "common.py":
+            # Register as a known shared module but don't return as a component
+            return []
+            
+        # Skip __init__.py files for direct parsing
+        if file_path.name == "__init__.py":
+            return []
+            
+        # Determine component type based on directory structure
+        rel_path = file_path.relative_to(self.project_root)
+        parent_dir = rel_path.parts[0] if rel_path.parts else None
+        
+        component_type = ComponentType.UNKNOWN
+        if parent_dir == "tools":
+            component_type = ComponentType.TOOL
+        elif parent_dir == "resources":
+            component_type = ComponentType.RESOURCE
+        elif parent_dir == "prompts":
+            component_type = ComponentType.PROMPT
+        
+        if component_type == ComponentType.UNKNOWN:
+            return []  # Not in a recognized directory
+        
+        # Read the file content and parse it with AST
+        with open(file_path, 'r', encoding='utf-8') as f:
+            file_content = f.read()
+        
+        try:
+            tree = ast.parse(file_content)
+        except SyntaxError as e:
+            raise ValueError(f"Syntax error in {file_path}: {e}")
+        
+        # Extract module docstring
+        module_docstring = ast.get_docstring(tree)
+        if not module_docstring:
+            raise ValueError(f"Missing module docstring in {file_path}")
+        
+        # Find the entry function - look for "export = function_name" pattern, 
+        # or any top-level function (like "run") as a fallback
+        entry_function = None
+        export_target = None
+        
+        # Look for export = function_name assignment
+        for node in tree.body:
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id == "export":
+                        if isinstance(node.value, ast.Name):
+                            export_target = node.value.id
+                            break
+        
+        # Find all top-level functions
+        functions = []
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                functions.append(node)
+                # If this function matches our export target, it's our entry function
+                if export_target and node.name == export_target:
+                    entry_function = node
+        
+        # Check for the run function as a fallback
+        run_function = None
+        for func in functions:
+            if func.name == "run":
+                run_function = func
+                
+        # If we have an export but didn't find the target function, warn
+        if export_target and not entry_function:
+            console.print(f"[yellow]Warning: Export target '{export_target}' not found in {file_path}[/yellow]")
+        
+        # Use the export target function if found, otherwise fall back to run
+        entry_function = entry_function or run_function
+        
+        # If no valid function found, skip this file
+        if not entry_function:
+            return []
+        
+        # Create component
+        component = ParsedComponent(
+            name="",  # Will be set later
+            type=component_type,
+            file_path=file_path,
+            module_path=file_path.relative_to(self.project_root).as_posix(),
+            docstring=module_docstring,
+            entry_function=export_target or "run"  # Store the name of the entry function
+        )
+        
+        # Process the entry function
+        self._process_entry_function(component, entry_function, tree, file_path)
+        
+        # Process other component-specific information
+        if component_type == ComponentType.TOOL:
+            self._process_tool(component, tree)
+        elif component_type == ComponentType.RESOURCE:
+            self._process_resource(component, tree)
+        elif component_type == ComponentType.PROMPT:
+            self._process_prompt(component, tree)
+        
+        # Set component name based on file path
+        component.name = self._derive_component_name(file_path, component_type)
+        
+        # Set parent module if it's in a nested structure
+        if len(rel_path.parts) > 2:  # More than just "tools/file.py"
+            parent_parts = rel_path.parts[1:-1]  # Skip the root category and the file itself
+            if parent_parts:
+                component.parent_module = ".".join(parent_parts)
+        
+        return [component]
+    
+    def _process_entry_function(self, component: ParsedComponent, func_node: ast.FunctionDef | ast.AsyncFunctionDef, tree: ast.Module, file_path: Path) -> None:
+        """Process the entry function to extract parameters and return type."""
+        # Extract function docstring
+        func_docstring = ast.get_docstring(func_node)
+        
+        # Extract parameter names and annotations
+        parameters = []
+        for arg in func_node.args.args:
+            # Skip self, cls parameters
+            if arg.arg in ("self", "cls"):
+                continue
+                
+            # Skip ctx parameter - GolfMCP will inject this
+            if arg.arg == "ctx":
+                continue
+                
+            parameters.append(arg.arg)
+        
+        # Check for return annotation - STRICT requirement
+        if func_node.returns is None:
+            raise ValueError(f"Missing return annotation for {func_node.name} function in {file_path}")
+        
+        # Store parameters
+        component.parameters = parameters
+    
+    def _process_tool(self, component: ParsedComponent, tree: ast.Module) -> None:
+        """Process a tool component to extract input/output schemas."""
+        # Look for Input and Output classes in the AST
+        input_class = None
+        output_class = None
+        
+        for node in tree.body:
+            if isinstance(node, ast.ClassDef):
+                if node.name == "Input":
+                    input_class = node
+                elif node.name == "Output":
+                    output_class = node
+        
+        # Process Input class if found
+        if input_class:
+            # Check if it inherits from BaseModel
+            for base in input_class.bases:
+                if isinstance(base, ast.Name) and base.id == "BaseModel":
+                    component.input_schema = self._extract_pydantic_schema_from_ast(input_class)
+                    break
+        
+        # Process Output class if found
+        if output_class:
+            # Check if it inherits from BaseModel
+            for base in output_class.bases:
+                if isinstance(base, ast.Name) and base.id == "BaseModel":
+                    component.output_schema = self._extract_pydantic_schema_from_ast(output_class)
+                    break
+    
+    def _process_resource(self, component: ParsedComponent, tree: ast.Module) -> None:
+        """Process a resource component to extract URI template."""
+        # Look for resource_uri assignment in the AST
+        for node in tree.body:
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id == "resource_uri":
+                        if isinstance(node.value, ast.Constant):
+                            uri_template = node.value.value
+                            component.uri_template = uri_template
+                            
+                            # Extract URI parameters (parts in {})
+                            uri_params = re.findall(r"{([^}]+)}", uri_template)
+                            if uri_params:
+                                component.parameters = uri_params
+                            break
+    
+    def _process_prompt(self, component: ParsedComponent, tree: ast.Module) -> None:
+        """Process a prompt component (no special processing needed)."""
+        pass
+    
+    def _derive_component_name(self, file_path: Path, component_type: ComponentType) -> str:
+        """Derive a component name from its file path according to the spec.
+        
+        Following the spec: <filename> + ("-" + "-".join(PathRev) if PathRev else "")
+        where PathRev is the reversed list of parent directories under the category.
+        """
+        rel_path = file_path.relative_to(self.project_root)
+        
+        # Find which category directory this is in
+        category = None
+        category_idx = -1
+        for i, part in enumerate(rel_path.parts):
+            if part in ["tools", "resources", "prompts"]:
+                category = part
+                category_idx = i
+                break
+        
+        if category_idx == -1:
+            return ""
+        
+        # Get the filename without extension
+        filename = rel_path.stem
+        
+        # Get parent directories between category and file
+        parent_dirs = list(rel_path.parts[category_idx+1:-1])
+        
+        # Reverse parent dirs according to spec
+        parent_dirs.reverse()
+        
+        # Form the ID according to spec
+        if parent_dirs:
+            return f"{filename}-{'-'.join(parent_dirs)}"
+        else:
+            return filename
+    
+    def _extract_pydantic_schema_from_ast(self, class_node: ast.ClassDef) -> Dict[str, Any]:
+        """Extract a JSON schema from an AST class definition.
+        
+        This is a simplified version that extracts basic field information.
+        For complex annotations, a more sophisticated approach would be needed.
+        """
+        schema = {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+        
+        for node in class_node.body:
+            if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+                field_name = node.target.id
+                
+                # Extract type annotation as string
+                annotation = ""
+                if isinstance(node.annotation, ast.Name):
+                    annotation = node.annotation.id
+                elif isinstance(node.annotation, ast.Subscript):
+                    # Simple handling of things like List[str]
+                    annotation = ast.unparse(node.annotation)
+                else:
+                    annotation = ast.unparse(node.annotation)
+                
+                # Create property definition
+                prop = {
+                    "type": self._type_hint_to_json_type(annotation),
+                    "title": field_name.replace('_', ' ').title()
+                }
+                
+                # Extract default value if present
+                if node.value is not None:
+                    if isinstance(node.value, ast.Constant):
+                        # Simple constant default
+                        prop["default"] = node.value.value
+                    elif (isinstance(node.value, ast.Call) and 
+                          isinstance(node.value.func, ast.Name) and 
+                          node.value.func.id == "Field"):
+                        # Field object - extract its parameters
+                        for keyword in node.value.keywords:
+                            if keyword.arg == "default" or keyword.arg == "default_factory":
+                                if isinstance(keyword.value, ast.Constant):
+                                    prop["default"] = keyword.value.value
+                            elif keyword.arg == "description":
+                                if isinstance(keyword.value, ast.Constant):
+                                    prop["description"] = keyword.value.value
+                            elif keyword.arg == "title":
+                                if isinstance(keyword.value, ast.Constant):
+                                    prop["title"] = keyword.value.value
+                        
+                        # Check for position default argument (Field(..., "description"))
+                        if node.value.args:
+                            for i, arg in enumerate(node.value.args):
+                                if i == 0 and isinstance(arg, ast.Constant) and arg.value != Ellipsis:
+                                    prop["default"] = arg.value
+                                elif i == 1 and isinstance(arg, ast.Constant):
+                                    prop["description"] = arg.value
+                
+                # Add to properties
+                schema["properties"][field_name] = prop
+                
+                # Check if required (no default value or Field(...))
+                is_required = True
+                if node.value is not None:
+                    if isinstance(node.value, ast.Constant):
+                        is_required = False
+                    elif (isinstance(node.value, ast.Call) and 
+                          isinstance(node.value.func, ast.Name) and 
+                          node.value.func.id == "Field"):
+                        # Field has default if it doesn't use ... or if it has a default keyword
+                        has_ellipsis = False
+                        has_default = False
+                        
+                        if node.value.args and isinstance(node.value.args[0], ast.Constant):
+                            has_ellipsis = node.value.args[0].value is Ellipsis
+                        
+                        for keyword in node.value.keywords:
+                            if keyword.arg == "default" or keyword.arg == "default_factory":
+                                has_default = True
+                        
+                        is_required = has_ellipsis and not has_default
+                
+                if is_required:
+                    schema["required"].append(field_name)
+        
+        return schema
+    
+    def _type_hint_to_json_type(self, type_hint: str) -> str:
+        """Convert a Python type hint to a JSON schema type.
+        
+        This is a simplified version. A more sophisticated approach would
+        handle complex types correctly.
+        """
+        type_map = {
+            "str": "string",
+            "int": "integer",
+            "float": "number",
+            "bool": "boolean",
+            "list": "array",
+            "dict": "object",
+        }
+        
+        # Handle simple types
+        for py_type, json_type in type_map.items():
+            if py_type in type_hint.lower():
+                return json_type
+        
+        # Default to string for unknown types
+        return "string"
+
+
+def parse_project(project_path: Path) -> Dict[ComponentType, List[ParsedComponent]]:
+    """Parse a GolfMCP project to extract all components."""
+    parser = AstParser(project_path)
+    
+    components: Dict[ComponentType, List[ParsedComponent]] = {
+        ComponentType.TOOL: [],
+        ComponentType.RESOURCE: [],
+        ComponentType.PROMPT: []
+    }
+    
+    # Parse each directory
+    for comp_type, dir_name in [
+        (ComponentType.TOOL, "tools"),
+        (ComponentType.RESOURCE, "resources"),
+        (ComponentType.PROMPT, "prompts")
+    ]:
+        dir_path = project_path / dir_name
+        if dir_path.exists() and dir_path.is_dir():
+            dir_components = parser.parse_directory(dir_path)
+            components[comp_type].extend([c for c in dir_components if c.type == comp_type])
+    
+    # Check for ID collisions
+    all_ids = []
+    for comp_type, comps in components.items():
+        for comp in comps:
+            if comp.name in all_ids:
+                raise ValueError(f"ID collision detected: {comp.name} is used by multiple components")
+            all_ids.append(comp.name)
+    
+    return components
+
+
+def parse_project_incremental(project_path: Path, fingerprints: Dict[str, str]) -> Dict[ComponentType, List[ParsedComponent]]:
+    """Parse a project with incremental file checking."""
+    parser = AstParser(project_root=project_path)
+    
+    components: Dict[ComponentType, List[ParsedComponent]] = {
+        ComponentType.TOOL: [],
+        ComponentType.RESOURCE: [],
+        ComponentType.PROMPT: []
+    }
+    
+    # Process each directory
+    for comp_type, dir_name in [
+        (ComponentType.TOOL, "tools"),
+        (ComponentType.RESOURCE, "resources"),
+        (ComponentType.PROMPT, "prompts")
+    ]:
+        dir_path = project_path / dir_name
+        if not dir_path.exists() or not dir_path.is_dir():
+            continue
+            
+        # Parse only changed files using fingerprints
+        for file_path in dir_path.glob("**/*.py"):
+            if "__pycache__" in file_path.parts or file_path.name == "__init__.py":
+                continue
+                
+            # Check if file changed
+            with open(file_path, "rb") as f:
+                content = f.read()
+                file_hash = hashlib.sha1(content).hexdigest()
+            
+            rel_path = str(file_path.relative_to(project_path))
+            
+            if rel_path not in fingerprints or fingerprints[rel_path] != file_hash:
+                try:
+                    file_components = parser.parse_file(file_path)
+                    components[comp_type].extend([c for c in file_components if c.type == comp_type])
+                    fingerprints[rel_path] = file_hash
+                except Exception as e:
+                    console.print(f"[bold red]Error parsing {rel_path}: {e}[/bold red]")
+    
+    return components
+
+
+def parse_common_files(project_path: Path) -> Dict[str, Path]:
+    """Find all common.py files in the project.
+    
+    Args:
+        project_path: Path to the project root
+        
+    Returns:
+        Dictionary mapping directory paths to common.py file paths
+    """
+    common_files = {}
+    
+    # Search for common.py files in tools, resources, and prompts directories
+    for dir_name in ["tools", "resources", "prompts"]:
+        base_dir = project_path / dir_name
+        if not base_dir.exists() or not base_dir.is_dir():
+            continue
+            
+        # Find all common.py files (recursively)
+        for common_file in base_dir.glob("**/common.py"):
+            # Skip files in __pycache__ or other hidden directories
+            if "__pycache__" in common_file.parts or any(part.startswith('.') for part in common_file.parts):
+                continue
+                
+            # Get the parent directory as the module path
+            module_path = str(common_file.parent.relative_to(project_path))
+            common_files[module_path] = common_file
+    
+    return common_files 

golf/core/transformer.py

@@ -0,0 +1,168 @@
+"""Transform GolfMCP components into standalone FastMCP code.
+
+This module provides utilities for transforming GolfMCP's convention-based code
+into explicit FastMCP component registrations.
+"""
+
+import ast
+from pathlib import Path
+from typing import Dict, Any
+
+from golf.core.parser import ParsedComponent
+
+
+class ImportTransformer(ast.NodeTransformer):
+    """AST transformer for rewriting imports in component files."""
+    
+    def __init__(self, 
+                 original_path: Path, 
+                 target_path: Path,
+                 import_map: Dict[str, str],
+                 project_root: Path):
+        """Initialize the import transformer.
+        
+        Args:
+            original_path: Path to the original file
+            target_path: Path to the target file
+            import_map: Mapping of original module paths to generated paths
+            project_root: Root path of the project
+        """
+        self.original_path = original_path
+        self.target_path = target_path
+        self.import_map = import_map
+        self.project_root = project_root
+    
+    def visit_Import(self, node: ast.Import) -> Any:
+        """Transform import statements."""
+        return node
+    
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> Any:
+        """Transform import from statements."""
+        if node.module is None:
+            return node
+            
+        # Handle relative imports
+        if node.level > 0:
+            # Calculate the source module path
+            source_dir = self.original_path.parent
+            for _ in range(node.level - 1):
+                source_dir = source_dir.parent
+                
+            if node.module:
+                source_module = source_dir / node.module.replace(".", "/")
+            else:
+                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
+                )
+                
+        return node
+
+
+def transform_component(
+    component: ParsedComponent,
+    output_file: Path,
+    project_path: Path,
+    import_map: Dict[str, str],
+    source_file: Path = None,
+) -> str:
+    """Transform a GolfMCP component into a standalone FastMCP component.
+    
+    Args:
+        component: Parsed component to transform
+        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)
+        
+    Returns:
+        Generated component code
+    """
+    # Read the original file
+    if source_file is not None:
+        file_path = source_file
+    elif component is not None:
+        file_path = Path(component.file_path)
+    else:
+        raise ValueError("Either component or source_file must be provided")
+        
+    with open(file_path, "r") as f:
+        source_code = f.read()
+        
+    # Parse the source code into an AST
+    tree = ast.parse(source_code)
+    
+    # Transform imports
+    transformer = ImportTransformer(
+        file_path,
+        output_file,
+        import_map,
+        project_path
+    )
+    tree = transformer.visit(tree)
+    
+    # Get all imports and docstring
+    imports = []
+    docstring = None
+    
+    # Find the module docstring if present
+    if (len(tree.body) > 0 and isinstance(tree.body[0], ast.Expr) and 
+        isinstance(tree.body[0].value, ast.Constant) and 
+        isinstance(tree.body[0].value.value, str)):
+        docstring = tree.body[0].value.value
+    
+    # Find imports
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            imports.append(node)
+    
+   # Generate the transformed code
+    transformed_imports = ast.unparse(ast.Module(body=imports, type_ignores=[]))
+    
+    # Build full transformed code
+    transformed_code = transformed_imports + "\n\n"
+    
+    # Add docstring if present, using proper triple quotes for multi-line docstrings
+    if docstring:
+        # Check if docstring contains newlines
+        if "\n" in docstring:
+            # Use triple quotes for multi-line docstrings
+            transformed_code += f'"""{docstring}"""\n\n'
+        else:
+            # Use single quotes for single-line docstrings
+            transformed_code += f'"{docstring}"\n\n'
+    
+    # Add the rest of the code except imports and the original docstring
+    remaining_nodes = []
+    for node in tree.body:
+        # Skip imports
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            continue
+            
+        # Skip the original docstring
+        if (isinstance(node, ast.Expr) and 
+            isinstance(node.value, ast.Constant) and 
+            isinstance(node.value.value, str)):
+            continue
+            
+        remaining_nodes.append(node)
+        
+    remaining_code = ast.unparse(ast.Module(body=remaining_nodes, type_ignores=[]))
+    transformed_code += remaining_code
+    
+    # Ensure the directory exists
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Write the transformed code to the output file
+    with open(output_file, "w") as f:
+        f.write(transformed_code)
+    
+    return transformed_code

golf/examples/__init__.py

@@ -0,0 +1 @@
+ 

golf/examples/basic/.env

@@ -0,0 +1,3 @@
+GITHUB_CLIENT_ID="Ov23liPVrFkEzGhXro5A"
+GITHUB_CLIENT_SECRET="4f050336d569559705963d88cf8ec8b3ce10441a"
+JWT_SECRET="example-jwt-secret-for-development-only"

golf/examples/basic/.env.example

@@ -0,0 +1,3 @@
+GOLF_CLIENT_ID="default-client-id"
+GOLF_CLIENT_SECRET="default-secret"
+JWT_SECRET="example-jwt-secret-for-development-only"