secondshift 0.1.0b12__py3-none-any.whl

secondshift/connections/mcp/client.py

@@ -0,0 +1,353 @@
+"""The shared MCP client. Provider details come from the provider registry."""
+
+import json
+import re
+from datetime import timedelta
+from typing import Any
+
+import anyio
+from asgiref.sync import async_to_sync
+from django.conf import settings
+from django.db import IntegrityError, transaction
+from jsonschema import Draft202012Validator
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+from secondshift.connections.dao import binding_taken
+from secondshift.connections.mcp.base import (
+    SOURCE_AUTH,
+    CustomMCPToolError,
+    MCPError,
+    MCPProvider,
+    MCPRequestError,
+    MCPSettings,
+)
+from secondshift.connections.mcp.oauth import fresh_connection
+from secondshift.connections.mcp.providers import mcp_provider
+from secondshift.connections.mcp.schemas import validate_tool_schema
+from secondshift.connections.models import Connection
+from secondshift.connections.outbound import (
+    RESPONSE_MAX_BYTES,
+    host_label,
+    outbound_client,
+)
+from secondshift.connections.services import ConnectionConflict
+from secondshift.connections.tools import UnknownTools, store_tools
+from secondshift.workspaces.models import Workspace
+
+MCP_MAX_PAGES = 10
+MCP_ERROR_REASON_MAX_CHARS = 500
+# Custom servers keep every tool for the owner to choose from, up to this many.
+MCP_MAX_OFFERED_TOOLS = 200
+AUTH_STRATEGIES = {
+    "token": Connection.AuthStrategy.API_KEY,
+    "oauth": Connection.AuthStrategy.OAUTH,
+    SOURCE_AUTH: Connection.AuthStrategy.MANAGED,
+}
+
+
+def validate_mcp_connection(connection: Connection) -> MCPProvider:
+    """Fail closed unless the connection matches a built-in provider exactly."""
+    provider = mcp_provider(connection.provider)
+    if (
+        connection.kind != Connection.Kind.MCP
+        or connection.endpoint_url
+        != provider.endpoint(provider.clean_settings(connection.settings))
+        or connection.auth_strategy
+        not in {AUTH_STRATEGIES[method] for method in provider.auth_methods}
+        or connection.status != Connection.Status.CONNECTED
+        or (not borrows_source(connection) and not connection.access_token)
+        or connection.token_expired
+    ):
+        raise MCPError(f"This {provider.label} MCP connection is unavailable.")
+    return provider
+
+
+def borrows_source(connection: Connection) -> bool:
+    """The connection uses each repository's source token, and stores none."""
+    return connection.auth_strategy == Connection.AuthStrategy.MANAGED
+
+
+async def mcp_request(
+    connection: Connection,
+    tool: str | None = None,
+    arguments: dict[str, Any] | None = None,
+    token: str = "",
+) -> dict[str, Any]:
+    """Redact the token and keep HTTP exception text inside this boundary.
+
+    A connection that borrows a source passes the token it minted for the call.
+    """
+    provider = validate_mcp_connection(connection)
+    secret = token if borrows_source(connection) else connection.access_token
+    if not secret:
+        raise MCPError(f"This {provider.label} MCP connection is unavailable.")
+    try:
+        with anyio.fail_after(settings.OUTBOUND_TIMEOUT_SECONDS):
+            async with (
+                outbound_client(
+                    {
+                        **provider.headers,
+                        "Authorization": f"{provider.auth_scheme} {secret}",
+                    }
+                ) as client,
+                streamable_http_client(connection.endpoint_url, http_client=client) as (
+                    reader,
+                    writer,
+                    session_id,
+                ),
+                ClientSession(
+                    reader,
+                    writer,
+                    read_timeout_seconds=timedelta(
+                        seconds=settings.OUTBOUND_TIMEOUT_SECONDS
+                    ),
+                ) as session,
+            ):
+                del session_id
+                await session.initialize()
+                if tool is not None:
+                    payload = await call_tool(session, tool, arguments)
+                else:
+                    payload = await offered_tools(session, provider)
+    except Exception:
+        # SDK exception groups can embed request headers or remote response text.
+        raise MCPRequestError(
+            f"{provider.label} MCP request failed. Check the token, permissions, "
+            "and service availability."
+        ) from None
+    if tool is not None and payload.get("isError"):
+        # Raised outside the session so the catch-all above keeps its message.
+        text = error_text(payload)
+        if message := provider.tool_error(tool, text):
+            raise MCPRequestError(message)
+        message = f"{provider.label} could not complete this tool call."
+        if provider.key == Connection.Provider.MCP:
+            reason = text.replace(secret, "[redacted]").strip()
+            if reason:
+                raise CustomMCPToolError(message, reason[:MCP_ERROR_REASON_MAX_CHARS])
+        raise MCPRequestError(message)
+    encoded = json.dumps(payload)
+    if len(encoded.encode()) > RESPONSE_MAX_BYTES:
+        raise MCPError("The MCP result exceeded the size limit.")
+    return json.loads(encoded.replace(secret, "[redacted]"))
+
+
+async def call_tool(
+    session: ClientSession,
+    tool: str,
+    arguments: dict[str, Any] | None,
+) -> dict[str, Any]:
+    result = await session.call_tool(tool, arguments)
+    return result.model_dump(mode="json", by_alias=True)
+
+
+def error_text(payload: dict[str, Any]) -> str:
+    """Collect text blocks from a remote error before applying provider policy."""
+    return " ".join(
+        str(item.get("text", ""))
+        for item in payload.get("content", [])
+        if isinstance(item, dict) and item.get("type") == "text"
+    )
+
+
+def offered_tool(item: Any, provider: MCPProvider) -> dict[str, Any] | None:
+    """A listed tool the provider lets jobs use, or None to skip it."""
+    read_only = bool(item.annotations and item.annotations.readOnlyHint)
+    allowed = provider.owner_selects_tools or item.name in provider.tools
+    if not allowed or (provider.require_read_only_hint and not read_only):
+        return None
+    return {
+        "description": item.description or item.name,
+        "inputSchema": provider.narrow_schema(item.name, item.inputSchema),
+        "readOnly": read_only,
+    }
+
+
+async def offered_tools(
+    session: ClientSession, provider: MCPProvider
+) -> dict[str, Any]:
+    """Every usable tool, page by page, within the page and tool limits."""
+    tools: dict[str, Any] = {}
+    cursor = None
+    for _ in range(MCP_MAX_PAGES):
+        page = await session.list_tools(cursor=cursor)
+        for item in page.tools:
+            if (tool := offered_tool(item, provider)) is not None:
+                tools[item.name] = tool
+        if len(tools) > MCP_MAX_OFFERED_TOOLS:
+            raise MCPError("The MCP server offers too many tools.")
+        cursor = page.nextCursor
+        if not cursor:
+            break
+    else:
+        raise MCPError("MCP tool discovery exceeded the page limit.")
+    if not tools:
+        raise MCPError(f"{provider.label} exposed no supported tools.")
+    return tools
+
+
+def discovery_secret(connection: Connection, provider: MCPProvider) -> str:
+    if not borrows_source(connection):
+        return ""
+    if provider.discovery_token is None:
+        raise MCPError(f"{provider.label} needs its own token.")
+    return provider.discovery_token(connection.workspace)
+
+
+def discover_tools(connection: Connection) -> dict[str, Any]:
+    fresh_connection(connection)
+    provider = mcp_provider(connection.provider)
+    tools = async_to_sync(mcp_request)(
+        connection, token=discovery_secret(connection, provider)
+    )
+    for tool in tools.values():
+        schema = tool["inputSchema"]
+        validate_tool_schema(schema)
+        try:
+            Draft202012Validator.check_schema(schema)
+        except Exception:
+            raise MCPError("The MCP server returned an invalid tool schema.") from None
+        if schema.get("type") != "object":
+            raise MCPError("MCP tool arguments must be an object.")
+    return tools
+
+
+def connection_target(provider: MCPProvider, cleaned: MCPSettings) -> str:
+    """A label safe to show: provider and scope, or just the host for custom servers."""
+    if provider.owner_selects_tools:
+        return host_label(provider.endpoint(cleaned))
+    return " · ".join(
+        part for part in (f"{provider.label} MCP", "/".join(cleaned.values())) if part
+    )
+
+
+def select_tools(
+    connection: Connection,
+    provider: MCPProvider,
+    tools: dict[str, Any],
+    selected: list[str] | None = None,
+) -> None:
+    """Built-in providers use every allowed tool. Custom servers let the owner choose."""
+    try:
+        store_tools(
+            connection, tools, selected, owner_selects=provider.owner_selects_tools
+        )
+    except UnknownTools as error:
+        raise MCPError("Choose tools from the server's list.") from error
+
+
+def create_mcp_connection(
+    workspace: Workspace,
+    provider_key: str,
+    binding_key: str,
+    display_name: str,
+    token: str,
+    settings: dict[str, str] | None = None,
+    auth: str = "token",
+) -> Connection:
+    """Save a connection with a pasted token, or one that borrows sources."""
+    provider = mcp_provider(provider_key)
+    if auth not in provider.auth_methods or auth not in {"token", SOURCE_AUTH}:
+        raise MCPError(f"{provider.label} does not accept this kind of connection.")
+    if auth == "token" and not re.fullmatch(provider.token_pattern, token):
+        raise MCPError(provider.token_hint)
+    if auth == SOURCE_AUTH and token:
+        raise MCPError("This connection uses your GitHub connections, not a token.")
+    cleaned = provider.clean_settings(settings or {})
+    if binding_taken(workspace.pk, binding_key):
+        raise ConnectionConflict("This binding already has a connection.")
+    connection = Connection(
+        workspace=workspace,
+        provider=provider.key,
+        kind=Connection.Kind.MCP,
+        binding_key=binding_key,
+        display_name=display_name.strip() or provider.label,
+        endpoint_url=provider.endpoint(cleaned),
+        auth_strategy=AUTH_STRATEGIES[auth],
+        access_token=token if auth == "token" else "",
+        metadata={"target": connection_target(provider, cleaned), "settings": cleaned},
+    )
+    select_tools(connection, provider, discover_tools(connection))
+    connection.full_clean()
+    try:
+        with transaction.atomic():
+            connection.save()
+    except IntegrityError:
+        raise ConnectionConflict("This binding already has a connection.") from None
+    return connection
+
+
+def apply_credentials(
+    connection: Connection,
+    provider: MCPProvider,
+    token: str | None,
+    settings: dict[str, str] | None,
+    current: dict[str, str],
+) -> None:
+    """Take a new token, or refuse when the edit needs one or a new sign-in."""
+    if connection.auth_strategy == Connection.AuthStrategy.OAUTH:
+        if token or (settings is not None and settings != current):
+            raise MCPError("Sign in again to change the server or credentials.")
+        if connection.status != Connection.Status.CONNECTED:
+            raise MCPError("Sign in again to reconnect.")
+    elif borrows_source(connection):
+        if token:
+            raise MCPError("This connection uses your GitHub connections, not a token.")
+    elif token:
+        if not re.fullmatch(provider.token_pattern, token):
+            raise MCPError(provider.token_hint)
+        connection.access_token = token
+    elif connection.status == Connection.Status.REVOKED or not connection.access_token:
+        raise MCPError("Enter a new token to reconnect.")
+
+
+def update_mcp_connection(
+    connection: Connection,
+    display_name: str | None,
+    token: str | None,
+    settings: dict[str, str] | None,
+    tools: list[str] | None = None,
+) -> Connection:
+    """Replace the token, scope, or tool choice, then rediscover before saving.
+
+    A blank token keeps the current one, unless the connection was revoked.
+    Signed-in connections change their token or server only by signing in again.
+    """
+    if connection.kind != Connection.Kind.MCP:
+        raise ConnectionConflict("Only MCP connections can be edited here.")
+    provider = mcp_provider(connection.provider)
+    if tools is not None and not provider.owner_selects_tools:
+        raise MCPError(f"{provider.label} tools are fixed by SecondShift.")
+    current = connection.settings
+    apply_credentials(connection, provider, token, settings, current)
+    cleaned = provider.clean_settings(current if settings is None else settings)
+    if display_name is not None:
+        connection.display_name = display_name.strip() or provider.label
+    connection.endpoint_url = provider.endpoint(cleaned)
+    connection.status = Connection.Status.CONNECTED
+    connection.metadata = {
+        **connection.metadata,
+        "target": connection_target(provider, cleaned),
+        "settings": cleaned,
+    }
+    # Raises before saving, so a bad token or scope leaves the stored one alone.
+    offered = discover_tools(connection)
+    if tools is None and provider.owner_selects_tools:
+        tools = [name for name in connection.available_tools if name in offered]
+    select_tools(connection, provider, offered, tools)
+    connection.full_clean()
+    connection.save()
+    return connection
+
+
+def recheck_mcp_connection(connection: Connection) -> str:
+    """List the server's tools again and keep the chosen ones it still offers."""
+    provider = mcp_provider(connection.provider)
+    tools = discover_tools(connection)
+    kept = [name for name in connection.available_tools if name in tools]
+    select_tools(
+        connection, provider, tools, kept if provider.owner_selects_tools else None
+    )
+    connection.save(update_fields=["available_tools", "metadata", "updated_at"])
+    return f"Discovered {len(tools)} supported {provider.label} tools."

