xpander-sdk 2.0.403__tar.gz → 2.0.404__tar.gz

{xpander_sdk-2.0.403/src/xpander_sdk.egg-info → xpander_sdk-2.0.404}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.403
+Version: 2.0.404
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.403 → xpander_sdk-2.0.404}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.403",
+    version="2.0.404",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

{xpander_sdk-2.0.403 → xpander_sdk-2.0.404}/src/xpander_sdk/__init__.py

@@ -15,7 +15,7 @@ Main Components:
 For more information, visit: https://xpander.ai
 """
 
-__version__ = "2.0.403"
+__version__ = "2.0.404"
 
 # Backend-related imports
 from .modules.backend.backend_module import Backend

{xpander_sdk-2.0.403 → xpander_sdk-2.0.404}/src/xpander_sdk/modules/backend/frameworks/agno.py

@@ -105,6 +105,9 @@ from xpander_sdk.modules.tools_repository.models.mcp import (
 from xpander_sdk.modules.tools_repository.models.tool_invocation_result import (
     ToolInvocationResult,
 )
+from xpander_sdk.modules.tools_repository.sub_modules.mcp_tool_proxy import (
+    build_mcp_proxies,
+)
 from xpander_sdk.modules.tools_repository.sub_modules.tool import Tool
 from xpander_sdk.modules.tools_repository.utils.schemas import build_model_from_schema
 from xpander_sdk.modules.tools_repository.utils.workspace_payload import (
@@ -909,6 +912,13 @@ async def build_agent_args(
     )
     args["tools"] = resolved_tools
 
+    # Dynamic mode: MCP toolkits are SDK-owned (kept out of args["tools"] so the LLM
+    # never sees them). Surface them here so the worker closes their sessions post-run
+    # — the agno-owned close path only iterates args["tools"].
+    args["_xpander_hidden_mcp_toolkits"] = list(
+        getattr(xpander_agent.tools, "_dynamic_mcp_toolkits", []) or []
+    )
+
     # Tell the agent about any MCP tools skipped this run (no user / unreachable) so it
     # can explain the missing capability to the user instead of silently lacking it.
     if _skipped_mcp_notes:
@@ -1000,6 +1010,14 @@ async def build_agent_args(
         if members and len(members) != 0:
             for member in members:
                 member["model"] = model
+                # A member's SDK-owned MCP toolkits (dynamic mode) must be hoisted to
+                # the top-level args so the worker closes them, and the key removed
+                # before AgnoAgent/AgnoTeam(**member) — their __init__ rejects it.
+                member_hidden = member.pop("_xpander_hidden_mcp_toolkits", None)
+                if member_hidden:
+                    args.setdefault("_xpander_hidden_mcp_toolkits", []).extend(
+                        member_hidden
+                    )
 
         args.update(
             {
@@ -3290,6 +3308,17 @@ async def _resolve_agent_tools(
     # Skipped-MCP notes surfaced to the agent (so it can tell the user a capability
     # is unavailable) — caller passes a list to receive them; else collect locally.
     notes = skipped_notes if skipped_notes is not None else []
+
+    # Dynamic mode collapses MCP tools into the same meta-tool disclosure as the
+    # xpander catalog: the SDK connects each server here, hides its tools from the
+    # LLM, and exposes them via xp_search/get/execute. Per-run reset because the
+    # repo can be reused across tasks in a long-lived worker.
+    use_dynamic = bool(getattr(agent, "use_dynamic_tools", False))
+    if use_dynamic:
+        agent.tools._dynamic_mcp_proxies.clear()
+        agent.tools._dynamic_mcp_toolkits.clear()
+        agent.tools._dynamic_inspected.clear()
+
     mcp_servers = agent.mcp_servers
 
     # combine task mcps and agent mcps
@@ -3314,6 +3343,51 @@ async def _resolve_agent_tools(
 
     is_xpander_cloud = getenv("IS_XPANDER_CLOUD", "false") == "true"
 
+    async def _finalize_toolkit(
+        toolkit: MCPTools, server_name: str, server_url: Optional[str] = None
+    ) -> Optional[MCPTools]:
+        """Non-dynamic: return the toolkit for agno to own (today's behavior).
+        Dynamic: connect + enumerate now, register proxies, keep the toolkit out of
+        the agent's tools (hidden from the LLM), and return None. The SDK owns the
+        session; the worker closes it post-run."""
+        if not use_dynamic:
+            return toolkit
+        try:
+            await toolkit.connect()
+        except (Exception, BaseException) as exc:
+            logger.warning(
+                f"[dynamic-mcp] connect failed for '{server_name}': "
+                f"{type(exc).__name__}: {exc}"
+            )
+            try:
+                await toolkit.close()
+            except (Exception, BaseException):
+                pass
+            notes.append(
+                f"{server_name}: temporarily unavailable (could not connect this run)."
+            )
+            return None
+        if not getattr(toolkit, "initialized", False) or not toolkit.functions:
+            try:
+                await toolkit.close()
+            except (Exception, BaseException):
+                pass
+            if not getattr(toolkit, "initialized", False):
+                notes.append(
+                    f"{server_name}: temporarily unavailable (could not connect this run)."
+                )
+            return None
+        proxies = build_mcp_proxies(
+            toolkit, server_name=server_name, server_url=server_url
+        )
+        agent.tools._dynamic_mcp_proxies.extend(proxies)
+        agent.tools._dynamic_mcp_toolkits.append(toolkit)
+        logger.info(
+            f"[dynamic-mcp] collapsed {len(proxies)} tools from '{server_name}' "
+            f"behind the dynamic meta-tools"
+        )
+        return None
+
     # Build one MCPTools per server. Remote servers each run a preflight probe
     # (~100-800ms); gathering them concurrently makes the wall-time the slowest
     # probe instead of their sum. Returns None for servers we deliberately skip.
@@ -3332,7 +3406,7 @@ async def _resolve_agent_tools(
                 return None
 
             command_parts = shlex.split(mcp.command)
-            return (
+            return await _finalize_toolkit(
                 MCPTools(
                     transport=transport,
                     server_params=StdioServerParameters(
@@ -3343,7 +3417,9 @@ async def _resolve_agent_tools(
                     include_tools=mcp.allowed_tools or None,
                     timeout_seconds=120,
                     tool_name_prefix="mcp_tool",
-                )
+                ),
+                mcp.name or mcp.command,
+                None,
             )
         elif mcp.url:
             params_cls = (
@@ -3489,7 +3565,7 @@ async def _resolve_agent_tools(
                 )
                 return None
 
-            return (
+            return await _finalize_toolkit(
                 MCPTools(
                     transport=transport,
                     server_params=params_cls(
@@ -3501,7 +3577,9 @@ async def _resolve_agent_tools(
                     include_tools=mcp.allowed_tools or None,
                     timeout_seconds=120,
                     tool_name_prefix="mcp_tool",
-                )
+                ),
+                mcp.name or mcp.url,
+                mcp.url,
             )
 
         return None

{xpander_sdk-2.0.403 → xpander_sdk-2.0.404}/src/xpander_sdk/modules/tools_repository/sub_modules/dynamic_tools.py

@@ -24,6 +24,7 @@ hints and concrete examples.
 
 import json
 import re
+import uuid
 from inspect import Parameter, Signature
 from typing import Any, Callable, Dict, List
 
@@ -68,6 +69,11 @@ META_TOOL_NAMES = (
 
 def is_always_loaded(tool: Any) -> bool:
     """Return True if the tool must stay fully loaded (never hidden)."""
+    # MCP proxies carry an "mcp_tool_*" id but ARE the thing we hide behind the
+    # meta-tools, so they must never count as always-loaded (unlike repo.list
+    # tools whose "mcp"/"xp" prefix genuinely means always-loaded).
+    if getattr(tool, "is_mcp_proxy", False):
+        return False
     tid = tool.id or ""
     tname = tool.name or ""
     return tid.startswith(DYNAMIC_TOOL_PREFIXES) or tname.startswith(
@@ -134,6 +140,21 @@ def _xml_escape_text(text: str) -> str:
     return (text or "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
 
 
+def _mcp_attrs(tool: Any) -> str:
+    """XML attributes naming an MCP proxy's source server (server + url), so the
+    model knows which MCP server a tool comes from. Empty for xpander tools."""
+    if not getattr(tool, "is_mcp_proxy", False):
+        return ""
+    parts = []
+    server_name = getattr(tool, "server_name", None)
+    server_url = getattr(tool, "server_url", None)
+    if server_name:
+        parts.append(f' server="{_xml_escape(str(server_name))}"')
+    if server_url:
+        parts.append(f' url="{_xml_escape(str(server_url))}"')
+    return "".join(parts)
+
+
 def _truncate(text: str, limit: int = TRUNCATED_DESC_LEN) -> str:
     collapsed = " ".join((text or "").split())
     if len(collapsed) <= limit:
@@ -202,11 +223,16 @@ def render_tool(tool: Any, full_schema: bool = False) -> str:
     display name."""
     name = _xml_escape(tool.id)
     desc = _truncate(tool.description or tool.name or tool.id, limit=300)
-    parts = [f'<tool name="{name}">', f"  <desc>{desc}</desc>"]
+    parts = [f'<tool name="{name}"{_mcp_attrs(tool)}>', f"  <desc>{desc}</desc>"]
 
     if full_schema:
         try:
-            schema_json = cached_tool_json_schema(tool.schema, "serialization")
+            if getattr(tool, "is_mcp_proxy", False):
+                # MCP tools carry a raw JSON-schema dict (no pydantic class) and
+                # take FLAT args — the example falls out of the raw inputSchema.
+                schema_json = tool.raw_json_schema or {"type": "object", "properties": {}}
+            else:
+                schema_json = cached_tool_json_schema(tool.schema, "serialization")
             # Show the actual xp_execute_tool call shape so the model passes the
             # correct nested envelope (body_params/headers) on the first try.
             example = {"name": tool.id, "arguments": _example_arguments(schema_json)}
@@ -283,9 +309,10 @@ _EXECUTE_DESC = (
     "Run a tool by id with its arguments. "
     "<when>ONLY after xp_get_tool for this exact tool — execution is REFUSED until you have "
     "read its schema, since you cannot know its arguments otherwise.</when> "
-    "`arguments` is the tool's own input object — pass the FULL nested envelope the schema "
-    'shows (e.g. {"body_params": {...}, "headers": {...}}), not flattened fields. '
-    "`name` is the tool id. Wrap arguments in a `payload` object."
+    "`arguments` is the tool's own input object — match the schema exactly. Most tools want the "
+    'FULL nested envelope the schema shows (e.g. {"body_params": {...}, "headers": {...}}), NOT '
+    "flattened fields; but MCP tools (name starts with `mcp_tool_`) take FLAT args as their schema "
+    "shows, with no body_params wrapper. `name` is the tool id. Wrap arguments in a `payload` object."
 )
 
 
@@ -310,12 +337,12 @@ def _list_impl(repo: Any, data: Dict[str, Any], inspected: set) -> str:
         ),
     )
 
