gopher-mcp-python 0.1.34__tar.gz → 0.1.38__tar.gz

{gopher_mcp_python-0.1.34 → gopher_mcp_python-0.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gopher-mcp-python
-Version: 0.1.34
+Version: 0.1.38
 Summary: Python SDK for Gopher MCP - AI Agent orchestration framework with native performance
 Author-email: Gopher Security <dev@gophersecurity.com>
 License: Apache-2.0
@@ -219,6 +219,42 @@ Result class with status and metadata.
 - `result.is_error()` - Check if error
 - `result.is_timeout()` - Check if timeout
 
+### Provider OAuth Elicitation
+
+Provider OAuth requested during a tool call is handled automatically by default.
+For URL-mode elicitation, the SDK opens the authorization URL when possible,
+prints it as a fallback, waits for the user to finish the browser flow, and then
+lets the native agent retry the tool call.
+
+No example-level elicitation configuration is required:
+
+```python
+agent = GopherAgent.create_with_url(provider, model, mcp_url)
+```
+
+Use `GopherAgentCreateOptions` only when you need a custom synchronous handler
+or want to disable browser opening while still printing the URL:
+
+```python
+from gopher_mcp_python import GopherAgentCreateOptions
+
+agent = GopherAgent.create_with_url(
+    provider,
+    model,
+    mcp_url,
+    GopherAgentCreateOptions(
+        elicitation={
+            "open_browser": False,
+            "handler": lambda request: "accept",
+        },
+    ),
+)
+```
+
+First-step MCP server OAuth is controlled separately by the `oauth` create
+option. Setting `oauth={"mode": "disabled"}` skips SDK OAuth discovery for the
+MCP endpoint but still leaves provider elicitation enabled.
+
 ### Exceptions
 
 - `AgentError` - Base exception for agent errors
@@ -234,6 +270,10 @@ Result class with status and metadata.
 pytest
 ```
 
+For deterministic OAuth auto verification with a local custom IdP and local MCP
+server/gateway endpoints, see
+[`docs/oauth-auto-custom-idp.md`](docs/oauth-auto-custom-idp.md).
+
 ### Code Formatting
 
 This project uses Black for code formatting and Ruff for linting.

{gopher_mcp_python-0.1.34 → gopher_mcp_python-0.1.38}/README.md

@@ -175,6 +175,42 @@ Result class with status and metadata.
 - `result.is_error()` - Check if error
 - `result.is_timeout()` - Check if timeout
 
+### Provider OAuth Elicitation
+
+Provider OAuth requested during a tool call is handled automatically by default.
+For URL-mode elicitation, the SDK opens the authorization URL when possible,
+prints it as a fallback, waits for the user to finish the browser flow, and then
+lets the native agent retry the tool call.
+
+No example-level elicitation configuration is required:
+
+```python
+agent = GopherAgent.create_with_url(provider, model, mcp_url)
+```
+
+Use `GopherAgentCreateOptions` only when you need a custom synchronous handler
+or want to disable browser opening while still printing the URL:
+
+```python
+from gopher_mcp_python import GopherAgentCreateOptions
+
+agent = GopherAgent.create_with_url(
+    provider,
+    model,
+    mcp_url,
+    GopherAgentCreateOptions(
+        elicitation={
+            "open_browser": False,
+            "handler": lambda request: "accept",
+        },
+    ),
+)
+```
+
+First-step MCP server OAuth is controlled separately by the `oauth` create
+option. Setting `oauth={"mode": "disabled"}` skips SDK OAuth discovery for the
+MCP endpoint but still leaves provider elicitation enabled.
+
 ### Exceptions
 
 - `AgentError` - Base exception for agent errors
@@ -190,6 +226,10 @@ Result class with status and metadata.
 pytest
 ```
 
+For deterministic OAuth auto verification with a local custom IdP and local MCP
+server/gateway endpoints, see
+[`docs/oauth-auto-custom-idp.md`](docs/oauth-auto-custom-idp.md).
+
 ### Code Formatting
 
 This project uses Black for code formatting and Ruff for linting.

{gopher_mcp_python-0.1.34 → gopher_mcp_python-0.1.38}/gopher_mcp_python/__init__.py

@@ -29,6 +29,13 @@ from gopher_mcp_python.config import (
     GopherAgentConfig,
     GopherAgentConfigBuilder,
 )
+from gopher_mcp_python.elicitation import (
+    GopherAgentElicitationAction,
+    GopherAgentElicitationHandler,
+    GopherAgentElicitationOptions,
+    GopherAgentElicitationRequest,
+    GopherAgentElicitationResponse,
+)
 from gopher_mcp_python.runtime_options import (
     GopherAgentCreateOptions,
     GopherAgentOAuthOptions,
@@ -46,7 +53,7 @@ from gopher_mcp_python.errors import (
 from gopher_mcp_python.server_config import ServerConfig, ServerConfigRoute
 from gopher_mcp_python.ffi import GopherOrchLibrary, GopherOrchHandle
 
-__version__ = "0.1.34"
+__version__ = "0.1.38"
 
 _AUTH_EXPORTS = {
     "GopherAuth",
@@ -128,6 +135,11 @@ __all__ = [
     "GopherAgentConfig",
     "GopherAgentConfigBuilder",
     "GopherAgentCreateOptions",
+    "GopherAgentElicitationAction",
+    "GopherAgentElicitationHandler",
+    "GopherAgentElicitationOptions",
+    "GopherAgentElicitationRequest",
+    "GopherAgentElicitationResponse",
     "GopherAgentOAuthOptions",
     "GopherAgentRuntimeOptions",
     "GopherAgentTokenRecord",

{gopher_mcp_python-0.1.34 → gopher_mcp_python-0.1.38}/gopher_mcp_python/agent.py

@@ -31,9 +31,13 @@ import asyncio
 import weakref
 from typing import Callable, Optional
 
+from gopher_mcp_python.gateway_elicitation_preflight import (
+    preflight_gateway_elicitation,
+)
 import gopher_mcp_python.oauth_resolver as oauth_resolver
 from gopher_mcp_python.config import GopherAgentConfig
 from gopher_mcp_python.runtime_options import (
+    GopherAgentCreateOptions,
     GopherAgentOAuthOptions,
     GopherAgentRuntimeOptions,
     RuntimeOptionsInput,
@@ -159,7 +163,7 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        create_options = normalize_create_options(runtime_options)
+        create_options = _normalize_create_options_for_agent(runtime_options)
         runtime_options = normalize_runtime_options(create_options)
         oauth = create_options.oauth if create_options is not None else None
         if _should_skip_oauth(runtime_options, oauth):
@@ -197,7 +201,7 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        create_options = normalize_create_options(runtime_options)
+        create_options = _normalize_create_options_for_agent(runtime_options)
         runtime_options = normalize_runtime_options(create_options)
         oauth = create_options.oauth if create_options is not None else None
         if _should_skip_oauth(runtime_options, oauth):
@@ -246,7 +250,7 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        create_options = normalize_create_options(runtime_options)
+        create_options = _normalize_create_options_for_agent(runtime_options)
         normalized_runtime_options = normalize_runtime_options(create_options)
         oauth = create_options.oauth if create_options is not None else None
         if _should_skip_oauth(normalized_runtime_options, oauth):
@@ -289,7 +293,7 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        create_options = normalize_create_options(runtime_options)
+        create_options = _normalize_create_options_for_agent(runtime_options)
         normalized_runtime_options = normalize_runtime_options(create_options)
         oauth = create_options.oauth if create_options is not None else None
         if _should_skip_oauth(normalized_runtime_options, oauth):
@@ -332,7 +336,7 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        create_options = normalize_create_options(runtime_options)
+        create_options = _normalize_create_options_for_agent(runtime_options)
         normalized_runtime_options = normalize_runtime_options(create_options)
         oauth = create_options.oauth if create_options is not None else None
         if _should_skip_oauth(normalized_runtime_options, oauth):
@@ -375,7 +379,7 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        create_options = normalize_create_options(runtime_options)
+        create_options = _normalize_create_options_for_agent(runtime_options)
         normalized_runtime_options = normalize_runtime_options(create_options)
         oauth = create_options.oauth if create_options is not None else None
         if _should_skip_oauth(normalized_runtime_options, oauth):
@@ -417,7 +421,7 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        create_options = normalize_create_options(runtime_options)
+        create_options = _normalize_create_options_for_agent(runtime_options)
         normalized_runtime_options = normalize_runtime_options(create_options)
         oauth = create_options.oauth if create_options is not None else None
         if url != "" and not _should_skip_oauth(normalized_runtime_options, oauth):
@@ -428,6 +432,11 @@ class GopherAgent:
                     oauth=oauth,
                 )
             )
+        normalized_runtime_options = preflight_gateway_elicitation(
+            url,
+            normalized_runtime_options,
+            create_options,
+        )
         return GopherAgent._create_from_ffi(
             lambda lib: lib.agent_create_by_url(
                 provider, model, url, normalized_runtime_options
@@ -605,6 +614,13 @@ def _run_oauth_coroutine(create_coroutine):
     )
 
 
+def _normalize_create_options_for_agent(
+    runtime_options: RuntimeOptionsInput,
+) -> GopherAgentCreateOptions:
+    create_options = normalize_create_options(runtime_options)
+    return create_options if create_options is not None else GopherAgentCreateOptions()
+
+
 def _should_skip_oauth(
     runtime_options: Optional[GopherAgentRuntimeOptions],
     oauth: Optional[GopherAgentOAuthOptions],

{gopher_mcp_python-0.1.34 → gopher_mcp_python-0.1.38}/gopher_mcp_python/config.py

@@ -206,13 +206,19 @@ class GopherAgentConfigBuilder:
         current_oauth = (
             self._runtime_options.oauth if self._runtime_options is not None else None
         )
-        self._runtime_options = normalize_create_options(
-            {
-                "access_token": access_token,
-                "headers": current_headers,
-                "oauth": current_oauth,
-            }
+        current_elicitation = (
+            self._runtime_options.elicitation
+            if self._runtime_options is not None
+            else None
         )
+        next_options = {
+            "access_token": access_token,
+            "headers": current_headers,
+            "oauth": current_oauth,
+        }
+        if current_elicitation is not None:
+            next_options["elicitation"] = current_elicitation
+        self._runtime_options = normalize_create_options(next_options)
         return self
 
     def headers(self, headers: Mapping[str, str]) -> "GopherAgentConfigBuilder":
@@ -233,13 +239,19 @@ class GopherAgentConfigBuilder:
         current_oauth = (
             self._runtime_options.oauth if self._runtime_options is not None else None
         )
-        self._runtime_options = normalize_create_options(
-            {
-                "access_token": current_token,
-                "headers": headers,
-                "oauth": current_oauth,
-            }
+        current_elicitation = (
+            self._runtime_options.elicitation
+            if self._runtime_options is not None
+            else None
         )
+        next_options = {
+            "access_token": current_token,
+            "headers": headers,
+            "oauth": current_oauth,
+        }
+        if current_elicitation is not None:
+            next_options["elicitation"] = current_elicitation
+        self._runtime_options = normalize_create_options(next_options)
         return self
 
     def build(self) -> GopherAgentConfig:

gopher_mcp_python-0.1.38/gopher_mcp_python/elicitation.py

@@ -0,0 +1,120 @@
+"""MCP server-to-client elicitation support."""
+
+from typing import Any, Callable, Mapping, Optional, Union
+
+
+GopherAgentElicitationAction = str
+
+
+class GopherAgentElicitationRequest:
+    """Server-provided MCP elicitation/create request."""
+
+    def __init__(
+        self,
+        mode: str,
+        elicitation_id: Optional[str] = None,
+        message: Optional[str] = None,
+        url: Optional[str] = None,
+        request_id_json: Optional[str] = None,
+        raw_json: Optional[str] = None,
+        raw_params_json: Optional[str] = None,
+    ) -> None:
+        if not isinstance(mode, str):
+            raise ValueError("elicitation mode must be a string")
+        self.mode = mode
+        self.elicitation_id = _optional_string(elicitation_id, "elicitation_id")
+        self.message = _optional_string(message, "message")
+        self.url = _optional_string(url, "url")
+        self.request_id_json = _optional_string(request_id_json, "request_id_json")
+        self.raw_json = _optional_string(raw_json, "raw_json")
+        self.raw_params_json = _optional_string(raw_params_json, "raw_params_json")
+
+
+class GopherAgentElicitationResponse:
+    """Application response to an MCP elicitation request."""
+
+    def __init__(self, action: GopherAgentElicitationAction) -> None:
+        self.action = normalize_elicitation_action(action)
+
+
+GopherAgentElicitationHandler = Callable[
+    [GopherAgentElicitationRequest],
+    Union[GopherAgentElicitationResponse, GopherAgentElicitationAction],
+]
+
+
+class GopherAgentElicitationOptions:
+    """Options for MCP server-to-client elicitation handling."""
+
+    def __init__(
+        self,
+        handler: Optional[GopherAgentElicitationHandler] = None,
+        timeout_ms: Optional[int] = None,
+        open_browser: Optional[bool] = None,
+    ) -> None:
+        if handler is not None and not callable(handler):
+            raise ValueError("elicitation handler must be callable")
+        if timeout_ms is not None:
+            if not isinstance(timeout_ms, (int, float)) or not _is_finite(timeout_ms):
+                raise ValueError("elicitation timeout_ms must be a finite number")
+            timeout_ms = max(0, int(timeout_ms))
+        if open_browser is not None and not isinstance(open_browser, bool):
+            raise ValueError("elicitation open_browser must be a boolean")
+        self.handler = handler
+        self.timeout_ms = timeout_ms
+        self.open_browser = open_browser
+
+
+def normalize_elicitation_options(
+    options: Optional[
+        Union[GopherAgentElicitationOptions, Mapping[str, Any]]
+    ] = None,
+) -> GopherAgentElicitationOptions:
+    """Normalize elicitation options, defaulting omitted options to enabled."""
+    if options is None:
+        return GopherAgentElicitationOptions()
+
+    if isinstance(options, GopherAgentElicitationOptions):
+        return options
+
+    if isinstance(options, Mapping):
+        timeout_ms = (
+            options.get("timeout_ms")
+            if "timeout_ms" in options
+            else options.get("timeoutMs")
+        )
+        open_browser = (
+            options.get("open_browser")
+            if "open_browser" in options
+            else options.get("openBrowser")
+        )
+        return GopherAgentElicitationOptions(
+            handler=options.get("handler"),
+            timeout_ms=timeout_ms,
+            open_browser=open_browser,
+        )
+
+    raise ValueError(
+        "elicitation options must be a GopherAgentElicitationOptions instance "
+        "or mapping"
+    )
+
+
+def normalize_elicitation_action(
+    response: Union[GopherAgentElicitationResponse, GopherAgentElicitationAction]
+) -> GopherAgentElicitationAction:
+    """Normalize and validate an MCP elicitation action."""
+    action = response.action if isinstance(response, GopherAgentElicitationResponse) else response
+    if action in ("accept", "decline", "cancel"):
+        return action
+    raise ValueError(f"unsupported MCP elicitation action: {action}")
+
+
+def _optional_string(value: Optional[str], name: str) -> Optional[str]:
+    if value is not None and not isinstance(value, str):
+        raise ValueError(f"elicitation {name} must be a string")
+    return value
+
+
+def _is_finite(value: Union[int, float]) -> bool:
+    return value == value and value not in (float("inf"), float("-inf"))

gopher_mcp_python-0.1.38/gopher_mcp_python/elicitation_runtime.py

@@ -0,0 +1,229 @@
+"""Runtime helpers for MCP elicitation callbacks."""
+
+import inspect
+import os
+import selectors
+import sys
+from typing import Any, Callable, Dict, Mapping, Optional
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from gopher_mcp_python.elicitation import (
+    GopherAgentElicitationAction,
+    GopherAgentElicitationHandler,
+    GopherAgentElicitationOptions,
+    GopherAgentElicitationRequest,
+    GopherAgentElicitationResponse,
+    normalize_elicitation_action,
+)
+from gopher_mcp_python.oauth_browser import open_authorization_url
+
+ELICITATION_ACTION_ACCEPT = 1
+ELICITATION_ACTION_DECLINE = 2
+ELICITATION_ACTION_CANCEL = 3
+
+_read_input: Callable[[Optional[int]], Optional[str]]
+
+
+def to_elicitation_request(
+    request: Mapping[str, Optional[str]]
+) -> GopherAgentElicitationRequest:
+    """Convert native request fields into the public Python request object."""
+    return GopherAgentElicitationRequest(
+        mode=request.get("mode") or "",
+        elicitation_id=request.get("elicitation_id"),
+        message=request.get("message"),
+        url=request.get("url"),
+        request_id_json=request.get("request_id_json"),
+        raw_json=request.get("raw_json"),
+        raw_params_json=request.get("raw_params_json"),
+    )
+
+
+def resolve_elicitation_action_sync(
+    options: GopherAgentElicitationOptions,
+    request: GopherAgentElicitationRequest,
+) -> GopherAgentElicitationAction:
+    """Resolve an elicitation request using a synchronous handler."""
+    handler = options.handler or default_url_elicitation_handler(options)
+    _log_elicitation_debug("request", _summarize_elicitation_request(request))
+    response = handler(request)
+    if inspect.isawaitable(response):
+        if inspect.iscoroutine(response):
+            response.close()
+        raise RuntimeError(
+            "Async MCP elicitation handlers are not supported by the native "
+            "FFI bridge yet"
+        )
+    action = normalize_elicitation_action(response)
+    _log_elicitation_debug(
+        "response",
+        {
+            "elicitation_id": request.elicitation_id,
+            "mode": request.mode,
+            "action": action,
+        },
+    )
+    return action
+
+
+def default_url_elicitation_handler(
+    options: Optional[GopherAgentElicitationOptions] = None,
+) -> GopherAgentElicitationHandler:
+    """Return the SDK's default URL-mode provider OAuth handler."""
+    resolved_options = options or GopherAgentElicitationOptions()
+
+    def handle(
+        request: GopherAgentElicitationRequest,
+    ) -> GopherAgentElicitationResponse:
+        if request.mode != "url" or not request.url:
+            return GopherAgentElicitationResponse("decline")
+        result = open_authorization_url(
+            request.url,
+            open_browser=resolved_options.open_browser,
+        )
+        if not result.get("opened"):
+            print(
+                "Open this OAuth authorization URL to continue:\n"
+                f"{request.url}",
+                file=sys.stderr,
+            )
+        return GopherAgentElicitationResponse(
+            wait_for_oauth_completion_sync(resolved_options.timeout_ms)
+        )
+
+    return handle
+
+
+def wait_for_oauth_completion_sync(
+    timeout_ms: Optional[int] = None,
+) -> GopherAgentElicitationAction:
+    """Wait synchronously for the user to finish browser OAuth."""
+    print(
+        'Complete the OAuth flow in the browser, then press Enter to continue. '
+        'Type "cancel" and press Enter to cancel.',
+        file=sys.stderr,
+    )
+    value = _read_input(timeout_ms)
+    if value is None:
+        print(
+            "Cannot access an interactive terminal; canceling provider "
+            "authorization.",
+            file=sys.stderr,
+        )
+        return "cancel"
+    return "cancel" if value.strip().lower() == "cancel" else "accept"
+
+
+def native_action_from_elicitation_action(
+    action: GopherAgentElicitationAction,
+) -> int:
+    """Map public action strings to native integer constants."""
+    if action == "accept":
+        return ELICITATION_ACTION_ACCEPT
+    if action == "decline":
+        return ELICITATION_ACTION_DECLINE
+    if action == "cancel":
+        return ELICITATION_ACTION_CANCEL
+    raise ValueError(f"unsupported MCP elicitation action: {action}")
+
+
+def set_elicitation_input_for_test(
+    read_input: Optional[Callable[[Optional[int]], Optional[str]]],
+) -> None:
+    """Override terminal input for tests."""
+    global _read_input
+    _read_input = read_input or _read_terminal_input
+
+
+def redact_elicitation_url(url: str) -> str:
+    """Redact sensitive OAuth query fields for diagnostic logging."""
+    try:
+        parsed = urlsplit(url)
+        query = urlencode(
+            [
+                (
+                    name,
+                    "<redacted>" if _is_sensitive_query_name(name) else "<present>",
+                )
+                for name, _value in parse_qsl(parsed.query, keep_blank_values=True)
+            ]
+        )
+        fragment = "<redacted>" if parsed.fragment else ""
+        return urlunsplit(
+            (parsed.scheme, parsed.netloc, parsed.path, query, fragment)
+        )
+    except Exception:
+        return "<invalid-url>"
+
+
+def _read_terminal_input(timeout_ms: Optional[int]) -> Optional[str]:
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        return None
+    if timeout_ms is not None and timeout_ms > 0:
+        return _read_terminal_input_with_timeout(timeout_ms)
+    if not sys.stdin or not sys.stdin.isatty():
+        return None
+    return sys.stdin.readline()
+
+
+def _read_terminal_input_with_timeout(timeout_ms: int) -> Optional[str]:
+    if not sys.stdin or not sys.stdin.isatty():
+        return None
+    selector = None
+    try:
+        selector = selectors.DefaultSelector()
+        selector.register(sys.stdin, selectors.EVENT_READ)
+        events = selector.select(timeout_ms / 1000.0)
+    except Exception:
+        return None
+    finally:
+        if selector is not None:
+            try:
+                selector.close()
+            except Exception:
+                pass
+    if not events:
+        print(
+            "Timed out waiting for OAuth completion; canceling provider "
+            "authorization.",
+            file=sys.stderr,
+        )
+        return None
+    return sys.stdin.readline()
+
+
+def _summarize_elicitation_request(
+    request: GopherAgentElicitationRequest,
+) -> Dict[str, Optional[str]]:
+    host = None
+    if request.url:
+        try:
+            host = urlsplit(request.url).netloc
+        except Exception:
+            host = None
+    return {
+        "elicitation_id": request.elicitation_id,
+        "mode": request.mode,
+        "host": host,
+        "url": redact_elicitation_url(request.url) if request.url else None,
+    }
+
+
+def _log_elicitation_debug(label: str, values: Any) -> None:
+    if os.environ.get("GOPHER_MCP_OAUTH_DEBUG") != "1" and os.environ.get("DEBUG") != "1":
+        return
+    print(f"[gopher-mcp-python elicitation] {label}: {values}", file=sys.stderr)
+
+
+def _is_sensitive_query_name(name: str) -> bool:
+    normalized = name.lower()
+    return (
+        normalized == "state"
+        or normalized == "code"
+        or normalized == "client_secret"
+        or "token" in normalized
+        or "secret" in normalized
+    )
+
+
+_read_input = _read_terminal_input