airbyte_ops_mcp.constants

Constants for the Airbyte Admin MCP server.

  1# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
  2"""Constants for the Airbyte Admin MCP server."""
  3
  4from __future__ import annotations
  5
  6from enum import Enum, StrEnum
  7
  8from airbyte.exceptions import PyAirbyteInputError
  9
 10from airbyte_ops_mcp.registry._constants import PROD_METADATA_SERVICE_BUCKET_NAME
 11
 12MCP_SERVER_NAME = "airbyte-internal-ops"
 13"""The name of the MCP server."""
 14
 15PACKAGE_NAME = "airbyte-internal-ops"
 16"""The installed package name, as declared in `pyproject.toml`."""
 17
 18
 19class ServerConfigKey(StrEnum):
 20    """Config keys for MCP server configuration arguments.
 21
 22    These keys are used both when defining server_config_args in mcp_server()
 23    and when retrieving config values via get_mcp_config().
 24    """
 25
 26    BEARER_TOKEN = "bearer_token"
 27    CLIENT_ID = "client_id"
 28    CLIENT_SECRET = "client_secret"
 29
 30
 31USER_AGENT = "Airbyte-Internal-Ops Python client"
 32"""User-Agent string for HTTP requests to Airbyte Cloud APIs."""
 33
 34# Environment variable names for internal admin authentication
 35ENV_AIRBYTE_INTERNAL_ADMIN_FLAG = "AIRBYTE_INTERNAL_ADMIN_FLAG"
 36ENV_AIRBYTE_INTERNAL_ADMIN_USER = "AIRBYTE_INTERNAL_ADMIN_USER"
 37
 38# Environment variable for GCP credentials (JSON content, not file path)
 39ENV_GCP_BIGQUERY_CREDENTIALS = "GCP_BIGQUERY_CREDENTIALS"
 40"""Environment variable containing GCP credentials for BigQuery access."""
 41
 42ENV_GCP_PROD_DB_ACCESS_CREDENTIALS = "GCP_PROD_DB_ACCESS_CREDENTIALS"
 43"""Environment variable containing GCP service account JSON credentials for prod DB access."""
 44
 45ENV_K_SERVICE = "K_SERVICE"
 46"""Cloud Run env var set to the service name, used only for runtime detection."""
 47
 48# Expected values for internal admin authentication
 49EXPECTED_ADMIN_FLAG_VALUE = "airbyte.io"
 50EXPECTED_ADMIN_EMAIL_DOMAIN = "@airbyte.io"
 51
 52# =============================================================================
 53# HTTP Header Names for Airbyte Cloud Authentication
 54# =============================================================================
 55# These headers follow the PyAirbyte convention for passing credentials
 56# via HTTP when running as an MCP HTTP server.
 57
 58HEADER_AIRBYTE_CLOUD_CLIENT_ID = "X-Airbyte-Cloud-Client-Id"
 59"""HTTP header for OAuth client ID."""
 60
 61HEADER_AIRBYTE_CLOUD_CLIENT_SECRET = "X-Airbyte-Cloud-Client-Secret"
 62"""HTTP header for OAuth client secret."""
 63
 64HEADER_AIRBYTE_CLOUD_WORKSPACE_ID = "X-Airbyte-Cloud-Workspace-Id"
 65"""HTTP header for default workspace ID."""
 66
 67HEADER_AIRBYTE_CLOUD_API_URL = "X-Airbyte-Cloud-Api-Url"
 68"""HTTP header for API root URL override."""
 69
 70# =============================================================================
 71# GCP and Prod DB Constants (from connection-retriever)
 72# =============================================================================
 73
 74GCP_PROJECT_NAME = "prod-ab-cloud-proj"
 75"""The GCP project name for Airbyte Cloud production."""
 76
 77CLOUD_SQL_INSTANCE = "prod-ab-cloud-proj:us-west3:prod-pgsql-replica"
 78"""The Cloud SQL instance connection name for the Prod DB Replica."""
 79
 80DEFAULT_CLOUD_SQL_PROXY_PORT = 15432
 81"""Default port for Cloud SQL Proxy connections."""
 82
 83CLOUD_SQL_PROXY_PID_FILE = "/tmp/airbyte-cloud-sql-proxy.pid"
 84"""PID file for tracking the Cloud SQL Proxy process."""
 85
 86CLOUD_REGISTRY_URL = (
 87    "https://connectors.airbyte.com/files/registries/v0/cloud_registry.json"
 88)
 89"""URL for the Airbyte Cloud connector registry."""
 90
 91CLOUD_REGISTRY_GCS_URL = (
 92    "https://storage.googleapis.com/"
 93    f"{PROD_METADATA_SERVICE_BUCKET_NAME}/registries/v0/cloud_registry.json"
 94)
 95"""Direct GCS URL for the Airbyte Cloud connector registry."""
 96
 97# =============================================================================
 98# Organization ID Aliases
 99# =============================================================================