-    tools = hidden_tools(repo.list)
+    tools = hidden_tools(repo.dynamic_catalog)
     total = len(tools)
     page = tools[cursor : cursor + limit]
 
     entries = "\n".join(
-        f'  <tool name="{_xml_escape(t.id)}">{_truncate(t.description or "")}</tool>'
+        f'  <tool name="{_xml_escape(t.id)}"{_mcp_attrs(t)}>{_truncate(t.description or "")}</tool>'
         for t in page
     )
     next_cursor = cursor + limit
@@ -345,7 +372,7 @@ def _search_impl(repo: Any, data: Dict[str, Any], inspected: set) -> str:
             "</no_matches>"
         )
 
-    tools = hidden_tools(repo.list)
+    tools = hidden_tools(repo.dynamic_catalog)
     scored = [(score_tool(query, t), t) for t in tools]
     scored = [(s, t) for s, t in scored if s > 0]
     scored.sort(key=lambda x: x[0], reverse=True)
@@ -411,6 +438,12 @@ async def _execute_impl(repo: Any, data: Dict[str, Any], inspected: set) -> Any:
     agent = getattr(state, "agent", None)
     task = getattr(state, "task", None)
 
+    # MCP proxies dispatch through their live agno session (not the xpander HTTP
+    # path), take flat args (no workspace_path/body_params envelope), and the
+    # meta-tool path bypasses the agno hook — so report activity ourselves.
+    if getattr(tool, "is_mcp_proxy", False):
+        return await _execute_mcp_proxy(tool, arguments, task)
+
     # Parity with the agno-hook path: resolve workspace_path offloads here too,
     # otherwise schema validation rejects the empty inline body_params.
     if has_workspace_path(arguments):