secondshift/connections/mcp/custom.py

@@ -0,0 +1,86 @@
+"""Any MCP server the owner names. SecondShift cannot scope what it reaches."""
+
+from typing import Any
+
+from secondshift.connections.access import AccessReason
+from secondshift.connections.mcp.base import (
+    MCPError,
+    MCPProvider,
+    MCPSetting,
+    MCPSettings,
+)
+from secondshift.connections.models import Connection
+from secondshift.connections.outbound import (
+    OutboundUrlError,
+    host_label,
+    validate_outbound_url,
+)
+from secondshift.connections.repository_ref import RepositoryRef
+
+URL = "url"
+# Connection.endpoint_url is a URLField with Django's default limit.
+CUSTOM_URL_MAX_LENGTH = 200
+OAUTH = "oauth"
+TOKEN = "token"
+
+
+def custom_server_url(value: str) -> str:
+    """HTTPS only, no credentials in the URL. DNS is checked when connecting."""
+    try:
+        return validate_outbound_url(value, "server URL", resolve=False)
+    except OutboundUrlError as error:
+        raise MCPError(str(error)) from None
+
+
+def custom_scope(settings: MCPSettings, repository: RepositoryRef) -> str | None:
+    del repository
+    url = settings.get(URL)
+    return host_label(url) if url else None
+
+
+def custom_arguments(
+    scope: str, tool: str, arguments: dict[str, Any]
+) -> dict[str, Any]:
+    # The owner chose the tools. Schema checks still run in the broker.
+    del scope, tool
+    return dict(arguments)
+
+
+def describe_custom_scope(scope: str) -> str:
+    return f"anything the credential can reach on {scope}"
+
+
+CUSTOM_MCP = MCPProvider(
+    key=Connection.Provider.MCP,
+    label="Custom server",
+    endpoint_url="",
+    tools=(),
+    scope=custom_scope,
+    scope_arguments=custom_arguments,
+    describe_scope=describe_custom_scope,
+    access_verb="use",
+    scope_label="server",
+    missing_scope_reason=AccessReason.MCP_SERVER_UNKNOWN,
+    missing_scope_message="This MCP connection has no server URL.",
+    settings=(
+        MCPSetting(
+            key=URL,
+            label="Server URL",
+            pattern=r"https?://\S+",
+            max_length=CUSTOM_URL_MAX_LENGTH,
+            help="The server's MCP endpoint, usually ending in /mcp.",
+            placeholder="https://mcp.example.com/mcp",
+            validate=custom_server_url,
+        ),
+    ),
+    endpoint_path=lambda settings: settings.get(URL, ""),
+    owner_selects_tools=True,
+    auth_methods=(OAUTH, TOKEN),
+    token_hint="Enter a bearer token without whitespace.",
+    description=(
+        "Connect any MCP server that supports sign-in or a bearer token. "
+        "You choose which tools jobs may use."
+    ),
+    token_label="Bearer token",
+    setup_help="Sent as Authorization: Bearer <token>.",
+)

