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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gopher-mcp-python
-Version: 0.1.30
+Version: 0.1.34
 Summary: Python SDK for Gopher MCP - AI Agent orchestration framework with native performance
 Author-email: Gopher Security <dev@gophersecurity.com>
 License: Apache-2.0
@@ -61,6 +61,9 @@ Python SDK for gopher-mcp-python, providing AI agent orchestration with native C
 - Python 3.8 or higher
 - `venv` and `pip` for PyPI installation, examples, and development workflows
 - Native gopher-mcp-python library (built from source)
+- On Linux, system OpenSSL runtime libraries (`libssl` / `libcrypto`) from
+  your distribution. Native wheels do not bundle OpenSSL, so OS security
+  updates remain effective.
 
 On Debian/Ubuntu, install the Python venv and pip packages before using the
 PyPI install path, running examples, or setting up development dependencies:

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

@@ -17,6 +17,9 @@ Python SDK for gopher-mcp-python, providing AI agent orchestration with native C
 - Python 3.8 or higher
 - `venv` and `pip` for PyPI installation, examples, and development workflows
 - Native gopher-mcp-python library (built from source)
+- On Linux, system OpenSSL runtime libraries (`libssl` / `libcrypto`) from
+  your distribution. Native wheels do not bundle OpenSSL, so OS security
+  updates remain effective.
 
 On Debian/Ubuntu, install the Python venv and pip packages before using the
 PyPI install path, running examples, or setting up development dependencies:

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

