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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gopher-mcp-python
-Version: 0.1.30
+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
@@ -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:
@@ -216,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
@@ -231,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.30 → gopher_mcp_python-0.1.38}/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:
@@ -172,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
@@ -187,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.38/gopher_mcp_python/__init__.py

@@ -0,0 +1,209 @@
+"""
+Gopher Orch Python SDK - AI Agent orchestration framework with native performance.
+
+This module provides Python bindings to the gopher-mcp-python native library through ctypes FFI.
+
+Example:
+    >>> from gopher_mcp_python import GopherAgent, GopherAgentConfig
+    >>>
+    >>> # Create an agent with API key
+    >>> config = (GopherAgentConfig.builder()
+    ...     .provider("AnthropicProvider")
+    ...     .model("claude-3-haiku-20240307")
+    ...     .api_key("your-api-key")
+    ...     .build())
+    >>> agent = GopherAgent.create(config)
+    >>>
+    >>> # Run a query
+    >>> answer = agent.run("What time is it in Tokyo?")
+    >>> print(answer)
+    >>>
+    >>> # Cleanup
+    >>> 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.elicitation import (
+    GopherAgentElicitationAction,
+    GopherAgentElicitationHandler,
+    GopherAgentElicitationOptions,
+    GopherAgentElicitationRequest,
+    GopherAgentElicitationResponse,
+)
+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 (
+    AgentError,
+    ApiKeyError,
+    ConnectionError,
+    TimeoutError,
+)
+from gopher_mcp_python.server_config import ServerConfig, ServerConfigRoute
+from gopher_mcp_python.ffi import GopherOrchLibrary, GopherOrchHandle
+
+__version__ = "0.1.38"
+
+_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}")
+
+
+__all__ = [
+    # Main classes
+    "GopherAgent",
+    "GopherAgentConfig",
+    "GopherAgentConfigBuilder",
+    "GopherAgentCreateOptions",
+    "GopherAgentElicitationAction",
+    "GopherAgentElicitationHandler",
+    "GopherAgentElicitationOptions",
+    "GopherAgentElicitationRequest",
+    "GopherAgentElicitationResponse",
+    "GopherAgentOAuthOptions",
+    "GopherAgentRuntimeOptions",
+    "GopherAgentTokenRecord",
+    "GopherAgentTokenStore",
+    "AgentResult",
+    "AgentResultStatus",
+    "AgentResultBuilder",
+    "ServerConfig",
+    "ServerConfigRoute",
+    # Errors
+    "AgentError",
+    "ApiKeyError",
+    "ConnectionError",
+    "TimeoutError",
+    # FFI
+    "GopherOrchLibrary",
+    "GopherOrchHandle",
+    # Auth
+    "GopherAuth",
+    "GopherAuthError",
+    "GopherAuthFfiError",
+    "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",
+    "ConfigurationError",
+    "InsufficientScopesError",
+    "JwksError",
+    "TokenExchangeError",
+    "TokenValidationError",
+    "has_all_scopes",
+    "has_any_scope",
+    "has_scope",
+    # Version
+    "__version__",
+]