airbyte-internal-ops 0.1.11__py3-none-any.whl → 0.2.1__py3-none-any.whl

airbyte_ops_mcp/mcp/cloud_connector_versions.py

@@ -5,20 +5,15 @@ This module provides MCP tools for viewing and managing connector version
 overrides (pins) in Airbyte Cloud. These tools enable admins to pin connectors
 to specific versions for troubleshooting or stability purposes.
 
-Uses PyAirbyte's CloudWorkspace, CloudSource, and CloudDestination classes
-for all cloud operations.
+Uses direct API client calls with either bearer token or client credentials auth.
 """
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Annotated, Literal
 
 from airbyte import constants
-from airbyte.cloud import CloudWorkspace
-from airbyte.cloud.auth import (
-    resolve_cloud_client_id,
-    resolve_cloud_client_secret,
-)
 from airbyte.exceptions import PyAirbyteInputError
 from fastmcp import FastMCP
 from pydantic import Field
@@ -26,39 +21,64 @@ from pydantic import Field
 from airbyte_ops_mcp.cloud_admin import api_client
 from airbyte_ops_mcp.cloud_admin.auth import (
     CloudAuthError,
-    get_admin_user_email,
-    require_internal_admin,
+    require_internal_admin_flag_only,
 )
 from airbyte_ops_mcp.cloud_admin.models import (
     ConnectorVersionInfo,
     VersionOverrideOperationResult,
 )
+from airbyte_ops_mcp.mcp._http_headers import (
+    resolve_bearer_token,
+    resolve_client_id,
+    resolve_client_secret,
+)
 from airbyte_ops_mcp.mcp._mcp_utils import mcp_tool, register_mcp_tools
 
 
-def _get_workspace(workspace_id: str) -> CloudWorkspace:
-    """Get a CloudWorkspace instance for the specified workspace.
+@dataclass(frozen=True)
+class _ResolvedCloudAuth:
+    """Resolved authentication for Airbyte Cloud API calls.
 
-    Args:
-        workspace_id: The Airbyte Cloud workspace ID (required).
+    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() -> _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)
 
     Returns:
-        CloudWorkspace instance configured for the specified workspace.
+        _ResolvedCloudAuth with either bearer_token or client credentials set.
 
     Raises:
-        CloudAuthError: If required environment variables are not set.
+        CloudAuthError: If credentials cannot be resolved from headers or env vars.
     """
+    # Try bearer token first (preferred)
+    bearer_token = resolve_bearer_token()
+    if bearer_token:
+        return _ResolvedCloudAuth(bearer_token=str(bearer_token))
+
+    # Fall back to client credentials
     try:
-        return CloudWorkspace(
-            workspace_id=workspace_id,
-            client_id=resolve_cloud_client_id(),
-            client_secret=resolve_cloud_client_secret(),
-            api_root=constants.CLOUD_API_ROOT,  # Used for workspace operations
+        client_id = resolve_client_id()
+        client_secret = resolve_client_secret()
+        return _ResolvedCloudAuth(
+            client_id=str(client_id),
+            client_secret=str(client_secret),
         )
     except Exception as e:
         raise CloudAuthError(
-            f"Failed to initialize CloudWorkspace. Ensure AIRBYTE_CLIENT_ID "
-            f"and AIRBYTE_CLIENT_SECRET are set. Error: {e}"
+            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
 
 
@@ -85,11 +105,13 @@ def get_cloud_connector_version(
     Returns version details including the current version string and whether
     an override (pin) is applied.
 
-    The `AIRBYTE_CLIENT_ID`, `AIRBYTE_CLIENT_SECRET`, and `AIRBYTE_API_ROOT`
-    environment variables will be used to authenticate with the Airbyte Cloud API.
+    Authentication credentials are resolved in priority order:
+    1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var)
+    2. HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret
+    3. Environment variables: AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET
     """
     try:
-        workspace = _get_workspace(workspace_id)
+        auth = _resolve_cloud_auth()
 
         # Use vendored API client instead of connector.get_connector_version()
         # Use Config API root for version management operations
@@ -97,8 +119,9 @@ def get_cloud_connector_version(
             connector_id=actor_id,
             connector_type=actor_type,
             api_root=constants.CLOUD_CONFIG_API_ROOT,  # Use Config API, not public API
-            client_id=workspace.client_id,
-            client_secret=workspace.client_secret,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
         )
 
         return ConnectorVersionInfo(
@@ -163,11 +186,47 @@ def set_cloud_connector_version_override(
             default=None,
         ),
     ],
+    admin_user_email: Annotated[
+        str | None,
+        Field(
+            description="Email of the admin user authorizing this operation. "
+            "Must be an @airbyte.io email address. Required for authorization.",
+            default=None,
+        ),
+    ],
+    issue_url: Annotated[
+        str | None,
+        Field(
+            description="URL to the GitHub issue providing context for this operation. "
+            "Must be a valid GitHub URL (https://github.com/...). Required for authorization.",
+            default=None,
+        ),
+    ],
+    approval_comment_url: Annotated[
+        str | None,
+        Field(
+            description="URL to a GitHub comment where the admin has explicitly "
+            "requested or authorized this deployment. Must be a valid GitHub comment URL. "
+            "Required for authorization.",
+            default=None,
+        ),
+    ],
+    ai_agent_session_url: Annotated[
+        str | None,
+        Field(
+            description="URL to the AI agent session driving this operation, if applicable. "
+            "Provides additional auditability for AI-driven operations.",
+            default=None,
+        ),
+    ],
 ) -> VersionOverrideOperationResult:
     """Set or clear a version override for a deployed connector.
 
-    **Admin-only operation** - Requires AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io
-    and AIRBYTE_INTERNAL_ADMIN_USER environment variables.
+    **Admin-only operation** - Requires:
+    - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
+    - admin_user_email parameter (must be @airbyte.io email)
+    - issue_url parameter (GitHub issue URL for context)
+    - approval_comment_url parameter (GitHub comment URL with approval)
 
     You must specify EXACTLY ONE of `version` OR `unset=True`, but not both.
     When setting a version, `override_reason` is required.
@@ -177,13 +236,14 @@ def set_cloud_connector_version_override(
     - Production versions: Require strong justification mentioning customer/support/investigation
     - Release candidates (-rc): Any admin can pin/unpin RC versions
 
-    The `AIRBYTE_CLIENT_ID`, `AIRBYTE_CLIENT_SECRET`, and `AIRBYTE_API_ROOT`
-    environment variables will be used to authenticate with the Airbyte Cloud API.
+    Authentication credentials are resolved in priority order:
+    1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var)
+    2. HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret
+    3. Environment variables: AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET
     """
-    # Validate admin access
+    # Validate admin access (check env var flag)
     try:
-        require_internal_admin()
-        user_email = get_admin_user_email()
+        require_internal_admin_flag_only()
     except CloudAuthError as e:
         return VersionOverrideOperationResult(
             success=False,
@@ -192,17 +252,72 @@ def set_cloud_connector_version_override(
             connector_type=actor_type,
         )
 
-    # Get workspace and current version info
+    # Validate new authorization parameters
+    validation_errors: list[str] = []
+
+    if not admin_user_email:
+        validation_errors.append("admin_user_email is required for authorization")
+    elif "@airbyte.io" not in admin_user_email:
+        validation_errors.append(
+            f"admin_user_email must be an @airbyte.io email address, got: {admin_user_email}"
+        )
+
+    if not issue_url:
+        validation_errors.append(
+            "issue_url is required for authorization (GitHub issue URL)"
+        )
+    elif not issue_url.startswith("https://github.com/"):
+        validation_errors.append(
+            f"issue_url must be a valid GitHub URL (https://github.com/...), got: {issue_url}"
+        )
+
+    if not approval_comment_url:
+        validation_errors.append(
+            "approval_comment_url is required for authorization (GitHub comment URL)"
+        )
+    elif not approval_comment_url.startswith("https://github.com/"):
+        validation_errors.append(
+            f"approval_comment_url must be a valid GitHub URL, got: {approval_comment_url}"
+        )
+    elif (
+        "#issuecomment-" not in approval_comment_url
+        and "#discussion_r" not in approval_comment_url
+    ):
+        validation_errors.append(
+            "approval_comment_url must be a GitHub comment URL "
+            "(containing #issuecomment- or #discussion_r)"
+        )
+
+    if validation_errors:
+        return VersionOverrideOperationResult(
+            success=False,
+            message="Authorization validation failed: " + "; ".join(validation_errors),
+            connector_id=actor_id,
+            connector_type=actor_type,
+        )
+
+    # Build enhanced override reason with audit fields (only for 'set' operations)
+    enhanced_override_reason = override_reason
+    if not unset and override_reason:
+        audit_parts = [override_reason]
+        audit_parts.append(f"Issue: {issue_url}")
+        audit_parts.append(f"Approval: {approval_comment_url}")
+        if ai_agent_session_url:
+            audit_parts.append(f"AI Session: {ai_agent_session_url}")
+        enhanced_override_reason = " | ".join(audit_parts)
+
+    # Resolve auth and get current version info
     try:
-        workspace = _get_workspace(workspace_id)
+        auth = _resolve_cloud_auth()
 
         # Get current version info before the operation
         current_version_data = api_client.get_connector_version(
             connector_id=actor_id,
             connector_type=actor_type,
             api_root=constants.CLOUD_CONFIG_API_ROOT,  # Use Config API
-            client_id=workspace.client_id,
-            client_secret=workspace.client_secret,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
         )
         current_version = current_version_data["dockerImageTag"]
         was_pinned_before = current_version_data["isVersionOverrideApplied"]
@@ -210,14 +325,7 @@ def set_cloud_connector_version_override(
     except CloudAuthError as e:
         return VersionOverrideOperationResult(
             success=False,
-            message=f"Failed to initialize workspace or connector: {e}",
-            connector_id=actor_id,
-            connector_type=actor_type,
-        )
-    except Exception as e:
-        return VersionOverrideOperationResult(
-            success=False,
-            message=f"Failed to get connector: {e}",
+            message=f"Failed to resolve credentials or get connector: {e}",
             connector_id=actor_id,
             connector_type=actor_type,
         )
@@ -228,14 +336,15 @@ def set_cloud_connector_version_override(
             connector_id=actor_id,
             connector_type=actor_type,
             api_root=constants.CLOUD_CONFIG_API_ROOT,  # Use Config API
-            client_id=workspace.client_id,
-            client_secret=workspace.client_secret,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
             workspace_id=workspace_id,
             version=version,
             unset=unset,
-            override_reason=override_reason,
+            override_reason=enhanced_override_reason,
             override_reason_reference_url=override_reason_reference_url,
-            user_email=user_email,
+            user_email=admin_user_email,
+            bearer_token=auth.bearer_token,
         )
 
         # Get updated version info after the operation
@@ -243,8 +352,9 @@ def set_cloud_connector_version_override(
             connector_id=actor_id,
             connector_type=actor_type,
             api_root=constants.CLOUD_CONFIG_API_ROOT,  # Use Config API
-            client_id=workspace.client_id,
-            client_secret=workspace.client_secret,
+            client_id=auth.client_id,
+            client_secret=auth.client_secret,
+            bearer_token=auth.bearer_token,
         )
         new_version = updated_version_data["dockerImageTag"] if not unset else None
         is_pinned_after = updated_version_data["isVersionOverrideApplied"]

airbyte_ops_mcp/mcp/github.py

@@ -14,12 +14,27 @@ import requests
 from fastmcp import FastMCP
 from pydantic import BaseModel, Field
 
-from airbyte_ops_mcp.github_actions import GITHUB_API_BASE, resolve_github_token
+from airbyte_ops_mcp.github_actions import (
+    GITHUB_API_BASE,
+    get_workflow_jobs,
+    resolve_github_token,
+)
 from airbyte_ops_mcp.mcp._mcp_utils import mcp_tool, register_mcp_tools
 
 DOCKERHUB_API_BASE = "https://hub.docker.com/v2"
 
 
+class JobInfo(BaseModel):
+    """Information about a single job in a workflow run."""
+
+    job_id: int
+    name: str
+    status: str
+    conclusion: str | None = None
+    started_at: str | None = None
+    completed_at: str | None = None
+
+
 class WorkflowRunStatus(BaseModel):
     """Response model for check_workflow_status MCP tool."""
 
@@ -34,6 +49,7 @@ class WorkflowRunStatus(BaseModel):
     updated_at: str
     run_started_at: str | None = None
     jobs_url: str
+    jobs: list[JobInfo] = []
 
 
 def _parse_workflow_url(url: str) -> tuple[str, str, int]:
@@ -148,6 +164,22 @@ def check_workflow_status(
     # Get workflow run details
     run_data = _get_workflow_run(owner, repo, run_id, token)
 
+    # Get jobs for the workflow run (uses upstream function that resolves its own token)
+    workflow_jobs = get_workflow_jobs(owner, repo, run_id)
+
+    # Convert dataclass objects to Pydantic models for the response
+    jobs = [
+        JobInfo(
+            job_id=job.job_id,
+            name=job.name,
+            status=job.status,
+            conclusion=job.conclusion,
+            started_at=job.started_at,
+            completed_at=job.completed_at,
+        )
+        for job in workflow_jobs
+    ]
+
     return WorkflowRunStatus(
         run_id=run_data["id"],
         status=run_data["status"],
@@ -160,6 +192,7 @@ def check_workflow_status(
         updated_at=run_data["updated_at"],
         run_started_at=run_data.get("run_started_at"),
         jobs_url=run_data["jobs_url"],
+        jobs=jobs,
     )
 
 

airbyte_ops_mcp/mcp/prod_db_queries.py

@@ -20,7 +20,7 @@ from airbyte_ops_mcp.prod_db_access.queries import (
     query_connections_by_connector,
     query_connector_versions,
     query_dataplanes_list,
-    query_failed_sync_attempts_for_version,
+    query_failed_sync_attempts_for_connector,
     query_new_connector_releases,
     query_sync_results_for_version,
     query_workspace_info,
@@ -249,12 +249,41 @@ def query_prod_connector_version_sync_results(
 @mcp_tool(
     read_only=True,
     idempotent=True,
+    open_world=True,
 )
-def query_prod_failed_sync_attempts_for_version(
-    connector_version_id: Annotated[
-        str,
-        Field(description="Connector version UUID to find failed sync attempts for"),
-    ],
+def query_prod_failed_sync_attempts_for_connector(
+    source_definition_id: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Source connector definition ID (UUID) to search for. "
+                "Exactly one of this or source_canonical_name is required. "
+                "Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
+            ),
+            default=None,
+        ),
+    ] = None,
+    source_canonical_name: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Canonical source connector name to search for. "
+                "Exactly one of this or source_definition_id is required. "
+                "Examples: 'source-youtube-analytics', 'YouTube Analytics'."
+            ),
+            default=None,
+        ),
+    ] = None,
+    organization_id: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Optional organization ID (UUID) to filter results. "
+                "If provided, only failed attempts from this organization will be returned."
+            ),
+            default=None,
+        ),
+    ] = None,
     days: Annotated[
         int,
         Field(description="Number of days to look back (default: 7)", default=7),
@@ -264,29 +293,43 @@ def query_prod_failed_sync_attempts_for_version(
         Field(description="Maximum number of results (default: 100)", default=100),
     ] = 100,
 ) -> list[dict[str, Any]]:
-    """List failed sync attempts with failure details for actors pinned to a connector version.
+    """List failed sync attempts for ALL actors using a source connector type.
 
-    Returns failed attempt records for connections using actors pinned to the specified
-    version. Includes failure_summary from the attempts table for debugging.
+    This tool finds all actors with the given connector definition and returns their
+    failed sync attempts, regardless of whether they have explicit version pins.
 
-    Key fields:
-    - latest_job_attempt_status: Final job status after all retries ('succeeded' means
-      the job eventually succeeded despite this failed attempt)
-    - failed_attempt_number: Which attempt this was (0-indexed)
-    - failure_summary: JSON containing failure details including failureType and messages
+    This is useful for investigating connector issues across all users. Use this when
+    you want to find failures for a connector type regardless of which version users
+    are on.
 
-    Note: May return multiple rows per job (one per failed attempt). Results ordered by
-    job_updated_at DESC, then failed_attempt_number DESC.
+    Note: This tool only supports SOURCE connectors. For destination connectors,
+    a separate tool would be needed.
 
-    Returns list of dicts with keys: job_id, connection_id, latest_job_attempt_status,
-    job_started_at, job_updated_at, connection_name, actor_id, actor_name,
-    actor_definition_id, pin_origin_type, pin_origin, workspace_id, workspace_name,
-    organization_id, dataplane_group_id, dataplane_name, failed_attempt_id,
-    failed_attempt_number, failed_attempt_status, failed_attempt_created_at,
-    failed_attempt_ended_at, failure_summary, processing_task_queue
+    Key fields in results:
+    - failure_summary: JSON containing failure details including failureType and messages
+    - pin_origin_type, pin_origin, pinned_version_id: Version pin context (NULL if not pinned)
     """
-    return query_failed_sync_attempts_for_version(
-        connector_version_id,
+    # Validate that exactly one of the two parameters is provided
+    if (source_definition_id is None) == (source_canonical_name is None):
+        raise PyAirbyteInputError(
+            message=(
+                "Exactly one of source_definition_id or source_canonical_name "
+                "must be provided, but not both."
+            ),
+        )
+
+    # Resolve canonical name to definition ID if needed
+    resolved_definition_id: str
+    if source_canonical_name:
+        resolved_definition_id = _resolve_canonical_name_to_definition_id(
+            canonical_name=source_canonical_name,
+        )
+    else:
+        resolved_definition_id = source_definition_id  # type: ignore[assignment]
+
+    return query_failed_sync_attempts_for_connector(
+        connector_definition_id=resolved_definition_id,
+        organization_id=organization_id,
         days=days,
         limit=limit,
     )