@@ -22,11 +22,19 @@ Example:
     >>> agent.dispose()
 """
 
+from importlib import import_module
+
 from gopher_mcp_python.agent import GopherAgent
 from gopher_mcp_python.config import (
     GopherAgentConfig,
     GopherAgentConfigBuilder,
+)
+from gopher_mcp_python.runtime_options import (
+    GopherAgentCreateOptions,
+    GopherAgentOAuthOptions,
     GopherAgentRuntimeOptions,
+    GopherAgentTokenRecord,
+    GopherAgentTokenStore,
 )
 from gopher_mcp_python.result import AgentResult, AgentResultStatus, AgentResultBuilder
 from gopher_mcp_python.errors import (
@@ -35,76 +43,100 @@ from gopher_mcp_python.errors import (
     ConnectionError,
     TimeoutError,
 )
-from gopher_mcp_python.server_config import ServerConfig
+from gopher_mcp_python.server_config import ServerConfig, ServerConfigRoute
 from gopher_mcp_python.ffi import GopherOrchLibrary, GopherOrchHandle
 
-# Auth module re-exports
-from gopher_mcp_python.ffi.auth import (
-    # Types
-    GopherAuthError,
-    AutoRefreshResult,
-    RegistrationResponse,
-    TokenResponse,
-    ValidationResult,
-    TokenPayload,
-    GopherAuthContext,
-    ERROR_DESCRIPTIONS,
-    get_error_description,
-    gopher_create_empty_auth_context,
-    is_gopher_auth_error,
-    # Classes
-    GopherAuthClient,
-    GopherAuthConfig,
-    GopherOAuthClient,
-    GopherSessionManager,
-    GopherValidationOptions,
-    # Functions
-    gopher_auth_auto_refresh,
-    gopher_auth_build_oidc_discovery_metadata,
-    gopher_auth_build_oauth_server_metadata,
-    gopher_auth_build_protected_resource_metadata,
-    gopher_auth_extract_bearer_token,
-    gopher_auth_extract_method,
-    gopher_auth_extract_path,
-    gopher_auth_url_decode,
-    gopher_auth_url_encode,
-    gopher_auth_validate_all_scopes,
-    gopher_auth_validate_any_scopes,
-    gopher_auth_validate_idp,
-    gopher_create_validation_options,
-    gopher_generate_www_authenticate_header,
-    gopher_generate_www_authenticate_header_v2,
-    gopher_get_auth_library_version,
-    gopher_init_auth_library,
-    gopher_is_auth_library_initialized,
-    gopher_shutdown_auth_library,
-    is_auth_available,
-)
-from gopher_mcp_python.auth import (
-    GopherAuth,
-    GopherAuthError as GopherAuthBaseError,
-    ConfigurationError,
-    InsufficientScopesError,
-    JwksError,
-    TokenExchangeError,
-    TokenValidationError,
-    has_all_scopes,
-    has_any_scope,
-    has_scope,
-)
+__version__ = "0.1.34"
+
+_AUTH_EXPORTS = {
+    "GopherAuth",
+    "GopherAuthError",
+    "ConfigurationError",
+    "InsufficientScopesError",
+    "JwksError",
+    "TokenExchangeError",
+    "TokenValidationError",
+    "has_all_scopes",
+    "has_any_scope",
+    "has_scope",
+}
+
+_AUTH_FFI_EXPORTS = {
+    "AutoRefreshResult",
+    "RegistrationResponse",
+    "TokenResponse",
+    "ValidationResult",
+    "TokenPayload",
+    "GopherAuthContext",
+    "ERROR_DESCRIPTIONS",
+    "get_error_description",
+    "gopher_create_empty_auth_context",
+    "is_gopher_auth_error",
+    "GopherAuthClient",
+    "GopherAuthConfig",
+    "GopherOAuthClient",
+    "GopherSessionManager",
+    "GopherValidationOptions",
+    "gopher_auth_auto_refresh",
+    "gopher_auth_build_oidc_discovery_metadata",
+    "gopher_auth_build_oauth_server_metadata",
+    "gopher_auth_build_protected_resource_metadata",
+    "gopher_auth_extract_bearer_token",
+    "gopher_auth_extract_method",
+    "gopher_auth_extract_path",
+    "gopher_auth_url_decode",
+    "gopher_auth_url_encode",
+    "gopher_auth_validate_all_scopes",
+    "gopher_auth_validate_any_scopes",
+    "gopher_auth_validate_idp",
+    "gopher_create_validation_options",
+    "gopher_generate_www_authenticate_header",
+    "gopher_generate_www_authenticate_header_v2",
+    "gopher_get_auth_library_version",
+    "gopher_init_auth_library",
+    "gopher_is_auth_library_initialized",
+    "gopher_shutdown_auth_library",
+    "is_auth_available",
+}
+
+
+def __getattr__(name: str):
+    if name in _AUTH_EXPORTS:
+        auth = import_module("gopher_mcp_python.auth")
+        value = getattr(auth, name)
+        globals()[name] = value
+        return value
+
+    if name == "GopherAuthFfiError":
+        from gopher_mcp_python.ffi.auth import GopherAuthError as GopherAuthFfiError
+
+        globals()[name] = GopherAuthFfiError
+        return GopherAuthFfiError
+
+    if name in _AUTH_FFI_EXPORTS:
+        ffi_auth = import_module("gopher_mcp_python.ffi.auth")
+        value = getattr(ffi_auth, name)
+        globals()[name] = value
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-__version__ = "0.1.30"
 
 __all__ = [
     # Main classes
     "GopherAgent",
     "GopherAgentConfig",
     "GopherAgentConfigBuilder",
+    "GopherAgentCreateOptions",
+    "GopherAgentOAuthOptions",
     "GopherAgentRuntimeOptions",
+    "GopherAgentTokenRecord",
+    "GopherAgentTokenStore",
     "AgentResult",
     "AgentResultStatus",
     "AgentResultBuilder",
     "ServerConfig",
+    "ServerConfigRoute",
     # Errors
     "AgentError",
     "ApiKeyError",
@@ -114,7 +146,9 @@ __all__ = [
     "GopherOrchLibrary",
     "GopherOrchHandle",
     # Auth
+    "GopherAuth",
     "GopherAuthError",
+    "GopherAuthFfiError",
     "AutoRefreshResult",
     "RegistrationResponse",
     "TokenResponse",
@@ -150,8 +184,6 @@ __all__ = [
     "gopher_is_auth_library_initialized",
     "gopher_shutdown_auth_library",
     "is_auth_available",
-    "GopherAuth",
-    "GopherAuthBaseError",
     "ConfigurationError",
     "InsufficientScopesError",
     "JwksError",

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

@@ -27,10 +27,21 @@ Example with context manager:
 """
 
 import atexit
+import asyncio
+import weakref
 from typing import Callable, Optional
 
+import gopher_mcp_python.oauth_resolver as oauth_resolver
 from gopher_mcp_python.config import GopherAgentConfig
+from gopher_mcp_python.runtime_options import (
+    GopherAgentOAuthOptions,
+    GopherAgentRuntimeOptions,
+    RuntimeOptionsInput,
+    normalize_create_options,
+    normalize_runtime_options,
+)
 from gopher_mcp_python.result import AgentResult, AgentResultStatus
+from gopher_mcp_python.server_config import ServerConfig, ServerConfigRoute
 from gopher_mcp_python.errors import AgentError, TimeoutError
 from gopher_mcp_python.ffi import GopherOrchLibrary, GopherOrchHandle
 
@@ -51,6 +62,7 @@ class GopherAgent:
         """
         self._handle = handle
         self._disposed = False
+        self._finalizer = weakref.finalize(self, _release_handle_best_effort, handle)
 
     def __enter__(self) -> "GopherAgent":
         """Context manager entry."""
@@ -103,7 +115,7 @@ class GopherAgent:
     @staticmethod
     def create(config: GopherAgentConfig) -> "GopherAgent":
         """
-        Create a new GopherAgent instance.
+        Create a new GopherAgent instance, resolving SDK OAuth credentials if needed.
 
         Args:
             config: Agent configuration
@@ -114,46 +126,26 @@ class GopherAgent:
         Raises:
             AgentError: if agent creation fails
         """
-        if not _initialized:
-            GopherAgent.init()
-
-        lib = GopherOrchLibrary.get_instance()
-        if lib is None:
-            load_error = GopherOrchLibrary.get_load_error_message()
-            raise AgentError(f"Native library not available.\n{load_error}")
-
-        handle: Optional[GopherOrchHandle] = None
-        try:
-            if config.has_api_key():
-                handle = lib.agent_create_by_api_key(
-                    config.provider,
-                    config.model,
-                    config.api_key,
-                    config.runtime_options,
-                )
-            else:
-                handle = lib.agent_create_by_json(
-                    config.provider,
-                    config.model,
-                    config.server_config,
-                    config.runtime_options,
-                )
-        except Exception as e:
-            raise AgentError(f"Failed to create agent: {e}")
-
-        if handle is None:
-            error = lib.get_last_error_message()
-            lib.clear_error()
-            raise AgentError(error or _build_create_error_message())
-
-        return GopherAgent(handle)
+        if config.has_api_key():
+            return GopherAgent.create_with_api_key(
+                config.provider,
+                config.model,
+                config.api_key,
+                config.runtime_options,
+            )
+        return GopherAgent.create_with_server_config(
+            config.provider,
+            config.model,
+            config.server_config,
+            config.runtime_options,
+        )
 
     @staticmethod
     def create_with_api_key(
         provider: str,
         model: str,
         api_key: str,
-        runtime_options: Optional[object] = None,
+        runtime_options: RuntimeOptionsInput = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent with API key.
@@ -167,22 +159,31 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        builder = (
-            GopherAgentConfig.builder()
-            .provider(provider)
-            .model(model)
-            .api_key(api_key)
+        create_options = normalize_create_options(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):
+            return GopherAgent._create_from_ffi(
+                lambda lib: lib.agent_create_by_api_key(
+                    provider, model, api_key, runtime_options
+                )
+            )
+
+        return _create_from_api_config(
+            provider,
+            model,
+            api_key,
+            route=None,
+            runtime_options=runtime_options,
+            oauth=oauth,
         )
-        if runtime_options is not None:
-            builder.runtime_options(runtime_options)
-        return GopherAgent.create(builder.build())
 
     @staticmethod
     def create_with_server_config(
         provider: str,
         model: str,
         server_config: str,
-        runtime_options: Optional[object] = None,
+        runtime_options: RuntimeOptionsInput = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent with JSON server config.
@@ -196,15 +197,29 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        builder = (
-            GopherAgentConfig.builder()
-            .provider(provider)
-            .model(model)
-            .server_config(server_config)
+        create_options = normalize_create_options(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):
+            return GopherAgent._create_from_ffi(
+                lambda lib: lib.agent_create_by_json(
+                    provider, model, server_config, runtime_options
+                )
+            )
+
+        resolved_runtime_options = _run_oauth_coroutine(
+            lambda: oauth_resolver.resolve_runtime_options_with_oauth(
+                urls=[],
+                server_config=server_config,
+                runtime_options=runtime_options,
+                oauth=oauth,
+            )
+        )
+        return GopherAgent._create_from_ffi(
+            lambda lib: lib.agent_create_by_json(
+                provider, model, server_config, resolved_runtime_options
+            )
         )
-        if runtime_options is not None:
-            builder.runtime_options(runtime_options)
-        return GopherAgent.create(builder.build())
 
     @staticmethod
     def create_with_server_id(
@@ -212,7 +227,7 @@ class GopherAgent:
         model: str,
         api_key: str,
         server_id: str,
-        runtime_options: Optional[object] = None,
+        runtime_options: RuntimeOptionsInput = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP server by id.
@@ -231,10 +246,22 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        return GopherAgent._create_from_ffi(
-            lambda lib: lib.agent_create_by_server_id(
-                provider, model, api_key, server_id, runtime_options
+        create_options = normalize_create_options(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):
+            return GopherAgent._create_from_ffi(
+                lambda lib: lib.agent_create_by_server_id(
+                    provider, model, api_key, server_id, normalized_runtime_options
+                )
             )
+        return _create_from_api_config(
+            provider,
+            model,
+            api_key,
+            route=ServerConfigRoute("serverId", server_id),
+            runtime_options=normalized_runtime_options,
+            oauth=oauth,
         )
 
     @staticmethod
@@ -243,7 +270,7 @@ class GopherAgent:
         model: str,
         api_key: str,
         server_name: str,
-        runtime_options: Optional[object] = None,
+        runtime_options: RuntimeOptionsInput = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP server by name.
@@ -262,10 +289,22 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        return GopherAgent._create_from_ffi(
-            lambda lib: lib.agent_create_by_server_name(
-                provider, model, api_key, server_name, runtime_options
+        create_options = normalize_create_options(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):
+            return GopherAgent._create_from_ffi(
+                lambda lib: lib.agent_create_by_server_name(
+                    provider, model, api_key, server_name, normalized_runtime_options
+                )
             )
+        return _create_from_api_config(
+            provider,
+            model,
+            api_key,
+            route=ServerConfigRoute("serverName", server_name),
+            runtime_options=normalized_runtime_options,
+            oauth=oauth,
         )
 
     @staticmethod
@@ -274,7 +313,7 @@ class GopherAgent:
         model: str,
         api_key: str,
         gateway_id: str,
-        runtime_options: Optional[object] = None,
+        runtime_options: RuntimeOptionsInput = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP gateway by id.
@@ -293,10 +332,22 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        return GopherAgent._create_from_ffi(
-            lambda lib: lib.agent_create_by_gateway_id(
-                provider, model, api_key, gateway_id, runtime_options
+        create_options = normalize_create_options(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):
+            return GopherAgent._create_from_ffi(
+                lambda lib: lib.agent_create_by_gateway_id(
+                    provider, model, api_key, gateway_id, normalized_runtime_options
+                )
             )
+        return _create_from_api_config(
+            provider,
+            model,
+            api_key,
+            route=ServerConfigRoute("gatewayId", gateway_id),
+            runtime_options=normalized_runtime_options,
+            oauth=oauth,
         )
 
     @staticmethod
@@ -305,7 +356,7 @@ class GopherAgent:
         model: str,
         api_key: str,
         gateway_name: str,
-        runtime_options: Optional[object] = None,
+        runtime_options: RuntimeOptionsInput = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP gateway by name.
@@ -324,10 +375,22 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
-        return GopherAgent._create_from_ffi(
-            lambda lib: lib.agent_create_by_gateway_name(
-                provider, model, api_key, gateway_name, runtime_options
+        create_options = normalize_create_options(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):
+            return GopherAgent._create_from_ffi(
+                lambda lib: lib.agent_create_by_gateway_name(
+                    provider, model, api_key, gateway_name, normalized_runtime_options
+                )
             )
+        return _create_from_api_config(
+            provider,
+            model,
+            api_key,
+            route=ServerConfigRoute("gatewayName", gateway_name),
+            runtime_options=normalized_runtime_options,
+            oauth=oauth,
         )
 
     @staticmethod
@@ -335,7 +398,7 @@ class GopherAgent:
         provider: str,
         model: str,
         url: str,
-        runtime_options: Optional[object] = None,
+        runtime_options: RuntimeOptionsInput = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent for a single MCP server reachable at a URL.
@@ -354,8 +417,21 @@ class GopherAgent:
         Returns:
             GopherAgent instance
         """
+        create_options = normalize_create_options(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):
+            normalized_runtime_options = _run_oauth_coroutine(
+                lambda: oauth_resolver.resolve_url_runtime_options_with_oauth(
+                    url,
+                    runtime_options=normalized_runtime_options,
+                    oauth=oauth,
+                )
+            )
         return GopherAgent._create_from_ffi(
-            lambda lib: lib.agent_create_by_url(provider, model, url, runtime_options)
+            lambda lib: lib.agent_create_by_url(
+                provider, model, url, normalized_runtime_options
+            )
         )
 
     @staticmethod
@@ -379,6 +455,8 @@ class GopherAgent:
 
         try:
             handle = create_handle(lib)
+        except AgentError:
+            raise
         except Exception as e:
             raise AgentError(f"Failed to create agent: {e}")
 
@@ -449,14 +527,18 @@ class GopherAgent:
             return AgentResult.error(str(e))
 
     def dispose(self) -> None:
-        """Dispose of the agent and free resources."""
+        """
+        Dispose of the agent and free native resources deterministically.
+
+        A best-effort finalizer also releases forgotten agents during garbage
+        collection, but callers should prefer dispose() or a with block.
+        """
         if self._disposed:
             return
 
         self._disposed = True
-        lib = GopherOrchLibrary.get_instance()
-        if lib is not None and self._handle is not None:
-            lib.agent_release(self._handle)
+        if self._finalizer.alive:
+            self._finalizer()
 
     def is_disposed(self) -> bool:
         """Check if agent is disposed."""