100
101
102class OrganizationAliasEnum(StrEnum):
103    """Organization ID aliases that can be used in place of UUIDs.
104
105    Each member's name is the alias (e.g., "@airbyte-internal") and its value
106    is the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to
107    resolve aliases to actual IDs.
108    """
109
110    AIRBYTE_INTERNAL = "664c690e-5263-49ba-b01f-4a6759b3330a"
111    """The Airbyte internal organization for testing and internal operations.
112
113    Alias: @airbyte-internal
114    """
115
116    @classmethod
117    def resolve(cls, org_id: str | None) -> str | None:
118        """Resolve an organization ID alias to its actual UUID.
119
120        Accepts either an alias string (e.g., "@airbyte-internal") or an
121        OrganizationAliasEnum enum member, and returns the actual UUID.
122
123        Returns:
124            The resolved organization ID (UUID), or None if input is None.
125            If the input doesn't start with "@", it is returned unchanged.
126
127        Raises:
128            PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
129        """
130        if org_id is None:
131            return None
132
133        # Handle OrganizationAliasEnum enum members directly
134        if isinstance(org_id, cls):
135            return org_id.value
136
137        # If it doesn't look like an alias, return as-is (assume it's a UUID)
138        if not org_id.startswith("@"):
139            return org_id
140
141        # Handle alias strings or raise an error if invalid
142        alias_mapping = {
143            "@airbyte-internal": cls.AIRBYTE_INTERNAL.value,
144        }
145        if org_id not in alias_mapping:
146            raise PyAirbyteInputError(
147                message=f"Unknown organization alias: {org_id}",
148                context={
149                    "valid_aliases": list(alias_mapping.keys()),
150                },
151            )
152        return alias_mapping[org_id]
153
154
155# =============================================================================
156# Workspace ID Aliases
157# =============================================================================
158
159
160class WorkspaceAliasEnum(StrEnum):
161    """Workspace ID aliases that can be used in place of UUIDs.
162
163    Each member's name is the alias (e.g., "@devin-ai-sandbox") and its value
164    is the actual workspace UUID. Use `WorkspaceAliasEnum.resolve()` to
165    resolve aliases to actual IDs.
166    """
167
168    DEVIN_AI_SANDBOX = "266ebdfe-0d7b-4540-9817-de7e4505ba61"
169    """The Devin AI sandbox workspace for testing and development.
170
171    Alias: @devin-ai-sandbox
172    """
173
174    @classmethod
175    def resolve(cls, workspace_id: str | None) -> str | None:
176        """Resolve a workspace ID alias to its actual UUID.
177
178        Accepts either an alias string (e.g., "@devin-ai-sandbox") or a
179        WorkspaceAliasEnum enum member, and returns the actual UUID.
180
181        Returns:
182            The resolved workspace ID (UUID), or None if input is None.
183            If the input doesn't start with "@", it is returned unchanged.
184
185        Raises:
186            PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
187        """
188        if workspace_id is None:
189            return None
190
191        # Handle WorkspaceAliasEnum enum members directly
192        if isinstance(workspace_id, cls):
193            return workspace_id.value
194
195        # If it doesn't look like an alias, return as-is (assume it's a UUID)
196        if not workspace_id.startswith("@"):
197            return workspace_id
198
199        # Handle alias strings or raise an error if invalid
200        alias_mapping = {
201            "@devin-ai-sandbox": cls.DEVIN_AI_SANDBOX.value,
202        }
203        if workspace_id not in alias_mapping:
204            raise PyAirbyteInputError(
205                message=f"Unknown workspace alias: {workspace_id}",
206                context={
207                    "valid_aliases": list(alias_mapping.keys()),
208                },
209            )
210        return alias_mapping[workspace_id]
211
212
213MEDIC_MODE_ENV_VAR = "AIRBYTE_OPS_MEDIC_MODE"
214"""Environment variable to enable emergency 'medic mode' write tools.
215
216When set to '1' or 'true', destructive MCP tools for connection state and catalog
217writes are registered. These are "break glass" operations for emergency use only.
218"""
219
220CONNECTION_RETRIEVER_PG_CONNECTION_DETAILS_SECRET_ID = (
221    "projects/587336813068/secrets/CONNECTION_RETRIEVER_PG_CONNECTION_DETAILS"
222)
223"""GCP Secret Manager ID for Prod DB connection details."""
224
225
226class ConnectionObject(Enum):
227    """Types of connection objects that can be retrieved."""
228
229    CONNECTION = "connection"
230    SOURCE_ID = "source-id"
231    DESTINATION_ID = "destination-id"
232    DESTINATION_CONFIG = "destination-config"
233    SOURCE_CONFIG = "source-config"
234    CATALOG = "catalog"
235    CONFIGURED_CATALOG = "configured-catalog"
236    STATE = "state"
237    WORKSPACE_ID = "workspace-id"
238    DESTINATION_DOCKER_IMAGE = "destination-docker-image"
239    SOURCE_DOCKER_IMAGE = "source-docker-image"
MCP_SERVER_NAME = 'airbyte-internal-ops'

