airbyte.mcp.server

  1# Copyright (c) 2024 Airbyte, Inc., all rights reserved.
  2"""Experimental MCP (Model Context Protocol) server for PyAirbyte connector management."""
  3
  4from __future__ import annotations
  5
  6import asyncio
  7import sys
  8
  9from fastmcp_extensions import mcp_server
 10
 11from airbyte._util.meta import set_mcp_mode
 12from airbyte.mcp._config import load_secrets_to_env_vars
 13from airbyte.mcp._tool_utils import (
 14    AIRBYTE_EXCLUDE_MODULES_CONFIG_ARG,
 15    AIRBYTE_INCLUDE_MODULES_CONFIG_ARG,
 16    AIRBYTE_READONLY_MODE_CONFIG_ARG,
 17    API_URL_CONFIG_ARG,
 18    BEARER_TOKEN_CONFIG_ARG,
 19    CLIENT_ID_CONFIG_ARG,
 20    CLIENT_SECRET_CONFIG_ARG,
 21    CONFIG_API_URL_CONFIG_ARG,
 22    WORKSPACE_ID_CONFIG_ARG,
 23    airbyte_module_filter,
 24    airbyte_readonly_mode_filter,
 25    airbyte_ui_support_filter,
 26)
 27from airbyte.mcp.cloud import register_cloud_tools
 28from airbyte.mcp.interactive import register_interactive_tools
 29from airbyte.mcp.local import register_local_tools
 30from airbyte.mcp.prompts import register_prompts
 31from airbyte.mcp.registry import register_registry_tools
 32
 33
 34# =============================================================================
 35# Server Instructions
 36# =============================================================================
 37# This text is provided to AI agents via the MCP protocol's "instructions" field.
 38# It helps agents understand when to use this server's tools, especially when
 39# tool search is enabled. For more context, see:
 40# - FastMCP docs: https://gofastmcp.com/servers/overview
 41# - Claude tool search: https://www.anthropic.com/news/tool-use-improvements
 42# =============================================================================
 43
 44MCP_SERVER_INSTRUCTIONS = """
 45PyAirbyte connector management and data integration server for discovering,
 46deploying, and running Airbyte connectors.
 47
 48Use this server for:
 49- Discovering connectors from the Airbyte registry (sources and destinations)
 50- Deploying sources, destinations, and connections to Airbyte Cloud
 51- Running cloud syncs and monitoring sync status
 52- Managing custom connector definitions in Airbyte Cloud
 53- Local connector execution for data extraction without cloud deployment
 54- Listing and describing environment variables for connector configuration
 55
 56Operational modes:
 57- Cloud operations: Deploy and manage connectors on Airbyte Cloud (requires
 58  AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET, AIRBYTE_CLOUD_WORKSPACE_ID)
 59- Local operations: Run connectors locally for data extraction (requires
 60  AIRBYTE_PROJECT_DIR for artifact storage)
 61
 62Safety features:
 63- Safe mode (default): Restricts destructive operations to objects created in
 64  the current session
 65- Read-only mode: Disables all write operations for cloud resources
 66""".strip()
 67
 68set_mcp_mode()
 69load_secrets_to_env_vars()
 70
 71app = mcp_server(
 72    name="airbyte-mcp",
 73    package_name="airbyte",
 74    instructions=MCP_SERVER_INSTRUCTIONS,
 75    include_standard_tool_filters=True,
 76    server_config_args=[
 77        AIRBYTE_READONLY_MODE_CONFIG_ARG,
 78        AIRBYTE_EXCLUDE_MODULES_CONFIG_ARG,
 79        AIRBYTE_INCLUDE_MODULES_CONFIG_ARG,
 80        WORKSPACE_ID_CONFIG_ARG,
 81        BEARER_TOKEN_CONFIG_ARG,
 82        CLIENT_ID_CONFIG_ARG,
 83        CLIENT_SECRET_CONFIG_ARG,
 84        API_URL_CONFIG_ARG,
 85        CONFIG_API_URL_CONFIG_ARG,
 86    ],
 87    tool_filters=[
 88        airbyte_readonly_mode_filter,
 89        airbyte_module_filter,
 90        airbyte_ui_support_filter,
 91    ],
 92)
 93"""The Airbyte MCP Server application instance."""
 94
 95# Register tools from each module
 96register_cloud_tools(app)
 97register_local_tools(app)
 98register_registry_tools(app)
 99register_interactive_tools(app)
100register_prompts(app)
101
102
103def main() -> None:
104    """@private Main entry point for the MCP server.
105
106    This function starts the FastMCP server to handle MCP requests.
107
108    It should not be called directly; instead, consult the MCP client documentation
109    for instructions on how to connect to the server.
110    """
111    print("Starting Airbyte MCP server.", file=sys.stderr)
112    try:
113        asyncio.run(app.run_stdio_async())
114    except KeyboardInterrupt:
115        print("Airbyte MCP server interrupted by user.", file=sys.stderr)
116    except Exception as ex:
117        print(f"Error running Airbyte MCP server: {ex}", file=sys.stderr)
118        sys.exit(1)
119
120    print("Airbyte MCP server stopped.", file=sys.stderr)
121
122
123if __name__ == "__main__":
124    main()