axmp-openapi-fastmcp-server 0.3.0__py3-none-any.whl

axmp_openapi_fastmcp_server/__init__.py

@@ -0,0 +1,19 @@
+"""This is the MCP server for the ZMP OpenAPI."""
+
+import logging
+
+# for stdio
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="[%(asctime)s.%(msecs)d] [%(levelname)s] [%(name)s] [%(threadName)s:%(thread)d] [%(module)s:%(funcName)s:%(lineno)d] - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    handlers=[logging.StreamHandler()],
+)
+
+# for streamable-http
+# logging.config.fileConfig("logging.conf", disable_existing_loggers=False)
+
+logging.getLogger("httpcore.http11").setLevel(logging.INFO)
+logging.getLogger("sse_starlette.sse").setLevel(logging.INFO)
+# logging.getLogger("axmp_openapi_helper").setLevel(logging.DEBUG)
+# logging.getLogger("axmp_openapi_mcp_server.openapi_mcp_server").setLevel(logging.DEBUG)

axmp_openapi_fastmcp_server/__main__.py

@@ -0,0 +1,7 @@
+"""This is the main entry point for the MCP server."""
+
+import sys
+
+from axmp_openapi_mcp_server.runner.cli import main
+
+sys.exit(main())

axmp_openapi_fastmcp_server/auth/providers/keycloak.py

