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    requires_client_filesystem=True,
 50)
 51def list_connectors_in_repo(
 52    repo_path: Annotated[str, "Absolute path to the Airbyte monorepo"],
 53    certified: Annotated[
 54        bool | None,
 55        "Filter by certification: True=certified only, False=non-certified only, None=all",
 56    ] = None,
 57    modified: Annotated[
 58        bool | None,
 59        "Filter by modification: True=modified only, False=not-modified only, None=all",
 60    ] = None,
 61    language_filter: Annotated[
 62        set[str] | None,
 63        "Set of languages to include (python, java, low-code, manifest-only)",
 64    ] = None,
 65    language_exclude: Annotated[
 66        set[str] | None,
 67        "Set of languages to exclude (mutually exclusive with language_filter)",
 68    ] = None,
 69    connector_type: Annotated[
 70        Literal["source", "destination"] | None,
 71        "Filter by connector type: 'source' or 'destination', None=all",
 72    ] = None,
 73    connector_subtype: Annotated[
 74        Literal["api", "database", "file", "custom"] | None,
 75        "Filter by connector subtype: 'api', 'database', 'file', 'custom', None=all",
 76    ] = None,
 77    pr_num_or_url: Annotated[
 78        str | None,
 79        "PR number (e.g., '123'), GitHub URL, or None to auto-detect from GITHUB_REF environment variable",
 80    ] = None,
 81    gh_token: Annotated[
 82        str | None,
 83        "GitHub API token. When provided together with pr_num_or_url, the GitHub API is used "
 84        "to detect modified files instead of local git diff (avoids shallow-clone issues).",
 85    ] = None,
 86) -> ConnectorListResponse:
 87    """List connectors in the Airbyte monorepo with flexible filtering.
 88
 89    Filters can be combined to narrow results. PR context (if provided or auto-detected)
 90    determines the git diff range for modification detection.
 91    """
 92    # Resolve PR info to base_ref and head_ref (MCP-specific: supports PR URL/number input)
 93    base_ref, head_ref, pr_number, pr_owner, pr_repo = resolve_diff_range(pr_num_or_url)
 94
 95    # Delegate to capability function
 96    result = list_connectors(
 97        repo_path=repo_path,
 98        certified=certified,
 99        modified=modified,
100        language_filter=language_filter,
101        language_exclude=language_exclude,
102        connector_type=connector_type,
103        connector_subtype=connector_subtype,
104        base_ref=base_ref,
105        head_ref=head_ref,
106        pr_number=pr_number,
107        pr_owner=pr_owner,
108        pr_repo=pr_repo,
109        gh_token=gh_token,
110    )
111
112    return ConnectorListResponse(
113        connectors=result.connectors,
114        count=result.count,
115    )
116
117
118@mcp_tool(
119    read_only=False,
120    idempotent=False,
121    open_world=False,
122    requires_client_filesystem=True,
123)
124def bump_version_in_repo(
125    repo_path: Annotated[str, "Absolute path to the Airbyte monorepo"],
126    connector_name: Annotated[str, "Connector technical name (e.g., 'source-github')"],
127    bump_type: Annotated[
128        Literal[
129            "patch",
130            "minor",
131            "major",
132            "patch_rc",
133            "minor_rc",
134            "major_rc",
135            "rc",
136            "promote",
137        ]
138        | None,
139        "Version bump type. Standard: 'patch', 'minor', 'major'. "
140        "RC: 'patch_rc', 'minor_rc', 'major_rc' (create RC for next version), "
141        "'rc' (smart default: minor_rc if not RC, else bump RC number). "
142        "'promote' (strip RC suffix to finalize release).",
143    ] = None,
144    new_version: Annotated[
145        str | None,
146        "Explicit new version (overrides bump_type if provided)",
147    ] = None,
148    changelog_message: Annotated[
149        str | None,
150        "Message to add to changelog (optional)",
151    ] = None,
152    pr_number: Annotated[
153        int | None,
154        "PR number for changelog entry (optional)",
155    ] = None,
156    dry_run: Annotated[
157        bool,
158        "If True, show what would be changed without modifying files",
159    ] = False,
160) -> BumpVersionResponse:
161    """Bump a connector's version across all relevant files.
162
163    Updates version in metadata.yaml (always), pyproject.toml (if exists),
164    and documentation changelog (if changelog_message provided).
165
166    Either bump_type or new_version must be provided.
167
168    RC bump types (patch_rc, minor_rc, major_rc) only work on non-RC versions.
169    If the version is already an RC, use 'rc' to bump the RC number or 'promote' to finalize.
170    """
171    # Delegate to capability function (validation happens there)
172    result = bump_connector_version(
173        repo_path=repo_path,
174        connector_name=connector_name,
175        bump_type=bump_type,
176        new_version=new_version,
177        changelog_message=changelog_message,
178        pr_number=pr_number,
179        dry_run=dry_run,
180    )
181
182    return BumpVersionResponse(
183        connector=result.connector,
184        previous_version=result.previous_version,
185        new_version=result.new_version,
186        files_modified=result.files_modified,
187        dry_run=result.dry_run,
188    )
189
190
191def register_github_repo_ops_tools(app: FastMCP) -> None:
192    """Register GitHub repository operation tools with the FastMCP app.
193
194    Args:
195        app: FastMCP application instance
196    """
197    register_mcp_tools(app, mcp_module=__name__)