The name of the MCP server.

PACKAGE_NAME = 'airbyte-internal-ops'

The installed package name, as declared in pyproject.toml.

class ServerConfigKey(enum.StrEnum):
20class ServerConfigKey(StrEnum):
21    """Config keys for MCP server configuration arguments.
22
23    These keys are used both when defining server_config_args in mcp_server()
24    and when retrieving config values via get_mcp_config().
25    """
26
27    BEARER_TOKEN = "bearer_token"
28    CLIENT_ID = "client_id"
29    CLIENT_SECRET = "client_secret"

Config keys for MCP server configuration arguments.

These keys are used both when defining server_config_args in mcp_server() and when retrieving config values via get_mcp_config().

BEARER_TOKEN = <ServerConfigKey.BEARER_TOKEN: 'bearer_token'>
CLIENT_ID = <ServerConfigKey.CLIENT_ID: 'client_id'>
CLIENT_SECRET = <ServerConfigKey.CLIENT_SECRET: 'client_secret'>
USER_AGENT = 'Airbyte-Internal-Ops Python client'

User-Agent string for HTTP requests to Airbyte Cloud APIs.

ENV_AIRBYTE_INTERNAL_ADMIN_FLAG = 'AIRBYTE_INTERNAL_ADMIN_FLAG'
ENV_AIRBYTE_INTERNAL_ADMIN_USER = 'AIRBYTE_INTERNAL_ADMIN_USER'
ENV_GCP_BIGQUERY_CREDENTIALS = 'GCP_BIGQUERY_CREDENTIALS'

Environment variable containing GCP credentials for BigQuery access.

ENV_GCP_PROD_DB_ACCESS_CREDENTIALS = 'GCP_PROD_DB_ACCESS_CREDENTIALS'

Environment variable containing GCP service account JSON credentials for prod DB access.

ENV_K_SERVICE = 'K_SERVICE'

Cloud Run env var set to the service name, used only for runtime detection.

EXPECTED_ADMIN_FLAG_VALUE = 'airbyte.io'
EXPECTED_ADMIN_EMAIL_DOMAIN = '@airbyte.io'
HEADER_AIRBYTE_CLOUD_CLIENT_ID = 'X-Airbyte-Cloud-Client-Id'