secondshift/connections/mcp/github.py

@@ -0,0 +1,256 @@
+"""GitHub's hosted MCP server: read-only tools, one repository per job."""
+
+import re
+from typing import Any
+
+from secondshift.config.constants import (
+    GITHUB_BASE_URL,
+    GITHUB_FINE_GRAINED_TOKEN_PATTERN,
+    GITHUB_MCP_TOOLS,
+    GITHUB_MCP_URL,
+    GITHUB_REPOSITORY_PATTERN,
+    GITHUB_TOKEN_HINT,
+    GitHubMCPTool,
+)
+from secondshift.connections.access import AccessReason
+from secondshift.connections.dao import connected_github_sources
+from secondshift.connections.github import connection_source, usable_source
+from secondshift.connections.mcp.base import (
+    SOURCE_AUTH,
+    MCPArgumentError,
+    MCPError,
+    MCPProvider,
+    MCPSettings,
+)
+from secondshift.connections.models import Connection
+from secondshift.connections.repository_ref import RepositoryRef
+from secondshift.github import credentials
+from secondshift.github.errors import GitHubError
+from secondshift.workspaces.models import Workspace
+
+# Search text is written by the model. A short limit keeps it a search.
+GITHUB_SEARCH_QUERY_MAX_CHARS = 256
+# Artifacts and log archives are left out. They return download links.
+GITHUB_ACTIONS_METHODS = {
+    GitHubMCPTool.ACTIONS_LIST: frozenset(
+        {"list_workflows", "list_workflow_runs", "list_workflow_jobs"}
+    ),
+    GitHubMCPTool.ACTIONS_GET: frozenset(
+        {"get_workflow", "get_workflow_run", "get_workflow_job"}
+    ),
+}
+GITHUB_ACTIONS_TOOLS = frozenset(
+    {GitHubMCPTool.ACTIONS_LIST, GitHubMCPTool.ACTIONS_GET, GitHubMCPTool.GET_JOB_LOGS}
+)
+GITHUB_MISSING_SOURCE = (
+    "This repository was not added from GitHub, so it has no GitHub connection "
+    "to borrow. Use a GitHub connection with its own token."
+)
+# The end of a failed job's log usually holds the error.
+GITHUB_JOB_LOG_MAX_LINES = 300
+
+
+def scoped_search_query(repository: str, query: str) -> str:
+    """Pin a pull request search to the job's repository."""
+    if len(query) > GITHUB_SEARCH_QUERY_MAX_CHARS:
+        raise MCPArgumentError(
+            f"Keep the search under {GITHUB_SEARCH_QUERY_MAX_CHARS} characters."
+        )
+    # OR can widen a repo-qualified search. Disallow it rather than attempt
+    # to rewrite the provider's query language. GitHub only reads it in capitals.
+    if re.search(r"\bOR\b", query):
+        raise MCPArgumentError("Use separate searches instead of OR.")
+    query = re.sub(rf"(?i)(?<!\S)repo:{re.escape(repository)}(?=\s|$)", "", query)
+    if re.search(r"repo\s*:", query, re.IGNORECASE):
+        raise MCPArgumentError("The search must target the approved repository.")
+    return f"repo:{repository} {query.strip()}".strip()
+
+
+def job_log_lines(requested: Any) -> int:
+    """The requested log tail, capped. Anything else gets the cap."""
+    if not isinstance(requested, int) or isinstance(requested, bool) or requested < 1:
+        return GITHUB_JOB_LOG_MAX_LINES
+    return min(requested, GITHUB_JOB_LOG_MAX_LINES)
+
+
+def scoped_github_arguments(
+    repository: str, tool: str, arguments: dict[str, Any]
+) -> dict[str, Any]:
+    """Enforce the owner's repository scope independently of model instructions."""
+    if tool not in GITHUB_MCP_TOOLS:
+        raise MCPError("This GitHub tool is not supported.")
+    if not re.fullmatch(GITHUB_REPOSITORY_PATTERN, repository):
+        raise MCPError("The job has no valid GitHub repository scope.")
+    owner, repo = repository.split("/", 1)
+    scoped = dict(arguments)
+    for key, value in (("owner", owner), ("repo", repo)):
+        if key in scoped and scoped[key] != value:
+            raise MCPArgumentError("The tool must target the approved repository.")
+        scoped[key] = value
+    if tool == GitHubMCPTool.LIST_COMMITS and scoped.get("sha"):
+        raise MCPArgumentError("List commits from the default branch by omitting sha.")
+    if tool == GitHubMCPTool.SEARCH_PULL_REQUESTS:
+        scoped["query"] = scoped_search_query(repository, str(scoped.get("query", "")))
+    methods = GITHUB_ACTIONS_METHODS.get(tool)
+    if methods is not None and scoped.get("method") not in methods:
+        raise MCPArgumentError(
+            f"Use one of these methods: {', '.join(sorted(methods))}."
+        )
+    if tool == GitHubMCPTool.GET_JOB_LOGS:
+        # A download link would skip the broker's size limit and redaction.
+        scoped["return_content"] = True
+        scoped["tail_lines"] = job_log_lines(scoped.get("tail_lines"))
+    return scoped
+
+
+def narrowed_github_schema(tool: str, schema: dict[str, Any]) -> dict[str, Any]:
+    """Show the model only the Actions methods and log options it may use.
+
+    A call outside the scope rules stops the run, so the model must not be
+    offered methods those rules block.
+    """
+    properties = schema.get("properties")
+    if not isinstance(properties, dict):
+        return schema
+    narrowed = {**schema, "properties": dict(properties)}
+    methods = GITHUB_ACTIONS_METHODS.get(tool)
+    if methods is not None and isinstance(properties.get("method"), dict):
+        narrowed["properties"]["method"] = {
+            **properties["method"],
+            "enum": sorted(methods),
+        }
+    if tool == GitHubMCPTool.GET_JOB_LOGS:
+        # Always set by scope_arguments, so the model has no choice to make.
+        narrowed["properties"].pop("return_content", None)
+        if isinstance(narrowed.get("required"), list):
+            narrowed["required"] = [
+                name for name in narrowed["required"] if name != "return_content"
+            ]
+        if isinstance(properties.get("tail_lines"), dict):
+            # GitHub's own default is above the cap.
+            narrowed["properties"]["tail_lines"] = {
+                **{
+                    key: value
+                    for key, value in properties["tail_lines"].items()
+                    if key != "default"
+                },
+                "description": (
+                    "Lines to return from the end of the log. "
+                    f"At most {GITHUB_JOB_LOG_MAX_LINES}."
+                ),
+            }
+    return narrowed
+
+
+def github_tool_error(tool: str, text: str) -> str | None:
+    """Name the missing token permission when GitHub refuses a call."""
+    if not re.search(r"\b403\b|Resource not accessible", text):
+        return None
+    if tool in GITHUB_ACTIONS_TOOLS:
+        return (
+            "GitHub refused this call. It needs read access to Actions on this "
+            "repository. Give it to the token or the GitHub App, then retry."
+        )
+    return (
+        "GitHub refused this call. Check the repository permissions of the "
+        "token or the GitHub App."
+    )
+
+
+def github_scope(settings: MCPSettings, repository: RepositoryRef) -> str | None:
+    """A job reads only its own repository, whatever the token can reach."""
+    del settings
+    return repository.github_name
+
+
+# What the tools read. An App token asks only for those the installation has.
+GITHUB_TOOL_PERMISSIONS = ("contents", "pull_requests", "actions", "statuses")
+
+
+def github_source_reachable(repository: RepositoryRef) -> bool:
+    connection = repository.source
+    return (
+        repository.github_id is not None
+        and usable_source(connection)
+        and connection.workspace_id == repository.workspace_id
+    )
+
+
+def github_source_token(repository: RepositoryRef) -> str:
+    """A read token for this repository only, from the source it was added with."""
+    connection = repository.source
+    if repository.github_id is None or connection is None:
+        raise MCPError(GITHUB_MISSING_SOURCE)
+    if connection.workspace_id != repository.workspace_id:
+        raise MCPError("The repository's GitHub connection is disconnected.")
+    try:
+        return credentials.read_token_for(
+            connection_source(connection),
+            repository.github_id,
+            GITHUB_TOOL_PERMISSIONS,
+        )
+    except GitHubError as error:
+        # These messages never contain a token.
+        raise MCPError(str(error)) from error
+
+
+def github_discovery_token(workspace: Workspace) -> str:
+    """Any source connection of the workspace can list GitHub's tools."""
+    for connection in connected_github_sources(workspace.pk):
+        if not usable_source(connection):
+            continue
+        try:
+            return credentials.read_token_for(
+                connection_source(connection), None, GITHUB_TOOL_PERMISSIONS
+            )
+        except GitHubError:
+            continue
+    raise MCPError(
+        "Connect GitHub on the Repositories page first, with the GitHub App or a token."
+    )
+
+
+def describe_github_scope(scope: str) -> str:
+    return f"the {scope} repository"
+
+
+GITHUB_MCP = MCPProvider(
+    key=Connection.Provider.GITHUB,
+    label="GitHub",
+    endpoint_url=GITHUB_MCP_URL,
+    tools=GITHUB_MCP_TOOLS,
+    headers={
+        "X-MCP-Tools": ",".join(GITHUB_MCP_TOOLS),
+        "X-MCP-Readonly": "true",
+    },
+    token_pattern=GITHUB_FINE_GRAINED_TOKEN_PATTERN,
+    token_hint=GITHUB_TOKEN_HINT,
+    scope=github_scope,
+    describe_scope=describe_github_scope,
+    scope_label="repository",
+    missing_scope_reason=AccessReason.GITHUB_REPOSITORY_UNKNOWN,
+    missing_scope_message=(
+        "This job has no GitHub repository identity. For a local checkout, "
+        "configure a GitHub origin and resync it."
+    ),
+    description=(
+        "Read pull requests, commits, and Actions runs and logs. "
+        "Each job reads only its own repository."
+    ),
+    default_binding="github",
+    token_label="Fine-grained personal access token",
+    setup_url=f"{GITHUB_BASE_URL}/settings/personal-access-tokens/new",
+    setup_help=(
+        "Pick your jobs' repositories and grant read-only Pull requests, "
+        "Commit statuses, and Contents. Add read-only Actions for jobs that "
+        "read CI runs and logs."
+    ),
+    auth_methods=("token", SOURCE_AUTH),
+    source_token=github_source_token,
+    discovery_token=github_discovery_token,
+    source_reachable=github_source_reachable,
+    missing_source_message=GITHUB_MISSING_SOURCE,
+    scope_arguments=scoped_github_arguments,
+    narrow_schema=narrowed_github_schema,
+    tool_error=github_tool_error,
+)