universal-mcp 0.1.8rc1__py3-none-any.whl → 0.1.8rc3__py3-none-any.whl

universal_mcp/utils/docstring_parser.py

@@ -0,0 +1,179 @@
+import re
+from typing import Any
+
+
+def parse_docstring(docstring: str | None) -> dict[str, Any]:
+    """
+    Parses a standard Python docstring into summary, args, returns, raises, and tags.
+
+    Args:
+        docstring: The docstring to parse.
+
+    Returns:
+        A dictionary with keys 'summary', 'args', 'returns', 'raises', 'tags'.
+        'args' is a dict mapping arg names to descriptions.
+        'raises' is a dict mapping exception type names to descriptions.
+        'tags' is a list of strings extracted from the 'Tags:' section, comma-separated.
+    """
+    if not docstring:
+        return {"summary": "", "args": {}, "returns": "", "raises": {}, "tags": []}
+
+    lines = docstring.strip().splitlines()
+    if not lines:
+        return {"summary": "", "args": {}, "returns": "", "raises": {}, "tags": []}
+
+    summary = lines[0].strip()
+    args = {}
+    returns = ""
+    raises = {}
+    tags: list[str] = []  # Final list of parsed tags
+    current_section = None
+    current_key = None
+    current_desc_lines = []  # Accumulator for multi-line descriptions/tag content
+    key_pattern = re.compile(r"^\s*([\w\.]+)\s*(?:\(.*\))?:\s*(.*)")
+
+    def finalize_current_item():
+        """Helper function to finalize the currently parsed item."""
+        nonlocal returns, tags  # Allow modification of outer scope variables
+        desc = " ".join(current_desc_lines).strip()
+        if current_section == "args" and current_key:
+            args[current_key] = desc
+        elif current_section == "raises" and current_key:
+            raises[current_key] = desc
+        elif current_section == "returns":
+            returns = desc
+        # SIM102 applied: Combine nested if
+        elif current_section == "tags" and desc:  # Only process if there's content
+            tags = [tag.strip() for tag in desc.split(",") if tag.strip()]
+
+    # B007 applied: Rename unused loop variable i to _
+    for _, line in enumerate(lines[1:]):
+        stripped_line = line.strip()
+        original_indentation = len(line) - len(line.lstrip(" "))
+
+        section_line = stripped_line.lower()
+        is_new_section_header = False
+        new_section_type = None
+        header_content = ""
+
+        if section_line in ("args:", "arguments:", "parameters:"):
+            new_section_type = "args"
+            is_new_section_header = True
+        elif section_line in ("returns:", "yields:"):
+            new_section_type = "returns"
+            is_new_section_header = True
+        elif section_line.startswith(("raises ", "raises:", "errors:", "exceptions:")):
+            new_section_type = "raises"
+            is_new_section_header = True
+        elif section_line.startswith(
+            ("tags:", "tags")
+        ):  # Match "Tags:" or "Tags" potentially followed by content
+            new_section_type = "tags"
+            is_new_section_header = True
+            if ":" in stripped_line:
+                header_content = stripped_line.split(":", 1)[1].strip()
+        elif section_line.endswith(":") and section_line[:-1] in (
+            "attributes",
+            "see also",
+            "example",
+            "examples",
+            "notes",
+        ):
+            new_section_type = "other"
+            is_new_section_header = True
+
+        finalize_previous = False
+        if is_new_section_header:
+            finalize_previous = True
+        elif current_section in ["args", "raises"] and current_key:
+            if key_pattern.match(line) or (original_indentation == 0 and stripped_line):
+                finalize_previous = True
+        elif current_section in ["returns", "tags"] and current_desc_lines:
+            if original_indentation == 0 and stripped_line:
+                finalize_previous = True
+        # SIM102 applied: Combine nested if/elif
+        elif (
+            not stripped_line
+            and current_desc_lines
+            and current_section in ["args", "raises", "returns", "tags"]
+            and (current_section not in ["args", "raises"] or current_key)
+        ):
+            finalize_previous = True
+
+        if finalize_previous:
+            finalize_current_item()
+            current_key = None
+            current_desc_lines = []
+            if not is_new_section_header or new_section_type == "other":
+                current_section = None
+
+        if is_new_section_header and new_section_type != "other":
+            current_section = new_section_type
+            # If Tags header had content, start accumulating it
+            if new_section_type == "tags" and header_content:
+                current_desc_lines.append(header_content)
+            # Don't process the header line itself further
+            continue
+
+        if not stripped_line:
+            continue
+
+        if current_section == "args" or current_section == "raises":
+            match = key_pattern.match(line)
+            if match:
+                current_key = match.group(1)
+                current_desc_lines = [match.group(2).strip()]  # Start new description
+            elif (
+                current_key and original_indentation > 0
+            ):  # Check for indentation for continuation
+                current_desc_lines.append(stripped_line)
+
+        elif current_section == "returns":
+            if not current_desc_lines or original_indentation > 0:
+                current_desc_lines.append(stripped_line)
+
+        elif current_section == "tags":
+            if (
+                original_indentation > 0 or not current_desc_lines
+            ):  # Indented or first line
+                current_desc_lines.append(stripped_line)
+
+    finalize_current_item()
+    return {
+        "summary": summary,
+        "args": args,
+        "returns": returns,
+        "raises": raises,
+        "tags": tags,
+    }
+
+
+docstring_example = """
+    Starts a crawl job for a given URL using Firecrawl. Returns the job ID immediately.
+
+    Args:
+        url: The starting URL for the crawl.
+                It can be a very long url that spans multiple lines if needed.
+        params: Optional dictionary of parameters to customize the crawl.
+                See API docs for details.
+        idempotency_key: Optional unique key to prevent duplicate jobs.
+
+    Returns:
+        A dictionary containing the job initiation response on success,
+        or a string containing an error message on failure. This description
+        can also span multiple lines.
+
+    Raises:
+        ValueError: If the URL is invalid.
+        requests.exceptions.ConnectionError: If connection fails.
+
+    Tags:
+        crawl, async_job, start, api,  long_tag_example , another
+        , final_tag
+"""
+
+if __name__ == "__main__":
+    parsed = parse_docstring(docstring_example)
+    import json
+
+    print(json.dumps(parsed, indent=4))

