mcp-client-kit 0.3.0__tar.gz → 0.4.0__tar.gz

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/CHANGELOG.md

@@ -1,6 +1,58 @@
 # Changelog
 
-## [Unreleased] — 0.4.0
+## [Unreleased] — 0.5.0
+
+## [0.4.0] — 2026-08-09
+
+### Added
+
+- **Headless OAuth login — `mcpgen login <server> --headless`** — logging in no longer requires
+  a browser on the machine running the command. Instead of opening a browser and binding a local
+  callback server, mcpgen prints the authorization URL to stderr, you authorize on any device,
+  and paste the resulting callback URL back on stdin. This is the only workable flow inside
+  containers, over SSH, and in CI, where `webbrowser.open()` silently does nothing and the
+  callback port is unreachable from wherever the browser actually runs. The redirect URI
+  registered in headless mode is port-less (`http://localhost/callback`) — nothing ever fetches
+  it, and keeping it free of an ephemeral port makes the registered value stable across runs for
+  servers that pin `redirect_uris`. Without the flag mcpgen auto-detects: macOS and Windows are
+  always treated as interactive, other platforms are headless when neither `DISPLAY` nor
+  `WAYLAND_DISPLAY` is set. `MCPGEN_HEADLESS=1`/`0` overrides the detection in either direction
+  for environments that guess wrong; an explicit `--headless`/`--no-headless` outranks both.
+
+- **`mcpgen login --callback-timeout SECONDS`** — the 300-second bound on the browser redirect
+  is a guess about how long a consent screen plus MFA takes, and guesses about human latency are
+  wrong for someone: a hardware-token or approve-on-phone flow can outlast it, while a scripted
+  login wants to fail fast. The flag sets that bound per invocation, `0` restores the original
+  unbounded wait as an escape hatch, and anything negative or non-numeric is rejected by argparse
+  with a usage message rather than surfacing as a traceback from inside asyncio. The same value
+  is available in code as `callback_timeout=` on `login()`, `ensure_login()`, and
+  `ensure_login_all()`. Headless logins ignore it — the pasted-URL prompt is never bounded.
+
+- **`ensure_login_all(servers)`** — pre-flight refresh-or-login across several servers in one
+  call, for pipelines that talk to more than one MCP server and want every token settled before
+  work starts. Deliberately sequential: concurrent logins would open several browser tabs at
+  once and, in headless mode, race each other for stdin. Servers with a valid cached token stay
+  silent, so the steady-state cost is zero.
+
+### Fixed
+
+- **An authorization denial in the browser flow now fails with the same clear error as the
+  headless flow.** The local callback server extracted only `code` and `state` and ignored
+  `error`/`error_description`, so declining consent resolved the callback to `(None, None)` and
+  surfaced later as an opaque downstream failure. Both callback paths now share one parser,
+  which raises `ValueError: OAuth authorization failed: <error> — <description>` at the point of
+  failure.
+
+- **`mcpgen login` no longer hangs forever when the browser never comes back.** The error-redirect
+  fix above only helps when the authorization server actually redirects; real ones often don't —
+  cancel the consent screen and the tab simply closes, so no request ever reaches the local
+  callback server and the wait never ends. The interactive flow now bounds that wait at 300s
+  (`_CALLBACK_TIMEOUT`) and raises `TimeoutError` explaining that the browser never returned,
+  with a pointer to `--headless` for pasting the redirect URL by hand. The timeout cancels the
+  pending callback future, so the background server task shuts down cleanly, and it unwinds
+  through the same restore path as any other login failure — a timed-out attempt leaves a
+  previously-working credential intact. Headless logins are deliberately unbounded: a human
+  pasting a URL may take arbitrarily long.
 
 ## [0.3.0] — 2026-07-14
 

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-client-kit
-Version: 0.3.0
+Version: 0.4.0
 Summary: mcp-client-kit — generate typed Python wrappers for any MCP server (codegen skill + CLI).
 Project-URL: Homepage, https://github.com/svd/mcp-client-kit
 Project-URL: Source, https://github.com/svd/mcp-client-kit
@@ -168,11 +168,14 @@ Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
 
 ```bash
 mcpgen login <server>                              # OAuth (most servers)
+mcpgen login <server> --headless                   # no browser: print URL, paste callback URL back
 mcpgen codegen <server> --bearer "$TOKEN" --out s.py  # PAT / bearer
 mcpgen codegen <server> --stdio "python server.py" --out s.py  # local stdio, no auth
 ```
 
-Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required.
+Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required; `ensure_login_all([...])` does the same for several servers, one at a time.
+
+In containers, over SSH, or in CI there is no browser to open. `--headless` prints the authorization URL, you authorize on any device, and paste the callback URL back on stdin. It is auto-detected when neither `DISPLAY` nor `WAYLAND_DISPLAY` is set (never on macOS or Windows); `MCPGEN_HEADLESS=1`/`0` overrides the detection, and `--headless`/`--no-headless` overrides both.
 
 ---
 

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/README.md

@@ -144,11 +144,14 @@ Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
 
 ```bash
 mcpgen login <server>                              # OAuth (most servers)
+mcpgen login <server> --headless                   # no browser: print URL, paste callback URL back
 mcpgen codegen <server> --bearer "$TOKEN" --out s.py  # PAT / bearer
 mcpgen codegen <server> --stdio "python server.py" --out s.py  # local stdio, no auth
 ```
 
-Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required.
+Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required; `ensure_login_all([...])` does the same for several servers, one at a time.
+
+In containers, over SSH, or in CI there is no browser to open. `--headless` prints the authorization URL, you authorize on any device, and paste the callback URL back on stdin. It is auto-detected when neither `DISPLAY` nor `WAYLAND_DISPLAY` is set (never on macOS or Windows); `MCPGEN_HEADLESS=1`/`0` overrides the detection, and `--headless`/`--no-headless` overrides both.
 
 ---
 

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/doc/USAGE.md

@@ -79,7 +79,7 @@ uv add mcp-client-kit            # or: pip install mcp-client-kit
 | `probe <server> <tool>` | Live call(s) → shape skeleton | `--args` (repeatable), `--emit-shape <path>` (writes `.parts/`) |
 | `call <server> <tool>` | One live call, raw payload to disk — bootstrap ids / inspect output | `--out <path>` (required) |
 | `merge <server>` | Consolidate `.parts/` → `<server>.shapes.json`; emit gitignored `verify.json` | `--out <path>` |
-| `login <server>` | Browser OAuth login | connection flags below |
+| `login <server>` | Browser OAuth login | `--headless` / `--no-headless`, `--callback-timeout <seconds>`, connection flags below |
 | `migrate-creds` | Copy stored OAuth tokens between `file`/`keyring` backends | `--from`, `--to`, `--servers`, `--purge`, `--set-default` |
 | `discover` | List servers from agent hosts | `--host <id>` (repeatable), `--json` |
 
@@ -138,6 +138,47 @@ mcpgen login myserver   # opens browser; token stored at ~/.mcpgen/credentials.j
 
 Re-run when you see `ReauthenticationRequired`.
 
