zjcode 0.0.1__py3-none-any.whl

deepagents_code/mcp_oauth_ui.py

@@ -0,0 +1,199 @@
+"""UI-agnostic interaction interface for MCP OAuth login.
+
+The OAuth login flow needs to ask the user a few things during the
+handshake — open or display the authorize URL, accept a pasted callback
+URL when the provider has no loopback redirect, show RFC 8628 device-code
+instructions, and report success or failure. The CLI uses `print` and
+`input`; a TUI surface needs in-app widgets instead. `OAuthInteraction` is
+the small Protocol both implementations satisfy, and `CliOAuthInteraction`
+is the existing CLI behavior preserved as one implementation of that
+interface.
+
+Important: implementations must never embed access or refresh tokens
+in user-facing messages. The interaction surface only ever sees
+authorize URLs, callback URLs, device codes, and short status strings,
+so leaks come from misuse, not from this interface's shape.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class OAuthInteraction(Protocol):
+    """User-facing OAuth interaction surface shared by CLI and TUI."""
+
+    async def show_authorize_url(self, url: str, *, opened_in_browser: bool) -> None:
+        """Tell the user about the authorize URL.
+
+        Args:
+            url: Final authorize URL with provider-specific extras applied.
+            opened_in_browser: `True` when the caller already launched the
+                URL via `webbrowser.open`; `False` when the caller needs the
+                user to open it manually.
+        """
+        ...
+
+    async def request_callback_url(self) -> str:
+        """Wait for the user to paste back the full provider callback URL.
+
+        Returns:
+            The raw pasted URL (the caller parses `code`/`state`/`error`).
+
+        Raises:
+            RuntimeError: When the user interaction cannot complete (for
+                example, the input surface is unavailable or was dismissed).
+        """
+        ...
+
+    async def show_device_code(
+        self,
+        *,
+        verification_uri: str,
+        user_code: str,
+        expires_in: int,
+    ) -> None:
+        """Show RFC 8628 device-code instructions to the user.
+
+        Args:
+            verification_uri: Provider URL the user visits in a browser.
+            user_code: Short code the user enters on `verification_uri`.
+            expires_in: Lifetime of the device code in seconds.
+        """
+        ...
+
+    async def show_success(self, message: str) -> None:
+        """Report a successful login step.
+
+        Implementations must not embed token material in `message`; the
+        login code only passes structural facts ("logged in", token file
+        path) here.
+
+        Args:
+            message: Plain-text status line.
+        """
+        ...
+
+    async def show_notice(self, message: str) -> None:
+        """Report a non-fatal progress notice (e.g. fallback path taken).
+
+        Args:
+            message: Plain-text notice.
+        """
+        ...
+
+    async def show_error(self, message: str) -> None:
+        """Report a fatal (flow-ending) error.
+
+        "Fatal" rather than "terminal" because this is a TUI codebase
+        where "terminal" reads ambiguously.
+
+        Args:
+            message: Plain-text error description.
+        """
+        ...
+
+
+class CliOAuthInteraction:
+    """Default `OAuthInteraction` that drives the flow via stdin/stdout.
+
+    Preserves the previous `dcode mcp login` behavior — paste-back input,
+    plain-text prompts, success messages printed to stdout.
+    """
+
+    async def show_authorize_url(  # noqa: PLR6301
+        self,
+        url: str,
+        *,
+        opened_in_browser: bool,
+    ) -> None:
+        """Print the full authorize instruction block to stdout.
+
+        Uses browser-opened wording when `opened_in_browser` is `True`;
+        otherwise instructs the user to open the URL and paste back the callback.
+        """
+        if opened_in_browser:
+            print(  # noqa: T201
+                "\nOpened your browser to approve MCP access. "
+                "If it did not open, visit this URL:\n"
+                f"\n  {url}\n",
+            )
+        else:
+            print(  # noqa: T201
+                "\nOpen this URL in a browser, approve access, then paste the full "
+                "callback URL back here:\n"
+                f"\n  {url}\n",
+            )
+
+    async def request_callback_url(self) -> str:  # noqa: PLR6301
+        """Read a trimmed callback URL from stdin via a worker thread.
+
+        Returns:
+            The trimmed callback URL string.
+
+        Raises:
+            RuntimeError: If stdin is closed before the user replies.
+        """
+        import asyncio
+
+        try:
+            raw = await asyncio.to_thread(input, "Callback URL: ")
+        except EOFError as exc:
+            msg = (
+                "No callback URL received (stdin closed). "
+                "Re-run `dcode mcp login <server>` and paste the URL."
+            )
+            raise RuntimeError(msg) from exc
+        return raw.strip()
+
+    async def show_device_code(  # noqa: PLR6301
+        self,
+        *,
+        verification_uri: str,
+        user_code: str,
+        expires_in: int,
+    ) -> None:
+        """Print RFC 8628 device-code instructions to stdout."""
+        print(  # noqa: T201
+            f"\nVisit {verification_uri} and enter code: "
+            f"{user_code}\n(code expires in {expires_in}s)\n",
+        )
+
+    async def prompt_slack_team_id(self) -> str | None:  # noqa: PLR6301
+        """Ask for a Slack team ID via `input()` on a worker thread.
+
+        Returns:
+            The entered Slack team ID, or `None` if the prompt was blank or
+                stdin was closed.
+        """
+        import asyncio
+
+        try:
+            raw = await asyncio.to_thread(
+                input,
+                "Slack team ID to install the app into "
+                "(e.g. T01234567 — leave blank to pick on Slack's page): ",
+            )
+        except EOFError:
+            return None
+        return raw.strip() or None
+
+    async def show_success(self, message: str) -> None:  # noqa: PLR6301
+        """Print success message to stdout."""
+        print(message)  # noqa: T201
+
+    async def show_notice(self, message: str) -> None:  # noqa: PLR6301
+        """Print progress notice to stdout."""
+        print(message)  # noqa: T201
+
+    async def show_error(self, message: str) -> None:  # noqa: PLR6301
+        """Print error message to stderr."""
+        import sys
+
+        print(message, file=sys.stderr)  # noqa: T201
+
+
+__all__ = [
+    "CliOAuthInteraction",
+    "OAuthInteraction",
+]

deepagents_code/mcp_providers/__init__.py

@@ -0,0 +1,23 @@
+"""Provider-specific MCP OAuth dispatch.
+
+`resolve_provider(url)` returns the registered policy whose `matches`
+predicate fires for `url`, with `GenericProvider` as the fallback.
+"""
+
+from deepagents_code.mcp_providers._registry import resolve_provider
+from deepagents_code.mcp_providers.base import (
+    GenericProvider,
+    LoginResult,
+    OAuthProvider,
+)
+from deepagents_code.mcp_providers.github import GitHubProvider
+from deepagents_code.mcp_providers.slack import SlackProvider
+
+__all__ = [
+    "GenericProvider",
+    "GitHubProvider",
+    "LoginResult",
+    "OAuthProvider",
+    "SlackProvider",
+    "resolve_provider",
+]

deepagents_code/mcp_providers/_registry.py

@@ -0,0 +1,39 @@
+"""Ordered provider registry for MCP OAuth dispatch.
+
+`resolve_provider` walks `_REGISTRY` in order and returns the first
+provider whose `matches(url)` is `True`. `GenericProvider` sits last so
+spec-compliant servers always resolve to a usable policy.
+"""
+
+from __future__ import annotations
+
+from deepagents_code.mcp_providers.base import GenericProvider, OAuthProvider
+from deepagents_code.mcp_providers.github import GitHubProvider
+from deepagents_code.mcp_providers.slack import SlackProvider
+
+_REGISTRY: tuple[OAuthProvider, ...] = (
+    SlackProvider(),
+    GitHubProvider(),
+    GenericProvider(),
+)
+"""Ordered provider list; `GenericProvider` must stay last as the fallback."""
+
+
+def resolve_provider(server_url: str) -> OAuthProvider:
+    """Return the provider policy that owns `server_url`.
+
+    Args:
+        server_url: Remote MCP endpoint URL.
+
+    Returns:
+        The first matching `OAuthProvider`; falls back to `GenericProvider`.
+
+    Raises:
+        RuntimeError: If no provider matches (unreachable in practice since
+            `GenericProvider.matches` always returns `True`).
+    """
+    for provider in _REGISTRY:
+        if provider.matches(server_url):
+            return provider
+    msg = f"No MCP OAuth provider matched {server_url!r}"
+    raise RuntimeError(msg)

deepagents_code/mcp_providers/base.py

@@ -0,0 +1,133 @@
+"""Policy interface for provider-specific MCP OAuth quirks.
+
+Each concrete provider module (e.g. `slack`, `github`) subclasses
+`OAuthProvider` to encode its own URL match rule, client metadata, and
+any pre-handshake login steps (preseeding client info, running a
+device flow, prompting for workspace IDs). `mcp_auth` dispatches to
+the first matching provider via `resolve_provider`, so adding a new
+provider is one new module plus one registry entry — no edits to
+`build_oauth_provider` or `login`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from mcp.shared.auth import AnyUrl, OAuthClientMetadata
+
+if TYPE_CHECKING:
+    from deepagents_code.mcp_auth import FileTokenStorage
+    from deepagents_code.mcp_oauth_ui import OAuthInteraction
+
+
+@dataclass(frozen=True)
+class LoginResult:
+    """Outcome of a provider's pre-handshake `run_login` step."""
+
+    completed: bool = False
+    """`True` means tokens are persisted and `login` should skip the handshake."""
+
+    extra_auth_params: dict[str, str] = field(default_factory=dict)
+    """Extra query params to thread into the interactive auth URL."""
+
+
+class OAuthProvider(ABC):
+    """Base class for provider-specific OAuth dispatch.
+
+    Subclasses override `matches` plus whichever of `client_metadata`
+    and `run_login` they customize. The default implementations cover
+    the spec-compliant Authorization Code + PKCE + Dynamic Client
+    Registration path.
+    """
+
+    @abstractmethod
+    def matches(self, server_url: str) -> bool:
+        """Return `True` when this provider owns `server_url`."""
+
+    def supports_loopback_callback(self) -> bool:  # noqa: PLR6301  # subclass hook
+        """Return whether this provider can use a runtime loopback redirect URI.
+
+        When `False`, `client_metadata()` ignores the `redirect_uri` argument
+        and uses the provider's own pre-registered static URI instead.
+
+        Returns:
+            `True` when the provider accepts dynamically registered redirect URIs.
+        """
+        return True
+
+    def loopback_port(self) -> int | None:  # noqa: PLR6301  # subclass hook
+        """Return a fixed loopback port, or `None` for a random ephemeral port.
+
+        Override when the provider's app registration requires a specific
+        pre-registered port (e.g. Slack registers `http://localhost:3118/callback`).
+        Ignored when `supports_loopback_callback()` is `False`.
+
+        Returns:
+            A fixed TCP port, or `None` to pick a random ephemeral port.
+        """
+        return None
+
+    def client_metadata(  # noqa: PLR6301  # subclass hook
+        self,
+        *,
+        redirect_uri: str | None = None,
+    ) -> OAuthClientMetadata:
+        """Return the `OAuthClientMetadata` used to build the auth provider.
+
+        Args:
+            redirect_uri: Optional runtime redirect URI for CLI loopback auth.
+
+        Returns:
+            Metadata for the spec-compliant Authorization Code + PKCE +
+            Dynamic Client Registration flow.
+        """
+        return OAuthClientMetadata(
+            client_name="deepagents-code",
+            redirect_uris=[AnyUrl(redirect_uri or "http://localhost/callback")],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+        )
+
+    async def run_login(  # noqa: PLR6301  # subclass hook
+        self,
+        *,
+        server_name: str,
+        server_url: str,
+        storage: FileTokenStorage,
+        ui: OAuthInteraction,
+    ) -> LoginResult:
+        """Perform any provider-specific pre-handshake work.
+
+        Args:
+            server_name: MCP server name from `mcpServers`.
+            server_url: Remote MCP endpoint URL.
+            storage: File-backed token storage for this server identity.
+            ui: Interaction surface used for any provider-specific
+                prompts (e.g. device-code instructions, workspace IDs).
+
+        Returns:
+            `LoginResult.completed=True` if the provider finished the
+            login itself (e.g. device flow). Otherwise the caller drives
+            the standard Authorization Code handshake and passes any
+            returned `extra_auth_params` to the redirect URL.
+        """
+        del server_name, server_url, storage, ui
+        return LoginResult()
+
+
+class GenericProvider(OAuthProvider):
+    """Fallback provider for spec-compliant MCP servers with no quirks."""
+
+    def matches(self, server_url: str) -> bool:  # noqa: PLR6301  # subclass hook
+        """Match any URL — the registry places this provider last.
+
+        Args:
+            server_url: Remote MCP endpoint URL (unused).
+
+        Returns:
+            Always `True`.
+        """
+        del server_url
+        return True

