mcp-openapi-proxy 0.1.1741340797__py3-none-any.whl

mcp_openapi_proxy/__main__.py

@@ -0,0 +1,53 @@
+"""
+Entry point for the mcp_openapi_proxy package.
+
+This script determines which server to run based on the presence of
+the OPENAPI_SIMPLE_MODE environment variable:
+- Low-Level Server: For dynamic tool creation from OpenAPI spec.
+- FastMCP Server: For static tool configurations defined in code.
+"""
+ 
+import os
+import sys
+from dotenv import load_dotenv
+from mcp_openapi_proxy.utils import setup_logging
+ 
+# Load environment variables from .env if present
+load_dotenv()
+
+def main():
+    """
+    Main entry point for the mcp_openapi_proxy package.
+
+    Depending on the OPENAPI_SIMPLE_MODE environment variable, this function
+    launches either:
+    - Low-Level Server (dynamic tools from OpenAPI spec)
+    - FastMCP Server (static tools defined in server_fastmcp.py)
+    """
+    # Configure logging
+    DEBUG = os.getenv("DEBUG", "").lower() in ("true", "1", "yes")
+    logger = setup_logging(debug=DEBUG)
+
+    logger.debug("Starting mcp_openapi_proxy package entry point.")
+
+    # Default to Low-Level Mode unless SIMPLE_MODE is explicitly enabled
+    OPENAPI_SIMPLE_MODE = os.getenv("OPENAPI_SIMPLE_MODE", "false").lower() in ("true", "1", "yes") # Default to false, enable with "true" etc.
+    if OPENAPI_SIMPLE_MODE:
+        logger.debug("OPENAPI_SIMPLE_MODE is enabled. Launching FastMCP Server.")
+        from mcp_openapi_proxy.server_fastmcp import run_simple_server
+        selected_server = run_simple_server
+    else:
+        logger.debug("OPENAPI_SIMPLE_MODE is disabled. Launching Low-Level Server.")
+        from mcp_openapi_proxy.server_lowlevel import run_server
+        selected_server = run_server
+
+    # Run the selected server
+    try:
+        selected_server()
+    except Exception as e:
+        logger.critical("Unhandled exception occurred while running the server.", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

mcp_openapi_proxy/server_fastmcp.py

@@ -0,0 +1,250 @@
+"""
+Provides the FastMCP server logic for mcp-openapi-proxy.
+
+This server exposes a pre-defined set of functions based on an OpenAPI specification.
+Configuration is controlled via environment variables:
+
+- OPENAPI_SPEC_URL_<hash>: Unique URL per test, falls back to OPENAPI_SPEC_URL.
+- TOOL_WHITELIST: Comma-separated list of allowed endpoint paths.
+- SERVER_URL_OVERRIDE: (Optional) Overrides the base URL from the OpenAPI spec.
+- API_AUTH_BEARER: (Optional) Token for endpoints requiring authentication.
+- API_AUTH_TYPE_OVERRIDE: (Optional) 'Bearer' or 'Api-Key'.
+"""
+
+import os
+import sys
+import json
+import requests
+import logging
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s %(levelname)s %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S'
+)
+logger = logging.getLogger(__name__)
+
+logger.debug(f"Server CWD: {os.getcwd()}")
+logger.debug(f"Server sys.path: {sys.path}")
+
+from mcp.server.fastmcp import FastMCP
+from mcp_openapi_proxy.utils import setup_logging, is_tool_whitelisted, get_auth_type
+
+mcp = FastMCP("OpenApiProxy-Fast")
+
+def fetch_openapi_spec(spec_url: str) -> dict:
+    logger.debug(f"Starting fetch_openapi_spec with spec_url: {spec_url}")
+    if not spec_url:
+        logger.error("spec_url is empty or None")
+        return None
+    logger.debug(f"Current CWD in fetch_openapi_spec: {os.getcwd()}")
+    try:
+        if spec_url.startswith("file://"):
+            spec_path = os.path.abspath(spec_url.replace("file://", ""))
+            logger.debug(f"Spec path after file:// strip and abspath: {spec_path}")
+            if not os.path.exists(spec_path):
+                logger.error(f"File does not exist at: {spec_path}")
+                return None
+            logger.debug(f"File exists at: {spec_path}")
+            with open(spec_path, 'r') as f:
+                spec = json.load(f)
+            logger.debug(f"Successfully read local OpenAPI spec from {spec_path}")
+        else:
+            logger.debug(f"Fetching remote spec from {spec_url}")
+            response = requests.get(spec_url)
+            response.raise_for_status()
+            spec = json.loads(response.text)
+            logger.debug(f"Successfully fetched OpenAPI spec from {spec_url}")
+        if not spec:
+            logger.error(f"Spec is empty after loading from {spec_url}")
+            return None
+        logger.debug(f"Spec keys loaded: {list(spec.keys())}")
+        logger.debug(f"Spec paths: {list(spec.get('paths', {}).keys())}")
+        return spec
+    except Exception as e:
+        logger.error(f"Failed to fetch or parse spec from {spec_url}: {e}", exc_info=True)
+        return None
+
+@mcp.tool()
+def list_functions(*, env_key: str = "OPENAPI_SPEC_URL") -> str:
+    logger.debug("Executing list_functions tool.")
+    spec_url = os.environ.get(env_key, os.environ.get("OPENAPI_SPEC_URL"))
+    whitelist = os.getenv('TOOL_WHITELIST')
+    logger.debug(f"Using spec_url: {spec_url}")
+    logger.debug(f"TOOL_WHITELIST value: {whitelist}")
+    if not spec_url:
+        logger.error("No OPENAPI_SPEC_URL or custom env_key configured.")
+        return json.dumps([])
+    logger.debug(f"Calling fetch_openapi_spec with: {spec_url}")
+    spec = fetch_openapi_spec(spec_url)
+    if spec is None:
+        logger.error("Spec is None after fetch_openapi_spec")
+        return json.dumps([])
+    logger.debug(f"Raw spec loaded: {json.dumps(spec, indent=2)}")
+    logger.debug(f"Spec loaded with keys: {list(spec.keys())}")
+    paths = spec.get("paths", {})
+    logger.debug(f"Paths extracted from spec: {list(paths.keys())}")
+    if not paths:
+        logger.debug("No paths found in spec.")
+        return json.dumps([])
+    functions = []
+    for path, path_item in paths.items():
+        logger.debug(f"Processing path: {path}")
+        if not path_item:
+            logger.debug(f"Path item is empty for {path}")
+            continue
+        whitelist_check = is_tool_whitelisted(path)
+        logger.debug(f"Whitelist check for {path}: {whitelist_check}")
+        if not whitelist_check:
+            logger.debug(f"Path {path} not in whitelist - skipping.")
+            continue
+        for method, operation in path_item.items():
+            logger.debug(f"Found method: {method} for path: {path}")
+            if not method:
+                logger.debug(f"Method is empty for {path}")
+                continue
+            if method.lower() not in ["get", "post", "put", "delete", "patch"]:
+                logger.debug(f"Method {method} not supported for {path} - skipping.")
+                continue
+            function_name = f"{method.upper()} {path}"
+            function_description = operation.get("summary", operation.get("description", "No description provided."))
+            logger.debug(f"Registering function: {function_name} - {function_description}")
+            functions.append({
+                "name": function_name,
+                "description": function_description,
+                "path": path,
+                "method": method.upper(),
+                "operationId": operation.get("operationId")
+            })
+    logger.info(f"Discovered {len(functions)} functions from the OpenAPI specification.")
+    logger.debug(f"Functions list: {functions}")
+    return json.dumps(functions, indent=2)
+
+@mcp.tool()
+def call_function(*, function_name: str, parameters: dict = None, env_key: str = "OPENAPI_SPEC_URL") -> str:
+    logger.debug(f"call_function invoked with function_name='{function_name}' and parameters={parameters}")
+    if not function_name:
+        logger.error("function_name is empty or None")
+        return json.dumps({"error": "function_name is required"})
+    spec_url = os.environ.get(env_key, os.environ.get("OPENAPI_SPEC_URL"))
+    if not spec_url:
+        logger.error("No OPENAPI_SPEC_URL or custom env_key configured.")
+        return json.dumps({"error": "OPENAPI_SPEC_URL is not configured"})
+    logger.debug(f"Fetching spec for call_function: {spec_url}")
+    spec = fetch_openapi_spec(spec_url)
+    if spec is None:
+        logger.error("Spec is None for call_function")
+        return json.dumps({"error": "Failed to fetch or parse the OpenAPI specification"})
+    logger.debug(f"Spec keys for call_function: {list(spec.keys())}")
+    API_AUTH_TYPE = os.getenv("API_AUTH_TYPE_OVERRIDE", get_auth_type(spec))
+    logger.debug(f"API_AUTH_TYPE set to: {API_AUTH_TYPE}")
+    function_def = None
+    paths = spec.get("paths", {})
+    logger.debug(f"Paths for function lookup: {list(paths.keys())}")
+    for path, path_item in paths.items():
+        logger.debug(f"Checking path: {path}")
+        for method, operation in path_item.items():
+            logger.debug(f"Checking method: {method} for {path}")
+            if method.lower() not in ["get", "post", "put", "delete", "patch"]:
+                logger.debug(f"Skipping unsupported method: {method}")
+                continue
+            current_function_name = f"{method.upper()} {path}"
+            logger.debug(f"Comparing {current_function_name} with {function_name}")
+            if current_function_name == function_name:
+                function_def = {
+                    "path": path,
+                    "method": method.upper(),
+                    "operation": operation
+                }
+                logger.debug(f"Matched function definition for '{function_name}': {function_def}")
+                break
+        if function_def:
+            break
+    if not function_def:
+        logger.error(f"Function '{function_name}' not found in the OpenAPI specification.")
+        return json.dumps({"error": f"Function '{function_name}' not found"})
+    logger.debug(f"Function def found: {function_def}")
+    if not is_tool_whitelisted(function_def["path"]):
+        logger.error(f"Access to function '{function_name}' is not allowed.")
+        return json.dumps({"error": f"Access to function '{function_name}' is not allowed"})
+    SERVER_URL_OVERRIDE = os.getenv("SERVER_URL_OVERRIDE")
+    if SERVER_URL_OVERRIDE:
+        base_url = SERVER_URL_OVERRIDE.strip()
+        logger.debug(f"Using SERVER_URL_OVERRIDE: {base_url}")
+    else:
+        servers = spec.get("servers", [])
+        logger.debug(f"Servers from spec: {servers}")
+        if servers:
+            base_url = servers[0].get("url", "")
+            logger.debug(f"Using base_url from OpenAPI 3.0 servers: {base_url}")
+        else:
+            schemes = spec.get("schemes", ["https"])
+            host = spec.get("host", "example.com")
+            base_url = f"{schemes[0]}://{host}"
+            logger.debug(f"Using Swagger 2.0 fallback base_url: {base_url}")
+        if not base_url:
+            logger.warning("No valid base URL found in spec or override; using empty string.")
+            base_url = ""
+    base_url = base_url.rstrip("/")
+    logger.debug(f"Normalized base_url: {base_url}")
+    base_path = spec.get("basePath", "")
+    if base_path:
+        base_path = "/" + base_path.strip("/")
+        logger.debug(f"Normalized base_path: {base_path}")
+        if base_path not in base_url:
+            base_url = base_url + base_path
+            logger.debug(f"Added base_path to URL: {base_url}")
+    path = function_def["path"]
+    path = "/" + path.lstrip("/")
+    logger.debug(f"Normalized path: {path}")
+    api_url = base_url + path
+    logger.debug(f"Final API URL: {api_url}")
+    request_params = {}
+    request_body = None
+    headers = {"Content-Type": "application/json"}
+    if parameters is None:
+        logger.debug("Parameters is None, using empty dict")
+        parameters = {}
+    logger.debug(f"Parameters received: {parameters}")
+    if parameters:
+        if function_def["method"] == "GET":
+            request_params = parameters
+            logger.debug(f"Set request_params for GET: {request_params}")
+        else:
+            request_body = parameters
+            logger.debug(f"Set request_body: {request_body}")
+    api_auth = os.getenv("API_AUTH_BEARER")
+    if api_auth:
+        headers["Authorization"] = f"{API_AUTH_TYPE} {api_auth}"
+        logger.debug(f"Added Authorization header with {API_AUTH_TYPE}")
+    logger.debug(f"Sending request - Method: {function_def['method']}, URL: {api_url}, Headers: {headers}, Params: {request_params}, Body: {request_body}")
+    try:
+        response = requests.request(
+            method=function_def["method"],
+            url=api_url,
+            headers=headers,
+            params=request_params if function_def["method"] == "GET" else None,
+            json=request_body if function_def["method"] != "GET" and request_body else None
+        )
+        response.raise_for_status()
+        logger.debug(f"API response received: {response.text}")
+        return response.text
+    except requests.exceptions.RequestException as e:
+        logger.error(f"API request failed: {e}", exc_info=True)
+        return json.dumps({"error": f"API request failed: {e}"})
+
+def run_simple_server():
+    logger.debug("Starting run_simple_server")
+    spec_url = os.environ.get("OPENAPI_SPEC_URL")
+    if not spec_url:
+        logger.error("OPENAPI_SPEC_URL environment variable is required for FastMCP mode.")
+        sys.exit(1)
+    try:
+        logger.debug("Starting MCP server (FastMCP version)...")
+        mcp.run(transport="stdio")
+    except Exception as e:
+        logger.error("Unhandled exception in MCP server (FastMCP): %s", e, exc_info=True)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    run_simple_server()

