feat(keycardai-mcp): headless clients

Author: kamil-keycard

packages/mcp/src/keycardai/mcp/client/CONTRIBUTORS.md

@@ -1182,9 +1182,12 @@ Clear boundaries help maintain clean architecture.
 
 **LocalAuthCoordinator** (CLI/Desktop):
 - Runs embedded HTTP callback server on localhost
-- Blocks on redirects using asyncio.Event (waits for callback)
-- Opens browser automatically (`webbrowser.open()`)
+- Blocks on redirects using asyncio.Event (waits for callback) - **configurable**
+- Opens browser automatically (`webbrowser.open()`) - **configurable**
 - Suitable for single-process applications
+- Parameters:
+  - `auto_open_browser` (default: `True`): Whether to automatically open browser
+  - `block_until_callback` (default: `True`): Whether to block until callback received
 
 **StarletteAuthCoordinator** (Web/Serverless):
 - Delegates to remote callback endpoint (Starlette/FastAPI)

packages/mcp/src/keycardai/mcp/client/README.md

@@ -269,6 +269,70 @@ def main():
     asyncio.run(run())
 ```
 
+#### Manual Browser Control (Non-Blocking)
+
+If you prefer to control when the browser opens or want a non-blocking flow:
+
+```python
+import asyncio
+from keycardai.mcp.client import Client, LocalAuthCoordinator, InMemoryBackend
+
+servers = {
+    "my-server": {
+        "url": "http://localhost:7878/mcp",
+        "transport": "http",
+        "auth": {"type": "oauth"}
+    }
+}
+
+async def run():
+    # Disable auto-open browser and blocking behavior
+    coordinator = LocalAuthCoordinator(
+        backend=InMemoryBackend(),
+        host="localhost",
+        port=8888,
+        callback_path="/oauth/callback",
+        auto_open_browser=False,      # Don't auto-open browser
+        block_until_callback=False    # Return immediately instead of blocking
+    )
+    
+    async with Client(servers, auth_coordinator=coordinator) as client:
+        # Try to connect (non-blocking if auth needed)
+        await client.connect()
+        
+        # Check if authentication is required
+        auth_status = await coordinator.get_auth_pending(
+            context_id=client.context.id,
+            server_name="my-server"
+        )
+        
+        if auth_status:
+            # Auth URL is logged but not auto-opened
+            auth_url = auth_status.get("authorization_url")
+            print(f"\n🔐 Authentication required!")
+            print(f"Please visit: {auth_url}\n")
+            
+            # Wait for user to complete auth in browser
+            # (callback server still runs in background)
+            import time
+            while auth_status:
+                await asyncio.sleep(1)
+                auth_status = await coordinator.get_auth_pending(
+                    context_id=client.context.id,
+                    server_name="my-server"
+                )
+            
+            # Reconnect now that auth is complete
+            await client.connect()
+        
+        # Now authenticated - use the tools
+        tools = await client.list_tools("my-server")
+        print(f"Available tools: {len(tools)}")
+
+def main():
+    asyncio.run(run())
+```
+
 ---
 
 ### 2. Web Applications

packages/mcp/src/keycardai/mcp/client/auth/coordinators/endpoint_managers.py

@@ -52,8 +52,8 @@ class LocalEndpointManager(EndpointManager):
 
     Key behaviors:
     - Starts local HTTP server on demand (lazy initialization)
-    - Opens user's browser to authorization URL
-    - BLOCKS in initiate_redirect() until callback is received
+    - Opens user's browser to authorization URL (configurable)
+    - BLOCKS in initiate_redirect() until callback is received (configurable)
     - Tracks pending flows by OAuth state parameter
 
     Use for: CLI apps, desktop apps, local development.
@@ -63,7 +63,9 @@ def __init__(
         self,
         host: str = "localhost",
         port: int = 0,
-        callback_path: str = "/callback"
+        callback_path: str = "/callback",
+        auto_open_browser: bool = True,
+        block_until_callback: bool = True
     ):
         """
         Initialize local endpoint manager.
@@ -72,11 +74,15 @@ def __init__(
             host: Host for local server (default: localhost)
             port: Port for local server (0 = auto-assign)
             callback_path: Path for callback endpoint (default: /callback)
+            auto_open_browser: Whether to automatically open browser (default: True)
+            block_until_callback: Whether to block until callback received (default: True)
         """
         self._host = host
         self._desired_port = port
         self._actual_port: int | None = None
         self._callback_path = callback_path
+        self._auto_open_browser = auto_open_browser
+        self._block_until_callback = block_until_callback
 
         self._server_task: asyncio.Task | None = None
         self._ready_event = asyncio.Event()
@@ -125,21 +131,22 @@ async def get_redirect_uris(self) -> list[str]:
 
     async def initiate_redirect(self, url: str, metadata: dict[str, Any]) -> None:
         """
-        Open browser and BLOCK until callback is received.
+        Initiate OAuth redirect (configurable browser opening and blocking).
 
-        This is the key behavior for CLI apps: the function blocks until
-        the user completes authorization in their browser.
+        Behavior depends on configuration:
+        - auto_open_browser=True: Opens browser automatically
+        - auto_open_browser=False: Logs URL for manual opening
+        - block_until_callback=True: Blocks until callback received
+        - block_until_callback=False: Returns immediately
 
         Args:
             url: Authorization URL to open in browser
             metadata: Flow metadata including server_name
 
         Raises:
-            TimeoutError: If authorization not completed within 300 seconds
+            TimeoutError: If authorization not completed within 300 seconds (when blocking)
         """
         server_name = metadata.get("server_name", "unknown")
-        logger.info(f"Opening browser for auth flow (server: {server_name})")
-        logger.info("Please authorize in your browser...")
 
         state = self._extract_state_from_url(url)
         if not state:
@@ -149,16 +156,25 @@ async def initiate_redirect(self, url: str, metadata: dict[str, Any]) -> None:
         if state not in self._pending_flows:
             self._pending_flows[state] = asyncio.Event()
 
-        webbrowser.open(url)
+        if self._auto_open_browser:
+            logger.info(f"Opening browser for auth flow (server: {server_name})")
+            logger.info("Please authorize in your browser...")
+            webbrowser.open(url)
+        else:
+            logger.info(f"Authorization required for {server_name}")
+            logger.info(f"Please visit: {url}")
 
-        logger.info("Waiting for authorization to complete...")
-        try:
-            await asyncio.wait_for(self._pending_flows[state].wait(), timeout=300)
-            logger.info(f"Authorization completed for {server_name}")
-        except asyncio.TimeoutError as e:
-            logger.error("Authorization timed out after 300s")
-            self._pending_flows.pop(state, None)
-            raise TimeoutError(f"Authorization timed out for {server_name}") from e
+        if self._block_until_callback:
+            logger.info("Waiting for authorization to complete...")
+            try:
+                await asyncio.wait_for(self._pending_flows[state].wait(), timeout=300)
+                logger.info(f"Authorization completed for {server_name}")
+            except asyncio.TimeoutError as e:
+                logger.error("Authorization timed out after 300s")
+                self._pending_flows.pop(state, None)
+                raise TimeoutError(f"Authorization timed out for {server_name}") from e
+        else:
+            logger.debug(f"Non-blocking mode: returning immediately for {server_name}")
 
     async def shutdown(self) -> None:
         """

packages/mcp/src/keycardai/mcp/client/auth/coordinators/local.py

@@ -19,17 +19,19 @@ class LocalAuthCoordinator(AuthCoordinator):
     Use for: CLI apps, desktop apps, local development.
 
     Key behaviors:
-    - Opens browser to authorization URL
-    - Blocks in handle_redirect() until completion arrives
-    - Requires synchronous cleanup to avoid race conditions
+    - Opens browser to authorization URL (configurable)
+    - Blocks in handle_redirect() until completion arrives (configurable)
+    - Requires synchronous cleanup to avoid race conditions (when blocking)
     """
 
     def __init__(
         self,
         backend: StorageBackend | None = None,
         host: str = "localhost",
         port: int = 0,
-        callback_path: str = "/callback"
+        callback_path: str = "/callback",
+        auto_open_browser: bool = True,
+        block_until_callback: bool = True
     ):
         """
         Initialize local coordinator with LocalEndpointManager.
@@ -39,9 +41,17 @@ def __init__(
             host: Host for local server (default: localhost)
             port: Port (0 = auto-assign)
             callback_path: HTTP callback path for OAuth redirects (default: /callback)
+            auto_open_browser: Whether to automatically open browser (default: True)
+            block_until_callback: Whether to block until callback received (default: True)
         """
-        # Create endpoint manager
-        endpoint_manager = LocalEndpointManager(host, port, callback_path)
+        # Create endpoint manager with configurable behavior
+        endpoint_manager = LocalEndpointManager(
+            host,
+            port,
+            callback_path,
+            auto_open_browser=auto_open_browser,
+            block_until_callback=block_until_callback
+        )
 
         # Initialize base coordinator with endpoint manager
         super().__init__(backend, endpoint_manager)