Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

fix(backend): expand @@agptfile refs for MCP tool arguments (#13373)

Abhimanyu Yadav96e27eef40dc
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
index 6420fe1e56..c510c9262a 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
@@ -14,6 +14,11 @@ from backend.blocks.mcp.helpers import (
server_host,
)
from backend.copilot.model import ChatSession
+from backend.copilot.sdk.file_ref import (
+ FILE_REF_PREFIX,
+ FileRefExpansionError,
+ expand_file_refs_in_args,
+)
from backend.copilot.tools.utils import build_missing_credentials_from_field_info
from backend.util.request import HTTPClientError, validate_url_host
@@ -40,6 +45,21 @@ def _service_name(host: str) -> str:
return host[4:] if host.startswith("mcp.") else host
+def _args_contain_file_ref(value: Any) -> bool:
+ """True if any nested string in *value* holds an ``@@agptfile:`` token.
+
+ Cheap pre-check so we only pay the ``list_tools`` round-trip (for
+ type-aware expansion) when a reference is actually present.
+ """
+ if isinstance(value, str):
+ return FILE_REF_PREFIX in value
+ if isinstance(value, dict):
+ return any(_args_contain_file_ref(v) for v in value.values())
+ if isinstance(value, list):
+ return any(_args_contain_file_ref(item) for item in value)
+ return False
+
+
class RunMCPToolTool(BaseTool):
"""
Tool for discovering and executing tools on any MCP server.
@@ -259,7 +279,13 @@ class RunMCPToolTool(BaseTool):
else:
# Stage 2: Execute the selected tool
return await self._execute_tool(
- client, server_url, tool_name, resolved_tool_arguments, session_id
+ client,
+ server_url,
+ tool_name,
+ resolved_tool_arguments,
+ session_id,
+ user_id,
+ session,
)
except HTTPClientError as e:
@@ -340,9 +366,18 @@ class RunMCPToolTool(BaseTool):
tool_name: str,
tool_arguments: dict[str, Any],
session_id: str,
+ user_id: str | None,
+ session: ChatSession,
) -> MCPToolOutputResponse | ErrorResponse:
"""Execute a specific tool on an already-initialized MCPClient.
+ Before dispatch, any ``@@agptfile:`` references in *tool_arguments* are
+ expanded inline so the external server receives the real file contents
+ rather than the literal token. The opaque ``tool_arguments`` object is
+ skipped by the SDK-level wrapper expansion (it has no declared
+ properties), so it must be expanded here using the tool's own schema —
+ mirroring how RunBlockTool expands block inputs.
+
Parses the MCP content response into a plain Python value:
- text items: parsed as JSON when possible, kept as str otherwise
- image items: kept as {type, data, mimeType} dict for frontend rendering
@@ -350,6 +385,21 @@ class RunMCPToolTool(BaseTool):
Single-item responses are unwrapped from the list; multiple items are
returned as a list; empty content returns None.
"""
+ if _args_contain_file_ref(tool_arguments):
+ input_schema = await self._lookup_tool_schema(client, tool_name)
+ try:
+ tool_arguments = await expand_file_refs_in_args(
+ tool_arguments, user_id, session, input_schema=input_schema
+ )
+ except FileRefExpansionError as exc:
+ return ErrorResponse(
+ message=(
+ f"Failed to resolve file reference: {exc}. "
+ "Ensure the file exists before referencing it."
+ ),
+ session_id=session_id,
+ )
+
result = await client.call_tool(tool_name, tool_arguments)
if result.is_error:
@@ -374,6 +424,34 @@ class RunMCPToolTool(BaseTool):
session_id=session_id,
)
+ async def _lookup_tool_schema(
+ self,
+ client: MCPClient,
+ tool_name: str,
+ ) -> dict[str, Any] | None:
+ """Return the named tool's input schema for type-aware ref expansion.
+
+ Returns ``None`` if the tool can't be found or listing fails —
+ expansion still proceeds, just without schema-driven type coercion
+ (e.g. keeping a string field as raw text instead of parsing JSON).
+ """
+ try:
+ tools = await client.list_tools()
+ except Exception as exc:
+ # Schema lookup is best-effort — any failure (HTTP 4xx/5xx,
+ # timeouts, connection errors, protocol errors) degrades to
+ # schema-less expansion rather than failing the tool call.
+ logger.debug(
+ "Could not list tools on %s for schema lookup: %s",
+ server_host(client.server_url),
+ exc,
+ )
+ return None
+ return next(
+ (t.input_schema for t in tools if t.name == tool_name),
+ None,
+ )
+
def _build_setup_requirements(
self,
server_url: str,
diff --git a/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py b/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py
index 84ebc550ce..82d6badcb5 100644
--- a/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py
+++ b/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py
@@ -1,11 +1,13 @@
"""Unit tests for the run_mcp_tool copilot tool."""
+from typing import Any
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from pydantic import SecretStr
from backend.blocks.mcp.helpers import server_host
+from backend.copilot.sdk.file_ref import FileRefExpansionError
from ._test_data import make_session
from .models import (
@@ -1059,3 +1061,148 @@ async def test_build_setup_requirements_returns_setup_response():
assert isinstance(result, SetupRequirementsResponse)
assert result.setup_info.agent_id == _SERVER_URL
assert "sign in" in result.message.lower()
+
+
+# ---------------------------------------------------------------------------
+# @@agptfile: reference expansion (OPEN-3159)
+# ---------------------------------------------------------------------------
+
+
+def _make_tool_schema(name: str, input_schema: dict[str, Any]):
+ t = MagicMock()
+ t.name = name
+ t.input_schema = input_schema
+ return t
+
+
[email protected](loop_scope="session")
+async def test_agptfile_ref_expanded_before_mcp_call():
+ """@@agptfile tokens in tool_arguments expand before reaching the server."""
+ tool = RunMCPToolTool()
+ session = make_session(_USER_ID)
+ expanded = {"content": "FILE BODY"}
+ schema = {"type": "object", "properties": {"content": {"type": "string"}}}
+ tool_schema = _make_tool_schema("notion-update-page", schema)
+
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.validate_url_host", new_callable=AsyncMock
+ ), patch(
+ "backend.copilot.tools.run_mcp_tool.auto_lookup_mcp_credential",
+ new_callable=AsyncMock,
+ return_value=None,
+ ), patch(
+ "backend.copilot.tools.run_mcp_tool.expand_file_refs_in_args",
+ new_callable=AsyncMock,
+ return_value=expanded,
+ ) as mock_expand:
+ mock_client = AsyncMock()
+ mock_client.list_tools = AsyncMock(return_value=[tool_schema])
+ mock_client.call_tool = AsyncMock(
+ return_value=_make_call_result([{"type": "text", "text": "ok"}])
+ )
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.MCPClient", return_value=mock_client
+ ):
+ await tool._execute(
+ user_id=_USER_ID,
+ session=session,
+ server_url=_SERVER_URL,
+ tool_name="notion-update-page",
+ tool_arguments={"content": "@@agptfile:/home/user/report.md"},
+ )
+
+ # The tool's real schema was looked up and threaded into expansion.
+ mock_expand.assert_awaited_once()
+ await_args = mock_expand.await_args
+ assert await_args is not None
+ assert await_args.kwargs["input_schema"] == schema
+ # user_id + session (positional) are forwarded — they gate file access
+ # permissions and are the reason _execute_tool's signature changed.
+ assert await_args.args[1] == _USER_ID
+ assert await_args.args[2] is session
+ # Expanded content (not the literal token) reached the server.
+ assert mock_client.call_tool.call_args.args[1] == expanded
+
+
[email protected](loop_scope="session")
+async def test_agptfile_expansion_failure_returns_error():
+ """A failed ref resolution blocks the call and returns ErrorResponse."""
+ tool = RunMCPToolTool()
+ session = make_session(_USER_ID)
+
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.validate_url_host", new_callable=AsyncMock
+ ), patch(
+ "backend.copilot.tools.run_mcp_tool.auto_lookup_mcp_credential",
+ new_callable=AsyncMock,
+ return_value=None,
+ ), patch(
+ "backend.copilot.tools.run_mcp_tool.expand_file_refs_in_args",
+ new_callable=AsyncMock,
+ side_effect=FileRefExpansionError("missing.md not found"),
+ ):
+ mock_client = AsyncMock()
+ mock_client.list_tools = AsyncMock(return_value=[])
+ mock_client.call_tool = AsyncMock()
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.MCPClient", return_value=mock_client
+ ):
+ response = await tool._execute(
+ user_id=_USER_ID,
+ session=session,
+ server_url=_SERVER_URL,
+ tool_name="notion-update-page",
+ tool_arguments={"content": "@@agptfile:/home/user/missing.md"},
+ )
+
+ assert isinstance(response, ErrorResponse)
+ assert "file reference" in response.message.lower()
+ mock_client.call_tool.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_no_agptfile_ref_skips_schema_lookup():
+ """Args without a ref pass through verbatim — no extra list_tools call."""
+ tool = RunMCPToolTool()
+ session = make_session(_USER_ID)
+ raw_args = {"url": "https://example.com"}
+
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.validate_url_host", new_callable=AsyncMock
+ ), patch(
+ "backend.copilot.tools.run_mcp_tool.auto_lookup_mcp_credential",
+ new_callable=AsyncMock,
+ return_value=None,
+ ):
+ mock_client = AsyncMock()
+ mock_client.list_tools = AsyncMock(return_value=[])
+ mock_client.call_tool = AsyncMock(
+ return_value=_make_call_result([{"type": "text", "text": "ok"}])
+ )
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.MCPClient", return_value=mock_client
+ ):
+ await tool._execute(
+ user_id=_USER_ID,
+ session=session,
+ server_url=_SERVER_URL,
+ tool_name="fetch",
+ tool_arguments=raw_args,
+ )
+
+ mock_client.list_tools.assert_not_called()
+ assert mock_client.call_tool.call_args.args[1] == raw_args
+
+
[email protected](loop_scope="session")
+async def test_lookup_tool_schema_returns_none_on_any_failure():
+ """Schema lookup degrades gracefully on any list_tools failure (not just
+ HTTP/MCP errors) so expansion proceeds schema-less instead of crashing."""
+ tool = RunMCPToolTool()
+ mock_client = AsyncMock()
+ mock_client.server_url = _SERVER_URL
+ mock_client.list_tools = AsyncMock(side_effect=TimeoutError("network timeout"))
+
+ schema = await tool._lookup_tool_schema(mock_client, "notion-update-page")
+
+ assert schema is None