@@ -438,6 +471,66 @@ async def _execute_impl(repo: Any, data: Dict[str, Any], inspected: set) -> Any:
     )
 
 
+async def _execute_mcp_proxy(tool: Any, arguments: Dict[str, Any], task: Any) -> Any:
+    """Run an MCP proxy via its live agno session, surfacing the real MCP tool in
+    the activity log (the meta-tool path bypasses the agno hook, so nothing else
+    reports it). Reporting is best-effort and never blocks the tool result."""
+    report_request = report_result = None
+    if task is not None and getattr(task, "id", None):
+        try:
+            from xpander_sdk.modules.backend.utils.tool_call_events import (
+                report_tool_call_request,
+                report_tool_call_result,
+            )
+
+            report_request, report_result = (
+                report_tool_call_request,
+                report_tool_call_result,
+            )
+        except Exception:
+            pass
+
+    request_id = uuid.uuid4().hex
+    if report_request:
+        try:
+            await report_request(
+                task=task,
+                request_id=request_id,
+                operation_id=tool.id,
+                tool_name=tool.id,
+                payload=arguments,
+            )
+        except Exception:
+            pass
+
+    is_error = False
+    try:
+        result = await tool.ainvoke(arguments)
+    except Exception as exc:
+        is_error = True
+        result = f"Error executing MCP tool '{tool.id}': {exc}"
+    else:
+        # agno reports MCP failures in-band as content prefixed "Error from MCP tool".
+        if isinstance(result, str) and result.lstrip().startswith("Error from MCP tool"):
+            is_error = True
+
+    if report_result:
+        try:
+            await report_result(
+                task=task,
+                request_id=request_id,
+                operation_id=tool.id,
+                tool_name=tool.id,
+                payload=arguments,
+                result=result,
+                is_error=is_error,
+            )
+        except Exception:
+            pass
+
+    return result
+
+
 # --- Meta-tool callable assembly -------------------------------------------- #
 
 
