amazon-ads-mcp 0.2.7__py3-none-any.whl

amazon_ads_mcp/server/mcp_server.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""Amazon Ads MCP Server - Modular Implementation.
+
+This is a refactored version of the MCP server that uses modular components
+for better maintainability and testability.
+
+Implements the FastMCP server lifespan pattern for clean startup/shutdown.
+"""
+
+import argparse
+import asyncio
+import atexit
+import logging
+import os
+import signal
+import sys
+import types
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, Optional
+
+# Note: FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER removed in v0.1.18
+# The new OpenAPI parser is now standard in FastMCP 2.14.0+
+# See: https://gofastmcp.com/v2/development/upgrade-guide
+
+from ..utils.http import http_client_manager
+from ..utils.security import setup_secure_logging
+from .server_builder import ServerBuilder
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def server_lifespan(server: Any) -> AsyncIterator[None]:
+    """Server lifespan context manager for clean startup and shutdown.
+
+    This lifespan function handles all server initialization and cleanup
+    in a single, testable async context manager. It's passed to the FastMCP
+    constructor to ensure proper resource management.
+
+    FastMCP 2.14+ passes the server instance to lifespan functions, which
+    enables access to server state during startup/shutdown.
+
+    Startup:
+        - Validates authentication configuration
+        - Initializes HTTP client connections
+        - Logs server state
+
+    Shutdown:
+        - Closes all HTTP client connections
+        - Shuts down the authentication manager
+        - Performs graceful cleanup
+
+    Usage:
+        server = FastMCP("Server", lifespan=server_lifespan)
+
+    :param server: The FastMCP server instance (provided by FastMCP)
+    :yield: Control to the running server
+    :rtype: AsyncIterator[None]
+    """
+    _ = server  # Server instance available if needed for future enhancements
+    logger.info("Server lifespan: Starting up...")
+
+    # Startup phase
+    try:
+        # Log initial state
+        from ..auth.manager import get_auth_manager
+
+        auth_mgr = get_auth_manager()
+        if auth_mgr and auth_mgr.provider:
+            provider_type = getattr(auth_mgr.provider, "provider_type", "unknown")
+            logger.info(f"Auth provider initialized: {provider_type}")
+        else:
+            logger.warning("No auth provider configured")
+
+        logger.info("Server lifespan: Startup complete")
+    except Exception as e:
+        logger.error(f"Server lifespan: Startup error: {e}")
+        raise
+
+    try:
+        # Yield control to the running server
+        yield
+    finally:
+        # Shutdown phase - coordinate with fallback cleanup handlers
+        global _cleanup_done
+
+        if _cleanup_done:
+            logger.debug("Server lifespan: Cleanup already done by fallback handler")
+            return
+
+        logger.info("Server lifespan: Shutting down...")
+
+        # Close HTTP clients
+        try:
+            await http_client_manager.close_all()
+            logger.info("HTTP clients closed")
+        except Exception as e:
+            logger.error(f"Error closing HTTP clients: {e}")
+
+        # Close auth manager
+        try:
+            from ..auth.manager import get_auth_manager
+
+            am = get_auth_manager()
+            if am:
+                await am.close()
+                logger.info("Auth manager closed")
+        except Exception as e:
+            logger.error(f"Error closing auth manager: {e}")
+
+        # Mark cleanup done to prevent fallback handlers from running again
+        _cleanup_done = True
+        logger.info("Server lifespan: Shutdown complete")
+
+
+async def create_amazon_ads_server() -> Any:
+    """Create and configure the Amazon Ads MCP server using modular components.
+
+    This function creates a new Amazon Ads MCP server instance using the
+    modular ServerBuilder. The server is fully configured with builtin tools,
+    authentication middleware, and lifespan management.
+
+    The lifespan pattern (FastMCP 2.14+) handles:
+    - Clean startup with auth validation
+    - Graceful shutdown with resource cleanup
+    - HTTP client connection management
+    - Auth manager lifecycle
+
+    :return: Configured FastMCP server instance
+    :raises Exception: If server initialization fails
+
+    Examples
+    --------
+    .. code-block:: python
+
+        server = await create_amazon_ads_server()
+        await server.run()
+    """
+    # Pass the lifespan to the builder for clean startup/shutdown
+    builder = ServerBuilder(lifespan=server_lifespan)
+    server = await builder.build()
+
+    # Built-in tools are registered in ServerBuilder._setup_builtin_tools()
+    # FastMCP handles prompts automatically
+
+    logger.info("MCP server setup complete (lifespan pattern enabled)")
+    return server
+
+
+_cleanup_task = None
+_cleanup_done = False
+
+
+async def cleanup_resources_async() -> None:
+    """Perform async cleanup of server resources.
+
+    This function performs asynchronous cleanup of server resources including
+    HTTP client connections and authentication manager shutdown. It ensures
+    that cleanup is only performed once and handles errors gracefully.
+
+    :raises Exception: If cleanup operations fail
+    """
+    global _cleanup_done
+    if _cleanup_done:
+        return
+
+    logger.info("Shutting down server...")
+    try:
+        await http_client_manager.close_all()
+        logger.info("HTTP clients closed")
+    except Exception as e:
+        logger.error("Error closing http clients: %s", e)
+
+    try:
+        from ..auth.manager import get_auth_manager
+
+        am = get_auth_manager()
+        if am:
+            await am.close()
+            logger.info("Auth manager closed")
+    except Exception as e:
+        logger.error("Error closing auth manager: %s", e)
+
+    _cleanup_done = True
+
+
+def cleanup_sync() -> None:
+    """Synchronously clean up server resources.
+
+    This function performs cleanup operations for the server in a safe manner
+    that avoids creating new event loops in signal handlers.
+
+    The cleanup includes:
+    - Closing all HTTP client connections
+    - Shutting down the authentication manager
+    - Handling any cleanup errors gracefully
+    """
+    global _cleanup_task, _cleanup_done
+
+    if _cleanup_done:
+        return
+
+    # Try to schedule cleanup in existing event loop
+    try:
+        loop = asyncio.get_running_loop()
+        if not loop.is_closed() and not _cleanup_task:
+            _cleanup_task = loop.create_task(cleanup_resources_async())
+            logger.debug("Cleanup scheduled in running event loop")
+            return
+    except RuntimeError:
+        # No running loop - that's OK for signal handlers
+        pass
+
+    # For atexit (not signal handlers), we can try more thorough cleanup
+    frame: Optional[types.FrameType] = sys._getframe()
+    # Check if we're in a signal handler by inspecting the stack
+    in_signal = False
+    while frame:
+        if frame.f_code.co_name in (
+            "<module>",
+            "<lambda>",
+        ) and "signal" in str(frame.f_code.co_filename):
+            in_signal = True
+            break
+        frame = frame.f_back
+
+    if not in_signal and not _cleanup_done:
+        # Safe to create new event loop when not in signal handler
+        try:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            loop.run_until_complete(cleanup_resources_async())
+            loop.close()
+            logger.info("Cleanup complete via new event loop")
+        except Exception as e:
+            logger.debug(f"Could not perform sync cleanup: {e}")
+
+
+def main() -> None:
+    """Run the Amazon Ads MCP server.
+
+    This is the main entry point for the Amazon Ads MCP server. It parses
+    command line arguments, initializes logging, creates the server, and
+    starts it with the specified transport.
+
+    The function supports multiple transport modes:
+    - stdio: Standard input/output communication
+    - http: HTTP-based communication
+    - streamable-http: Server-sent events HTTP communication
+
+    :raises KeyboardInterrupt: If the server is stopped by user interrupt
+    :raises Exception: If server initialization or startup fails
+
+    Examples
+    --------
+    .. code-block:: bash
+
+        # Run with HTTP transport
+        python -m amazon_ads_mcp.server.mcp_server --transport http --port 9080
+
+        # Run with stdio transport
+        python -m amazon_ads_mcp.server.mcp_server --transport stdio
+    """
+    # Load environment variables from .env file if it exists
+    try:
+        from dotenv import load_dotenv
+
+        load_dotenv()
+    except ImportError:
+        pass
+
+    setup_secure_logging(level=os.environ.get("LOG_LEVEL", "INFO"))
+    logger.debug("Environment variables loaded")
+
+    parser = argparse.ArgumentParser(description="Amazon Ads MCP Server (Modular)")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http", "streamable-http"],
+        default="stdio",
+    )
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=9080)
+    args = parser.parse_args()
+
+    # Set the port in environment for OAuth redirect URI
+    if args.transport in ("http", "streamable-http"):
+        os.environ["PORT"] = str(args.port)
+
+    # Register cleanup handlers
+    atexit.register(cleanup_sync)
+    signal.signal(signal.SIGTERM, lambda *_: cleanup_sync())
+    signal.signal(signal.SIGINT, lambda *_: cleanup_sync())
+
+    logger.info("Creating Amazon Ads MCP server...")
+    mcp = asyncio.run(create_amazon_ads_server())
+
+    # Small delay to ensure server is fully initialized
+    import time
+
+    time.sleep(0.5)
+    logger.info("Server initialization complete")
+
+    try:
+        if args.transport in ("http", "streamable-http"):
+            transport = (
+                "streamable-http" if args.transport == "streamable-http" else "http"
+            )
+            logger.info("Starting %s server on %s:%d", transport, args.host, args.port)
+            # Use streamable-http transport which handles SSE properly
+            mcp.run(
+                transport=transport,
+                host=args.host,
+                port=args.port,
+                # Using default path to avoid redirect issues
+            )
+        else:
+            logger.info("Running in stdio mode")
+            mcp.run()
+    except KeyboardInterrupt:
+        logger.info("Server stopped by user")
+    finally:
+        cleanup_sync()
+
+
+if __name__ == "__main__":
+    main()

amazon_ads_mcp/server/openapi_utils.py

@@ -0,0 +1,158 @@
+"""OpenAPI utilities for the MCP server.
+
+This module provides utilities for processing OpenAPI specifications,
+including slimming large descriptions and managing spec resources.
+"""
+
+from typing import Any, Dict, Optional
+
+
+def truncate_text(text: Optional[str], max_len: int) -> Optional[str]:
+    """Truncate text to a maximum length with ellipsis.
+
+    :param text: Text to truncate
+    :type text: Optional[str]
+    :param max_len: Maximum length
+    :type max_len: int
+    :return: Truncated text or original if shorter
+    :rtype: Optional[str]
+    """
+    if not isinstance(text, str):
+        return text
+    if len(text) <= max_len:
+        return text
+    tail = "…"
+    return text[: max(0, max_len - len(tail))] + tail
+
+
+def slim_openapi_for_tools(spec: Dict[str, Any], max_desc: int = 200) -> None:
+    """Reduce large descriptions in OpenAPI operations and parameters.
+
+    This helps keep tool metadata small when clients ingest tool definitions.
+    Modifies the spec in place.
+
+    :param spec: OpenAPI specification to slim
+    :type spec: Dict[str, Any]
+    :param max_desc: Maximum description length
+    :type max_desc: int
+    """
+    try:
+        auth_header_names = {
+            "Authorization",
+            "Amazon-Advertising-API-ClientId",
+            "Amazon-Advertising-API-Scope",
+        }
+        auth_parameter_keys: set[str] = set()
+
+        def resolve_local_ref(ref: str) -> Any:
+            if not ref.startswith("#/"):
+                return None
+            current: Any = spec
+            for part in ref[2:].split("/"):
+                if not isinstance(current, dict) or part not in current:
+                    return None
+                current = current[part]
+            return current
+
+        def is_auth_parameter_ref(ref: str) -> bool:
+            if not ref.startswith("#/components/parameters/"):
+                return False
+            key = ref.split("/")[-1]
+            return key in auth_parameter_keys
+
+        def is_auth_header_param(param: Dict[str, Any]) -> bool:
+            if (
+                param.get("in") == "header"
+                and param.get("name") in auth_header_names
+            ):
+                return True
+
+            ref = param.get("$ref")
+            if isinstance(ref, str) and ref.startswith("#/"):
+                if is_auth_parameter_ref(ref):
+                    return True
+                resolved = resolve_local_ref(ref)
+                if isinstance(resolved, dict):
+                    return (
+                        resolved.get("in") == "header"
+                        and resolved.get("name") in auth_header_names
+                    )
+            return False
+
+        spec.pop("externalDocs", None)
+
+        # Fix server URLs that have descriptions in them
+        if "servers" in spec and isinstance(spec["servers"], list):
+            fixed_servers = []
+            for server in spec["servers"]:
+                if isinstance(server, dict) and "url" in server:
+                    url = server["url"]
+                    # Extract just the URL part if it contains description
+                    if " (" in url:
+                        url = url.split(" (")[0].strip()
+                    fixed_servers.append({"url": url})
+            if fixed_servers:
+                # Use the first server as default (North America)
+                spec["servers"] = [fixed_servers[0]]
+
+        # Remove auth header params that are supplied by auth middleware/client
+        components = spec.get("components")
+        if isinstance(components, dict):
+            params = components.get("parameters")
+            if isinstance(params, dict):
+                for key, param in params.items():
+                    if isinstance(param, dict) and is_auth_header_param(param):
+                        auth_parameter_keys.add(key)
+
+        for p, methods in (spec.get("paths") or {}).items():
+            if not isinstance(methods, dict):
+                continue
+
+            # Path-item parameters
+            path_params = methods.get("parameters") or []
+            if isinstance(path_params, list):
+                filtered_path_params = []
+                for prm in path_params:
+                    if isinstance(prm, dict) and "description" in prm:
+                        prm["description"] = truncate_text(prm.get("description"), max_desc)
+                    if isinstance(prm, dict) and is_auth_header_param(prm):
+                        continue
+                    filtered_path_params.append(prm)
+                methods["parameters"] = filtered_path_params
+
+            for m, op in list(methods.items()):
+                if not isinstance(op, dict):
+                    continue
+                # Trim top-level description
+                if "description" in op:
+                    op["description"] = truncate_text(op.get("description"), max_desc)
+                # Prefer summary if description missing or too long
+                if not op.get("description") and op.get("summary"):
+                    op["description"] = truncate_text(op.get("summary"), max_desc)
+                op.pop("externalDocs", None)
+                # Parameters
+                params = op.get("parameters") or []
+                if isinstance(params, list):
+                    filtered_params = []
+                    for prm in params:
+                        if isinstance(prm, dict) and "description" in prm:
+                            prm["description"] = truncate_text(
+                                prm.get("description"), max_desc
+                            )
+                        if isinstance(prm, dict) and is_auth_header_param(prm):
+                            continue
+                        filtered_params.append(prm)
+                    op["parameters"] = filtered_params
+                # Request body description
+                req = op.get("requestBody")
+                if isinstance(req, dict) and "description" in req:
+                    req["description"] = truncate_text(req.get("description"), max_desc)
+
+        if auth_parameter_keys and isinstance(components, dict):
+            params = components.get("parameters")
+            if isinstance(params, dict):
+                for key in auth_parameter_keys:
+                    params.pop(key, None)
+    except Exception:
+        # Do not fail mounting if slimming fails
+        pass