Skip to content

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

Studio: fit MCP image mappings in the dialog and keep one field per tool (#13162)

Etherla0a8f2ec575e
diff --git a/studio/backend/models/mcp_servers.py b/studio/backend/models/mcp_servers.py
index 17d457f8350..2b61c7908c9 100644
--- a/studio/backend/models/mcp_servers.py
+++ b/studio/backend/models/mcp_servers.py
@@ -1,9 +1,9 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-from typing import Literal, Optional
+from typing import Annotated, Literal, Optional
-from pydantic import BaseModel, Field, StrictStr
+from pydantic import AfterValidator, BaseModel, Field, StrictStr
class McpImageInputMapping(BaseModel):
@@ -14,6 +14,17 @@ class McpImageInputMapping(BaseModel):
encoding: Literal["base64", "data_url"] = "base64"
+def _one_field_per_tool(mappings: list[McpImageInputMapping]) -> list[McpImageInputMapping]:
+ # image_mapping sends the image to one field per tool; a second one could only be a fallback the UI never offered.
+ tools = [mapping.tool for mapping in mappings]
+ if len(tools) != len(set(tools)):
+ raise ValueError("each tool can map only one image field")
+ return mappings
+
+
+McpImageInputMappings = Annotated[list[McpImageInputMapping], AfterValidator(_one_field_per_tool)]
+
+
class McpServerCreate(BaseModel):
display_name: str
url: str
@@ -22,7 +33,7 @@ class McpServerCreate(BaseModel):
use_oauth: bool = False
oauth_client_id: Optional[str] = None
oauth_client_secret: Optional[str] = None
- image_input_mappings: list[McpImageInputMapping] = Field(default_factory = list, max_length = 64)
+ image_input_mappings: McpImageInputMappings = Field(default_factory = list, max_length = 64)
class McpServerUpdate(BaseModel):
@@ -34,7 +45,7 @@ class McpServerUpdate(BaseModel):
use_oauth: Optional[bool] = None
oauth_client_id: Optional[str] = None
oauth_client_secret: Optional[str] = None
- image_input_mappings: Optional[list[McpImageInputMapping]] = Field(None, max_length = 64)
+ image_input_mappings: Optional[McpImageInputMappings] = Field(None, max_length = 64)
class McpServerResponse(BaseModel):
diff --git a/studio/backend/tests/test_mcp_image.py b/studio/backend/tests/test_mcp_image.py
index d8bcbe38ee1..7418f616146 100644
--- a/studio/backend/tests/test_mcp_image.py
+++ b/studio/backend/tests/test_mcp_image.py
@@ -653,6 +653,21 @@ def test_mappings_round_trip_through_the_routes(mapped_server):
assert cleared.image_input_mappings == []
+def test_a_tool_maps_one_image_field():
+ from pydantic import ValidationError
+
+ from models.mcp_servers import McpServerCreate, McpServerUpdate
+
+ two_fields = [{"tool": "lookup", "field": "image"}, {"tool": "lookup", "field": "url"}]
+ with pytest.raises(ValidationError, match = "only one image field"):
+ McpServerCreate(display_name = "x", url = "https://x", image_input_mappings = two_fields)
+ with pytest.raises(ValidationError, match = "only one image field"):
+ McpServerUpdate(image_input_mappings = two_fields)
+ two_tools = [{"tool": "lookup", "field": "image"}, {"tool": "search", "field": "image"}]
+ assert len(McpServerUpdate(image_input_mappings = two_tools).image_input_mappings) == 2
+ assert McpServerUpdate().image_input_mappings is None
+
+
def test_every_local_exit_without_a_tool_loop_refuses_the_image():
import ast
import inspect
diff --git a/studio/frontend/src/features/chat/api/mcp-image.ts b/studio/frontend/src/features/chat/api/mcp-image.ts
index 860923b6c81..c556698f4d3 100644
--- a/studio/frontend/src/features/chat/api/mcp-image.ts
+++ b/studio/frontend/src/features/chat/api/mcp-image.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-import type { McpServerConfig } from "./mcp-servers-api";
+import type { McpImageInputMapping, McpServerConfig } from "./mcp-servers-api";
/** Sent with a tool_start that would send the user's image; approval covers this one call. */
export type ImageDisclosure = {
@@ -76,3 +76,46 @@ export function imageFieldCandidates(schema: unknown): string[] {
)
.map(([name]) => name);
}
+
+type ImageField = { tool: string; field: string };
+
+/** The tool / field pairs not mapped yet, so picking one always changes something. */
+export function unmappedImageFields<T extends ImageField>(
+ options: readonly T[],
+ mappings: readonly McpImageInputMapping[],
+): T[] {
+ return options.filter(
+ (option) =>
+ !mappings.some((m) => m.tool === option.tool && m.field === option.field),
+ );
+}
+
+/** Maps `option`; the backend takes one field per tool, so it replaces that tool's row in place. */
+export function withImageField(
+ mappings: readonly McpImageInputMapping[],
+ option: ImageField,
+ encoding: McpImageInputMapping["encoding"] = "base64",
+): McpImageInputMapping[] {
+ const next: McpImageInputMapping = {
+ tool: option.tool,
+ field: option.field,
+ encoding,
+ };
+ const index = mappings.findIndex((m) => m.tool === option.tool);
+ if (index < 0) return [...mappings, next];
+ // A server saved through the API can hold two rows for one tool; keep only the replacement.
+ return mappings.flatMap((m, i) =>
+ i === index ? [next] : m.tool === option.tool ? [] : [m],
+ );
+}
+
+/** The mappings an edit should send, or undefined when they are unchanged and the update can leave them alone. */
+export function changedImageMappings(
+ saved: readonly McpImageInputMapping[],
+ current: McpImageInputMapping[],
+): McpImageInputMapping[] | undefined {
+ // A legacy server can hold two rows per tool, which the backend now rejects: skip unchanged lists, else keep each tool's first row.
+ if (JSON.stringify(saved) === JSON.stringify(current)) return undefined;
+ const tools = new Set<string>();
+ return current.filter((m) => !tools.has(m.tool) && tools.add(m.tool));
+}
diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
index 0e8792dde79..0371d9451b3 100644
--- a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -39,6 +39,7 @@ import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Spinner } from "@/components/ui/spinner";
import { Switch } from "@/components/ui/switch";
+import { changedImageMappings } from "./api/mcp-image";
import { subscribeToMcpServerMutationSettlements } from "./api/mcp-server-mutation-tracker";
import {
type McpImageInputMapping,
@@ -747,7 +748,10 @@ export function ChatMcpServersDialog({
url,
headers: headers ?? null,
...oauthPayload(form, stdio),
- imageInputMappings: form.imageInputMappings,
+ imageInputMappings: changedImageMappings(
+ servers.find((s) => s.id === view.id)?.image_input_mappings ?? [],
+ form.imageInputMappings,
+ ),
});
if (formGenerationRef.current !== generation) return;
toast.success("MCP server updated");
diff --git a/studio/frontend/src/features/chat/mcp-image-mappings.tsx b/studio/frontend/src/features/chat/mcp-image-mappings.tsx
index 461284db7b9..b95dbda7236 100644
--- a/studio/frontend/src/features/chat/mcp-image-mappings.tsx
+++ b/studio/frontend/src/features/chat/mcp-image-mappings.tsx
@@ -15,7 +15,11 @@ import {
import { Spinner } from "@/components/ui/spinner";
import { Switch } from "@/components/ui/switch";
-import { imageFieldCandidates } from "./api/mcp-image";
+import {
+ imageFieldCandidates,
+ unmappedImageFields,
+ withImageField,
+} from "./api/mcp-image";
import {
type McpImageInputMapping,
listMcpServerTools,
@@ -40,6 +44,7 @@ export function McpImageMappings({
const [enabled, setEnabled] = useState(value.length > 0);
const [options, setOptions] = useState<Option[] | null>(null);
const [loading, setLoading] = useState(false);
+ const addable = options ? unmappedImageFields(options, value) : [];
async function discover(id: string) {
setLoading(true);
@@ -100,10 +105,11 @@ export function McpImageMappings({
<div className="space-y-2">
{value.map((mapping) => (
<div
- key={mapping.tool}
+ key={`${mapping.tool}:${mapping.field}`}
className="flex items-center justify-between gap-3 text-xs"
>
- <span className="min-w-0 flex-1 truncate">
+ {/* Wraps instead of truncating: a nowrap name widens the whole dialog grid to its length. */}
+ <span className="min-w-0 flex-1 [overflow-wrap:anywhere]">
{mapping.tool} / {mapping.field}
</span>
<Select
@@ -111,13 +117,10 @@ export function McpImageMappings({
disabled={disabled}
onValueChange={(next) =>
onChange(
- value.map((m) =>
- m.tool === mapping.tool
- ? {
- ...m,
- encoding: next as McpImageInputMapping["encoding"],
- }
- : m,
+ withImageField(
+ value,
+ mapping,
+ next as McpImageInputMapping["encoding"],
),
)
}
@@ -165,18 +168,14 @@ export function McpImageMappings({
<p className="text-xs text-muted-foreground">
No tool on this server takes a top-level string field.
</p>
- ) : (
+ ) : addable.length > 0 ? (
<div className="flex flex-wrap gap-2">
<Select
value=""
disabled={disabled}
onValueChange={(index) => {
- const option = options[Number(index)];
- if (!option) return;
- onChange([
- ...value.filter((m) => m.tool !== option.tool),
- { ...option, encoding: "base64" },
- ]);
+ const option = addable[Number(index)];
+ if (option) onChange(withImageField(value, option));
}}
>
<SelectTrigger
@@ -186,10 +185,11 @@ export function McpImageMappings({
<SelectValue placeholder="Add tool / field" />
</SelectTrigger>
<SelectContent>
- {options.map((option, index) => (
+ {addable.map((option, index) => (
<SelectItem
key={`${option.tool}:${option.field}`}
value={String(index)}
+ className="[overflow-wrap:anywhere]"
>
{option.tool} / {option.field}
</SelectItem>
@@ -197,7 +197,7 @@ export function McpImageMappings({
</SelectContent>
</Select>
</div>
- )}
+ ) : null}
</div>
) : null}
</div>
diff --git a/studio/frontend/tests/mcp-image.test.ts b/studio/frontend/tests/mcp-image.test.ts
index 1ea557cdecd..15a0e29e0fb 100644
--- a/studio/frontend/tests/mcp-image.test.ts
+++ b/studio/frontend/tests/mcp-image.test.ts
@@ -5,10 +5,13 @@ import assert from "node:assert/strict";
import test from "node:test";
import {
+ changedImageMappings,
imageFieldCandidates,
mcpImageMappingsEnabled,
modelVisibleMessage,
toolOnlyImages,
+ unmappedImageFields,
+ withImageField,
} from "../src/features/chat/api/mcp-image.ts";
const PRIVATE = "data:image/png;base64,UFJJVkFURQ==";
@@ -98,3 +101,95 @@ test("mapping candidates are the top-level string fields", () => {
);
assert.deepEqual(imageFieldCandidates(undefined), []);
});
+
+test("the add list leaves out pairs that are already mapped", () => {
+ const options = [
+ { tool: "search_by_file", field: "filePath" },
+ { tool: "search_by_file", field: "imageBase64" },
+ { tool: "search_by_url", field: "url" },
+ ];
+ assert.deepEqual(
+ unmappedImageFields(options, [
+ { tool: "search_by_file", field: "imageBase64", encoding: "data_url" },
+ ]),
+ [options[0], options[2]],
+ );
+ assert.deepEqual(unmappedImageFields(options, []), options);
+});
+
+test("adding a field keeps one row per tool, in place", () => {
+ const mapped = [
+ { tool: "search_by_file", field: "imageBase64", encoding: "data_url" },
+ { tool: "search_by_url", field: "url", encoding: "base64" },
+ ] as const;
+ assert.deepEqual(
+ withImageField(mapped, { tool: "search_by_file", field: "filePath" }),
+ [
+ { tool: "search_by_file", field: "filePath", encoding: "base64" },
+ mapped[1],
+ ],
+ );
+ assert.deepEqual(withImageField(mapped, { tool: "lookup", field: "image" }), [
+ ...mapped,
+ { tool: "lookup", field: "image", encoding: "base64" },
+ ]);
+});
+
+test("a tool saved with two rows keeps one after picking a field", () => {
+ const saved = [
+ { tool: "search_by_file", field: "imageBase64", encoding: "data_url" },
+ { tool: "search_by_url", field: "url", encoding: "base64" },
+ { tool: "search_by_file", field: "filePath", encoding: "base64" },
+ ] as const;
+ assert.deepEqual(
+ withImageField(saved, { tool: "search_by_file", field: "file" }),
+ [{ tool: "search_by_file", field: "file", encoding: "base64" }, saved[1]],
+ );
+});
+
+test("changing a row's encoding keeps that field and its tool's other rows go", () => {
+ const saved = [
+ { tool: "search_by_file", field: "imageBase64", encoding: "base64" },
+ { tool: "search_by_file", field: "filePath", encoding: "base64" },
+ ] as const;
+ assert.deepEqual(withImageField(saved, saved[1], "data_url"), [
+ { tool: "search_by_file", field: "filePath", encoding: "data_url" },
+ ]);
+});
+
+test("an edit leaves unchanged mappings out of the update", () => {
+ const saved = [
+ { tool: "search_by_file", field: "imageBase64", encoding: "base64" },
+ { tool: "search_by_file", field: "filePath", encoding: "base64" },
+ ] as const;
+ assert.equal(changedImageMappings(saved, [...saved]), undefined);
+ const edited = [{ ...saved[0], encoding: "data_url" as const }];
+ assert.deepEqual(changedImageMappings(saved, edited), edited);
+ assert.deepEqual(changedImageMappings([], []), undefined);
+});
+
+test("any mapping edit on a legacy server sends one row per tool", () => {
+ const saved = [
+ { tool: "search_by_file", field: "imageBase64", encoding: "data_url" },
+ { tool: "search_by_file", field: "filePath", encoding: "base64" },
+ { tool: "search_by_url", field: "url", encoding: "base64" },
+ ] as const;
+ assert.deepEqual(
+ changedImageMappings(
+ saved,
+ withImageField(saved, { tool: "lookup", field: "image" }),
+ ),
+ [
+ saved[0],
+ saved[2],
+ { tool: "lookup", field: "image", encoding: "base64" },
+ ],
+ );
+ assert.deepEqual(
+ changedImageMappings(
+ saved,
+ saved.filter((m) => m.tool !== "search_by_url"),
+ ),
+ [saved[0]],
+ );
+});