@@ -544,14 +637,14 @@ def build_dynamic_tools_hint(repo: Any) -> str:
     """The <dynamic_tools> system-prompt block: workflow, rules, inline catalog.
 
     Returns "" when there are no hidden tools (nothing to disclose)."""
-    tools = hidden_tools(repo.list)
+    tools = hidden_tools(repo.dynamic_catalog)
     total = len(tools)
     if total == 0:
         return ""
 
     shown = tools[:HINT_CATALOG_CAP]
     catalog = "\n".join(
-        f'  <tool name="{_xml_escape(t.id)}">{_truncate(t.description or "")}</tool>'
+        f'  <tool name="{_xml_escape(t.id)}"{_mcp_attrs(t)}>{_truncate(t.description or "")}</tool>'
         for t in shown
     )
     overflow = ""
@@ -561,7 +654,7 @@ def build_dynamic_tools_hint(repo: Any) -> str:
     return f"""
 
 <dynamic_tools>
-Your full tool library ({total} tools) is NOT loaded into context. Only xp*/mcp*/knowledge tools are directly callable; everything else is reached through the meta-tools below.
+Your full tool library ({total} tools) is NOT loaded into context. Only xp*/knowledge tools are directly callable; everything else — including MCP server tools (name starts with `mcp_tool_`) — is reached through the meta-tools below.
 <workflow>
 1. xp_search_tools(query) — find candidates by intent (or xp_list_tools to browse).
 2. xp_get_tool(name) — read the chosen tool's schema + a ready-to-copy execute example. REQUIRED before step 3.
@@ -570,9 +663,11 @@ Your full tool library ({total} tools) is NOT loaded into context. Only xp*/mcp*
 <rules>
 - Search FIRST. Never assume a tool is missing because it isn't loaded — search for it.
 - `name` is the tool id shown in search/list/catalog — use it verbatim for xp_get_tool and xp_execute_tool.
-- ALWAYS xp_get_tool before xp_execute_tool. Never guess a tool's arguments — pass the FULL nested
-  envelope the schema shows (e.g. {{"body_params": {{...}}, "headers": {{...}}}}), not flattened fields.
-- xp*/mcp*/knowledge tools are already available directly; no search needed for those.
+- ALWAYS xp_get_tool before xp_execute_tool. Never guess a tool's arguments — match the schema exactly:
+  most tools want the FULL nested envelope (e.g. {{"body_params": {{...}}, "headers": {{...}}}}), but MCP
+  tools (`mcp_tool_*`) take FLAT args with no body_params wrapper — copy the shape their schema shows.
+- xp*/knowledge tools are already available directly; no search needed for those. MCP tools are NOT
+  directly loaded — search/get them like any other hidden tool.
 </rules>
 <catalog>
 {catalog}{overflow}

xpander_sdk-2.0.404/src/xpander_sdk/modules/tools_repository/sub_modules/mcp_tool_proxy.py

@@ -0,0 +1,60 @@
+"""Adapter that lets an MCP server tool ride the dynamic-tools mechanism.
+
+When ``agent.use_dynamic_tools`` is on, MCP servers are connected at build time
+and each of their tools is wrapped as an ``MCPToolProxy`` instead of being handed
+to agno directly. The proxy exposes the same small surface the dynamic meta-tools
+already read off an xpander ``Tool`` (``id``/``name``/``description`` plus a schema)
+so ``xp_list_tools``/``xp_search_tools``/``xp_get_tool``/``xp_execute_tool`` can
+disclose and run MCP tools with no special-casing beyond the raw-schema render.
+
+An MCP tool's schema is a raw JSON-schema dict (``Function.parameters``), not a
+pydantic model, and it takes flat kwargs (no ``payload``/``body_params`` envelope);
+both differences are handled where the proxy is consumed.
+"""
+
+from typing import Any, Dict, List, Optional
+
+
+class MCPToolProxy:
+    """Dynamic-catalog entry backed by one live agno MCP ``Function``."""
+
+    # Marker read by the dynamic-tools code to branch on MCP vs xpander tools.
+    is_mcp_proxy: bool = True
+
+    def __init__(
+        self,
+        agno_function: Any,
+        server_name: Optional[str] = None,
+        server_url: Optional[str] = None,
+    ):
+        # ``Function.name`` is already prefixed ("mcp_tool_<tool>") and unique, so
+        # it doubles as the id the model passes to xp_get_tool / xp_execute_tool.
+        self.id: str = agno_function.name
+        self.name: str = agno_function.name
+        self.description: str = agno_function.description or agno_function.name
+        # Raw MCP inputSchema; rendered directly (not via a pydantic model class).
+        self.raw_json_schema: Dict[str, Any] = agno_function.parameters or {}
+        # Source server identity — rendered into the catalog XML so the agent knows
+        # which MCP server a tool belongs to (url is None for local/stdio servers).
+        self.server_name: Optional[str] = server_name
+        self.server_url: Optional[str] = server_url
+        self._agno_function = agno_function
+
+    async def ainvoke(self, arguments: Optional[Dict[str, Any]] = None) -> Any:
+        """Run the MCP tool via the live session; return its text content."""
+        result = await self._agno_function.entrypoint(**(arguments or {}))
+        # agno wraps output as a ToolResult (content str, optional images); MCP
+        # failures come back as content prefixed "Error from MCP tool ...".
+        return getattr(result, "content", result)
+
+
+def build_mcp_proxies(
+    mcp_tool: Any,
+    server_name: Optional[str] = None,
+    server_url: Optional[str] = None,
+) -> List[MCPToolProxy]:
+    """Wrap every tool of a connected agno ``MCPTools`` toolkit as a proxy."""
+    return [
+        MCPToolProxy(fn, server_name=server_name, server_url=server_url)
+        for fn in (mcp_tool.functions or {}).values()
+    ]

{xpander_sdk-2.0.403 → xpander_sdk-2.0.404}/src/xpander_sdk/modules/tools_repository/tools_repository_module.py

@@ -68,6 +68,16 @@ class ToolsRepository(XPanderSharedModel):
     # re-materialization of the non-cached `functions` property within a run.
     _dynamic_inspected: set = PrivateAttr(default_factory=set)
 
+    # MCP server tools collapsed into the dynamic catalog for this run (populated
+    # by the agno framework layer when use_dynamic_tools is on). The meta-tools
+    # list/search/get/execute over these alongside repo.list.
+    _dynamic_mcp_proxies: List[Any] = PrivateAttr(default_factory=list)
+
+    # The live agno MCPTools toolkits backing the proxies above. The SDK owns
+    # their session (they are kept out of the agno agent's tools so the LLM never
+    # sees them); the worker closes them post-run via args["_xpander_hidden_mcp_toolkits"].
+    _dynamic_mcp_toolkits: List[Any] = PrivateAttr(default_factory=list)
+
     @classmethod
     def register_tool(cls, tool: Tool):
         """