universal_mcp/utils/dump_app_tools.py

@@ -7,62 +7,72 @@ from universal_mcp.applications import app_from_slug
 def discover_available_app_slugs():
     apps_dir = Path(__file__).resolve().parent.parent / "applications"
     app_slugs = []
-    
+
     for item in apps_dir.iterdir():
-        if not item.is_dir() or item.name.startswith('_'):
+        if not item.is_dir() or item.name.startswith("_"):
             continue
-        
+
         if (item / "app.py").exists():
             slug = item.name.replace("_", "-")
             app_slugs.append(slug)
-    
+
     return app_slugs
 
+
 def extract_app_tools(app_slugs):
     all_apps_tools = []
-    
+
     for slug in app_slugs:
         try:
             print(f"Loading app: {slug}")
             app_class = app_from_slug(slug)
-            
+
             app_instance = app_class(integration=None)
-            
+
             tools = app_instance.list_tools()
-            
+
             for tool in tools:
                 tool_name = tool.__name__
-                description = tool.__doc__.strip().split('\n')[0] if tool.__doc__ else "No description"
-                
-                all_apps_tools.append({
-                    "app_name": slug,
-                    "tool_name": tool_name,
-                    "description": description
-                })
-                
+                description = (
+                    tool.__doc__.strip().split("\n")[0]
+                    if tool.__doc__
+                    else "No description"
+                )
+
+                all_apps_tools.append(
+                    {
+                        "app_name": slug,
+                        "tool_name": tool_name,
+                        "description": description,
+                    }
+                )
+
         except Exception as e:
             print(f"Error loading app {slug}: {e}")
-    
+
     return all_apps_tools
 
+
 def write_to_csv(app_tools, output_file="app_tools.csv"):
     fieldnames = ["app_name", "tool_name", "description"]
-    
-    with open(output_file, 'w', newline='') as csvfile:
+
+    with open(output_file, "w", newline="") as csvfile:
         writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
         writer.writeheader()
         writer.writerows(app_tools)
-    
+
     print(f"CSV file created: {output_file}")
 
+
 def main():
     app_slugs = discover_available_app_slugs()
     print(f"Found {len(app_slugs)} app slugs: {', '.join(app_slugs)}")
-    
+
     app_tools = extract_app_tools(app_slugs)
     print(f"Extracted {len(app_tools)} tools from all apps")
