Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: search and load large MCP tool catalogs on demand (#13601)

Daniel Hanc174a7db5fff
diff --git a/studio/MCP.md b/studio/MCP.md
index c227dee8380..6b39c302a37 100644
--- a/studio/MCP.md
+++ b/studio/MCP.md
@@ -39,20 +39,22 @@ or launching Unsloth Studio does not download anything.
A server can expose dozens of tools with long descriptions and deeply nested
parameter schemas: Notion's catalog alone is about 65,000 tokens. Every tool is
-listed in full whenever the catalog fits the loaded local model's context window,
-so a model that can hold the full listing always gets it.
-
-When the full listing would take more than three quarters of the window, which
-would otherwise get even a short prompt refused, the largest tools (only those
-whose description and schema together exceed about 1,500 characters) are listed
-in a compact form, largest first, until the listing fits: a compact tool shows its
-first sentence plus its top-level parameters with their types, required flags and
-short enums. Every other tool keeps its full schema. The model then also gets `mcp_tool_schema`, which returns a tool's
-full description and JSON Schema on demand, in pages when it is longer than the
-room left for a tool result. A compact tool called without one of its required
-arguments, or whose call the server rejects, answers with that schema so the model
-can correct the call. Arguments to a compact tool are still typed against its full
-schema. External providers always get the full listing.
+listed in full while the catalog takes at most a tenth of the loaded local model's
+context window. External providers always get the full listing.
+
+Past that, Studio searches tools the way Claude Code and Codex do. The model gets
+`mcp_tool_search`, whose description names every tool with a one-line summary,
+instead of the schemas. A search ranks the catalog with the SQLite FTS5 BM25 index
+and rank fusion the knowledge base uses (tool names and descriptions searched
+separately) and loads the best matches, exact names always; the model then calls
+them with their full schemas. A tool the model calls by name loads the same way.
+
+Up front, the listing also carries a tool a `tool_choice` forces, the tools mapped
+to take an attached image, and, within a third of the window, the tools the chat
+ran on earlier turns (so the prompt prefix the model server caches holds) and up
+to five tools ranked against the user's message. Tools a turn loads stay within
+half of the window, the oldest leaving first; a tool too large for that is refused
+with a message naming it.
## Unsloth Decisions MCP
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 76884e767f3..221efcaefdf 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -38894,10 +38894,15 @@ class LlamaCppBackend:
# Gate telling a genuine NAME[ARGS] rehearsal from inactive-name prose; built from the
# ORIGINAL tools list so a spent one-shot still reads as a tool name. None = no gate.
- _enabled_names_gate = set(_gguf_active_tool_names(tools)) if tools else None
+ from core.inference.tools import mcp_loadable_specs
+
+ # Plus the MCP tools a search can load mid-turn (#10997).
+ _loadable_mcp = mcp_loadable_specs(tools)
+ _loadable_mcp_names = set(_gguf_active_tool_names(_loadable_mcp))
+ _detect_tools = list(tools or []) + _loadable_mcp
+ _enabled_names_gate = set(_gguf_active_tool_names(_detect_tools)) if tools else None
# Detection must see the same names as the strip gate (ORIGINAL list, incl. a spent
# one-shot), else its repeat is stripped but never drained and the turn ends blank.
- _detect_tools = list(tools or [])
def _reasoning_summary_event(started_at: float) -> dict:
return {
@@ -39332,7 +39337,7 @@ class LlamaCppBackend:
(tool.get("function") or {}).get("name")
for tool in safe_tools
if (tool.get("function") or {}).get("name")
- }
+ } | (set() if forced_name else _loadable_mcp_names)
# Shared signal tuple so GGUF BUFFERING wakes on every format the parser knows (like safetensors).
_tool_xml_signals = _SHARED_TOOL_XML_SIGNALS
@@ -41894,8 +41899,10 @@ class LlamaCppBackend:
# stall text over would read the same sentence as a repeat and
# swallow the one post-tool nudge.
_last_reprompt_text = ""
- # A tool ran this turn, so it counts against the caller's budget.
- _turn_executed_real_tool = True
+ # A tool ran this turn, so it counts against the caller's budget. Loading
+ # MCP tools does not, or a budget of one could never call what it found.
+ if decision.tool_name != "mcp_tool_search":
+ _turn_executed_real_tool = True
_forced_choice_resolved = True
_tool_end = completion.tool_end_event()
yield _tool_end
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index b56226b6f44..a68a58109b0 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -758,10 +758,14 @@ def run_safetensors_tool_loop(
unrestricted_tools = not tools
# Gate telling a genuine NAME[ARGS] rehearsal from inactive-name prose; built from the
# ORIGINAL tools list so a spent one-shot still reads as a tool name. None = unrestricted.
- _enabled_names_gate = None if unrestricted_tools else set(_active_tool_names(tools))
+ from core.inference.tools import mcp_loadable_specs
+
+ # Plus the MCP tools a search can load mid-turn (#10997).
+ _loadable_mcp = [] if unrestricted_tools else mcp_loadable_specs(tools)
+ _detect_tools = [] if unrestricted_tools else list(tools or []) + _loadable_mcp
+ _enabled_names_gate = None if unrestricted_tools else set(_active_tool_names(_detect_tools))
# Detection must see the same names as the strip gate (ORIGINAL list, incl. a spent
# one-shot), else its repeat is stripped but never drained and the turn ends blank.
- _detect_tools = [] if unrestricted_tools else list(tools or [])
# Sanitized at construction: prepare_call authorizes against the controller, so a tool
# dropped from the prompt for unsafe markup must leave the controller too. The gates above
# keep the ORIGINAL names: those decide what LOOKS like a call, not what may run (#7066).
@@ -842,7 +846,12 @@ def run_safetensors_tool_loop(
tool_protocol_active = not final_attempt_done and (unrestricted_tools or bool(active_tools))
tool_xml_signals = TOOL_XML_SIGNALS if tool_protocol_active else ()
# Gate the markerless bare-JSON form on enabled names so an ordinary JSON answer isn't misread as a call.
- _enabled_tool_names = None if unrestricted_tools else set(_active_tool_names(active_tools))
+ _enabled_tool_names = (
+ None
+ if unrestricted_tools
+ else set(_active_tool_names(active_tools))
+ | (set(_active_tool_names(_loadable_mcp)) if active_tools else set())
+ )
# Refit every iteration: tool results grow the prompt after the first turn. Given
# the prompt, this turn's tools and the live branch; returns `messages` and `events`.
@@ -1805,7 +1814,9 @@ def run_safetensors_tool_loop(
completion = tool_controller.record_result(decision, result)
if provisional_match:
provisional_resolved = True
- _turn_executed_real_tool = True
+ # Loading MCP tools is not a tool round, or a budget of one could never call what it found.
+ if decision.tool_name != "mcp_tool_search":
+ _turn_executed_real_tool = True
yield completion.tool_end_event()
conversation.append(completion.tool_message())
# Parsed only when there is a sink for them.
diff --git a/studio/backend/core/inference/tool_loop_controller.py b/studio/backend/core/inference/tool_loop_controller.py
index 5ab6a5cfd26..38d081c3c92 100644
--- a/studio/backend/core/inference/tool_loop_controller.py
+++ b/studio/backend/core/inference/tool_loop_controller.py
@@ -27,6 +27,8 @@ from core.inference.mcp_images import is_image_tool, split_images as split_mcp_i
# Stamped by mcp_client on every tool it registers; the provenance the envelope
# is trusted on.
MCP_TOOL_PREFIX = "mcp__"
+# tools.MCP_TOOL_SEARCH_NAME; tools imports this module.
+MCP_TOOL_SEARCH_NAME = "mcp_tool_search"
from core.inference.tool_call_parser import TOOL_ERROR_NUDGE, TOOL_ERROR_PREFIXES
@@ -681,22 +683,35 @@ def _declared_properties(tool_name: str, tool_schemas) -> Any:
function = tool.get("function") if isinstance(tool, Mapping) else None
if not isinstance(function, Mapping) or function.get("name") != tool_name:
continue
- parameters = _mcp_full_parameters(tool_name) or function.get("parameters")
+ parameters = function.get("parameters")
return parameters.get("properties") if isinstance(parameters, Mapping) else None
return None
-def _mcp_full_parameters(tool_name: str) -> Any:
- # A large MCP tool is listed with only its top-level parameters; type its arguments by the full schema.
- if not tool_name.startswith("mcp__"):
- return None
+def _mcp_tool_spec(tool_name: str) -> Any:
try:
- from core.inference.tools import mcp_tool_input_schema # noqa: PLC0415 -- cycle at import time
- return mcp_tool_input_schema(tool_name)
- except Exception: # noqa: BLE001 -- typing must never break a chat
+ from core.inference.tools import mcp_tool_spec # noqa: PLC0415 -- cycle at import time
+ return mcp_tool_spec(tool_name)
+ except Exception: # noqa: BLE001 -- an unknown tool stays disabled
return None
+def _mcp_fit_loaded(specs: list) -> list:
+ try:
+ from core.inference.tools import mcp_fit_loaded # noqa: PLC0415 -- cycle at import time
+ return mcp_fit_loaded(specs)
+ except Exception: # noqa: BLE001 -- unsized, the newest load still goes through
+ return specs[:1]
+
+
+def _mcp_tool_search_specs(arguments: Any) -> list:
+ try:
+ from core.inference.tools import mcp_tool_search_specs # noqa: PLC0415 -- cycle at import time
+ return mcp_tool_search_specs(arguments)
+ except Exception: # noqa: BLE001 -- a failed load leaves the listing as it was
+ return []
+
+
def coerce_tool_arguments(
raw_args: Any,
*,
@@ -1228,6 +1243,9 @@ class ToolLoopController:
self._allowed_tool_names = {
name for name in (_tool_name_from_schema(tool) for tool in self._tools) if name
}
+ self._mcp_search = MCP_TOOL_SEARCH_NAME in self._allowed_tool_names
+ self._listed_count = len(self._tools)
+ self._mcp_loaded: list[dict[str, Any]] = []
self._auto_heal_tool_calls = auto_heal_tool_calls
self._deduplicate_tool_calls = deduplicate_tool_calls
self._one_shot_tools = one_shot_tools
@@ -1275,6 +1293,12 @@ class ToolLoopController:
function = tool_call.get("function")
function = function if isinstance(function, Mapping) else {}
tool_name = str(function.get("name") or "").strip()
+ if (
+ self._mcp_search
+ and tool_name.startswith(MCP_TOOL_PREFIX)
+ and tool_name not in self._allowed_tool_names
+ ):
+ self._load_mcp_tools([_mcp_tool_spec(tool_name)])
coerced = coerce_tool_arguments(
function.get("arguments", {}),
heal = self._auto_heal_tool_calls,
@@ -1309,9 +1333,11 @@ class ToolLoopController:
self._deduplicate_tool_calls
and key in self._successful_keys
and tool_name not in BROWSER_TOOL_NAMES
+ and tool_name != MCP_TOOL_SEARCH_NAME
):
# Not the browser tools: each acts on or reads the page as it is now, so a second
# scroll down or a snapshot after a click is new work, and two such no-ops ended the turn.
+ # Nor mcp_tool_search: a repeat restores tools a later load evicted.
action = "duplicate"
noop = _noop_result("duplicate", tool_name)
@@ -1389,6 +1415,11 @@ class ToolLoopController:
self._workspace_novel_at[decision.key] = self._workspace_novel
if not failed:
self._successful_keys.add(decision.key)
+ if self._mcp_search and decision.tool_name == MCP_TOOL_SEARCH_NAME:
+ self._load_mcp_tools(_mcp_tool_search_specs(decision.arguments))
+ elif decision.tool_name.startswith(MCP_TOOL_PREFIX):
+ # Also while the catalog is listed in full, for a later turn that defers it.
+ self._remember_mcp_tools([decision.tool_name])
if decision.tool_name in self._one_shot_tools:
self._completed_one_shot_tools.add(decision.tool_name)
return ToolCallCompletion(
@@ -1398,6 +1429,42 @@ class ToolLoopController:
executed = True,
)
+ def _load_mcp_tools(self, specs) -> None:
+ from core.inference.chat_template_helpers import neutralize_tool_descriptions # noqa: PLC0415
+
+ # Remote text, swept as the loops sweep the catalog this controller was built from (#7066); with no model's
+ # profile at hand, against every family's markup.
+ specs = (
+ neutralize_tool_descriptions([dict(s) for s in specs if isinstance(s, Mapping)]) or []
+ )
+ listed = self._tools[: self._listed_count]
+ listed_names = {_tool_name_from_schema(tool) for tool in listed}
+ fresh = [s for s in specs if _tool_name_from_schema(s) not in listed_names]
+ fresh_names = {_tool_name_from_schema(s) for s in fresh}
+ # Newest first into the turn's load share, so a later search can retire an older load but never overflow.
+ kept = _mcp_fit_loaded(
+ fresh
+ + [
+ s
+ for s in reversed(self._mcp_loaded)
+ if _tool_name_from_schema(s) not in fresh_names
+ ]
+ )
+ self._mcp_loaded = [copy.deepcopy(s) for s in reversed(kept)]
+ self._tools = listed + self._mcp_loaded
+ self._allowed_tool_names = {
+ name for name in (_tool_name_from_schema(tool) for tool in self._tools) if name
+ }
+
+ def _remember_mcp_tools(self, names) -> None:
+ if not names:
+ return
+ try:
+ from core.inference.tools import mcp_record_loaded_tools # noqa: PLC0415 -- import cycle
+ mcp_record_loaded_tools(self._thread_id, names)
+ except Exception: # noqa: BLE001 -- remembering for later turns must never break this one
+ pass
+
def _cap_result(self, text: str, tool_name: str | None) -> str:
"""The card and the model get the same capped body; the frontend envelope stays whole."""
from core.inference.tools import ( # noqa: PLC0415 -- import cycle
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index f2b9014c6b8..525b07a65e6 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -7,13 +7,14 @@ execution, and terminal commands."""
import ast
import codecs
import copy
-from collections import deque
+from collections import OrderedDict, deque
from collections.abc import Iterable
import fnmatch
import functools
import hashlib
from html.parser import HTMLParser
import json
+import math
import http.client
import ntpath
import os
@@ -26,6 +27,7 @@ import asyncio
import queue
import random
import re
+import sqlite3
import shlex
import shutil
import ssl
@@ -7278,7 +7280,7 @@ _ALWAYS_SAFE_TOOLS = frozenset(
"search_conversation",
"read_skill",
"deep_research",
- "mcp_tool_schema",
+ "mcp_tool_search",
"view_image",
# Gated in the chat tab instead, which knows what each ref on the live page is: submits,
# purchases, sign-ins and new sites ask there, in every permission mode.
@@ -13569,48 +13571,123 @@ _MCP_ALIAS_DIGEST_LEN = 8
# The "_" plus digest every alias ends with, which is the room its stem does not get.
_MCP_ALIAS_SUFFIX_LEN = _MCP_ALIAS_DIGEST_LEN + 1
-_MCP_COMPACT_SPEC_CHARS = 1500
_MCP_SUMMARY_CHARS = 240
-_MCP_COMPACT_HINT = "Full parameters via mcp_tool_schema."
-_MCP_MIN_SCHEMA_PAGE_CHARS = 64
-_MCP_FULL_LISTING_SHARE = 0.75
+# Past this share of the local window, MCP tools are deferred behind mcp_tool_search (#10997).
+_MCP_TOOL_SEARCH_SHARE = 0.10
+_MCP_TOOL_SEARCH_LIMIT = 5
+# Up to this many tools ranked against the user's message are listed up front, within their own share of the
+# window: small models often answer that a tool is unavailable rather than search for it (#10997).
+_MCP_TOOL_PRELOAD = 5
+_MCP_TOOL_PRELOAD_SHARE = 0.33
+# Tools a turn loads by search or by name, newest first; older ones leave the listing to stay within it.
+_MCP_TOOL_LOAD_SHARE = 0.5
+_MCP_TOOL_SEARCH_SUMMARY_CHARS = 80
+_MCP_TOOL_SEARCH_MAX_LIMIT = 10
+_MCP_TOOL_SEARCH_MAX_NAMES = 200
+# Tools a thread ran stay listed on its later turns, so the prompt prefix (and llama-server's cache) holds.
+_MCP_LOADED_PER_THREAD = 8
+_MCP_LOADED_THREADS_MAX = 512
+MCP_TOOL_SEARCH_NAME = "mcp_tool_search"
_MCP_LISTING_CONTEXT_TOKENS: ContextVar = ContextVar("mcp_listing_context_tokens", default = None)
-# (account, window) -> tools its last MCP listing compacted; per account since studio.db (and so MCP servers) is.
-_MCP_COMPACTED_WINDOWS: dict[tuple, frozenset] = {}
-
+_MCP_LISTING_THREAD: ContextVar = ContextVar("mcp_listing_thread", default = None)
+_MCP_LISTING_QUERY: ContextVar = ContextVar("mcp_listing_query", default = "")
+_MCP_LISTING_FORCED: ContextVar = ContextVar("mcp_listing_forced", default = None)
+_MCP_LISTING_IMAGE: ContextVar = ContextVar("mcp_listing_image", default = False)
+# (account, thread) -> MCP tools the thread ran while they were deferred, oldest first.
+_MCP_LOADED_THREADS: "OrderedDict[tuple, list[str]]" = OrderedDict()
+_MCP_LOADED_LOCK = threading.Lock()
+# Digest of the catalog's searchable text -> its in-memory FTS5 index, rebuilt only when that text changes.
+_MCP_SEARCH_INDEXES: "OrderedDict[str, sqlite3.Connection]" = OrderedDict()
+_MCP_SEARCH_LOCK = threading.Lock()
+
+
+def set_mcp_listing_context_tokens(
+ context_tokens,
+ thread_id = None,
+ messages = None,
+ tool_choice = None,
+ mcp_image = None,
+) -> None:
+ """The local window the next MCP listing in this context is sized against; unset lists every tool in full.
+ ``thread_id`` keeps the tools a chat ran listed; ``messages`` ranks the deferred ones listed up front; a
+ ``tool_choice`` forcing a tool keeps that one listed, and an attached image (in the message or, sent to MCP tools
+ only, as ``mcp_image``) keeps the tools mapped to take it listed."""
+ from core.inference.chat_template_helpers import forced_tool_name, last_user_text # noqa: PLC0415
-def set_mcp_listing_context_tokens(context_tokens) -> None:
- """The local window the next MCP listing in this context is sized against; unset lists every tool in full."""
valid = isinstance(context_tokens, int) and context_tokens > 0
_MCP_LISTING_CONTEXT_TOKENS.set(context_tokens if valid else None)
+ _MCP_LISTING_THREAD.set(thread_id if isinstance(thread_id, str) and thread_id else None)
+ dicts = [m.model_dump() if hasattr(m, "model_dump") else m for m in messages or []]
+ _MCP_LISTING_QUERY.set(last_user_text(dicts) if valid else "")
+ _MCP_LISTING_FORCED.set(forced_tool_name(tool_choice))
+ last_user = next(
+ (m for m in reversed(dicts) if isinstance(m, dict) and m.get("role") == "user"), None
+ )
+ _MCP_LISTING_IMAGE.set(
+ bool(mcp_image) or (bool(last_user) and _content_has_image(last_user.get("content")))
+ )
-MCP_TOOL_SCHEMA_TOOL = {
- "type": "function",
- "function": {
- "name": "mcp_tool_schema",
- "description": (
- "Return the full description and parameter schema of an MCP tool. A tool whose "
- f"listing ends with '{_MCP_COMPACT_HINT}' shows only its top-level parameters; "
- "call this before using it when that listing is not enough."
- ),
- "parameters": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The MCP tool name exactly as listed, including its mcp__ prefix.",
- },
- "offset": {
- "type": "integer",
- "minimum": 0,
- "description": "Character offset for the next page. Defaults to 0.",
+def _content_has_image(content) -> bool:
+ if isinstance(content, list):
+ return any(_content_has_image(part) for part in content)
+ return isinstance(content, dict) and str(content.get("type", "")).lower() in (
+ "image",
+ "image_url",
+ "input_image",
+ )
+
+
+def _mcp_tool_search_spec(
+ catalog: list[tuple[str, list[tuple[str, str]]]], max_chars: int | None = None
+) -> dict:
+ """``catalog`` is (server display name, [(tool name, summary)]) per server, in listing order; the tool lines
+ stop at ``_MCP_TOOL_SEARCH_MAX_NAMES`` and at ``max_chars``, and at 0 only the count is left."""
+ names_left = _MCP_TOOL_SEARCH_MAX_NAMES
+ chars_left = max_chars if max_chars is not None else float("inf")
+ groups = []
+ for display, tools in catalog:
+ lines = []
+ for name, summary in tools:
+ line = f"- {name}: {summary}" if summary else f"- {name}"
+ if names_left <= 0 or len(line) > chars_left:
+ break
+ lines.append(line)
+ names_left -= 1
+ chars_left -= len(line) + 1
+ if len(tools) > len(lines):
+ lines.append(f"- and {len(tools) - len(lines)} more")
+ groups.append(f"{display[:_MCP_SUMMARY_CHARS]}:\n" + "\n".join(lines))
+ if max_chars == 0:
+ groups = [f"{sum(len(tools) for _, tools in catalog)} tools, found by searching."]
+ return {
+ "type": "function",
+ "function": {
+ "name": MCP_TOOL_SEARCH_NAME,
+ "description": (
+ "Find and load MCP tools. The connected MCP servers have the tools named below; one that is "
+ "not in your tool list must be loaded with this tool before you call it. Search with keywords "
+ "for the action (or the tool's exact name); the best matches are loaded and you can then call "
+ "them with their full parameters. Tools:\n" + "\n".join(groups)
+ ),
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Keywords for the action, or exact tool names.",
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": _MCP_TOOL_SEARCH_MAX_LIMIT,
+ "description": f"How many tools to load. Defaults to {_MCP_TOOL_SEARCH_LIMIT}.",
+ },
},
+ "required": ["query"],
},
- "required": ["name"],
},
- },
-}
+ }
def _mcp_input_schema(tool: dict) -> dict:
@@ -13619,63 +13696,16 @@ def _mcp_input_schema(tool: dict) -> dict:
)
-def _mcp_spec_compacted(tool: dict) -> bool:
- schema_chars = len(json.dumps(_mcp_input_schema(tool), separators = (",", ":")))
- return schema_chars + len(tool.get("description") or "") > _MCP_COMPACT_SPEC_CHARS
-
-
-def _mcp_summary(description: str) -> str:
+def _mcp_summary(description: str, limit: int = _MCP_SUMMARY_CHARS) -> str:
text = " ".join((description or "").split()).lstrip("# ")
match = re.match(r"(.+?[.!?])(?:\s|$)", text)
if match:
text = match.group(1)
- if len(text) > _MCP_SUMMARY_CHARS:
- text = text[: _MCP_SUMMARY_CHARS - 3].rstrip() + "..."
+ if len(text) > limit:
+ text = text[: limit - 3].rstrip() + "..."
return text
-def _mcp_compact_parameters(schema: dict) -> dict:
- properties: dict[str, dict] = {}
- for key, value in (schema.get("properties") or {}).items():
- prop: dict = {}
- if isinstance(value, dict):
- branches = value.get("anyOf") or value.get("oneOf") or []
- branch_types = [b.get("type") for b in branches if isinstance(b, dict)]
- if isinstance(value.get("type"), (str, list)):
- prop["type"] = value["type"]
- elif branch_types and all(isinstance(kind, str) for kind in branch_types):
- kinds = list(dict.fromkeys(branch_types))
- prop["type"] = kinds[0] if len(kinds) == 1 else kinds
- if isinstance(value.get("enum"), list) and len(json.dumps(value["enum"])) <= 200:
- prop["enum"] = value["enum"]
- # llama.cpp compiles an empty schema to an object-only grammar; a description alone accepts any value.
- properties[key] = prop or {"description": "See mcp_tool_schema."}
- compact: dict = (
- {"type": "object", "properties": properties} if properties else {"type": "object"}
- )
- if isinstance(schema.get("required"), list):
- compact["required"] = schema["required"]
- return compact
-
-
-def _mcp_compact_spec(name: str, display: str, tool: dict, description: str) -> dict:
- parts = (f"[{display}]", _mcp_summary(description), _MCP_COMPACT_HINT)
- return {
- "type": "function",
- "function": {
- "name": name,
- "description": " ".join(part for part in parts if part),
- "parameters": _mcp_compact_parameters(_mcp_input_schema(tool)),
- },
- }
-
-
-def _mcp_tool_schema_text(display: str, tool: dict) -> str:
- schema = json.dumps(_mcp_input_schema(tool), separators = (",", ":"))
- description = " ".join((tool.get("description") or "").split())
- return f"[{display}] {tool.get('name')}: {description}\n\nParameters (JSON Schema): {schema}"
-
-
def _mcp_cached_tool(server: dict, tool_name: str) -> dict | None:
for tool in get_cached_tools(server["id"]) or []:
if tool.get("name") == tool_name and tool_visible_to(tool, "model"):
@@ -13769,70 +13799,29 @@ def mcp_catalog_takes_image(names) -> bool:
return False
-def mcp_tool_input_schema(name) -> dict | None:
- tool = _mcp_resolve_tool(name)[1]
- return _mcp_input_schema(tool) if tool is not None else None
+def _mcp_thread_key() -> tuple | None:
+ thread_id = _MCP_LISTING_THREAD.get()
+ return (current_account_id(), thread_id) if thread_id else None
-def _mcp_schema_page(prefix: str, text: str, offset: int) -> str:
- page_chars = _other_tool_result_char_budget()
- while True:
- end = min(offset + page_chars, len(text))
- page = prefix + text[offset:end]
- if end < len(text):
- page += (
- f"\n\n[Characters {offset}-{end} of {len(text)}. "
- f"Call mcp_tool_schema with offset={end} for the rest.]"
- )
- if _fit_result_to_room(page, "mcp_tool_schema") == page:
- return page
- if page_chars < _MCP_MIN_SCHEMA_PAGE_CHARS:
- # The prefix may be a server's own unbounded error text.
- return _fit_result_to_room(
- (prefix or "Error: ") + "Not enough context room to read this MCP tool schema. "
- "Reduce the conversation context and retry.",
- "mcp_tool_schema",
- )
- page_chars //= 2
+def _mcp_loaded_names() -> list[str]:
+ key = _mcp_thread_key()
+ if key is None:
+ return []
+ with _MCP_LOADED_LOCK:
+ return list(_MCP_LOADED_THREADS.get(key, ()))
-def _mcp_tool_schema(name, offset = None) -> str:
- server, tool, tool_name = _mcp_resolve_tool(name)
- if not tool_name:
- return "Error: mcp_tool_schema needs an MCP tool name as listed, such as mcp__<server>__<tool>."
- if not server:
- return f"Error: MCP server for tool '{tool_name}' not found"
- display = server.get("display_name") or server["id"]
- if tool is None:
- return f"Error: MCP server '{display}' does not list a tool named '{tool_name}'"
- text = _mcp_tool_schema_text(display, tool)
- offset = 0 if offset is None else offset
- if isinstance(offset, bool) or not isinstance(offset, int) or not 0 <= offset < len(text):
- return f"Error: offset must be an integer from 0 to {len(text) - 1}."
- return _mcp_schema_page("", text, offset)
-
-
-def _mcp_compact_candidates(listed) -> list[tuple[int, dict]]:
- """(index in the flat listing, compact spec) for every large tool, largest saving first."""
- candidates: list[tuple[int, int, dict]] = []
- index = 0
- for server, payload, server_specs in listed:
- display = server.get("display_name") or server["id"]
- by_name = {tool.get("name"): tool for tool in payload if isinstance(tool, dict)}
- for spec in server_specs:
- function = spec["function"]
- tool = by_name.get(_mcp_raw_tool_name(function["name"]))
- if tool is not None and _mcp_spec_compacted(tool):
- description = function["description"].removeprefix(f"[{display}]").strip()
- compact = _mcp_compact_spec(function["name"], display, tool, description)
- saving = len(json.dumps(spec, separators = (",", ":"))) - len(
- json.dumps(compact, separators = (",", ":"))
- )
- if saving > 0:
- candidates.append((saving, index, compact))
- index += 1
- candidates.sort(key = lambda item: -item[0])
- return [(index, compact) for _, index, compact in candidates]
+def mcp_record_loaded_tools(thread_id, names) -> None:
+ """Remember tools a thread ran, so its next turns list them up front."""
+ if not isinstance(thread_id, str) or not thread_id or not names:
+ return
+ key = (current_account_id(), thread_id)
+ with _MCP_LOADED_LOCK:
+ loaded = [n for n in _MCP_LOADED_THREADS.pop(key, []) if n not in names] + list(names)
+ _MCP_LOADED_THREADS[key] = loaded[-_MCP_LOADED_PER_THREAD:]
+ while len(_MCP_LOADED_THREADS) > _MCP_LOADED_THREADS_MAX:
+ _MCP_LOADED_THREADS.popitem(last = False)
def _mcp_listing(listed: list[tuple[dict, list[dict], list[dict]]]) -> list[dict]:
@@ -13840,43 +13829,282 @@ def _mcp_listing(listed: list[tuple[dict, list[dict], list[dict]]]) -> list[dict
ctx = _MCP_LISTING_CONTEXT_TOKENS.get()
if not ctx or not specs:
return specs
- budget = ctx * _MCP_FULL_LISTING_SHARE
+ budget = ctx * _MCP_TOOL_SEARCH_SHARE
text = json.dumps(specs, separators = (",", ":"))
listing_tokens = _text_token_cost(text, ctx)
if listing_tokens <= budget:
- _MCP_COMPACTED_WINDOWS[(current_account_id(), ctx)] = frozenset()
return specs
- # Compact the largest tools first and stop once the listing fits, so every tool that can keep its nested and
- # union parameters does: dropping them costs tool-call accuracy (#11046 measurements).
- tokens_per_char = listing_tokens / max(len(text), 1)
- budget -= _text_token_cost(json.dumps(MCP_TOOL_SCHEMA_TOOL, separators = (",", ":")), ctx)
- listing = list(specs)
- candidates = _mcp_compact_candidates(listed)
- chars = len(text)
- compacted: set[str] = set()
- for position, (index, compact) in enumerate(candidates):
- chars -= len(json.dumps(listing[index], separators = (",", ":"))) - len(
- json.dumps(compact, separators = (",", ":"))
- )
- listing[index] = compact
- compacted.add(compact["function"]["name"])
- if chars * tokens_per_char > budget:
+ # Every tool is deferred, as Claude Code and Codex do: a small tool left listed beside the search tool was called
+ # in place of the right, deferred one (Qwen3-4B on Notion, #10997).
+ by_name = {spec["function"]["name"]: spec for spec in specs}
+ # Always listed: a forced tool_choice names its tool, and an attached image is refused unless the catalog
+ # lists a tool mapped to take it.
+ pinned = [_MCP_LISTING_FORCED.get()]
+ catalog = []
+ for server, payload, server_specs in listed:
+ display = server.get("display_name") or server["id"]
+ names = [_mcp_raw_tool_name(spec["function"]["name"]) for spec in server_specs]
+ # The composed name past its mcp__<server>__ prefix: a raw name can be any length, an alias cannot.
+ tools_listed = [
+ (
+ spec["function"]["name"].split("__", 2)[2],
+ _mcp_summary(
+ spec["function"]["description"].removeprefix(f"[{display}]"),
+ _MCP_TOOL_SEARCH_SUMMARY_CHARS,
+ ),
+ )
+ for spec in server_specs
+ ]
+ if names:
+ catalog.append((display, tools_listed))
+ if _MCP_LISTING_IMAGE.get():
+ tools = {tool.get("name"): tool for tool in payload if isinstance(tool, dict)}
+ pinned += [
+ spec["function"]["name"]
+ for spec, raw in zip(server_specs, names)
+ if image_mapping(server, tools.get(raw))
+ ]
+ # Halved until the finished declaration fits the share, since summaries can run a token a character.
+ max_chars = int(budget * 4)
+ search = _mcp_tool_search_spec(catalog, max_chars)
+ while max_chars and _text_token_cost(json.dumps(search, separators = (",", ":")), ctx) > budget:
+ max_chars //= 2
+ search = _mcp_tool_search_spec(catalog, max_chars)
+ listing = [search]
+ listing += [by_name[name] for name in dict.fromkeys(pinned) if name in by_name]
+ room = ctx * _MCP_TOOL_PRELOAD_SHARE - _text_token_cost(
+ json.dumps(listing, separators = (",", ":")), ctx
+ )
+ ran = [name for name in reversed(_mcp_loaded_names()) if name in by_name]
+ ranked = [specs[i]["function"]["name"] for i in _mcp_ranked(specs, _MCP_LISTING_QUERY.get())[0]]
+ for name in dict.fromkeys(ran + ranked[:_MCP_TOOL_PRELOAD]):
+ if by_name[name] in listing:
continue
- # The per-character rate is an average; confirm on the real listing before stopping short of the rest.
- if (
- position == len(candidates) - 1
- or _text_token_cost(json.dumps(listing, separators = (",", ":")), ctx) <= budget
- ):
- break
- _MCP_COMPACTED_WINDOWS[(current_account_id(), ctx)] = frozenset(compacted)
- if compacted:
- listing.append(MCP_TOOL_SCHEMA_TOOL)
+ cost = _text_token_cost(json.dumps(by_name[name], separators = (",", ":")), ctx)
+ if cost <= room:
+ listing.append(by_name[name])
+ room -= cost
return listing
-def _mcp_listing_compacted(name: str) -> bool:
- key = (current_account_id(), _window_context_tokens() or 0)
- return name in _MCP_COMPACTED_WINDOWS.get(key, frozenset())
+def _cached_mcp_catalog() -> list[dict]:
+ """Every model-visible MCP tool spec already cached for this account's enabled servers."""
+ servers = _enabled_mcp_servers(mcp_servers_db.list_servers())
+ if not stdio_mcp_enabled():
+ servers = [s for s in servers if not is_stdio(s["url"])]
+ specs: list[dict] = []
+ for server in servers:
+ payload = get_cached_tools(server["id"])
+ if payload:
+ specs.extend(
+ _mcp_specs_for_server(server, [public_tool(server, tool) for tool in payload])
+ )
+ return specs
+
+
+def mcp_loadable_specs(tools) -> list[dict]:
+ """The MCP tools a loop offering mcp_tool_search may load mid-turn, so its call detection knows their names."""
+ names = {(t.get("function") or {}).get("name") for t in tools or [] if isinstance(t, dict)}
+ return _cached_mcp_catalog() if MCP_TOOL_SEARCH_NAME in names else []
+
+
+def mcp_tool_spec(name) -> dict | None:
+ """The full spec of a cached MCP tool, for loading it into a running tool loop."""
+ if not isinstance(name, str) or not name.startswith(MCP_TOOL_PREFIX):
+ return None
+ for spec in _cached_mcp_catalog():
+ if spec["function"]["name"] == name:
+ return spec
+ return None
+
+
+def _mcp_search_text(spec: dict) -> tuple[str, str, str]:
+ function = spec["function"]
+ parameters = function.get("parameters") or {}
+ props = parameters.get("properties") if isinstance(parameters, dict) else None
+ props = props if isinstance(props, dict) else {}
+ param_text = " ".join(
+ f"{key} {value.get('description') or ''}" if isinstance(value, dict) else str(key)
+ for key, value in props.items()
+ )
+ # Names are word-split so notion-create-pages matches "create pages".
+ return re.sub(r"[_\-.]+", " ", function["name"]), function.get("description") or "", param_text
+
+
+def _mcp_search_index(specs: list[dict]) -> sqlite3.Connection:
+ rows = [_mcp_search_text(spec) for spec in specs]
+ digest = hashlib.sha256(json.dumps(rows).encode()).hexdigest()
+ cached = _MCP_SEARCH_INDEXES.get(digest)
+ if cached is not None:
+ _MCP_SEARCH_INDEXES.move_to_end(digest)
+ return cached
+ conn = sqlite3.connect(":memory:", check_same_thread = False)
+ # The RAG store's tokenizer (storage/rag_db.py chunks_fts). Names get their own table: a word every
+ # description shares ("page" on Notion) has its BM25 IDF floored to nothing there, but still tells names apart.
+ conn.execute("CREATE VIRTUAL TABLE tool_names USING fts5(name, tokenize='porter unicode61')")
+ conn.execute(
+ "CREATE VIRTUAL TABLE tool_text USING fts5(description, params, tokenize='porter unicode61')"
+ )
+ conn.executemany(
+ "INSERT INTO tool_names(rowid, name) VALUES (?, ?)", [(i, r[0]) for i, r in enumerate(rows)]
+ )
+ conn.executemany(
+ "INSERT INTO tool_text(rowid, description, params) VALUES (?, ?, ?)",
+ [(i, r[1], r[2]) for i, r in enumerate(rows)],
+ )
+ _MCP_SEARCH_INDEXES[digest] = conn
+ while len(_MCP_SEARCH_INDEXES) > 4:
+ _MCP_SEARCH_INDEXES.popitem(last = False)[1].close()
+ return conn
+
+
+def _mcp_search_limit(limit) -> int:
+ if isinstance(limit, bool) or not isinstance(limit, (int, float)) or not math.isfinite(limit):
+ return _MCP_TOOL_SEARCH_LIMIT
+ return max(1, min(_MCP_TOOL_SEARCH_MAX_LIMIT, int(limit)))
+
+
+_MCP_SEARCH_QUERY_CHARS = 2000
+# Ids and numbers ("page 195de922-...", "issue 55"); short names like ec2, s3 and v2 stay.
+_MCP_SEARCH_ID_RE = re.compile(r"\b(?:\d+|(?=[0-9a-f]*\d)[0-9a-f]{4,})\b", re.IGNORECASE)
+# Users and tool names pick different verbs for one write: "add a comment" is notion-create-comments, and an
+# unexpanded name leg ranks the update/fetch siblings that share the noun above it. Read verbs (find, get) stay
+# unexpanded: "find" -> "search" lists every search-* tool over the one the noun names.
+_MCP_VERB_GROUPS = (
+ ("create", "add", "new", "make", "insert", "append", "post", "reply"),
+ ("delete", "remove", "erase", "trash", "drop"),
+ ("update", "edit", "change", "modify", "rename", "patch"),
+)
+
+
+def _verb_forms(verb: str) -> set[str]:
+ if verb == "new": # an adjective: "news" is not "create"
+ return {verb}
+ stem = verb.removesuffix("e")
+ return {
+ verb,
+ verb + "s",
+ verb + "d",
+ verb + "ed",
+ stem + "ing",
+ verb + "ing",
+ verb + verb[-1] + "ed",
+ verb + verb[-1] + "ing",
+ verb.removesuffix("y") + "ies",
+ }
+
+
+_MCP_VERB_SYNONYMS: dict[str, tuple[str, ...]] = {
+ form: tuple(v for v in group if v != verb)
+ for group in _MCP_VERB_GROUPS
+ for verb in group
+ for form in _verb_forms(verb)
+}
+
+
+def _mcp_ranked(specs: list[dict], query) -> tuple[list[int], int]:
+ """Indexes into ``specs`` for ``query`` and how many lead as exact names (openai/codex#21503), then names and
+ descriptions ranked by BM25 and fused as the knowledge-base search fuses its legs."""
+ if not isinstance(query, str) or not query.strip() or not specs:
+ return [], 0
+ words = [w.casefold() for w in re.split(r"[\s,]+", query) if w]
+ by_name: dict[str, list[int]] = {}
+ for i, spec in enumerate(specs):
+ name = spec["function"]["name"]
+ for key in dict.fromkeys((name.casefold(), _mcp_raw_tool_name(name).casefold())):
+ by_name.setdefault(key, []).append(i)
+ # A raw name two servers share ("search") is both of their tools.
+ exact = list(dict.fromkeys(i for w in words for i in by_name.get(w, ())))
+ if exact and all(w in by_name for w in words):
+ return exact, len(exact)
+ from core.rag import config as rag_config, retrieval # noqa: PLC0415 -- RAG ranking, imported lazily
+ from core.rag.store import conversation_match_queries # noqa: PLC0415
+
+ # A long paste would OR thousands of terms (seconds per request).
+ query = query[:_MCP_SEARCH_QUERY_CHARS]
+ expressions = conversation_match_queries(
+ _MCP_SEARCH_ID_RE.sub(" ", query)
+ ) or conversation_match_queries(query)
+ rankings: list[list] = []
+ if expressions:
+ synonyms = dict.fromkeys(
+ v
+ for w in re.findall(r"[a-z]+", query.casefold())
+ for v in _MCP_VERB_SYNONYMS.get(w, ())
+ )
+ name_expression = " OR ".join([expressions[-1], *(f'"{v}"' for v in synonyms)])
+ with _MCP_SEARCH_LOCK:
+ conn = _mcp_search_index(specs)
+ for sql, expression in (
+ (
+ "SELECT rowid, bm25(tool_names) AS s FROM tool_names WHERE tool_names MATCH ? "
+ "ORDER BY s LIMIT ?",
+ name_expression,
+ ),
+ (
+ "SELECT rowid, bm25(tool_text, 1.0, 0.3) AS s FROM tool_text WHERE tool_text MATCH ? "
+ "ORDER BY s LIMIT ?",
+ expressions[-1],
+ ),
+ ):
+ rows = conn.execute(sql, (expression, 4 * _MCP_TOOL_SEARCH_MAX_LIMIT))
+ rankings.append([retrieval.Hit(str(rowid), -score) for rowid, score in rows])
+ ranked = [int(hit.chunk_id) for hit in retrieval._rrf(rankings, rag_config.RRF_K, len(specs))]
+ return list(dict.fromkeys(exact + ranked)), len(exact)
+
+
+def mcp_fit_loaded(specs: list[dict]) -> list[dict]:
+ """The leading ``specs`` (newest first) that fit the share of the window a turn's loaded tools may take."""
+ ctx = _MCP_LISTING_CONTEXT_TOKENS.get() or _window_context_tokens()
+ if not ctx:
+ return list(specs)
+ room = ctx * _MCP_TOOL_LOAD_SHARE
+ fitted = []
+ for spec in specs:
+ cost = _text_token_cost(json.dumps(spec, separators = (",", ":")), ctx)
+ if cost <= room:
+ fitted.append(spec)
+ room -= cost
+ return fitted
+
+
+def _mcp_search_matches(arguments) -> tuple[list[dict], list[dict]]:
+ """(the cached MCP tools a mcp_tool_search call loads, the matches too large to)."""
+ arguments = arguments if isinstance(arguments, dict) else {}
+ specs = _cached_mcp_catalog()
+ order, exact = _mcp_ranked(specs, arguments.get("query"))
+ picked = [specs[i] for i in order[: max(_mcp_search_limit(arguments.get("limit")), exact)]]
+ fitted = mcp_fit_loaded(picked)
+ return fitted, [spec for spec in picked if spec not in fitted]
+
+
+def mcp_tool_search_specs(arguments) -> list[dict]:
+ """The cached MCP tools a mcp_tool_search call loads: exact names first, then the best matches, while they
+ fit the window's load share (five Notion query tools are more schema than a 32K window)."""
+ return _mcp_search_matches(arguments)[0]
+
+
+def _mcp_tool_search(arguments) -> str:
+ query = arguments.get("query") if isinstance(arguments, dict) else None
+ if not isinstance(query, str) or not query.strip():
+ return "Error: mcp_tool_search needs a query naming the action you need."
+ found, too_large = _mcp_search_matches(arguments)
+ if not found and too_large:
+ names = ", ".join(spec["function"]["name"] for spec in too_large)
+ return f"Error: the matching MCP tools ({names}) are too large for this model's context window."
+ if not found:
+ return (
+ f"No MCP tool matched '{query.strip()}'. Try other keywords, or one of the tool names "
+ f"listed in the {MCP_TOOL_SEARCH_NAME} description."
+ )
+ lines = [
+ f"- {spec['function']['name']}: {_mcp_summary(spec['function'].get('description') or '')}"
+ for spec in found
+ ]
+ return (
+ f"Loaded {len(found)} MCP tool{'s' if len(found) != 1 else ''}. Call the one that fits directly, "
+ "with the parameters in its schema:\n" + "\n".join(lines)
+ )
def _mcp_tool_names(server: dict, mcp_tools: list[dict]) -> dict[str, str]:
@@ -14340,8 +14568,8 @@ def execute_tool(
)
if name == "render_html":
return _fit_result_to_room(_render_html_result(arguments), name)
- if name == "mcp_tool_schema":
- return _mcp_tool_schema(arguments.get("name"), arguments.get("offset"))
+ if name == MCP_TOOL_SEARCH_NAME:
+ return _fit_result_to_room(_mcp_tool_search(arguments), name)
if name.startswith(MCP_TOOL_PREFIX):
# An MCP server is not inside the terminal sandbox, so the local refusal has to hold here too.
if _mcp_arguments_reference_studio_credential(arguments):
@@ -14360,23 +14588,12 @@ def execute_tool(
return f"Error: MCP server '{display}' is disabled"
if is_stdio(server["url"]) and not stdio_mcp_enabled():
return f"Error: stdio MCP server '{display}' is disabled on this host"
- tool = _mcp_cached_tool(server, tool_name) if _mcp_listing_compacted(name) else None
- if tool is not None and isinstance(arguments, dict):
- missing = [
- key for key in _mcp_input_schema(tool).get("required") or [] if key not in arguments
- ]
- if missing:
- return _mcp_schema_page(
- f"Error: MCP tool '{tool_name}' requires {', '.join(missing)}.\n\n",
- _mcp_tool_schema_text(display, tool),
- 0,
- )
mcp_scope = mcp_session_scope(session_id, thread_id)
headers = parse_server_headers(server)
url = server["url"]
use_oauth = bool(server.get("use_oauth"))
mapping = (
- image_mapping(server, tool or _mcp_cached_tool(server, tool_name))
+ image_mapping(server, _mcp_cached_tool(server, tool_name))
if image_input_mappings(server) and isinstance(arguments, dict)
else None
)
@@ -14393,7 +14610,7 @@ def execute_tool(
# Re-read the row: an edit while the approval card was open must not redirect the image.
fresh = mcp_servers_db.get_server(server_id)
fresh_mapping = (
- image_mapping(fresh, tool or _mcp_cached_tool(fresh, tool_name)) if fresh else None
+ image_mapping(fresh, _mcp_cached_tool(fresh, tool_name)) if fresh else None
)
if not (
fresh_mapping
@@ -14409,7 +14626,7 @@ def execute_tool(
# Checked again at dispatch: a call can wait behind a stdio session lock after the re-read above.
if not carries_image:
return True
- current = image_mapping(row, tool or _mcp_cached_tool(row, tool_name))
+ current = image_mapping(row, _mcp_cached_tool(row, tool_name))
return bool(current) and _mcp_image_recipient(row, current) == mcp_image.recipient
def _config_current() -> bool:
@@ -14449,10 +14666,6 @@ def execute_tool(
+ "\n[Images the tool returned were withheld from the model.]"
)
result = mcp_image.redact(result)
- if tool is not None and isinstance(result, str) and result.startswith("Error:"):
- return _mcp_schema_page(
- result.rstrip() + "\n\n", _mcp_tool_schema_text(display, tool), 0
- )
return _fit_result_to_room(result, name)
if name == "deep_research":
if not str(arguments.get("question") or "").strip():
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 480ddb620ed..15ef11d4a77 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -5299,7 +5299,10 @@ def _confirm_gate_needs_stream(payload, selected_names = None) -> bool:
# web_search prompts once the model supplies a ``url`` (it fetches that page), and the
# gate can only prompt while streaming. Without this a non-streaming auto request is
# admitted, then blocks in wait_tool_decision on an approval the client never reads.
- return not all(is_always_safe_tool(t) and t != "web_search" for t in enabled)
+ # mcp_tool_search loads MCP tools, which can prompt, into the same turn.
+ return not all(
+ is_always_safe_tool(t) and t not in ("web_search", "mcp_tool_search") for t in enabled
+ )
class _AutoPermissionMode:
@@ -31777,7 +31780,13 @@ async def produce_openai_chat_completions(
if use_tools:
from core.inference.tools import set_mcp_listing_context_tokens
- set_mcp_listing_context_tokens(getattr(llama_backend, "context_length", None))
+ set_mcp_listing_context_tokens(
+ getattr(llama_backend, "context_length", None),
+ payload.thread_id,
+ payload.messages,
+ payload.tool_choice,
+ getattr(payload, "mcp_image", None),
+ )
tools_to_use = await _select_request_tools(
payload,
supports_vision = bool(getattr(llama_backend, "is_vision", False)),
@@ -33953,7 +33962,13 @@ async def produce_openai_chat_completions(
if _sf_use_tools:
from core.inference.tools import set_mcp_listing_context_tokens
- set_mcp_listing_context_tokens(_monitor_context_length())
+ set_mcp_listing_context_tokens(
+ _monitor_context_length(),
+ payload.thread_id,
+ payload.messages,
+ payload.tool_choice,
+ getattr(payload, "mcp_image", None),
+ )
_sf_tools_to_use = await _select_request_tools(
payload,
tools_on = _sf_tools_on,
@@ -41193,7 +41208,13 @@ async def _mlx_count_chat_tokens(
from core.inference.mcp_client import mcp_server_snapshot_guard
from core.inference.tools import cached_mcp_tools, set_mcp_listing_context_tokens
- set_mcp_listing_context_tokens(_monitor_context_length())
+ set_mcp_listing_context_tokens(
+ _monitor_context_length(),
+ getattr(payload, "thread_id", None),
+ payload.messages,
+ getattr(payload, "tool_choice", None),
+ getattr(payload, "mcp_image", None),
+ )
# A database read, so off the loop. Guarded as the GGUF count guards it, or
# an interleaving edit pairs a new row with the schema cached before it.
@@ -41596,7 +41617,13 @@ async def chat_count_tokens(
if _mcp_on and not _takes_passthrough and llama_backend.supports_tools:
from core.inference.tools import cached_mcp_tools, set_mcp_listing_context_tokens
- set_mcp_listing_context_tokens(getattr(llama_backend, "context_length", None))
+ set_mcp_listing_context_tokens(
+ getattr(llama_backend, "context_length", None),
+ getattr(payload, "thread_id", None),
+ payload.messages,
+ getattr(payload, "tool_choice", None),
+ getattr(payload, "mcp_image", None),
+ )
from core.inference.mcp_client import mcp_server_snapshot_guard
# Keep the SQLite read off-loop while coordinating the row/cache snapshot with edits.
diff --git a/studio/backend/tests/test_llama_cpp_tool_loop.py b/studio/backend/tests/test_llama_cpp_tool_loop.py
index 646e438a2c2..6f8e937232e 100644
--- a/studio/backend/tests/test_llama_cpp_tool_loop.py
+++ b/studio/backend/tests/test_llama_cpp_tool_loop.py
@@ -7338,6 +7338,40 @@ def test_nested_object_schema_is_relaxed_on_the_wire_but_not_in_the_loop(monkeyp
]
+def test_an_mcp_tool_search_leaves_a_budget_of_one_for_the_tool_it_found(monkeypatch):
+ """Loading deferred MCP tools is not a tool round (#10997)."""
+ from core.inference import tools as tools_mod
+
+ ping = {
+ "type": "function",
+ "function": {
+ "name": "mcp__srv1__ping",
+ "description": "[A] Ping.",
+ "parameters": {"type": "object"},
+ },
+ }
+ monkeypatch.setattr(tools_mod, "mcp_tool_search_specs", lambda arguments: [ping])
+ monkeypatch.setattr(tools_mod, "mcp_loadable_specs", lambda tools: [ping])
+ monkeypatch.setattr(tools_mod, "mcp_record_loaded_tools", lambda *a: None)
+ streams = [
+ _structured_tool_call("mcp_tool_search", {"query": "ping"}, "call_search"),
+ _structured_tool_call("mcp__srv1__ping", {}, "call_ping"),
+ [_sse({"content": "Pinged."}), _done()],
+ ]
+ backend, payloads = _backend_and_payloads(monkeypatch, streams)
+ calls = _record_tool_calls(monkeypatch, "ok")
+
+ _run_tool_loop(
+ backend,
+ [{"role": "user", "content": "ping it"}],
+ [tools_mod._mcp_tool_search_spec([])],
+ max_tool_iterations = 1,
+ )
+
+ assert [name for name, _ in calls] == ["mcp_tool_search", "mcp__srv1__ping"]
+ assert "mcp__srv1__ping" in [t["function"]["name"] for t in payloads[1].get("tools", [])]
+
+
def test_budget_exhausted_final_pass_keeps_the_cached_tool_catalogue(monkeypatch):
# The template renders tools at the top of the system prompt. Dropping them on the final
# pass changed the prompt from its first tokens, so llama-server re-processed the whole
diff --git a/studio/backend/tests/test_mcp_image.py b/studio/backend/tests/test_mcp_image.py
index 7418f616146..f05dbb2f70d 100644
--- a/studio/backend/tests/test_mcp_image.py
+++ b/studio/backend/tests/test_mcp_image.py
@@ -58,7 +58,6 @@ def mapped_server(tmp_path, monkeypatch):
monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
monkeypatch.setattr(mcp_servers_db, "_schema_ready", set())
monkeypatch.setattr(mcp_client, "_tool_cache", {})
- monkeypatch.setattr(tools_mod, "_MCP_COMPACTED_WINDOWS", {})
mcp_servers_db.create_server(
id = "srv1",
display_name = "Trace",
diff --git a/studio/backend/tests/test_mcp_servers.py b/studio/backend/tests/test_mcp_servers.py
index a3453a33066..13be7b45ab7 100644
--- a/studio/backend/tests/test_mcp_servers.py
+++ b/studio/backend/tests/test_mcp_servers.py
@@ -2,6 +2,7 @@
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import json
+from collections import OrderedDict
import pytest
from fastapi import HTTPException
@@ -2224,7 +2225,7 @@ def _cache_server_tools(tmp_path, monkeypatch, tools):
_reset_db(tmp_path, monkeypatch)
monkeypatch.setattr(mcp_client, "_tool_cache", {})
- monkeypatch.setattr(tools_mod, "_MCP_COMPACTED_WINDOWS", {})
+ monkeypatch.setattr(tools_mod, "_MCP_LOADED_THREADS", OrderedDict())
mcp_servers_db.create_server(id = "srv1", display_name = "A", url = "https://a.example/mcp")
mcp_client.cache_tools("srv1", tools)
@@ -2245,9 +2246,9 @@ def listing_window():
@pytest.fixture
-def compacting(monkeypatch, listing_window):
+def searching(monkeypatch, listing_window):
from core.inference import tools as tools_mod
- monkeypatch.setattr(tools_mod, "_MCP_FULL_LISTING_SHARE", 0.0)
+ monkeypatch.setattr(tools_mod, "_MCP_TOOL_SEARCH_SHARE", 0.0)
return listing_window(100_000)
@@ -2261,109 +2262,66 @@ _PING = {
}
+def _names(specs):
+ return [s["function"]["name"] for s in specs]
+
+
+def _search_spec(specs):
+ return next(s for s in specs if s["function"]["name"] == "mcp_tool_search")
+
+
def test_mcp_listing_stays_full_when_it_fits_the_window(tmp_path, monkeypatch, listing_window):
from core.inference import tools as tools_mod
_cache_server_tools(tmp_path, monkeypatch, [_PING, _big_mcp_tool()])
unsized = tools_mod.cached_mcp_tools()[0]
- assert [s["function"]["name"] for s in unsized] == ["mcp__srv1__ping", "mcp__srv1__query"]
+ assert _names(unsized) == ["mcp__srv1__ping", "mcp__srv1__query"]
assert unsized[1]["function"]["parameters"] == _big_mcp_tool()["inputSchema"]
listing_window(1_000_000)
assert tools_mod.cached_mcp_tools()[0] == unsized
- assert list(tools_mod._MCP_COMPACTED_WINDOWS.values()) == [frozenset()]
listing_window(1_000)
specs = tools_mod.cached_mcp_tools()[0]
- assert tools_mod._MCP_COMPACTED_WINDOWS[(tools_mod.current_account_id(), 1_000)] == {
- "mcp__srv1__query"
- }
- assert specs[0] == unsized[0]
- assert specs[1]["function"]["parameters"] != unsized[1]["function"]["parameters"]
- assert specs[2] == tools_mod.MCP_TOOL_SCHEMA_TOOL
+ assert _names(specs) == ["mcp_tool_search"]
+ # Too small to name them within its share, so it only counts them.
+ assert _search_spec(specs)["function"]["description"].endswith(
+ "Tools:\n2 tools, found by searching."
+ )
-def test_mcp_listing_compacts_only_the_largest_tools_it_needs_to(
- tmp_path, monkeypatch, listing_window
-):
- from core.inference import tools as tools_mod
+def test_mcp_listing_defers_every_tool_past_its_share(tmp_path, monkeypatch, listing_window):
+ from core.inference import mcp_client, tools as tools_mod
huge = dict(_big_mcp_tool(), name = "huge")
huge["inputSchema"] = dict(huge["inputSchema"], description = "z" * 20_000)
_cache_server_tools(tmp_path, monkeypatch, [_PING, _big_mcp_tool(), huge])
+ mcp_servers_db.create_server(id = "srv2", display_name = "B", url = "https://b.example/mcp")
+ mcp_client.cache_tools("srv2", [{"name": "echo"}])
full = tools_mod.cached_mcp_tools()[0]
full_tokens = tools_mod._text_token_cost(json.dumps(full, separators = (",", ":")), 10_000)
- ctx = listing_window(int(full_tokens * 0.9 / tools_mod._MCP_FULL_LISTING_SHARE))
- specs = tools_mod.cached_mcp_tools()[0]
- assert tools_mod._MCP_COMPACTED_WINDOWS[(tools_mod.current_account_id(), ctx)] == {
- "mcp__srv1__huge"
- }
- assert specs[:2] == full[:2]
- assert specs[2]["function"]["parameters"] != full[2]["function"]["parameters"]
- assert specs[3] == tools_mod.MCP_TOOL_SCHEMA_TOOL
- listed = tools_mod._text_token_cost(json.dumps(specs, separators = (",", ":")), ctx)
- assert listed <= ctx * tools_mod._MCP_FULL_LISTING_SHARE
-
- monkeypatch.setattr(tools_mod, "_window_context_tokens", lambda: ctx)
- assert tools_mod._mcp_listing_compacted("mcp__srv1__huge")
- assert not tools_mod._mcp_listing_compacted("mcp__srv1__query")
-
-
-def test_mcp_listing_never_compacts_a_tool_its_compact_form_would_enlarge(
- tmp_path, monkeypatch, compacting
-):
- from core.inference import tools as tools_mod
-
- loose = {
- "name": "loose",
- "description": "Takes anything.",
- "inputSchema": {"type": "object", "properties": {f"p{i}": {} for i in range(200)}},
- }
- _cache_server_tools(tmp_path, monkeypatch, [_PING, loose])
+ # Over the share by a little: the small tools are deferred too, so none is called in place of a deferred one.
+ listing_window(int(full_tokens * 0.9 / tools_mod._MCP_TOOL_SEARCH_SHARE))
specs = tools_mod.cached_mcp_tools()[0]
- assert specs[1]["function"]["parameters"] == loose["inputSchema"]
- assert tools_mod.MCP_TOOL_SCHEMA_TOOL not in specs
-
-
-def test_compacted_tools_are_remembered_per_account(tmp_path, monkeypatch, compacting):
- from core.inference import tools as tools_mod
-
- _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
- monkeypatch.setattr(tools_mod, "_window_context_tokens", lambda: compacting)
- monkeypatch.setattr(tools_mod, "current_account_id", lambda: "alice")
- tools_mod.cached_mcp_tools()
- assert tools_mod._mcp_listing_compacted("mcp__srv1__query")
-
- # Another account whose catalog fits the same window lists in full.
- monkeypatch.setattr(tools_mod, "current_account_id", lambda: "bob")
- monkeypatch.setattr(tools_mod, "_MCP_FULL_LISTING_SHARE", 1.0)
- tools_mod.cached_mcp_tools()
- assert not tools_mod._mcp_listing_compacted("mcp__srv1__query")
-
- monkeypatch.setattr(tools_mod, "current_account_id", lambda: "alice")
- assert tools_mod._mcp_listing_compacted("mcp__srv1__query")
+ assert _names(specs) == ["mcp_tool_search"]
+ assert _search_spec(specs)["function"]["description"].endswith(
+ "Tools:\nA:\n- ping: Ping.\n- query: Query rows.\n- huge: Query rows.\nB:\n- echo"
+ )
+ listing_window(int(full_tokens * 1.1 / tools_mod._MCP_TOOL_SEARCH_SHARE))
+ assert tools_mod.cached_mcp_tools()[0] == full
-def test_mcp_listing_compacts_large_schemas(tmp_path, monkeypatch, compacting):
+def test_mcp_tool_search_lists_a_bounded_number_of_names(monkeypatch):
from core.inference import tools as tools_mod
- _cache_server_tools(tmp_path, monkeypatch, [_PING, _big_mcp_tool()])
- specs = tools_mod.cached_mcp_tools()[0]
- assert specs[0]["function"]["description"] == "[A] Ping. Returns pong."
- assert specs[0]["function"]["parameters"] == _PING["inputSchema"]
- compact = specs[1]["function"]
- assert compact["name"] == "mcp__srv1__query"
- assert compact["description"] == "[A] Query rows. Full parameters via mcp_tool_schema."
- assert compact["parameters"] == {
- "type": "object",
- "properties": {
- "data": {"type": "object"},
- "mode": {"type": "string", "enum": ["sql", "rows"]},
- "tags": {"type": "array"},
- },
- "required": ["data"],
- }
+ monkeypatch.setattr(tools_mod, "_MCP_TOOL_SEARCH_MAX_NAMES", 2)
+ spec = tools_mod._mcp_tool_search_spec(
+ [("A", [("a", "Does a."), ("b", ""), ("c", "")]), ("B", [("d", "")])]
+ )
+ assert spec["function"]["description"].endswith(
+ "Tools:\nA:\n- a: Does a.\n- b\n- and 1 more\nB:\n- and 1 more"
+ )
def test_mcp_summary_caps_a_description_without_a_sentence_end():
@@ -2375,226 +2333,372 @@ def test_mcp_summary_caps_a_description_without_a_sentence_end():
assert len(long) == 240 and long.endswith("...")
-def test_mcp_tool_lists_offer_the_schema_tool_only_when_something_was_compacted(
- tmp_path, monkeypatch, compacting
+def test_mcp_tool_lists_offer_the_search_tool_only_when_something_was_deferred(
+ tmp_path, monkeypatch, searching
):
import asyncio
from core.inference import mcp_client, tools as tools_mod
- _cache_server_tools(tmp_path, monkeypatch, [{"name": "ping"}])
- specs, complete = tools_mod.cached_mcp_tools()
- assert complete is True
- assert [s["function"]["name"] for s in specs] == ["mcp__srv1__ping"]
- assert asyncio.run(tools_mod.get_enabled_mcp_tools()) == specs
+ _cache_server_tools(tmp_path, monkeypatch, [])
+ assert tools_mod.cached_mcp_tools() == ([], True)
mcp_client.cache_tools("srv1", [{"name": "ping"}, _big_mcp_tool()])
- names = [s["function"]["name"] for s in tools_mod.cached_mcp_tools()[0]]
- assert names == ["mcp__srv1__ping", "mcp__srv1__query", "mcp_tool_schema"]
- assert [s["function"]["name"] for s in asyncio.run(tools_mod.get_enabled_mcp_tools())] == names
+ names = _names(tools_mod.cached_mcp_tools()[0])
+ assert names == ["mcp_tool_search"]
+ assert _names(asyncio.run(tools_mod.get_enabled_mcp_tools())) == names
-def test_execute_tool_answers_a_compacted_call_missing_required_args_with_its_schema(
- tmp_path, monkeypatch, compacting
-):
+_NOTES = [
+ _PING,
+ _big_mcp_tool(),
+ {"name": "create-pages", "description": "Create one or more pages in a workspace."},
+ {"name": "move-pages", "description": "Move pages to a new parent page."},
+ {"name": "get-users", "description": "List the users in the workspace."},
+]
+
+
+def test_mcp_tool_search_loads_exact_names_then_ranked_matches(tmp_path, monkeypatch):
from core.inference import tools as tools_mod
- _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
- tools_mod.cached_mcp_tools()
- calls = []
- monkeypatch.setattr(tools_mod, "call_tool_sync", lambda **kwargs: calls.append(kwargs) or "ran")
+ _cache_server_tools(tmp_path, monkeypatch, _NOTES)
+ search = tools_mod.mcp_tool_search_specs
- out = tools_mod.execute_tool("mcp__srv1__query", {"mode": "sql"}, context_tokens = compacting)
- assert out.startswith("Error: MCP tool 'query' requires data.\n\n[A] query: Query rows.")
- assert json.dumps(_big_mcp_tool()["inputSchema"], separators = (",", ":")) in out
- assert calls == []
+ assert _names(search({"query": "mcp__srv1__query"})) == ["mcp__srv1__query"]
+ assert _names(search({"query": "move-pages, get-users"})) == [
+ "mcp__srv1__move-pages",
+ "mcp__srv1__get-users",
+ ]
+ assert _names(search({"query": "create a new page"}))[0] == "mcp__srv1__create-pages"
+ assert _names(search({"query": "move my page under another parent", "limit": 1})) == [
+ "mcp__srv1__move-pages"
+ ]
+ assert _names(search({"query": "who are the users"})) == ["mcp__srv1__get-users"]
+ # An exact name loads whatever the ranked matches are (openai/codex#21503).
+ assert _names(search({"query": "ping and the users", "limit": 1})) == ["mcp__srv1__ping"]
+ assert search({"query": " "}) == search({}) == []
- assert (
- tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = compacting) == "ran"
+ out = tools_mod.execute_tool("mcp_tool_search", {"query": "query rows with sql"})
+ assert out.startswith("Loaded 1 MCP tool. Call the one that fits directly")
+ assert "- mcp__srv1__query: [A] Query rows." in out
+ assert tools_mod.execute_tool("mcp_tool_search", {"query": "zzzz"}).startswith(
+ "No MCP tool matched 'zzzz'."
)
- assert calls[0]["name"] == "query" and calls[0]["args"] == {"data": {}}
+ assert tools_mod.execute_tool("mcp_tool_search", {}).startswith(
+ "Error: mcp_tool_search needs a query"
+ )
+ assert not tools_mod.is_potentially_unsafe_tool_call("mcp_tool_search", {"query": "x"})
+ assert not tools_mod.is_high_risk_tool_call("mcp_tool_search", {"query": "x"})
+
+def test_mcp_listing_lists_the_tools_the_user_message_asks_for(tmp_path, monkeypatch, searching):
+ import contextvars
-def test_execute_tool_returns_the_schema_with_a_rejected_compacted_call(
- tmp_path, monkeypatch, listing_window
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, _NOTES)
+
+ def listing_for(messages, thread_id = None):
+ ctx = contextvars.copy_context()
+ ctx.run(tools_mod.set_mcp_listing_context_tokens, searching, thread_id, messages)
+ return ctx.run(lambda: _names(tools_mod.cached_mcp_tools()[0]))
+
+ ask = [{"role": "user", "content": "Move my roadmap page under the Archive page."}]
+ listed = listing_for(ask)
+ assert listed[:2] == ["mcp_tool_search", "mcp__srv1__move-pages"]
+ assert len(listed) <= 1 + tools_mod._MCP_TOOL_PRELOAD
+ assert listing_for([{"role": "user", "content": "hello"}]) == ["mcp_tool_search"]
+ # Nothing ranked fits a window this small, so only the search tool is listed.
+ monkeypatch.setattr(tools_mod, "_MCP_TOOL_PRELOAD_SHARE", 0.0)
+ assert listing_for(ask) == ["mcp_tool_search"]
+
+
+def test_mcp_listing_matches_a_write_verb_to_the_tool_named_with_another(
+ tmp_path, monkeypatch, searching
):
+ """ "Add a comment" lists create-comments, not only the update/fetch siblings sharing its noun (#13601)."""
+ import contextvars
+
from core.inference import tools as tools_mod
- _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
- rejected = "Error: data: 'q' is a required property"
- monkeypatch.setattr(tools_mod, "call_tool_sync", lambda **kwargs: rejected)
- schema = json.dumps(_big_mcp_tool()["inputSchema"], separators = (",", ":"))
+ catalog = [
+ {"name": "search-pages", "description": "Search pages in the workspace by title or text."},
+ {"name": "fetch-page", "description": "Fetch a page and its content by page id."},
+ {"name": "fetch-comment", "description": "Fetch one comment on a page by comment id."},
+ {"name": "search-comments", "description": "Search comments on a page."},
+ {"name": "update-comment", "description": "Update the text of a comment by comment id."},
+ {
+ "name": "create-comments",
+ "description": "Start a discussion on a page, or reply to one.",
+ },
+ {"name": "delete-page", "description": "Move a page to the trash."},
+ ]
+ _cache_server_tools(tmp_path, monkeypatch, catalog)
+ monkeypatch.setattr(tools_mod, "_MCP_TOOL_PRELOAD", 3)
- fits = listing_window(1_000_000)
- tools_mod.cached_mcp_tools()
- assert (
- tools_mod.execute_tool("mcp__srv1__query", {"mode": "sql"}, context_tokens = fits) == rejected
- )
- assert tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = fits) == rejected
+ def listing_for(prompt):
+ ctx = contextvars.copy_context()
+ messages = [{"role": "user", "content": prompt}]
+ ctx.run(tools_mod.set_mcp_listing_context_tokens, searching, None, messages)
+ return ctx.run(lambda: _names(tools_mod.cached_mcp_tools()[0]))
- monkeypatch.setattr(tools_mod, "_MCP_FULL_LISTING_SHARE", 0.0)
- overflows = listing_window(100_000)
- tools_mod.cached_mcp_tools()
- out = tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = overflows)
- assert out == rejected + "\n\n" + tools_mod._mcp_tool_schema_text("A", _big_mcp_tool())
- assert schema in out
+ add = listing_for("Add a comment to the Roadmap Q3 page saying the launch moved to September.")
+ assert "mcp__srv1__create-comments" in add
+ assert "mcp__srv1__delete-page" in listing_for("Remove the Roadmap Q3 page.")
+ assert "mcp__srv1__update-comment" in listing_for("Edit my comment on the Roadmap page.")
+ # Read verbs are not expanded, so "find" does not pull every search tool in.
+ assert tools_mod._MCP_VERB_SYNONYMS.get("find") is None
+ assert tools_mod._MCP_VERB_SYNONYMS.get("news") is None
-def test_a_rejected_compacted_call_stays_within_the_room_left(tmp_path, monkeypatch, compacting):
+def test_mcp_tool_search_exact_name_loads_it_on_every_server(tmp_path, monkeypatch):
+ from core.inference import mcp_client, tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [{"name": "search", "description": "Search A."}])
+ mcp_servers_db.create_server(id = "srv2", display_name = "B", url = "https://b.example/mcp")
+ mcp_client.cache_tools("srv2", [{"name": "search", "description": "Search B."}])
+ assert _names(tools_mod.mcp_tool_search_specs({"query": "search"})) == [
+ "mcp__srv1__search",
+ "mcp__srv2__search",
+ ]
+
+
+def test_mcp_tool_search_never_finds_an_app_only_tool(tmp_path, monkeypatch, searching):
from core.inference import tools as tools_mod
- _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
- rejected = "Error: " + "invalid value " * 2_000
- monkeypatch.setattr(tools_mod, "call_tool_sync", lambda **kwargs: rejected)
- monkeypatch.setattr(tools_mod, "_fit_result_to_room", lambda text, name = None: text[:200])
- tools_mod.cached_mcp_tools()
- out = tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = compacting)
- assert out == rejected[:200]
+ hidden = {
+ "name": "widget_refresh",
+ "description": "Refresh the widget.",
+ "_meta": {"ui": {"visibility": ["app"]}},
+ }
+ _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool(), hidden])
+ specs = tools_mod.cached_mcp_tools()[0]
+ assert "widget_refresh" not in json.dumps(specs)
+ assert tools_mod.mcp_tool_search_specs({"query": "refresh the widget"}) == []
+ assert tools_mod.mcp_tool_spec("mcp__srv1__widget_refresh") is None
-def test_execute_tool_mcp_tool_schema(tmp_path, monkeypatch):
+def test_mcp_tool_search_finds_an_alias_by_its_raw_name(tmp_path, monkeypatch):
from core.inference import tools as tools_mod
- _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
- out = tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__srv1__query"})
- assert out.startswith("[A] query: Query rows. Use SQL mode by default. Long details follow.")
- assert out.endswith(json.dumps(_big_mcp_tool()["inputSchema"], separators = (",", ":")))
- assert (
- tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__srv1__nope"})
- == "Error: MCP server 'A' does not list a tool named 'nope'"
- )
- assert (
- tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__missing__query"})
- == "Error: MCP server for tool 'query' not found"
- )
- assert tools_mod.execute_tool("mcp_tool_schema", {"name": "query"}).startswith(
- "Error: mcp_tool_schema needs an MCP tool name"
- )
- assert not tools_mod.is_potentially_unsafe_tool_call("mcp_tool_schema", {"name": "x"})
- assert not tools_mod.is_high_risk_tool_call("mcp_tool_schema", {"name": "x"})
+ tool = dict(_big_mcp_tool(), name = "catalog.query")
+ _cache_server_tools(tmp_path, monkeypatch, [tool])
+ found = tools_mod.mcp_tool_search_specs({"query": "catalog.query"})
+ assert len(found) == 1
+ assert found[0]["function"]["name"] != "mcp__srv1__catalog.query"
+ assert found[0]["function"]["parameters"] == tool["inputSchema"]
-def test_mcp_compact_parameters_never_emit_an_empty_schema():
- from core.inference.tools import _mcp_compact_parameters
+def test_controller_loads_searched_and_named_mcp_tools(tmp_path, monkeypatch, searching):
+ import contextvars
- compact = _mcp_compact_parameters(
- {
- "type": "object",
- "properties": {
- "labels": {"type": "array", "items": {"type": "string"}},
- "assignees": {
- "anyOf": [{"type": "array", "items": {"type": "string"}}, {"type": "null"}]
- },
- "state": {"$ref": "#/$defs/State"},
- },
- }
- )
- assert compact["properties"] == {
- "labels": {"type": "array"},
- "assignees": {"type": ["array", "null"]},
- "state": {"description": "See mcp_tool_schema."},
+ from core.inference import tools as tools_mod
+ from core.inference.tool_loop_controller import ToolLoopController
+
+ _cache_server_tools(tmp_path, monkeypatch, _NOTES)
+
+ def listing_for(thread_id):
+ ctx = contextvars.copy_context()
+ ctx.run(tools_mod.set_mcp_listing_context_tokens, searching, thread_id)
+ return ctx.run(lambda: tools_mod.cached_mcp_tools()[0])
+
+ listing = listing_for("thread-1")
+ assert _names(listing) == ["mcp_tool_search"]
+
+ controller = ToolLoopController(tools = listing, thread_id = "thread-1")
+ call = {
+ "function": {"name": "mcp_tool_search", "arguments": '{"query": "move pages", "limit": 1}'}
}
- assert _mcp_compact_parameters({"$ref": "#/$defs/Args"}) == {"type": "object"}
+ decision = controller.prepare_call(call)
+ controller.record_result(
+ decision, tools_mod.execute_tool("mcp_tool_search", decision.arguments)
+ )
+ active = controller.active_tools()
+ assert _names(active) == ["mcp_tool_search", "mcp__srv1__move-pages"]
+ assert active[1] == tools_mod.mcp_tool_spec("mcp__srv1__move-pages")
+
+ # A deferred tool named without a search loads too, typed by its full schema.
+ named = controller.prepare_call(
+ {"function": {"name": "mcp__srv1__ping", "arguments": '{"n": "3"}'}}
+ )
+ assert named.action == "execute" and named.arguments == {"n": 3}
+ assert "mcp__srv1__ping" in _names(controller.active_tools())
+
+ # Later turns of the thread list the tools it ran, newest first; a tool only loaded is not relisted.
+ assert _names(listing_for("thread-1")) == ["mcp_tool_search"]
+ controller.record_result(named, "pong")
+ moved = controller.prepare_call(
+ {"function": {"name": "mcp__srv1__move-pages", "arguments": "{}"}}
+ )
+ controller.record_result(moved, "moved")
+ assert _names(listing_for("thread-1")) == [
+ "mcp_tool_search",
+ "mcp__srv1__move-pages",
+ "mcp__srv1__ping",
+ ]
+ assert _names(listing_for("thread-2")) == ["mcp_tool_search"]
+ # Relisted tools share the preload room, so a small window drops them rather than overflow.
+ monkeypatch.setattr(tools_mod, "_MCP_TOOL_PRELOAD_SHARE", 0.0)
+ assert _names(listing_for("thread-1")) == ["mcp_tool_search"]
-def test_compacted_mcp_call_arguments_are_typed_by_the_full_schema(
- tmp_path, monkeypatch, compacting
-):
+def test_a_search_loads_only_what_fits_the_window(tmp_path, monkeypatch):
from core.inference import tools as tools_mod
- from core.inference.tool_loop_controller import coerce_tool_arguments
- tool = _big_mcp_tool()
- tool["inputSchema"]["properties"]["filter"] = {
- "type": "object",
- "properties": {"archived": {"type": "boolean"}, "limit": {"type": "integer"}},
- }
- _cache_server_tools(tmp_path, monkeypatch, [tool])
- specs = tools_mod.cached_mcp_tools()[0]
- assert "archived" not in json.dumps(specs[0]["function"]["parameters"])
- coerced = coerce_tool_arguments(
- {"filter": '{"archived": "false", "limit": "25"}'},
- heal = False,
- tool_name = "mcp__srv1__query",
- tool_schemas = specs,
+ big = [dict(_big_mcp_tool(), name = f"query-{i}") for i in range(4)]
+ _cache_server_tools(tmp_path, monkeypatch, big)
+ cost = tools_mod._text_token_cost(json.dumps(tools_mod.mcp_tool_spec("mcp__srv1__query-0")), 1)
+ window = lambda share: lambda: int(share * cost / tools_mod._MCP_TOOL_LOAD_SHARE) # noqa: E731
+ monkeypatch.setattr(tools_mod, "_window_context_tokens", window(2.5))
+ assert len(tools_mod.mcp_tool_search_specs({"query": "query rows"})) == 2
+
+ monkeypatch.setattr(tools_mod, "_window_context_tokens", window(0.5))
+ assert tools_mod.mcp_tool_search_specs({"query": "query rows"}) == []
+ out = tools_mod.execute_tool("mcp_tool_search", {"query": "query rows"})
+ assert out.startswith("Error: the matching MCP tools (mcp__srv1__query-0, ")
+ assert out.endswith("are too large for this model's context window.")
+
+
+def test_controller_retires_older_loads_to_stay_within_the_window(tmp_path, monkeypatch):
+ from core.inference import tools as tools_mod
+ from core.inference.tool_loop_controller import ToolLoopController
+
+ big = [dict(_big_mcp_tool(), name = f"query-{i}") for i in range(4)]
+ _cache_server_tools(tmp_path, monkeypatch, big)
+ cost = tools_mod._text_token_cost(json.dumps(tools_mod.mcp_tool_spec("mcp__srv1__query-0")), 1)
+ monkeypatch.setattr(
+ tools_mod,
+ "_window_context_tokens",
+ lambda: int(2.5 * cost / tools_mod._MCP_TOOL_LOAD_SHARE),
+ )
+ controller = ToolLoopController(tools = [tools_mod._mcp_tool_search_spec([])])
+ for name in ("query-0", "query-1", "query-2"):
+ decision = controller.prepare_call(
+ {"function": {"name": "mcp_tool_search", "arguments": json.dumps({"query": name})}}
+ )
+ controller.record_result(decision, "Loaded")
+ assert _names(controller.active_tools()) == [
+ "mcp_tool_search",
+ "mcp__srv1__query-1",
+ "mcp__srv1__query-2",
+ ]
+ assert (
+ controller.prepare_call(
+ {"function": {"name": "mcp__srv1__query-0", "arguments": "{}"}}
+ ).action
+ == "execute"
)
- assert coerced.arguments == {"filter": {"archived": False, "limit": 25}}
+ assert _names(controller.active_tools())[1:] == ["mcp__srv1__query-2", "mcp__srv1__query-0"]
-def test_mcp_tool_schema_pages_a_schema_larger_than_the_result_room(tmp_path, monkeypatch):
+def test_forced_and_image_mapped_tools_stay_listed(tmp_path, monkeypatch, searching):
+ import contextvars
+
from core.inference import tools as tools_mod
- tool = _big_mcp_tool()
- tool["inputSchema"]["properties"]["notes"] = {"type": "string", "description": "z " * 12000}
- _cache_server_tools(tmp_path, monkeypatch, [tool])
- full = tools_mod._mcp_tool_schema_text("A", tool)
- monkeypatch.setattr(tools_mod, "_loaded_context_tokens", lambda: 16384)
- token = tools_mod._REQUEST_RESULT_BUDGET.set(2000)
- try:
- pages, offset = [], 0
- for _ in range(50):
- out = tools_mod.execute_tool(
- "mcp_tool_schema", {"name": "mcp__srv1__query", "offset": offset}
- )
- body, marker, rest = out.partition("\n\n[Characters ")
- pages.append(body)
- if not marker:
- break
- offset = int(rest.split("offset=")[1].split(" ")[0])
- finally:
- tools_mod._REQUEST_RESULT_BUDGET.reset(token)
- assert len(pages) > 1
- assert "".join(pages) == full
-
-
-def test_hidden_large_mcp_tool_does_not_offer_the_schema_tool(tmp_path, monkeypatch, compacting):
+ _cache_server_tools(tmp_path, monkeypatch, _NOTES)
+
+ def listing_for(messages, tool_choice = None):
+ ctx = contextvars.copy_context()
+ ctx.run(tools_mod.set_mcp_listing_context_tokens, searching, None, messages, tool_choice)
+ return ctx.run(lambda: _names(tools_mod.cached_mcp_tools()[0]))
+
+ forced = {"type": "function", "function": {"name": "mcp__srv1__get-users"}}
+ assert listing_for(None, forced) == ["mcp_tool_search", "mcp__srv1__get-users"]
+
+ monkeypatch.setattr(
+ tools_mod, "image_mapping", lambda server, tool: tool and tool.get("name") == "ping"
+ )
+ image = {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA=="}}
+ asked = [{"role": "user", "content": [{"type": "text", "text": "hi"}, image]}]
+ assert listing_for(asked) == ["mcp_tool_search", "mcp__srv1__ping"]
+ # Without an attachment the mapped tool is deferred like any other.
+ assert listing_for([{"role": "user", "content": "hi"}]) == ["mcp_tool_search"]
+ # A tool-only image is sent as mcp_image, never in the messages.
+ ctx = contextvars.copy_context()
+ hi = [{"role": "user", "content": "hi"}]
+ ctx.run(
+ tools_mod.set_mcp_listing_context_tokens,
+ searching,
+ None,
+ hi,
+ None,
+ "data:image/png;base64,AA==",
+ )
+ assert ctx.run(lambda: _names(tools_mod.cached_mcp_tools()[0])) == [
+ "mcp_tool_search",
+ "mcp__srv1__ping",
+ ]
+
+
+def test_the_search_declaration_fits_its_share_of_the_window(tmp_path, monkeypatch, listing_window):
from core.inference import tools as tools_mod
- hidden = _big_mcp_tool()
- hidden["_meta"] = {"ui": {"visibility": ["app"]}}
- _cache_server_tools(tmp_path, monkeypatch, [{"name": "ping"}, hidden])
- assert [s["function"]["name"] for s in tools_mod.cached_mcp_tools()[0]] == ["mcp__srv1__ping"]
+ # One token a character, as CJK summaries cost.
+ wide = [{"name": f"t{i}", "description": "\u8868" * 200 + "\u3002"} for i in range(40)]
+ _cache_server_tools(tmp_path, monkeypatch, wide)
+ ctx = listing_window(20_000)
+ specs = tools_mod.cached_mcp_tools()[0]
+ assert _names(specs) == ["mcp_tool_search"]
+ cost = tools_mod._text_token_cost(json.dumps(specs, separators = (",", ":")), ctx)
+ assert cost <= ctx * tools_mod._MCP_TOOL_SEARCH_SHARE
-def test_mcp_tool_schema_does_not_reveal_an_app_only_tool(tmp_path, monkeypatch, compacting):
+def test_malformed_schemas_and_limits_do_not_break_the_search(tmp_path, monkeypatch):
from core.inference import tools as tools_mod
- hidden = {
- "name": "widget_refresh",
- "description": "Refresh the widget.",
- "_meta": {"ui": {"visibility": ["app"]}},
+ odd = {
+ "name": "odd",
+ "description": "Odd rows.",
+ "inputSchema": {"type": "object", "properties": "x"},
}
- _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool(), hidden])
- assert "mcp_tool_schema" in [s["function"]["name"] for s in tools_mod.cached_mcp_tools()[0]]
- assert (
- tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__srv1__widget_refresh"})
- == "Error: MCP server 'A' does not list a tool named 'widget_refresh'"
- )
+ _cache_server_tools(tmp_path, monkeypatch, [odd])
+ assert _names(
+ tools_mod.mcp_tool_search_specs({"query": "odd rows", "limit": float("inf")})
+ ) == ["mcp__srv1__odd"]
-def test_compacted_alias_keeps_its_raw_name_and_resolves_its_schema(
- tmp_path, monkeypatch, compacting
+def test_the_search_tool_names_tools_within_a_character_budget():
+ from core.inference import tools as tools_mod
+
+ catalog = [("A", [("t" * 60, "s" * 80) for _ in range(10)])]
+ description = tools_mod._mcp_tool_search_spec(catalog, 500)["function"]["description"]
+ assert description.count("- " + "t" * 60) == 3
+ assert description.endswith("- and 7 more")
+
+
+def test_a_repeated_search_runs_again_and_tools_run_unsearched_are_remembered(
+ tmp_path, monkeypatch
):
+ import contextvars
+
from core.inference import tools as tools_mod
- from core.inference.tool_loop_controller import coerce_tool_arguments
+ from core.inference.tool_loop_controller import ToolLoopController
- tool = _big_mcp_tool()
- tool["name"] = "catalog.query"
- tool["inputSchema"]["properties"]["filter"] = {
- "type": "object",
- "properties": {"limit": {"type": "integer"}},
- }
- _cache_server_tools(tmp_path, monkeypatch, [tool])
- specs = tools_mod.cached_mcp_tools()[0]
- spec = specs[0]["function"]
- alias = spec["name"]
- assert alias != "mcp__srv1__catalog.query"
- assert (
- spec["description"]
- == "[A] (catalog.query) Query rows. Full parameters via mcp_tool_schema."
- )
- out = tools_mod.execute_tool("mcp_tool_schema", {"name": alias})
- assert out.startswith("[A] catalog.query: Query rows.")
- coerced = coerce_tool_arguments(
- {"filter": '{"limit": "25"}'}, heal = False, tool_name = alias, tool_schemas = specs
- )
- assert coerced.arguments == {"filter": {"limit": 25}}
+ _cache_server_tools(tmp_path, monkeypatch, _NOTES)
+ controller = ToolLoopController(tools = [tools_mod._mcp_tool_search_spec([])])
+ call = {"function": {"name": "mcp_tool_search", "arguments": '{"query": "move pages"}'}}
+ controller.record_result(controller.prepare_call(call), "Loaded")
+ assert controller.prepare_call(call).action == "execute"
+
+ # A catalog listed in full has no search tool, and what the thread ran is still remembered.
+ full = ToolLoopController(tools = tools_mod.cached_mcp_tools()[0], thread_id = "t9")
+ ran = full.prepare_call({"function": {"name": "mcp__srv1__get-users", "arguments": "{}"}})
+ full.record_result(ran, "users")
+ ctx = contextvars.copy_context()
+ ctx.run(tools_mod.set_mcp_listing_context_tokens, 100_000, "t9")
+ monkeypatch.setattr(tools_mod, "_MCP_TOOL_SEARCH_SHARE", 0.0)
+ assert ctx.run(lambda: _names(tools_mod.cached_mcp_tools()[0])) == [
+ "mcp_tool_search",
+ "mcp__srv1__get-users",
+ ]
+
+
+def test_controller_without_the_search_tool_never_loads_mcp_tools(tmp_path, monkeypatch):
+ from core.inference.tool_loop_controller import ToolLoopController
+
+ _cache_server_tools(tmp_path, monkeypatch, _NOTES)
+ controller = ToolLoopController(tools = [])
+ decision = controller.prepare_call({"function": {"name": "mcp__srv1__ping", "arguments": "{}"}})
+ assert decision.action == "disabled"
+ assert controller.active_tools() == []
diff --git a/studio/backend/tests/test_permission_mode.py b/studio/backend/tests/test_permission_mode.py
index 09abe53a0dd..7caca8d0a60 100644
--- a/studio/backend/tests/test_permission_mode.py
+++ b/studio/backend/tests/test_permission_mode.py
@@ -3207,6 +3207,11 @@ def test_confirm_gate_needs_stream():
)
is True
)
+ # A catalog deferred behind mcp_tool_search loads MCP tools, which can prompt.
+ assert (
+ _confirm_gate_needs_stream(req(permission_mode = "auto"), selected_names = ["mcp_tool_search"])
+ is True
+ )
# But a selectable unsafe tool, an unrestricted (omitted) selection, MCP, or an
# explicit confirm flag all still require streaming under auto.
assert (