mcp_openapi_proxy/server_lowlevel.py

@@ -0,0 +1,283 @@
+"""
+Low-Level Server for mcp-openapi-proxy.
+
+This server dynamically registers functions (tools) based on an OpenAPI specification,
+directly utilizing the spec for tool definitions and invocation.
+"""
+
+import os
+import sys
+import asyncio
+import json
+import requests
+from typing import List, Dict, Any
+from mcp import types
+from mcp.server.lowlevel import Server
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+from mcp_openapi_proxy.utils import setup_logging, fetch_openapi_spec, normalize_tool_name, is_tool_whitelisted
+
+# Configure logging
+DEBUG = os.getenv("DEBUG", "").lower() in ("true", "1", "yes")
+logger = setup_logging(debug=DEBUG)
+
+# Global function (tool) list
+tools: List[types.Tool] = []
+openapi_spec_data = None  # Store OpenAPI spec globally (or use caching)
+
+# Initialize the Low-Level MCP Server
+mcp = Server("OpenApiProxy-LowLevel")
+
+
+async def dispatcher_handler(request: types.CallToolRequest) -> types.ServerResult:
+    """
+    Dispatcher handler that routes CallToolRequest to the appropriate function (tool)
+    and makes the actual API call, now handling path parameters.
+    """
+    global openapi_spec_data
+
+    try:
+        function_name = request.params.name
+        logger.debug(f"Dispatcher received CallToolRequest for function: {function_name}")
+
+        tool = next((tool for tool in tools if tool.name == function_name), None)
+        if not tool:
+            logger.error(f"Unknown function requested: {function_name}")
+            return types.ServerResult(
+                root=types.CallToolResult(
+                    content=[types.TextContent(type="text", text="Unknown function requested")]
+                )
+            )
+
+        arguments = request.params.arguments
+        logger.debug(f"Function arguments: {arguments}")
+
+        operation_details = lookup_operation_details(function_name, openapi_spec_data)
+        if not operation_details:
+            return types.ServerResult(
+                root=types.CallToolResult(
+                    content=[types.TextContent(type="text", text=f"Could not find OpenAPI operation for function: {function_name}")]
+                )
+            )
+
+        path = operation_details['path']
+        method = operation_details['method']
+        operation = operation_details['operation']
+
+        # Construct API request URL
+        base_url = openapi_spec_data.get('servers', [{}])[0].get('url', '').rstrip('/')
+        api_url = base_url + path
+        path_params = {}  # Dictionary to hold path parameters
+
+        # Extract path parameters from arguments and replace in URL
+        if arguments and 'parameters' in arguments:
+            path_params_in_openapi = [
+                param['name'] for param in operation.get('parameters', []) if param['in'] == 'path'
+            ]
+            for param_name in path_params_in_openapi:
+                if param_name in arguments['parameters']:
+                    path_params[param_name] = arguments['parameters'].pop(param_name)  # Remove from arguments as it's a path param
+                    api_url = api_url.replace(f"{{{param_name}}}", str(path_params[param_name]))  # Replace placeholder in URL
+
+        # Prepare remaining parameters as query parameters (after removing path params)
+        query_params = {}
+        headers = {}
+        auth_token = os.getenv("API_AUTH_BEARER")
+        if auth_token:
+            headers["Authorization"] = "Bearer " + auth_token
+        request_body = None
+
+        if arguments and 'parameters' in arguments:  # 'parameters' now only contains query params (after path params removed)
+            query_params = arguments['parameters'].copy()
+
+        logger.debug(f"API Request URL: {api_url}")
+        logger.debug(f"Request Method: {method}")
+        logger.debug(f"Path Parameters: {path_params}")
+        logger.debug(f"Query Parameters: {query_params}")
+
+        try:
+            response = requests.request(
+                method=method,
+                url=api_url,
+                params=query_params if query_params else None,
+                headers=headers,
+                json=request_body if request_body else None
+            )
+            response.raise_for_status()
+
+            try:
+                response_data = response.json()
+            except json.JSONDecodeError:
+                response_data = response.text
+
+            return types.ServerResult(
+                root=types.CallToolResult(
+                    content=[types.TextContent(type="text", text=json.dumps({
+                        "status_code": response.status_code,
+                        "headers": dict(response.headers),
+                        "body": response_data
+                    }, indent=2))]
+                )
+            )
+
+        except requests.exceptions.RequestException as e:
+            logger.error(f"API request failed: {e}")
+            return types.ServerResult(
+                root=types.CallToolResult(
+                    content=[types.TextContent(type="text", text=json.dumps({
+                        "error": f"API request failed: {e}"
+                    }, indent=2))]
+                )
+            )
+
+    except Exception as e:
+        logger.error(f"Unhandled exception in dispatcher_handler: {e}", exc_info=True)
+        return types.ServerResult(
+            root=types.CallToolResult(
+                content=[types.TextContent(type="text", text=json.dumps({"error": "Internal server error."}, indent=2))]
+            )
+        )
+
+
+async def list_tools(request: types.ListToolsRequest) -> types.ServerResult:
+    """
+    Handler for ListToolsRequest to list all registered functions (tools).
+    """
+    logger.debug("Handling list_tools request.")
+    return types.ServerResult(root=types.ListToolsResult(tools=tools))
+
+
+def register_functions(spec: Dict) -> List[types.Tool]:
+    """
+    Register functions (tools) dynamically based on the OpenAPI specification.
+    No longer stores metadata in tool.metadata, relies on spec lookup.
+    """
+    global tools
+    tools = []  # Clear existing functions before re-registration
+
+    if not spec or 'paths' not in spec:
+        logger.warning("No paths found in OpenAPI spec, no functions registered.")
+        return tools
+
+    for path, path_item in spec['paths'].items():
+        if not is_tool_whitelisted(path):
+            logger.debug(f"Skipping non-whitelisted path: {path}")
+            continue
+        for method, operation in path_item.items():
+            if method.lower() not in ['get', 'post', 'put', 'delete', 'patch']:
+                continue  # Skip OPTIONS, HEAD etc.
+
+            try:
+                # Create a function name from method and path
+                function_name = normalize_tool_name(f"{method.upper()} {path}")  # Normalize function name
+
+                description = operation.get('summary', operation.get('description', 'No description available'))
+
+                # Define a generic input schema - you can expand on this later
+                input_schema = {
+                    "type": "object",
+                    "properties": {
+                        "parameters": {  # Generic 'parameters' field for now
+                            "type": "object",
+                            "description": "Parameters for the API call",
+                            "additionalProperties": True  # Allow any properties for parameters
+                        }
+                    },
+                    "additionalProperties": False  # No other top-level properties allowed
+                }
+
+                tool = types.Tool(
+                    name=function_name,
+                    description=description,
+                    inputSchema=input_schema,
+                )
+                tools.append(tool)
+                logger.debug(f"Registered function: {function_name} ({method.upper()} {path})")
+
+            except Exception as e:
+                logger.error(f"Error registering function for {method.upper()} {path}: {e}")
+
+    logger.info(f"Registered {len(tools)} functions from OpenAPI spec.")
+    return tools
+
+
+def lookup_operation_details(function_name: str, spec: Dict) -> Dict or None:
+    """
+    Lookup OpenAPI operation details (path, method, operation) based on function name.
+    """
+    if not spec or 'paths' not in spec:
+        return None
+
+    for path, path_item in spec['paths'].items():
+        for method, operation in path_item.items():
+            if method.lower() not in ['get', 'post', 'put', 'delete', 'patch']:
+                continue
+
+            current_function_name = normalize_tool_name(f"{method.upper()} {path}")
+            if current_function_name == function_name:
+                return {
+                    "path": path,
+                    "method": method.upper(),
+                    "operation": operation
+                }
+    return None
+
+
+async def start_server():
+    """
+    Start the Low-Level MCP server.
+    """
+    logger.debug("Starting Low-Level MCP server...")
+    try:
+        async with stdio_server() as (read_stream, write_stream):
+            await mcp.run(
+                read_stream,
+                write_stream,
+                initialization_options=InitializationOptions(
+                    server_name="AnyOpenAPIMCP-LowLevel",
+                    server_version="0.1.0",
+                    capabilities=types.ServerCapabilities(),
+                ),
+            )
+    except Exception as e:
+        logger.critical(f"Unhandled exception in MCP server: {e}", e)
+        sys.exit(1)
+
+
+def run_server():
+    """
+    Run the Low-Level Any OpenAPI server.
+    Fetches OpenAPI spec, registers functions, and makes it available globally.
+    """
+    global openapi_spec_data  # To store it globally
+
+    try:
+        openapi_url = os.getenv('OPENAPI_SPEC_URL', 'https://raw.githubusercontent.com/seriousme/fastify-openapi-glue/refs/heads/master/examples/petstore/petstore-openapi.v3.json')  # Example URL
+        openapi_spec_data = fetch_openapi_spec(openapi_url)  # Fetch and store globally
+        if not openapi_spec_data:
+            raise ValueError("Failed to fetch or parse OpenAPI specification.")
+        logger.info("OpenAPI specification fetched successfully.")
+
+        register_functions(openapi_spec_data)  # Register functions after fetching spec
+
+    except Exception as e:
+        logger.critical(f"Failed to start server: {e}")
+        sys.exit(1)
+
+    mcp.request_handlers[types.ListToolsRequest] = list_tools
+    logger.debug("Registered list_tools handler.")
+
+    mcp.request_handlers[types.CallToolRequest] = dispatcher_handler
+    logger.debug("Registered dispatcher_handler for CallToolRequest.")
+
+    try:
+        asyncio.run(start_server())
+    except KeyboardInterrupt:
+        logger.debug("MCP server shutdown initiated by user.")
+    except Exception as e:
+        logger.critical("Failed to start MCP server: %s", e)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_server()