-    
+
     write_to_csv(app_tools)
 
+
 if __name__ == "__main__":
-    main()
+    main()

universal_mcp/utils/openapi.py

@@ -70,6 +70,33 @@ def determine_return_type(operation: dict[str, Any]) -> str:
     return "Any"
 
 
+def resolve_schema_reference(reference, schema):
+    """
+    Resolve a JSON schema reference to its target schema.
+
+    Args:
+        reference (str): The reference string (e.g., '#/components/schemas/User')
+        schema (dict): The complete OpenAPI schema that contains the reference
+
+    Returns:
+        dict: The resolved schema, or None if not found
+    """
+    if not reference.startswith("#/"):
+        return None
+
+    # Split the reference path and navigate through the schema
+    parts = reference[2:].split("/")
+    current = schema
+
+    for part in parts:
+        if part in current:
+            current = current[part]
+        else:
+            return None
+
+    return current
+
+
 def generate_api_client(schema):
     """
     Generate a Python API client class from an OpenAPI schema.
@@ -130,7 +157,7 @@ def generate_api_client(schema):
             if method in ["get", "post", "put", "delete", "patch", "options", "head"]:
                 operation = path_info[method]
                 method_code, func_name = generate_method_code(
-                    path, method, operation, tool_name
+                    path, method, operation, schema, tool_name
                 )
                 methods.append(method_code)
                 method_names.append(func_name)
@@ -164,7 +191,7 @@ def generate_api_client(schema):
     return class_code
 
 
-def generate_method_code(path, method, operation, tool_name=None):
+def generate_method_code(path, method, operation, full_schema, tool_name=None):
     """
     Generate the code for a single API method.
 
@@ -172,14 +199,15 @@ def generate_method_code(path, method, operation, tool_name=None):
         path (str): The API path (e.g., '/users/{user_id}').
         method (str): The HTTP method (e.g., 'get').
         operation (dict): The operation details from the schema.
