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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gopher-mcp-python
-Version: 0.1.16
+Version: 0.1.23
 Summary: Python SDK for Gopher MCP - AI Agent orchestration framework with native performance
 Author-email: Gopher Security <dev@gophersecurity.com>
 License: Apache-2.0

{gopher_mcp_python-0.1.16 → gopher_mcp_python-0.1.23}/gopher_mcp_python/__init__.py

@@ -32,7 +32,7 @@ from gopher_mcp_python.errors import (
     TimeoutError,
 )
 from gopher_mcp_python.server_config import ServerConfig
-from gopher_mcp_python.ffi import GopherOrchLibrary
+from gopher_mcp_python.ffi import GopherOrchLibrary, GopherOrchHandle
 
 # Auth module re-exports
 from gopher_mcp_python.ffi.auth import (
@@ -50,7 +50,7 @@ from gopher_mcp_python.ffi.auth import (
     is_auth_available,
 )
 
-__version__ = "0.1.16"
+__version__ = "0.1.23"
 
 __all__ = [
     # Main classes
@@ -68,6 +68,7 @@ __all__ = [
     "TimeoutError",
     # FFI
     "GopherOrchLibrary",
+    "GopherOrchHandle",
     # Auth
     "GopherAuthError",
     "ValidationResult",

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

@@ -27,7 +27,7 @@ Example with context manager:
 """
 
 import atexit
-from typing import Optional
+from typing import Callable, Optional
 
 from gopher_mcp_python.config import GopherAgentConfig
 from gopher_mcp_python.result import AgentResult, AgentResultStatus
@@ -183,6 +183,162 @@ class GopherAgent:
             .build()
         )
 
+    @staticmethod
+    def create_with_server_id(
+        provider: str, model: str, api_key: str, server_id: str
+    ) -> "GopherAgent":
+        """
+        Create a new GopherAgent scoped to a single MCP server by id.
+
+        Fetches server config from the Gopher API using the Bearer api key,
+        appending "?serverId={server_id}" so the response carries only the
+        matching MCP server entry.
+
+        Args:
+            provider: Provider name (e.g., "AnthropicProvider")
+            model: Model identifier accepted by the chosen provider
+            api_key: Gopher API key
+            server_id: MCP server id to scope the agent to
+
+        Returns:
+            GopherAgent instance
+        """
+        return GopherAgent._create_from_ffi(
+            lambda lib: lib.agent_create_by_server_id(
+                provider, model, api_key, server_id
+            )
+        )
+
+    @staticmethod
+    def create_with_server_name(
+        provider: str, model: str, api_key: str, server_name: str
+    ) -> "GopherAgent":
+        """
+        Create a new GopherAgent scoped to a single MCP server by name.
+
+        Fetches server config from the Gopher API using the Bearer api key,
+        appending "?serverName={server_name}" so the response carries only
+        the matching MCP server entry.
+
+        Args:
+            provider: Provider name (e.g., "AnthropicProvider")
+            model: Model identifier accepted by the chosen provider
+            api_key: Gopher API key
+            server_name: MCP server name to scope the agent to
+
+        Returns:
+            GopherAgent instance
+        """
+        return GopherAgent._create_from_ffi(
+            lambda lib: lib.agent_create_by_server_name(
+                provider, model, api_key, server_name
+            )
+        )
+
+    @staticmethod
+    def create_with_gateway_id(
+        provider: str, model: str, api_key: str, gateway_id: str
+    ) -> "GopherAgent":
+        """
+        Create a new GopherAgent scoped to a single MCP gateway by id.
+
+        Fetches server config from the Gopher API using the Bearer api key,
+        appending "?gatewayId={gateway_id}" so the response carries the
+        backing MCP servers for that gateway.
+
+        Args:
+            provider: Provider name (e.g., "AnthropicProvider")
+            model: Model identifier accepted by the chosen provider
+            api_key: Gopher API key
+            gateway_id: MCP gateway id to scope the agent to
+
+        Returns:
+            GopherAgent instance
+        """
+        return GopherAgent._create_from_ffi(
+            lambda lib: lib.agent_create_by_gateway_id(
+                provider, model, api_key, gateway_id
+            )
+        )
+
+    @staticmethod
+    def create_with_gateway_name(
+        provider: str, model: str, api_key: str, gateway_name: str
+    ) -> "GopherAgent":
+        """
+        Create a new GopherAgent scoped to a single MCP gateway by name.
+
+        Fetches server config from the Gopher API using the Bearer api key,
+        appending "?gatewayName={gateway_name}" so the response carries the
+        backing MCP servers for that gateway.
+
+        Args:
+            provider: Provider name (e.g., "AnthropicProvider")
+            model: Model identifier accepted by the chosen provider
+            api_key: Gopher API key
+            gateway_name: MCP gateway name to scope the agent to
+
+        Returns:
+            GopherAgent instance
+        """
+        return GopherAgent._create_from_ffi(
+            lambda lib: lib.agent_create_by_gateway_name(
+                provider, model, api_key, gateway_name
+            )
+        )
+
+    @staticmethod
+    def create_with_url(provider: str, model: str, url: str) -> "GopherAgent":
+        """
+        Create a new GopherAgent for a single MCP server reachable at a URL.
+
+        Skips the remote config fetch entirely: synthesises an http_sse
+        server entry around the URL and delegates to create_by_json on the
+        native side. Useful for local development or one-off endpoints where
+        the operator already knows the URL.
+
+        Args:
+            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")
+
+        Returns:
+            GopherAgent instance
+        """
+        return GopherAgent._create_from_ffi(
+            lambda lib: lib.agent_create_by_url(provider, model, url)
+        )
+
+    @staticmethod
+    def _create_from_ffi(
+        create_handle: Callable[[GopherOrchLibrary], Optional[GopherOrchHandle]],
+    ) -> "GopherAgent":
+        """
+        Shared handle-creation pump for factories that bypass GopherAgentConfig.
+
+        Ensures the native library is initialised, invokes the supplied FFI
+        callable, and translates a null handle return into AgentError using
+        the same last_error / clear_error contract as create().
+        """
+        if not _initialized:
+            GopherAgent.init()
+
+        lib = GopherOrchLibrary.get_instance()
+        if lib is None:
+            raise AgentError("Native library not available")
+
+        try:
+            handle = create_handle(lib)
+        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 "Failed to create agent")
+
+        return GopherAgent(handle)
+
     def run(self, query: str, timeout_ms: int = 60000) -> str:
         """
         Run a query against the agent.

{gopher_mcp_python-0.1.16 → gopher_mcp_python-0.1.23}/gopher_mcp_python/config.py

@@ -9,10 +9,20 @@ from typing import Optional
 
 class GopherAgentConfig:
     """
-    Immutable configuration for GopherAgent.
+    Immutable configuration for GopherAgent created via GopherAgent.create().
 
     Use the builder() method to create configurations.
 
+    The builder accepts only the api_key / server_config XOR that maps to
+    the original gopher_orch_agent_create_by_api_key and
+    gopher_orch_agent_create_by_json C entry points. The five newer routing
+    factories (GopherAgent.create_with_server_id, create_with_server_name,
+    create_with_gateway_id, create_with_gateway_name, create_with_url) take
+    additional inputs (server / gateway identifier, or URL) that do not fit
+    that XOR shape and deliberately bypass this builder; they are exposed
+    as static methods on GopherAgent and dispatch into GopherOrchLibrary
+    directly via GopherAgent._create_from_ffi.
+
     Example:
         >>> config = (GopherAgentConfig.builder()
         ...     .provider("AnthropicProvider")

{gopher_mcp_python-0.1.16 → gopher_mcp_python-0.1.23}/gopher_mcp_python/ffi/library.py

@@ -134,6 +134,54 @@ class GopherOrchLibrary:
         ]
         self._lib.gopher_orch_agent_create_by_api_key.restype = c_void_p
 
+        # Routing factories: scope the agent to a single MCP server or gateway
+        # selected by id / name, or to a known MCP URL. These C symbols landed
+        # in gopher-orch 0.1.23 -- wrapped in try / except so the SDK still
+        # loads against an older libgopher-orch, with the higher-level
+        # factories raising AgentError at call time if the symbol is missing.
+        try:
+            self._lib.gopher_orch_agent_create_by_server_id.argtypes = [
+                c_char_p,
+                c_char_p,
+                c_char_p,
+                c_char_p,
+            ]
+            self._lib.gopher_orch_agent_create_by_server_id.restype = c_void_p
+
+            self._lib.gopher_orch_agent_create_by_server_name.argtypes = [
+                c_char_p,
+                c_char_p,
+                c_char_p,
+                c_char_p,
+            ]
+            self._lib.gopher_orch_agent_create_by_server_name.restype = c_void_p
+
+            self._lib.gopher_orch_agent_create_by_gateway_id.argtypes = [
+                c_char_p,
+                c_char_p,
+                c_char_p,
+                c_char_p,
+            ]
+            self._lib.gopher_orch_agent_create_by_gateway_id.restype = c_void_p
+
+            self._lib.gopher_orch_agent_create_by_gateway_name.argtypes = [
+                c_char_p,
+                c_char_p,
+                c_char_p,
+                c_char_p,
+            ]
+            self._lib.gopher_orch_agent_create_by_gateway_name.restype = c_void_p
+
+            self._lib.gopher_orch_agent_create_by_url.argtypes = [
+                c_char_p,
+                c_char_p,
+                c_char_p,
+            ]
+            self._lib.gopher_orch_agent_create_by_url.restype = c_void_p
+        except AttributeError:
+            # Older libgopher-orch builds (< 0.1.23) lack these symbols.
+            pass
+
         self._lib.gopher_orch_agent_run.argtypes = [c_void_p, c_char_p, c_int64]
         self._lib.gopher_orch_agent_run.restype = c_char_p
 
@@ -287,6 +335,106 @@ class GopherOrchLibrary:
             api_key.encode("utf-8"),
         )
 
+    def agent_create_by_server_id(
+        self, provider: str, model: str, api_key: str, server_id: str
+    ) -> Optional[GopherOrchHandle]:
+        """Create an agent scoped to a single MCP server by id.
+
+        The native side fetches server config from the Gopher API using the
+        Bearer api key, appending "?serverId={server_id}" so the response
+        carries only the matching MCP server entry.
+        """
+        if not self._available or self._lib is None:
+            return None
+        fn = getattr(self._lib, "gopher_orch_agent_create_by_server_id", None)
+        if fn is None:
+            return None
+        return fn(
+            provider.encode("utf-8"),
+            model.encode("utf-8"),
+            api_key.encode("utf-8"),
+            server_id.encode("utf-8"),
+        )
+
+    def agent_create_by_server_name(
+        self, provider: str, model: str, api_key: str, server_name: str
+    ) -> Optional[GopherOrchHandle]:
+        """Create an agent scoped to a single MCP server by name.
+
+        Mirrors agent_create_by_server_id but routes via "?serverName=".
+        """
+        if not self._available or self._lib is None:
+            return None
+        fn = getattr(self._lib, "gopher_orch_agent_create_by_server_name", None)
+        if fn is None:
+            return None
+        return fn(
+            provider.encode("utf-8"),
+            model.encode("utf-8"),
+            api_key.encode("utf-8"),
+            server_name.encode("utf-8"),
+        )
+
+    def agent_create_by_gateway_id(
+        self, provider: str, model: str, api_key: str, gateway_id: str
+    ) -> Optional[GopherOrchHandle]:
+        """Create an agent scoped to a single MCP gateway by id.
+
+        The native side appends "?gatewayId={gateway_id}" to the Gopher API
+        fetch so the response carries the backing MCP servers for that
+        gateway.
+        """
+        if not self._available or self._lib is None:
+            return None
+        fn = getattr(self._lib, "gopher_orch_agent_create_by_gateway_id", None)
+        if fn is None:
+            return None
+        return fn(
+            provider.encode("utf-8"),
+            model.encode("utf-8"),
+            api_key.encode("utf-8"),
+            gateway_id.encode("utf-8"),
+        )
+
+    def agent_create_by_gateway_name(
+        self, provider: str, model: str, api_key: str, gateway_name: str
+    ) -> Optional[GopherOrchHandle]:
+        """Create an agent scoped to a single MCP gateway by name.
+
+        Mirrors agent_create_by_gateway_id but routes via "?gatewayName=".
+        """
+        if not self._available or self._lib is None:
+            return None
+        fn = getattr(self._lib, "gopher_orch_agent_create_by_gateway_name", None)
+        if fn is None:
+            return None
+        return fn(
+            provider.encode("utf-8"),
+            model.encode("utf-8"),
+            api_key.encode("utf-8"),
+            gateway_name.encode("utf-8"),
+        )
+
+    def agent_create_by_url(
+        self, provider: str, model: str, url: str
+    ) -> Optional[GopherOrchHandle]:
+        """Create an agent for a single MCP server reachable at a URL.
+
+        Skips the remote config fetch: the native side synthesises an
+        http_sse server entry around the URL. Useful for local development
+        or one-off endpoints where the operator already knows the URL.
+        """
+        if not self._available or self._lib is None:
+            return None
+        fn = getattr(self._lib, "gopher_orch_agent_create_by_url", None)
+        if fn is None:
+            return None
+        return fn(
+            provider.encode("utf-8"),
+            model.encode("utf-8"),
+            url.encode("utf-8"),
+        )
+
     def agent_run(
         self, agent: GopherOrchHandle, query: str, timeout_ms: int
     ) -> Optional[str]:

{gopher_mcp_python-0.1.16 → gopher_mcp_python-0.1.23}/gopher_mcp_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gopher-mcp-python
-Version: 0.1.16
+Version: 0.1.23
 Summary: Python SDK for Gopher MCP - AI Agent orchestration framework with native performance
 Author-email: Gopher Security <dev@gophersecurity.com>
 License: Apache-2.0

{gopher_mcp_python-0.1.16 → gopher_mcp_python-0.1.23}/gopher_mcp_python.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ gopher_mcp_python/ffi/auth/oauth_client.py
 gopher_mcp_python/ffi/auth/session_manager.py
 gopher_mcp_python/ffi/auth/types.py
 gopher_mcp_python/ffi/auth/validation_options.py
+tests/test_agent_create_by.py
 tests/test_config.py
 tests/test_ffi.py
 tests/test_gopher_auth.py

{gopher_mcp_python-0.1.16 → gopher_mcp_python-0.1.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gopher-mcp-python"
-version = "0.1.16"
+version = "0.1.23"
 description = "Python SDK for Gopher MCP - AI Agent orchestration framework with native performance"
 readme = "README.md"
 license = {text = "Apache-2.0"}

gopher_mcp_python-0.1.23/tests/test_agent_create_by.py

@@ -0,0 +1,90 @@
+"""
+Contract tests for the five routing factories on GopherAgent.
+
+Mirrors the failure-path test set in
+gopher-orch/tests/gopher/orch/agent_create_by_test.cc which locks down
+the nullptr-on-failure contract that the C FFI surfaces here as
+AgentError. Happy-path coverage needs a stubbed HTTP listener capturing
+the /v1/mcp-servers query string with the camelCase routing keys
+(serverId / serverName / gatewayId / gatewayName); that infrastructure
+is tracked separately, same as on the C++ side.
+"""
+
+import pytest
+
+from gopher_mcp_python import AgentError, GopherAgent
+from gopher_mcp_python.ffi import GopherOrchLibrary
+
+PROVIDER = "AnthropicProvider"
+MODEL = "test-model"
+BAD_PROVIDER = "NotARealProvider"
+URL = "http://127.0.0.1:8080/mcp"
+
+
+pytestmark = pytest.mark.skipif(
+    not GopherOrchLibrary.is_available(),
+    reason="Native library not available -- run ./build.sh first",
+)
+
+
+class TestRoutingFactoryContracts:
+    """Failure-path contract for the five routing factories on GopherAgent."""
+
+    # ----------------------------------------------------------------
+    # Empty api key. fetch_mcp_servers throws on the native side; the
+    # factory must surface that as AgentError rather than returning a
+    # partially-constructed agent or a null handle leaking through.
+    # ----------------------------------------------------------------
+
+    def test_create_with_server_id_rejects_empty_api_key(self) -> None:
+        with pytest.raises(AgentError):
+            GopherAgent.create_with_server_id(PROVIDER, MODEL, "", "srv-1")
+
+    def test_create_with_server_name_rejects_empty_api_key(self) -> None:
+        with pytest.raises(AgentError):
+            GopherAgent.create_with_server_name(
+                PROVIDER, MODEL, "", "my-server"
+            )
+
+    def test_create_with_gateway_id_rejects_empty_api_key(self) -> None:
+        with pytest.raises(AgentError):
+            GopherAgent.create_with_gateway_id(PROVIDER, MODEL, "", "gw-1")
+
+    def test_create_with_gateway_name_rejects_empty_api_key(self) -> None:
+        with pytest.raises(AgentError):
+            GopherAgent.create_with_gateway_name(
+                PROVIDER, MODEL, "", "my-gateway"
+            )
+
+    # ----------------------------------------------------------------
+    # create_with_url rejects empty url before any FFI work happens.
+    # Mirrors the CreateByUrlRejectsEmptyUrl case in the C++ suite.
+    # ----------------------------------------------------------------
+
+    def test_create_with_url_rejects_empty_url(self) -> None:
+        with pytest.raises(AgentError):
+            GopherAgent.create_with_url(PROVIDER, MODEL, "")
+
+    # ----------------------------------------------------------------
+    # Unknown provider. create_with_url synthesises a local http_sse
+    # config and reaches create_by_json on the native side, which
+    # rejects an unknown provider name. The factory must surface that
+    # as AgentError.
+    # ----------------------------------------------------------------
+
+    def test_create_with_url_rejects_unknown_provider(self) -> None:
+        with pytest.raises(AgentError):
+            GopherAgent.create_with_url(BAD_PROVIDER, MODEL, URL)
+
+    # ----------------------------------------------------------------
+    # AgentError surfaces a non-empty message so SDK consumers can log
+    # a meaningful diagnostic; the C side fills last_error() and the
+    # wrapper pump should propagate it through. A future change to the
+    # error pump that swallows the underlying C diagnostic gets caught
+    # here immediately.
+    # ----------------------------------------------------------------
+
+    def test_create_with_server_id_surfaces_non_empty_message(self) -> None:
+        with pytest.raises(AgentError) as exc_info:
+            GopherAgent.create_with_server_id(PROVIDER, MODEL, "", "srv-1")
+        assert len(str(exc_info.value)) > 0