From 510dae1b4fd9002257ac6a6cf722320a47e8848b Mon Sep 17 00:00:00 2001 From: yassin Date: Tue, 20 Oct 2026 20:52:21 +0000 Subject: [PATCH] feat(mcp): expose outputSchema, title and configurable ttlMs for OpenAPI MCP tools Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../migration.sql | 4 + .../litellm_proxy_extras/schema.prisma | 2 + litellm/constants.py | 1 + litellm/models/mcp_server.py | 1 + .../proxy/_experimental/mcp_server/catalog.py | 31 +- .../_experimental/mcp_server/contracts.py | 1 + .../_experimental/mcp_server/mcp_context.py | 3 + .../mcp_server/mcp_server_manager.py | 25 +- .../mcp_server/openapi_to_mcp_generator.py | 262 ++++++++++- .../_experimental/mcp_server/operations.py | 43 +- .../proxy/_experimental/mcp_server/server.py | 2 + .../_experimental/mcp_server/tool_registry.py | 45 +- .../_experimental/mcp_server/toolset_db.py | 2 + litellm/proxy/_lazy_openapi_snapshot.json | 108 +++++ litellm/proxy/_types.py | 2 + litellm/proxy/proxy_server.py | 14 +- litellm/proxy/schema.prisma | 2 + .../types/mcp_server/mcp_server_manager.py | 1 + litellm/types/mcp_server/mcp_toolset.py | 3 + litellm/types/mcp_server/tool_registry.py | 2 + schema.prisma | 2 + .../code_coverage_tests/recursive_detector.py | 1 + .../_experimental/mcp_server/test_catalog.py | 48 ++ .../mcp_server/test_mcp_partial_update.py | 39 ++ .../mcp_server/test_mcp_server.py | 1 + .../mcp_server/test_mcp_server_manager.py | 204 +++++++++ .../test_mcp_server_tool_calls_and_headers.py | 101 +++++ .../test_openapi_to_mcp_generator.py | 413 +++++++++++++++++- .../mcp_server/test_operations.py | 84 +++- .../mcp_server/test_rest_endpoints.py | 4 +- .../mcp/test_litellm_proxy_mcp_handler.py | 2 + .../CreateMCPServer.integration.test.tsx | 8 + .../_components/CreateMCPServer.tsx | 24 + .../MCPToolsetsTab.integration.test.tsx | 107 ++++- .../_components/MCPToolsetsTab.tsx | 73 +++- .../_components/createServerPayload.test.ts | 11 + .../editServerPayload.differential.test.ts | 22 + .../_components/editServerPayload.ts | 7 + .../_components/mcp_server_edit.test.tsx | 20 + .../_components/mcp_server_edit.tsx | 24 + .../src/components/mcp_tools/types.tsx | 2 + ui/litellm-dashboard/src/lib/http/schema.d.ts | 10 + 42 files changed, 1693 insertions(+), 68 deletions(-) create mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20261020000000_add_tools_ttl_ms_to_mcp/migration.sql diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20261020000000_add_tools_ttl_ms_to_mcp/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20261020000000_add_tools_ttl_ms_to_mcp/migration.sql new file mode 100644 index 00000000000..44887d6855e --- /dev/null +++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20261020000000_add_tools_ttl_ms_to_mcp/migration.sql @@ -0,0 +1,4 @@ +SET LOCAL lock_timeout = '10s'; + +ALTER TABLE "LiteLLM_MCPServerTable" ADD COLUMN IF NOT EXISTS "tools_ttl_ms" INTEGER; +ALTER TABLE "LiteLLM_MCPToolsetTable" ADD COLUMN IF NOT EXISTS "tools_ttl_ms" INTEGER; diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma index 83a0e6f9e05..b0171d6fced 100644 --- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma +++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma @@ -367,6 +367,7 @@ model LiteLLM_MCPServerTable { instructions String? url String? spec_path String? + tools_ttl_ms Int? transport String @default("sse") auth_type String? credentials Json? @default("{}") @@ -434,6 +435,7 @@ model LiteLLM_MCPToolsetTable { toolset_id String @id @default(uuid()) toolset_name String @unique description String? + tools_ttl_ms Int? tools Json @default("[]") // [{server_id: string, tool_name: string}] created_at DateTime @default(now()) created_by String? diff --git a/litellm/constants.py b/litellm/constants.py index cb50d74f0cf..d38de5a9730 100644 --- a/litellm/constants.py +++ b/litellm/constants.py @@ -270,6 +270,7 @@ AGENT_HEALTH_CHECK_TIMEOUT_SECONDS: Final = get_env_float("LITELLM_AGENT_HEALTH_ AGENT_HEALTH_CHECK_GATHER_TIMEOUT_SECONDS: Final = get_env_float("LITELLM_AGENT_HEALTH_CHECK_GATHER_TIMEOUT", 30.0) MCP_UPSTREAM_SESSION_SHUTDOWN_TIMEOUT_SECONDS: Final = 5.0 MCP_TOOL_LISTING_MAX_PAGES: Final = 1000 +MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES: Final = 10000 MCP_GATEWAY_SESSION_ID_PREFIX_LENGTH: Final = 8 MCP_BYOK_CREDENTIAL_CACHE_TTL_SECONDS: Final = 60 MCP_BYOK_CREDENTIAL_CACHE_MAX_SIZE: Final = 4096 diff --git a/litellm/models/mcp_server.py b/litellm/models/mcp_server.py index cdbda7b1b70..519d5c43dda 100644 --- a/litellm/models/mcp_server.py +++ b/litellm/models/mcp_server.py @@ -56,6 +56,7 @@ class LiteLLM_MCPServerTable(LiteLLMPydanticObjectBase): description: str | None = None url: str | None = None spec_path: str | None = None + tools_ttl_ms: int | None = Field(default=None, ge=0) transport: MCPTransportType auth_type: MCPAuthType | None = None credentials: MCPCredentials | None = None diff --git a/litellm/proxy/_experimental/mcp_server/catalog.py b/litellm/proxy/_experimental/mcp_server/catalog.py index 71eb2112bd5..80c09a914d1 100644 --- a/litellm/proxy/_experimental/mcp_server/catalog.py +++ b/litellm/proxy/_experimental/mcp_server/catalog.py @@ -24,9 +24,11 @@ from pydantic import BaseModel, ConfigDict, JsonValue, TypeAdapter from litellm._logging import verbose_logger from litellm.caching.in_memory_cache import InMemoryCache from litellm.proxy._experimental.mcp_server.result_conversion import age_freshness, aggregate_freshness +from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat if TYPE_CHECKING: from mcp.types import ListToolsResult, PaginatedRequestParams, PaginatedResult + from mcp.types import Tool as MCPWireTool from litellm.proxy._experimental.mcp_server.contracts import CatalogListRequest, CatalogListResult, OperationContext from litellm.proxy._experimental.mcp_server.db import OAuthCredentialPayload @@ -858,6 +860,7 @@ async def get_filtered_server_tools( proxy_logging_obj=proxy_logging_obj, catalog_auth_header=catalog_auth_header, record_listing=False, + wire_compat=context.wire_compat, ) ) else: @@ -875,6 +878,7 @@ async def get_filtered_server_tools( catalog_auth_header=catalog_auth_header, record_listing=False, listing_updates=listing_updates, + wire_compat=context.wire_compat, ) tools: Final = page.tools filtered_tools = filter_tools_by_allowed_tools(tools, server) @@ -907,20 +911,29 @@ async def get_filtered_server_tools( else: listing_updates.callback(record) - if mcp_proxy_mode: + def with_proxy_identity(tool: MCPWireTool) -> MCPWireTool: from litellm.proxy._experimental.mcp_server.tool_search import with_mcp_proxy_identity - filtered_tools = [with_mcp_proxy_identity(tool, server.server_id) for tool in filtered_tools] - else: - filtered_tools = apply_display_name_overrides(filtered_tools, server) + return with_mcp_proxy_identity(tool, server.server_id) + + listed_tools: Final = ( + tuple(with_proxy_identity(tool) for tool in filtered_tools) + if mcp_proxy_mode + else apply_display_name_overrides(filtered_tools, server, wire_compat=context.wire_compat) + ) + response_tools: Final = ( + [tool.model_copy(update={"output_schema": None, "title": None}) for tool in listed_tools] + if not mcp_proxy_mode and server.spec_path and context.wire_compat == WireCompat.LEGACY + else list(listed_tools) + ) verbose_logger.debug( "Successfully fetched %s tools from server %s, %s after filtering", len(tools), server.name, - len(filtered_tools), + len(response_tools), ) - return page.model_copy(update={"tools": filtered_tools}), ServerListOk(tool_count=len(filtered_tools)) + return page.model_copy(update={"tools": response_tools}), ServerListOk(tool_count=len(response_tools)) except MCPUpstreamAuthError as e: # Absorb so one unauthenticated server does not empty every other server's # tools. Surfacing the upstream 401 to the client as a re-auth challenge is @@ -1067,6 +1080,7 @@ async def list_gateway_tools( from litellm.proxy._experimental.mcp_server.faults.list_outcomes import ( SERVER_OUTCOMES_META_KEY, + ServerListOk, listing_failed_outright, outcome_wire_value, ) @@ -1096,10 +1110,13 @@ async def list_gateway_tools( message="Every MCP server in scope failed to list tools", data={SERVER_OUTCOMES_META_KEY: wire_outcomes}, ) + toolset_ttl: Final = context.toolset_tools_ttl_ms + complete: Final = not any(not isinstance(outcome, ServerListOk) for outcome in listing.outcomes.values()) + ttl_ms: Final = toolset_ttl if toolset_ttl is not None and complete else listing.ttl_ms return ListToolsResult( tools=listing.tools, next_cursor=listing.next_cursor, - ttl_ms=listing.ttl_ms, + ttl_ms=ttl_ms, cache_scope="private", _meta={SERVER_OUTCOMES_META_KEY: wire_outcomes} if wire_outcomes else None, ) diff --git a/litellm/proxy/_experimental/mcp_server/contracts.py b/litellm/proxy/_experimental/mcp_server/contracts.py index 84cd2751444..16858f7bdb5 100644 --- a/litellm/proxy/_experimental/mcp_server/contracts.py +++ b/litellm/proxy/_experimental/mcp_server/contracts.py @@ -70,6 +70,7 @@ class OperationContext: mcp_proxy_mode: bool = False wire_compat: WireCompat = WireCompat.LEGACY protocol_version: str | None = None + toolset_tools_ttl_ms: int | None = None incoming_bearer_token: SecretStr | None | EllipsisType = field(default=..., repr=False) def __post_init__(self) -> None: diff --git a/litellm/proxy/_experimental/mcp_server/mcp_context.py b/litellm/proxy/_experimental/mcp_server/mcp_context.py index 8ec44f65bdf..e05e4e9404e 100644 --- a/litellm/proxy/_experimental/mcp_server/mcp_context.py +++ b/litellm/proxy/_experimental/mcp_server/mcp_context.py @@ -28,6 +28,9 @@ def get_active_mcp_request_ctx() -> "ServerRequestContext | None": # /toolset/{name}/mcp or the toolset fallback in dynamic_mcp_route. # Never populated from client-supplied headers. mcp_active_toolset_id: Final[ContextVar[str | None]] = ContextVar("_mcp_active_toolset_id", default=None) +mcp_active_toolset_tools_ttl_ms: Final[ContextVar[int | None]] = ContextVar( + "_mcp_active_toolset_tools_ttl_ms", default=None +) _mcp_active_toolset_id: Final = mcp_active_toolset_id diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py index f65310a77e3..e0735dd99b2 100644 --- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py +++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py @@ -409,8 +409,10 @@ class MCPServerConfig(TypedDict, total=False): mcp_info: MCPInfo url: str spec_path: str + tools_ttl_ms: ReadOnly[int | None] transport: MCPTransportType auth_type: MCPAuthType + tool_name_to_display_name: ReadOnly[_StringMap] authentication_token: str auth_value: str instructions: str @@ -2723,6 +2725,8 @@ class MCPServerManager: alias=alias, server_name=server_name, spec_path=server_config.get("spec_path", None), + tools_ttl_ms=server_config.get("tools_ttl_ms", None), + tool_name_to_display_name=server_config.get("tool_name_to_display_name", None), url=server_url, command=server_config.get("command", None) or "", args=server_config.get("args", None) or [], @@ -2876,6 +2880,7 @@ class MCPServerManager: """ from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import ( build_input_schema, + build_output_schema, create_tool_function, load_openapi_spec_async, resolve_operation_params, @@ -2987,6 +2992,8 @@ class MCPServerManager: description=description, input_schema=input_schema, handler=tool_func, + output_schema=build_output_schema(operation, spec), + title=operation.get("summary"), server_id=server.server_id, ) @@ -3306,6 +3313,7 @@ class MCPServerManager: server_name=getattr(mcp_server, "server_name", None), url=mcp_server.url, spec_path=getattr(mcp_server, "spec_path", None), + tools_ttl_ms=getattr(mcp_server, "tools_ttl_ms", None), transport=cast(MCPTransportType, mcp_server.transport), auth_type=auth_type, authentication_token=auth_value, @@ -4373,6 +4381,7 @@ class MCPServerManager: *, catalog_auth_header: str | dict[str, str] | None | EllipsisType = ..., record_listing: bool = False, + wire_compat: WireCompat = WireCompat.LEGACY, ) -> list[MCPTool]: result: Final = await self.get_tools_page( server=server, @@ -4386,6 +4395,7 @@ class MCPServerManager: proxy_logging_obj=proxy_logging_obj, catalog_auth_header=catalog_auth_header, record_listing=record_listing, + wire_compat=wire_compat, ) return result.tools @@ -4407,6 +4417,7 @@ class MCPServerManager: catalog_auth_header: str | dict[str, str] | None | EllipsisType = ..., record_listing: bool = False, listing_updates: ExitStack | None = None, + wire_compat: WireCompat = WireCompat.LEGACY, ) -> ListToolsResult: from litellm.proxy._experimental.mcp_server.tool_registry import ( global_mcp_tool_registry, @@ -4509,7 +4520,8 @@ class MCPServerManager: # active at registration time — fetch by that same prefix. registry_prefix: Final = normalize_server_name(get_server_prefix(server)) + MCP_TOOL_PREFIX_SEPARATOR registered: Final = global_mcp_tool_registry.convert_tools_to_mcp_sdk_tool_type( - global_mcp_tool_registry.list_tools(tool_prefix=registry_prefix) + global_mcp_tool_registry.list_tools(tool_prefix=registry_prefix), + wire_compat=wire_compat, ) registered_names: Final = MappingProxyType( {t.name.removeprefix(registry_prefix): t.name for t in registered} @@ -4529,9 +4541,13 @@ class MCPServerManager: server, guarded_openapi, listed_caller, listed_generation, record_listing=record_listing ) if not add_prefix: - return ListToolsResult(tools=list(guarded_openapi)) + return ListToolsResult( + tools=list(guarded_openapi), + ttl_ms=server.tools_ttl_ms if server.tools_ttl_ms is not None else 0, + ) return ListToolsResult( - tools=[t.model_copy(update={"name": registered_names[t.name]}) for t in guarded_openapi] + tools=[t.model_copy(update={"name": registered_names[t.name]}) for t in guarded_openapi], + ttl_ms=server.tools_ttl_ms if server.tools_ttl_ms is not None else 0, ) else: page: Final = ( @@ -7550,6 +7566,8 @@ class MCPServerManager: alias=server.alias, description=(server.mcp_info.get("description") if server.mcp_info else None), url=server.url, + spec_path=server.spec_path, + tools_ttl_ms=server.tools_ttl_ms, transport=server.transport, auth_type=server.auth_type, created_at=server.created_at, @@ -7663,6 +7681,7 @@ class MCPServerManager: description=(server.mcp_info.get("description") if server.mcp_info else None), url=server.url, spec_path=server.spec_path, + tools_ttl_ms=server.tools_ttl_ms, transport=server.transport, auth_type=server.auth_type, credentials=({"scopes": list(server.configured_scopes)} if server.configured_scopes else None), diff --git a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py index f0353f309a9..38c1051775c 100644 --- a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py +++ b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py @@ -8,13 +8,17 @@ import json import os import re from collections.abc import Mapping, Sequence +from functools import reduce +from itertools import chain from pathlib import PurePosixPath from typing import Final, Literal, Protocol, TypeAlias, TypedDict, overload from urllib.parse import quote import httpx +from pydantic import TypeAdapter, ValidationError from typing_extensions import ReadOnly, Required +from litellm import constants from litellm.llms.custom_httpx.http_handler import MaskedHTTPStatusError from litellm.proxy._experimental.mcp_server.exceptions import ( MCPOpenApiUpstreamError, @@ -31,6 +35,8 @@ OPENAPI_TOOL_NAME_MAX_LEN: Final = 128 _OPENAPI_TOOL_NAME_MAX_LEN: Final = OPENAPI_TOOL_NAME_MAX_LEN +_OPENAPI_SCHEMA_RESOLUTION_CHUNK_SIZE: Final = 32 + def sanitize_openapi_tool_name(raw_name: str) -> str: """Map an OpenAPI operationId / fallback to a provider-safe tool name. @@ -74,7 +80,11 @@ class _OpenAPIParameter(TypedDict, total=False): class _OpenAPIMediaType(TypedDict, total=False): - schema: _OpenAPIJSONSchema + schema: ReadOnly[Mapping[str, object]] + + +class _OpenAPIResponse(TypedDict, total=False): + content: ReadOnly[Mapping[str, _OpenAPIMediaType]] class _OpenAPIRequestBody(TypedDict, total=False): @@ -89,6 +99,7 @@ class _OpenAPIOperation(TypedDict, total=False): description: str parameters: Sequence[_OpenAPIParameter] requestBody: _OpenAPIRequestBody + responses: ReadOnly[Mapping[str, _OpenAPIResponse]] _OpenAPIMethod: TypeAlias = Literal["get", "post", "put", "delete", "patch"] @@ -110,6 +121,7 @@ class _OpenAPIPathItem(Protocol): class _OpenAPIComponents(TypedDict, total=False): parameters: Mapping[str, _OpenAPIParameter] + schemas: ReadOnly[Mapping[str, Mapping[str, object]]] class _OpenAPIServer(TypedDict): @@ -125,6 +137,10 @@ class _OpenAPISpec(TypedDict, total=False): basePath: ReadOnly[str] +_OPENAPI_OBJECT_ADAPTER: Final = TypeAdapter(dict[str, object]) +_OPENAPI_ARRAY_ADAPTER: Final = TypeAdapter(list[object]) + + # Store the base URL and headers globally BASE_URL: Final = "" HEADERS: Final[dict[str, str]] = {} @@ -379,7 +395,7 @@ def build_input_schema(operation: _OpenAPIOperation) -> dict[str, object]: # Try to get JSON schema if "application/json" in content: - schema: Final[_OpenAPIJSONSchema] = content["application/json"].get("schema", {}) + schema: Final = content["application/json"].get("schema", {}) properties["body"] = { "type": "object", "description": request_body.get("description", "Request body"), @@ -395,6 +411,246 @@ def build_input_schema(operation: _OpenAPIOperation) -> dict[str, object]: } +def _resolve_openapi_schema_value( + value: object, spec: _OpenAPISpec, seen: frozenset[str], budget: int +) -> tuple[bool, object, int]: + remaining: Final = budget - 1 + if remaining < 0: + return False, None, remaining + if isinstance(value, Mapping): + try: + mapping_value: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(value) + except ValidationError: + return False, None, remaining + return _resolve_openapi_schema_mapping(mapping_value, spec, seen, remaining) + if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)): + try: + sequence_value: Final = _OPENAPI_ARRAY_ADAPTER.validate_python(value) + except ValidationError: + return False, None, remaining + return _resolve_openapi_schema_sequence(sequence_value, spec, seen, remaining) + return True, value, remaining + + +def _resolve_openapi_schema_mapping( + value: Mapping[str, object], spec: _OpenAPISpec, seen: frozenset[str], budget: int +) -> tuple[bool, object, int]: + ref: Final = value.get("$ref") + if ref is not None: + ref_result: Final = _resolve_openapi_schema_value(ref, spec, seen, budget) + if not ref_result[0]: + return False, None, ref_result[2] + return _resolve_openapi_schema_reference(ref_result[1], spec, seen, ref_result[2]) + mapping_items: Final = tuple(value.items()) + child_values: Final = tuple(item for _, item in mapping_items) + resolved_items: Final = _resolve_openapi_schema_children(child_values, spec, seen, budget) + if not resolved_items[0] or resolved_items[1] is None: + return False, None, resolved_items[2] + resolved_values: Final = resolved_items[1] + return ( + True, + {key: item for (key, _), item in zip(mapping_items, resolved_values)}, + resolved_items[2], + ) + + +def _resolve_openapi_schema_reference( + ref: object, spec: _OpenAPISpec, seen: frozenset[str], budget: int +) -> tuple[bool, object, int]: + if not isinstance(ref, str) or not ref.startswith("#/components/schemas/") or ref in seen: + return False, None, budget + schema_name: Final = ref.rsplit("/", 1)[-1] + components: Final = spec.get("components") + if components is None: + return False, None, budget + schemas: Final = components.get("schemas") + if schemas is None: + return False, None, budget + target: Final = schemas.get(schema_name) + if target is None: + return False, None, budget + return _resolve_openapi_schema_value(target, spec, seen | {ref}, budget) + + +def _resolve_openapi_schema_sequence( + value: Sequence[object], spec: _OpenAPISpec, seen: frozenset[str], budget: int +) -> tuple[bool, object, int]: + resolved_items: Final = _resolve_openapi_schema_children(value, spec, seen, budget) + if not resolved_items[0] or resolved_items[1] is None: + return False, None, resolved_items[2] + resolved_values: Final = resolved_items[1] + return True, list(resolved_values), resolved_items[2] + + +def _resolve_openapi_schema_children( + values: Sequence[object], + spec: _OpenAPISpec, + seen: frozenset[str], + budget: int, +) -> tuple[bool, tuple[object, ...] | None, int]: + def resolve_child( + accumulator: tuple[bool, tuple[tuple[object, ...], ...], tuple[object, ...], int], + value: object, + ) -> tuple[bool, tuple[tuple[object, ...], ...], tuple[object, ...], int]: + if not accumulator[0]: + return accumulator + child_result: Final = _resolve_openapi_schema_value(value, spec, seen, accumulator[3]) + if not child_result[0]: + return False, accumulator[1], accumulator[2], child_result[2] + current_chunk: Final = (*accumulator[2], child_result[1]) + if len(current_chunk) < _OPENAPI_SCHEMA_RESOLUTION_CHUNK_SIZE: + return True, accumulator[1], current_chunk, child_result[2] + return True, (*accumulator[1], current_chunk), (), child_result[2] + + resolved: Final = reduce(resolve_child, values, (True, (), (), budget)) + if not resolved[0]: + return False, None, resolved[3] + chunks: Final = (*resolved[1], resolved[2]) if resolved[2] else resolved[1] + return True, tuple(chain.from_iterable(chunks)), resolved[3] + + +def _get_openapi_output_schema(operation: _OpenAPIOperation) -> Mapping[str, object] | None: + responses: Final = operation.get("responses") + if responses is None: + return None + response_codes: Final = tuple( + sorted((code for code in responses if code.isdigit() and 200 <= int(code) < 300), key=int) + ) + selected_code: Final = response_codes[0] if response_codes else ("2XX" if "2XX" in responses else None) + if selected_code is None: + return None + response: Final = responses.get(selected_code) + if response is None: + return None + content: Final = response.get("content") + if content is None: + return None + media_type: Final = next( + ( + value + for key, value in content.items() + if key == "application/json" or (key.startswith("application/") and key.endswith("+json")) + ), + None, + ) + if media_type is None: + return None + return media_type.get("schema") + + +_OPENAPI_SCHEMA_CHILD_KEYS: Final = frozenset( + { + "additionalItems", + "additionalProperties", + "contains", + "contentSchema", + "else", + "if", + "items", + "not", + "propertyNames", + "then", + "unevaluatedItems", + "unevaluatedProperties", + } +) +_OPENAPI_SCHEMA_MAP_KEYS: Final = frozenset( + {"$defs", "definitions", "dependentSchemas", "patternProperties", "properties"} +) +_OPENAPI_SCHEMA_SEQUENCE_KEYS: Final = frozenset({"allOf", "anyOf", "oneOf", "prefixItems"}) +_OPENAPI_SCHEMA_KEYS: Final = _OPENAPI_SCHEMA_CHILD_KEYS | _OPENAPI_SCHEMA_MAP_KEYS | _OPENAPI_SCHEMA_SEQUENCE_KEYS + + +def _normalize_openapi_exclusive_bound( + value: Mapping[str, object], bound_key: str, exclusive_key: str +) -> dict[str, object]: + bound: Final = value.get(bound_key) + exclusive: Final = value.get(exclusive_key) + bound_fields: Final = {bound_key: bound} if bound_key in value else {} + if isinstance(exclusive, bool): + if exclusive and isinstance(bound, (int, float)) and not isinstance(bound, bool): + return {exclusive_key: bound} + return bound_fields + if exclusive_key in value: + return {**bound_fields, exclusive_key: exclusive} + return bound_fields + + +def _normalize_openapi_nullable_schema(value: object) -> object: + if isinstance(value, Mapping): + schema_mapping: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(value) + nullable: Final = schema_mapping.get("nullable") is True + schema_type: Final = schema_mapping.get("type") + schema_children: Final = { + key: _normalize_openapi_nullable_schema_children(item) + if key in _OPENAPI_SCHEMA_MAP_KEYS + else _normalize_openapi_nullable_schema(item) + for key, item in schema_mapping.items() + if key in _OPENAPI_SCHEMA_KEYS + } + schema_fields: Final = { + key: item + for key, item in schema_mapping.items() + if key not in _OPENAPI_SCHEMA_KEYS + and key not in ("nullable", "type", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum") + } + normalized_fields: Final = { + **schema_fields, + **schema_children, + **_normalize_openapi_exclusive_bound(schema_mapping, "minimum", "exclusiveMinimum"), + **_normalize_openapi_exclusive_bound(schema_mapping, "maximum", "exclusiveMaximum"), + } + if nullable and isinstance(schema_type, str): + return {**normalized_fields, "type": [schema_type, "null"]} + if nullable and isinstance(schema_type, Sequence) and not isinstance(schema_type, (str, bytes, bytearray)): + type_values: Final = _OPENAPI_ARRAY_ADAPTER.validate_python(schema_type) + normalized_types: Final = tuple(_normalize_openapi_nullable_schema(item) for item in type_values) + nullable_types: Final = ( + list(normalized_types) if "null" in normalized_types else [*normalized_types, "null"] + ) + return {**normalized_fields, "type": nullable_types} + if nullable: + return {"anyOf": [normalized_fields, {"type": "null"}]} + if "type" in schema_mapping: + return { + **normalized_fields, + "type": _normalize_openapi_nullable_schema(schema_type), + } + return normalized_fields + if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)): + schema_sequence: Final = _OPENAPI_ARRAY_ADAPTER.validate_python(value) + return [_normalize_openapi_nullable_schema(item) for item in schema_sequence] + return value + + +def _normalize_openapi_nullable_schema_children(value: object) -> object: + if not isinstance(value, Mapping): + return value + schema_children: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(value) + return {key: _normalize_openapi_nullable_schema(item) for key, item in schema_children.items()} + + +def build_output_schema( + operation: _OpenAPIOperation, spec: _OpenAPISpec +) -> dict[str, object] | None: # mutable-ok: MCP SDK output schemas require a copied dict + schema: Final = _get_openapi_output_schema(operation) + if schema is None: + return None + resolved: Final = _resolve_openapi_schema_value( + schema, spec, frozenset(), constants.MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES + ) + if not resolved[0]: + return None + try: + normalized_schema: Final = _normalize_openapi_nullable_schema(resolved[1]) + resolved_schema: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(normalized_schema) + except ValidationError: + return None + if resolved_schema.get("type") != "object": + return None + return resolved_schema + + async def _drop_credential_across_origin(request: httpx.Request) -> None: """Apply this request's cross-origin credential guard, if it needs one. @@ -677,5 +933,7 @@ def register_tools_from_openapi(spec: _OpenAPISpec, base_url: str) -> None: description=description, input_schema=input_schema, handler=tool_func, + output_schema=build_output_schema(operation, spec), + title=operation.get("summary"), ) verbose_logger.debug("Registered tool: %s", tool_name) diff --git a/litellm/proxy/_experimental/mcp_server/operations.py b/litellm/proxy/_experimental/mcp_server/operations.py index 39e882fcab0..283fe081a19 100644 --- a/litellm/proxy/_experimental/mcp_server/operations.py +++ b/litellm/proxy/_experimental/mcp_server/operations.py @@ -123,6 +123,7 @@ from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import ( # request_auth_header, request_extra_headers, request_resolved_auth_headers, + sanitize_openapi_tool_name, ) from litellm.proxy._experimental.mcp_server.result_conversion import ( WireCompat, @@ -827,18 +828,39 @@ def filter_tools_by_allowed_tools( def apply_display_name_overrides( tools: list[MCPTool], mcp_server: MCPServer, + *, + wire_compat: WireCompat = WireCompat.LEGACY, ) -> list[MCPTool]: """Apply admin-configured display name overrides, keyed by the unprefixed tool name like allowed_tools.""" display_name_map: Final = mcp_server.tool_name_to_display_name or {} if not display_name_map: return tools - for tool in tools: - unprefixed = strip_known_server_prefix(tool.name, mcp_server) - lookup_key = unprefixed or tool.name - if lookup_key in display_name_map: - tool.name = display_name_map[lookup_key] - return tools + modern_openapi: Final = mcp_server.spec_path is not None and wire_compat == WireCompat.MODERN + + def apply_override(tool: MCPTool) -> MCPTool: + unprefixed: Final = strip_known_server_prefix(tool.name, mcp_server) + lookup_key: Final = unprefixed or tool.name + raw_display_name: Final = display_name_map.get(lookup_key) + display_name: Final[str | None] = ( + raw_display_name + if raw_display_name is not None + else next( + ( + override + for key, override in display_name_map.items() + if mcp_server.spec_path and sanitize_openapi_tool_name(key) == lookup_key + ), + None, + ) + ) + if display_name is None: + return tool + if modern_openapi: + return tool.model_copy(update={"title": display_name}) + return tool.model_copy(update={"name": display_name}) + + return [apply_override(tool) for tool in tools] @catalog_operation(lambda: global_mcp_server_manager) @@ -1367,6 +1389,7 @@ async def _get_tools_from_mcp_servers( ) from litellm.proxy._experimental.mcp_server.catalog import get_filtered_server_tools + from litellm.proxy._experimental.mcp_server.result_conversion import wire_compat_for context: Final = OperationContext( _caller=user_api_key_auth, @@ -1377,6 +1400,7 @@ async def _get_tools_from_mcp_servers( raw_headers=raw_headers, client_ip=client_ip, mcp_proxy_mode=mcp_proxy_mode, + wire_compat=wire_compat_for(protocol_version) if protocol_version is not None else WireCompat.LEGACY, protocol_version=protocol_version, ) @@ -1884,7 +1908,10 @@ def _resolve_display_name_to_original( display_map = server.tool_name_to_display_name or {} for unprefixed_name, display_name in display_map.items(): if display_name == name: - return add_server_prefix_to_name(unprefixed_name, get_server_prefix(server)) + return add_server_prefix_to_name( + sanitize_openapi_tool_name(unprefixed_name) if server.spec_path else unprefixed_name, + get_server_prefix(server), + ) return name @@ -3665,6 +3692,7 @@ def prepare_context( wire_compat: WireCompat = WireCompat.LEGACY, protocol_version: str | None = None, incoming_bearer_token: SecretStr | None | EllipsisType = ..., + toolset_tools_ttl_ms: int | None = None, ) -> OperationContext: return OperationContext( _caller=user_api_key_auth, @@ -3677,6 +3705,7 @@ def prepare_context( mcp_proxy_mode=mcp_proxy_mode, wire_compat=wire_compat, protocol_version=protocol_version, + toolset_tools_ttl_ms=toolset_tools_ttl_ms, incoming_bearer_token=incoming_bearer_token, ) diff --git a/litellm/proxy/_experimental/mcp_server/server.py b/litellm/proxy/_experimental/mcp_server/server.py index b3426089375..1ee486ad0cc 100644 --- a/litellm/proxy/_experimental/mcp_server/server.py +++ b/litellm/proxy/_experimental/mcp_server/server.py @@ -59,6 +59,7 @@ from litellm.proxy._experimental.mcp_server.mcp_context import ( # noqa: F401 active_mcp_request_ctx_var, get_active_mcp_request_ctx, mcp_active_toolset_id, + mcp_active_toolset_tools_ttl_ms, mcp_gateway_initialize_instructions, mcp_gateway_server_name, ) @@ -889,6 +890,7 @@ if MCP_AVAILABLE: if isinstance(request, StarletteRequest) else None ), + toolset_tools_ttl_ms=mcp_active_toolset_tools_ttl_ms.get(), ) async def handle_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams) -> ListToolsResult: diff --git a/litellm/proxy/_experimental/mcp_server/tool_registry.py b/litellm/proxy/_experimental/mcp_server/tool_registry.py index 1f1d952f96c..992cf9fc1f1 100644 --- a/litellm/proxy/_experimental/mcp_server/tool_registry.py +++ b/litellm/proxy/_experimental/mcp_server/tool_registry.py @@ -1,11 +1,14 @@ import asyncio import json -from collections.abc import Callable, Generator, Mapping +from collections.abc import Callable, Generator, Mapping, Sequence from contextlib import contextmanager from contextvars import ContextVar from typing import TYPE_CHECKING, Final +from pydantic import TypeAdapter + from litellm._logging import verbose_logger +from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat from litellm.proxy.types_utils.utils import get_instance_fn from litellm.types.mcp_server.tool_registry import MCPTool @@ -60,6 +63,8 @@ class MCPToolRegistry: handler: Callable, *, server_id: str | None = None, + output_schema: Mapping[str, object] | None = None, + title: str | None = None, ) -> None: """ Register a new tool in the registry @@ -70,6 +75,8 @@ class MCPToolRegistry: input_schema=input_schema, handler=handler, server_id=server_id, + output_schema=dict(output_schema) if output_schema is not None else None, + title=title, ) verbose_logger.debug("Registered tool: %s", name) @@ -103,14 +110,20 @@ class MCPToolRegistry: verbose_logger.debug("Unregistered MCP tool %s", name) return removed - def convert_tools_to_mcp_sdk_tool_type(self, tools: list[MCPTool]) -> list["MCPToolSDKTool"]: + def convert_tools_to_mcp_sdk_tool_type( + self, tools: Sequence[MCPTool], *, wire_compat: WireCompat = WireCompat.LEGACY + ) -> Sequence["MCPToolSDKTool"]: if MCPToolSDKTool is None: raise ImportError("MCP SDK is not installed. Please install it with: pip install 'litellm[proxy]'") return [ - MCPToolSDKTool( - name=tool.name, - description=tool.description, - inputSchema=tool.input_schema, + MCPToolSDKTool.model_validate( + { + "name": tool.name, + "description": tool.description, + "inputSchema": tool.input_schema, + "outputSchema": tool.output_schema if wire_compat is WireCompat.MODERN else None, + "title": tool.title if wire_compat is WireCompat.MODERN else None, + } ) for tool in tools ] @@ -140,16 +153,23 @@ class MCPToolRegistry: name = tool_config.get("name") description = tool_config.get("description") - input_schema = tool_config.get("input_schema", {}) + raw_input_schema = tool_config.get("input_schema", {}) handler_name = tool_config.get("handler") - if not all([name, description, handler_name]): + if ( + not isinstance(name, str) + or not name + or not isinstance(description, str) + or not description + or not isinstance(handler_name, str) + or not handler_name + ): continue + input_schema = TypeAdapter(dict[str, object]).validate_python(raw_input_schema) + # Try to resolve the handler # First check if it's a module path (e.g., "module.submodule.function") - if handler_name is None: - raise ValueError(f"handler is required for tool {name}") handler = get_instance_fn(handler_name, config_file_path) if handler is None: @@ -157,11 +177,6 @@ class MCPToolRegistry: continue # Register the tool - if name is None: - raise ValueError(f"name is required for tool {name}") - if description is None: - raise ValueError(f"description is required for tool {name}") - self.register_tool( name=name, description=description, diff --git a/litellm/proxy/_experimental/mcp_server/toolset_db.py b/litellm/proxy/_experimental/mcp_server/toolset_db.py index f3a78d206d7..92ca59eee71 100644 --- a/litellm/proxy/_experimental/mcp_server/toolset_db.py +++ b/litellm/proxy/_experimental/mcp_server/toolset_db.py @@ -23,6 +23,7 @@ class MCPToolsetFields(TypedDict): toolset_id: ReadOnly[str] toolset_name: ReadOnly[str] description: NotRequired[ReadOnly[str | None]] + tools_ttl_ms: NotRequired[ReadOnly[int | None]] tools: NotRequired[ReadOnly[list[MCPToolsetTool]]] created_at: NotRequired[ReadOnly[datetime | None]] created_by: NotRequired[ReadOnly[str | None]] @@ -36,6 +37,7 @@ class MCPToolsetRowData(TypedDict): toolset_id: ReadOnly[str] toolset_name: ReadOnly[str] description: NotRequired[ReadOnly[str | None]] + tools_ttl_ms: NotRequired[ReadOnly[int | None]] tools: NotRequired[ReadOnly[str | list[MCPToolsetTool]]] created_at: NotRequired[ReadOnly[datetime | None]] created_by: NotRequired[ReadOnly[str | None]] diff --git a/litellm/proxy/_lazy_openapi_snapshot.json b/litellm/proxy/_lazy_openapi_snapshot.json index 7198d74909c..2dc5b12ed4c 100644 --- a/litellm/proxy/_lazy_openapi_snapshot.json +++ b/litellm/proxy/_lazy_openapi_snapshot.json @@ -35226,6 +35226,18 @@ ], "title": "Tool Name To Display Name" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "transport": { "default": "sse", "enum": [ @@ -37150,6 +37162,18 @@ ], "title": "Tool Name To Display Name" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "transport": { "enum": [ "sse", @@ -38054,6 +38078,18 @@ ], "title": "Tool Name To Display Name" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "transport": { "default": "sse", "enum": [ @@ -40349,6 +40385,18 @@ ], "title": "Tool Name To Display Name" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "transport": { "enum": [ "sse", @@ -42097,6 +42145,18 @@ ], "title": "Tool Name To Display Name" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "transport": { "default": "sse", "enum": [ @@ -42143,6 +42203,18 @@ "title": "Tools", "type": "array" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "toolset_name": { "title": "Toolset Name", "type": "string" @@ -42620,6 +42692,18 @@ ], "title": "Tool Name To Display Name" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "transport": { "default": "sse", "enum": [ @@ -42675,6 +42759,18 @@ ], "title": "Tools" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "toolset_id": { "title": "Toolset Id", "type": "string" @@ -45561,6 +45657,18 @@ ], "title": "Tool Name To Display Name" }, + "tools_ttl_ms": { + "anyOf": [ + { + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tools Ttl Ms" + }, "transport": { "default": "sse", "enum": [ diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 315533d6d0f..d8645fa5008 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -1377,6 +1377,7 @@ class NewMCPServerRequest(LiteLLMPydanticObjectBase): credentials: MCPCredentials | None = None url: str | None = None spec_path: str | None = None + tools_ttl_ms: int | None = Field(default=None, ge=0) mcp_info: MCPInfo | None = None mcp_access_groups: list[str] = Field(default_factory=list) allowed_tools: list[str] | None = None @@ -1485,6 +1486,7 @@ class UpdateMCPServerRequest(LiteLLMPydanticObjectBase): credentials: MCPCredentials | None = None url: str | None = None spec_path: str | None = None + tools_ttl_ms: int | None = Field(default=None, ge=0) mcp_info: MCPInfo | None = None mcp_access_groups: list[str] = Field(default_factory=list) allowed_tools: list[str] | None = None diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index c6d3e12a378..810881a4147 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -21685,12 +21685,15 @@ async def toolset_mcp_route(toolset_name: str, request: Request): will be rejected with a 403. """ try: + from litellm.proxy._experimental.mcp_server.mcp_context import ( + mcp_active_toolset_id, + mcp_active_toolset_tools_ttl_ms, + ) from litellm.proxy._experimental.mcp_server.mcp_server_manager import ( global_mcp_server_manager, ) from litellm.proxy._experimental.mcp_server.server import ( handle_streamable_http_mcp, - mcp_active_toolset_id, ) if prisma_client is None: @@ -21707,9 +21710,11 @@ async def toolset_mcp_route(toolset_name: str, request: Request): scope["path"] = "/mcp" token: Final = mcp_active_toolset_id.set(toolset.toolset_id) + ttl_token: Final = mcp_active_toolset_tools_ttl_ms.set(toolset.tools_ttl_ms) try: return await _stream_mcp_asgi_response(handle_streamable_http_mcp, scope, request.receive) finally: + mcp_active_toolset_tools_ttl_ms.reset(ttl_token) mcp_active_toolset_id.reset(token) except HTTPException as e: @@ -21851,9 +21856,12 @@ async def dynamic_mcp_route(mcp_server_name: str, request: Request): # 3. Toolset name (cached) if prisma_client is not None: + from litellm.proxy._experimental.mcp_server.mcp_context import ( + mcp_active_toolset_id, + mcp_active_toolset_tools_ttl_ms, + ) from litellm.proxy._experimental.mcp_server.server import ( handle_streamable_http_mcp, - mcp_active_toolset_id, ) toolset: Final = await global_mcp_server_manager.get_toolset_by_name_cached(prisma_client, mcp_server_name) @@ -21862,9 +21870,11 @@ async def dynamic_mcp_route(mcp_server_name: str, request: Request): scope["_original_path"] = scope.get("path", "") scope["path"] = "/mcp" token: Final = mcp_active_toolset_id.set(toolset.toolset_id) + ttl_token: Final = mcp_active_toolset_tools_ttl_ms.set(toolset.tools_ttl_ms) try: return await _stream_mcp_asgi_response(handle_streamable_http_mcp, scope, request.receive) finally: + mcp_active_toolset_tools_ttl_ms.reset(ttl_token) mcp_active_toolset_id.reset(token) # 4. MCP access group tag (cached) diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma index 83a0e6f9e05..b0171d6fced 100644 --- a/litellm/proxy/schema.prisma +++ b/litellm/proxy/schema.prisma @@ -367,6 +367,7 @@ model LiteLLM_MCPServerTable { instructions String? url String? spec_path String? + tools_ttl_ms Int? transport String @default("sse") auth_type String? credentials Json? @default("{}") @@ -434,6 +435,7 @@ model LiteLLM_MCPToolsetTable { toolset_id String @id @default(uuid()) toolset_name String @unique description String? + tools_ttl_ms Int? tools Json @default("[]") // [{server_id: string, tool_name: string}] created_at DateTime @default(now()) created_by String? diff --git a/litellm/types/mcp_server/mcp_server_manager.py b/litellm/types/mcp_server/mcp_server_manager.py index 219f23200d2..773a4302280 100644 --- a/litellm/types/mcp_server/mcp_server_manager.py +++ b/litellm/types/mcp_server/mcp_server_manager.py @@ -100,6 +100,7 @@ class MCPServer(LiteLLMBaseModel): transport: MCPTransportType protocol_version: MCPUpstreamProtocol = "auto" spec_path: str | None = None + tools_ttl_ms: int | None = Field(default=None, ge=0) auth_type: MCPAuthType | None = None authentication_token: str | None = None instructions: str | None = None diff --git a/litellm/types/mcp_server/mcp_toolset.py b/litellm/types/mcp_server/mcp_toolset.py index 2eab0af161f..bee079d585f 100644 --- a/litellm/types/mcp_server/mcp_toolset.py +++ b/litellm/types/mcp_server/mcp_toolset.py @@ -15,6 +15,7 @@ class MCPToolset(LiteLLMBaseModel): toolset_id: str toolset_name: str description: str | None = None + tools_ttl_ms: int | None = Field(default=None, ge=0) tools: list[MCPToolsetTool] = Field(default=[]) created_at: datetime | None = None created_by: str | None = None @@ -25,6 +26,7 @@ class MCPToolset(LiteLLMBaseModel): class NewMCPToolsetRequest(LiteLLMBaseModel): toolset_name: str description: str | None = None + tools_ttl_ms: int | None = Field(default=None, ge=0) tools: list[MCPToolsetTool] = Field(default=[]) @@ -32,4 +34,5 @@ class UpdateMCPToolsetRequest(LiteLLMBaseModel): toolset_id: str toolset_name: str | None = None description: str | None = None + tools_ttl_ms: int | None = Field(default=None, ge=0) tools: list[MCPToolsetTool] | None = None diff --git a/litellm/types/mcp_server/tool_registry.py b/litellm/types/mcp_server/tool_registry.py index 738d37c9503..c7079511cf2 100644 --- a/litellm/types/mcp_server/tool_registry.py +++ b/litellm/types/mcp_server/tool_registry.py @@ -13,6 +13,8 @@ class MCPTool(LiteLLMBaseModel): input_schema: dict[str, Any] handler: Callable server_id: str | None = Field(default=None, frozen=True) + output_schema: dict[str, object] | None = None # mutable-ok: SDK tools require a dict-shaped output schema + title: str | None = None class ToolSchema(LiteLLMBaseModel): diff --git a/schema.prisma b/schema.prisma index 83a0e6f9e05..b0171d6fced 100644 --- a/schema.prisma +++ b/schema.prisma @@ -367,6 +367,7 @@ model LiteLLM_MCPServerTable { instructions String? url String? spec_path String? + tools_ttl_ms Int? transport String @default("sse") auth_type String? credentials Json? @default("{}") @@ -434,6 +435,7 @@ model LiteLLM_MCPToolsetTable { toolset_id String @id @default(uuid()) toolset_name String @unique description String? + tools_ttl_ms Int? tools Json @default("[]") // [{server_id: string, tool_name: string}] created_at DateTime @default(now()) created_by String? diff --git a/tests/code_coverage_tests/recursive_detector.py b/tests/code_coverage_tests/recursive_detector.py index 7610d602fff..c9597ee0c3e 100644 --- a/tests/code_coverage_tests/recursive_detector.py +++ b/tests/code_coverage_tests/recursive_detector.py @@ -2,6 +2,7 @@ import ast import os IGNORE_FUNCTIONS = [ + "_normalize_openapi_nullable_schema", # input bounded by MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES. "_json_cost", # bounded at depth 32 and consumed under byte/node limits. "_format_type", "remove_additional_properties", diff --git a/tests/unit/proxy/_experimental/mcp_server/test_catalog.py b/tests/unit/proxy/_experimental/mcp_server/test_catalog.py index b383078c0ed..0f57f182761 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_catalog.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_catalog.py @@ -624,6 +624,54 @@ async def test_tool_catalog_preserves_upstream_freshness() -> None: assert result.cache_scope == "private" +@pytest.mark.asyncio +async def test_toolset_ttl_overrides_complete_listing_and_keeps_private_cache_scope( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from litellm.proxy._experimental.mcp_server import operations + from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing + + listing_result: Final = AggregateToolListing( + tools=[], + outcomes={"server": ServerListOk(tool_count=0)}, + ttl_ms=9000, + ) + monkeypatch.setattr(operations, "_list_mcp_tools", AsyncMock(return_value=listing_result)) + result: Final = await catalog.list_gateway_tools( + operations.prepare_context(toolset_tools_ttl_ms=0), + PaginatedRequestParams(), + log_list_tools_to_spendlogs=False, + ) + + assert result.ttl_ms == 0 + assert result.model_dump(mode="json", by_alias=True, exclude_none=True)["ttlMs"] == 0 + assert result.cache_scope == "private" + + +@pytest.mark.asyncio +async def test_toolset_ttl_does_not_override_partial_listing(monkeypatch: pytest.MonkeyPatch) -> None: + from litellm.proxy._experimental.mcp_server import operations + from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing, ServerListFault + + listing_result: Final = AggregateToolListing( + tools=[], + outcomes={ + "healthy": ServerListOk(tool_count=0), + "failed": ServerListFault(tag="timeout"), + }, + ttl_ms=0, + ) + monkeypatch.setattr(operations, "_list_mcp_tools", AsyncMock(return_value=listing_result)) + result: Final = await catalog.list_gateway_tools( + operations.prepare_context(toolset_tools_ttl_ms=9000), + PaginatedRequestParams(), + log_list_tools_to_spendlogs=False, + ) + + assert result.ttl_ms == 0 + assert result.cache_scope == "private" + + @pytest.mark.asyncio @pytest.mark.parametrize("upstream_ttl,limit,expected_ttl", [(1000, 60, 1000), (90000, 1, 1000), (0, 60, 0)]) async def test_discovery_cache_uses_upstream_freshness_and_configured_cap( diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py index d6894979906..1d99fd80e54 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py @@ -90,6 +90,13 @@ async def test_partial_update_omits_unset_defaultful_fields(): ) +@pytest.mark.asyncio +async def test_server_ttl_update_sets_clears_and_omits(): + assert (await _run_update(UpdateMCPServerRequest(server_id="s", tools_ttl_ms=2400)))["tools_ttl_ms"] == 2400 + assert (await _run_update(UpdateMCPServerRequest(server_id="s", tools_ttl_ms=None)))["tools_ttl_ms"] is None + assert "tools_ttl_ms" not in await _run_update(UpdateMCPServerRequest(server_id="s", allowed_tools=["tool"])) + + @pytest.mark.asyncio async def test_partial_update_null_tool_name_maps_clear_to_empty_json(): """Explicit null on Json map fields must clear overrides (UI legacy).""" @@ -900,6 +907,38 @@ async def test_toolset_partial_update_clears_description_on_explicit_null(): assert await _run_toolset_update({"toolset_id": "ts-1", "description": None}) == {"description": None} +@pytest.mark.asyncio +async def test_toolset_partial_update_persists_zero_ttl_and_clears_null_ttl(): + assert await _run_toolset_update({"toolset_id": "ts-1", "tools_ttl_ms": 0}) == {"tools_ttl_ms": 0} + assert await _run_toolset_update({"toolset_id": "ts-1", "tools_ttl_ms": None}) == {"tools_ttl_ms": None} + + +@pytest.mark.asyncio +async def test_toolset_ttl_create_update_and_omission(): + from litellm.proxy._experimental.mcp_server.toolset_db import create_mcp_toolset + from litellm.types.mcp_server.mcp_toolset import NewMCPToolsetRequest + + mock_prisma = _mock_toolset_prisma() + created_row = MagicMock() + created_row.model_dump.return_value = { + "toolset_id": "ts-1", + "toolset_name": "ops", + "tools_ttl_ms": 1200, + "tools": "[]", + } + mock_prisma.db.litellm_mcptoolsettable.create = AsyncMock(return_value=created_row) + + created = await create_mcp_toolset( + mock_prisma, + NewMCPToolsetRequest(toolset_name="ops", tools=[], tools_ttl_ms=1200), + "test-user", + ) + assert mock_prisma.db.litellm_mcptoolsettable.create.call_args.kwargs["data"]["tools_ttl_ms"] == 1200 + assert created.tools_ttl_ms == 1200 + assert await _run_toolset_update({"toolset_id": "ts-1", "tools_ttl_ms": 2400}) == {"tools_ttl_ms": 2400} + assert await _run_toolset_update({"toolset_id": "ts-1"}) == {} + + @pytest.mark.asyncio async def test_toolset_partial_update_omits_the_fields_the_caller_left_out(): tools = [{"server_id": "s1", "tool_name": "alpha"}] diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py index de711d737d0..cd861229005 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py @@ -981,6 +981,7 @@ async def test_get_tools_from_mcp_servers(): proxy_logging_obj=None, catalog_auth_header=None, record_listing=True, + wire_compat=None, ): if server.server_id == "server1_id": return [mock_tool_1] diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py index 4896c2f1706..87ff0576548 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py @@ -879,6 +879,42 @@ class TestMCPServerManager: assert server.alias == "friendly_alias" assert server.server_name == "validserver" + @pytest.mark.asyncio + async def test_load_servers_from_config_preserves_openapi_display_name_overrides( + self, config_only_mcp_manager_factory, tmp_path + ): + manager = config_only_mcp_manager_factory() + spec_path = tmp_path / "petstore.json" + spec_path.write_text( + json.dumps( + { + "openapi": "3.0.0", + "paths": { + "/pets/{petId}": { + "get": { + "operationId": "getPetById", + "summary": "Find pet by ID", + "responses": {"200": {"description": "Success"}}, + } + } + }, + } + ) + ) + + await manager.load_servers_from_config( + { + "petstore": { + "url": "https://petstore.test", + "spec_path": str(spec_path), + "tool_name_to_display_name": {"getPetById": "Get Pet"}, + } + } + ) + + server: Final = next(iter(manager.config_mcp_servers.values())) + assert server.tool_name_to_display_name == {"getPetById": "Get Pet"} + def _oauth2_config(self, **overrides): base = { "url": "https://example.com/mcp", @@ -16552,6 +16588,174 @@ async def test_openapi_listing_finds_tools_registered_under_the_normalized_prefi assert [t.name for t in listed] == ["list"] +@pytest.mark.asyncio +@pytest.mark.parametrize(("configured_ttl", "expected_ttl"), ((0, 0), (2500, 2500), (None, 0))) +async def test_openapi_listing_uses_configured_tools_ttl(configured_ttl: int | None, expected_ttl: int) -> None: + from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry + + manager: Final = MCPServerManager() + manager.create_mcp_client = AsyncMock(return_value=AsyncMock()) + global_mcp_tool_registry.unregister_tools_with_prefix("pet-") + _register_local_tool("pet-list", "Pet tool") + server: Final = _openapi_server("pet").model_copy(update={"tools_ttl_ms": configured_ttl}) + try: + listed: Final = await manager.get_tools_page(server=server, add_prefix=False) + finally: + global_mcp_tool_registry.unregister_tools_with_prefix("pet-") + + assert listed.ttl_ms == expected_ttl + assert listed.model_dump(mode="json", by_alias=True, exclude_none=True)["ttlMs"] == expected_ttl + + +@pytest.mark.asyncio +async def test_openapi_listing_serializes_metadata_only_for_modern_revision() -> None: + from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry + from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat + + manager: Final = MCPServerManager() + manager.create_mcp_client = AsyncMock(return_value=AsyncMock()) + global_mcp_tool_registry.unregister_tools_with_prefix("pet-") + + async def handler(**kwargs: object) -> None: + return None + + global_mcp_tool_registry.register_tool( + name="pet-list", + description="Pet tool", + input_schema={"type": "object"}, + handler=handler, + output_schema={"type": "object", "properties": {"count": {"type": "integer"}}}, + title="List pets", + ) + try: + modern: Final = await manager.get_tools_page( + server=_openapi_server("pet"), add_prefix=False, wire_compat=WireCompat.MODERN + ) + legacy: Final = await manager.get_tools_page( + server=_openapi_server("pet"), add_prefix=False, wire_compat=WireCompat.LEGACY + ) + finally: + global_mcp_tool_registry.unregister_tools_with_prefix("pet-") + + modern_wire: Final = modern.model_dump(mode="json", by_alias=True, exclude_none=True) + legacy_wire: Final = legacy.model_dump(mode="json", by_alias=True, exclude_none=True) + assert modern_wire["tools"][0]["title"] == "List pets" + assert modern_wire["tools"][0]["outputSchema"] == { + "type": "object", + "properties": {"count": {"type": "integer"}}, + } + assert "title" not in legacy_wire["tools"][0] + assert "outputSchema" not in legacy_wire["tools"][0] + + +@pytest.mark.asyncio +async def test_manager_openapi_registration_lists_response_metadata_for_modern_revision(tmp_path: Path) -> None: + from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry + from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat + + spec_path: Final = tmp_path / "openapi.json" + spec_path.write_text( + json.dumps( + { + "openapi": "3.0.0", + "info": {"title": "Demo", "version": "1.0.0"}, + "components": { + "schemas": { + "Pet": { + "type": "object", + "properties": {"owner": {"$ref": "#/components/schemas/Owner"}}, + }, + "Owner": {"type": "object", "properties": {"name": {"type": "string"}}}, + } + }, + "paths": { + "/pets": { + "get": { + "operationId": "list_pets", + "summary": "List pets", + "responses": { + "200": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Pet"}, + } + } + } + }, + } + } + }, + } + ) + ) + server: Final = _openapi_server("pet").model_copy(update={"spec_path": str(spec_path)}) + manager: Final = MCPServerManager() + manager.create_mcp_client = AsyncMock(return_value=AsyncMock()) + global_mcp_tool_registry.unregister_tools_with_prefix("pet-") + + try: + await manager._register_openapi_tools(str(spec_path), server, "https://example.com") + modern: Final = await manager.get_tools_page(server=server, add_prefix=False, wire_compat=WireCompat.MODERN) + legacy: Final = await manager.get_tools_page(server=server, add_prefix=False, wire_compat=WireCompat.LEGACY) + finally: + global_mcp_tool_registry.unregister_tools_with_prefix("pet-") + + modern_wire: Final = modern.model_dump(mode="json", by_alias=True, exclude_none=True) + legacy_wire: Final = legacy.model_dump(mode="json", by_alias=True, exclude_none=True) + assert modern_wire["tools"][0]["outputSchema"] == { + "type": "object", + "properties": {"owner": {"type": "object", "properties": {"name": {"type": "string"}}}}, + } + assert modern_wire["tools"][0]["title"] == "List pets" + assert "outputSchema" not in legacy_wire["tools"][0] + assert "title" not in legacy_wire["tools"][0] + + +@pytest.mark.asyncio +async def test_toolset_name_cache_round_trips_configured_tools_ttl(monkeypatch: pytest.MonkeyPatch) -> None: + from litellm.proxy._experimental.mcp_server import toolset_db + from litellm.types.mcp_server.mcp_toolset import MCPToolset + + cache: Final = DualCache() + toolset: Final = MCPToolset(toolset_id="ttl-toolset", toolset_name="ttl-toolset", tools_ttl_ms=0) + fetch: Final = AsyncMock(return_value=toolset) + monkeypatch.setattr(proxy_server, "user_api_key_cache", cache) + monkeypatch.setattr(toolset_db, "get_mcp_toolset_by_name", fetch) + manager: Final = MCPServerManager() + + first: Final = await manager.get_toolset_by_name_cached(None, "ttl-toolset") + second: Final = await manager.get_toolset_by_name_cached(None, "ttl-toolset") + + assert first is not None and first.tools_ttl_ms == 0 + assert second is not None and second.tools_ttl_ms == 0 + fetch.assert_awaited_once() + + +@pytest.mark.asyncio +async def test_toolset_name_cache_returns_updated_ttl_after_invalidation(monkeypatch: pytest.MonkeyPatch) -> None: + from litellm.proxy._experimental.mcp_server import toolset_db + from litellm.types.mcp_server.mcp_toolset import MCPToolset + + cache: Final = DualCache() + old_toolset: Final = MCPToolset(toolset_id="ttl-toolset", toolset_name="ttl-toolset", tools_ttl_ms=0) + updated_toolset: Final = MCPToolset(toolset_id="ttl-toolset", toolset_name="ttl-toolset", tools_ttl_ms=2400) + await cache.async_set_cache( + key="toolset_name:ttl-toolset", + value=old_toolset.model_dump(mode="json"), + ttl=60, + ) + fetch: Final = AsyncMock(return_value=updated_toolset) + monkeypatch.setattr(proxy_server, "user_api_key_cache", cache) + monkeypatch.setattr(toolset_db, "get_mcp_toolset_by_name", fetch) + manager: Final = MCPServerManager() + + manager.invalidate_toolset_cache("ttl-toolset") + result: Final = await manager.get_toolset_by_name_cached(None, "ttl-toolset") + + assert result is not None and result.tools_ttl_ms == 2400 + fetch.assert_awaited_once() + + @pytest.mark.asyncio async def test_discovery_cache_retries_cancelled_fetches() -> None: from litellm.proxy._experimental.mcp_server.catalog import _DiscoveryCache diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py index b8e28c3f9b8..278df3081e0 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py @@ -1017,6 +1017,9 @@ async def test_get_resource_templates_from_mcp_servers_success(): server.server_id = "server-id" server.auth_type = None server.extra_headers = None + server.spec_path = None + server.tools_ttl_ms = None + server.tool_name_to_display_name = None with ( patch( @@ -4489,6 +4492,9 @@ async def test_list_tools_single_server_unprefixed_names(): server.server_name = "server1" server.auth_type = None server.extra_headers = None + server.spec_path = None + server.tools_ttl_ms = None + server.tool_name_to_display_name = None # Mock manager: allow just one server and return a tool based on add_prefix flag mock_manager = MagicMock() @@ -4557,6 +4563,9 @@ async def test_list_tools_multiple_servers_prefixed_names(): server1.server_name = "server1" server1.auth_type = None server1.extra_headers = None + server1.spec_path = None + server1.tools_ttl_ms = None + server1.tool_name_to_display_name = None server2 = MagicMock() server2.server_id = "server2" @@ -4567,6 +4576,9 @@ async def test_list_tools_multiple_servers_prefixed_names(): server2.server_name = "server2" server2.auth_type = None server2.extra_headers = None + server2.spec_path = None + server2.tools_ttl_ms = None + server2.tool_name_to_display_name = None # Mock manager mock_manager = MagicMock() @@ -4980,6 +4992,9 @@ async def test_list_tools_filters_by_key_team_permissions(): server.server_name = "server1" server.auth_type = None server.extra_headers = None + server.spec_path = None + server.tools_ttl_ms = None + server.tool_name_to_display_name = None # Mock manager mock_manager = MagicMock() @@ -5091,6 +5106,9 @@ async def test_list_tools_with_team_tool_permissions_inheritance(): server.server_name = "server1" server.auth_type = None server.extra_headers = None + server.spec_path = None + server.tools_ttl_ms = None + server.tool_name_to_display_name = None # Mock manager mock_manager = MagicMock() @@ -5188,6 +5206,9 @@ async def test_list_tools_with_no_tool_permissions_shows_all(): server.server_name = "server1" server.auth_type = None server.extra_headers = None + server.spec_path = None + server.tools_ttl_ms = None + server.tool_name_to_display_name = None # Mock manager mock_manager = MagicMock() @@ -5289,6 +5310,9 @@ async def test_list_tools_strips_prefix_when_matching_permissions(): server.server_name = "GITMCP" server.allowed_tools = None server.disallowed_tools = None + server.spec_path = None + server.tools_ttl_ms = None + server.tool_name_to_display_name = None # Mock manager mock_manager = MagicMock() @@ -5496,6 +5520,74 @@ def test_apply_display_name_overrides_no_overrides(): assert result[0].description == "Original description" +def test_apply_display_name_overrides_modern_openapi_preserves_name_and_matches_camel_case() -> None: + from mcp.types import Tool + + from litellm.proxy._experimental.mcp_server.operations import apply_display_name_overrides + from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat + from litellm.types.mcp import MCPTransport + from litellm.types.mcp_server.mcp_server_manager import MCPServer + + mcp_server = MCPServer( + server_id="my_api_mcp", + name="my_api_mcp", + transport=MCPTransport.http, + spec_path="https://api.example.com/openapi.json", + tool_name_to_display_name={"getPetById": "Get Pet"}, + ) + tool = Tool( + name="my_api_mcp-getpetbyid", + title="Get a pet", + description="Original description", + inputSchema={"type": "object", "properties": {}}, + outputSchema={"type": "object"}, + annotations=None, + ) + + result = apply_display_name_overrides([tool], mcp_server, wire_compat=WireCompat.MODERN) + + assert result[0].name == tool.name + assert result[0].title == "Get Pet" + assert tool.title == "Get a pet" + + +def test_resolve_display_name_to_original_sanitizes_openapi_operation_id() -> None: + from litellm.proxy._experimental.mcp_server.operations import _resolve_display_name_to_original + from litellm.types.mcp import MCPTransport + from litellm.types.mcp_server.mcp_server_manager import MCPServer + + server = MCPServer( + server_id="my_api_mcp", + name="my_api_mcp", + transport=MCPTransport.http, + spec_path="https://api.example.com/openapi.json", + tool_name_to_display_name={"getPetById": "Get Pet"}, + ) + + assert _resolve_display_name_to_original("Get Pet", [server]) == "my_api_mcp-getpetbyid" + + +def test_convert_tools_to_mcp_sdk_tool_type_serializes_modern_metadata() -> None: + from litellm.proxy._experimental.mcp_server.tool_registry import MCPToolRegistry + from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat + from litellm.types.mcp_server.tool_registry import MCPTool + + tool = MCPTool( + name="getpetbyid", + description="Get a pet", + input_schema={"type": "object"}, + handler=lambda: None, + output_schema={"type": "object", "properties": {"id": {"type": "string"}}}, + title="Get Pet", + ) + + serialized = MCPToolRegistry().convert_tools_to_mcp_sdk_tool_type([tool], wire_compat=WireCompat.MODERN)[0] + + wire_value = serialized.model_dump(mode="json", by_alias=True) + assert wire_value["outputSchema"] == tool.output_schema + assert wire_value["title"] == "Get Pet" + + def _make_db_mcp_server(server_id: str, updated_at: datetime) -> LiteLLM_MCPServerTable: return LiteLLM_MCPServerTable( server_id=server_id, @@ -5831,6 +5923,9 @@ async def test_get_tools_from_mcp_servers_logs_list_tools_to_spendlogs_when_enab server_a.server_id = "a" server_a.auth_type = None server_a.extra_headers = None + server_a.spec_path = None + server_a.tools_ttl_ms = None + server_a.tool_name_to_display_name = None tool_1 = MCPTool( name="server_a-tool_1", @@ -5989,6 +6084,9 @@ async def test_get_tools_from_mcp_servers_returns_tools_when_success_logging_fai server_a.server_id = "a" server_a.auth_type = None server_a.extra_headers = None + server_a.spec_path = None + server_a.tools_ttl_ms = None + server_a.tool_name_to_display_name = None tool_1 = Tool(name="placeholder", inputSchema={}) tool_1.name = "server_a-tool_1" @@ -6312,6 +6410,9 @@ async def test_get_tools_from_mcp_servers_injects_stored_oauth2_token(): oauth2_server.server_id = SERVER_ID oauth2_server.auth_type = MCPAuth.oauth2 oauth2_server.extra_headers = None + oauth2_server.spec_path = None + oauth2_server.tools_ttl_ms = None + oauth2_server.tool_name_to_display_name = None # Simulate the DB returning a valid credential for this user+server prefetched_creds = {SERVER_ID: {"access_token": STORED_TOKEN, "server_id": SERVER_ID}} diff --git a/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py b/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py index 9f3db632db1..223649b5366 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py @@ -9,6 +9,8 @@ This test suite ensures that: 5. Path parameters are properly URL encoded """ +from copy import deepcopy +from time import perf_counter from types import SimpleNamespace from typing import Final from unittest.mock import AsyncMock, patch @@ -17,27 +19,346 @@ import pytest from fastapi import HTTPException from respx import MockRouter -from litellm.types.mcp import MCPAuth, MCPAuthType - +from litellm import constants from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import ( - request_auth_header, - request_extra_headers, - request_resolved_auth_headers, + _OpenAPISpec, _request_upstream_url, _resolve_param_list, _resolve_ref, build_input_schema, + build_output_schema, create_tool_function, extract_parameters, get_base_url, + request_auth_header, + request_extra_headers, + request_resolved_auth_headers, resolve_operation_params, ) -from litellm.proxy._experimental.mcp_server.tool_outcome import JsonResult, TextResult +from litellm.types.mcp import MCPAuth, MCPAuthType + + +def _doubling_openapi_spec(levels: int) -> _OpenAPISpec: + schemas: Final = { + **{ + f"Level{index}": { + "type": "object", + "properties": { + "left": {"$ref": f"#/components/schemas/Level{index + 1}"}, + "right": {"$ref": f"#/components/schemas/Level{index + 1}"}, + }, + } + for index in range(levels) + }, + f"Level{levels}": {"type": "object", "properties": {"leaf": {"type": "string"}}}, + } + return { + "components": {"schemas": schemas}, + "paths": { + "/doubling": { + "get": { + "operationId": "openapi-budget-doubling", + "summary": "Budgeted doubling", + "responses": { + "200": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Level0"}, + } + } + } + }, + } + } + }, + } + + +def test_build_output_schema_resolves_nested_json_refs_without_mutating_spec() -> None: + spec = { + "components": { + "schemas": { + "Pet": { + "type": "object", + "properties": {"owner": {"$ref": "#/components/schemas/Owner"}}, + }, + "Owner": {"type": "object", "properties": {"name": {"type": "string"}}}, + } + } + } + operation = { + "responses": { + "201": {"content": {"application/vnd.api+json": {"schema": {"$ref": "#/components/schemas/Pet"}}}}, + "204": {"content": {"application/json": {"schema": {"type": "string"}}}}, + } + } + original = deepcopy(spec) + + result = build_output_schema(operation, spec) + + assert result == { + "type": "object", + "properties": { + "owner": {"type": "object", "properties": {"name": {"type": "string"}}}, + }, + } + assert spec == original + + +@pytest.mark.asyncio +async def test_build_output_schema_normalizes_nullable_values_for_sdk_validation() -> None: + import anyio + from mcp import ClientSession + from mcp.shared.message import SessionMessage + from mcp.types import CallToolResult, ListToolsResult, TextContent, Tool + + spec = { + "components": { + "schemas": { + "Pet": { + "type": "object", + "properties": {"tag": {"type": "string", "nullable": True}}, + }, + } + } + } + operation = { + "responses": { + "200": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Pet"}, + } + } + } + } + } + + result = build_output_schema(operation, spec) + + assert result is not None + send, receive = anyio.create_memory_object_stream[SessionMessage](1) + async with send, receive: + client = ClientSession(receive, send) + client._absorb_tool_listing( + ListToolsResult( + tools=[ + Tool( + name="get-pet", + inputSchema={"type": "object"}, + outputSchema=result, + ) + ] + ), + complete=True, + ) + await client.validate_tool_result( + "get-pet", + CallToolResult( + content=[TextContent(type="text", text="{}")], + structuredContent={"tag": None}, + isError=False, + ), + ) + assert result == { + "type": "object", + "properties": {"tag": {"type": ["string", "null"]}}, + } + + +async def _validate_output_schema_result( + output_schema: dict[str, object], structured_content: dict[str, object] +) -> None: + import anyio + from mcp import ClientSession + from mcp.shared.message import SessionMessage + from mcp.types import CallToolResult, ListToolsResult, TextContent, Tool + + send, receive = anyio.create_memory_object_stream[SessionMessage](1) + async with send, receive: + client = ClientSession(receive, send) + client._absorb_tool_listing( + ListToolsResult( + tools=[ + Tool( + name="get-pet", + inputSchema={"type": "object"}, + outputSchema=output_schema, + ) + ] + ), + complete=True, + ) + await client.validate_tool_result( + "get-pet", + CallToolResult( + content=[TextContent(type="text", text="{}")], + structuredContent=structured_content, + isError=False, + ), + ) + + +@pytest.mark.asyncio +async def test_build_output_schema_normalizes_nullable_allof_ref_for_sdk_validation() -> None: + spec = { + "components": { + "schemas": { + "Owner": {"type": "object", "properties": {"name": {"type": "string"}}}, + "Pet": { + "type": "object", + "properties": { + "owner": { + "allOf": [{"$ref": "#/components/schemas/Owner"}], + "nullable": True, + } + }, + }, + } + } + } + operation = { + "responses": { + "200": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Pet"}, + } + } + } + } + } + + result = build_output_schema(operation, spec) + + assert result == { + "type": "object", + "properties": { + "owner": { + "anyOf": [ + { + "allOf": [ + {"type": "object", "properties": {"name": {"type": "string"}}}, + ] + }, + {"type": "null"}, + ] + } + }, + } + await _validate_output_schema_result(result, {"owner": None}) + + +@pytest.mark.asyncio +async def test_build_output_schema_normalizes_boolean_exclusive_minimum_for_sdk_validation() -> None: + spec = { + "components": { + "schemas": { + "Pet": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": True, + } + }, + }, + } + } + } + operation = { + "responses": { + "200": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Pet"}, + } + } + } + } + } + + result = build_output_schema(operation, spec) + + assert result == { + "type": "object", + "properties": {"id": {"type": "integer", "exclusiveMinimum": 0}}, + } + await _validate_output_schema_result(result, {"id": 1}) + + +@pytest.mark.parametrize( + ("response", "expected"), + [ + ({"200": {"content": {"application/json": {"schema": {"type": "array"}}}}}, None), + ({"200": {"content": {"text/plain": {"schema": {"type": "object"}}}}}, None), + ({"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Missing"}}}}}, None), + ( + {"2XX": {"content": {"application/json": {"schema": {"type": "object", "properties": {}}}}}}, + {"type": "object", "properties": {}}, + ), + ], +) +def test_build_output_schema_rejects_invalid_or_uses_range_response( + response: dict[str, object], expected: dict[str, object] | None +) -> None: + assert build_output_schema({"responses": response}, {}) == expected + + +def test_build_output_schema_rejects_cyclic_refs_and_selects_lowest_numeric_2xx() -> None: + spec = { + "components": { + "schemas": { + "Cycle": {"type": "object", "properties": {"next": {"$ref": "#/components/schemas/Cycle"}}}, + } + } + } + operation = { + "responses": { + "201": {"content": {"application/json": {"schema": {"type": "object", "properties": {}}}}}, + "204": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Cycle"}}}}, + } + } + + assert build_output_schema(operation, spec) == {"type": "object", "properties": {}} + assert ( + build_output_schema( + {"responses": {"200": operation["responses"]["204"]}}, + spec, + ) + is None + ) + + +def test_build_output_schema_stops_doubling_chain_within_default_budget(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(constants, "MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES", 10000) + spec: Final = _doubling_openapi_spec(20) + operation: Final = { + "responses": { + "200": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Level0"}, + } + } + } + } + } + + start: Final = perf_counter() + result: Final = build_output_schema(operation, spec) + elapsed: Final = perf_counter() - start + + assert result is None + assert elapsed < 2.0 + from litellm.proxy._experimental.mcp_server.exceptions import ( MCPOpenApiUpstreamError, MCPUpstreamAuthError, ) +from litellm.proxy._experimental.mcp_server.tool_outcome import JsonResult, TextResult GET_ASYNC_CLIENT_TARGET = "litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator.get_async_httpx_client" @@ -1114,6 +1435,80 @@ class TestSanitizeOpenAPIToolName: class TestRegisterToolsFromOpenAPI: """Verify register_tools_from_openapi emits provider-safe tool names.""" + def test_registration_passes_openapi_response_schema_and_summary(self) -> None: + from litellm.proxy._experimental.mcp_server import openapi_to_mcp_generator + from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat + + registry: Final = openapi_to_mcp_generator.global_mcp_tool_registry + tool_prefix: Final = "litellm9923-" + registry.unregister_tools_with_prefix(tool_prefix) + + output_schema: Final = {"type": "object", "properties": {"pets": {"type": "array"}}} + spec: Final = { + "paths": { + "/pets": { + "get": { + "operationId": f"{tool_prefix}list-pets", + "summary": "List pets", + "responses": { + "200": { + "content": { + "application/json": {"schema": output_schema}, + } + } + }, + } + } + } + } + try: + openapi_to_mcp_generator.register_tools_from_openapi(spec, base_url="https://api.example.com") + registered: Final = registry.list_tools(tool_prefix=tool_prefix) + sdk_tools: Final = registry.convert_tools_to_mcp_sdk_tool_type(registered, wire_compat=WireCompat.MODERN) + wire_tool: Final = sdk_tools[0].model_dump(mode="json", by_alias=True, exclude_none=True) + finally: + registry.unregister_tools_with_prefix(tool_prefix) + + assert wire_tool["name"] == "litellm9923-list-pets" + assert wire_tool["outputSchema"] == output_schema + assert wire_tool["title"] == "List pets" + + def test_schema_budget_keeps_registered_tool_name_and_title(self, monkeypatch: pytest.MonkeyPatch) -> None: + from litellm.proxy._experimental.mcp_server import openapi_to_mcp_generator + from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat + + monkeypatch.setattr(constants, "MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES", 50) + spec: Final = _doubling_openapi_spec(7) + operation: Final = { + "responses": { + "200": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Level0"}, + } + } + } + } + } + assert build_output_schema(operation, spec) is None + + registry: Final = openapi_to_mcp_generator.global_mcp_tool_registry + tool_prefix: Final = "openapi-budget-" + registry.unregister_tools_with_prefix(tool_prefix) + try: + openapi_to_mcp_generator.register_tools_from_openapi(spec, base_url="https://api.example.com") + registered: Final = registry.list_tools(tool_prefix=tool_prefix) + sdk_tools: Final = registry.convert_tools_to_mcp_sdk_tool_type(registered, wire_compat=WireCompat.MODERN) + wire_tool: Final = sdk_tools[0].model_dump(mode="json", by_alias=True, exclude_none=True) + registered_tool: Final = registered[0] + finally: + registry.unregister_tools_with_prefix(tool_prefix) + + assert registered_tool.output_schema is None + assert wire_tool["name"] == "openapi-budget-doubling" + assert wire_tool["title"] == "Budgeted doubling" + assert "outputSchema" not in wire_tool + def test_github_style_operation_ids_are_sanitized(self, monkeypatch): import re @@ -1121,7 +1516,7 @@ class TestRegisterToolsFromOpenAPI: registered: list = [] - def _capture(name, description, input_schema, handler): # noqa: ANN001 + def _capture(name, description, input_schema, handler, **kwargs): # noqa: ANN001 registered.append(name) monkeypatch.setattr( @@ -1169,7 +1564,7 @@ class TestRegisterToolsFromOpenAPI: registered: list = [] - def _capture(name, description, input_schema, handler): # noqa: ANN001 + def _capture(name, description, input_schema, handler, **kwargs): # noqa: ANN001 registered.append(name) monkeypatch.setattr( @@ -1572,6 +1967,7 @@ class TestBoundedOpenAPISpecLoading: @pytest.mark.parametrize("headers", [{"content-length": "1000000"}, {"content-encoding": "gzip"}]) async def test_unsafe_response_headers_reject_before_reading(self, respx_mock, monkeypatch, headers): import httpx + from litellm.llms.custom_httpx.http_handler import HTTPResponseLimitError from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import ( load_openapi_spec_async, @@ -1596,6 +1992,7 @@ class TestBoundedOpenAPISpecLoading: @pytest.mark.asyncio async def test_chunked_response_is_bounded_and_closed(self, respx_mock, monkeypatch): import httpx + from litellm.llms.custom_httpx.http_handler import HTTPResponseLimitError from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import ( load_openapi_spec_async, diff --git a/tests/unit/proxy/_experimental/mcp_server/test_operations.py b/tests/unit/proxy/_experimental/mcp_server/test_operations.py index 6f7437c90dc..56e78e6b094 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_operations.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_operations.py @@ -368,24 +368,32 @@ async def test_legacy_adapter_cleans_context_after_cancelled_operation(): from types import SimpleNamespace from litellm.proxy._experimental.mcp_server import server - from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var + from litellm.proxy._experimental.mcp_server.mcp_context import ( + active_mcp_request_ctx_var, + mcp_active_toolset_tools_ttl_ms, + ) previous_session = server.active_mcp_session_var.get() previous_request = active_mcp_request_ctx_var.get() + ttl_token = mcp_active_toolset_tools_ttl_ms.set(1200) request = SimpleNamespace(session=object(), protocol_version="2025-06-18", method="tools/call") auth = (None, None, None, None, None, None, None) async def cancelled_operation(): - async with server._legacy_operation_context(request, trace=False): + async with server._legacy_operation_context(request, trace=False) as context: assert server.active_mcp_session_var.get() is request.session assert active_mcp_request_ctx_var.get() is request + assert context.toolset_tools_ttl_ms == 1200 raise asyncio.CancelledError - with patch( - "litellm.proxy._experimental.mcp_server.server.get_or_extract_auth_context", AsyncMock(return_value=auth) - ): - with pytest.raises(asyncio.CancelledError): - await cancelled_operation() + try: + with patch( + "litellm.proxy._experimental.mcp_server.server.get_or_extract_auth_context", AsyncMock(return_value=auth) + ): + with pytest.raises(asyncio.CancelledError): + await cancelled_operation() + finally: + mcp_active_toolset_tools_ttl_ms.reset(ttl_token) assert server.active_mcp_session_var.get() is previous_session assert active_mcp_request_ctx_var.get() is previous_request @@ -705,6 +713,68 @@ async def test_tools_call_warmup_does_not_consume_mcp_server_rpm() -> None: assert [tool.name for tool in listing.tools] == ["echo"] +@pytest.mark.asyncio +async def test_modern_protocol_metadata_survives_tool_listing_context_rebuild( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from mcp.types import ListToolsResult + + from litellm.proxy import proxy_server + from litellm.proxy._experimental.mcp_server.mcp_server_manager import MCPServerManager + from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat + + server: Final = MCPServer( + server_id="wire-compat-openapi", + name="petstore", + server_name="petstore", + transport=MCPTransport.http, + url="http://petstore.test", + spec_path="petstore.json", + tool_name_to_display_name={"getPetById": "Get Pet"}, + ) + output_schema: Final[dict[str, object]] = { + "type": "object", + "properties": {"name": {"type": "string"}}, + } + manager: Final = MCPServerManager() + manager.config_mcp_servers = {server.server_id: server} + get_tools_page: Final = AsyncMock( + return_value=ListToolsResult( + tools=[ + MCPTool( + name="petstore-getpetbyid", + description="Find pet by ID", + inputSchema={"type": "object"}, + outputSchema=output_schema, + title="Find pet by ID", + ) + ] + ) + ) + monkeypatch.setattr(proxy_server, "prisma_client", None) + monkeypatch.setattr(operations, "global_mcp_server_manager", manager) + monkeypatch.setattr( + operations, + "_get_allowed_mcp_servers", + AsyncMock(return_value=[server]), + ) + monkeypatch.setattr(manager, "get_tools_page", get_tools_page) + + listing: Final = await operations._get_tools_from_mcp_servers( + user_api_key_auth=None, + mcp_auth_header=None, + mcp_servers=[server.server_id], + protocol_version="2026-07-28", + enforce_rate_limits=False, + ) + + listed_tool: Final = listing.tools[0].model_dump(by_alias=True, exclude_none=True) + assert get_tools_page.await_args.kwargs["wire_compat"] is WireCompat.MODERN + assert listed_tool["name"] == "petstore-getpetbyid" + assert listed_tool["title"] == "Get Pet" + assert listed_tool["outputSchema"] == output_schema + + def _scoped_rig( monkeypatch: pytest.MonkeyPatch, ) -> tuple[MCPServer, MCPServer, AsyncMock, AsyncMock]: diff --git a/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py b/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py index 73e248ff52e..b1464f62164 100644 --- a/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py +++ b/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py @@ -4288,7 +4288,9 @@ class TestPreviewOpenAPITools: ) class _StubRegistry: - def register_tool(self, name, description, input_schema, handler): # noqa: ANN001 + def register_tool( + self, name, description, input_schema, handler, output_schema=None, title=None + ): # noqa: ANN001 registered_summary_to_name[description] = name monkeypatch.setattr( diff --git a/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py b/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py index 26553558298..e07e21402eb 100644 --- a/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py +++ b/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py @@ -345,6 +345,7 @@ async def test_execute_tool_calls_reverse_maps_display_name(monkeypatch): server_id="other-server-id", short_prefix=None, mcp_info=None, + spec_path=None, tool_name_to_display_name={"search": "search_docs"}, ) fake_server = types.SimpleNamespace( @@ -353,6 +354,7 @@ async def test_execute_tool_calls_reverse_maps_display_name(monkeypatch): server_id="test-server-id", short_prefix=None, mcp_info=None, + spec_path=None, tool_name_to_display_name={"read_wiki_structure": "browse_repo_docs"}, ) from litellm.proxy._experimental.mcp_server import mcp_server_manager as _msm diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx index 65656a053ce..cb8a64f04a9 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx @@ -123,6 +123,14 @@ describe("CreateMCPServer", () => { expect(screen.getByText("Add New MCP Server")).toBeInTheDocument(); }); + it("shows the tools list TTL input only for OpenAPI transport", async () => { + render(); + + expect(screen.queryByLabelText("Tools list TTL (ms)")).not.toBeInTheDocument(); + await selectOption("Transport Type", "OpenAPI Spec"); + expect(screen.getByLabelText("Tools list TTL (ms)")).toBeInTheDocument(); + }); + // The modal DOES render for a non-admin; it retitles and routes the submit to the review endpoint. // The assertion this replaced only checked that the admin title was absent, which passed for the // wrong reason and left the whole non-admin submission path uncovered. diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx index 07618abb9a4..eac03faf0fa 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx @@ -838,6 +838,30 @@ const CreateMCPServer: React.FC = ({ )} + {transportType === TRANSPORT.OPENAPI && ( + + Tools list TTL (ms) + + + + + } + name="tools_ttl_ms" + > + {(control) => ( + + )} + + )} + {/* Authentication - show for HTTP, SSE, and OpenAPI */} {transportType !== "stdio" && transportType !== "" && ( diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx index 81462c6bf9b..0e923d5f61e 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx @@ -73,14 +73,17 @@ describe("MCPToolsetsTab create/edit toolset form", () => { target: { value: "github-linear-tools" }, }); fireEvent.change(dialog.getByPlaceholderText("Optional description"), { target: { value: "tools for triage" } }); + fireEvent.change(screen.getByLabelText("Tools list TTL (ms)"), { target: { value: "0" } }); await user.click(dialog.getByRole("button", { name: "Create Toolset" })); + const expectedCreate = { + toolset_name: "github-linear-tools", + description: "tools for triage", + tools_ttl_ms: 0, + tools: [], + }; await waitFor(() => { - expect(networking.createMCPToolset).toHaveBeenCalledWith("sk-test", { - toolset_name: "github-linear-tools", - description: "tools for triage", - tools: [], - }); + expect(networking.createMCPToolset).toHaveBeenCalledWith("sk-test", expectedCreate); }); expect(networking.createMCPToolset).toHaveBeenCalledTimes(1); }); @@ -146,6 +149,7 @@ describe("MCPToolsetsTab create/edit toolset form", () => { toolset_id: "ts-1", toolset_name: "existing", description: "old description", + tools_ttl_ms: 2000, tools: [{ server_id: "srv-1", tool_name: "search" }], } as MCPToolset; renderTab([toolset]); @@ -155,6 +159,7 @@ describe("MCPToolsetsTab create/edit toolset form", () => { expect(name).toBe(dialog.getByPlaceholderText("e.g. github-linear-tools")); expect(dialog.getByText("Toolset Name")).toBeInTheDocument(); expect(dialog.getByPlaceholderText("Optional description")).toHaveValue("old description"); + expect(dialog.getByLabelText("Tools list TTL (ms)")).toHaveValue(2000); await user.clear(name); fireEvent.change(name, { target: { value: "renamed" } }); @@ -171,6 +176,90 @@ describe("MCPToolsetsTab create/edit toolset form", () => { }); }); + it("sends null when the toolset tools list TTL is cleared", async () => { + const user = setup(); + vi.mocked(networking.updateMCPToolset).mockResolvedValue( + {} as Awaited>, + ); + renderTab([ + { + toolset_id: "ts-1", + toolset_name: "existing", + tools_ttl_ms: 2000, + tools: [], + } as MCPToolset, + ]); + + await openEditFor(user); + fireEvent.change(screen.getByLabelText("Tools list TTL (ms)"), { target: { value: "" } }); + await user.click(screen.getByRole("button", { name: "Save Changes" })); + + await waitFor(() => { + expect(networking.updateMCPToolset).toHaveBeenCalledWith( + "sk-test", + expect.objectContaining({ toolset_id: "ts-1", tools_ttl_ms: null }), + ); + }); + }); + + it("updates a changed toolset tools list TTL", async () => { + const user = setup(); + vi.mocked(networking.updateMCPToolset).mockResolvedValue( + {} as Awaited>, + ); + renderTab([ + { + toolset_id: "ts-1", + toolset_name: "existing", + tools_ttl_ms: 2000, + tools: [], + } as MCPToolset, + ]); + + await openEditFor(user); + fireEvent.change(screen.getByLabelText("Tools list TTL (ms)"), { target: { value: "3500" } }); + await user.click(screen.getByRole("button", { name: "Save Changes" })); + + await waitFor(() => { + expect(networking.updateMCPToolset).toHaveBeenCalledWith( + "sk-test", + expect.objectContaining({ toolset_id: "ts-1", tools_ttl_ms: 3500 }), + ); + }); + }); + + it("saves the full toolset TTL typed into the edit form", async () => { + const user = setup(); + vi.mocked(networking.updateMCPToolset).mockResolvedValue( + {} as Awaited>, + ); + renderTab([ + { + toolset_id: "ts-1", + toolset_name: "existing", + tools_ttl_ms: 120000, + tools: [], + } as MCPToolset, + ]); + + const dialog = await openEditFor(user); + const ttlInput = dialog.getByLabelText("Tools list TTL (ms)"); + await user.clear(ttlInput); + await user.type(ttlInput, "45000"); + expect(ttlInput).toHaveValue(45000); + await user.click(dialog.getByRole("button", { name: "Save Changes" })); + + await waitFor(() => { + expect(networking.updateMCPToolset).toHaveBeenCalledWith("sk-test", { + toolset_id: "ts-1", + toolset_name: "existing", + description: "", + tools: [], + tools_ttl_ms: 45000, + }); + }); + }); + it("seeds an absent description as an empty string rather than failing", async () => { const user = setup(); vi.mocked(networking.updateMCPToolset).mockResolvedValue( @@ -184,11 +273,11 @@ describe("MCPToolsetsTab create/edit toolset form", () => { } as unknown as MCPToolset; renderTab([toolset]); - const dialog = await openEditFor(user); - await dialog.findByDisplayValue("no-desc"); - expect(dialog.getByPlaceholderText("Optional description")).toHaveValue(""); + await openEditFor(user); + await screen.findByDisplayValue("no-desc"); + expect(screen.getByPlaceholderText("Optional description")).toHaveValue(""); - await user.click(dialog.getByRole("button", { name: "Save Changes" })); + await user.click(screen.getByRole("button", { name: "Save Changes" })); const expectedUpdate = { toolset_id: "ts-2", toolset_name: "no-desc", description: "", tools: [] }; await waitFor(() => { diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx index ff0e8f7b6a9..2c4a928762e 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx @@ -1,7 +1,7 @@ import React, { useState, useCallback } from "react"; import { z } from "zod"; import { SortingState } from "@tanstack/react-table"; -import { Inbox, Plus, X } from "lucide-react"; +import { Inbox, Info, Plus, X } from "lucide-react"; import { useMCPToolsets } from "@/app/(dashboard)/hooks/mcpServers/useMCPToolsets"; import { useMCPServers } from "@/app/(dashboard)/hooks/mcpServers/useMCPServers"; import { useQueryClient } from "@tanstack/react-query"; @@ -24,6 +24,7 @@ import { useZodForm } from "@/lib/forms/useZodForm"; import { toast } from "@/lib/toast"; import { displayToolName, getMCPToolsetTableColumns } from "./MCPToolsetTableColumns"; import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "@/components/ui/dialog"; +import { SimpleTooltip } from "@/components/ui/tooltip"; interface MCPToolsetsTabProps { accessToken: string | null; @@ -33,6 +34,10 @@ interface MCPToolsetsTabProps { const toolsetSchema = z.object({ toolset_name: z.string().min(1, "Please enter a toolset name"), description: z.string(), + tools_ttl_ms: z.preprocess( + (value) => (value === "" || value === null || value === undefined ? undefined : value), + z.coerce.number().int().min(0).optional(), + ), }); type ToolsetFormValues = z.infer; @@ -148,7 +153,12 @@ function MCPToolList({ serverId, serverName, accessToken, selectedTools, onToggl interface CreateToolsetModalProps { open: boolean; onClose: () => void; - onSave: (name: string, description: string | undefined, tools: MCPToolsetTool[]) => Promise; + onSave: ( + name: string, + description: string | undefined, + toolsTtlMs: number | undefined, + tools: MCPToolsetTool[], + ) => Promise; accessToken: string | null; initialToolset?: MCPToolset; } @@ -158,6 +168,7 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset defaultValues: { toolset_name: initialToolset?.toolset_name || "", description: initialToolset?.description || "", + tools_ttl_ms: initialToolset?.tools_ttl_ms ?? undefined, }, }); const [selectedTools, setSelectedTools] = useState(initialToolset?.tools || []); @@ -174,6 +185,7 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset form.reset({ toolset_name: initialToolset?.toolset_name || "", description: initialToolset?.description || "", + tools_ttl_ms: initialToolset?.tools_ttl_ms ?? undefined, }); setSelectedTools(initialToolset?.tools || []); setServerSearch(""); @@ -192,7 +204,7 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset const handleSubmit = async (values: ToolsetFormValues) => { setSaving(true); try { - await onSave(values.toolset_name, values.description, selectedTools); + await onSave(values.toolset_name, values.description, values.tools_ttl_ms, selectedTools); onClose(); } finally { setSaving(false); @@ -218,6 +230,30 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset {(field) => } + + Tools list TTL (ms) + + + + + } + className="w-48" + > + {(field) => ( + + )} + @@ -386,16 +422,39 @@ export function MCPToolsetsTab({ accessToken, userRole }: MCPToolsetsTabProps) { const isAdmin = userRole === "Admin" || userRole === "proxy_admin"; - const handleCreate = async (name: string, description: string | undefined, tools: MCPToolsetTool[]) => { + const handleCreate = async ( + name: string, + description: string | undefined, + toolsTtlMs: number | undefined, + tools: MCPToolsetTool[], + ) => { if (!accessToken) return; - await createMCPToolset(accessToken, { toolset_name: name, description, tools }); + const toolsetInput = { + toolset_name: name, + description, + tools, + ...(toolsTtlMs !== undefined ? { tools_ttl_ms: toolsTtlMs } : {}), + }; + await createMCPToolset(accessToken, toolsetInput); toast.success("Toolset created"); queryClient.invalidateQueries({ queryKey: ["mcpToolsets"] }); }; - const handleUpdate = async (name: string, description: string | undefined, tools: MCPToolsetTool[]) => { + const handleUpdate = async ( + name: string, + description: string | undefined, + toolsTtlMs: number | undefined, + tools: MCPToolsetTool[], + ) => { if (!accessToken || !editToolset) return; - await updateMCPToolset(accessToken, { toolset_id: editToolset.toolset_id, toolset_name: name, description, tools }); + const toolsetUpdate = { + toolset_id: editToolset.toolset_id, + toolset_name: name, + description, + tools, + ...((toolsTtlMs ?? null) !== (editToolset.tools_ttl_ms ?? null) ? { tools_ttl_ms: toolsTtlMs ?? null } : {}), + }; + await updateMCPToolset(accessToken, toolsetUpdate); toast.success("Toolset updated"); queryClient.invalidateQueries({ queryKey: ["mcpToolsets"] }); setEditToolset(null); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts index 3ae846b0308..c0fcf92f0d4 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts @@ -125,6 +125,17 @@ describe("buildCreateServerPayload transport and naming", () => { expect(payload.transport).toBe("http"); }); + it("includes a configured OpenAPI tools list TTL, including zero", () => { + const payload = payloadOf( + build({ + transport: "openapi", + spec_path: "https://api.example.com/openapi.json", + tools_ttl_ms: 0, + }), + ); + expect(payload.tools_ttl_ms).toBe(0); + }); + it("leaves http and sse transports untouched", () => { expect(payloadOf(build({ transport: "sse" })).transport).toBe("sse"); }); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts index ee5cce2d0d2..3298d6507f5 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts @@ -333,6 +333,28 @@ const EDIT_FORM_VALUES: EditServerFormValues = { }; describe("buildEditServerPayload wire contract", () => { + it("omits an unchanged OpenAPI tools list TTL", () => { + const ui: EditServerUiState = { + ...baseUi, + mcpServer: { ...baseUi.mcpServer, spec_path: "https://example.com/openapi.json", tools_ttl_ms: 2000 }, + }; + const result = buildEditServerPayload({ ...EDIT_FORM_VALUES, tools_ttl_ms: 2000 }, ui); + + expect(result).toMatchObject({ kind: "ok" }); + if (result.kind !== "ok") throw new Error("Expected valid MCP server payload"); + expect(result.payload).not.toHaveProperty("tools_ttl_ms"); + }); + + it("clears an OpenAPI tools list TTL with an explicit null", () => { + const ui: EditServerUiState = { + ...baseUi, + mcpServer: { ...baseUi.mcpServer, spec_path: "https://example.com/openapi.json", tools_ttl_ms: 2000 }, + }; + const result = buildEditServerPayload({ ...EDIT_FORM_VALUES, tools_ttl_ms: null }, ui); + + expect(result).toMatchObject({ kind: "ok", payload: { tools_ttl_ms: null } }); + }); + it("carries an edited alias and the server identifier onto the wire", () => { const result = buildEditServerPayload({ ...EDIT_FORM_VALUES, alias: "renamed" }, baseUi); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts index 081063854c0..7ac22aba16e 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts @@ -42,6 +42,7 @@ export interface EditServerFormValues { readonly extra_headers?: readonly string[]; readonly disallowed_tools?: readonly string[]; readonly oauth_flow_type?: string; + readonly tools_ttl_ms?: number | string | null; readonly [key: string]: unknown; } @@ -296,6 +297,7 @@ export const buildEditServerPayload = (values: EditServerFormValues, ui: EditSer oauth_passthrough: oauthPassthroughRaw, dcr_bridge: dcrBridgeRaw, token_validation_json: rawTokenValidationJson, + tools_ttl_ms: rawToolsTtlMs, ...rawRestValues } = values; @@ -318,6 +320,10 @@ export const buildEditServerPayload = (values: EditServerFormValues, ui: EditSer // position, which the payload's serialised key order depends on. const restValues = rawRestValues.transport === TRANSPORT.OPENAPI ? { ...rawRestValues, transport: "http" } : rawRestValues; + const toolsTtlPayload = + mcpServer.spec_path && rawToolsTtlMs !== mcpServer.tools_ttl_ms + ? { tools_ttl_ms: rawToolsTtlMs == null || rawToolsTtlMs === "" ? null : Number(rawToolsTtlMs) } + : {}; const tokenValidation = ((): TokenValidationResult => { if (!rawTokenValidationJson || rawTokenValidationJson.trim() === "") return { kind: "ok", value: null }; @@ -365,6 +371,7 @@ export const buildEditServerPayload = (values: EditServerFormValues, ui: EditSer const payload: EditServerPayload = { ...restValues, + ...toolsTtlPayload, ...stdio.fields, // Remove UI-only fields stdio_config: undefined, diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx index 35e212faf37..d9decf12d9f 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx @@ -179,6 +179,26 @@ describe("MCPServerEdit (stdio)", () => { ); expect(screen.getByRole("tab", { name: "Server Configuration" })).toBeInTheDocument(); + expect(screen.queryByLabelText("Tools list TTL (ms)")).not.toBeInTheDocument(); + }); + + it("shows tools list TTL for an OpenAPI server", () => { + render( + , + ); + + expect(screen.getByLabelText("Tools list TTL (ms)")).toBeInTheDocument(); }); it("should allow updating stdio transport configuration", async () => { diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx index f35e3ab3d3a..9d755d274db 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx @@ -994,6 +994,30 @@ const MCPServerEdit: React.FC = ({ )} + {isOpenAPITransport && ( + + Tools list TTL (ms) + + + + + } + name="tools_ttl_ms" + > + {(control) => ( + + )} + + )} + {/* Authentication - for HTTP, SSE, and OpenAPI */} {!isStdioTransport && ( <> diff --git a/ui/litellm-dashboard/src/components/mcp_tools/types.tsx b/ui/litellm-dashboard/src/components/mcp_tools/types.tsx index 22fd64f10d8..7dbfbe42917 100644 --- a/ui/litellm-dashboard/src/components/mcp_tools/types.tsx +++ b/ui/litellm-dashboard/src/components/mcp_tools/types.tsx @@ -434,6 +434,7 @@ export interface MCPServer { */ url?: string | null; spec_path?: string | null; + tools_ttl_ms?: number | null; transport?: string | null; auth_type?: string | null; oauth2_flow?: string | null; @@ -548,6 +549,7 @@ export interface MCPToolset { toolset_id: string; toolset_name: string; description?: string; + tools_ttl_ms?: number | null; tools: MCPToolsetTool[]; created_at?: string; created_by?: string; diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts index e432c947116..48a1d3b4e8d 100644 --- a/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -34625,6 +34625,8 @@ export interface components { tool_name_to_display_name?: { [key: string]: string; } | null; + /** Tools Ttl Ms */ + tools_ttl_ms?: number | null; /** * Transport * @enum {string} @@ -38762,6 +38764,8 @@ export interface components { tool_name_to_display_name?: { [key: string]: string; } | null; + /** Tools Ttl Ms */ + tools_ttl_ms?: number | null; /** * Transport * @default sse @@ -38780,6 +38784,8 @@ export interface components { * @default [] */ tools: components["schemas"]["MCPToolsetTool"][]; + /** Tools Ttl Ms */ + tools_ttl_ms?: number | null; /** Toolset Name */ toolset_name: string; }; @@ -48261,6 +48267,8 @@ export interface components { tool_name_to_display_name?: { [key: string]: string; } | null; + /** Tools Ttl Ms */ + tools_ttl_ms?: number | null; /** * Transport * @default sse @@ -48276,6 +48284,8 @@ export interface components { description?: string | null; /** Tools */ tools?: components["schemas"]["MCPToolsetTool"][] | null; + /** Tools Ttl Ms */ + tools_ttl_ms?: number | null; /** Toolset Id */ toolset_id: string; /** Toolset Name */