HTTP header for OAuth client ID.

HEADER_AIRBYTE_CLOUD_CLIENT_SECRET = 'X-Airbyte-Cloud-Client-Secret'

HTTP header for OAuth client secret.

HEADER_AIRBYTE_CLOUD_WORKSPACE_ID = 'X-Airbyte-Cloud-Workspace-Id'

HTTP header for default workspace ID.

HEADER_AIRBYTE_CLOUD_API_URL = 'X-Airbyte-Cloud-Api-Url'

HTTP header for API root URL override.

GCP_PROJECT_NAME = 'prod-ab-cloud-proj'

The GCP project name for Airbyte Cloud production.

CLOUD_SQL_INSTANCE = 'prod-ab-cloud-proj:us-west3:prod-pgsql-replica'

The Cloud SQL instance connection name for the Prod DB Replica.

DEFAULT_CLOUD_SQL_PROXY_PORT = 15432

Default port for Cloud SQL Proxy connections.

CLOUD_SQL_PROXY_PID_FILE = '/tmp/airbyte-cloud-sql-proxy.pid'

PID file for tracking the Cloud SQL Proxy process.

CLOUD_REGISTRY_URL = 'https://connectors.airbyte.com/files/registries/v0/cloud_registry.json'

URL for the Airbyte Cloud connector registry.

CLOUD_REGISTRY_GCS_URL = 'https://storage.googleapis.com/prod-airbyte-cloud-connector-metadata-service/registries/v0/cloud_registry.json'

Direct GCS URL for the Airbyte Cloud connector registry.

class OrganizationAliasEnum(enum.StrEnum):
103class OrganizationAliasEnum(StrEnum):
104    """Organization ID aliases that can be used in place of UUIDs.
105
106    Each member's name is the alias (e.g., "@airbyte-internal") and its value
107    is the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to
108    resolve aliases to actual IDs.
109    """
110
111    AIRBYTE_INTERNAL = "664c690e-5263-49ba-b01f-4a6759b3330a"
112    """The Airbyte internal organization for testing and internal operations.
113
114    Alias: @airbyte-internal
115    """
116
117    @classmethod
118    def resolve(cls, org_id: str | None) -> str | None:
119        """Resolve an organization ID alias to its actual UUID.
120
121        Accepts either an alias string (e.g., "@airbyte-internal") or an
122        OrganizationAliasEnum enum member, and returns the actual UUID.
123
124        Returns:
125            The resolved organization ID (UUID), or None if input is None.
126            If the input doesn't start with "@", it is returned unchanged.
127
128        Raises:
129            PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
130        """
131        if org_id is None:
132            return None
133
134        # Handle OrganizationAliasEnum enum members directly
135        if isinstance(org_id, cls):
136            return org_id.value
137
138        # If it doesn't look like an alias, return as-is (assume it's a UUID)
139        if not org_id.startswith("@"):
140            return org_id
141
142        # Handle alias strings or raise an error if invalid
143        alias_mapping = {
144            "@airbyte-internal": cls.AIRBYTE_INTERNAL.value,
145        }
146        if org_id not in alias_mapping:
147            raise PyAirbyteInputError(
148                message=f"Unknown organization alias: {org_id}",
149                context={
150                    "valid_aliases": list(alias_mapping.keys()),
151                },
152            )
153        return alias_mapping[org_id]

Organization ID aliases that can be used in place of UUIDs.

Each member's name is the alias (e.g., "@airbyte-internal") and its value is the actual organization UUID. Use OrganizationAliasEnum.resolve() to resolve aliases to actual IDs.

AIRBYTE_INTERNAL = <OrganizationAliasEnum.AIRBYTE_INTERNAL: '664c690e-5263-49ba-b01f-4a6759b3330a'>

The Airbyte internal organization for testing and internal operations.

Alias: @airbyte-internal

@classmethod
def resolve(cls, org_id: str | None) -> str | None:
117    @classmethod
118    def resolve(cls, org_id: str | None) -> str | None:
119        """Resolve an organization ID alias to its actual UUID.
120
121        Accepts either an alias string (e.g., "@airbyte-internal") or an
122        OrganizationAliasEnum enum member, and returns the actual UUID.
123
124        Returns:
125            The resolved organization ID (UUID), or None if input is None.
126            If the input doesn't start with "@", it is returned unchanged.
127
128        Raises:
129            PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
130        """
131        if org_id is None:
132            return None
133
134        # Handle OrganizationAliasEnum enum members directly
135        if isinstance(org_id, cls):
136            return org_id.value
137
138        # If it doesn't look like an alias, return as-is (assume it's a UUID)
139        if not org_id.startswith("@"):
140            return org_id
141
142        # Handle alias strings or raise an error if invalid
143        alias_mapping = {
144            "@airbyte-internal": cls.AIRBYTE_INTERNAL.value,
145        }
146        if org_id not in alias_mapping:
147            raise PyAirbyteInputError(
148                message=f"Unknown organization alias: {org_id}",
149                context={
150                    "valid_aliases": list(alias_mapping.keys()),
151                },
152            )
153        return alias_mapping[org_id]

Resolve an organization ID alias to its actual UUID.

Accepts either an alias string (e.g., "@airbyte-internal") or an OrganizationAliasEnum enum member, and returns the actual UUID.

Returns:

The resolved organization ID (UUID), or None if input is None. If the input doesn't start with "@", it is returned unchanged.

Raises:
  • PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
class WorkspaceAliasEnum(enum.StrEnum):
161class WorkspaceAliasEnum(StrEnum):
162    """Workspace ID aliases that can be used in place of UUIDs.
163
164    Each member's name is the alias (e.g., "@devin-ai-sandbox") and its value
165    is the actual workspace UUID. Use `WorkspaceAliasEnum.resolve()` to
166    resolve aliases to actual IDs.
167    """
168
169    DEVIN_AI_SANDBOX = "266ebdfe-0d7b-4540-9817-de7e4505ba61"
170    """The Devin AI sandbox workspace for testing and development.
171
172    Alias: @devin-ai-sandbox
173    """
174
175    @classmethod
176    def resolve(cls, workspace_id: str | None) -> str | None:
177        """Resolve a workspace ID alias to its actual UUID.
178
179        Accepts either an alias string (e.g., "@devin-ai-sandbox") or a
180        WorkspaceAliasEnum enum member, and returns the actual UUID.
181
182        Returns:
183            The resolved workspace ID (UUID), or None if input is None.
184            If the input doesn't start with "@", it is returned unchanged.
185
186        Raises:
187            PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
188        """
189        if workspace_id is None:
190            return None
191
192        # Handle WorkspaceAliasEnum enum members directly
193        if isinstance(workspace_id, cls):
194            return workspace_id.value
195
196        # If it doesn't look like an alias, return as-is (assume it's a UUID)
197        if not workspace_id.startswith("@"):
198            return workspace_id
199
200        # Handle alias strings or raise an error if invalid
201        alias_mapping = {
202            "@devin-ai-sandbox": cls.DEVIN_AI_SANDBOX.value,
203        }
204        if workspace_id not in alias_mapping:
205            raise PyAirbyteInputError(
206                message=f"Unknown workspace alias: {workspace_id}",
207                context={
208                    "valid_aliases": list(alias_mapping.keys()),
209                },
210            )
211        return alias_mapping[workspace_id]

Workspace ID aliases that can be used in place of UUIDs.

Each member's name is the alias (e.g., "@devin-ai-sandbox") and its value is the actual workspace UUID. Use WorkspaceAliasEnum.resolve() to resolve aliases to actual IDs.

DEVIN_AI_SANDBOX = <WorkspaceAliasEnum.DEVIN_AI_SANDBOX: '266ebdfe-0d7b-4540-9817-de7e4505ba61'>

The Devin AI sandbox workspace for testing and development.

Alias: @devin-ai-sandbox

@classmethod
def resolve(cls, workspace_id: str | None) -> str | None:
175    @classmethod
176    def resolve(cls, workspace_id: str | None) -> str | None:
177        """Resolve a workspace ID alias to its actual UUID.
178
179        Accepts either an alias string (e.g., "@devin-ai-sandbox") or a
180        WorkspaceAliasEnum enum member, and returns the actual UUID.
181
182        Returns:
183            The resolved workspace ID (UUID), or None if input is None.
184            If the input doesn't start with "@", it is returned unchanged.
185
186        Raises:
187            PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
188        """
189        if workspace_id is None:
190            return None
191
192        # Handle WorkspaceAliasEnum enum members directly
193        if isinstance(workspace_id, cls):
194            return workspace_id.value
195
196        # If it doesn't look like an alias, return as-is (assume it's a UUID)
197        if not workspace_id.startswith("@"):
198            return workspace_id
199
200        # Handle alias strings or raise an error if invalid
201        alias_mapping = {
202            "@devin-ai-sandbox": cls.DEVIN_AI_SANDBOX.value,
203        }
204        if workspace_id not in alias_mapping:
205            raise PyAirbyteInputError(
206                message=f"Unknown workspace alias: {workspace_id}",
207                context={
208                    "valid_aliases": list(alias_mapping.keys()),
209                },
210            )
211        return alias_mapping[workspace_id]

Resolve a workspace ID alias to its actual UUID.

Accepts either an alias string (e.g., "@devin-ai-sandbox") or a WorkspaceAliasEnum enum member, and returns the actual UUID.

Returns:

The resolved workspace ID (UUID), or None if input is None. If the input doesn't start with "@", it is returned unchanged.

Raises:
  • PyAirbyteInputError: If the input starts with "@" but is not a recognized alias.
MEDIC_MODE_ENV_VAR = 'AIRBYTE_OPS_MEDIC_MODE'

Environment variable to enable emergency 'medic mode' write tools.

When set to '1' or 'true', destructive MCP tools for connection state and catalog writes are registered. These are "break glass" operations for emergency use only.

CONNECTION_RETRIEVER_PG_CONNECTION_DETAILS_SECRET_ID = 'projects/587336813068/secrets/CONNECTION_RETRIEVER_PG_CONNECTION_DETAILS'

GCP Secret Manager ID for Prod DB connection details.

class ConnectionObject(enum.Enum):
227class ConnectionObject(Enum):
228    """Types of connection objects that can be retrieved."""
229
230    CONNECTION = "connection"
231    SOURCE_ID = "source-id"
232    DESTINATION_ID = "destination-id"
233    DESTINATION_CONFIG = "destination-config"
234    SOURCE_CONFIG = "source-config"
235    CATALOG = "catalog"
236    CONFIGURED_CATALOG = "configured-catalog"
237    STATE = "state"
238    WORKSPACE_ID = "workspace-id"
239    DESTINATION_DOCKER_IMAGE = "destination-docker-image"
240    SOURCE_DOCKER_IMAGE = "source-docker-image"

Types of connection objects that can be retrieved.

CONNECTION = <ConnectionObject.CONNECTION: 'connection'>
SOURCE_ID = <ConnectionObject.SOURCE_ID: 'source-id'>
DESTINATION_ID = <ConnectionObject.DESTINATION_ID: 'destination-id'>
DESTINATION_CONFIG = <ConnectionObject.DESTINATION_CONFIG: 'destination-config'>
SOURCE_CONFIG = <ConnectionObject.SOURCE_CONFIG: 'source-config'>
CATALOG = <ConnectionObject.CATALOG: 'catalog'>
CONFIGURED_CATALOG = <ConnectionObject.CONFIGURED_CATALOG: 'configured-catalog'>
STATE = <ConnectionObject.STATE: 'state'>
WORKSPACE_ID = <ConnectionObject.WORKSPACE_ID: 'workspace-id'>
DESTINATION_DOCKER_IMAGE = <ConnectionObject.DESTINATION_DOCKER_IMAGE: 'destination-docker-image'>
SOURCE_DOCKER_IMAGE = <ConnectionObject.SOURCE_DOCKER_IMAGE: 'source-docker-image'>