@@ -0,0 +1,320 @@
+"""Keycloak OAuth provider for FastMCP.
+
+This module provides a complete Keycloak OAuth integration that's ready to use
+with just a client ID and client secret. It handles all the complexity of
+Keycloak's OAuth flow, token validation, and user management.
+"""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl, BaseModel, Field, model_validator
+
+logger = get_logger(__name__)
+
+
+class KeyCloakEndpoints(BaseModel):
+    """Keycloak endpoints."""
+
+    issuer_url: AnyHttpUrl | str = Field(...)
+    token_endpoint: AnyHttpUrl | str | None = None
+    authorization_endpoint: AnyHttpUrl | str | None = None
+    user_info_endpoint: AnyHttpUrl | str | None = None
+    jwks_uri: AnyHttpUrl | str | None = None
+    introspection_endpoint: AnyHttpUrl | str | None = None
+    revocation_endpoint: AnyHttpUrl | str | None = None
+
+    @model_validator(mode="after")
+    def set_defaults_from_issuer_url(self) -> KeyCloakEndpoints:
+        """Set default endpoint URLs based on the actual issuer_url value."""
+        base = str(self.issuer_url).rstrip("/")
+        if self.token_endpoint is None:
+            self.token_endpoint = f"{base}/protocol/openid-connect/token"
+        if self.authorization_endpoint is None:
+            self.authorization_endpoint = f"{base}/protocol/openid-connect/auth"
+        if self.user_info_endpoint is None:
+            self.user_info_endpoint = f"{base}/protocol/openid-connect/userinfo"
+        if self.jwks_uri is None:
+            self.jwks_uri = f"{base}/protocol/openid-connect/certs"
+        if self.introspection_endpoint is None:
+            self.introspection_endpoint = (
+                f"{base}/protocol/openid-connect/token/introspect"
+            )
+        if self.revocation_endpoint is None:
+            self.revocation_endpoint = (
+                f"{base}/protocol/openid-connect/token/revocation"
+            )
+        return self
+
+
+class KeyCloakTokenVerifier(TokenVerifier):
+    """Token verifier for Keycloak OAuth tokens.
+
+    Keycloak OAuth tokens are opaque (not JWTs), so we verify them
+    by calling Keycloak's tokeninfo API to check if they're valid and get user info.
+    """
+
+    def __init__(
+        self,
+        *,
+        issuer_url: AnyHttpUrl | str,
+        client_id: str,
+        client_secret: str,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+    ):
+        """Initialize the Keycloak token verifier.
+
+        Args:
+            client_id: Client ID for introspection authentication
+            client_secret: Client secret for introspection authentication
+            required_scopes: Required OAuth scopes (e.g., ['openid', 'https://www.googleapis.com/auth/userinfo.email'])
+            timeout_seconds: HTTP request timeout
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.timeout_seconds = timeout_seconds
+        self.keycloak_endpoints = KeyCloakEndpoints(issuer_url=issuer_url)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify Keycloak OAuth token by calling Keycloak's tokeninfo API."""
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                # Use Keycloak's introspection endpoint to validate the token
+                # Keycloak expects POST with basic auth for confidential clients
+                response = await client.post(
+                    self.keycloak_endpoints.introspection_endpoint,
+                    data={"token": token},
+                    auth=(self.client_id, self.client_secret),
+                    headers={"User-Agent": "FastMCP-Keycloak-OAuth"},
+                )
+
+                if response.status_code != 200:
+                    logger.debug(
+                        "Keycloak token verification failed: %d",
+                        response.status_code,
+                    )
+                    return None
+
+                token_info = response.json()
+
+                # Check if token is active
+                if not token_info.get("active"):
+                    logger.debug("Token is inactive")
+                    return None
+
+                # Check if token is expired (backup check)
+                expires_in = token_info.get("expires_in")
+                if expires_in and int(expires_in) <= 0:
+                    logger.debug("Access token has expired")
+                    return None
+
+                # Extract scopes from token info
+                scope_string = token_info.get("scope", "")
+                token_scopes = [
+                    scope.strip() for scope in scope_string.split(" ") if scope.strip()
+                ]
+
+                # Check required scopes
+                if self.required_scopes:
+                    token_scopes_set = set(token_scopes)
+                    required_scopes_set = set(self.required_scopes)
+                    if not required_scopes_set.issubset(token_scopes_set):
+                        logger.debug(
+                            "Access token missing required scopes. Has %d, needs %d",
+                            len(token_scopes_set),
+                            len(required_scopes_set),
+                        )
+                        return None
+
+                # Get additional user info if we have the right scopes
+                user_data = {}
+                if "openid" in token_scopes or "profile" in token_scopes:
+                    try:
+                        userinfo_response = await client.get(
+                            self.keycloak_endpoints.user_info_endpoint,
+                            headers={
+                                "Authorization": f"Bearer {token}",
+                                "User-Agent": "FastMCP-Keycloak-OAuth",
+                            },
+                        )
+                        if userinfo_response.status_code == 200:
+                            user_data = userinfo_response.json()
+                    except Exception as e:
+                        logger.debug("Failed to fetch Keycloak user info: %s", e)
+
+                # Calculate expiration time
+                expires_at = None
+                if expires_in:
+                    expires_at = int(time.time() + int(expires_in))
+
+                # Create AccessToken with Keycloak user info
+                access_token = AccessToken(
+                    token=token,
+                    client_id=token_info.get(
+                        "audience", "unknown"
+                    ),  # Use audience as client_id
+                    scopes=token_scopes,
+                    expires_at=expires_at,
+                    claims={
+                        "sub": user_data.get("sub"),
+                        "email": user_data.get("email"),
+                        "username": user_data.get("preferred_username")
+                        if user_data.get("preferred_username")
+                        else user_data.get("email"),
+                        "given_name": user_data.get("given_name"),
+                        "family_name": user_data.get("family_name"),
+                        "keycloak_user_data": user_data,
+                        "keycloak_token_info": token_info,
+                    },
+                )
+                logger.debug("Keycloak token verified successfully")
+                return access_token
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify Keycloak token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("Keycloak token verification error: %s", e)
+            return None
+
+
+class KeyCloakProvider(OAuthProxy):
+    """Complete Keycloak OAuth provider for FastMCP.
+
+    This provider makes it trivial to add Keycloak OAuth protection to any
+    FastMCP server. Just provide your Keycloak OAuth app credentials and
+    a base URL, and you're ready to go.
+
+    Features:
+    - Transparent OAuth proxy to Keycloak
+    - Automatic token validation via Keycloak's tokeninfo API
+    - User information extraction from Keycloak APIs
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.keycloak import KeycloakProvider
+
+        auth = KeycloakProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-abc123...",
+            base_url="https://my-server.com"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        base_url: AnyHttpUrl | str,
+        issuer_url: AnyHttpUrl | str,
+        redirect_path: str | None = None,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool = True,
+        extra_authorize_params: dict[str, str] | None = None,
+    ):
+        """Initialize KeyCloak OAuth provider.
+
+        Args:
+            client_id: KeyCloak OAuth client ID (e.g., "123456789.apps.googleusercontent.com")
+            client_secret: KeyCloak OAuth client secret (e.g., "GOCSPX-abc123...")
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in KeyCloak OAuth app (defaults to "/auth/callback")
+            required_scopes: Required KeyCloak scopes (defaults to ["openid"]). Common scopes include:
+                - "openid" for OpenID Connect (default)
+                - "https://www.googleapis.com/auth/userinfo.email" for email access
+                - "https://www.googleapis.com/auth/userinfo.profile" for profile info
+            timeout_seconds: HTTP request timeout for KeyCloak API calls (defaults to 10)
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, a DiskStore will be created in the data directory (derived from `platformdirs`). The
+                disk store will be encrypted using a key derived from the JWT Signing Key.
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to KeyCloak.
+                When False, authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or testing environments.
+            extra_authorize_params: Additional parameters to forward to KeyCloak's authorization endpoint.
+                By default, KeyCloakProvider sets {"access_type": "offline", "prompt": "consent"} to ensure
+                refresh tokens are returned. You can override these defaults or add additional parameters.
+                Example: {"prompt": "select_account"} to let users choose their KeyCloak account.
+        """
+        # Parse scopes if provided as string
+        # KeyCloak requires at least one scope - openid is the minimal OIDC scope
+        required_scopes_final = (
+            parse_scopes(required_scopes) if required_scopes is not None else ["openid"]
+        )
+
+        # Create Keycloak token verifier
+        token_verifier = KeyCloakTokenVerifier(
+            issuer_url=issuer_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds,
+        )
+
+        # Get Keycloak endpoints
+        keycloak_endpoints = KeyCloakEndpoints(
+            issuer_url=issuer_url,
+        )
+
+        # Set Keycloak-specific defaults for extra authorize params
+        # access_type=offline ensures refresh tokens are returned
+        # prompt=consent forces consent screen to get refresh token (KeyCloak only issues on first auth otherwise)
+        # keycloak_defaults = {
+        #     "access_type": "offline",
+        #     "prompt": "consent",
+        # }
+        # User-provided params override defaults
+        # if extra_authorize_params:
+        #     keycloak_defaults.update(extra_authorize_params)
+        # extra_authorize_params_final = keycloak_defaults
+
+        # Initialize OAuth proxy with KeyCloak endpoints
+        super().__init__(
+            upstream_authorization_endpoint=keycloak_endpoints.authorization_endpoint,
+            upstream_token_endpoint=keycloak_endpoints.token_endpoint,
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            redirect_path=redirect_path,
+            # issuer_url=issuer_url or base_url,  # Default to base_url if not specified
+            issuer_url=base_url,  # NOTE: should be the same as base_url for the DCR
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            extra_authorize_params=extra_authorize_params,
+        )
+
+        logger.debug(
+            "Initialized Keycloak OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )

axmp_openapi_fastmcp_server/multi_openapi_spec.py

@@ -0,0 +1,185 @@
+"""This module provides a model for the mixed API specification."""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import List
+
+from pydantic import BaseModel
+
+
+class AuthenticationType(str, Enum):
+    """Authentication type model."""
+
+    NONE = "None"
+    BASIC = "Basic"
+    BEARER_TOKEN = "BearerToken"
+    API_KEY = "ApiKey"
+
+
+class MethodSpec(BaseModel):
+    """A model for the method specification."""
+
+    method: str
+    tool_name: str | None = None
+    description: str | None = None
+
+
+class APIMap(BaseModel):
+    """A model for the API simple specification."""
+
+    path: str
+    methods: List[str | MethodSpec]
+
+
+class RouteMap(BaseModel):
+    """A model for the route map."""
+
+    methods: List[str] | None = None
+    tags: List[str] | None = None
+    pattern: str | None = None
+
+
+class ToolConfig(BaseModel):
+    """A model for the tool configuration."""
+
+    api_maps: List[APIMap] | None = None
+    route_maps: List[RouteMap] | None = None
+
+
+class AuthConfig(BaseModel):
+    """A model for the authentication configuration."""
+
+    type: AuthenticationType = AuthenticationType.NONE
+    username: str | None = None
+    password: str | None = None
+    api_key_name: str | None = None
+    api_key_value: str | None = None
+    bearer_token: str | None = None
+
+
+class APIServerConfig(BaseModel):
+    """A model for the API server configuration."""
+
+    server_name: str
+    endpoint: str
+    base_path: str | None = None
+    timeout: float = 10
+    tls_verify: bool = True
+    spec_file_path: str | Path
+    # NOTE: open_api_spec is not needed any more
+    # open_api_spec: AxmpOpenAPI | None = None
+    tool_config: ToolConfig
+    auth_config: AuthConfig
+
+
+class MultiOpenAPISpecConfig(BaseModel):
+    """MultiOpenAPISpecConfig is a model that contains the configuration for the multi-server API specification.
+
+    ```json
+    {
+        "backends": [
+            {
+                "server_name": "zcp-alert-backend",
+                "endpoint": "https://zcp-alert-backend.com",
+                "base_path": "/api/alert/v1",
+                "tls_verify": false,
+                "timeout": 10,
+                "auth_config": {
+                    "type": "basic",
+                    "username": "admin",
+                    "password": "password"
+                },
+                "spec_file_path": "openapi_spec/zcp_spec/alert_openapi_spec.json",
+                "tool_config": {
+                    "api_maps": [
+                        {
+                            "path":"/api/alert/v1/alerts",
+                            "methods": ["get", "post"]
+                        },
+                        {
+                            "path":"/api/alert/v1/alerts/webhook",
+                            "methods": ["post"]
+                        },
+                        {
+                            "path":"/api/alert/v1/alert/priorities",
+                            "methods": ["get"]
+                        }
+                    ]
+                }
+            },
+            {
+                "server_name": "example-backend",
+                "endpoint": "https://example-backend.com",
+                "base_path": "/api/example/v1",
+                "spec_file_path": "openapi_spec/example_spec/test_spec.json",
+                "tls_verify": true,
+                "timeout": 10,
+                "auth_config": {
+                    "type": "api_key",
+                    "custom_header_api_key_name": "X-API-KEY",
+                    "custom_header_api_key_value": "1234567890"
+                },
+                "tool_config": {
+                    "api_maps": [
+                        {
+                            "path":"/api/example/v1/test",
+                            "methods": [
+                                {
+                                    "method": "post",
+                                    "tool_name": "create_test",
+                                    "description": "Create test"
+                                }
+                            ]
+                        }
+                    ],
+                    "route_maps": [
+                        {
+                            "pattern": r".*",
+                            "methods": ["get"],
+                            "tags": ["*"]
+                        }
+                    ]
+                }
+            },
+            {
+                "server_name": "zcp-alert-backend",
+                "endpoint": "https://zcp-alert-backend.com",
+                "base_path": "/api/alert/v1",
+                "spec_file_path": "openapi_spec/zcp_spec/alert_openapi_spec.json",
+                "tls_verify": true,
+                "timeout": 10,
+                "auth_config": {
+                    "type": "bearer",
+                    "bearer_token": "1234567890"
+                },
+                "tool_config": {
+                    "route_maps": [
+                        {
+                            "pattern": "^/api/alert/v1/channels/.*",
+                            "methods": ["get"],
+                            "tags": []
+                        },
+                        {
+                            "pattern": "^/api/alert/v1/admin/.*",
+                            "methods": ["post"],
+                            "tags": ["alerts"]
+                        }
+                    ]
+                }
+            }
+        ]
+    }
+    ```
+    """
+
+    backends: List[APIServerConfig]
+
+    @classmethod
+    def from_multi_server_spec_file(
+        cls, file_path: str | Path
+    ) -> MultiOpenAPISpecConfig:
+        """Load the multi-server API specification from a file."""
+        with open(file_path) as f:
+            return cls.model_validate_json(f.read())