+        full_schema (dict): The complete OpenAPI schema, used for reference resolution.
         tool_name (str, optional): The name of the tool/app to prefix the function name with.
 
     Returns:
         tuple: (method_code, func_name) - The Python code for the method and its name.
     """
     # Extract path parameters from the URL path
-    path_params_in_url = re.findall(r'{([^}]+)}', path)
-    
+    path_params_in_url = re.findall(r"{([^}]+)}", path)
+
     # Determine function name
     if "operationId" in operation:
         raw_name = operation["operationId"]
@@ -195,42 +223,179 @@ def generate_method_code(path, method, operation, tool_name=None):
             else:
                 name_parts.append(part)
         func_name = "_".join(name_parts).replace("-", "_").lower()
-    
-   
-   
-    func_name = re.sub(r'_a([^_])', r'_a_\1', func_name)  # Fix for patterns like retrieve_ablock
-    func_name = re.sub(r'_an([^_])', r'_an_\1', func_name)  # Fix for patterns like create_anitem
+
+    # Only fix isolated 'a' and 'an' as articles, not when they're part of words
+    func_name = re.sub(
+        r"_a([^_a-z])", r"_a_\1", func_name
+    )  # Fix for patterns like retrieve_ablock -> retrieve_a_block
+    func_name = re.sub(
+        r"_a$", r"_a", func_name
+    )  # Don't change if 'a' is at the end of the name
+    func_name = re.sub(
+        r"_an([^_a-z])", r"_an_\1", func_name
+    )  # Fix for patterns like create_anitem -> create_an_item
+    func_name = re.sub(
+        r"_an$", r"_an", func_name
+    )  # Don't change if 'an' is at the end of the name
 
     # Get parameters and request body
-    # Filter out header parameters
-    parameters = [param for param in operation.get("parameters", []) if param.get("in") != "header"]
+    # Resolve parameter references before processing
+    resolved_parameters = []
+    for param in operation.get("parameters", []):
+        if "$ref" in param:
+            # Resolve reference to actual parameter object
+            ref_param = resolve_schema_reference(param["$ref"], full_schema)
+            if ref_param:
+                resolved_parameters.append(ref_param)
+            else:
+                print(
+                    f"Warning: Could not resolve parameter reference: {param['$ref']}"
+                )
+        else:
+            resolved_parameters.append(param)
+
+    # Filter out header parameters from the resolved parameters
+    parameters = [param for param in resolved_parameters if param.get("in") != "header"]
+
     has_body = "requestBody" in operation
     body_required = has_body and operation["requestBody"].get("required", False)
 
+    # Check if the requestBody has actual content or is empty
+    has_empty_body = False
+    if has_body:
+        request_body_content = operation["requestBody"].get("content", {})
+        if not request_body_content or all(
+            not content for content_type, content in request_body_content.items()
+        ):
+            has_empty_body = True
+        else:
+            # Handle empty properties with additionalProperties:true
+            for content_type, content in request_body_content.items():
+                if content_type.startswith("application/json") and "schema" in content:
+                    schema = content["schema"]
+
+                    # Resolve schema reference if present
+                    if "$ref" in schema:
+                        ref_schema = resolve_schema_reference(
+                            schema["$ref"], full_schema
+                        )
+                        if ref_schema:
+                            schema = ref_schema
+
+                    # Check if properties is empty and additionalProperties is true
+                    if (
+                        schema.get("type") == "object"
+                        and schema.get("additionalProperties", False) is True
+                    ):
+                        properties = schema.get("properties", {})
+                        if not properties or len(properties) == 0:
+                            has_empty_body = True
+
+    # Extract request body schema properties and required fields
+    required_fields = []
+    request_body_properties = {}
+    is_array_body = False
+    array_items_schema = None
+
+    if has_body:
+        for content_type, content in (
+            operation["requestBody"].get("content", {}).items()
+        ):
+            if content_type.startswith("application/json") and "schema" in content:
+                schema = content["schema"]
+
+                # Resolve schema reference if present
+                if "$ref" in schema:
+                    ref_schema = resolve_schema_reference(schema["$ref"], full_schema)
+                    if ref_schema:
+                        schema = ref_schema
+
+                # Check if the schema is an array type
+                if schema.get("type") == "array":
+                    is_array_body = True
+                    array_items_schema = schema.get("items", {})
+                    # Try to resolve any reference in items
+                    if "$ref" in array_items_schema:
+                        array_items_schema = resolve_schema_reference(
+                            array_items_schema["$ref"], full_schema
+                        )
+                else:
+                    # Extract required fields from schema
+                    if "required" in schema:
+                        required_fields = schema["required"]
+                    # Extract properties from schema
+                    if "properties" in schema:
+                        request_body_properties = schema["properties"]
+
+                        # Check for nested references in properties
+                        for prop_name, prop_schema in request_body_properties.items():
+                            if "$ref" in prop_schema:
+                                ref_prop_schema = resolve_schema_reference(
+                                    prop_schema["$ref"], full_schema
+                                )
+                                if ref_prop_schema:
+                                    request_body_properties[prop_name] = ref_prop_schema
+
+                # Handle schemas with empty properties but additionalProperties: true
+                # by treating them similar to empty bodies
+                if (
+                    not request_body_properties or len(request_body_properties) == 0
+                ) and schema.get("additionalProperties") is True:
+                    has_empty_body = True
+
     # Build function arguments
     required_args = []
     optional_args = []
-    
-    
+
+    # Add path parameters
     for param_name in path_params_in_url:
         if param_name not in required_args:
             required_args.append(param_name)
 
-    
+    # Add query parameters
     for param in parameters:
         param_name = param["name"]
-        if param_name not in required_args:  
+        if param_name not in required_args:
             if param.get("required", False):
                 required_args.append(param_name)
             else:
                 optional_args.append(f"{param_name}=None")
 
-    # Add request body parameter
+    # Handle array type request body differently
+    request_body_params = []
     if has_body:
-        if body_required:
-            required_args.append("request_body")
-        else:
-            optional_args.append("request_body=None")
+        if is_array_body:
+            # For array request bodies, add a single parameter for the entire array
+            array_param_name = "items"
+            # Try to get a better name from the operation or path
+            if func_name.endswith("_list_input"):
+                array_param_name = func_name.replace("_list_input", "")
+            elif "List" in func_name:
+                array_param_name = func_name.split("List")[0].lower() + "_list"
+
+            # Make the array parameter required if the request body is required
+            if body_required:
+                required_args.append(array_param_name)
+            else:
+                optional_args.append(f"{array_param_name}=None")
+
+            # Remember this is an array param
+            request_body_params = [array_param_name]
+        elif request_body_properties:
+            # For object request bodies, add individual properties as parameters
+            for prop_name in request_body_properties:
+                if prop_name in required_fields:
+                    request_body_params.append(prop_name)
+                    if prop_name not in required_args:
+                        required_args.append(prop_name)
+                else:
+                    request_body_params.append(prop_name)
+                    if f"{prop_name}=None" not in optional_args:
+                        optional_args.append(f"{prop_name}=None")
+
+    # If request body is present but empty (content: {}), add a generic request_body parameter
+    if has_empty_body and "request_body=None" not in optional_args:
+        optional_args.append("request_body=None")
 
     # Combine required and optional arguments
     args = required_args + optional_args
@@ -245,19 +410,32 @@ def generate_method_code(path, method, operation, tool_name=None):
 
     # Validate required parameters including path parameters
     for param_name in required_args:
-        if param_name != "request_body":  # Skip validation for request body as it's handled separately
-            body_lines.append(f"        if {param_name} is None:")
-            body_lines.append(
-                f"            raise ValueError(\"Missing required parameter '{param_name}'\")"
-            )
-
-    # Validate required body
-    if has_body and body_required:
-        body_lines.append("        if request_body is None:")
+        body_lines.append(f"        if {param_name} is None:")
         body_lines.append(
-            '            raise ValueError("Missing required request body")'
+            f"            raise ValueError(\"Missing required parameter '{param_name}'\")"
         )
 
+    # Build request body (handle array and object types differently)
+    if has_body:
+        if is_array_body:
+            # For array request bodies, use the array parameter directly
+            body_lines.append("        # Use items array directly as request body")
+            body_lines.append(f"        request_body = {request_body_params[0]}")
+        elif request_body_properties:
+            # For object request bodies, build the request body from individual parameters
+
+            body_lines.append("        request_body = {")
+
+            for prop_name in request_body_params:
+                # Only include non-None values in the request body
+                body_lines.append(f"            '{prop_name}': {prop_name},")
+
+            body_lines.append("        }")
+
+            body_lines.append(
+                "        request_body = {k: v for k, v in request_body.items() if v is not None}"
+            )
+
     # Format URL directly with path parameters
     url_line = f'        url = f"{{self.base_url}}{path}"'
     body_lines.append(url_line)
@@ -276,30 +454,35 @@ def generate_method_code(path, method, operation, tool_name=None):
 
     # Make HTTP request using the proper method
     method_lower = method.lower()
+
+    # Determine what to use as the request body argument
+    if has_empty_body:
+        request_body_arg = "request_body"
+    elif not has_body:
+        request_body_arg = "{}"
+    else:
+        request_body_arg = "request_body"
+
     if method_lower == "get":
         body_lines.append("        response = self._get(url, params=query_params)")
     elif method_lower == "post":
-        if has_body:
-            body_lines.append("        response = self._post(url, data=request_body, params=query_params)")
-        else:
-            body_lines.append("        response = self._post(url, data={}, params=query_params)")
+        body_lines.append(
+            f"        response = self._post(url, data={request_body_arg}, params=query_params)"
+        )
     elif method_lower == "put":
-        if has_body:
-            body_lines.append("        response = self._put(url, data=request_body, params=query_params)")
-        else:
-            body_lines.append("        response = self._put(url, data={}, params=query_params)")
+        body_lines.append(
+            f"        response = self._put(url, data={request_body_arg}, params=query_params)"
+        )
     elif method_lower == "patch":
-        if has_body:
-            body_lines.append("        response = self._patch(url, data=request_body, params=query_params)")
-        else:
-            body_lines.append("        response = self._patch(url, data={}, params=query_params)")
+        body_lines.append(
+            f"        response = self._patch(url, data={request_body_arg}, params=query_params)"
+        )
     elif method_lower == "delete":
         body_lines.append("        response = self._delete(url, params=query_params)")
     else:
-        if has_body:
-            body_lines.append(f"        response = self._{method_lower}(url, data=request_body, params=query_params)")
-        else:
-            body_lines.append(f"        response = self._{method_lower}(url, data={{}}, params=query_params)")
+        body_lines.append(
+            f"        response = self._{method_lower}(url, data={request_body_arg}, params=query_params)"
+        )
 
     # Handle response
     body_lines.append("        response.raise_for_status()")