deepagents_code/mcp_providers/github.py

@@ -0,0 +1,102 @@
+"""GitHub-hosted MCP OAuth provider.
+
+GitHub's remote MCP at `api.githubcopilot.com` authenticates via RFC
+8628 Device Authorization Grant — the app runs the device flow,
+persists the resulting token plus a stub client-info record, and skips
+the standard Authorization Code handshake entirely.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+
+from mcp.shared.auth import AnyUrl, OAuthClientInformationFull
+
+from deepagents_code.mcp_auth import _run_device_flow
+from deepagents_code.mcp_providers.base import LoginResult, OAuthProvider
+
+if TYPE_CHECKING:
+    from deepagents_code.mcp_auth import FileTokenStorage
+    from deepagents_code.mcp_oauth_ui import OAuthInteraction
+
+
+_GITHUB_MCP_CLIENT_ID = "Iv23libxz8qOApH0WQL3"
+"""Public OAuth client ID for the GitHub App backing GitHub's remote MCP."""
+
+_GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code"
+"""GitHub Device Authorization Grant endpoint that issues the user/device code pair."""
+
+_GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token"  # noqa: S105
+"""GitHub OAuth token endpoint polled while the user completes the device flow."""
+
+
+def _is_github_mcp_url(url: str) -> bool:
+    """Return `True` when `url` points at GitHub's remote MCP endpoint."""
+    return (urlparse(url).hostname or "") == "api.githubcopilot.com"
+
+
+async def _preseed_github_auth(
+    storage: FileTokenStorage, *, ui: OAuthInteraction
+) -> None:
+    """Run GitHub Device Flow and persist the token and stub client info.
+
+    Args:
+        storage: File-backed token storage for this server identity.
+        ui: Interaction surface that renders the device-code prompt.
+    """
+    token = await _run_device_flow(
+        device_code_url=_GITHUB_DEVICE_CODE_URL,
+        token_url=_GITHUB_TOKEN_URL,
+        client_id=_GITHUB_MCP_CLIENT_ID,
+        ui=ui,
+    )
+    await storage.set_tokens_and_client_info(
+        token,
+        OAuthClientInformationFull(
+            client_id=_GITHUB_MCP_CLIENT_ID,
+            redirect_uris=[AnyUrl("http://localhost/callback")],
+            grant_types=["urn:ietf:params:oauth:grant-type:device_code"],
+            response_types=["code"],
+            token_endpoint_auth_method="none",  # noqa: S106
+        ),
+    )
+
+
+class GitHubProvider(OAuthProvider):
+    """GitHub-hosted MCP: RFC 8628 Device Authorization Grant."""
+
+    def matches(self, server_url: str) -> bool:  # noqa: PLR6301  # subclass hook
+        """Match `api.githubcopilot.com`.
+
+        Args:
+            server_url: Remote MCP endpoint URL.
+
+        Returns:
+            `True` when `server_url`'s host is GitHub's MCP endpoint.
+        """
+        return _is_github_mcp_url(server_url)
+
+    async def run_login(  # noqa: PLR6301  # subclass hook
+        self,
+        *,
+        server_name: str,
+        server_url: str,
+        storage: FileTokenStorage,
+        ui: OAuthInteraction,
+    ) -> LoginResult:
+        """Run the device flow and short-circuit the Authorization Code handshake.
+
+        Args:
+            server_name: MCP server name (unused).
+            server_url: Remote MCP endpoint URL (unused).
+            storage: File-backed token storage for this server identity.
+            ui: Interaction surface that renders the device-code prompt.
+
+        Returns:
+            `LoginResult(completed=True)` — tokens are already persisted so
+            the caller must skip the handshake step.
+        """
+        del server_name, server_url
+        await _preseed_github_auth(storage, ui=ui)
+        return LoginResult(completed=True)