+The browser flow waits up to 300 seconds for the redirect. If you cancel on the consent
+screen, many authorization servers just close the tab without redirecting back, so mcpgen
+never hears anything — the wait then ends with `TimeoutError` instead of hanging. Your
+existing credential is left untouched by a failed or timed-out attempt.
+
+Adjust the bound when the default doesn't fit — a hardware token or an approve-on-phone
+step can outlast it, and a scripted login may want to fail sooner:
+
+```bash
+mcpgen login myserver --callback-timeout 900   # 15 minutes
+mcpgen login myserver --callback-timeout 0     # wait forever (no bound)
+```
+
+Negative or non-numeric values are rejected outright. Headless logins ignore the flag —
+the pasted-URL prompt is never bounded. In code, the same value is `callback_timeout=` on
+`login()`, `ensure_login()`, and `ensure_login_all()`.
+
+**No browser available (container, SSH, CI):**
+
+```bash
+mcpgen login myserver --headless
+```
+
+mcpgen prints the authorization URL instead of opening it, and waits:
+
+```
+Open this URL in your browser:
+
+https://auth.example.com/authorize?response_type=code&client_id=…
+
+After authorizing, paste the full callback URL here (http://localhost.../callback?code=...):
+```
+
+Authorize on any device, then copy the URL from the browser's address bar — the page
+itself will fail to load, which is expected, nothing is listening on that address — and
+paste it at the prompt.
+
+Headless mode is auto-detected when neither `DISPLAY` nor `WAYLAND_DISPLAY` is set (macOS
+and Windows are always treated as interactive). Set `MCPGEN_HEADLESS=1` or `0` to override
+the detection; an explicit `--headless` / `--no-headless` overrides both.
+
 **PAT / Bearer token:**
 
 ```bash
@@ -323,6 +364,10 @@ How it works:
   absent), it falls back to a full browser login — the in-code equivalent of
   `mcpgen login <server>`. Credentials are persisted at
   `~/.mcpgen/credentials.json`.
+- **Several servers at once** — `await ensure_login_all(["a", "b"])` runs the same
+  refresh-or-login for each name in turn. Sequential on purpose: parallel logins would
+  open several browser tabs at once and race for stdin in headless mode. Both functions
+  accept `headless=True`/`False` to force the paste-the-URL or browser flow explicitly.
 - **Lower-level alternative** — skip `ensure_login` and catch
   `ReauthenticationRequired` from the first failing `.call()`, then call
   `login(SERVER, url=URL)` and retry. `ReauthenticationRequired` and `login` are

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/mcpgen/__init__.py

@@ -5,6 +5,7 @@ from mcpgen._bridge import (
     ReauthenticationRequired,
     delete_cred,
     ensure_login,
+    ensure_login_all,
     list_creds,
     login,
     migrate_creds,
@@ -17,6 +18,7 @@ __all__ = [
     "ReauthenticationRequired",
     "delete_cred",
     "ensure_login",
+    "ensure_login_all",
     "list_creds",
     "login",
     "migrate_creds",

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/mcpgen/_bridge.py

@@ -48,10 +48,11 @@ import json
 import os
 import shlex
 import stat
+import sys
 import time
 import warnings
 import webbrowser
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager, suppress
 from pathlib import Path
 from typing import Any
 from urllib.parse import parse_qs, urlparse
@@ -371,6 +372,14 @@ def _explain_registration_error(exc: OAuthRegistrationError) -> OAuthRegistratio
 # Treat a cached token as expired this many seconds before its real expiry.
 _MARGIN = 120
 
+# How long the interactive login waits for the browser to hit the local callback
+# server. Some authorization servers drop the user on cancel without an error
+# redirect, so the callback simply never arrives — bound the wait rather than
+# hang forever. Generous: it has to cover reading a consent screen and an MFA
+# prompt. Headless login is not bounded — a human pasting a URL may take any
+# amount of time.
+_CALLBACK_TIMEOUT = 300
+
 
 class ReauthenticationRequired(Exception):
     """Tokens absent or refresh failed. Run: mcpgen login <server>"""
@@ -1060,6 +1069,39 @@ def parse(content_items: list) -> Any:
 # ---------------------------------------------------------------------------
 
 
+def _parse_callback_query(query: str) -> tuple[str | None, str | None]:
+    """Extract (code, state) from an OAuth redirect query string.
+
+    Shared by both callback paths — the local HTTP server and the headless
+    paste-the-URL prompt — so an authorization denial surfaces identically in
+    either mode.
+
+    Raises ValueError when the authorization server returned an error.
+    """
+    params = parse_qs(query)
+    error = params.get("error", [None])[0]
+    if error:
+        description = params.get("error_description", ["(no description)"])[0]
+        raise ValueError(f"OAuth authorization failed: {error} — {description}")
+    return params.get("code", [None])[0], params.get("state", [None])[0]
+
+
+def _is_headless() -> bool:
+    """Return True when no interactive browser is reachable (container, no display).
+
+    MCPGEN_HEADLESS overrides the detection in both directions: set it to
+    1/true/yes/on to force the paste-the-URL flow, or to anything else (e.g. 0)
+    to force the browser flow.
+    """
+    override = os.environ.get("MCPGEN_HEADLESS")
+    if override is not None:
+        return override.strip().lower() in ("1", "true", "yes", "on")
+    # macOS/Windows: the user's own desktop — a browser is always reachable.
+    if sys.platform in ("darwin", "win32"):
+        return False
+    return not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
 async def _local_callback_server(port: int = 0) -> tuple[int, asyncio.Future]:
     """Start a local HTTP server to receive the OAuth redirect. Returns (port, future)."""
     loop = asyncio.get_event_loop()
@@ -1068,14 +1110,20 @@ async def _local_callback_server(port: int = 0) -> tuple[int, asyncio.Future]:
     async def _handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
         code: str | None = None
         state: str | None = None
+        failure: ValueError | None = None
         try:
             data = await reader.read(4096)
             first_line = data.decode(errors="replace").split("\n")[0]
             path = first_line.split(" ")[1] if " " in first_line else ""
-            params = parse_qs(urlparse(path).query)
-            code = params.get("code", [None])[0]
-            state = params.get("state", [None])[0]
-            body = b"<html><body><h1>Login complete. You can close this tab.</h1></body></html>"
+            try:
+                code, state = _parse_callback_query(urlparse(path).query)
+            except ValueError as exc:
+                failure = exc
+            body = (
+                b"<html><body><h1>Login failed. You can close this tab.</h1></body></html>"
+                if failure is not None
+                else b"<html><body><h1>Login complete. You can close this tab.</h1></body></html>"
+            )
             writer.write(
                 b"HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n"
                 + f"Content-Length: {len(body)}\r\n\r\n".encode()
@@ -1085,7 +1133,10 @@ async def _local_callback_server(port: int = 0) -> tuple[int, asyncio.Future]:
         finally:
             writer.close()
             if not future.done():
-                future.set_result((code, state))
+                if failure is not None:
+                    future.set_exception(failure)
+                else:
+                    future.set_result((code, state))
 
     try:
         server = await asyncio.start_server(_handle, "localhost", port)
@@ -1099,7 +1150,12 @@ async def _local_callback_server(port: int = 0) -> tuple[int, asyncio.Future]:
 
     async def _serve_until_done() -> None:
         async with server:
-            await future
+            # The future may carry an OAuth error (see _handle). Swallow it here —
+            # this task exists only to keep the socket open until the callback
+            # lands; the exception is delivered to callback_handler, which awaits
+            # the same future.
+            with suppress(BaseException):
+                await future
 
     asyncio.create_task(_serve_until_done())
     return actual_port, future
@@ -1113,11 +1169,19 @@ async def login(
     client_name: str | None = None,
     config_path: str | Path | None = None,
     cred_backend: str | None = None,
+    headless: bool | None = None,
+    callback_timeout: float | None = None,
 ) -> None:
     """Full browser-based OAuth login for server_name. Caches tokens + token_endpoint.
 
     url/client_name: inline overrides (no config entry needed).
     config_path: read the server registry from this file instead of the default search.
+    headless: True prints the authorization URL and reads the pasted callback URL
+        from stdin instead of opening a browser; False forces the browser flow;
+        None (default) auto-detects via _is_headless().
+    callback_timeout: seconds to wait for the browser redirect; None (default) uses
+        _CALLBACK_TIMEOUT, and any value <= 0 waits indefinitely. Ignored in
+        headless mode, where the stdin read is never bounded.
     """
     _servers = servers(config_path=config_path)
     server_url = url or _servers.get(server_name)
@@ -1133,17 +1197,63 @@ async def login(
     stashed = data.pop(server_name, None)
     storage._save(data)
 
-    try:
-        port, callback_future = await _local_callback_server()
-        callback_uri = f"http://localhost:{port}/callback"
+    if headless is None:
+        headless = _is_headless()
+    timeout = _CALLBACK_TIMEOUT if callback_timeout is None else callback_timeout
 
-        async def redirect_handler(url: str) -> None:
-            print(f"\nOpening browser: {url}\n")
-            webbrowser.open(url)
+    try:
+        callback_future: asyncio.Future | None = None
+
+        if headless:
+            # No local server: the redirect URI is never actually fetched, the
+            # user pastes it back. Port-less keeps the registered URI stable
+            # across runs, which matters for servers that pin redirect_uris.
+            callback_uri = "http://localhost/callback"
+
+            async def redirect_handler(url: str) -> None:
+                print(f"\nOpen this URL in your browser:\n\n{url}\n", file=sys.stderr, flush=True)
+
+            async def callback_handler() -> tuple[str, str | None]:
+                print(
+                    "After authorizing, paste the full callback URL here (http://localhost.../callback?code=...):",
+                    file=sys.stderr,
+                    flush=True,
+                )
+                # run_in_executor: a bare sys.stdin.readline() would block the loop.
+                loop = asyncio.get_running_loop()
+                line = (await loop.run_in_executor(None, sys.stdin.readline)).strip()
+                if not line:
+                    raise ValueError("No URL pasted — login aborted.")
+                code, state = _parse_callback_query(urlparse(line).query)
+                if code is None:
+                    raise ValueError(f"Pasted URL has no ?code= parameter: {line[:120]}")
+                return code, state
 
-        async def callback_handler() -> tuple[str, str | None]:
-            print("Waiting for OAuth callback… (complete login in your browser)")
-            return await callback_future
+        else:
+            port, callback_future = await _local_callback_server()
+            callback_uri = f"http://localhost:{port}/callback"
+
+            async def redirect_handler(url: str) -> None:
+                print(f"\nOpening browser: {url}\n")
+                webbrowser.open(url)
+
+            async def callback_handler() -> tuple[str, str | None]:
+                print("Waiting for OAuth callback… (complete login in your browser)")
+                assert callback_future is not None
+                if timeout <= 0:  # opt-out: wait indefinitely
+                    return await callback_future
+                try:
+                    # wait_for cancels the future on timeout; _serve_until_done
+                    # awaits the same future under suppress(), so the background
+                    # task exits cleanly instead of dangling.
+                    return await asyncio.wait_for(callback_future, timeout)
+                except TimeoutError:
+                    raise TimeoutError(
+                        f"No OAuth callback received within {timeout}s. The browser never "
+                        "returned to mcpgen — some authorization servers just close the tab when you "
+                        "cancel, without redirecting back. Retry, or use --headless to paste the "
+                        "redirect URL manually."
+                    ) from None
 
         provider = OAuthClientProvider(
             server_url=server_url,
@@ -1175,7 +1285,7 @@ async def login(
             except OAuthRegistrationError as e:
                 raise _explain_registration_error(e) from e
         finally:
-            if not callback_future.done():
+            if callback_future is not None and not callback_future.done():
                 callback_future.set_result((None, None))
             await asyncio.sleep(0)
 
@@ -1199,6 +1309,8 @@ async def ensure_login(
     client_name: str | None = None,
     config_path: str | Path | None = None,
     cred_backend: str | None = None,
+    headless: bool | None = None,
+    callback_timeout: float | None = None,
 ) -> None:
     """Ensure a usable token exists for server_name, refreshing or logging in.
 
@@ -1224,6 +1336,8 @@ async def ensure_login(
             client_name=client_name,
             config_path=config_path,
             cred_backend=cred_backend,
+            headless=headless,
+            callback_timeout=callback_timeout,
         )
         return
     if await storage.get_tokens() is None:  # first-time: no token cached at all
@@ -1234,4 +1348,32 @@ async def ensure_login(
             client_name=client_name,
             config_path=config_path,
             cred_backend=cred_backend,
+            headless=headless,
+            callback_timeout=callback_timeout,
+        )
+
+
+async def ensure_login_all(
+    server_names: list[str],
+    creds_path: Path = DEFAULT_CREDS_PATH,
+    *,
+    config_path: str | Path | None = None,
+    cred_backend: str | None = None,
+    headless: bool | None = None,
+    callback_timeout: float | None = None,
+) -> None:
+    """Run ensure_login() for each server, one at a time.
+
+    Sequential on purpose: a parallel version would open several browser tabs at
+    once and race for stdin in headless mode. Servers with a valid cached token
+    are silent, so the common case costs nothing.
+    """
+    for name in server_names:
+        await ensure_login(
+            name,
+            creds_path,
+            config_path=config_path,
+            cred_backend=cred_backend,
+            headless=headless,
+            callback_timeout=callback_timeout,
         )

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/mcpgen/cli.py

@@ -624,6 +624,8 @@ def _cmd_login(ns: argparse.Namespace) -> int:
             client_name=ns.client_name,
             config_path=ns.config,
             cred_backend=ns.cred_backend,
+            headless=ns.headless,
+            callback_timeout=ns.callback_timeout,
         )
     )
     return 0
@@ -714,6 +716,30 @@ def _cmd_delete_creds(ns: argparse.Namespace) -> int:
     return 0
 
 
+def _add_headless_flag(p: argparse.ArgumentParser) -> None:
+    """Add --headless / --no-headless to a subparser (absent → None → auto-detect)."""
+    p.add_argument(
+        "--headless",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="print the auth URL and read the pasted callback URL from stdin "
+        "instead of opening a browser. --no-headless forces the browser flow. "
+        "Default: auto-detect (headless without DISPLAY/WAYLAND_DISPLAY; "
+        "override with MCPGEN_HEADLESS).",
+    )
+
+
+def _callback_timeout(value: str) -> float:
+    """argparse type for --callback-timeout: a non-negative number of seconds."""
+    try:
+        seconds = float(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"expected a number of seconds, got {value!r}") from None
+    if seconds < 0 or seconds != seconds:  # NaN never equals itself
+        raise argparse.ArgumentTypeError(f"must be >= 0 (0 waits forever), got {value!r}")
+    return seconds
+
+
 def _add_conn_args(p: argparse.ArgumentParser) -> None:
     """Inline server-connection args shared by all commands (override config)."""
     p.add_argument("--url", help="server URL inline; enables OAuth without a config entry")
@@ -834,6 +860,16 @@ def main(argv: list[str] | None = None) -> int:
     lg = sub.add_parser("login", help="browser OAuth login for a named server")
     lg.add_argument("server", help="server name (e.g. acme)")
     _add_conn_args(lg)
+    _add_headless_flag(lg)
+    lg.add_argument(
+        "--callback-timeout",
+        dest="callback_timeout",
+        type=_callback_timeout,
+        metavar="SECONDS",
+        help="how long to wait for the browser redirect before giving up "
+        f"(default: {_bridge._CALLBACK_TIMEOUT}). 0 waits forever. "
+        "Ignored in headless mode, where the pasted-URL prompt is never bounded.",
+    )
     lg.set_defaults(func=_cmd_login)
 
     mc = sub.add_parser(

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-client-kit"
-version = "0.3.0"
+version = "0.4.0"
 description = "mcp-client-kit — generate typed Python wrappers for any MCP server (codegen skill + CLI)."
 readme = "README.md"
 license = { text = "MIT" }

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/tests/test_bridge.py

@@ -11,9 +11,11 @@ no pytest-asyncio dependency needed).
 from __future__ import annotations
 
 import asyncio
+import io
 import json
 import os
 import stat
+import time
 import warnings
 from contextlib import asynccontextmanager
 from unittest.mock import AsyncMock, MagicMock, patch
@@ -1311,3 +1313,496 @@ def test_mcp_bridge_caller_resource_link_missing_uri_stays_none():
     result = _run_call_with_content(_FakeResourceLinkItem(uri=None, name="x.txt"))
     assert result["uri"] is None
     json.dumps(result)  # must not raise TypeError
+
+
+# ---------------------------------------------------------------------------
+# Headless login — callback parsing, detection, login()/ensure_login_all(), CLI
+# ---------------------------------------------------------------------------
+
+
+def test_parse_callback_query_returns_code_and_state():
+    assert _bridge._parse_callback_query("code=abc&state=xyz") == ("abc", "xyz")
+
+
+def test_parse_callback_query_raises_on_error_with_description():
+    with pytest.raises(ValueError) as exc:
+        _bridge._parse_callback_query("error=access_denied&error_description=User+said+no")
+    assert "access_denied" in str(exc.value)
+    assert "User said no" in str(exc.value)
+
+
+def test_parse_callback_query_error_without_description():
+    with pytest.raises(ValueError, match=r"\(no description\)"):
+        _bridge._parse_callback_query("error=server_error")
+
+
+def test_parse_callback_query_missing_code_returns_nones():
+    """A bare redirect (no code, no error) is not an error — the caller decides."""
+    assert _bridge._parse_callback_query("") == (None, None)
+
+
+def test_is_headless_env_override_forces_headless(monkeypatch):
+    monkeypatch.setenv("MCPGEN_HEADLESS", "1")
+    with patch("sys.platform", "darwin"):
+        assert _bridge._is_headless() is True
+
+
+def test_is_headless_env_override_forces_interactive(monkeypatch):
+    monkeypatch.setenv("MCPGEN_HEADLESS", "0")
+    monkeypatch.delenv("DISPLAY", raising=False)
+    monkeypatch.delenv("WAYLAND_DISPLAY", raising=False)
+    with patch("sys.platform", "linux"):
+        assert _bridge._is_headless() is False
+
+
+def test_is_headless_false_on_desktop_platforms(monkeypatch):
+    monkeypatch.delenv("MCPGEN_HEADLESS", raising=False)
+    monkeypatch.delenv("DISPLAY", raising=False)
+    monkeypatch.delenv("WAYLAND_DISPLAY", raising=False)
+    for platform in ("darwin", "win32"):
+        with patch("sys.platform", platform):
+            assert _bridge._is_headless() is False
+
+
+def test_is_headless_true_on_linux_without_display(monkeypatch):
+    monkeypatch.delenv("MCPGEN_HEADLESS", raising=False)
+    monkeypatch.delenv("DISPLAY", raising=False)
+    monkeypatch.delenv("WAYLAND_DISPLAY", raising=False)
+    with patch("sys.platform", "linux"):
+        assert _bridge._is_headless() is True
+
+
+def test_is_headless_false_on_linux_with_x11_display(monkeypatch):
+    monkeypatch.delenv("MCPGEN_HEADLESS", raising=False)
+    monkeypatch.setenv("DISPLAY", ":0")
+    monkeypatch.delenv("WAYLAND_DISPLAY", raising=False)
+    with patch("sys.platform", "linux"):
+        assert _bridge._is_headless() is False
+
+
+def test_is_headless_false_on_linux_with_wayland_display(monkeypatch):
+    monkeypatch.delenv("MCPGEN_HEADLESS", raising=False)
+    monkeypatch.delenv("DISPLAY", raising=False)
+    monkeypatch.setenv("WAYLAND_DISPLAY", "wayland-0")
+    with patch("sys.platform", "linux"):
+        assert _bridge._is_headless() is False
+
+
+def test_login_headless_skips_callback_server(tmp_path):
+    """headless=True must not bind a socket, and must register the port-less URI.
+
+    The redirect URI is never fetched in this mode — the user pastes it back —
+    so it stays port-less, which keeps the registered value stable across runs.
+    """
+    creds = tmp_path / "credentials.json"
+    provider_cls = MagicMock()
+    server = MagicMock()
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._local_callback_server", server),
+            patch("mcpgen._bridge._open_http", _fake_http_fail),
+            patch("mcpgen._bridge.OAuthClientProvider", provider_cls),
+        ):
+            with pytest.raises(RuntimeError, match="network error"):
+                await _bridge.login("acme", creds_path=creds, url="https://acme.example.com/mcp", headless=True)
+
+    asyncio.run(run())
+    server.assert_not_called()
+    metadata = provider_cls.call_args.kwargs["client_metadata"]
+    assert [str(u) for u in metadata.redirect_uris] == ["http://localhost/callback"]
+    assert metadata.token_endpoint_auth_method == "none"
+
+
+def _capture_provider_and_invoke_callback():
+    """Provider factory + _open_http fake that drives the captured callback_handler.
+
+    _fake_http_fail short-circuits before the handler ever runs; this pair lets a
+    test exercise the headless stdin path end to end inside login().
+    """
+    captured: dict = {}
+
+    def provider(**kwargs):
+        captured.update(kwargs)
+        return MagicMock()
+
+    @asynccontextmanager
+    async def fake_http(*args, **kwargs):
+        await captured["callback_handler"]()
+        yield  # unreachable
+
+    return provider, fake_http
+
+
+def test_login_headless_empty_stdin_aborts_and_restores_credential(tmp_path):
+    """An empty paste aborts the login and leaves the prior credential intact."""
+    creds = tmp_path / "credentials.json"
+    original_entry = {"tokens": {"access_token": "orig_tok", "token_type": "bearer"}}
+    creds.write_text(json.dumps({"acme": original_entry}))
+    os.chmod(creds, 0o600)
+
+    provider, fake_http = _capture_provider_and_invoke_callback()
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+            patch("sys.stdin", io.StringIO("")),
+        ):
+            with pytest.raises(ValueError, match="No URL pasted"):
+                await _bridge.login("acme", creds_path=creds, url="https://acme.example.com/mcp", headless=True)
+
+    asyncio.run(run())
+    assert json.loads(creds.read_text())["acme"] == original_entry
+
+
+def test_login_headless_pasted_url_error_surfaces(tmp_path):
+    """A denial pasted back reaches the caller as the shared ValueError."""
+    creds = tmp_path / "credentials.json"
+    provider, fake_http = _capture_provider_and_invoke_callback()
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+            patch("sys.stdin", io.StringIO("http://localhost/callback?error=access_denied\n")),
+        ):
+            with pytest.raises(ValueError, match="access_denied"):
+                await _bridge.login("acme", creds_path=creds, url="https://acme.example.com/mcp", headless=True)
+
+    asyncio.run(run())
+
+
+def test_login_explicit_headless_false_beats_env(monkeypatch, tmp_path):
+    """headless=False wins over MCPGEN_HEADLESS=1 — the argument is the top priority."""
+    monkeypatch.setenv("MCPGEN_HEADLESS", "1")
+    creds = tmp_path / "credentials.json"
+    provider_cls = MagicMock()
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._local_callback_server", _fake_callback_server_factory()),
+            patch("mcpgen._bridge._open_http", _fake_http_fail),
+            patch("mcpgen._bridge.OAuthClientProvider", provider_cls),
+        ):
+            with pytest.raises(RuntimeError, match="network error"):
+                await _bridge.login("acme", creds_path=creds, url="https://acme.example.com/mcp", headless=False)
+
+    asyncio.run(run())
+    metadata = provider_cls.call_args.kwargs["client_metadata"]
+    assert [str(u) for u in metadata.redirect_uris] == ["http://localhost:9999/callback"]
+
+
+def test_ensure_login_all_runs_servers_in_order_with_kwargs(tmp_path):
+    """Sequential by design — parallel logins would race for the browser and stdin."""
+    creds = tmp_path / "credentials.json"
+    calls = []
+
+    async def fake_ensure_login(name, creds_path=None, **kwargs):
+        calls.append((name, creds_path, kwargs))
+
+    async def run():
+        with patch("mcpgen._bridge.ensure_login", fake_ensure_login):
+            await _bridge.ensure_login_all(
+                ["acme", "beta"],
+                creds,
+                config_path="/tmp/servers.json",
+                cred_backend="keyring",
+                headless=True,
+            )
+
+    asyncio.run(run())
+    assert [c[0] for c in calls] == ["acme", "beta"]
+    for _, creds_path, kwargs in calls:
+        assert creds_path == creds
+        assert kwargs == {
+            "config_path": "/tmp/servers.json",
+            "cred_backend": "keyring",
+            "headless": True,
+            "callback_timeout": None,
+        }
+
+
+def test_ensure_login_threads_headless_into_login(tmp_path):
+    """ensure_login() with no cached token must pass headless through to login()."""
+    creds = tmp_path / "credentials.json"
+    login_mock = AsyncMock()
+
+    async def run():
+        with patch("mcpgen._bridge.login", login_mock):
+            await _bridge.ensure_login("acme", creds, url="https://acme.example.com/mcp", headless=True)
+
+    asyncio.run(run())
+    assert login_mock.await_args.kwargs["headless"] is True
+
+
+@pytest.mark.parametrize(
+    ("argv_flag", "expected"),
+    [(["--headless"], True), (["--no-headless"], False), ([], None)],
+)
+def test_cli_login_headless_flag(argv_flag, expected):
+    """--headless / --no-headless / absent → True / False / None at _bridge.login."""
+    from mcpgen.cli import main
+
+    login_mock = AsyncMock()
+    with patch("mcpgen._bridge.login", login_mock):
+        assert main(["login", "acme", *argv_flag]) == 0
+    assert login_mock.await_args.kwargs["headless"] is expected
+
+
+def test_login_headless_pasted_url_without_code_rejected(tmp_path):
+    """A URL pasted without ?code= (e.g. the bare redirect) fails loudly."""
+    creds = tmp_path / "credentials.json"
+    provider, fake_http = _capture_provider_and_invoke_callback()
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+            patch("sys.stdin", io.StringIO("http://localhost/callback\n")),
+        ):
+            with pytest.raises(ValueError, match="no \\?code="):
+                await _bridge.login("acme", creds_path=creds, url="https://acme.example.com/mcp", headless=True)
+
+    asyncio.run(run())
+
+
+def test_login_interactive_times_out_when_callback_never_arrives(tmp_path):
+    """A browser that never returns must fail, not hang.
+
+    Some authorization servers close the tab on cancel without an error
+    redirect, so no callback request ever reaches the local server and the
+    future stays pending forever.
+    """
+    creds = tmp_path / "credentials.json"
+    original_entry = {"tokens": {"access_token": "orig_tok", "token_type": "bearer"}}
+    creds.write_text(json.dumps({"acme": original_entry}))
+    os.chmod(creds, 0o600)
+
+    async def never_resolving_callback_server():
+        return 9999, asyncio.get_running_loop().create_future()
+
+    provider, fake_http = _capture_provider_and_invoke_callback()
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._local_callback_server", never_resolving_callback_server),
+            patch("mcpgen._bridge._CALLBACK_TIMEOUT", 0.01),
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+        ):
+            with pytest.raises(TimeoutError) as exc:
+                await _bridge.login("acme", creds_path=creds, url="https://acme.example.com/mcp", headless=False)
+        assert "--headless" in str(exc.value)
+
+    asyncio.run(run())
+    assert json.loads(creds.read_text())["acme"] == original_entry, (
+        "a timed-out login must restore the prior credential"
+    )
+
+
+def test_login_headless_stdin_read_is_not_timed_out(tmp_path):
+    """The stdin paste must not inherit the browser timeout — humans are slow."""
+    creds = tmp_path / "credentials.json"
+    captured: dict = {}
+    result: dict = {}
+
+    def provider(**kwargs):
+        captured.update(kwargs)
+        return MagicMock()
+
+    @asynccontextmanager
+    async def fake_http(*args, **kwargs):
+        result["callback"] = await captured["callback_handler"]()
+        raise RuntimeError("callback returned")
+        yield  # unreachable
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._CALLBACK_TIMEOUT", 0.01),
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+            patch("sys.stdin", _SlowStdin("http://localhost/callback?code=abc&state=xyz\n")),
+        ):
+            with pytest.raises(RuntimeError, match="callback returned"):
+                await _bridge.login("acme", creds_path=creds, url="https://acme.example.com/mcp", headless=True)
+
+    asyncio.run(run())
+    # A TimeoutError instead would mean the stdin read inherited the browser bound.
+    assert result["callback"] == ("abc", "xyz")
+
+
+class _SlowStdin:
+    """stdin whose readline() takes longer than the patched callback timeout."""
+
+    def __init__(self, line: str):
+        self._line = line
+
+    def readline(self) -> str:
+        time.sleep(0.05)
+        return self._line
+
+
+def _never_resolving_callback_server():
+    async def fake_callback_server():
+        return 9999, asyncio.get_running_loop().create_future()
+
+    return fake_callback_server
+
+
+def test_login_callback_timeout_overrides_the_constant(tmp_path):
+    """An explicit callback_timeout wins over _CALLBACK_TIMEOUT and reaches wait_for."""
+    creds = tmp_path / "credentials.json"
+    provider, fake_http = _capture_provider_and_invoke_callback()
+    seen: dict = {}
+    real_wait_for = asyncio.wait_for
+
+    async def spy_wait_for(awaitable, timeout):
+        seen["timeout"] = timeout
+        return await real_wait_for(awaitable, timeout)
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._local_callback_server", _never_resolving_callback_server()),
+            patch("mcpgen._bridge._CALLBACK_TIMEOUT", 999),
+            patch("mcpgen._bridge.asyncio.wait_for", spy_wait_for),
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+        ):
+            with pytest.raises(TimeoutError, match="0.01s"):
+                await _bridge.login(
+                    "acme",
+                    creds_path=creds,
+                    url="https://acme.example.com/mcp",
+                    headless=False,
+                    callback_timeout=0.01,
+                )
+
+    asyncio.run(run())
+    assert seen["timeout"] == 0.01
+
+
+def test_login_callback_timeout_zero_waits_forever(tmp_path):
+    """callback_timeout=0 restores the unbounded wait — no wait_for, no timeout."""
+    creds = tmp_path / "credentials.json"
+    captured: dict = {}
+
+    def provider(**kwargs):
+        captured.update(kwargs)
+        return MagicMock()
+
+    @asynccontextmanager
+    async def fake_http(*args, **kwargs):
+        # The handler must still be pending well past the patched 0.01s bound.
+        handler = asyncio.ensure_future(captured["callback_handler"]())
+        await asyncio.sleep(0.05)
+        assert not handler.done(), "callback_timeout=0 must not time out"
+        handler.cancel()
+        raise RuntimeError("stopped waiting")
+        yield  # unreachable
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._local_callback_server", _never_resolving_callback_server()),
+            patch("mcpgen._bridge._CALLBACK_TIMEOUT", 0.01),
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+        ):
+            with pytest.raises(RuntimeError, match="stopped waiting"):
+                await _bridge.login(
+                    "acme",
+                    creds_path=creds,
+                    url="https://acme.example.com/mcp",
+                    headless=False,
+                    callback_timeout=0,
+                )
+
+    asyncio.run(run())
+
+
+def test_login_headless_ignores_callback_timeout(tmp_path):
+    """The flag must not bound the stdin read — a human paste may take any time."""
+    creds = tmp_path / "credentials.json"
+    captured: dict = {}
+    result: dict = {}
+
+    def provider(**kwargs):
+        captured.update(kwargs)
+        return MagicMock()
+
+    @asynccontextmanager
+    async def fake_http(*args, **kwargs):
+        result["callback"] = await captured["callback_handler"]()
+        raise RuntimeError("callback returned")
+        yield  # unreachable
+
+    async def run():
+        with (
+            patch("mcpgen._bridge._open_http", fake_http),
+            patch("mcpgen._bridge.OAuthClientProvider", provider),
+            patch("sys.stdin", _SlowStdin("http://localhost/callback?code=abc&state=xyz\n")),
+        ):
+            with pytest.raises(RuntimeError, match="callback returned"):
+                await _bridge.login(
+                    "acme",
+                    creds_path=creds,
+                    url="https://acme.example.com/mcp",
+                    headless=True,
+                    callback_timeout=0.01,
+                )
+
+    asyncio.run(run())
+    assert result["callback"] == ("abc", "xyz")
+
+
+def test_ensure_login_all_threads_callback_timeout(tmp_path):
+    """callback_timeout rides along with headless through both ensure_* helpers."""
+    creds = tmp_path / "credentials.json"
+    calls = []
+
+    async def fake_ensure_login(name, creds_path=None, **kwargs):
+        calls.append(kwargs)
+
+    async def run():
+        with patch("mcpgen._bridge.ensure_login", fake_ensure_login):
+            await _bridge.ensure_login_all(["acme", "beta"], creds, callback_timeout=42)
+
+    asyncio.run(run())
+    assert [c["callback_timeout"] for c in calls] == [42, 42]
+
+
+def test_ensure_login_threads_callback_timeout_into_login(tmp_path):
+    creds = tmp_path / "credentials.json"
+    login_mock = AsyncMock()
+
+    async def run():
+        with patch("mcpgen._bridge.login", login_mock):
+            await _bridge.ensure_login("acme", creds, url="https://acme.example.com/mcp", callback_timeout=42)
+
+    asyncio.run(run())
+    assert login_mock.await_args.kwargs["callback_timeout"] == 42
+
+
+@pytest.mark.parametrize(
+    ("argv_flag", "expected"),
+    [(["--callback-timeout", "45"], 45.0), (["--callback-timeout", "0"], 0.0), ([], None)],
+)
+def test_cli_login_callback_timeout_flag(argv_flag, expected):
+    """--callback-timeout reaches _bridge.login; absent → None → module default."""
+    from mcpgen.cli import main
+
+    login_mock = AsyncMock()
+    with patch("mcpgen._bridge.login", login_mock):
+        assert main(["login", "acme", *argv_flag]) == 0
+    assert login_mock.await_args.kwargs["callback_timeout"] == expected
+
+
+@pytest.mark.parametrize("bad", ["-1", "abc", "nan"])
+def test_cli_login_callback_timeout_rejects_invalid(bad, capsys):
+    """Nonsense values fail at argparse with a usage message, not deep in asyncio."""
+    from mcpgen.cli import main
+
+    with pytest.raises(SystemExit) as exc:
+        main(["login", "acme", "--callback-timeout", bad])
+    assert exc.value.code == 2
+    assert "--callback-timeout" in capsys.readouterr().err

{mcp_client_kit-0.3.0 → mcp_client_kit-0.4.0}/uv.lock

@@ -535,7 +535,7 @@ cli = [
 
 [[package]]
 name = "mcp-client-kit"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },