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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gopher-mcp-python
-Version: 0.1.23
+Version: 0.1.30
 Summary: Python SDK for Gopher MCP - AI Agent orchestration framework with native performance
 Author-email: Gopher Security <dev@gophersecurity.com>
 License: Apache-2.0
@@ -59,8 +59,16 @@ Python SDK for gopher-mcp-python, providing AI agent orchestration with native C
 ## Requirements
 
 - Python 3.8 or higher
+- `venv` and `pip` for PyPI installation, examples, and development workflows
 - Native gopher-mcp-python library (built from source)
 
+On Debian/Ubuntu, install the Python venv and pip packages before using the
+PyPI install path, running examples, or setting up development dependencies:
+
+```bash
+sudo apt-get install python3 python3-venv python3-pip
+```
+
 ## Installation
 
 ### From Source
@@ -78,7 +86,7 @@ cd gopher-mcp-python
 
 3. Install the Python package:
 ```bash
-pip install -e .
+python3 -m pip install -e .
 ```
 
 ## Quick Start

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

@@ -15,8 +15,16 @@ Python SDK for gopher-mcp-python, providing AI agent orchestration with native C
 ## Requirements
 
 - Python 3.8 or higher
+- `venv` and `pip` for PyPI installation, examples, and development workflows
 - Native gopher-mcp-python library (built from source)
 
+On Debian/Ubuntu, install the Python venv and pip packages before using the
+PyPI install path, running examples, or setting up development dependencies:
+
+```bash
+sudo apt-get install python3 python3-venv python3-pip
+```
+
 ## Installation
 
 ### From Source
@@ -34,7 +42,7 @@ cd gopher-mcp-python
 
 3. Install the Python package:
 ```bash
-pip install -e .
+python3 -m pip install -e .
 ```
 
 ## Quick Start

gopher_mcp_python-0.1.30/gopher_mcp_python/__init__.py

@@ -0,0 +1,165 @@
+"""
+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 gopher_mcp_python.agent import GopherAgent
+from gopher_mcp_python.config import (
+    GopherAgentConfig,
+    GopherAgentConfigBuilder,
+    GopherAgentRuntimeOptions,
+)
+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
+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.30"
+
+__all__ = [
+    # Main classes
+    "GopherAgent",
+    "GopherAgentConfig",
+    "GopherAgentConfigBuilder",
+    "GopherAgentRuntimeOptions",
+    "AgentResult",
+    "AgentResultStatus",
+    "AgentResultBuilder",
+    "ServerConfig",
+    # Errors
+    "AgentError",
+    "ApiKeyError",
+    "ConnectionError",
+    "TimeoutError",
+    # FFI
+    "GopherOrchLibrary",
+    "GopherOrchHandle",
+    # Auth
+    "GopherAuthError",
+    "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",
+    "GopherAuth",
+    "GopherAuthBaseError",
+    "ConfigurationError",
+    "InsufficientScopesError",
+    "JwksError",
+    "TokenExchangeError",
+    "TokenValidationError",
+    "has_all_scopes",
+    "has_any_scope",
+    "has_scope",
+    # Version
+    "__version__",
+]

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

@@ -34,7 +34,6 @@ from gopher_mcp_python.result import AgentResult, AgentResultStatus
 from gopher_mcp_python.errors import AgentError, TimeoutError
 from gopher_mcp_python.ffi import GopherOrchLibrary, GopherOrchHandle
 
-
 _initialized = False
 _cleanup_handler_registered = False
 
@@ -78,7 +77,10 @@ class GopherAgent:
 
         lib = GopherOrchLibrary.get_instance()
         if lib is None:
-            raise AgentError("Failed to load gopher-mcp-python native library")
+            load_error = GopherOrchLibrary.get_load_error_message()
+            raise AgentError(
+                f"Failed to load gopher-mcp-python native library.\n{load_error}"
+            )
 
         _initialized = True
         _setup_cleanup_handler()
@@ -117,17 +119,24 @@ class GopherAgent:
 
         lib = GopherOrchLibrary.get_instance()
         if lib is None:
-            raise AgentError("Native library not available")
+            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.provider,
+                    config.model,
+                    config.api_key,
+                    config.runtime_options,
                 )
             else:
                 handle = lib.agent_create_by_json(
-                    config.provider, config.model, config.server_config
+                    config.provider,
+                    config.model,
+                    config.server_config,
+                    config.runtime_options,
                 )
         except Exception as e:
             raise AgentError(f"Failed to create agent: {e}")
@@ -135,12 +144,17 @@ class GopherAgent:
         if handle is None:
             error = lib.get_last_error_message()
             lib.clear_error()
-            raise AgentError(error or "Failed to create agent")
+            raise AgentError(error or _build_create_error_message())
 
         return GopherAgent(handle)
 
     @staticmethod
-    def create_with_api_key(provider: str, model: str, api_key: str) -> "GopherAgent":
+    def create_with_api_key(
+        provider: str,
+        model: str,
+        api_key: str,
+        runtime_options: Optional[object] = None,
+    ) -> "GopherAgent":
         """
         Create a new GopherAgent with API key.
 
@@ -148,21 +162,27 @@ class GopherAgent:
             provider: Provider name (e.g., "AnthropicProvider")
             model: Model name (e.g., "claude-3-haiku-20240307")
             api_key: API key for fetching remote server config
+            runtime_options: Dynamic MCP runtime headers/access token
 
         Returns:
             GopherAgent instance
         """
-        return GopherAgent.create(
+        builder = (
             GopherAgentConfig.builder()
             .provider(provider)
             .model(model)
             .api_key(api_key)
-            .build()
         )
+        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
+        provider: str,
+        model: str,
+        server_config: str,
+        runtime_options: Optional[object] = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent with JSON server config.
@@ -171,21 +191,28 @@ class GopherAgent:
             provider: Provider name (e.g., "AnthropicProvider")
             model: Model name (e.g., "claude-3-haiku-20240307")
             server_config: JSON server configuration
+            runtime_options: Dynamic MCP runtime headers/access token
 
         Returns:
             GopherAgent instance
         """
-        return GopherAgent.create(
+        builder = (
             GopherAgentConfig.builder()
             .provider(provider)
             .model(model)
             .server_config(server_config)
-            .build()
         )
+        if runtime_options is not None:
+            builder.runtime_options(runtime_options)
+        return GopherAgent.create(builder.build())
 
     @staticmethod
     def create_with_server_id(
-        provider: str, model: str, api_key: str, server_id: str
+        provider: str,
+        model: str,
+        api_key: str,
+        server_id: str,
+        runtime_options: Optional[object] = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP server by id.
@@ -199,19 +226,24 @@ class GopherAgent:
             model: Model identifier accepted by the chosen provider
             api_key: Gopher API key
             server_id: MCP server id to scope the agent to
+            runtime_options: Dynamic MCP runtime headers/access token
 
         Returns:
             GopherAgent instance
         """
         return GopherAgent._create_from_ffi(
             lambda lib: lib.agent_create_by_server_id(
-                provider, model, api_key, server_id
+                provider, model, api_key, server_id, runtime_options
             )
         )
 
     @staticmethod
     def create_with_server_name(
-        provider: str, model: str, api_key: str, server_name: str
+        provider: str,
+        model: str,
+        api_key: str,
+        server_name: str,
+        runtime_options: Optional[object] = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP server by name.
@@ -225,19 +257,24 @@ class GopherAgent:
             model: Model identifier accepted by the chosen provider
             api_key: Gopher API key
             server_name: MCP server name to scope the agent to
+            runtime_options: Dynamic MCP runtime headers/access token
 
         Returns:
             GopherAgent instance
         """
         return GopherAgent._create_from_ffi(
             lambda lib: lib.agent_create_by_server_name(
-                provider, model, api_key, server_name
+                provider, model, api_key, server_name, runtime_options
             )
         )
 
     @staticmethod
     def create_with_gateway_id(
-        provider: str, model: str, api_key: str, gateway_id: str
+        provider: str,
+        model: str,
+        api_key: str,
+        gateway_id: str,
+        runtime_options: Optional[object] = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP gateway by id.
@@ -251,19 +288,24 @@ class GopherAgent:
             model: Model identifier accepted by the chosen provider
             api_key: Gopher API key
             gateway_id: MCP gateway id to scope the agent to
+            runtime_options: Dynamic MCP runtime headers/access token
 
         Returns:
             GopherAgent instance
         """
         return GopherAgent._create_from_ffi(
             lambda lib: lib.agent_create_by_gateway_id(
-                provider, model, api_key, gateway_id
+                provider, model, api_key, gateway_id, runtime_options
             )
         )
 
     @staticmethod
     def create_with_gateway_name(
-        provider: str, model: str, api_key: str, gateway_name: str
+        provider: str,
+        model: str,
+        api_key: str,
+        gateway_name: str,
+        runtime_options: Optional[object] = None,
     ) -> "GopherAgent":
         """
         Create a new GopherAgent scoped to a single MCP gateway by name.
@@ -277,18 +319,24 @@ class GopherAgent:
             model: Model identifier accepted by the chosen provider
             api_key: Gopher API key
             gateway_name: MCP gateway name to scope the agent to
+            runtime_options: Dynamic MCP runtime headers/access token
 
         Returns:
             GopherAgent instance
         """
         return GopherAgent._create_from_ffi(
             lambda lib: lib.agent_create_by_gateway_name(
-                provider, model, api_key, gateway_name
+                provider, model, api_key, gateway_name, runtime_options
             )
         )
 
     @staticmethod
-    def create_with_url(provider: str, model: str, url: str) -> "GopherAgent":
+    def create_with_url(
+        provider: str,
+        model: str,
+        url: str,
+        runtime_options: Optional[object] = None,
+    ) -> "GopherAgent":
         """
         Create a new GopherAgent for a single MCP server reachable at a URL.
 
@@ -301,12 +349,13 @@ class GopherAgent:
             provider: Provider name (e.g., "AnthropicProvider")
             model: Model identifier accepted by the chosen provider
             url: Full URL of the MCP server (e.g., "http://127.0.0.1:8080/mcp")
+            runtime_options: Dynamic MCP runtime headers/access token
 
         Returns:
             GopherAgent instance
         """
         return GopherAgent._create_from_ffi(
-            lambda lib: lib.agent_create_by_url(provider, model, url)
+            lambda lib: lib.agent_create_by_url(provider, model, url, runtime_options)
         )
 
     @staticmethod
@@ -325,7 +374,8 @@ class GopherAgent:
 
         lib = GopherOrchLibrary.get_instance()
         if lib is None:
-            raise AgentError("Native library not available")
+            load_error = GopherOrchLibrary.get_load_error_message()
+            raise AgentError(f"Native library not available.\n{load_error}")
 
         try:
             handle = create_handle(lib)
@@ -335,7 +385,7 @@ class GopherAgent:
         if handle is None:
             error = lib.get_last_error_message()
             lib.clear_error()
-            raise AgentError(error or "Failed to create agent")
+            raise AgentError(error or _build_create_error_message())
 
         return GopherAgent(handle)
 
@@ -357,13 +407,18 @@ class GopherAgent:
 
         lib = GopherOrchLibrary.get_instance()
         if lib is None:
-            raise AgentError("Native library not available")
+            load_error = GopherOrchLibrary.get_load_error_message()
+            raise AgentError(f"Native library not available.\n{load_error}")
 
         try:
             response = lib.agent_run(self._handle, query, timeout_ms)
             if response is None:
-                return f'No response for query: "{query}"'
+                error = lib.get_last_error_message()
+                lib.clear_error()
+                raise AgentError(error or f'No response for query: "{query}"')
             return response
+        except AgentError:
+            raise
         except Exception as e:
             raise AgentError(f"Query execution failed: {e}")
 
@@ -421,3 +476,20 @@ def _setup_cleanup_handler() -> None:
 
     _cleanup_handler_registered = True
     atexit.register(GopherAgent.shutdown)
+
+
+def _build_create_error_message() -> str:
+    """
+    Build the AgentError message for a null native create*() result.
+
+    Native should usually populate gopher_orch_last_error, but a few
+    defensive paths can still return null without details. Keep that
+    fallback actionable instead of raising only "Failed to create agent".
+    """
+    return (
+        "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."
+    )

gopher_mcp_python-0.1.30/gopher_mcp_python/auth/__init__.py

@@ -0,0 +1,83 @@
+"""
+Auth Module - Reusable OAuth/JWT authentication for Python MCP servers.
+"""
+
+from gopher_mcp_python.auth.gopher_auth import GopherAuth
+from gopher_mcp_python.auth.errors import (
+    GopherAuthError,
+    TokenValidationError,
+    InsufficientScopesError,
+    JwksError,
+    ConfigurationError,
+    TokenExchangeError,
+)
+from gopher_mcp_python.auth.scope_helpers import (
+    has_scope,
+    has_all_scopes,
+    has_any_scope,
+)
+from gopher_mcp_python.ffi.auth import (
+    AutoRefreshResult,
+    GopherAuthClient,
+    GopherAuthConfig,
+    GopherOAuthClient,
+    GopherSessionManager,
+    GopherValidationOptions,
+    RegistrationResponse,
+    TokenPayload,
+    TokenResponse,
+    ValidationResult,
+    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,
+)
+
+__all__ = [
+    "GopherAuth",
+    "GopherAuthError",
+    "TokenValidationError",
+    "InsufficientScopesError",
+    "JwksError",
+    "ConfigurationError",
+    "TokenExchangeError",
+    "has_scope",
+    "has_all_scopes",
+    "has_any_scope",
+    "AutoRefreshResult",
+    "GopherAuthClient",
+    "GopherAuthConfig",
+    "GopherOAuthClient",
+    "GopherSessionManager",
+    "GopherValidationOptions",
+    "RegistrationResponse",
+    "TokenPayload",
+    "TokenResponse",
+    "ValidationResult",
+    "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",
+]