deepagents_code/mcp_providers/slack.py

@@ -0,0 +1,175 @@
+"""Slack-hosted MCP OAuth provider.
+
+Slack's hosted MCP endpoint uses the Authorization Code flow with a
+hardcoded public client ID and a fixed pre-registered loopback redirect
+URI (`http://localhost:3118/callback`). The local callback server listens
+on that port so the browser redirect completes automatically. An optional
+`team` query parameter selects the workspace to install the app into.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from urllib.parse import urlparse
+
+from mcp.shared.auth import (
+    AnyUrl,
+    OAuthClientInformationFull,
+    OAuthClientMetadata,
+)
+
+from deepagents_code.mcp_providers.base import LoginResult, OAuthProvider
+
+if TYPE_CHECKING:
+    from deepagents_code.mcp_auth import FileTokenStorage
+    from deepagents_code.mcp_oauth_ui import OAuthInteraction
+
+
+@runtime_checkable
+class _SupportsSlackTeamPrompt(Protocol):
+    """Optional interaction-surface capability: prompt for a Slack team ID.
+
+    `OAuthInteraction` deliberately omits this method — only the CLI
+    surface implements it. The TUI lets Slack's browser page handle
+    workspace selection. Marked `runtime_checkable` so `isinstance`
+    can replace `getattr`-style structural probes at the call site.
+    """
+
+    async def prompt_slack_team_id(self) -> str | None: ...
+
+
+# Public OAuth client ID — safe to check in. No secret is associated;
+# Slack treats this as a browser-style public client where the security
+# boundary is the redirect URI rather than client secrecy.
+_SLACK_MCP_CLIENT_ID = "4518649543379.10944517634130"
+"""Public OAuth client ID registered with Slack for the hosted MCP endpoint."""
+
+_SLACK_LOOPBACK_PORT = 3118
+"""Fixed TCP port the local callback server binds to for Slack OAuth.
+
+Slack validates the redirect URI against the app's registered allowlist, so
+the port must be pre-registered in the Slack app dashboard. Only one Slack
+login can proceed at a time per machine (port conflicts are surfaced as an
+OSError from the loopback server's `start()` call).
+"""
+
+_SLACK_REDIRECT_URI = f"http://localhost:{_SLACK_LOOPBACK_PORT}/callback"
+"""Pre-registered loopback redirect URI for the Slack MCP OAuth app."""
+
+
+def _is_slack_mcp_url(url: str) -> bool:
+    """Return `True` when `url` points at a Slack-hosted MCP endpoint."""
+    host = urlparse(url).hostname or ""
+    return host == "slack.com" or host.endswith(".slack.com")
+
+
+async def _prompt_slack_team(ui: OAuthInteraction) -> str | None:
+    """Return a Slack team ID when the interaction surface supports prompting.
+
+    `prompt_slack_team_id` is **not** a member of the `OAuthInteraction`
+    Protocol — only the CLI surface implements it. The TUI omits it so
+    Slack's browser page handles workspace selection instead. Detection
+    uses `isinstance` against the `runtime_checkable`
+    `_SupportsSlackTeamPrompt` capability protocol.
+
+    Args:
+        ui: Interaction surface to use.
+
+    Returns:
+        The entered Slack team ID, or `None` when the surface lacks the
+            optional prompt method or the user declined to specify one.
+    """
+    if not isinstance(ui, _SupportsSlackTeamPrompt):
+        return None
+    return await ui.prompt_slack_team_id()
+
+
+async def _preseed_slack_client_info(storage: FileTokenStorage) -> None:
+    """Write the hardcoded Slack `client_info` to `storage` if not current."""
+    existing = await storage.get_client_info()
+    redirect_uris = existing.redirect_uris if existing is not None else None
+    current_redirect = str(redirect_uris[0]) if redirect_uris else None
+    if (
+        existing is not None
+        and existing.client_id == _SLACK_MCP_CLIENT_ID
+        and current_redirect == _SLACK_REDIRECT_URI
+    ):
+        return
+    await storage.set_client_info(
+        OAuthClientInformationFull(
+            client_id=_SLACK_MCP_CLIENT_ID,
+            redirect_uris=[AnyUrl(_SLACK_REDIRECT_URI)],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            token_endpoint_auth_method="none",  # noqa: S106
+        )
+    )
+
+
+class SlackProvider(OAuthProvider):
+    """Slack-hosted MCP: loopback Authorization Code with a public client."""
+
+    def matches(self, server_url: str) -> bool:  # noqa: PLR6301  # subclass hook
+        """Match `slack.com` and any `*.slack.com` subdomain.
+
+        Args:
+            server_url: Remote MCP endpoint URL.
+
+        Returns:
+            `True` when `server_url`'s host is Slack.
+        """
+        return _is_slack_mcp_url(server_url)
+
+    def loopback_port(self) -> int:  # noqa: PLR6301  # subclass hook
+        """Return the fixed loopback port registered in the Slack OAuth app.
+
+        Returns:
+            `_SLACK_LOOPBACK_PORT` (3118).
+        """
+        return _SLACK_LOOPBACK_PORT
+
+    def client_metadata(  # noqa: PLR6301  # subclass hook
+        self, *, redirect_uri: str | None = None
+    ) -> OAuthClientMetadata:
+        """Return public-client metadata with Slack's pre-registered loopback URI.
+
+        Args:
+            redirect_uri: Ignored; Slack requires its pre-registered loopback URI.
+
+        Returns:
+            Metadata configured for Slack's public OAuth client (no token secret).
+        """
+        del redirect_uri
+        return OAuthClientMetadata(
+            client_name="deepagents-code",
+            redirect_uris=[AnyUrl(_SLACK_REDIRECT_URI)],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            token_endpoint_auth_method="none",  # noqa: S106
+        )
+
+    async def run_login(  # noqa: PLR6301  # subclass hook
+        self,
+        *,
+        server_name: str,
+        server_url: str,
+        storage: FileTokenStorage,
+        ui: OAuthInteraction,
+    ) -> LoginResult:
+        """Preseed client info and optionally thread the team ID into auth URL.
+
+        Args:
+            server_name: MCP server name (unused).
+            server_url: Remote MCP endpoint URL (unused).
+            storage: File-backed token storage for this server identity.
+            ui: Interaction surface used to prompt for the Slack team ID.
+
+        Returns:
+            A `LoginResult` carrying the optional `team=<id>` extra param
+            so the Slack authorize URL installs into the chosen workspace.
+        """
+        del server_name, server_url
+        await _preseed_slack_client_info(storage)
+        team_id = await _prompt_slack_team(ui)
+        extras = {"team": team_id} if team_id else {}
+        return LoginResult(extra_auth_params=extras)