@@ -478,6 +560,64 @@ def _setup_cleanup_handler() -> None:
     atexit.register(GopherAgent.shutdown)
 
 
+def _release_handle_best_effort(handle: GopherOrchHandle) -> None:
+    try:
+        lib = GopherOrchLibrary.get_instance()
+        if lib is not None and handle is not None:
+            lib.agent_release(handle)
+    except Exception:
+        return
+
+
+def _create_from_api_config(
+    provider: str,
+    model: str,
+    api_key: str,
+    route: Optional[ServerConfigRoute],
+    runtime_options: Optional[GopherAgentRuntimeOptions],
+    oauth: Optional[GopherAgentOAuthOptions],
+) -> GopherAgent:
+    server_config = ServerConfig.fetch(api_key, route=route)
+    resolved_runtime_options = _run_oauth_coroutine(
+        lambda: oauth_resolver.resolve_runtime_options_with_oauth(
+            urls=[],
+            server_config=server_config,
+            runtime_options=runtime_options,
+            oauth=oauth,
+        )
+    )
+    return GopherAgent._create_from_ffi(
+        lambda lib: lib.agent_create_by_json(
+            provider, model, server_config, resolved_runtime_options
+        )
+    )
+
+
+def _run_oauth_coroutine(create_coroutine):
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(create_coroutine())
+    raise AgentError(
+        "SDK OAuth auto-flow cannot run inside an active asyncio event loop. "
+        "Provide runtime_options with access_token/Authorization, or set "
+        'oauth.mode to "disabled".'
+    )
+
+
+def _should_skip_oauth(
+    runtime_options: Optional[GopherAgentRuntimeOptions],
+    oauth: Optional[GopherAgentOAuthOptions],
+) -> bool:
+    if oauth is not None and oauth.mode == "disabled":
+        return True
+    if runtime_options is None:
+        return False
+    if runtime_options.access_token is not None:
+        return True
+    return any(name.lower() == "authorization" for name in runtime_options.headers)
+
+
 def _build_create_error_message() -> str:
     """
     Build the AgentError message for a null native create*() result.
@@ -490,6 +630,6 @@ def _build_create_error_message() -> str:
         "Failed to create agent: native library returned null without a "
         "specific error. Most often this means every configured MCP server "
         "failed to connect or returned no tools (TLS / network / bad URL), "
-        "or the LLM provider could not be initialized. Set GOPHER_DEBUG=1 to "
-        "see native-side logs."
+        "or the LLM provider could not be initialized. Set DEBUG=1 to see "
+        "Python-side native library load diagnostics and native-side logs."
     )