mcp_openapi_proxy/utils.py

@@ -0,0 +1,255 @@
+"""
+Utility functions for mcp_openapi_proxy, including logging setup,
+OpenAPI fetching, name normalization, and whitelist filtering for tools.
+"""
+
+import os
+import sys
+import logging
+import requests
+import re
+import json
+import yaml
+from dotenv import load_dotenv
+
+# Load environment variables from .env if present
+load_dotenv()
+
+OPENAPI_SPEC_URL = os.getenv("OPENAPI_SPEC_URL")
+
+def setup_logging(debug: bool = False, log_dir: str = None, log_file: str = "debug-mcp-any-openapi.log") -> logging.Logger:
+    """
+    Sets up logging for the application, including outputting CRITICAL and ERROR logs to stdout.
+
+    Args:
+        debug (bool): If True, sets log level to DEBUG; otherwise, INFO.
+        log_dir (str): Directory where log files will be stored. Ignored if OPENAPI_LOGFILE_PATH is set.
+        log_file (str): Name of the log file. Ignored if OPENAPI_LOGFILE_PATH is set.
+
+    Returns:
+        logging.Logger: Configured logger instance.
+    """
+    log_path = os.getenv("OPENAPI_LOGFILE_PATH")
+    if not log_path:
+        if log_dir is None:
+            log_dir = os.path.join(os.path.expanduser("~"), "mcp_logs")
+        try:
+            os.makedirs(log_dir, exist_ok=True)
+            log_path = os.path.join(log_dir, log_file)
+        except PermissionError as e:
+            log_path = None
+            print(f"[ERROR] Failed to create log directory: {e}", file=sys.stderr)
+    logger = logging.getLogger(__name__)
+    logger.setLevel(logging.DEBUG if debug else logging.INFO)
+    logger.propagate = False
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+    handlers = []
+    if log_path:
+        try:
+            file_handler = logging.FileHandler(log_path, mode="a")
+            file_handler.setLevel(logging.DEBUG if debug else logging.INFO)
+            formatter = logging.Formatter("[%(levelname)s] %(asctime)s - %(message)s")
+            file_handler.setFormatter(formatter)
+            handlers.append(file_handler)
+        except Exception as e:
+            print(f"[ERROR] Failed to create log file handler: {e}", file=sys.stderr)
+    try:
+        stdout_handler = logging.StreamHandler(sys.stdout)
+        stdout_handler.setLevel(logging.ERROR)
+        formatter = logging.Formatter("[%(levelname)s] %(message)s")
+        stdout_handler.setFormatter(formatter)
+        handlers.append(stdout_handler)
+    except Exception as e:
+        print(f"[ERROR] Failed to create stdout log handler: {e}", file=sys.stderr)
+    for handler in handlers:
+        logger.addHandler(handler)
+    if log_path:
+        logger.debug(f"Logging initialized. Writing logs to {log_path}")
+    else:
+        logger.debug("Logging initialized. Logs will only appear in stdout.")
+    return logger
+
+DEBUG = os.getenv("DEBUG", "").lower() in ("true", "1", "yes")
+logger = setup_logging(debug=DEBUG)
+
+logger.debug(f"OpenAPI Spec URL: {OPENAPI_SPEC_URL}")
+logger.debug("utils.py initialized")
+
+def redact_api_key(key: str) -> str:
+    """
+    Redacts an API key for secure logging.
+
+    Args:
+        key (str): The API key or secret.
+
+    Returns:
+        str: The redacted API key, or '<not set>' if key is invalid.
+    """
+    if not key or len(key) <= 4:
+        return "<not set>"
+    return f"{key[:2]}{'*' * (len(key) - 4)}{key[-2:]}"
+
+def normalize_tool_name(name: str) -> str:
+    """
+    Normalizes tool names by converting to lowercase and replacing non-alphanumeric characters with underscores.
+
+    Args:
+        name (str): The original tool name.
+
+    Returns:
+        str: A normalized tool name. Returns 'unknown_tool' if input is invalid.
+    """
+    logger = logging.getLogger(__name__)
+    if not name or not isinstance(name, str):
+        logger.warning(f"Invalid tool name input: {name}. Using default 'unknown_tool'.")
+        return "unknown_tool"
+    normalized = re.sub(r"[^a-zA-Z0-9_]", "_", name).lower()
+    normalized = re.sub(r"_+", "_", normalized)
+    normalized = normalized.strip('_')
+    logger.debug(f"Normalized tool name from '{name}' to '{normalized}'")
+    return normalized or "unknown_tool"
+
+def get_tool_prefix() -> str:
+    """
+    Obtains the tool name prefix from the environment variable, ensuring it ends with an underscore.
+
+    Returns:
+        str: The tool name prefix.
+    """
+    prefix = os.getenv("TOOL_NAME_PREFIX", "")
+    if prefix and not prefix.endswith("_"):
+        prefix += "_"
+    return prefix
+
+def is_tool_whitelisted(endpoint: str) -> bool:
+    """
+    Checks if an endpoint is in the TOOL_WHITELIST, supporting exact matches, prefixes, and path parameters.
+
+    Args:
+        endpoint (str): The API endpoint path to check.
+
+    Returns:
+        bool: True if whitelisted or no whitelist set, False otherwise.
+    """
+    whitelist = os.getenv("TOOL_WHITELIST", "")
+    logger.debug(f"Checking whitelist - endpoint: {endpoint}, TOOL_WHITELIST: {whitelist}")
+    if not whitelist:
+        logger.debug("No TOOL_WHITELIST set, allowing all endpoints.")
+        return True
+    
+    whitelist_items = [item.strip() for item in whitelist.split(",") if item.strip()]
+    
+    # Direct match
+    if endpoint in whitelist_items:
+        logger.debug(f"Direct match found for {endpoint} in whitelist")
+        return True
+    
+    # Prefix match (e.g., /tasks matches /tasks/123)
+    for item in whitelist_items:
+        if not '{' in item and endpoint.startswith(item):
+            logger.debug(f"Prefix match found: {item} starts {endpoint}")
+            return True
+    
+    # Path parameter match (e.g., /sessions/{sessionId} matches /sessions/abc123 or /sessions/abc123/items)
+    for item in whitelist_items:
+        if '{' in item and '}' in item:
+            pattern = re.escape(item)
+            pattern = pattern.replace(r"\{", "{").replace(r"\}", "}")
+            pattern = re.sub(r"\{[^}]+\}", r"[^/]+", pattern)
+            pattern = f"^{pattern}(/.*)?$"  # Allow optional trailing segments
+            if re.match(pattern, endpoint):
+                logger.debug(f"Pattern match found for {endpoint} using {item}")
+                return True
+                
+    logger.debug(f"No whitelist match found for {endpoint}")
+    return False
+
+def fetch_openapi_spec(spec_url: str) -> dict:
+    """
+    Fetches and parses an OpenAPI specification from a URL or local file, supporting JSON and YAML.
+
+    Args:
+        spec_url (str): The URL or file path (e.g., file:///path/to/spec.json) of the OpenAPI spec.
+
+    Returns:
+        dict: The parsed OpenAPI specification, or None if an error occurs.
+    """
+    logger = logging.getLogger(__name__)
+    try:
+        if spec_url.startswith("file://"):
+            spec_path = spec_url.replace("file://", "")
+            with open(spec_path, 'r') as f:
+                content = f.read()
+            logger.debug(f"Read local OpenAPI spec from {spec_path}")
+        else:
+            response = requests.get(spec_url)
+            response.raise_for_status()
+            content = response.text
+            logger.debug(f"Fetched OpenAPI spec from {spec_url}")
+
+        if spec_url.endswith(('.yaml', '.yml')):
+            spec = yaml.safe_load(content)
+            logger.debug(f"Parsed YAML OpenAPI spec from {spec_url}")
+        else:
+            spec = json.loads(content)
+            logger.debug(f"Parsed JSON OpenAPI spec from {spec_url}")
+        return spec
+    except requests.exceptions.RequestException as e:
+        logger.error(f"Error fetching OpenAPI spec from {spec_url}: {e}")
+        return None
+    except (json.JSONDecodeError, yaml.YAMLError) as e:
+        logger.error(f"Error parsing OpenAPI spec from {spec_url}: {e}")
+        return None
+    except FileNotFoundError as e:
+        logger.error(f"Local file not found for OpenAPI spec at {spec_url}: {e}")
+        return None
+    except Exception as e:
+        logger.error(f"Unexpected error with OpenAPI spec from {spec_url}: {e}")
+        return None
+
+def get_auth_type(spec: dict) -> str:
+    """
+    Determines the authentication type from the OpenAPI spec's securityDefinitions.
+
+    Args:
+        spec (dict): The OpenAPI specification.
+
+    Returns:
+        str: 'Api-Key' if apiKey auth is defined in Authorization header, 'Bearer' otherwise.
+    """
+    security_defs = spec.get("securityDefinitions", {})
+    for name, definition in security_defs.items():
+        if definition.get("type") == "apiKey" and definition.get("in") == "header" and definition.get("name") == "Authorization":
+            logger.debug(f"Detected ApiKeyAuth in spec: {name}")
+            return "Api-Key"
+    logger.debug("No ApiKeyAuth found in spec, defaulting to Bearer")
+    return "Bearer"
+
+def map_schema_to_tools(schema: dict) -> list:
+    """
+    Maps a given schema to a list of MCP tools.
+
+    Args:
+        schema (dict): The schema containing a list of classes.
+
+    Returns:
+        list: A list of tool objects configured from the schema.
+    """
+    from mcp import types
+    tools = []
+    classes = schema.get("classes", [])
+    for entry in classes:
+        cls = entry.get("class", "")
+        if not cls:
+            continue
+        tool_name = normalize_tool_name(cls)
+        prefix = os.getenv("TOOL_NAME_PREFIX", "")
+        if prefix:
+            if not prefix.endswith("_"):
+                prefix += "_"
+            tool_name = prefix + tool_name
+        description = f"Tool for class {cls}: " + json.dumps(entry)
+        tool = types.Tool(name=tool_name, description=description, inputSchema={"type": "object"})
+        tools.append(tool)
+    return tools

