π OpenHands: AI-Driven Development
fix(frontend): read SDK 1.31.x flat mcp_config wire format (#15165)
Tim O'Farrell2dc45f5e0d19
diff --git a/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsxindex eb835c7447..2d1050c573 100644--- a/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx+++ b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx@@ -25,6 +25,11 @@ describe("MCP Server Mutation Hooks", () => {);};+ // SDK 1.31.x dropped the ``mcpServers`` wrapper from ``model_dump``, so the+ // settings endpoint now returns a flat server map. ``parseMcpConfig`` still+ // accepts the legacy wrapped shape, and ``toSdkMcpConfig`` now emits the+ // flat shape. Tests below cover both directions.+describe("useAddMcpServer", () => {it("fetches fresh settings at mutation time", async () => {const getSettingsSpy = vi@@ -32,9 +37,7 @@ describe("MCP Server Mutation Hooks", () => {.mockResolvedValue({agent_settings: {mcp_config: {- mcpServers: {- existing: { url: "https://existing.com", transport: "sse" },- },+ existing: { url: "https://existing.com", transport: "sse" },},},} as any);@@ -59,12 +62,54 @@ describe("MCP Server Mutation Hooks", () => {expect(getSettingsSpy).toHaveBeenCalledTimes(1);expect(saveSettingsSpy).toHaveBeenCalledWith({agent_settings_diff: {+ mcp_config: expect.objectContaining({+ existing: expect.objectContaining({ url: "https://existing.com" }),+ }),+ },+ });+ // Should not wrap in the legacy ``mcpServers`` envelope.+ const savedConfig = (+ saveSettingsSpy.mock.calls[0][0] as {+ agent_settings_diff: { mcp_config: Record<string, unknown> };+ }+ ).agent_settings_diff.mcp_config;+ expect(savedConfig).not.toHaveProperty("mcpServers");+ });++ it("also accepts the legacy wrapped shape on read", async () => {+ // Backwards-compat: a server persisted before the SDK 1.31.x bump may+ // still come back as ``{ mcpServers: {...} }`` if the value has not yet+ // been rewritten by the backend. The frontend must still parse it.+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({+ agent_settings: {mcp_config: {- mcpServers: expect.objectContaining({- existing: expect.objectContaining({ url: "https://existing.com" }),- }),+ mcpServers: {+ existing: { url: "https://existing.com", transport: "sse" },+ },},},+ } as any);++ const saveSettingsSpy = vi+ .spyOn(SettingsService, "saveSettings")+ .mockResolvedValue(true);++ const { result } = renderHook(() => useAddMcpServer(), {+ wrapper: createWrapper(),+ });++ result.current.mutate({ type: "sse", url: "https://new-server.com" });++ await waitFor(() => {+ expect(result.current.isSuccess).toBe(true);+ });++ expect(saveSettingsSpy).toHaveBeenCalledWith({+ agent_settings_diff: {+ mcp_config: expect.objectContaining({+ existing: expect.objectContaining({ url: "https://existing.com" }),+ }),+ },});});@@ -93,11 +138,9 @@ describe("MCP Server Mutation Hooks", () => {expect(saveSettingsSpy).toHaveBeenCalledWith({agent_settings_diff: {mcp_config: {- mcpServers: {- sse: {- url: "https://first-server.com",- transport: "sse",- },+ sse: {+ url: "https://first-server.com",+ transport: "sse",},},},@@ -128,11 +171,9 @@ describe("MCP Server Mutation Hooks", () => {expect(saveSettingsSpy).toHaveBeenCalledWith({agent_settings_diff: {mcp_config: {- mcpServers: {- sse: {- url: "https://server.com",- transport: "sse",- },+ sse: {+ url: "https://server.com",+ transport: "sse",},},},@@ -145,11 +186,9 @@ describe("MCP Server Mutation Hooks", () => {vi.spyOn(SettingsService, "getSettings").mockResolvedValue({agent_settings: {mcp_config: {- mcpServers: {- server1: { url: "https://server1.com", transport: "sse" },- server2: { url: "https://server2.com", transport: "sse" },- server3: { url: "https://server3.com", transport: "sse" },- },+ server1: { url: "https://server1.com", transport: "sse" },+ server2: { url: "https://server2.com", transport: "sse" },+ server3: { url: "https://server3.com", transport: "sse" },},},} as any);@@ -171,11 +210,11 @@ describe("MCP Server Mutation Hooks", () => {const savedPayload = saveSettingsSpy.mock.calls[0][0] as {agent_settings_diff: {- mcp_config: { mcpServers: Record<string, unknown> } | null;+ mcp_config: Record<string, unknown> | null;};};const savedConfig = savedPayload.agent_settings_diff.mcp_config;- const serverNames = Object.keys(savedConfig?.mcpServers ?? {});+ const serverNames = Object.keys(savedConfig ?? {});expect(serverNames).toHaveLength(2);});@@ -209,9 +248,7 @@ describe("MCP Server Mutation Hooks", () => {vi.spyOn(SettingsService, "getSettings").mockResolvedValue({agent_settings: {mcp_config: {- mcpServers: {- myserver: { url: "https://old-url.com", transport: "sse" },- },+ myserver: { url: "https://old-url.com", transport: "sse" },},},} as any);@@ -239,13 +276,11 @@ describe("MCP Server Mutation Hooks", () => {const savedPayload = saveSettingsSpy.mock.calls[0][0] as {agent_settings_diff: {- mcp_config: { mcpServers: Record<string, { url: string }> };+ mcp_config: Record<string, { url: string }>;};};const savedConfig = savedPayload.agent_settings_diff.mcp_config;- const serverUrls = Object.values(savedConfig.mcpServers).map(- (s) => s.url,- );+ const serverUrls = Object.values(savedConfig).map((s) => s.url);expect(serverUrls).toContain("https://new-url.com");});});diff --git a/frontend/__tests__/utils/mcp-config-format.test.ts b/frontend/__tests__/utils/mcp-config-format.test.tsnew file mode 100644index 0000000000..60d73abd0c--- /dev/null+++ b/frontend/__tests__/utils/mcp-config-format.test.ts@@ -0,0 +1,105 @@+import { describe, it, expect } from "vitest";+import { parseMcpConfig, toSdkMcpConfig } from "#/utils/mcp-config";+import { MCPConfig } from "#/types/settings";++// SDK 1.31.x dropped the ``mcpServers`` wrapper from ``model_dump``, so+// ``GET /api/v1/settings`` now returns a flat server map directly. These tests+// cover both the new wire format (flat) and the legacy wrapped shape, on both+// the parse and serialize paths.++describe("parseMcpConfig β SDK 1.31.x flat wire format", () => {+ it("parses an shttp server from the flat shape", () => {+ const input = {+ shttp: { url: "https://mcp.deepwiki.com/mcp", timeout: 60 },+ };++ const result = parseMcpConfig(input);++ expect(result).toEqual({+ sse_servers: [],+ stdio_servers: [],+ shttp_servers: [+ { name: "shttp", url: "https://mcp.deepwiki.com/mcp", timeout: 60 },+ ],+ });+ });++ it("parses mixed server types from the flat shape", () => {+ const input = {+ "sse-server": { url: "https://sse.example", transport: "sse" },+ "http-server": { url: "https://http.example", transport: "http" },+ "stdio-server": { command: "/usr/bin/cmd" },+ };++ const result = parseMcpConfig(input);++ expect(result.sse_servers).toHaveLength(1);+ expect(result.shttp_servers).toHaveLength(1);+ expect(result.stdio_servers).toHaveLength(1);+ });++ it("treats mcpServers: null as the flat shape (empty server map)", () => {+ // Defensive: a null ``mcpServers`` key on the new flat input shouldn't be+ // confused with the legacy wrapper β it's just a stray key on the flat map.+ const input = { mcpServers: null, real: { url: "https://x", transport: "sse" } };++ const result = parseMcpConfig(input);++ expect(result.sse_servers).toHaveLength(1);+ expect(result.sse_servers[0]).toMatchObject({ name: "real" });+ });+});++describe("parseMcpConfig β legacy wrapped shape still works", () => {+ it("parses an shttp server from the wrapped shape", () => {+ const input = {+ mcpServers: {+ shttp: { url: "https://mcp.deepwiki.com/mcp", timeout: 60 },+ },+ };++ const result = parseMcpConfig(input);++ expect(result.shttp_servers).toHaveLength(1);+ expect(result.shttp_servers[0]).toEqual({+ name: "shttp",+ url: "https://mcp.deepwiki.com/mcp",+ timeout: 60,+ });+ });+});++describe("toSdkMcpConfig β emits flat server map", () => {+ it("returns a flat server map without the mcpServers wrapper", () => {+ const config: MCPConfig = {+ sse_servers: [{ name: "my-custom-name", url: "https://example.com" }],+ stdio_servers: [],+ shttp_servers: [],+ };++ const result = toSdkMcpConfig(config);++ expect(result).not.toHaveProperty("mcpServers");+ expect(result).toEqual({+ "my-custom-name": {+ url: "https://example.com",+ transport: "sse",+ },+ });+ });++ it("round-trips through parseMcpConfig unchanged", () => {+ const config: MCPConfig = {+ sse_servers: [{ name: "sse", url: "https://a.example" }],+ stdio_servers: [{ name: "stdio", command: "/bin/x" }],+ shttp_servers: [+ { name: "shttp", url: "https://b.example", timeout: 90 },+ ],+ };++ const serialized = toSdkMcpConfig(config);+ const reparsed = parseMcpConfig(serialized);++ expect(reparsed).toEqual(config);+ });+});diff --git a/frontend/__tests__/utils/mcp-config.test.ts b/frontend/__tests__/utils/mcp-config.test.tsindex 73fdf51fdb..5e604c2029 100644--- a/frontend/__tests__/utils/mcp-config.test.ts+++ b/frontend/__tests__/utils/mcp-config.test.ts@@ -174,11 +174,9 @@ describe("toSdkMcpConfig", () => {const result = toSdkMcpConfig(config);expect(result).toEqual({- mcpServers: {- "my-custom-name": {- url: "https://example.com",- transport: "sse",- },+ "my-custom-name": {+ url: "https://example.com",+ transport: "sse",},});});@@ -193,11 +191,9 @@ describe("toSdkMcpConfig", () => {const result = toSdkMcpConfig(config);expect(result).toEqual({- mcpServers: {- sse: {- url: "https://example.com",- transport: "sse",- },+ sse: {+ url: "https://example.com",+ transport: "sse",},});});@@ -215,12 +211,12 @@ describe("toSdkMcpConfig", () => {const result = toSdkMcpConfig(config);- expect(result?.mcpServers).toHaveProperty("sse");- expect(result?.mcpServers).toHaveProperty("sse_1");- expect(result?.mcpServers).toHaveProperty("sse_2");- expect(result?.mcpServers["sse"].url).toBe("https://example1.com");- expect(result?.mcpServers["sse_1"].url).toBe("https://example2.com");- expect(result?.mcpServers["sse_2"].url).toBe("https://example3.com");+ expect(result).toHaveProperty("sse");+ expect(result).toHaveProperty("sse_1");+ expect(result).toHaveProperty("sse_2");+ expect(result?.["sse"].url).toBe("https://example1.com");+ expect(result?.["sse_1"].url).toBe("https://example2.com");+ expect(result?.["sse_2"].url).toBe("https://example3.com");});it("should serialize api_key as an Authorization bearer header", () => {@@ -238,12 +234,12 @@ describe("toSdkMcpConfig", () => {const result = toSdkMcpConfig(config);- expect(result?.mcpServers["secure"]).toEqual({+ expect(result?.["secure"]).toEqual({url: "https://example.com",transport: "sse",headers: { Authorization: "Bearer my-secret" },});- expect(result?.mcpServers["shttp"]).toEqual({+ expect(result?.["shttp"]).toEqual({url: "https://shttp.example",headers: { Authorization: "Bearer shttp-secret" },});@@ -280,12 +276,10 @@ describe("toSdkMcpConfig", () => {const written = toSdkMcpConfig(parseMcpConfig(persisted));expect(written).toEqual({- mcpServers: {- sse: {- url: "https://example.com",- transport: "sse",- headers: { Authorization: "Bearer legacy-secret" },- },+ sse: {+ url: "https://example.com",+ transport: "sse",+ headers: { Authorization: "Bearer legacy-secret" },},});});@@ -301,7 +295,7 @@ describe("toSdkMcpConfig", () => {const result = toSdkMcpConfig(config);- expect(result?.mcpServers["timeout"]).toEqual({+ expect(result?.["timeout"]).toEqual({url: "https://example.com",timeout: 60,});@@ -323,7 +317,7 @@ describe("toSdkMcpConfig", () => {const result = toSdkMcpConfig(config);- expect(result?.mcpServers["my-stdio"]).toEqual({+ expect(result?.["my-stdio"]).toEqual({command: "/usr/bin/server",args: ["--flag"],env: { KEY: "value" },@@ -352,9 +346,9 @@ describe("round-trip preservation", () => {const parsed = parseMcpConfig(original);const serialized = toSdkMcpConfig(parsed);- expect(serialized?.mcpServers).toHaveProperty("custom-sse-name");- expect(serialized?.mcpServers).toHaveProperty("custom-http-name");- expect(serialized?.mcpServers).toHaveProperty("custom-stdio-name");+ expect(serialized).toHaveProperty("custom-sse-name");+ expect(serialized).toHaveProperty("custom-http-name");+ expect(serialized).toHaveProperty("custom-stdio-name");});it("should not generate new names if original names are preserved", () => {@@ -369,10 +363,10 @@ describe("round-trip preservation", () => {const serialized = toSdkMcpConfig(parsed);// Should use original names, not "sse" or "sse_1"- expect(serialized?.mcpServers).toHaveProperty("server1");- expect(serialized?.mcpServers).toHaveProperty("server2");- expect(serialized?.mcpServers).not.toHaveProperty("sse");- expect(serialized?.mcpServers).not.toHaveProperty("sse_1");+ expect(serialized).toHaveProperty("server1");+ expect(serialized).toHaveProperty("server2");+ expect(serialized).not.toHaveProperty("sse");+ expect(serialized).not.toHaveProperty("sse_1");});});@@ -469,9 +463,9 @@ describe("edge cases", () => {const parsed = parseMcpConfig(input);const serialized = toSdkMcpConfig(parsed);- expect(serialized?.mcpServers).toHaveProperty("server/with/slashes");- expect(serialized?.mcpServers).toHaveProperty("server:with:colons");- expect(serialized?.mcpServers).toHaveProperty("server with spaces");+ expect(serialized).toHaveProperty("server/with/slashes");+ expect(serialized).toHaveProperty("server:with:colons");+ expect(serialized).toHaveProperty("server with spaces");});it("should handle cross-type name collisions", () => {@@ -483,7 +477,7 @@ describe("edge cases", () => {const result = toSdkMcpConfig(config);- const names = Object.keys(result?.mcpServers || {});+ const names = Object.keys(result || {});expect(names).toContain("myserver");expect(names).toContain("myserver_1");expect(names).toHaveLength(2);diff --git a/frontend/src/utils/mcp-config.ts b/frontend/src/utils/mcp-config.tsindex e50cbfc569..1d53afdd0e 100644--- a/frontend/src/utils/mcp-config.ts+++ b/frontend/src/utils/mcp-config.ts@@ -13,7 +13,50 @@ const EMPTY_MCP_CONFIG: MCPConfig = {};type SdkMcpServerConfig = Record<string, SettingsValue>;-type SdkMcpConfig = { mcpServers: Record<string, SdkMcpServerConfig> };++/**+ * Normalize the SDK wire payload to a flat server map.+ *+ * SDK 1.31.x dropped the ``mcpServers`` wrapper from ``model_dump``, so the+ * ``GET /api/v1/settings`` response now returns a flat dict keyed by server+ * name (e.g. ``{shttp: {...}}``) instead of ``{mcpServers: {shttp: {...}}}``.+ * Older persisted settings, and clients that still send the wrapper, are+ * accepted by the SDK's ``_normalize_mcp_config_field``, so we mirror its+ * unwrap-or-pass-through logic here for both directions.+ */+function unwrapMcpServers(+ value: Record<string, unknown>,+): Record<string, unknown> {+ if (+ "mcpServers" in value &&+ value.mcpServers &&+ typeof value.mcpServers === "object"+ ) {+ return value.mcpServers as Record<string, unknown>;+ }+ return value;+}++/**+ * Returns true if ``value`` already matches the frontend's parsed ``MCPConfig``+ * shape (the grouped ``{ sse_servers, stdio_servers, shttp_servers }`` form+ * used internally by the UI and as the placeholder on ``DEFAULT_AGENT_SETTINGS``).+ *+ * The check requires **exactly** the three grouping keys as arrays; a strict+ * 3-key shape avoids misidentifying SDK-format payloads that happen to also+ * carry an empty ``sse_servers``/``stdio_servers``/``shttp_servers`` array+ * (e.g. a defensive frontend caller returning ``EMPTY_MCP_CONFIG`` alongside+ * an SDK-format flat map).+ */+function isParsedMcpConfigShape(value: Record<string, unknown>): boolean {+ const keys = Object.keys(value);+ return (+ keys.length === 3 &&+ Array.isArray(value.sse_servers) &&+ Array.isArray(value.stdio_servers) &&+ Array.isArray(value.shttp_servers)+ );+}function apiKeyFromAuthorizationHeader(value: unknown): string | undefined {if (Array.isArray(value)) {@@ -78,9 +121,13 @@ function getUniqueName(base: string, usedNames: Set<string>): string {}/**- * Parse an SDK mcp_config value ({ mcpServers: { ... } }) and convert it- * to the frontend MCPConfig format used by UI components.- * Preserves server names for round-trip serialization.+ * Parse an SDK mcp_config value and convert it to the frontend MCPConfig+ * format used by UI components.+ *+ * Accepts both the SDK 1.31.x flat server map ({ shttp: {...} }) and the+ * legacy wrapped shape ({ mcpServers: { shttp: {...} } }) so previously+ * persisted settings keep loading. Preserves server names for round-trip+ * serialization.*/export function parseMcpConfig(value: unknown): MCPConfig {if (!value || typeof value !== "object") {@@ -89,24 +136,34 @@ export function parseMcpConfig(value: unknown): MCPConfig {const obj = value as Record<string, unknown>;- if (- !("mcpServers" in obj) ||- !obj.mcpServers ||- typeof obj.mcpServers !== "object"- ) {- return { ...EMPTY_MCP_CONFIG };+ // Pass-through for the frontend's already-parsed grouped shape (used by+ // ``DEFAULT_AGENT_SETTINGS`` and any internal caller that hands us an+ // ``MCPConfig`` value). Detected by the three array-typed grouping keys.+ if (isParsedMcpConfigShape(obj)) {+ return {+ sse_servers: obj.sse_servers as (string | MCPSSEServer)[],+ stdio_servers: obj.stdio_servers as MCPStdioServer[],+ shttp_servers: obj.shttp_servers as (string | MCPSHTTPServer)[],+ };}+ const mcpServers = unwrapMcpServers(obj);+const sseServers: (string | MCPSSEServer)[] = [];const stdioServers: MCPStdioServer[] = [];const shttpServers: (string | MCPSHTTPServer)[] = [];- const mcpServers = obj.mcpServers as Record<string, Record<string, unknown>>;-- for (const [serverName, serverConfig] of Object.entries(mcpServers)) {- // eslint-disable-next-line no-continue- if (!serverConfig || typeof serverConfig !== "object") continue;+ for (const [serverName, rawServerConfig] of Object.entries(mcpServers)) {+ if (+ !rawServerConfig ||+ typeof rawServerConfig !== "object" ||+ Array.isArray(rawServerConfig)+ ) {+ // eslint-disable-next-line no-continue+ continue;+ }+ const serverConfig = rawServerConfig as Record<string, unknown>;const url = serverConfig.url as string | undefined;if (url) {@@ -154,11 +211,18 @@ export function parseMcpConfig(value: unknown): MCPConfig {}/**- * Convert the frontend MCPConfig format back to the SDK { mcpServers: { ... } }- * shape expected by agent_settings.mcp_config on the backend.+ * Convert the frontend MCPConfig format to the flat server map shape the+ * SDK 1.31.x settings model emits via ``model_dump`` (``agent_settings.mcp_config``+ * is now a ``dict[str, MCPServer]``, not a FastMCP ``MCPConfig``). The backend's+ * ``_normalize_mcp_config_field`` still accepts the legacy ``{ mcpServers: ... }``+ * wrapper for back-compat, so either shape round-trips; we emit the SDK-native+ * shape to match the wire format the frontend receives.+ ** Uses preserved names when available, only generates names for new servers.*/-export function toSdkMcpConfig(config: MCPConfig): SdkMcpConfig | null {+export function toSdkMcpConfig(+ config: MCPConfig,+): Record<string, SdkMcpServerConfig> | null {const mcpServers: Record<string, SdkMcpServerConfig> = {};const usedNames = new Set<string>();@@ -212,5 +276,5 @@ export function toSdkMcpConfig(config: MCPConfig): SdkMcpConfig | null {mcpServers[name] = server;}- return Object.keys(mcpServers).length > 0 ? { mcpServers } : null;+ return Object.keys(mcpServers).length > 0 ? mcpServers : null;}