airbyte-internal-ops 0.9.1__py3-none-any.whl → 0.10.1__py3-none-any.whl

airbyte_ops_mcp/mcp/connector_rollout.py

@@ -0,0 +1,882 @@
+# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
+"""MCP tools for connector rollout management.
+
+This module provides MCP tools for managing connector rollouts in Airbyte Cloud,
+including finalizing (promoting, rolling back, or canceling) rollouts.
+"""
+
+# NOTE: We intentionally do NOT use `from __future__ import annotations` here.
+# FastMCP has issues resolving forward references when PEP 563 deferred annotations
+# are used. See: https://github.com/jlowin/fastmcp/issues/905
+# Python 3.12+ supports modern type hint syntax natively, so this is not needed.
+
+from dataclasses import dataclass
+from typing import Annotated, Literal
+
+from airbyte import constants
+from airbyte.exceptions import PyAirbyteInputError
+from fastmcp import Context, FastMCP
+from fastmcp_extensions import get_mcp_config, mcp_tool, register_mcp_tools
+from pydantic import BaseModel, Field
+
+from airbyte_ops_mcp.cloud_admin import api_client
+from airbyte_ops_mcp.cloud_admin.auth import (
+    CloudAuthError,
+    require_internal_admin_flag_only,
+)
+from airbyte_ops_mcp.cloud_admin.models import (
+    ConnectorRolloutFinalizeResult,
+    ConnectorRolloutProgressResult,
+    ConnectorRolloutStartResult,
+)
+from airbyte_ops_mcp.constants import ServerConfigKey
+from airbyte_ops_mcp.github_api import (
+    GitHubAPIError,
+    GitHubCommentParseError,
+    GitHubUserEmailNotFoundError,
+    get_admin_email_from_approval_comment,
+)
+
+
+@dataclass(frozen=True)
+class _ResolvedCloudAuth:
+    """Resolved authentication for Airbyte Cloud API calls.
+
+    Either bearer_token OR (client_id AND client_secret) will be set, not both.
+    """
+
+    bearer_token: str | None = None
+    client_id: str | None = None
+    client_secret: str | None = None
+
+
+def _resolve_cloud_auth(ctx: Context) -> _ResolvedCloudAuth:
+    """Resolve authentication credentials for Airbyte Cloud API.
+
+    Credentials are resolved in priority order:
+    1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var)
+    2. Client credentials (X-Airbyte-Cloud-Client-Id/Secret headers or env vars)
+
+    Args:
+        ctx: FastMCP Context object from the current tool invocation.
+
+    Returns:
+        _ResolvedCloudAuth with either bearer_token or client credentials set.
+
+    Raises:
+        CloudAuthError: If credentials cannot be resolved from headers or env vars.
+    """
+    # Try bearer token first (preferred, but not required)
+    bearer_token = get_mcp_config(ctx, ServerConfigKey.BEARER_TOKEN)
+    if bearer_token:
+        return _ResolvedCloudAuth(bearer_token=bearer_token)
+
+    # Fall back to client credentials
+    try:
+        client_id = get_mcp_config(ctx, ServerConfigKey.CLIENT_ID)
+        client_secret = get_mcp_config(ctx, ServerConfigKey.CLIENT_SECRET)
+        return _ResolvedCloudAuth(
+            client_id=client_id,
+            client_secret=client_secret,
+        )
+    except ValueError as e:
+        raise CloudAuthError(
+            f"Failed to resolve credentials. Ensure credentials are provided "
+            f"via Authorization header (Bearer token), "
+            f"HTTP headers (X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret), "
+            f"or environment variables. Error: {e}"
+        ) from e
+
+
+@mcp_tool(
+    destructive=True,
+    idempotent=False,
+    open_world=True,
+)
+def start_connector_rollout(
+    docker_repository: Annotated[
+        str,
+        Field(description="The docker repository (e.g., 'airbyte/source-pokeapi')"),
+    ],
+    docker_image_tag: Annotated[
+        str,
+        Field(description="The docker image tag (e.g., '0.3.48-rc.1')"),
+    ],
+    actor_definition_id: Annotated[
+        str,
+        Field(description="The actor definition ID (UUID)"),
+    ],
+    approval_comment_url: Annotated[
+        str,
+        Field(
+            description="URL to a GitHub comment where an Airbyte contributor has "
+            "explicitly requested or authorized starting this rollout. "
+            "Must be a valid GitHub comment URL (containing #issuecomment- or #discussion_r). "
+            "The admin email is automatically derived from the comment author's GitHub profile."
+        ),
+    ],
+    rollout_strategy: Annotated[
+        Literal["manual", "automated", "overridden"],
+        Field(
+            description="The rollout strategy: "
+            "'manual' for manual control of rollout progression, "
+            "'automated' for automatic progression based on metrics, "
+            "'overridden' for special cases where normal rules are bypassed.",
+            default="manual",
+        ),
+    ] = "manual",
+    initial_rollout_pct: Annotated[
+        int | None,
+        Field(
+            description="Initial/step percentage for rollout progression (0-100). "
+            "For automated rollouts, this is the percentage increment per step. "
+            "For example, 25 means the rollout will advance by 25% each step. "
+            "Default is 25% if not specified.",
+            default=None,
+        ),
+    ] = None,
+    final_target_rollout_pct: Annotated[
+        int | None,
+        Field(
+            description="Maximum percentage of actors to pin (0-100). "
+            "The rollout will not exceed this percentage. "
+            "For example, 50 means at most 50% of actors will be pinned to the RC. "
+            "Default is 50% if not specified.",
+            default=None,
+        ),
+    ] = None,
+    *,
+    ctx: Context,
+) -> ConnectorRolloutStartResult:
+    """Start or configure a connector rollout workflow.
+
+    This tool configures and starts a connector rollout workflow. It can be called
+    multiple times while the rollout is in INITIALIZED state to update the configuration
+    (strategy, percentages). Once the Temporal workflow starts and the state transitions
+    to WORKFLOW_STARTED, the configuration is locked and cannot be changed.
+
+    **Behavior:**
+    - If rollout is INITIALIZED: Updates configuration and starts the workflow
+    - If rollout is already started: Returns an error (configuration is locked)
+
+    **Configuration Parameters:**
+    - rollout_strategy: 'manual' (default), 'automated', or 'overridden'
+    - initial_rollout_pct: Step size for progression (default: 25%)
+    - final_target_rollout_pct: Maximum percentage to pin (default: 50%)
+
+    **Admin-only operation** - Requires:
+    - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
+    - approval_comment_url parameter (GitHub comment URL with approval from an @airbyte.io user)
+
+    The admin user email is automatically derived from the approval_comment_url by:
+    1. Fetching the comment from GitHub API to get the author's username
+    2. Fetching the user's profile to get their public email
+    3. Validating the email is an @airbyte.io address
+    """
+    # Validate admin access (check env var flag)
+    try:
+        require_internal_admin_flag_only()
+    except CloudAuthError as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=f"Admin authentication failed: {e}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+
+    # Validate approval_comment_url format
+    if not approval_comment_url.startswith("https://github.com/"):
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=f"approval_comment_url must be a valid GitHub URL, got: {approval_comment_url}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+
+    if (
+        "#issuecomment-" not in approval_comment_url
+        and "#discussion_r" not in approval_comment_url
+    ):
+        return ConnectorRolloutStartResult(
+            success=False,
+            message="approval_comment_url must be a GitHub comment URL "
+            "(containing #issuecomment- or #discussion_r)",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+
+    # Derive admin email from approval comment URL
+    try:
+        admin_user_email = get_admin_email_from_approval_comment(approval_comment_url)
+    except GitHubCommentParseError as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=f"Failed to parse approval comment URL: {e}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+    except GitHubAPIError as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=f"Failed to fetch approval comment from GitHub: {e}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+    except GitHubUserEmailNotFoundError as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=str(e),
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+
+    # Resolve auth credentials
+    try:
+        auth = _resolve_cloud_auth(ctx)
+    except CloudAuthError as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=f"Failed to resolve credentials: {e}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+
+    # Get user ID from admin email
+    try:
+        user_id = api_client.get_user_id_by_email(
+            email=admin_user_email,
+            config_api_root=constants.CLOUD_CONFIG_API_ROOT,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
+        )
+    except PyAirbyteInputError as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=f"Failed to get user ID for admin email '{admin_user_email}': {e}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+
+    # Call the API to start the rollout
+    try:
+        api_client.start_connector_rollout(
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+            updated_by=user_id,
+            rollout_strategy=rollout_strategy,
+            config_api_root=constants.CLOUD_CONFIG_API_ROOT,
+            initial_rollout_pct=initial_rollout_pct,
+            final_target_rollout_pct=final_target_rollout_pct,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
+        )
+
+        # Build message with configuration details
+        config_details = []
+        if initial_rollout_pct is not None:
+            config_details.append(f"initial_rollout_pct={initial_rollout_pct}%")
+        if final_target_rollout_pct is not None:
+            config_details.append(
+                f"final_target_rollout_pct={final_target_rollout_pct}%"
+            )
+        config_str = (
+            f" Configuration: {', '.join(config_details)}." if config_details else ""
+        )
+
+        return ConnectorRolloutStartResult(
+            success=True,
+            message=f"Successfully started rollout workflow for "
+            f"{docker_repository}:{docker_image_tag}. "
+            f"The rollout state has transitioned from INITIALIZED to WORKFLOW_STARTED."
+            f"{config_str}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+            rollout_strategy=rollout_strategy,
+        )
+
+    except PyAirbyteInputError as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=str(e),
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+    except Exception as e:
+        return ConnectorRolloutStartResult(
+            success=False,
+            message=f"Failed to start connector rollout: {e}",
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+        )
+
+
+@mcp_tool(
+    destructive=True,
+    idempotent=False,
+    open_world=True,
+)
+def progress_connector_rollout(
+    docker_repository: Annotated[
+        str,
+        Field(description="The docker repository (e.g., 'airbyte/source-pokeapi')"),
+    ],
+    docker_image_tag: Annotated[
+        str,
+        Field(description="The docker image tag (e.g., '0.3.48-rc.1')"),
+    ],
+    actor_definition_id: Annotated[
+        str,
+        Field(description="The actor definition ID (UUID)"),
+    ],
+    rollout_id: Annotated[
+        str,
+        Field(
+            description="The rollout ID (UUID). Can be found from query_prod_connector_rollouts."
+        ),
+    ],
+    approval_comment_url: Annotated[
+        str,
+        Field(
+            description="URL to a GitHub comment where an Airbyte contributor has "
+            "explicitly requested or authorized this rollout progression. "
+            "Must be a valid GitHub comment URL (containing #issuecomment- or #discussion_r). "
+            "The admin email is automatically derived from the comment author's GitHub profile."
+        ),
+    ],
+    target_percentage: Annotated[
+        int | None,
+        Field(
+            description="Target percentage of actors to pin to the RC (1-100). "
+            "Either target_percentage or actor_ids must be provided.",
+            default=None,
+        ),
+    ] = None,
+    actor_ids: Annotated[
+        list[str] | None,
+        Field(
+            description="Specific actor IDs to pin to the RC. "
+            "Either target_percentage or actor_ids must be provided.",
+            default=None,
+        ),
+    ] = None,
+    *,
+    ctx: Context,
+) -> ConnectorRolloutProgressResult:
+    """Progress a connector rollout by pinning actors to the RC version.
+
+    This tool progresses a connector rollout by either:
+    - Setting a target percentage of actors to pin to the RC version
+    - Specifying specific actor IDs to pin
+
+    **Admin-only operation** - Requires:
+    - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
+    - approval_comment_url parameter (GitHub comment URL with approval from an @airbyte.io user)
+
+    The admin user email is automatically derived from the approval_comment_url.
+    """
+    # Validate admin access (check env var flag)
+    try:
+        require_internal_admin_flag_only()
+    except CloudAuthError as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=f"Admin authentication failed: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Validate that at least one of target_percentage or actor_ids is provided
+    if target_percentage is None and actor_ids is None:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message="Either target_percentage or actor_ids must be provided",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Validate approval_comment_url format
+    if not approval_comment_url.startswith("https://github.com/"):
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=f"approval_comment_url must be a valid GitHub URL, got: {approval_comment_url}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    if (
+        "#issuecomment-" not in approval_comment_url
+        and "#discussion_r" not in approval_comment_url
+    ):
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message="approval_comment_url must be a GitHub comment URL "
+            "(containing #issuecomment- or #discussion_r)",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Derive admin email from approval comment URL
+    try:
+        admin_user_email = get_admin_email_from_approval_comment(approval_comment_url)
+    except GitHubCommentParseError as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=f"Failed to parse approval comment URL: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+    except GitHubAPIError as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=f"Failed to fetch approval comment from GitHub: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+    except GitHubUserEmailNotFoundError as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=str(e),
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Resolve auth credentials
+    try:
+        auth = _resolve_cloud_auth(ctx)
+    except CloudAuthError as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=f"Failed to resolve credentials: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Get user ID from admin email
+    try:
+        user_id = api_client.get_user_id_by_email(
+            email=admin_user_email,
+            config_api_root=constants.CLOUD_CONFIG_API_ROOT,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
+        )
+    except PyAirbyteInputError as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=f"Failed to get user ID for admin email '{admin_user_email}': {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Call the API to progress the rollout
+    try:
+        api_client.progress_connector_rollout(
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+            rollout_id=rollout_id,
+            updated_by=user_id,
+            config_api_root=constants.CLOUD_CONFIG_API_ROOT,
+            target_percentage=target_percentage,
+            actor_ids=actor_ids,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
+        )
+
+        progress_msg = (
+            f"target_percentage={target_percentage}%"
+            if target_percentage
+            else f"{len(actor_ids) if actor_ids else 0} specific actors"
+        )
+        return ConnectorRolloutProgressResult(
+            success=True,
+            message=f"Successfully progressed rollout for "
+            f"{docker_repository}:{docker_image_tag} to {progress_msg}.",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            target_percentage=target_percentage,
+        )
+
+    except PyAirbyteInputError as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=str(e),
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+    except Exception as e:
+        return ConnectorRolloutProgressResult(
+            success=False,
+            message=f"Failed to progress connector rollout: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+
+@mcp_tool(
+    destructive=True,
+    idempotent=False,
+    open_world=True,
+)
+def finalize_connector_rollout(
+    docker_repository: Annotated[
+        str,
+        Field(
+            description="The docker repository (e.g., 'airbyte/source-youtube-analytics')"
+        ),
+    ],
+    docker_image_tag: Annotated[
+        str,
+        Field(description="The docker image tag (e.g., '1.2.0-rc.2')"),
+    ],
+    actor_definition_id: Annotated[
+        str,
+        Field(description="The actor definition ID (UUID)"),
+    ],
+    rollout_id: Annotated[
+        str,
+        Field(
+            description="The rollout ID (UUID). Can be found in the 'pin_origin' field "
+            "of rollout data from query_prod_actors_by_connector_version."
+        ),
+    ],
+    state: Annotated[
+        Literal["succeeded", "failed_rolled_back", "canceled"],
+        Field(
+            description="The final state for the rollout: "
+            "'succeeded' promotes the RC to GA (default version for all users), "
+            "'failed_rolled_back' rolls back the RC, "
+            "'canceled' cancels the rollout without promotion or rollback."
+        ),
+    ],
+    approval_comment_url: Annotated[
+        str,
+        Field(
+            description="URL to a GitHub comment where an Airbyte contributor has "
+            "explicitly requested or authorized this rollout finalization. "
+            "Must be a valid GitHub comment URL (containing #issuecomment- or #discussion_r). "
+            "The admin email is automatically derived from the comment author's GitHub profile."
+        ),
+    ],
+    error_msg: Annotated[
+        str | None,
+        Field(
+            description="Optional error message for failed/canceled states.",
+            default=None,
+        ),
+    ] = None,
+    failed_reason: Annotated[
+        str | None,
+        Field(
+            description="Optional failure reason for failed/canceled states.",
+            default=None,
+        ),
+    ] = None,
+    retain_pins_on_cancellation: Annotated[
+        bool | None,
+        Field(
+            description="If True, retain version pins when canceling. "
+            "Only applicable when state is 'canceled'.",
+            default=None,
+        ),
+    ] = None,
+    *,
+    ctx: Context,
+) -> ConnectorRolloutFinalizeResult:
+    """Finalize a connector rollout by promoting, rolling back, or canceling.
+
+    This tool allows admins to finalize connector rollouts that are in progress.
+    Use this after monitoring a rollout and determining it is ready for finalization.
+
+    **Admin-only operation** - Requires:
+    - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
+    - approval_comment_url parameter (GitHub comment URL with approval from an @airbyte.io user)
+
+    The admin user email is automatically derived from the approval_comment_url by:
+    1. Fetching the comment from GitHub API to get the author's username
+    2. Fetching the user's profile to get their public email
+    3. Validating the email is an @airbyte.io address
+    """
+    # Validate admin access (check env var flag)
+    try:
+        require_internal_admin_flag_only()
+    except CloudAuthError as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=f"Admin authentication failed: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Validate approval_comment_url format
+    if not approval_comment_url.startswith("https://github.com/"):
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=f"approval_comment_url must be a valid GitHub URL, got: {approval_comment_url}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    if (
+        "#issuecomment-" not in approval_comment_url
+        and "#discussion_r" not in approval_comment_url
+    ):
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message="approval_comment_url must be a GitHub comment URL "
+            "(containing #issuecomment- or #discussion_r)",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Derive admin email from approval comment URL
+    try:
+        admin_user_email = get_admin_email_from_approval_comment(approval_comment_url)
+    except GitHubCommentParseError as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=f"Failed to parse approval comment URL: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+    except GitHubAPIError as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=f"Failed to fetch approval comment from GitHub: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+    except GitHubUserEmailNotFoundError as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=str(e),
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Resolve auth credentials
+    try:
+        auth = _resolve_cloud_auth(ctx)
+    except CloudAuthError as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=f"Failed to resolve credentials: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Get user ID from admin email
+    try:
+        user_id = api_client.get_user_id_by_email(
+            email=admin_user_email,
+            config_api_root=constants.CLOUD_CONFIG_API_ROOT,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
+        )
+    except PyAirbyteInputError as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=f"Failed to get user ID for admin email '{admin_user_email}': {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+    # Call the API to finalize the rollout
+    try:
+        api_client.finalize_connector_rollout(
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            actor_definition_id=actor_definition_id,
+            rollout_id=rollout_id,
+            updated_by=user_id,
+            state=state,
+            config_api_root=constants.CLOUD_CONFIG_API_ROOT,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
+            error_msg=error_msg,
+            failed_reason=failed_reason,
+            retain_pins_on_cancellation=retain_pins_on_cancellation,
+        )
+
+        state_descriptions = {
+            "succeeded": "promoted to GA (default version for all users)",
+            "failed_rolled_back": "rolled back",
+            "canceled": "canceled",
+        }
+        state_desc = state_descriptions.get(state, state)
+
+        return ConnectorRolloutFinalizeResult(
+            success=True,
+            message=f"Successfully finalized rollout: {docker_repository}:{docker_image_tag} "
+            f"has been {state_desc}.",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+            state=state,
+        )
+
+    except PyAirbyteInputError as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=str(e),
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+    except Exception as e:
+        return ConnectorRolloutFinalizeResult(
+            success=False,
+            message=f"Failed to finalize connector rollout: {e}",
+            rollout_id=rollout_id,
+            docker_repository=docker_repository,
+            docker_image_tag=docker_image_tag,
+        )
+
+
+class RolloutActorSelectionInfo(BaseModel):
+    """Actor selection info for a connector rollout."""
+
+    num_actors: int = Field(description="Total actors using this connector")
+    num_pinned_to_connector_rollout: int = Field(
+        description="Actors specifically pinned to this rollout"
+    )
+    num_actors_eligible_or_already_pinned: int = Field(
+        description="Actors eligible for pinning or already pinned"
+    )
+
+
+class RolloutActorSyncStats(BaseModel):
+    """Per-actor sync stats for a rollout (only syncs using the RC version)."""
+
+    actor_id: str = Field(description="Actor UUID")
+    num_connections: int = Field(description="Number of connections using this actor")
+    num_succeeded: int = Field(
+        description="Number of successful syncs using the RC version"
+    )
+    num_failed: int = Field(description="Number of failed syncs using the RC version")
+
+
+class RolloutMonitoringResult(BaseModel):
+    """Complete monitoring result for a rollout from the platform API.
+
+    This uses the platform API's /get_actor_sync_info endpoint which filters
+    sync stats to only include syncs that actually used the RC version
+    associated with the rollout.
+    """
+
+    rollout_id: str = Field(description="Rollout UUID")
+    actor_selection_info: RolloutActorSelectionInfo = Field(
+        description="Actor selection info for the rollout"
+    )
+    actor_sync_stats: list[RolloutActorSyncStats] = Field(
+        description="Per-actor sync stats for actors pinned to the rollout"
+    )
+
+
+@mcp_tool(
+    read_only=True,
+    idempotent=True,
+)
+def query_prod_rollout_monitoring_stats(
+    rollout_id: Annotated[
+        str,
+        Field(description="Rollout UUID to get monitoring stats for"),
+    ],
+    *,
+    ctx: Context,
+) -> RolloutMonitoringResult:
+    """Get monitoring stats for a connector rollout.
+
+    Returns actor selection info and per-actor sync stats for actors
+    participating in the rollout. This uses the platform API's
+    /get_actor_sync_info endpoint which filters sync stats to only include
+    syncs that actually used the RC version associated with the rollout.
+
+    This is more accurate than SQL-based approaches which count all syncs
+    regardless of which connector version was used.
+    """
+    auth = _resolve_cloud_auth(ctx)
+
+    response = api_client.get_actor_sync_info(
+        rollout_id=rollout_id,
+        config_api_root=constants.CLOUD_CONFIG_API_ROOT,
+        client_id=auth.client_id,
+        client_secret=auth.client_secret,
+        bearer_token=auth.bearer_token,
+    )
+
+    data = response.get("data", {})
+    actor_selection_info_data = data.get("actorSelectionInfo", {})
+    syncs_data = data.get("syncs", {})
+
+    actor_selection_info = RolloutActorSelectionInfo(
+        num_actors=actor_selection_info_data.get("numActors", 0),
+        num_pinned_to_connector_rollout=actor_selection_info_data.get(
+            "numPinnedToConnectorRollout", 0
+        ),
+        num_actors_eligible_or_already_pinned=actor_selection_info_data.get(
+            "numActorsEligibleOrAlreadyPinned", 0
+        ),
+    )
+
+    actor_sync_stats = [
+        RolloutActorSyncStats(
+            actor_id=actor_id,
+            num_connections=sync_info.get("numConnections", 0),
+            num_succeeded=sync_info.get("numSucceeded", 0),
+            num_failed=sync_info.get("numFailed", 0),
+        )
+        for actor_id, sync_info in syncs_data.items()
+    ]
+
+    return RolloutMonitoringResult(
+        rollout_id=rollout_id,
+        actor_selection_info=actor_selection_info,
+        actor_sync_stats=actor_sync_stats,
+    )
+
+
+def register_connector_rollout_tools(app: FastMCP) -> None:
+    """Register connector rollout tools with the FastMCP app.
+
+    Args:
+        app: FastMCP application instance
+    """
+    register_mcp_tools(app)