mcp_openapi_proxy-0.1.1741340797.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mhand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_openapi_proxy-0.1.1741340797.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.2
+Name: mcp-openapi-proxy
+Version: 0.1.1741340797
+Summary: MCP server for exposing OpenAPI specifications as MCP tools.
+Author-email: Matthew Hand <matthewhandau@gmail.com>
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: requests>=2.25.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: prance>=23.6.21.0
+Requires-Dist: openapi-spec-validator>=0.7.1
+
+# mcp-openapi-proxy
+
+**mcp-openapi-proxy** is a Python package implementing a Model Context Protocol (MCP) server that dynamically exposes REST APIs defined by OpenAPI specifications as MCP tools. This allows you to easily integrate any OpenAPI-described API into MCP-based workflows.
+
+## Overview
+
+The package supports two operation modes:
+
+- **Low-Level Mode (Default):** Dynamically registers tools for all API endpoints defined in an OpenAPI specification eg. /chat/completions becomes chat_completions().
+- **FastMCP Mode (Simple Mode):** Provides a simplified mode for exposing specific pre-configured API endpoints as tools ie. list_functions() and call_functions().
+
+## Features
+
+- **Dynamic Tool Generation:** Automatically creates MCP tools from OpenAPI endpoint definitions.
+- **Simple Mode Option:** Offers a static configuration option with FastMCP mode.
+- **OpenAPI Specification Support:** Works with OpenAPI v3 specifications, and potentially v2.
+- **Flexible Filtering:** Supports filtering endpoints by tags, paths, methods, etc. (if implemented)
+- **MCP Integration:** Integrates seamlessly with MCP ecosystems to invoke REST APIs as tools.
+
+## Installation
+
+### MCP Ecosystem Integration
+
+Add **mcp-openapi-proxy** to your MCP ecosystem by configuring your `mcpServers`. Generic example:
+
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
+                "API_AUTH_BEARER": "",
+                "TOOL_WHITELIST": "",
+                "TOOL_NAME_PREFIX": ""
+            }
+        }
+    }
+}
+```
+
+For examples of real world APIs like GetZep, Open-Webui, Netlify, Vercel, etc refer to [examples](./examples).
+
+
+## Modes of Operation
+
+### FastMCP Mode (Simple Mode)
+
+- **Enabled by:** Setting `OPENAPI_SIMPLE_MODE=true`
+- **Description:** Exposes a pre-defined set of tools based on specific OpenAPI endpoints defined in code.
+- **Configuration:** Requires environment variables for tool definitions.
+
+### Low-Level Mode (Default)
+
+- **Description:** Dynamically registers all valid API endpoints from the provided OpenAPI specification as separate tools.
+- **Tool Naming:** Tools are named based on normalized OpenAPI path and method.
+- **Behavior:** Descriptions are generated from the OpenAPI operation summaries and descriptions.
+
+## Environment Variables
+
+- `OPENAPI_SPEC_URL`: URL to the OpenAPI specification JSON file (required).
+- `OPENAPI_LOGFILE_PATH`: (Optional) Path for the log file.
+- `OPENAPI_SIMPLE_MODE`: (Optional) Set to `true` for FastMCP mode.
+- `TOOL_WHITELIST`: (Optional) A prefix filter to select only certain tools.
+- `TOOL_NAME_PREFIX`: (Optional) A string to prepend to all tool names when mapping.
+
+## Examples
+
+### OpenWebUI Example
+
+**1. Confirming the OpenAPI Endpoint**
+
+Run the following command to retrieve the OpenAPI specification:
+ 
+```bash
+curl http://localhost:3000/openapi.json
+```
+ 
+If the output is a valid OpenAPI JSON document, it confirms that the endpoint is working correctly.
+
+**2. Configuring mcp-openapi-proxy**
+
+In your MCP ecosystem configuration file, set the `OPENAPI_SPEC_URL` to the above endpoint. For example:
+ 
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "http://localhost:3000/openapi.json",
+                "SERVER_URL_OVERRIDE": "http://localhost:3000/v1",
+                "TOOL_WHITELIST": "/models,/chat/completion",
+                "API_AUTH_BEARER": "your_openwebui_token_here"
+            }
+        }
+    }
+}
+```
+ 
+- **OPENAPI_SPEC_URL**: The URL to the OpenAPI specification.
+- **SERVER_URL_OVERRIDE**: Should the spec not include servers, or you wish to use a different URL.
+- **TOOL_WHITELIST**: A comma-separated list of endpoint paths to expose as tools. In this example, only the `/api/models` and `/api/chat/completions` endpoints are allowed.
+- **API_AUTH_BEARER**: The bearer token for endpoints requiring authentication.  Alternatively use ${OPENWEBUI_API_KEY} if configured as an environment variable or stored securely in a `.env` file.
+
+**3. Resulting Tools**
+
+With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:
+
+```json
+[
+    {
+        "name": "api_models",
+        "description": "Fetches available models from /api/models"
+    },
+    {
+        "name": "api_chat_completions",
+        "description": "Generates chat completions via /api/chat/completions"
+    }
+]
+```
+ 
+**4. Visual Verification**
+ 
+You can verify the registration of these tools by inspecting the MCP server logs or using your MCP client.
+
+ 
+## Fly.io Example
+
+**1. Verify the OpenAPI Endpoint**
+
+Run the following command to retrieve the Fly.io OpenAPI JSON specification:
+
+```bash
+curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json
+```
+
+Ensure the response is a valid OpenAPI JSON document containing an "openapi" field (e.g., "openapi": "3.0.0") and defined API paths.
+
+**2. Configure mcp-openapi-proxy for Fly.io**
+
+Update your MCP ecosystem configuration to point to the Fly.io endpoint. For example:
+
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
+                "SERVER_URL_OVERRIDE": "https://api.machines.dev",
+                "TOOL_WHITELIST": "/machines/list,/machines/start,/machines/status",
+                "API_AUTH_BEARER": "${FLY_API_TOKEN}"
+            }
+        }
+    }
+}
+```
+
+**3. Resulting Tools**
+
+With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:
+ 
+```json
+[
+    {
+        "name": "machines_list",
+        "description": "Fetches machine listing from /machines/list"
+    },
+    {
+        "name": "machines_start",
+        "description": "Initiates machine start via /machines/start"
+    },
+    {
+        "name": "machines_status",
+        "description": "Retrieves machine status from /machines/status"
+    }
+]
+```
+
+## Troubleshooting
+
+- **Missing OPENAPI_SPEC_URL:** Verify that the `OPENAPI_SPEC_URL` environment variable is set and points to a valid OpenAPI JSON file.
+- **Invalid OpenAPI Spec:** Ensure the JSON specification complies with the OpenAPI standard.
+- **Filtering Issues:** Check that `TOOL_WHITELIST` is correctly defined to filter the desired classes.
+- **Logging:** Consult the logs (as defined by `MCP_OPENAPI_LOGFILE_PATH`) for debugging information.
+- **Verify `uvx`** Run the server directly from the GitHub repository using `uvx`:
+
+```bash
+uvx --from git+https://github.com/matthewhand/mcp-openapi-proxy mcp-openapi-proxy
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

