🙌 OpenHands: AI-Driven Development
fix(mcp): explain failed stdio connection tests without the URL hint (#18018)
Engel Nyst60444de16ae8
diff --git a/__tests__/components/features/mcp-page/custom-server-editor.test.tsx b/__tests__/components/features/mcp-page/custom-server-editor.test.tsxindex ae1037c01f..6dfe2e3086 100644--- a/__tests__/components/features/mcp-page/custom-server-editor.test.tsx+++ b/__tests__/components/features/mcp-page/custom-server-editor.test.tsx@@ -303,6 +303,30 @@ describe("CustomServerEditor", () => {);});+ it("explains a stdio connection failure from Test connection as a command that could not start", async () => {+ // Arrange: editing an installed stdio server whose command cannot spawn.+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettingsWithMcp(),+ );+ vi.spyOn(McpService, "testServer").mockResolvedValue({+ ok: false,+ error: "Client failed to connect: [Errno 2] No such file or directory",+ error_kind: "connection",+ });+ renderWith(<EditEditorOnceSettingsLoaded onClose={vi.fn()} />);+ await screen.findByTestId("mcp-custom-editor");++ // Act+ fireEvent.click(screen.getByTestId("mcp-test-connection"));++ // Assert: the stdio-specific message, not the URL hint.+ await waitFor(() =>+ expect(screen.getByTestId("mcp-test-message")).toHaveTextContent(+ "MCP$TEST_ERROR_STDIO_START",+ ),+ );+ });+it("offers Test connection for remote servers on cloud backends and shows the result", async () => {// Arrange: a cloud backend is active and the probe (routed through the// app server) succeeds.diff --git a/__tests__/components/features/mcp-page/install-server-modal.test.tsx b/__tests__/components/features/mcp-page/install-server-modal.test.tsxindex 3bb525f155..06e7e57b89 100644--- a/__tests__/components/features/mcp-page/install-server-modal.test.tsx+++ b/__tests__/components/features/mcp-page/install-server-modal.test.tsx@@ -720,9 +720,11 @@ describe("InstallServerModal", () => {fireEvent.click(screen.getByTestId("mcp-install-submit"));- // Error message must appear.+ // The remote-server connection message must appear.await waitFor(() =>- expect(screen.getByTestId("mcp-install-modal-error")).toBeInTheDocument(),+ expect(screen.getByTestId("mcp-install-modal-error")).toHaveTextContent(+ "MCP$TEST_ERROR_CONNECTION",+ ),);// Save must never have been called.@@ -733,6 +735,33 @@ describe("InstallServerModal", () => {expect(screen.getByTestId("mcp-install-modal")).toBeInTheDocument();});+ it("explains a stdio pre-flight connection failure as a command that could not start", async () => {+ // Arrange: a stdio catalog entry whose command the Agent Server cannot spawn.+ vi.spyOn(McpService, "testServer").mockResolvedValue({+ ok: false,+ error: "Client failed to connect: [Errno 2] No such file or directory",+ error_kind: "connection",+ });+ const saveSpy = vi+ .spyOn(SettingsService, "saveSettings")+ .mockResolvedValue(true);+ const time = MCP_MARKETPLACE.find((e) => e.id === "time")!;+ renderWith(<InstallServerModal existingServers={[]} entry={time} onClose={vi.fn()} />);+ await screen.findByTestId("mcp-install-modal");+ await waitFor(() => expect(SettingsService.getSettings).toHaveBeenCalled());++ // Act+ fireEvent.click(screen.getByTestId("mcp-install-submit"));++ // Assert: the stdio-specific message, not the URL hint, and nothing saved.+ await waitFor(() =>+ expect(screen.getByTestId("mcp-install-modal-error")).toHaveTextContent(+ "MCP$TEST_ERROR_STDIO_START",+ ),+ );+ expect(saveSpy).not.toHaveBeenCalled();+ });+it("shows the credential-specific message when the pre-flight test reports invalid credentials", async () => {// Arrange: installing Slack with credentials its verification call// rejects (the service maps Slack's invalid_auth to "credentials").diff --git a/__tests__/components/features/mcp-page/mcp-server-health.test.tsx b/__tests__/components/features/mcp-page/mcp-server-health.test.tsxindex 257a9cfada..35b224d5a7 100644--- a/__tests__/components/features/mcp-page/mcp-server-health.test.tsx+++ b/__tests__/components/features/mcp-page/mcp-server-health.test.tsx@@ -159,6 +159,30 @@ describe("InstalledServerCard connection health", () => {);});+ it.each([+ { server: STDIO_SERVER, expectedLabel: "MCP$TEST_ERROR_STDIO_START" },+ { server: CUSTOM_SERVER, expectedLabel: "MCP$TEST_ERROR_CONNECTION" },+ ])(+ "labels a $server.type connection failure with transport-specific copy",+ async ({ server, expectedLabel }) => {+ vi.spyOn(McpService, "testServer").mockResolvedValue({+ ok: false,+ error: "Client failed to connect",+ error_kind: "connection",+ });+ renderCard(server);++ fireEvent.click(probeButton(server.id));++ // i18n keys are returned as-is in tests.+ await waitFor(() =>+ expect(screen.getByTestId(`mcp-health-label-${server.id}`)).toHaveTextContent(+ expectedLabel,+ ),+ );+ },+ );+it("renders the health section for remote servers on cloud backends", () => {setRegisteredBackends([{diff --git a/__tests__/utils/mcp-test-error-message.test.ts b/__tests__/utils/mcp-test-error-message.test.tsnew file mode 100644index 0000000000..e5d63e9c33--- /dev/null+++ b/__tests__/utils/mcp-test-error-message.test.ts@@ -0,0 +1,60 @@+import { describe, expect, it } from "vitest";+import i18next, { type TFunction } from "i18next";+import { translationResources } from "#/i18n/resources";+import { makeMcpTestErrorMessage } from "#/utils/mcp-test-error-message";++// Drive a real i18next instance with the actual en resource so the assertions+// cover the rendered copy and its interpolation, not just the chosen key.+const instance = i18next.createInstance();+instance.init({+ lng: "en",+ resources: { en: { openhands: translationResources.en } },+ ns: ["openhands"],+ defaultNS: "openhands",+ interpolation: { escapeValue: false },+});+const t = instance.t as unknown as TFunction<"openhands">;++const STDIO_DETAIL =+ "Client failed to connect: [Errno 2] No such file or directory: 'qa-no-such-command'";+const REMOTE_DETAIL =+ "Client failed to connect: All connection attempts failed";++describe("makeMcpTestErrorMessage", () => {+ it("explains a stdio connection failure as a command that could not start, with the backend detail", () => {+ const message = makeMcpTestErrorMessage(+ t,+ "connection",+ STDIO_DETAIL,+ "stdio",+ );++ expect(message).toBe(`Could not start the server command: ${STDIO_DETAIL}`);+ expect(message).not.toContain("URL");+ });++ it.each(["shttp", "sse", undefined] as const)(+ "keeps the reach-the-server guidance for a %s connection failure and adds the backend detail",+ (serverType) => {+ const message = makeMcpTestErrorMessage(+ t,+ "connection",+ REMOTE_DETAIL,+ serverType,+ );++ expect(message).toBe(+ `Could not reach the server (check the URL and server type): ${REMOTE_DETAIL}`,+ );+ },+ );++ it("leaves timeout and credentials failures unchanged for stdio servers", () => {+ expect(makeMcpTestErrorMessage(t, "timeout", "late", "stdio")).toBe(+ "Connection timed out. Check the URL and try again.",+ );+ expect(+ makeMcpTestErrorMessage(t, "credentials", "invalid_auth", "stdio"),+ ).toBe("Credential check failed: invalid_auth");+ });+});diff --git a/src/components/features/mcp-page/custom-server-editor.tsx b/src/components/features/mcp-page/custom-server-editor.tsxindex 5e8d44905b..b35df6cd7d 100644--- a/src/components/features/mcp-page/custom-server-editor.tsx+++ b/src/components/features/mcp-page/custom-server-editor.tsx@@ -85,11 +85,19 @@ export function CustomServerEditor({text: t(I18nKey.MCP$TEST_SUCCESS, { count: result.tools.length }),};}+ // OAuth results come only from remote servers; `testedServer` may be+ // left over from an earlier non-OAuth test.+ const resultServerType = oauthTestResult ? undefined : testedServer?.type;return {ok: false,- text: makeMcpTestErrorMessage(t, result.error_kind, result.error),+ text: makeMcpTestErrorMessage(+ t,+ result.error_kind,+ result.error,+ resultServerType,+ ),};- }, [oauthTestResult, testResult, t]);+ }, [oauthTestResult, testResult, testedServer, t]);// A save always follows a fresh successful probe of the exact config being// saved, so publish that result to the card's health entry. For stdiodiff --git a/src/components/features/mcp-page/install-server-modal.tsx b/src/components/features/mcp-page/install-server-modal.tsxindex 17007724ad..652938339d 100644--- a/src/components/features/mcp-page/install-server-modal.tsx+++ b/src/components/features/mcp-page/install-server-modal.tsx@@ -278,7 +278,12 @@ export function InstallServerModal({.then((result) => {if (!result.ok) {setGlobalError(- makeMcpTestErrorMessage(t, result.error_kind, result.error),+ makeMcpTestErrorMessage(+ t,+ result.error_kind,+ result.error,+ payload.type,+ ),);return;}@@ -321,7 +326,12 @@ export function InstallServerModal({onSuccess: (result) => {if (!result.ok) {setGlobalError(- makeMcpTestErrorMessage(t, result.error_kind, result.error),+ makeMcpTestErrorMessage(+ t,+ result.error_kind,+ result.error,+ payload.type,+ ),);// Modal stays open — do NOT call onClose.return;diff --git a/src/components/features/mcp-page/mcp-server-health.tsx b/src/components/features/mcp-page/mcp-server-health.tsxindex 9ba2ba9269..0554e6725d 100644--- a/src/components/features/mcp-page/mcp-server-health.tsx+++ b/src/components/features/mcp-page/mcp-server-health.tsx@@ -43,6 +43,7 @@ function getDotStatus(health: McpServerHealth): string {function getStatusLabel(t: TFunction<"openhands">,health: McpServerHealth,+ serverType: MCPServerConfig["type"],): string {switch (health.status) {case "checking":@@ -52,7 +53,7 @@ function getStatusLabel(? t(I18nKey.MCP$HEALTH_STATUS_VERIFIED, { count: health.toolCount }): t(I18nKey.MCP$HEALTH_STATUS_CONNECTIVITY_ONLY);case "failed":- return makeMcpTestErrorMessage(t, health.kind, health.error);+ return makeMcpTestErrorMessage(t, health.kind, health.error, serverType);default:return t(I18nKey.MCP$HEALTH_STATUS_UNCHECKED);}@@ -82,7 +83,7 @@ export function McpServerHealthSection({const isChecking = health.status === "checking";const isFailed = health.status === "failed";- const label = getStatusLabel(t, health);+ const label = getStatusLabel(t, health, server.type);const handleReauthorize = async () => {const result = await reauthorize();diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex 041dd8942b..8ae9147eb1 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -17357,21 +17357,38 @@"uk": "Час очікування з'єднання вичерпано. Перевірте URL-адресу та спробуйте ще раз."},"MCP$TEST_ERROR_CONNECTION": {- "en": "Could not reach the server. Check the URL and server type.",- "ja": "サーバーに接続できませんでした。URLとサーバーの種類を確認してください。",- "zh-CN": "无法连接到服务器。请检查 URL 和服务器类型。",- "zh-TW": "無法連線到伺服器。請檢查 URL 和伺服器類型。",- "ko-KR": "서버에 연결할 수 없습니다. URL과 서버 유형을 확인하세요.",- "no": "Kunne ikke nå serveren. Sjekk URL-en og servertypen.",- "ar": "تعذّر الوصول إلى الخادم. تحقق من عنوان URL ونوع الخادم.",- "de": "Server konnte nicht erreicht werden. Überprüfen Sie die URL und den Servertyp.",- "fr": "Impossible d'atteindre le serveur. Vérifiez l'URL et le type de serveur.",- "it": "Impossibile raggiungere il server. Controlla l'URL e il tipo di server.",- "pt": "Não foi possível acessar o servidor. Verifique a URL e o tipo de servidor.",- "es": "No se pudo conectar con el servidor. Comprueba la URL y el tipo de servidor.",- "ca": "No s'ha pogut connectar amb el servidor. Comprova l'URL i el tipus de servidor.",- "tr": "Sunucuya ulaşılamadı. URL'yi ve sunucu türünü kontrol edin.",- "uk": "Не вдалося підключитися до сервера. Перевірте URL-адресу та тип сервера."+ "en": "Could not reach the server (check the URL and server type): {{-error}}",+ "ja": "サーバーに接続できませんでした(URLとサーバーの種類を確認してください): {{-error}}",+ "zh-CN": "无法连接到服务器(请检查 URL 和服务器类型):{{-error}}",+ "zh-TW": "無法連線到伺服器(請檢查 URL 和伺服器類型):{{-error}}",+ "ko-KR": "서버에 연결할 수 없습니다(URL과 서버 유형을 확인하세요): {{-error}}",+ "no": "Kunne ikke nå serveren (sjekk URL-en og servertypen): {{-error}}",+ "ar": "تعذّر الوصول إلى الخادم (تحقق من عنوان URL ونوع الخادم): {{-error}}",+ "de": "Server konnte nicht erreicht werden (überprüfen Sie die URL und den Servertyp): {{-error}}",+ "fr": "Impossible d'atteindre le serveur (vérifiez l'URL et le type de serveur) : {{-error}}",+ "it": "Impossibile raggiungere il server (controlla l'URL e il tipo di server): {{-error}}",+ "pt": "Não foi possível acessar o servidor (verifique a URL e o tipo de servidor): {{-error}}",+ "es": "No se pudo conectar con el servidor (comprueba la URL y el tipo de servidor): {{-error}}",+ "ca": "No s'ha pogut connectar amb el servidor (comprova l'URL i el tipus de servidor): {{-error}}",+ "tr": "Sunucuya ulaşılamadı (URL'yi ve sunucu türünü kontrol edin): {{-error}}",+ "uk": "Не вдалося підключитися до сервера (перевірте URL-адресу та тип сервера): {{-error}}"+ },+ "MCP$TEST_ERROR_STDIO_START": {+ "en": "Could not start the server command: {{-error}}",+ "ja": "サーバーのコマンドを起動できませんでした: {{-error}}",+ "zh-CN": "无法启动服务器命令:{{-error}}",+ "zh-TW": "無法啟動伺服器命令:{{-error}}",+ "ko-KR": "서버 명령을 시작할 수 없습니다: {{-error}}",+ "no": "Kunne ikke starte serverkommandoen: {{-error}}",+ "ar": "تعذّر تشغيل أمر الخادم: {{-error}}",+ "de": "Der Serverbefehl konnte nicht gestartet werden: {{-error}}",+ "fr": "Impossible de démarrer la commande du serveur : {{-error}}",+ "it": "Impossibile avviare il comando del server: {{-error}}",+ "pt": "Não foi possível iniciar o comando do servidor: {{-error}}",+ "es": "No se pudo iniciar el comando del servidor: {{-error}}",+ "ca": "No s'ha pogut iniciar l'ordre del servidor: {{-error}}",+ "tr": "Sunucu komutu başlatılamadı: {{-error}}",+ "uk": "Не вдалося запустити команду сервера: {{-error}}"},"MCP$TEST_ERROR_UNKNOWN": {"en": "Connection failed: {{-error}}",diff --git a/src/utils/mcp-test-error-message.ts b/src/utils/mcp-test-error-message.tsindex 18e1f15440..ab9e02a469 100644--- a/src/utils/mcp-test-error-message.ts+++ b/src/utils/mcp-test-error-message.ts@@ -1,22 +1,30 @@import type { TFunction } from "i18next";import { I18nKey } from "#/i18n/declaration";-import type { ExtendedMCPTestFailureKind } from "#/types/mcp-server";+import type {+ ExtendedMCPTestFailureKind,+ MCPServerType,+} from "#/types/mcp-server";/*** Kind-specific, localized guidance for a failed MCP connection test.* `error` is interpolated for the kinds whose message surfaces the provider- * detail — callers pass display-safe (redacted) text.+ * detail — callers pass display-safe (redacted) text. `serverType` picks+ * transport-appropriate copy for a `connection` failure: a stdio server has+ * no URL, its command failed to start. An unknown type reads as remote.*/export function makeMcpTestErrorMessage(t: TFunction<"openhands">,errorKind: ExtendedMCPTestFailureKind,error: string,+ serverType: MCPServerType | undefined,): string {switch (errorKind) {case "timeout":return t(I18nKey.MCP$TEST_ERROR_TIMEOUT);case "connection":- return t(I18nKey.MCP$TEST_ERROR_CONNECTION);+ return serverType === "stdio"+ ? t(I18nKey.MCP$TEST_ERROR_STDIO_START, { error })+ : t(I18nKey.MCP$TEST_ERROR_CONNECTION, { error });case "credentials":return t(I18nKey.MCP$TEST_ERROR_CREDENTIALS, { error });default: