airbyte_ops_mcp.mcp.github_repo_ops

  1# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
  2"""MCP tools for GitHub repository operations.
  3
  4This module exposes repository operations as MCP tools for AI agents to use.
  5These are thin wrappers around capability functions in airbyte_repo module.
  6
  7## MCP reference
  8
  9.. include:: ../../../docs/mcp-generated/github_repo_ops.md
 10    :start-line: 2
 11"""
 12
 13from __future__ import annotations
 14
 15__all__: list[str] = []
 16
 17from typing import Annotated, Literal
 18
 19from fastmcp import FastMCP
 20from fastmcp_extensions import mcp_tool, register_mcp_tools
 21from pydantic import BaseModel
 22
 23from airbyte_ops_mcp.airbyte_repo.bump_version import bump_connector_version
 24from airbyte_ops_mcp.airbyte_repo.list_connectors import list_connectors
 25from airbyte_ops_mcp.airbyte_repo.utils import resolve_diff_range
 26
 27
 28class ConnectorListResponse(BaseModel):
 29    """Response model for list_connectors MCP tool."""
 30
 31    connectors: list[str]
 32    count: int
 33
 34
 35class BumpVersionResponse(BaseModel):
 36    """Response model for bump_connector_version MCP tool."""
 37
 38    connector: str
 39    previous_version: str
 40    new_version: str
 41    files_modified: list[str]
 42    dry_run: bool
 43
 44
 45@mcp_tool(
 46    read_only=True,
 47    idempotent=True,
 48    open_world=False,
 49)
 50def list_connectors_in_repo(
 51    repo_path: Annotated[str, "Absolute path to the Airbyte monorepo"],
 52    certified: Annotated[
 53        bool | None,
 54        "Filter by certification: True=certified only, False=non-certified only, None=all",
 55    ] = None,
 56    modified: Annotated[
 57        bool | None,
 58        "Filter by modification: True=modified only, False=not-modified only, None=all",
 59    ] = None,
 60    language_filter: Annotated[
 61        set[str] | None,
 62        "Set of languages to include (python, java, low-code, manifest-only)",
 63    ] = None,
 64    language_exclude: Annotated[
 65        set[str] | None,
 66        "Set of languages to exclude (mutually exclusive with language_filter)",
 67    ] = None,
 68    connector_type: Annotated[
 69        Literal["source", "destination"] | None,
 70        "Filter by connector type: 'source' or 'destination', None=all",
 71    ] = None,
 72    connector_subtype: Annotated[
 73        Literal["api", "database", "file", "custom"] | None,
 74        "Filter by connector subtype: 'api', 'database', 'file', 'custom', None=all",
 75    ] = None,
 76    pr_num_or_url: Annotated[
 77        str | None,
 78        "PR number (e.g., '123'), GitHub URL, or None to auto-detect from GITHUB_REF environment variable",
 79    ] = None,
 80    gh_token: Annotated[
 81        str | None,
 82        "GitHub API token. When provided together with pr_num_or_url, the GitHub API is used "
 83        "to detect modified files instead of local git diff (avoids shallow-clone issues).",
 84    ] = None,
 85) -> ConnectorListResponse:
 86    """List connectors in the Airbyte monorepo with flexible filtering.
 87
 88    Filters can be combined to narrow results. PR context (if provided or auto-detected)
 89    determines the git diff range for modification detection.
 90    """
 91    # Resolve PR info to base_ref and head_ref (MCP-specific: supports PR URL/number input)
 92    base_ref, head_ref, pr_number, pr_owner, pr_repo = resolve_diff_range(pr_num_or_url)
 93
 94    # Delegate to capability function
 95    result = list_connectors(
 96        repo_path=repo_path,
 97        certified=certified,
 98        modified=modified,
 99        language_filter=language_filter,
100        language_exclude=language_exclude,
101        connector_type=connector_type,
102        connector_subtype=connector_subtype,
103        base_ref=base_ref,
104        head_ref=head_ref,
105        pr_number=pr_number,
106        pr_owner=pr_owner,
107        pr_repo=pr_repo,
108        gh_token=gh_token,
109    )
110
111    return ConnectorListResponse(
112        connectors=result.connectors,
113        count=result.count,
114    )
115
116
117@mcp_tool(
118    read_only=False,
119    idempotent=False,
120    open_world=False,
121)
122def bump_version_in_repo(
123    repo_path: Annotated[str, "Absolute path to the Airbyte monorepo"],
124    connector_name: Annotated[str, "Connector technical name (e.g., 'source-github')"],
125    bump_type: Annotated[
126        Literal[
127            "patch",
128            "minor",
129            "major",
130            "patch_rc",
131            "minor_rc",
132            "major_rc",
133            "rc",
134            "promote",
135        ]
136        | None,
137        "Version bump type. Standard: 'patch', 'minor', 'major'. "
138        "RC: 'patch_rc', 'minor_rc', 'major_rc' (create RC for next version), "
139        "'rc' (smart default: minor_rc if not RC, else bump RC number). "
140        "'promote' (strip RC suffix to finalize release).",
141    ] = None,
142    new_version: Annotated[
143        str | None,
144        "Explicit new version (overrides bump_type if provided)",
145    ] = None,
146    changelog_message: Annotated[
147        str | None,
148        "Message to add to changelog (optional)",
149    ] = None,
150    pr_number: Annotated[
151        int | None,
152        "PR number for changelog entry (optional)",
153    ] = None,
154    dry_run: Annotated[
155        bool,
156        "If True, show what would be changed without modifying files",
157    ] = False,
158) -> BumpVersionResponse:
159    """Bump a connector's version across all relevant files.
160
161    Updates version in metadata.yaml (always), pyproject.toml (if exists),
162    and documentation changelog (if changelog_message provided).
163
164    Either bump_type or new_version must be provided.
165
166    RC bump types (patch_rc, minor_rc, major_rc) only work on non-RC versions.
167    If the version is already an RC, use 'rc' to bump the RC number or 'promote' to finalize.
168    """
169    # Delegate to capability function (validation happens there)
170    result = bump_connector_version(
171        repo_path=repo_path,
172        connector_name=connector_name,
173        bump_type=bump_type,
174        new_version=new_version,
175        changelog_message=changelog_message,
176        pr_number=pr_number,
177        dry_run=dry_run,
178    )
179
180    return BumpVersionResponse(
181        connector=result.connector,
182        previous_version=result.previous_version,
183        new_version=result.new_version,
184        files_modified=result.files_modified,
185        dry_run=result.dry_run,
186    )
187
188
189def register_github_repo_ops_tools(app: FastMCP) -> None:
190    """Register GitHub repository operation tools with the FastMCP app.
191
192    Args:
193        app: FastMCP application instance
194    """
195    register_mcp_tools(app, mcp_module=__name__)