mcp_openapi_proxy-0.1.1741340797.dist-info/RECORD

@@ -0,0 +1,11 @@
+mcp_openapi_proxy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_openapi_proxy/__main__.py,sha256=VIc087EhndsDqeRU5uVMrtxZMMapxfDih1KlpouF6r8,1867
+mcp_openapi_proxy/server_fastmcp.py,sha256=UEKz1vjX0FgkmCVl0Y9eFht4E-CfSd2MXSm004P8bVE,11400
+mcp_openapi_proxy/server_lowlevel.py,sha256=3atPZpIPMRzul4UCny73ycZoNorEnv6j-lhhApIIwu4,10947
+mcp_openapi_proxy/utils.py,sha256=3fgQi_IC5Cw8B57GRCDMwKqqidzDuaKawe3V5pxTonU,9495
+mcp_openapi_proxy-0.1.1741340797.dist-info/LICENSE,sha256=PjkyMZfBImLXpO5eKb_sI__W1JMf1jL51n1O7H4a1I0,1062
+mcp_openapi_proxy-0.1.1741340797.dist-info/METADATA,sha256=7UO-9toQSEOHNVtjMOPyr9SoxNoNs_g4CibxrZjj0CY,7976
+mcp_openapi_proxy-0.1.1741340797.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+mcp_openapi_proxy-0.1.1741340797.dist-info/entry_points.txt,sha256=d_nfFSGK0wyUwv01H4wjtOI45eo8CZ-XdKAbJOvnhFU,70
+mcp_openapi_proxy-0.1.1741340797.dist-info/top_level.txt,sha256=oLvmu0l9_s8gAkTCT5921baWF27hlPDr1i2SIopuOc8,18
+mcp_openapi_proxy-0.1.1741340797.dist-info/RECORD,,

mcp_openapi_proxy-0.1.1741340797.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_openapi_proxy-0.1.1741340797.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-openapi-proxy = mcp_openapi_proxy.__main__:main

mcp_openapi_proxy-0.1.1741340797.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_openapi_proxy