airbyte-internal-ops 0.2.4__py3-none-any.whl → 0.3.1__py3-none-any.whl

airbyte_ops_mcp/mcp/cloud_connector_versions.py

@@ -121,6 +121,7 @@ def get_cloud_connector_version(
 
         # Use vendored API client instead of connector.get_connector_version()
         # Use Config API root for version management operations
+        # Pass workspace_id to get detailed scoped configuration context
         version_data = api_client.get_connector_version(
             connector_id=actor_id,
             connector_type=actor_type,
@@ -128,13 +129,31 @@ def get_cloud_connector_version(
             client_id=auth.client_id,
             client_secret=auth.client_secret,
             bearer_token=auth.bearer_token,
+            workspace_id=workspace_id,
+        )
+
+        # Determine if version is pinned from scoped config context (more reliable)
+        # The API's isVersionOverrideApplied only returns true for USER-created pins,
+        # not system-generated pins (e.g., breaking_change origin). Check scopedConfigs
+        # for a more accurate picture of whether ANY pin exists.
+        scoped_configs = version_data.get("scopedConfigs", {})
+        has_any_pin = (
+            any(config is not None for config in scoped_configs.values())
+            if scoped_configs
+            else False
+        )
+
+        # Use scoped config existence as the source of truth for "is pinned"
+        # Fall back to API's isVersionOverrideApplied if no scoped config data
+        is_pinned = (
+            has_any_pin if scoped_configs else version_data["isVersionOverrideApplied"]
         )
 
         return ConnectorVersionInfo(
             connector_id=actor_id,
             connector_type=actor_type,
             version=version_data["dockerImageTag"],
-            is_version_pinned=version_data["isVersionOverrideApplied"],
+            is_version_pinned=is_pinned,
         )
     except CloudAuthError:
         raise

airbyte_ops_mcp/mcp/gcp_logs.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
+"""MCP tools for GCP Cloud Logging operations.
+
+This module provides MCP tools for querying GCP Cloud Logging,
+particularly for looking up error details by error ID.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastmcp import FastMCP
+from pydantic import Field
+
+from airbyte_ops_mcp.gcp_logs import (
+    GCPLogSearchResult,
+    GCPSeverity,
+    fetch_error_logs,
+)
+from airbyte_ops_mcp.gcp_logs.error_lookup import DEFAULT_GCP_PROJECT
+from airbyte_ops_mcp.mcp._mcp_utils import mcp_tool, register_mcp_tools
+
+
+@mcp_tool(
+    read_only=True,
+    idempotent=True,
+)
+def lookup_cloud_backend_error(
+    error_id: Annotated[
+        str,
+        Field(
+            description=(
+                "The error ID (UUID) to search for. This is typically returned "
+                "in API error responses as {'errorId': '...'}"
+            )
+        ),
+    ],
+    project: Annotated[
+        str,
+        Field(
+            default=DEFAULT_GCP_PROJECT,
+            description=(
+                "GCP project ID to search in. Defaults to 'prod-ab-cloud-proj' "
+                "(Airbyte Cloud production)."
+            ),
+        ),
+    ],
+    lookback_days: Annotated[
+        int,
+        Field(
+            default=7,
+            description="Number of days to look back in logs. Defaults to 7.",
+        ),
+    ],
+    min_severity_filter: Annotated[
+        GCPSeverity | None,
+        Field(
+            default=None,
+            description="Optional minimum severity level to filter logs.",
+        ),
+    ],
+    max_log_entries: Annotated[
+        int,
+        Field(
+            default=200,
+            description="Maximum number of log entries to return. Defaults to 200.",
+        ),
+    ],
+) -> GCPLogSearchResult:
+    """Look up error details from GCP Cloud Logging by error ID.
+
+    When an Airbyte Cloud API returns an error response with only an error ID
+    (e.g., {"errorId": "3173452e-8f22-4286-a1ec-b0f16c1e078a"}), this tool
+    fetches the full stack trace and error details from GCP Cloud Logging.
+
+    The tool searches for log entries containing the error ID and fetches
+    related entries (multi-line stack traces) from the same timestamp and pod.
+
+    Requires GCP credentials with Logs Viewer role on the target project.
+    """
+    return fetch_error_logs(
+        error_id=error_id,
+        project=project,
+        lookback_days=lookback_days,
+        min_severity_filter=min_severity_filter,
+        max_log_entries=max_log_entries,
+    )
+
+
+def register_gcp_logs_tools(app: FastMCP) -> None:
+    """Register GCP logs tools with the FastMCP app."""
+    register_mcp_tools(app)

airbyte_ops_mcp/mcp/prod_db_queries.py

@@ -8,6 +8,7 @@ airbyte_ops_mcp.prod_db_access.queries for use by AI agents.
 from __future__ import annotations
 
 from datetime import datetime
+from enum import StrEnum
 from typing import Annotated, Any
 
 import requests
@@ -25,11 +26,21 @@ from airbyte_ops_mcp.prod_db_access.queries import (
     query_dataplanes_list,
     query_failed_sync_attempts_for_connector,
     query_new_connector_releases,
-    query_sync_results_for_version,
+    query_recent_syncs_for_connector,
+    query_syncs_for_version_pinned_connector,
     query_workspace_info,
     query_workspaces_by_email_domain,
 )
 
+
+class StatusFilter(StrEnum):
+    """Filter for job status in sync queries."""
+
+    ALL = "all"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
 # Cloud UI base URL for building connection URLs
 CLOUD_UI_BASE_URL = "https://cloud.airbyte.com"
 
@@ -293,7 +304,7 @@ def query_prod_actors_by_connector_version(
     read_only=True,
     idempotent=True,
 )
-def query_prod_connector_version_sync_results(
+def query_prod_recent_syncs_for_version_pinned_connector(
     connector_version_id: Annotated[
         str,
         Field(description="Connector version UUID to find sync results for"),
@@ -314,11 +325,16 @@ def query_prod_connector_version_sync_results(
         ),
     ] = False,
 ) -> list[dict[str, Any]]:
-    """List sync job results for actors pinned to a specific connector version.
+    """List sync job results for actors PINNED to a specific connector version.
 
-    Returns sync job results for connections using actors that are pinned
-    to the specified version. Useful for monitoring rollout health and
-    identifying issues with specific connector versions.
+    IMPORTANT: This tool ONLY returns results for actors that have been explicitly
+    pinned to the specified version via scoped_configuration. Most connections run
+    unpinned and will NOT appear in these results.
+
+    Use this tool when you want to monitor rollout health for actors that have been
+    explicitly pinned to a pre-release or specific version. For finding healthy
+    connections across ALL actors using a connector type (regardless of pinning),
+    use query_prod_recent_syncs_for_connector instead.
 
     The actor_id field is the actor ID (superset of source_id/destination_id).
 
@@ -327,7 +343,7 @@ def query_prod_connector_version_sync_results(
     pin_origin_type, pin_origin, workspace_id, workspace_name, organization_id,
     dataplane_group_id, dataplane_name
     """
-    return query_sync_results_for_version(
+    return query_syncs_for_version_pinned_connector(
         connector_version_id,
         days=days,
         limit=limit,
@@ -335,6 +351,163 @@ def query_prod_connector_version_sync_results(
     )
 
 
+@mcp_tool(
+    read_only=True,
+    idempotent=True,
+    open_world=True,
+)
+def query_prod_recent_syncs_for_connector(
+    source_definition_id: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Source connector definition ID (UUID) to search for. "
+                "Provide this OR source_canonical_name OR destination_definition_id "
+                "OR destination_canonical_name (exactly one required). "
+                "Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
+            ),
+            default=None,
+        ),
+    ],
+    source_canonical_name: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Canonical source connector name to search for. "
+                "Provide this OR source_definition_id OR destination_definition_id "
+                "OR destination_canonical_name (exactly one required). "
+                "Examples: 'source-youtube-analytics', 'YouTube Analytics'."
+            ),
+            default=None,
+        ),
+    ],
+    destination_definition_id: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Destination connector definition ID (UUID) to search for. "
+                "Provide this OR destination_canonical_name OR source_definition_id "
+                "OR source_canonical_name (exactly one required). "
+                "Example: '94bd199c-2ff0-4aa2-b98e-17f0acb72610' for DuckDB."
+            ),
+            default=None,
+        ),
+    ],
+    destination_canonical_name: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Canonical destination connector name to search for. "
+                "Provide this OR destination_definition_id OR source_definition_id "
+                "OR source_canonical_name (exactly one required). "
+                "Examples: 'destination-duckdb', 'DuckDB'."
+            ),
+            default=None,
+        ),
+    ],
+    status_filter: Annotated[
+        StatusFilter,
+        Field(
+            description=(
+                "Filter by job status: 'all' (default), 'succeeded', or 'failed'. "
+                "Use 'succeeded' to find healthy connections with recent successful syncs. "
+                "Use 'failed' to find connections with recent failures."
+            ),
+            default=StatusFilter.ALL,
+        ),
+    ],
+    organization_id: Annotated[
+        str | OrganizationAliasEnum | None,
+        Field(
+            description=(
+                "Optional organization ID (UUID) or alias to filter results. "
+                "If provided, only syncs from this organization will be returned. "
+                "Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
+            ),
+            default=None,
+        ),
+    ],
+    lookback_days: Annotated[
+        int,
+        Field(description="Number of days to look back (default: 7)", default=7),
+    ],
+    limit: Annotated[
+        int,
+        Field(description="Maximum number of results (default: 100)", default=100),
+    ],
+) -> list[dict[str, Any]]:
+    """List recent sync jobs for ALL actors using a connector type.
+
+    This tool finds all actors with the given connector definition and returns their
+    recent sync jobs, regardless of whether they have explicit version pins. It filters
+    out deleted actors, deleted workspaces, and deprecated connections.
+
+    Use this tool to:
+    - Find healthy connections with recent successful syncs (status_filter='succeeded')
+    - Investigate connector issues across all users (status_filter='failed')
+    - Get an overview of all recent sync activity (status_filter='all')
+
+    Supports both SOURCE and DESTINATION connectors. Provide exactly one of:
+    source_definition_id, source_canonical_name, destination_definition_id,
+    or destination_canonical_name.
+
+    Key fields in results:
+    - job_status: 'succeeded', 'failed', 'cancelled', etc.
+    - connection_id, connection_name: The connection that ran the sync
+    - actor_id, actor_name: The source or destination actor
+    - pin_origin_type, pin_origin, pinned_version_id: Version pin context (NULL if not pinned)
+    """
+    # Validate that exactly one connector parameter is provided
+    provided_params = [
+        source_definition_id,
+        source_canonical_name,
+        destination_definition_id,
+        destination_canonical_name,
+    ]
+    num_provided = sum(p is not None for p in provided_params)
+    if num_provided != 1:
+        raise PyAirbyteInputError(
+            message=(
+                "Exactly one of source_definition_id, source_canonical_name, "
+                "destination_definition_id, or destination_canonical_name must be provided."
+            ),
+        )
+
+    # Determine if this is a destination connector
+    is_destination = (
+        destination_definition_id is not None or destination_canonical_name is not None
+    )
+
+    # 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,
+        )
+    elif destination_canonical_name:
+        resolved_definition_id = _resolve_canonical_name_to_definition_id(
+            canonical_name=destination_canonical_name,
+        )
+    elif source_definition_id:
+        resolved_definition_id = source_definition_id
+    else:
+        # We've validated exactly one param is provided, so this must be set
+        assert destination_definition_id is not None
+        resolved_definition_id = destination_definition_id
+
+    # Resolve organization ID alias
+    resolved_organization_id = OrganizationAliasEnum.resolve(organization_id)
+
+    return query_recent_syncs_for_connector(
+        connector_definition_id=resolved_definition_id,
+        is_destination=is_destination,
+        status_filter=status_filter,
+        organization_id=resolved_organization_id,
+        days=lookback_days,
+        limit=limit,
+    )
+
+
 @mcp_tool(
     read_only=True,
     idempotent=True,

airbyte_ops_mcp/mcp/server.py

@@ -24,6 +24,7 @@ from airbyte_ops_mcp.constants import MCP_SERVER_NAME
 from airbyte_ops_mcp.mcp.cloud_connector_versions import (
     register_cloud_connector_version_tools,
 )
+from airbyte_ops_mcp.mcp.gcp_logs import register_gcp_logs_tools
 from airbyte_ops_mcp.mcp.github import register_github_tools
 from airbyte_ops_mcp.mcp.github_repo_ops import register_github_repo_ops_tools
 from airbyte_ops_mcp.mcp.prerelease import register_prerelease_tools
@@ -62,6 +63,7 @@ def register_server_assets(app: FastMCP) -> None:
     register_prerelease_tools(app)
     register_cloud_connector_version_tools(app)
     register_prod_db_query_tools(app)
+    register_gcp_logs_tools(app)
     register_prompts(app)
     register_regression_tests_tools(app)
 

airbyte_ops_mcp/prod_db_access/queries.py

@@ -29,6 +29,12 @@ from airbyte_ops_mcp.prod_db_access.sql import (
     SELECT_FAILED_SYNC_ATTEMPTS_FOR_CONNECTOR,
     SELECT_NEW_CONNECTOR_RELEASES,
     SELECT_ORG_WORKSPACES,
+    SELECT_RECENT_FAILED_SYNCS_FOR_DESTINATION_CONNECTOR,
+    SELECT_RECENT_FAILED_SYNCS_FOR_SOURCE_CONNECTOR,
+    SELECT_RECENT_SUCCESSFUL_SYNCS_FOR_DESTINATION_CONNECTOR,
+    SELECT_RECENT_SUCCESSFUL_SYNCS_FOR_SOURCE_CONNECTOR,
+    SELECT_RECENT_SYNCS_FOR_DESTINATION_CONNECTOR,
+    SELECT_RECENT_SYNCS_FOR_SOURCE_CONNECTOR,
     SELECT_SUCCESSFUL_SYNCS_FOR_VERSION,
     SELECT_SYNC_RESULTS_FOR_VERSION,
     SELECT_WORKSPACE_INFO,
@@ -227,7 +233,7 @@ def query_actors_pinned_to_version(
     )
 
 
-def query_sync_results_for_version(
+def query_syncs_for_version_pinned_connector(
     connector_version_id: str,
     days: int = 7,
     limit: int = 100,
@@ -320,6 +326,81 @@ def query_failed_sync_attempts_for_connector(
     return results
 
 
+def query_recent_syncs_for_connector(
+    connector_definition_id: str,
+    is_destination: bool = False,
+    status_filter: str = "all",
+    organization_id: str | None = None,
+    days: int = 7,
+    limit: int = 100,
+    *,
+    gsm_client: secretmanager.SecretManagerServiceClient | None = None,
+) -> list[dict[str, Any]]:
+    """Query recent sync jobs for ALL actors using a connector definition.
+
+    Finds all actors with the given actor_definition_id and returns their sync jobs,
+    regardless of whether they have explicit version pins. Filters out deleted actors,
+    deleted workspaces, and deprecated connections.
+
+    This is useful for finding healthy connections with recent successful syncs,
+    or for investigating connector issues across all users.
+
+    Args:
+        connector_definition_id: Connector definition UUID to filter by
+        is_destination: If True, query destination connectors; if False, query sources
+        status_filter: Filter by job status - "all", "succeeded", or "failed"
+        organization_id: Optional organization UUID to filter results by (post-query filter)
+        days: Number of days to look back (default: 7)
+        limit: Maximum number of results (default: 100)
+        gsm_client: GCP Secret Manager client. If None, a new client will be instantiated.
+
+    Returns:
+        List of sync job records with workspace info and optional pin context
+    """
+    cutoff_date = datetime.now(timezone.utc) - timedelta(days=days)
+
+    # Select the appropriate query based on connector type and status filter
+    if is_destination:
+        if status_filter == "succeeded":
+            query = SELECT_RECENT_SUCCESSFUL_SYNCS_FOR_DESTINATION_CONNECTOR
+            query_name = "SELECT_RECENT_SUCCESSFUL_SYNCS_FOR_DESTINATION_CONNECTOR"
+        elif status_filter == "failed":
+            query = SELECT_RECENT_FAILED_SYNCS_FOR_DESTINATION_CONNECTOR
+            query_name = "SELECT_RECENT_FAILED_SYNCS_FOR_DESTINATION_CONNECTOR"
+        else:
+            query = SELECT_RECENT_SYNCS_FOR_DESTINATION_CONNECTOR
+            query_name = "SELECT_RECENT_SYNCS_FOR_DESTINATION_CONNECTOR"
+    else:
+        if status_filter == "succeeded":
+            query = SELECT_RECENT_SUCCESSFUL_SYNCS_FOR_SOURCE_CONNECTOR
+            query_name = "SELECT_RECENT_SUCCESSFUL_SYNCS_FOR_SOURCE_CONNECTOR"
+        elif status_filter == "failed":
+            query = SELECT_RECENT_FAILED_SYNCS_FOR_SOURCE_CONNECTOR
+            query_name = "SELECT_RECENT_FAILED_SYNCS_FOR_SOURCE_CONNECTOR"
+        else:
+            query = SELECT_RECENT_SYNCS_FOR_SOURCE_CONNECTOR
+            query_name = "SELECT_RECENT_SYNCS_FOR_SOURCE_CONNECTOR"
+
+    results = _run_sql_query(
+        query,
+        parameters={
+            "connector_definition_id": connector_definition_id,
+            "cutoff_date": cutoff_date,
+            "limit": limit,
+        },
+        query_name=query_name,
+        gsm_client=gsm_client,
+    )
+
+    # Post-query filter by organization_id if provided
+    if organization_id is not None:
+        results = [
+            r for r in results if str(r.get("organization_id")) == organization_id
+        ]
+
+    return results
+
+
 def query_dataplanes_list(
     *,
     gsm_client: secretmanager.SecretManagerServiceClient | None = None,