Skip to content

πŸ™Œ OpenHands: AI-Driven Development

test: cover MCP config utilities (#17344)

aivong-openhandsa07364828c8f
diff --git a/__tests__/utils/mcp-config.test.ts b/__tests__/utils/mcp-config.test.ts
index 88c1a69199..7305f97d10 100644
--- a/__tests__/utils/mcp-config.test.ts
+++ b/__tests__/utils/mcp-config.test.ts
@@ -1,464 +1,1237 @@
import { describe, expect, it } from "vitest";
-import type { MCPConfig } from "@openhands/typescript-client";
-import type { MCPServerConfig } from "#/types/mcp-server";
+import type {
+ MCPConfig,
+ MCPServer,
+} from "@openhands/typescript-client";
+
import {
+ allocateMcpSettingsKey,
buildMcpServerPatch,
buildRenameMcpConfigPatch,
+ getMcpServerEnabled,
+ getSdkMcpServerMap,
+ hasRedactedMcpSecretLeaf,
MCP_HEADER_REMOVAL_ERROR,
MCP_RENAME_CREDENTIAL_ERROR,
parseMcpConfig,
REDACTED_MCP_SECRET_VALUE,
+ stringRecord,
toCanonicalMcpServer,
} from "#/utils/mcp-config";
import { flattenMcpConfig } from "#/utils/mcp-installed-servers";
+import type { MCPServerConfig } from "#/types/mcp-server";
-describe("canonical MCP configuration", () => {
- // @spec MCP-003 β€” Settings map keys are stable MCP identities
- it("keeps settings map keys as stable identities across transport grouping", () => {
- const first = parseMcpConfig({
- github: {
- transport: "http",
- url: "https://github.example/mcp",
- },
- filesystem: {
- transport: "stdio",
- command: "npx",
- args: ["-y", "@modelcontextprotocol/server-filesystem"],
- },
+describe("getSdkMcpServerMap", () => {
+ it("returns null for non-record values", () => {
+ expect(getSdkMcpServerMap(null)).toBeNull();
+ expect(getSdkMcpServerMap(undefined)).toBeNull();
+ expect(getSdkMcpServerMap("string")).toBeNull();
+ expect(getSdkMcpServerMap(42)).toBeNull();
+ expect(getSdkMcpServerMap([])).toBeNull();
+ });
+
+ it("unwraps the mcpServers wrapper when it is a plain server map", () => {
+ const wrapped = { mcpServers: { docs: { url: "https://docs.example" } } };
+ expect(getSdkMcpServerMap(wrapped)).toEqual({
+ docs: { url: "https://docs.example" },
+ });
+ });
+
+ it("treats a server-shaped mcpServers value as a flat map, not a wrapper", () => {
+ const urlServer = { mcpServers: { url: "https://meta.example" } };
+ expect(getSdkMcpServerMap(urlServer)).toEqual(urlServer);
+
+ const commandServer = { mcpServers: { command: "npx" } };
+ expect(getSdkMcpServerMap(commandServer)).toEqual(commandServer);
+ });
+
+ it("keeps a server literally named mcpServers instead of discarding it", () => {
+ // Unwrapping a server-shaped `mcpServers` would strip the only name in the
+ // map, leaving `{ url: ... }` whose entries parse to nothing at all.
+ expect(
+ parseMcpConfig({ mcpServers: { url: "https://meta.example" } }),
+ ).toEqual({
+ mcpServers: { transport: "http", url: "https://meta.example" },
+ });
+
+ expect(parseMcpConfig({ mcpServers: { command: "npx" } })).toEqual({
+ mcpServers: { transport: "stdio", command: "npx" },
+ });
+ });
+
+ it("does not unwrap when mcpServers is not a record", () => {
+ const value = { mcpServers: "invalid" };
+ expect(getSdkMcpServerMap(value)).toEqual(value);
+ });
+
+ it("returns the value unchanged when there is no mcpServers key", () => {
+ const flat = { docs: { url: "https://docs.example" } };
+ expect(getSdkMcpServerMap(flat)).toBe(flat);
+ });
+});
+
+describe("stringRecord", () => {
+ it("returns undefined for non-records", () => {
+ expect(stringRecord(null)).toBeUndefined();
+ expect(stringRecord(["a"])).toBeUndefined();
+ expect(stringRecord("x")).toBeUndefined();
+ });
+
+ it("keeps only string-valued entries", () => {
+ expect(stringRecord({ valid: "yes", count: 1, nested: {} })).toEqual({
+ valid: "yes",
+ });
+ });
+
+ it("returns undefined when no entry is a string", () => {
+ expect(stringRecord({ count: 1, flag: true })).toBeUndefined();
+ });
+});
+
+describe("hasRedactedMcpSecretLeaf", () => {
+ it("detects the redaction marker the agent server actually sends", () => {
+ // The literal is the wire contract: the agent server replaces secrets with
+ // exactly this text, so matching it only symbolically would silently stop
+ // recognizing redacted values if the sentinel ever drifted.
+ expect(hasRedactedMcpSecretLeaf("**********")).toBe(true);
+ expect(hasRedactedMcpSecretLeaf(REDACTED_MCP_SECRET_VALUE)).toBe(true);
+ });
+
+ it("returns false for plain scalars", () => {
+ expect(hasRedactedMcpSecretLeaf("plain")).toBe(false);
+ expect(hasRedactedMcpSecretLeaf(123)).toBe(false);
+ expect(hasRedactedMcpSecretLeaf(null)).toBe(false);
+ });
+
+ it("recurses into arrays", () => {
+ expect(
+ hasRedactedMcpSecretLeaf(["plain", { nested: REDACTED_MCP_SECRET_VALUE }]),
+ ).toBe(true);
+ expect(hasRedactedMcpSecretLeaf(["plain", "other"])).toBe(false);
+ });
+
+ it("recurses into records", () => {
+ expect(
+ hasRedactedMcpSecretLeaf({ a: { b: REDACTED_MCP_SECRET_VALUE } }),
+ ).toBe(true);
+ expect(hasRedactedMcpSecretLeaf({ nested: ["plain"] })).toBe(false);
+ });
+});
+
+describe("getMcpServerEnabled", () => {
+ it("returns false only for an explicit disabled flag", () => {
+ expect(getMcpServerEnabled({ enabled: false } as unknown as MCPServer)).toBe(
+ false,
+ );
+ });
+
+ it("returns undefined when enabled is true or absent", () => {
+ expect(
+ getMcpServerEnabled({ enabled: true } as unknown as MCPServer),
+ ).toBeUndefined();
+ expect(getMcpServerEnabled({} as unknown as MCPServer)).toBeUndefined();
+ });
+});
+
+describe("parseMcpConfig", () => {
+ it("returns an empty config for non-record input", () => {
+ expect(parseMcpConfig("invalid")).toEqual({});
+ expect(parseMcpConfig(null)).toEqual({});
+ });
+
+ it("unwraps the cloud mcpServers wrapper", () => {
+ expect(
+ parseMcpConfig({
+ mcpServers: {
+ cloud: { url: "https://cloud.example", transport: "http" },
+ },
+ }),
+ ).toEqual({
+ cloud: { transport: "http", url: "https://cloud.example" },
});
- const reordered = parseMcpConfig({
- filesystem: {
+ });
+
+ it("normalizes a fully-populated stdio server", () => {
+ expect(
+ parseMcpConfig({
+ local: {
+ command: "npx",
+ args: ["a", "b"],
+ env: { TOKEN: "value", ignored: 2 },
+ cwd: "/tmp",
+ description: "desc",
+ icon: "icon",
+ timeout: 5,
+ enabled: false,
+ },
+ }),
+ ).toEqual({
+ local: {
transport: "stdio",
command: "npx",
- args: ["-y", "@modelcontextprotocol/server-filesystem"],
+ args: ["a", "b"],
+ env: { TOKEN: "value" },
+ cwd: "/tmp",
+ description: "desc",
+ icon: "icon",
+ timeout: 5,
+ enabled: false,
},
- github: {
+ });
+ });
+
+ it("omits stdio args when not every entry is a string", () => {
+ expect(
+ parseMcpConfig({ local: { command: "x", args: ["ok", 2] } }),
+ ).toEqual({ local: { transport: "stdio", command: "x" } });
+ });
+
+ it("normalizes remote transports and their optional fields", () => {
+ expect(
+ parseMcpConfig({
+ http_default: {
+ url: "https://http.example",
+ headers: { "X-Test": "yes", ignored: 1 },
+ auth: { strategy: "bearer", value: "token" },
+ description: "d",
+ icon: "i",
+ timeout: 0,
+ sse_read_timeout: 10,
+ keep_alive: true,
+ enabled: false,
+ },
+ sse_server: { url: "https://sse.example", transport: "sse" },
+ streamable: { url: "https://x.example", transport: "streamable-http" },
+ shttp_alias: { url: "https://y.example", transport: "shttp" },
+ }),
+ ).toEqual({
+ http_default: {
transport: "http",
- url: "https://github.example/mcp",
+ url: "https://http.example",
+ headers: { "X-Test": "yes" },
+ auth: { strategy: "bearer", value: "token" },
+ description: "d",
+ icon: "i",
+ timeout: 0,
+ sse_read_timeout: 10,
+ keep_alive: true,
+ enabled: false,
},
+ sse_server: { transport: "sse", url: "https://sse.example" },
+ streamable: { transport: "streamable-http", url: "https://x.example" },
+ shttp_alias: { transport: "http", url: "https://y.example" },
});
+ });
+ it("drops invalid auth credentials while keeping the server", () => {
expect(
- flattenMcpConfig(first)
- .map(({ id }) => id)
- .sort(),
- ).toEqual(["filesystem", "github"]);
- expect(
- flattenMcpConfig(reordered)
- .map(({ id }) => id)
- .sort(),
- ).toEqual(["filesystem", "github"]);
+ parseMcpConfig({
+ remote: {
+ url: "https://remote.example",
+ auth: { strategy: "not-a-real-strategy" },
+ },
+ }),
+ ).toEqual({
+ remote: { transport: "http", url: "https://remote.example" },
+ });
});
- it("normalizes the cloud wrapper while preserving tagged auth and OAuth state", () => {
+ it("skips entries that are not usable server records", () => {
expect(
parseMcpConfig({
- mcpServers: {
- github: {
- url: "https://github.example/mcp",
- transport: "streamable-http",
- auth: {
- strategy: "oauth2",
- authentication: {
- type: "oauth",
- client_auth_method: "client_secret_post",
- },
- state: {
- tokens: { access_token: REDACTED_MCP_SECRET_VALUE },
- },
- },
- },
+ scalar: "nope",
+ null_entry: null,
+ empty_object: { foo: "bar" },
+ bad_transport: { url: "https://z.example", transport: "weird" },
+ stdio_transport_url: {
+ url: "https://s.example",
+ transport: "stdio",
},
+ keep: { url: "https://keep.example" },
}),
).toEqual({
- github: {
- transport: "streamable-http",
- url: "https://github.example/mcp",
- auth: {
- strategy: "oauth2",
- authentication: {
- type: "oauth",
- client_auth_method: "client_secret_post",
- },
- state: {
- tokens: { access_token: REDACTED_MCP_SECRET_VALUE },
- },
+ keep: { transport: "http", url: "https://keep.example" },
+ });
+ });
+
+ it("ignores optional fields whose types are wrong", () => {
+ expect(
+ parseMcpConfig({
+ stdio_bad: {
+ command: "c",
+ args: "not-array",
+ env: "not-record",
+ cwd: 1,
+ description: 2,
+ icon: 3,
+ timeout: "x",
+ enabled: "no",
},
- },
+ remote_bad: {
+ url: "https://bad.example",
+ headers: "not-record",
+ auth: 123,
+ description: 1,
+ icon: 2,
+ timeout: "x",
+ sse_read_timeout: "y",
+ keep_alive: "z",
+ enabled: "no",
+ },
+ }),
+ ).toEqual({
+ stdio_bad: { transport: "stdio", command: "c" },
+ remote_bad: { transport: "http", url: "https://bad.example" },
});
});
+});
- it("preserves a disabled server while treating omitted enabled as true", () => {
+describe("canonical MCP configuration integration", () => {
+ // @spec MCP-003 β€” Settings map keys are stable MCP identities
+ it("preserves settings keys through parse and installed-server flattening", () => {
const config = parseMcpConfig({
- disabled: { command: "npx", enabled: false },
- enabled: { command: "npx" },
+ github: { url: "https://github.example/mcp" },
+ filesystem: { command: "npx" },
});
- expect(flattenMcpConfig(config)).toEqual([
- expect.objectContaining({ id: "disabled", enabled: false }),
- expect.objectContaining({ id: "enabled", enabled: undefined }),
+ expect(flattenMcpConfig(config).map(({ id }) => id).sort()).toEqual([
+ "filesystem",
+ "github",
]);
- expect(toCanonicalMcpServer({
- id: "disabled",
+ });
+});
+
+describe("toCanonicalMcpServer", () => {
+ it("serializes a full stdio server", () => {
+ const server: MCPServerConfig = {
+ id: "local",
type: "stdio",
command: "npx",
+ args: ["server"],
+ env: { TOKEN: "value" },
+ enabled: false,
+ };
+ expect(toCanonicalMcpServer(server)).toEqual({
+ transport: "stdio",
+ command: "npx",
+ args: ["server"],
+ env: { TOKEN: "value" },
enabled: false,
- })).toMatchObject({ enabled: false });
+ });
});
-});
-describe("MCP sparse patches", () => {
- const storedRemote: MCPConfig["github"] = {
- transport: "http",
- url: "https://github.example/mcp",
- auth: {
- strategy: "bearer",
- value: REDACTED_MCP_SECRET_VALUE,
- },
- };
+ it("omits empty stdio args and env", () => {
+ const server: MCPServerConfig = {
+ id: "local",
+ type: "stdio",
+ command: "uvx",
+ args: [],
+ env: {},
+ };
+ expect(toCanonicalMcpServer(server)).toEqual({
+ transport: "stdio",
+ command: "uvx",
+ });
+ });
- // @spec MCP-002 β€” Secret patches preserve user intent
- it("omits unchanged redacted auth while updating a non-secret field", () => {
- const edited: MCPServerConfig = {
- id: "github",
+ it("serializes an sse server and ignores timeout", () => {
+ const server: MCPServerConfig = {
+ id: "events",
+ type: "sse",
+ url: "https://events.example",
+ headers: { "X-Test": "yes" },
+ auth: { strategy: "bearer", value: "secret" },
+ timeout: 5,
+ };
+ expect(toCanonicalMcpServer(server)).toEqual({
+ transport: "sse",
+ url: "https://events.example",
+ headers: { "X-Test": "yes" },
+ auth: { strategy: "bearer", value: "secret" },
+ });
+ });
+
+ it("serializes an shttp server and keeps its timeout", () => {
+ const server: MCPServerConfig = {
+ id: "http",
type: "shttp",
- name: "github",
- url: "https://github.example/v2/mcp",
- auth: storedRemote.auth ?? undefined,
+ url: "https://http.example",
+ timeout: 15,
};
+ expect(toCanonicalMcpServer(server)).toEqual({
+ transport: "http",
+ url: "https://http.example",
+ timeout: 15,
+ });
+ });
- expect(buildMcpServerPatch(storedRemote, edited)).toEqual({
+ it("omits empty headers and undefined timeout for remote servers", () => {
+ const server: MCPServerConfig = {
+ id: "http-min",
+ type: "shttp",
+ url: "https://http.example",
+ headers: {},
+ };
+ expect(toCanonicalMcpServer(server)).toStrictEqual({
transport: "http",
- url: "https://github.example/v2/mcp",
+ url: "https://http.example",
});
});
- it("replaces auth when the user enters a new credential", () => {
- const edited: MCPServerConfig = {
- id: "github",
+ it("omits stdio args and env when they are absent", () => {
+ const server: MCPServerConfig = { id: "m", type: "stdio", command: "uvx" };
+ expect(toCanonicalMcpServer(server)).toEqual({
+ transport: "stdio",
+ command: "uvx",
+ });
+ });
+
+ it("keeps enabled:false on a remote server", () => {
+ const server: MCPServerConfig = {
+ id: "r",
type: "shttp",
- name: "github",
- url: storedRemote.url,
- auth: { strategy: "bearer", value: "github_pat_replacement" },
+ url: "https://r.example",
+ enabled: false,
};
+ expect(toCanonicalMcpServer(server)).toEqual({
+ transport: "http",
+ url: "https://r.example",
+ enabled: false,
+ });
+ });
+});
+
+describe("buildMcpServerPatch", () => {
+ const stdioPrevious = { transport: "stdio", command: "old" } as MCPServer;
+
+ it("adds args and env for a stdio edit", () => {
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "stdio",
+ command: "npx",
+ args: ["a"],
+ env: { TOKEN: "value" },
+ };
+ expect(buildMcpServerPatch(stdioPrevious, edited)).toEqual({
+ transport: "stdio",
+ command: "npx",
+ args: ["a"],
+ env: { TOKEN: "value" },
+ });
+ });
- expect(buildMcpServerPatch(storedRemote, edited)).toMatchObject({
- auth: { strategy: "bearer", value: "github_pat_replacement" },
+ it("nulls previously-set args that are removed on edit", () => {
+ const previous = {
+ transport: "stdio",
+ command: "c",
+ args: ["x"],
+ } as MCPServer;
+ const edited: MCPServerConfig = { id: "s", type: "stdio", command: "c" };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "stdio",
+ command: "c",
+ args: null,
});
});
- it("clears auth explicitly when the user selects no authentication", () => {
+ it("skips redacted env values and nulls removed env keys", () => {
+ const previous = {
+ transport: "stdio",
+ command: "c",
+ env: { OLD: "1", KEEP: "2" },
+ } as MCPServer;
const edited: MCPServerConfig = {
- id: "github",
- type: "shttp",
- name: "github",
- url: storedRemote.url,
+ id: "s",
+ type: "stdio",
+ command: "c",
+ env: { KEEP: REDACTED_MCP_SECRET_VALUE, NEW: "3" },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "stdio",
+ command: "c",
+ env: { NEW: "3", OLD: null },
+ });
+ });
+
+ // @spec MCP-002 β€” Secret patches preserve user intent
+ it("clears the entire stdio environment when all entries are removed", () => {
+ const previous: MCPServer = {
+ transport: "stdio",
+ command: "npx",
+ env: { API_KEY: "stored-secret" },
+ };
+ // The form omits env after the user removes every environment entry.
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "stdio",
+ command: "npx",
};
- expect(buildMcpServerPatch(storedRemote, edited)).toMatchObject({
- auth: null,
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "stdio",
+ command: "npx",
+ env: null,
});
});
- it("deletes stale auth fields when replacing one strategy with another", () => {
- const storedOAuth = {
- transport: "http" as const,
- url: "https://mail.example/mcp",
- auth: {
- strategy: "oauth2" as const,
- authentication: { type: "oauth" as const, scopes: "mail.read" },
- state: { tokens: { access_token: REDACTED_MCP_SECRET_VALUE } },
- },
+ it("emits enabled:false when the edit disables the server", () => {
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "sse",
+ url: "https://e.example",
+ enabled: false,
};
- const bearerEdit: MCPServerConfig = {
- id: "mail",
+ expect(buildMcpServerPatch(stdioPrevious, edited)).toEqual({
+ transport: "sse",
+ url: "https://e.example",
+ enabled: false,
+ });
+ });
+
+ it("re-enables a previously disabled server", () => {
+ const previous = {
+ transport: "http",
+ url: "https://e.example",
+ enabled: false,
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
type: "shttp",
- name: "mail",
- url: storedOAuth.url,
- auth: { strategy: "bearer", value: "replacement-token" },
+ url: "https://e.example",
};
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://e.example",
+ enabled: true,
+ });
+ });
- expect(buildMcpServerPatch(storedOAuth, bearerEdit).auth).toEqual({
- strategy: "bearer",
- value: "replacement-token",
- authentication: null,
- state: null,
+ it("sets and clears shttp timeout", () => {
+ const previousWithTimeout = {
+ transport: "http",
+ url: "https://u.example",
+ timeout: 10,
+ } as MCPServer;
+ const clearEdit: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ };
+ expect(buildMcpServerPatch(previousWithTimeout, clearEdit)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ timeout: null,
});
- const storedHeader = {
- transport: "http" as const,
- url: "https://mail.example/mcp",
- auth: {
- strategy: "header" as const,
- headers: { "X-API-Key": REDACTED_MCP_SECRET_VALUE },
- },
+ const setEdit: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ timeout: 5,
};
- const oauthEdit: MCPServerConfig = {
- id: "mail",
+ expect(buildMcpServerPatch(stdioPrevious, setEdit)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ timeout: 5,
+ });
+ });
+
+ it("clears remote auth when the edit removes it", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "tok" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
type: "shttp",
- name: "mail",
- url: storedHeader.url,
- auth: {
- strategy: "oauth2",
- authentication: { type: "oauth", scopes: "mail.read" },
- },
+ url: "https://u.example",
};
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: null,
+ });
+ });
- expect(buildMcpServerPatch(storedHeader, oauthEdit).auth).toEqual({
- strategy: "oauth2",
- authentication: { type: "oauth", scopes: "mail.read" },
- headers: null,
+ it("writes a new non-oauth credential", () => {
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "sse",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "tok" },
+ };
+ expect(buildMcpServerPatch(stdioPrevious, edited)).toEqual({
+ transport: "sse",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "tok" },
});
});
// @spec MCP-002 β€” Secret patches preserve user intent
- it("applies added and changed header-auth headers while preserving redacted leaves", () => {
- const stored = {
- transport: "http" as const,
- url: "https://mail.example/mcp",
- auth: {
- strategy: "header" as const,
- headers: {
- "X-API-Key": REDACTED_MCP_SECRET_VALUE,
- "X-Region": "us-east-1",
- },
- },
+ it("skips a redacted credential rather than persisting the mask", () => {
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "sse",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: REDACTED_MCP_SECRET_VALUE },
};
+ expect(buildMcpServerPatch(stdioPrevious, edited)).toEqual({
+ transport: "sse",
+ url: "https://u.example",
+ });
+ });
+
+ it("nulls fields that differ across a credential strategy replacement", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "tok" },
+ } as MCPServer;
const edited: MCPServerConfig = {
- id: "mail",
+ id: "s",
type: "shttp",
- name: "mail",
- url: stored.url,
- auth: {
- strategy: "header",
- headers: {
- "X-API-Key": REDACTED_MCP_SECRET_VALUE,
- "X-Region": "eu-west-1",
- "X-Trace": "on",
- },
- },
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { "X-One": "one" } },
};
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { "X-One": "one" }, value: null },
+ });
+ });
- expect(buildMcpServerPatch(stored, edited).auth).toEqual({
- strategy: "header",
- headers: { "X-Region": "eu-west-1", "X-Trace": "on" },
+ // @spec MCP-002 β€” Secret patches preserve user intent
+ it("patches header auth by merging headers", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1", B: "2" } },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1", B: "2" } },
});
});
// @spec MCP-002 β€” Secret patches preserve user intent
- it("rejects removing an individual header from header auth", () => {
- const stored = {
- transport: "http" as const,
- url: "https://mail.example/mcp",
+ it("throws when a header removal is attempted", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1", B: "2" } },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ };
+ expect(() => buildMcpServerPatch(previous, edited)).toThrow(
+ MCP_HEADER_REMOVAL_ERROR,
+ );
+ // Asserting against the constant alone would still pass if it were emptied,
+ // because `toThrow("")` matches any error. Pin the actionable wording too.
+ expect(() => buildMcpServerPatch(previous, edited)).toThrow(
+ /replace the credential/i,
+ );
+ });
+
+ it("creates a new oauth credential and drops redacted state leaves", () => {
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
auth: {
- strategy: "header" as const,
- headers: {
- "X-API-Key": REDACTED_MCP_SECRET_VALUE,
- "X-Region": "us-east-1",
+ strategy: "oauth2",
+ authentication: {
+ type: "oauth",
+ client_id: "cid",
+ scopes: ["read", "write"],
+ },
+ state: {
+ token_expires_at: 5,
+ tokens: { access_token: REDACTED_MCP_SECRET_VALUE },
},
},
};
+ expect(buildMcpServerPatch(stdioPrevious, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: {
+ type: "oauth",
+ client_id: "cid",
+ scopes: ["read", "write"],
+ },
+ state: { token_expires_at: 5 },
+ },
+ });
+ });
+
+ it("nulls oauth authentication fields removed on edit", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid", scopes: ["a"] },
+ },
+ } as MCPServer;
const edited: MCPServerConfig = {
- id: "mail",
+ id: "s",
type: "shttp",
- name: "mail",
- url: stored.url,
+ url: "https://u.example",
auth: {
- strategy: "header",
- headers: { "X-Region": "eu-west-1" },
+ strategy: "oauth2",
+ authentication: { type: "oauth", scopes: ["a"] },
},
};
-
- expect(() => buildMcpServerPatch(stored, edited)).toThrow(
- MCP_HEADER_REMOVAL_ERROR,
- );
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: null },
+ },
+ });
});
- it("patches OAuth metadata and a replacement secret without sending redacted state", () => {
- const stored = {
- transport: "http" as const,
- url: "https://mail.example/mcp",
+ // @spec MCP-002 β€” Secret patches preserve user intent
+ it("nulls every editable oauth authentication field the edit clears", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
auth: {
- strategy: "oauth2" as const,
+ strategy: "oauth2",
authentication: {
- type: "oauth" as const,
- client_auth_method: "client_secret_post" as const,
+ type: "oauth",
+ client_auth_method: "client_secret_post",
scopes: "mail.read",
- client_name: "OpenHands Canvas",
- client_metadata_url: "https://mail.example/oauth/client.json",
client_id: "old-client",
client_secret: REDACTED_MCP_SECRET_VALUE,
- },
- state: {
- tokens: {
- access_token: REDACTED_MCP_SECRET_VALUE,
- refresh_token: REDACTED_MCP_SECRET_VALUE,
- },
- token_expires_at: 123,
+ client_name: "OpenHands Canvas",
},
},
- };
+ } as MCPServer;
const edited: MCPServerConfig = {
- id: "mail",
+ id: "s",
type: "shttp",
- name: "mail",
- url: stored.url,
+ url: "https://u.example",
+ auth: { strategy: "oauth2", authentication: { type: "oauth" } },
+ };
+ // Every user-editable field must be nulled individually: an emptied field
+ // list would silently leave the stale client registration in place.
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
auth: {
strategy: "oauth2",
authentication: {
type: "oauth",
- client_auth_method: "client_secret_basic",
- scopes: "mail.read mail.send",
- client_id: "new-client",
- client_secret: "replacement-secret",
+ client_auth_method: null,
+ scopes: null,
+ client_id: null,
+ client_secret: null,
},
- state: stored.auth.state,
},
+ });
+ });
+
+ it("omits the auth key when an oauth credential is unchanged", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ state: { token_expires_at: 5 },
+ },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ state: { token_expires_at: 5 },
+ },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toStrictEqual({
+ transport: "http",
+ url: "https://u.example",
+ });
+ });
+
+ it("omits the env patch when the only change is a redacted secret", () => {
+ const previous = {
+ transport: "stdio",
+ command: "c",
+ env: { SECRET: "real" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "stdio",
+ command: "c",
+ env: { SECRET: REDACTED_MCP_SECRET_VALUE },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toStrictEqual({
+ transport: "stdio",
+ command: "c",
+ });
+ });
+
+ it("ignores timeout for sse edits", () => {
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "sse",
+ url: "https://u.example",
+ timeout: 5,
+ };
+ expect(buildMcpServerPatch(stdioPrevious, edited)).toEqual({
+ transport: "sse",
+ url: "https://u.example",
+ });
+ });
+
+ it("does not clear timeout when the previous server was stdio", () => {
+ const previous = {
+ transport: "stdio",
+ command: "c",
+ timeout: 10,
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ });
+ });
+
+ it("uses stdio env/args baselines only when the previous server was stdio", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ env: { X: "1" },
+ args: ["x"],
+ } as unknown as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "stdio",
+ command: "c",
+ env: { Y: "2" },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "stdio",
+ command: "c",
+ env: { Y: "2" },
+ });
+ });
+
+ it("omits an unchanged-redacted credential field on a same-strategy edit", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "old" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "bearer" },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer" },
+ });
+ });
+
+ it("replaces a header credential with a different strategy", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "x" },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "x", headers: null },
+ });
+ });
+
+ // @spec MCP-002 β€” Secret patches preserve user intent
+ it("keeps the new secret when a strategy replacement reuses a field name", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "api_key", value: "old" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "new" },
+ };
+ // `value` exists on both strategies, so the stale-field deletes must skip
+ // it; nulling it would erase the credential the user just entered.
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "new" },
+ });
+ });
+
+ it("adds a header credential when the previous server was stdio", () => {
+ const previous = { transport: "stdio", command: "c" } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ });
+ });
+
+ it("adds a header credential when the previous remote had no auth", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ });
+ });
+
+ it("makes no header change when the edit only re-sends a redacted header", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: "1" } },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "header", headers: { A: REDACTED_MCP_SECRET_VALUE } },
};
+ expect(buildMcpServerPatch(previous, edited)).toStrictEqual({
+ transport: "http",
+ url: "https://u.example",
+ });
+ });
- const patch = buildMcpServerPatch(stored, edited);
+ it("treats a non-oauth previous credential as having no oauth baseline", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: "old" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "oauth2" },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "oauth2", value: null },
+ });
+ });
- expect(patch.auth).toEqual({
- strategy: "oauth2",
- authentication: {
- type: "oauth",
- client_auth_method: "client_secret_basic",
- scopes: "mail.read mail.send",
- client_id: "new-client",
- client_secret: "replacement-secret",
+ it("patches only oauth state when the authentication block is omitted", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ state: { token_expires_at: 5 },
},
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "oauth2", state: { token_expires_at: 9 } },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "oauth2", state: { token_expires_at: 9 } },
+ });
+ });
+
+ it("clears oauth authentication when it is set to null", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: { strategy: "oauth2", authentication: null },
+ };
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "oauth2", authentication: null },
});
- expect(JSON.stringify(patch)).not.toContain(REDACTED_MCP_SECRET_VALUE);
});
- it("sends nested nulls for explicitly cleared OAuth authentication fields", () => {
- const stored = {
- transport: "http" as const,
- url: "https://mail.example/mcp",
+ it("drops oauth scopes that contain a redacted secret", () => {
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
auth: {
- strategy: "oauth2" as const,
+ strategy: "oauth2",
authentication: {
- type: "oauth" as const,
- client_auth_method: "client_secret_post" as const,
- scopes: "mail.read",
- client_id: "old-client",
- client_secret: REDACTED_MCP_SECRET_VALUE,
- },
- state: {
- tokens: { access_token: REDACTED_MCP_SECRET_VALUE },
+ type: "oauth",
+ client_id: "cid",
+ scopes: ["read", REDACTED_MCP_SECRET_VALUE],
},
},
};
+ expect(buildMcpServerPatch(stdioPrevious, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ },
+ });
+ });
+
+ it("does not resurrect previous oauth state when the edit omits it", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ state: { token_expires_at: 5 },
+ },
+ } as MCPServer;
const edited: MCPServerConfig = {
- id: "mail",
+ id: "s",
type: "shttp",
- name: "mail",
- url: stored.url,
+ url: "https://u.example",
auth: {
strategy: "oauth2",
- authentication: { type: "oauth" },
- state: stored.auth.state,
+ authentication: { type: "oauth", client_id: "NEW" },
},
};
-
- expect(buildMcpServerPatch(stored, edited).auth).toEqual({
- strategy: "oauth2",
- authentication: {
- type: "oauth",
- client_auth_method: null,
- scopes: null,
- client_id: null,
- client_secret: null,
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "NEW" },
},
});
});
- it("omits unchanged redacted env leaves and deletes removed env entries", () => {
- const stored = {
- transport: "stdio" as const,
- command: "npx",
- env: {
- API_KEY: REDACTED_MCP_SECRET_VALUE,
- REGION: "us-east-1",
+ it("keeps an explicit null oauth state", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ state: null,
},
- };
+ } as MCPServer;
const edited: MCPServerConfig = {
- id: "worker",
- type: "stdio",
- name: "worker",
- command: "npx",
- env: {
- API_KEY: REDACTED_MCP_SECRET_VALUE,
- REGION: "eu-west-1",
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
+ auth: {
+ strategy: "oauth2",
+ authentication: { type: "oauth", client_id: "cid" },
+ state: null,
},
};
-
- expect(buildMcpServerPatch(stored, edited)).toMatchObject({
- env: { REGION: "eu-west-1" },
+ expect(buildMcpServerPatch(previous, edited)).toEqual({
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "oauth2", state: null },
});
+ });
+});
- delete edited.env!.REGION;
- expect(buildMcpServerPatch(stored, edited)).toMatchObject({
- env: { REGION: null },
- });
+describe("buildRenameMcpConfigPatch", () => {
+ it("throws when a stdio credential is still redacted", () => {
+ const previous = {
+ transport: "stdio",
+ command: "c",
+ env: { TOKEN: REDACTED_MCP_SECRET_VALUE },
+ } as MCPServer;
+ const edited: MCPServerConfig = { id: "s", type: "stdio", command: "c" };
+ expect(() =>
+ buildRenameMcpConfigPatch("old", "new", previous, edited),
+ ).toThrow(MCP_RENAME_CREDENTIAL_ERROR);
});
- // @spec MCP-003 β€” Settings map keys are stable MCP identities
- it("builds a rename as one map patch and rejects hidden secrets", () => {
- const uncredentialed = {
- transport: "http" as const,
- url: "https://docs.example/mcp",
+ it("throws when a remote credential is still redacted", () => {
+ const previous = {
+ transport: "http",
+ url: "https://u.example",
+ auth: { strategy: "bearer", value: REDACTED_MCP_SECRET_VALUE },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "shttp",
+ url: "https://u.example",
};
- const renamed: MCPServerConfig = {
- id: "docs",
+ expect(() =>
+ buildRenameMcpConfigPatch("old", "new", previous, edited),
+ ).toThrow(MCP_RENAME_CREDENTIAL_ERROR);
+ // Asserting against the constant alone would still pass if it were emptied,
+ // because `toThrow("")` matches any error. Pin the actionable wording too.
+ expect(() =>
+ buildRenameMcpConfigPatch("old", "new", previous, edited),
+ ).toThrow(/before renaming this mcp server/i);
+ });
+
+ // @spec MCP-003 β€” Settings map keys are stable MCP identities
+ it("removes the old key and writes the merged server under the new key", () => {
+ const previous = {
+ transport: "http",
+ url: "https://old.example",
+ auth: { strategy: "bearer", value: "tok" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
type: "shttp",
- name: "reference",
- url: uncredentialed.url,
+ url: "https://new.example",
};
+ expect(buildRenameMcpConfigPatch("old", "new", previous, edited)).toEqual({
+ old: null,
+ new: { transport: "http", url: "https://new.example" },
+ });
+ });
- expect(
- buildRenameMcpConfigPatch("docs", "reference", uncredentialed, renamed),
- ).toEqual({
- docs: null,
- reference: toCanonicalMcpServer(renamed),
+ it("merges nested record fields when renaming", () => {
+ const previous = {
+ transport: "stdio",
+ command: "c",
+ env: { A: "1" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "stdio",
+ command: "c",
+ env: { A: "1", B: "2" },
+ };
+ expect(buildRenameMcpConfigPatch("old", "new", previous, edited)).toEqual({
+ old: null,
+ new: { transport: "stdio", command: "c", env: { A: "1", B: "2" } },
});
- expect(() =>
- buildRenameMcpConfigPatch("github", "github-renamed", storedRemote, {
- id: "github",
- type: "shttp",
- name: "github-renamed",
- url: storedRemote.url,
- auth: storedRemote.auth ?? undefined,
- }),
- ).toThrow(MCP_RENAME_CREDENTIAL_ERROR);
});
// @spec MCP-003 β€” Settings map keys are stable MCP identities
- it("preserves stored remote metadata when renaming a server", () => {
- const stored = {
- transport: "http" as const,
- url: "https://catalog.example/mcp",
- description: "Catalog-managed server",
- icon: "catalog-icon",
- headers: { "X-Catalog-Mode": "managed" },
- sse_read_timeout: 5_000,
- keep_alive: true,
- };
- const renamed: MCPServerConfig = {
- id: "catalog",
+ it("preserves fields the edit does not touch", () => {
+ const previous = {
+ transport: "http",
+ url: "https://old.example",
+ description: "keep",
+ icon: "ico",
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
type: "shttp",
- name: "renamed-catalog",
- url: "https://catalog.example/v2/mcp",
+ url: "https://new.example",
};
+ expect(buildRenameMcpConfigPatch("old", "new", previous, edited)).toEqual({
+ old: null,
+ new: {
+ transport: "http",
+ url: "https://new.example",
+ description: "keep",
+ icon: "ico",
+ },
+ });
+ });
- expect(
- buildRenameMcpConfigPatch("catalog", "renamed-catalog", stored, renamed),
- ).toEqual({
- catalog: null,
- "renamed-catalog": {
- ...stored,
- url: renamed.url,
+ it("deep-merges nested records so untouched secrets survive the rename", () => {
+ const previous = {
+ transport: "stdio",
+ command: "c",
+ env: { A: "1", SECRET: "real" },
+ } as MCPServer;
+ const edited: MCPServerConfig = {
+ id: "s",
+ type: "stdio",
+ command: "c",
+ env: { A: "1", SECRET: REDACTED_MCP_SECRET_VALUE },
+ };
+ expect(buildRenameMcpConfigPatch("old", "new", previous, edited)).toEqual({
+ old: null,
+ new: {
+ transport: "stdio",
+ command: "c",
+ env: { A: "1", SECRET: "real" },
},
});
});
});
+
+describe("allocateMcpSettingsKey", () => {
+ it("normalizes the preferred name when it does not collide", () => {
+ expect(allocateMcpSettingsKey({}, "My Server", "sse")).toBe("My_Server");
+ });
+
+ it("falls back to the provided base when no name is given", () => {
+ expect(allocateMcpSettingsKey({}, undefined, "shttp")).toBe("shttp");
+ });
+
+ it("appends the first free numeric suffix on collision", () => {
+ const config = {
+ tool: {} as MCPServer,
+ tool_1: {} as MCPServer,
+ } satisfies MCPConfig;
+ expect(allocateMcpSettingsKey(config, "tool", "stdio")).toBe("tool_2");
+ });
+
+ it("uses a single suffix when only the base collides", () => {
+ const config = { tool: {} as MCPServer } satisfies MCPConfig;
+ expect(allocateMcpSettingsKey(config, "tool", "stdio")).toBe("tool_1");
+ });
+});