@@ -105,6 +115,12 @@ class ToolsRepository(XPanderSharedModel):
 
         return tools
 
+    @property
+    def dynamic_catalog(self) -> List[Any]:
+        """All targets the dynamic meta-tools operate over: xpander tools plus any
+        MCP proxies collapsed into the catalog for this run."""
+        return self.list + self._dynamic_mcp_proxies
+
     def get_tool_by_id(self, tool_id: str):
         """
         Retrieve a tool by its unique identifier.
@@ -115,7 +131,7 @@ class ToolsRepository(XPanderSharedModel):
         Returns:
             Tool: The tool corresponding to the given ID.
         """
-        return next((tool for tool in self.list if tool.id == tool_id), None)
+        return next((tool for tool in self.dynamic_catalog if tool.id == tool_id), None)
 
     def get_tool_by_name(self, tool_name: str):
         """
@@ -127,7 +143,7 @@ class ToolsRepository(XPanderSharedModel):
         Returns:
             Tool: The tool corresponding to the given ID.
         """
-        return next((tool for tool in self.list if tool.name == tool_name), None)
+        return next((tool for tool in self.dynamic_catalog if tool.name == tool_name), None)
 
     def should_sync_local_tools(self):
         """

{xpander_sdk-2.0.403 → xpander_sdk-2.0.404/src/xpander_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.403
+Version: 2.0.404
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.403 → xpander_sdk-2.0.404}/src/xpander_sdk.egg-info/SOURCES.txt

@@ -119,6 +119,7 @@ src/xpander_sdk/modules/tools_repository/models/mcp.py
 src/xpander_sdk/modules/tools_repository/models/tool_invocation_result.py
 src/xpander_sdk/modules/tools_repository/sub_modules/__init__.py
 src/xpander_sdk/modules/tools_repository/sub_modules/dynamic_tools.py
+src/xpander_sdk/modules/tools_repository/sub_modules/mcp_tool_proxy.py
 src/xpander_sdk/modules/tools_repository/sub_modules/tool.py
 src/xpander_sdk/modules/tools_repository/utils/__init__.py
 src/xpander_sdk/modules/tools_repository/utils/generic.py