From 590e9042e8add02c872a86149530572c4db1cd22 Mon Sep 17 00:00:00 2001
From: zipg <geeky@foxmail.com>
Date: Thu, 23 Jul 2026 12:51:11 +0800
Subject: [PATCH] fix(ai): support Windows Claude Code MCP config

---
 .../src/components/editor/AiAssistant.vue     |  4 +-
 .../editor/EditorSettingsDialog.vue           |  3 +-
 apps/desktop/src/i18n/backend-errors.ts       | 23 ++++++
 apps/desktop/src/i18n/locales/en.ts           | 16 ++++
 apps/desktop/src/i18n/locales/es.ts           | 16 ++++
 apps/desktop/src/i18n/locales/it.ts           | 16 ++++
 apps/desktop/src/i18n/locales/ja.ts           | 16 ++++
 apps/desktop/src/i18n/locales/pt-BR.ts        | 16 ++++
 apps/desktop/src/i18n/locales/zh-CN.ts        | 16 ++++
 apps/desktop/src/i18n/locales/zh-TW.ts        | 16 ++++
 crates/dbx-core/src/ai_claude_code_cli.rs     | 81 +++++++++++++++----
 packages/app-tests/aiCliErrorI18n.test.ts     | 51 ++++++++++++
 packages/app-tests/aiMessageLayout.test.ts    | 19 +++++
 src-tauri/src/commands/mcp.rs                 |  4 +-
 14 files changed, 275 insertions(+), 22 deletions(-)
 create mode 100644 packages/app-tests/aiCliErrorI18n.test.ts

diff --git a/apps/desktop/src/components/editor/AiAssistant.vue b/apps/desktop/src/components/editor/AiAssistant.vue
index bd5df778d8..584aa2163a 100644
--- a/apps/desktop/src/components/editor/AiAssistant.vue
+++ b/apps/desktop/src/components/editor/AiAssistant.vue
@@ -1546,7 +1546,7 @@ async function send() {
     );
   } catch (e: unknown) {
     const message = e instanceof Error ? e.message : String(e);
-    messages.value[assistantIdx].content = `Error: ${message}`;
+    messages.value[assistantIdx].content = `${t("ai.requestFailed")}\n\n${translateBackendError(t, message)}`;
   } finally {
     if (assistantDeltaFrame !== null) cancelAnimationFrame(assistantDeltaFrame);
     flushAssistantDeltas();
@@ -1948,7 +1948,7 @@ async function openExternalUrl(url: string) {
             </div>
 
             <div v-else-if="msg.content || msg.reasoning || msg.isThinking" class="flex">
-              <div class="max-w-[95%] min-w-0 rounded-lg bg-muted px-3 py-2 text-xs leading-relaxed">
+              <div class="max-w-[95%] min-w-0 rounded-lg bg-muted px-3 py-2 text-xs leading-relaxed [overflow-wrap:anywhere]">
                 <div v-if="msg.reasoning || msg.isThinking" class="mb-2">
                   <button class="flex items-center gap-1 text-[11px] text-muted-foreground hover:text-foreground transition-colors" @click="toggleReasoning()">
                     <ChevronRight class="h-3 w-3 transition-transform duration-200" :class="{ 'rotate-90': reasoningExpanded }" />
diff --git a/apps/desktop/src/components/editor/EditorSettingsDialog.vue b/apps/desktop/src/components/editor/EditorSettingsDialog.vue
index 15de1fa51d..8d0ac9417d 100644
--- a/apps/desktop/src/components/editor/EditorSettingsDialog.vue
+++ b/apps/desktop/src/components/editor/EditorSettingsDialog.vue
@@ -3,6 +3,7 @@ import { ref, watch, shallowRef, computed, onMounted, onUnmounted, nextTick } fr
 import type { Ref } from "vue";
 import type { EditorView as EditorViewType } from "@codemirror/view";
 import { useI18n } from "vue-i18n";
+import { translateBackendError } from "@/i18n/backend-errors";
 import { AlertTriangle, ArrowLeft, Check, CheckCircle2, CircleHelp, Cloud, Copy, Download, ExternalLink, GripVertical, Loader2, Moon, PackageSearch, Pencil, Plus, RefreshCw, RotateCcw, Search, Settings, Sun, SunMoon, Terminal, Trash2, Upload, X } from "@lucide/vue";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -2675,7 +2676,7 @@ async function aiTestConn() {
     aiTestLatency.value = result.latencyMs ?? null;
   } catch (e: any) {
     aiTestResult.value = "error";
-    aiTestError.value = e?.message || String(e);
+    aiTestError.value = translateBackendError(t, e?.message || String(e));
   } finally {
     aiTesting.value = false;
   }
diff --git a/apps/desktop/src/i18n/backend-errors.ts b/apps/desktop/src/i18n/backend-errors.ts
index db2aa9bc68..5dbf3b36a5 100644
--- a/apps/desktop/src/i18n/backend-errors.ts
+++ b/apps/desktop/src/i18n/backend-errors.ts
@@ -1,5 +1,18 @@
 import type { ComposerTranslation } from "vue-i18n";
 
+const taggedAiCliErrorKeys: Record<string, string> = {
+  claudeCodeNotInstalled: "ai.cliErrors.claudeCodeNotInstalled",
+  claudeCodeCliPathInvalid: "ai.cliErrors.claudeCodeCliPathInvalid",
+  claudeCodeEnvInvalid: "ai.cliErrors.claudeCodeEnvInvalid",
+  claudeCodeEnvReserved: "ai.cliErrors.claudeCodeEnvReserved",
+  claudeCodeNotAuthenticated: "ai.cliErrors.claudeCodeNotAuthenticated",
+  claudeCodeMcpConfigInvalid: "ai.cliErrors.claudeCodeMcpConfigInvalid",
+  dbxMcpMissing: "ai.cliErrors.dbxMcpMissing",
+  claudeCodeMcpStartupFailed: "ai.cliErrors.claudeCodeMcpStartupFailed",
+  claudeCodeCommandLineTooLong: "ai.cliErrors.claudeCodeCommandLineTooLong",
+  claudeCodeRunFailed: "ai.cliErrors.claudeCodeRunFailed",
+};
+
 const patterns: [RegExp, string][] = [
   [/^(.+?) driver is not installed\. Please install it from the Driver Manager\.$/, "connection.driverNotInstalled"],
   [/^JRE (.+?) runtime is not installed\. Please install it from the Driver Manager\.$/, "connection.jreNotInstalled"],
@@ -49,6 +62,16 @@ const paramNames: Record<string, string> = {
 };
 
 export function translateBackendError(t: ComposerTranslation, message: string): string {
+  const tagged = message.match(/^\[([A-Za-z][A-Za-z0-9]+)\]\s*([\s\S]*)$/);
+  if (tagged) {
+    const [, code, rawDetail] = tagged;
+    const key = taggedAiCliErrorKeys[code];
+    if (key) {
+      const detail = rawDetail.trim();
+      return [t(key), t("ai.cliErrors.code", { code }), t("ai.cliErrors.reportHint"), detail ? `${t("ai.cliErrors.details")}\n${detail}` : ""].filter(Boolean).join("\n\n");
+    }
+  }
+
   for (const [regex, key] of patterns) {
     const match = message.match(regex);
     if (match) {
diff --git a/apps/desktop/src/i18n/locales/en.ts b/apps/desktop/src/i18n/locales/en.ts
index 5fcd4f3018..bcd2ffe368 100644
--- a/apps/desktop/src/i18n/locales/en.ts
+++ b/apps/desktop/src/i18n/locales/en.ts
@@ -1517,6 +1517,7 @@ export default {
     apply: "Apply to Editor",
     clear: "Clear Chat",
     welcome: "Tell me what you'd like to query, and I'll write the SQL",
+    requestFailed: "AI request failed",
     newChat: "New Chat",
     thinking: "Thinking...",
     reasoningProcess: "Thinking process",
@@ -1618,6 +1619,21 @@ export default {
     reasoningLevelHint: "Controls Codex CLI model_reasoning_effort. Default uses your Codex config.",
     claudeCodeEffortHint: "Available levels are reported by the selected model through your local Claude Code CLI.",
     claudeCodeEffortUnavailable: "The selected model does not report configurable effort levels. Claude Code will use its default.",
+    cliErrors: {
+      code: "Error code: {code}",
+      details: "Diagnostic details:",
+      reportHint: "When reporting this problem, include the error code and diagnostic details below.",
+      claudeCodeNotInstalled: "Claude Code CLI was not found. Install Claude Code or set its executable path in Settings > AI.",
+      claudeCodeCliPathInvalid: "The Claude Code CLI path is invalid. Select only the Claude executable and configure environment variables separately.",
+      claudeCodeEnvInvalid: "A Claude Code CLI environment variable name is invalid. Use names such as HTTPS_PROXY.",
+      claudeCodeEnvReserved: "A DBX-managed MCP environment variable was overridden. Remove DBX_MCP_* variables from the provider configuration.",
+      claudeCodeNotAuthenticated: "Claude Code CLI is not authenticated. Run `claude auth login` in a terminal and try again.",
+      claudeCodeMcpConfigInvalid: "Claude Code could not read or parse the DBX MCP configuration. Check the Claude Code CLI version and executable path.",
+      dbxMcpMissing: "A compatible DBX MCP Server installation was not found. Check Settings > MCP, then reinstall or update it.",
+      claudeCodeMcpStartupFailed: "Claude Code loaded the MCP configuration but could not start DBX MCP Server. Check Settings > MCP and the diagnostics below.",
+      claudeCodeCommandLineTooLong: "Windows rejected the Claude Code command because it was too long. Update DBX and retry using the generated MCP configuration file.",
+      claudeCodeRunFailed: "Claude Code CLI exited unexpectedly. Use the error code and diagnostics below to identify the failing executable or CLI output.",
+    },
     actions: {
       general: "General",
       generate: "Generate SQL",
diff --git a/apps/desktop/src/i18n/locales/es.ts b/apps/desktop/src/i18n/locales/es.ts
index 35634081b0..5207ff02c3 100644
--- a/apps/desktop/src/i18n/locales/es.ts
+++ b/apps/desktop/src/i18n/locales/es.ts
@@ -1475,6 +1475,21 @@ export default withEnglishFallback({
     reasoningLevelHint: "Controla model_reasoning_effort de Codex CLI. Predeterminado usa tu configuración de Codex.",
     claudeCodeEffortHint: "Los niveles disponibles los proporciona dinámicamente tu Claude Code CLI local para el modelo seleccionado.",
     claudeCodeEffortUnavailable: "El modelo seleccionado no informa niveles de esfuerzo configurables. Claude Code usará su valor predeterminado.",
+    cliErrors: {
+      code: "Código de error: {code}",
+      details: "Detalles de diagnóstico:",
+      reportHint: "Al informar este problema, incluye el código de error y los detalles de diagnóstico siguientes.",
+      claudeCodeNotInstalled: "No se encontró Claude Code CLI. Instala Claude Code o configura la ruta del ejecutable en Configuración > AI.",
+      claudeCodeCliPathInvalid: "La ruta de Claude Code CLI no es válida. Selecciona solo el ejecutable de Claude y configura las variables de entorno por separado.",
+      claudeCodeEnvInvalid: "El nombre de una variable de entorno de Claude Code CLI no es válido. Usa nombres como HTTPS_PROXY.",
+      claudeCodeEnvReserved: "Se sobrescribió una variable MCP administrada por DBX. Elimina las variables DBX_MCP_* de la configuración del proveedor.",
+      claudeCodeNotAuthenticated: "Claude Code CLI no está autenticado. Ejecuta `claude auth login` en una terminal y vuelve a intentarlo.",
+      claudeCodeMcpConfigInvalid: "Claude Code no pudo leer o analizar la configuración MCP de DBX. Comprueba la versión y la ruta del ejecutable de Claude Code CLI.",
+      dbxMcpMissing: "No se encontró una instalación compatible de DBX MCP Server. Comprueba Configuración > MCP y vuelve a instalarla o actualizarla.",
+      claudeCodeMcpStartupFailed: "Claude Code cargó la configuración MCP, pero no pudo iniciar DBX MCP Server. Comprueba Configuración > MCP y los detalles siguientes.",
+      claudeCodeCommandLineTooLong: "Windows rechazó el comando de Claude Code porque era demasiado largo. Actualiza DBX y vuelve a intentarlo con el archivo MCP generado.",
+      claudeCodeRunFailed: "Claude Code CLI terminó de forma inesperada. Usa el código de error y los detalles siguientes para identificar el ejecutable o la salida que falló.",
+    },
     run: "Ejecutar",
     readingSchema: "Leyendo esquema",
     noConnection: "No hay una conexión disponible para esta pestaña",
@@ -1492,6 +1507,7 @@ export default withEnglishFallback({
     apply: "Aplicar al editor",
     clear: "Limpiar chat",
     welcome: "Dime qué quieres consultar y escribiré el SQL",
+    requestFailed: "La solicitud de AI falló",
     newChat: "Nuevo chat",
     thinking: "Procesando...",
     reasoningProcess: "Proceso de razonamiento",
diff --git a/apps/desktop/src/i18n/locales/it.ts b/apps/desktop/src/i18n/locales/it.ts
index b6ae711e0e..72e1da0fe6 100644
--- a/apps/desktop/src/i18n/locales/it.ts
+++ b/apps/desktop/src/i18n/locales/it.ts
@@ -1457,6 +1457,7 @@ export default withEnglishFallback({
     apply: "Applica all'Editor",
     clear: "Cancella Chat",
     welcome: "Dimmi cosa vorresti interrogare e io scriverò il codice SQL",
+    requestFailed: "Richiesta AI non riuscita",
     newChat: "Nuova Chat",
     thinking: "Riflessione...",
     reasoningProcess: "Processo di riflessione",
@@ -1592,6 +1593,21 @@ export default withEnglishFallback({
     reasoningLevelHint: "Controlla model_reasoning_effort di Codex CLI. Predefinito usa la configurazione Codex.",
     claudeCodeEffortHint: "I livelli disponibili vengono forniti dinamicamente dal Claude Code CLI locale per il modello selezionato.",
     claudeCodeEffortUnavailable: "Il modello selezionato non segnala livelli di effort configurabili. Claude Code userà il valore predefinito.",
+    cliErrors: {
+      code: "Codice errore: {code}",
+      details: "Dettagli diagnostici:",
+      reportHint: "Quando segnali il problema, includi il codice errore e i dettagli diagnostici seguenti.",
+      claudeCodeNotInstalled: "Claude Code CLI non è stato trovato. Installa Claude Code o imposta il percorso dell'eseguibile in Impostazioni > AI.",
+      claudeCodeCliPathInvalid: "Il percorso di Claude Code CLI non è valido. Seleziona solo l'eseguibile Claude e configura separatamente le variabili d'ambiente.",
+      claudeCodeEnvInvalid: "Il nome di una variabile d'ambiente di Claude Code CLI non è valido. Usa nomi come HTTPS_PROXY.",
+      claudeCodeEnvReserved: "È stata sovrascritta una variabile MCP gestita da DBX. Rimuovi le variabili DBX_MCP_* dalla configurazione del provider.",
+      claudeCodeNotAuthenticated: "Claude Code CLI non è autenticato. Esegui `claude auth login` in un terminale e riprova.",
+      claudeCodeMcpConfigInvalid: "Claude Code non ha potuto leggere o analizzare la configurazione MCP di DBX. Controlla la versione e il percorso di Claude Code CLI.",
+      dbxMcpMissing: "Non è stata trovata un'installazione compatibile di DBX MCP Server. Controlla Impostazioni > MCP, quindi reinstalla o aggiorna.",
+      claudeCodeMcpStartupFailed: "Claude Code ha caricato la configurazione MCP ma non ha potuto avviare DBX MCP Server. Controlla Impostazioni > MCP e i dettagli seguenti.",
+      claudeCodeCommandLineTooLong: "Windows ha rifiutato il comando Claude Code perché troppo lungo. Aggiorna DBX e riprova usando il file MCP generato.",
+      claudeCodeRunFailed: "Claude Code CLI è terminato in modo imprevisto. Usa il codice errore e i dettagli seguenti per identificare l'eseguibile o l'output non riuscito.",
+    },
     actions: {
       general: "Generale",
       generate: "Genera SQL",
diff --git a/apps/desktop/src/i18n/locales/ja.ts b/apps/desktop/src/i18n/locales/ja.ts
index f651568b52..b2de9008f0 100644
--- a/apps/desktop/src/i18n/locales/ja.ts
+++ b/apps/desktop/src/i18n/locales/ja.ts
@@ -1479,6 +1479,21 @@ export default withEnglishFallback({
     reasoningLevelHint: "Codex CLIのmodel_reasoning_effortを制御します。デフォルトではCodex設定を使用します。",
     claudeCodeEffortHint: "利用可能なレベルは、選択したモデルについてローカルのClaude Code CLIから動的に取得されます。",
     claudeCodeEffortUnavailable: "選択したモデルは設定可能なeffortレベルを返していません。Claude Codeのデフォルトを使用します。",
+    cliErrors: {
+      code: "エラーコード: {code}",
+      details: "診断詳細:",
+      reportHint: "この問題を報告する際は、エラーコードと以下の診断詳細を添付してください。",
+      claudeCodeNotInstalled: "Claude Code CLIが見つかりません。Claude Codeをインストールするか、設定 > AIで実行ファイルのパスを指定してください。",
+      claudeCodeCliPathInvalid: "Claude Code CLIのパスが無効です。Claudeの実行ファイルのみを選択し、環境変数は別に設定してください。",
+      claudeCodeEnvInvalid: "Claude Code CLIの環境変数名が無効です。HTTPS_PROXYなどの有効な名前を使用してください。",
+      claudeCodeEnvReserved: "DBXが管理するMCP環境変数が上書きされています。プロバイダー設定からDBX_MCP_*変数を削除してください。",
+      claudeCodeNotAuthenticated: "Claude Code CLIにログインしていません。ターミナルで`claude auth login`を実行してから再試行してください。",
+      claudeCodeMcpConfigInvalid: "Claude CodeがDBXのMCP設定を読み取りまたは解析できません。Claude Code CLIのバージョンと実行ファイルのパスを確認してください。",
+      dbxMcpMissing: "互換性のあるDBX MCP Serverが見つかりません。設定 > MCPで確認し、再インストールまたは更新してください。",
+      claudeCodeMcpStartupFailed: "Claude CodeはMCP設定を読み込みましたが、DBX MCP Serverを起動できません。設定 > MCPと以下の診断詳細を確認してください。",
+      claudeCodeCommandLineTooLong: "Windowsが長すぎるClaude Codeコマンドを拒否しました。DBXを更新し、生成されたMCP設定ファイルで再試行してください。",
+      claudeCodeRunFailed: "Claude Code CLIが予期せず終了しました。エラーコードと以下の診断詳細から、失敗した実行ファイルまたはCLI出力を確認してください。",
+    },
     run: "実行",
     readingSchema: "スキーマを読み取り中",
     noConnection: "このタブに利用可能な接続がありません",
@@ -1496,6 +1511,7 @@ export default withEnglishFallback({
     apply: "エディタに適用",
     clear: "チャットをクリア",
     welcome: "クエリしたい内容を教えてください。SQLを作成します",
+    requestFailed: "AIリクエストに失敗しました",
     newChat: "新しいチャット",
     thinking: "思考中...",
     reasoningProcess: "思考プロセス",
diff --git a/apps/desktop/src/i18n/locales/pt-BR.ts b/apps/desktop/src/i18n/locales/pt-BR.ts
index 93ec3cf9a8..8d8d22ee87 100644
--- a/apps/desktop/src/i18n/locales/pt-BR.ts
+++ b/apps/desktop/src/i18n/locales/pt-BR.ts
@@ -1477,6 +1477,21 @@ export default withEnglishFallback({
     reasoningLevelHint: "Controla model_reasoning_effort do Codex CLI. Padrão usa sua configuração do Codex.",
     claudeCodeEffortHint: "Os níveis disponíveis são informados dinamicamente pelo Claude Code CLI local para o modelo selecionado.",
     claudeCodeEffortUnavailable: "O modelo selecionado não informa níveis de effort configuráveis. O Claude Code usará o padrão.",
+    cliErrors: {
+      code: "Código do erro: {code}",
+      details: "Detalhes de diagnóstico:",
+      reportHint: "Ao relatar este problema, inclua o código do erro e os detalhes de diagnóstico abaixo.",
+      claudeCodeNotInstalled: "Claude Code CLI não foi encontrado. Instale o Claude Code ou defina o caminho do executável em Configurações > AI.",
+      claudeCodeCliPathInvalid: "O caminho do Claude Code CLI é inválido. Selecione apenas o executável do Claude e configure as variáveis de ambiente separadamente.",
+      claudeCodeEnvInvalid: "O nome de uma variável de ambiente do Claude Code CLI é inválido. Use nomes como HTTPS_PROXY.",
+      claudeCodeEnvReserved: "Uma variável MCP gerenciada pelo DBX foi sobrescrita. Remova as variáveis DBX_MCP_* da configuração do provedor.",
+      claudeCodeNotAuthenticated: "Claude Code CLI não está autenticado. Execute `claude auth login` em um terminal e tente novamente.",
+      claudeCodeMcpConfigInvalid: "O Claude Code não conseguiu ler ou analisar a configuração MCP do DBX. Verifique a versão e o caminho do executável do Claude Code CLI.",
+      dbxMcpMissing: "Uma instalação compatível do DBX MCP Server não foi encontrada. Verifique Configurações > MCP e reinstale ou atualize.",
+      claudeCodeMcpStartupFailed: "O Claude Code carregou a configuração MCP, mas não conseguiu iniciar o DBX MCP Server. Verifique Configurações > MCP e os detalhes abaixo.",
+      claudeCodeCommandLineTooLong: "O Windows rejeitou o comando do Claude Code porque era muito longo. Atualize o DBX e tente novamente com o arquivo MCP gerado.",
+      claudeCodeRunFailed: "Claude Code CLI foi encerrado inesperadamente. Use o código do erro e os detalhes abaixo para identificar o executável ou a saída com falha.",
+    },
     run: "Executar",
     readingSchema: "Lendo schema",
     noConnection: "Nenhuma conexão disponível para esta aba",
@@ -1494,6 +1509,7 @@ export default withEnglishFallback({
     apply: "Aplicar ao Editor",
     clear: "Limpar Conversa",
     welcome: "Diga o que você gostaria de consultar e eu escreverei o SQL",
+    requestFailed: "Falha na solicitação de AI",
     newChat: "Nova Conversa",
     thinking: "Pensando...",
     reasoningProcess: "Processo de raciocínio",
diff --git a/apps/desktop/src/i18n/locales/zh-CN.ts b/apps/desktop/src/i18n/locales/zh-CN.ts
index 353155e3d7..d86966081d 100644
--- a/apps/desktop/src/i18n/locales/zh-CN.ts
+++ b/apps/desktop/src/i18n/locales/zh-CN.ts
@@ -1517,6 +1517,7 @@ export default withEnglishFallback({
     apply: "应用到编辑器",
     clear: "清空对话",
     welcome: "聊聊你想查什么，我来写 SQL",
+    requestFailed: "AI 请求失败",
     newChat: "新对话",
     thinking: "思考中...",
     reasoningProcess: "思考过程",
@@ -1618,6 +1619,21 @@ export default withEnglishFallback({
     reasoningLevelHint: "控制 Codex CLI 的 model_reasoning_effort。默认使用你的 Codex 配置。",
     claudeCodeEffortHint: "可用级别由本地 Claude Code CLI 根据所选模型动态提供。",
     claudeCodeEffortUnavailable: "所选模型未提供可配置的推理级别，将使用 Claude Code 的默认设置。",
+    cliErrors: {
+      code: "错误代码：{code}",
+      details: "诊断详情：",
+      reportHint: "反馈此问题时，请同时提供错误代码和下方诊断详情。",
+      claudeCodeNotInstalled: "未找到 Claude Code CLI。请安装 Claude Code，或在 设置 > AI 中填写其可执行文件路径。",
+      claudeCodeCliPathInvalid: "Claude Code CLI 路径无效。请只选择 Claude 可执行文件，环境变量需单独配置。",
+      claudeCodeEnvInvalid: "Claude Code CLI 环境变量名称无效。请使用 HTTPS_PROXY 这类合法名称。",
+      claudeCodeEnvReserved: "配置覆盖了由 DBX 管理的 MCP 环境变量。请从供应商配置中移除 DBX_MCP_* 变量。",
+      claudeCodeNotAuthenticated: "Claude Code CLI 尚未登录。请在终端执行 `claude auth login` 后重试。",
+      claudeCodeMcpConfigInvalid: "Claude Code 无法读取或解析 DBX 生成的 MCP 配置。请检查 Claude Code CLI 版本和可执行文件路径。",
+      dbxMcpMissing: "未找到兼容的 DBX MCP Server。请在 设置 > MCP 中检查并重新安装或更新。",
+      claudeCodeMcpStartupFailed: "Claude Code 已加载 MCP 配置，但无法启动 DBX MCP Server。请检查 设置 > MCP 和下方诊断详情。",
+      claudeCodeCommandLineTooLong: "Windows 拒绝了过长的 Claude Code 命令。请更新 DBX，并使用生成的 MCP 配置文件重试。",
+      claudeCodeRunFailed: "Claude Code CLI 异常退出。请根据错误代码和下方诊断详情确认失败的可执行文件或 CLI 输出。",
+    },
     actions: {
       general: "通用问答",
       generate: "生成 SQL",
diff --git a/apps/desktop/src/i18n/locales/zh-TW.ts b/apps/desktop/src/i18n/locales/zh-TW.ts
index af0cdf42a2..6dd7c5b536 100644
--- a/apps/desktop/src/i18n/locales/zh-TW.ts
+++ b/apps/desktop/src/i18n/locales/zh-TW.ts
@@ -1459,6 +1459,7 @@ export default withEnglishFallback({
     apply: "套用到編輯器",
     clear: "清空對話",
     welcome: "告訴我你想查詢什麼，我會寫出 SQL",
+    requestFailed: "AI 請求失敗",
     newChat: "新對話",
     thinking: "思考中……",
     reasoningProcess: "思考過程",
@@ -1594,6 +1595,21 @@ export default withEnglishFallback({
     reasoningLevelHint: "控制 Codex CLI 的 model_reasoning_effort。預設會使用你的 Codex 設定。",
     claudeCodeEffortHint: "可用層級由本機 Claude Code CLI 根據所選模型動態提供。",
     claudeCodeEffortUnavailable: "所選模型未提供可設定的推理層級，將使用 Claude Code 的預設設定。",
+    cliErrors: {
+      code: "錯誤代碼：{code}",
+      details: "診斷詳情：",
+      reportHint: "回報此問題時，請同時提供錯誤代碼和下方診斷詳情。",
+      claudeCodeNotInstalled: "找不到 Claude Code CLI。請安裝 Claude Code，或在 設定 > AI 中填寫其可執行檔路徑。",
+      claudeCodeCliPathInvalid: "Claude Code CLI 路徑無效。請只選擇 Claude 可執行檔，環境變數需另外設定。",
+      claudeCodeEnvInvalid: "Claude Code CLI 環境變數名稱無效。請使用 HTTPS_PROXY 這類合法名稱。",
+      claudeCodeEnvReserved: "設定覆寫了由 DBX 管理的 MCP 環境變數。請從供應商設定中移除 DBX_MCP_* 變數。",
+      claudeCodeNotAuthenticated: "Claude Code CLI 尚未登入。請在終端機執行 `claude auth login` 後重試。",
+      claudeCodeMcpConfigInvalid: "Claude Code 無法讀取或解析 DBX 產生的 MCP 設定。請檢查 Claude Code CLI 版本和可執行檔路徑。",
+      dbxMcpMissing: "找不到相容的 DBX MCP Server。請在 設定 > MCP 中檢查並重新安裝或更新。",
+      claudeCodeMcpStartupFailed: "Claude Code 已載入 MCP 設定，但無法啟動 DBX MCP Server。請檢查 設定 > MCP 和下方診斷詳情。",
+      claudeCodeCommandLineTooLong: "Windows 拒絕了過長的 Claude Code 命令。請更新 DBX，並使用產生的 MCP 設定檔重試。",
+      claudeCodeRunFailed: "Claude Code CLI 異常結束。請依據錯誤代碼和下方診斷詳情確認失敗的可執行檔或 CLI 輸出。",
+    },
     actions: {
       general: "通用問答",
       generate: "產生 SQL",
diff --git a/crates/dbx-core/src/ai_claude_code_cli.rs b/crates/dbx-core/src/ai_claude_code_cli.rs
index 2747989f2d..5c1aaf0519 100644
--- a/crates/dbx-core/src/ai_claude_code_cli.rs
+++ b/crates/dbx-core/src/ai_claude_code_cli.rs
@@ -32,6 +32,13 @@ impl ClaudeCodeIsolatedCwd {
         })?;
         Ok(Self { path })
     }
+
+    fn write_mcp_config(&self, config: &str) -> Result<PathBuf, String> {
+        let path = self.path.join("mcp.json");
+        std::fs::write(&path, config)
+            .map_err(|error| format!("[claudeCodeRunFailed] Failed to write temporary MCP configuration: {error}"))?;
+        Ok(path)
+    }
 }
 
 impl Drop for ClaudeCodeIsolatedCwd {
@@ -242,6 +249,14 @@ pub fn build_claude_code_command(
     config: &AiConfig,
     _prompt: &str,
     options: &ClaudeCodeRunOptions,
+) -> ClaudeCodeCommandSpec {
+    build_claude_code_command_with_mcp_arg(config, options, claude_code_mcp_config(options))
+}
+
+fn build_claude_code_command_with_mcp_arg(
+    config: &AiConfig,
+    options: &ClaudeCodeRunOptions,
+    mcp_config_arg: String,
 ) -> ClaudeCodeCommandSpec {
     let enabled_tools = claude_code_enabled_tools(options.agent_mode);
     let mut args = vec![
@@ -255,7 +270,7 @@ pub fn build_claude_code_command(
         "--permission-mode".to_string(),
         "dontAsk".to_string(),
         "--mcp-config".to_string(),
-        claude_code_mcp_config(options),
+        mcp_config_arg,
         "--strict-mcp-config".to_string(),
     ];
     append_claude_code_isolation_args(&mut args);
@@ -438,12 +453,11 @@ pub async fn test_claude_code_connection(config: &AiConfig) -> Result<AiTestConn
 
 fn classify_claude_code_spawn_error(message: &str) -> String {
     if message.contains("No such file") || message.contains("not found") {
-        "[claudeCodeNotInstalled] Claude Code CLI was not found. Install Claude Code or set the Claude Code CLI path in DBX AI settings."
-            .to_string()
+        format!("[claudeCodeNotInstalled] {message}")
     } else if is_command_line_too_long_error(message) {
-        "[claudeCodeCommandLineTooLong] Claude Code CLI command line is too long.".to_string()
+        format!("[claudeCodeCommandLineTooLong] {message}")
     } else {
-        format!("[claudeCodeRunFailed] Failed to start Claude Code CLI: {message}")
+        format!("[claudeCodeRunFailed] {message}")
     }
 }
 
@@ -457,16 +471,19 @@ fn is_command_line_too_long_error(message: &str) -> bool {
 
 fn classify_claude_code_run_error(stderr: &str) -> String {
     let lower = stderr.to_ascii_lowercase();
-    if lower.contains("not authenticated") || lower.contains("login") || lower.contains("auth") {
-        format!(
-            "[claudeCodeNotAuthenticated] Claude Code CLI is not authenticated. Run `claude auth login` and try again. {stderr}"
-        )
+    if lower.contains("invalid mcp configuration") || lower.contains("mcp config file not found") {
+        format!("[claudeCodeMcpConfigInvalid] {stderr}")
+    } else if lower.contains("not authenticated")
+        || lower.contains("authentication required")
+        || lower.contains("please login")
+    {
+        format!("[claudeCodeNotAuthenticated] {stderr}")
     } else if lower.contains("dbx-mcp-server") || lower.contains("enoent") {
-        format!("[dbxMcpMissing] DBX MCP server was not found. Install @dbx-app/mcp-server and try again. {stderr}")
+        format!("[dbxMcpMissing] {stderr}")
     } else if lower.contains("mcp") && (lower.contains("dbx") || lower.contains("server")) {
-        format!("[claudeCodeMcpStartupFailed] Claude Code could not start the DBX MCP server. {stderr}")
+        format!("[claudeCodeMcpStartupFailed] {stderr}")
     } else {
-        format!("[claudeCodeRunFailed] Claude Code CLI failed. {stderr}")
+        format!("[claudeCodeRunFailed] {stderr}")
     }
 }
 
@@ -482,10 +499,12 @@ pub async fn run_claude_code_agent(
     on_event: impl Fn(AgentEvent) + Send + Sync + 'static,
 ) -> Result<String, String> {
     let program = validate_claude_code_program(config)?;
-    let mut command = build_claude_code_command(config, prompt, &options);
+    let isolated_cwd = ClaudeCodeIsolatedCwd::create()?;
+    let mcp_config_path = isolated_cwd.write_mcp_config(&claude_code_mcp_config(&options))?;
+    let mut command =
+        build_claude_code_command_with_mcp_arg(config, &options, mcp_config_path.to_string_lossy().to_string());
     command.program = program;
     let env = claude_code_process_env(config, &command)?;
-    let isolated_cwd = ClaudeCodeIsolatedCwd::create()?;
     let result = run_cli_jsonl_agent(
         CliAgentProcessSpec {
             command,
@@ -506,8 +525,9 @@ pub async fn run_claude_code_agent(
 #[cfg(test)]
 mod tests {
     use super::{
-        build_claude_code_command, claude_code_cli_env, claude_code_enabled_tools, parse_claude_code_jsonl_event,
-        parse_claude_code_models, validate_claude_code_program, ClaudeCodeRunOptions, DEFAULT_CLAUDE_CODE_MODELS,
+        build_claude_code_command, classify_claude_code_run_error, claude_code_cli_env, claude_code_enabled_tools,
+        parse_claude_code_jsonl_event, parse_claude_code_models, validate_claude_code_program, ClaudeCodeRunOptions,
+        DEFAULT_CLAUDE_CODE_MODELS,
     };
     #[cfg(unix)]
     use super::{list_claude_code_models, run_claude_code_agent};
@@ -584,10 +604,13 @@ mod tests {
             &executable,
             r#"#!/bin/sh
 user_settings=false
+mcp_config=""
 previous=""
 for arg in "$@"; do
   if [ "$previous" = "--setting-sources" ] && [ "$arg" = "user" ]; then
     user_settings=true
+  elif [ "$previous" = "--mcp-config" ]; then
+    mcp_config="$arg"
   fi
   previous="$arg"
 done
@@ -603,6 +626,10 @@ case " $* " in
     printf '%s\n' '{"type":"control_response","response":{"response":{"models":[{"value":"claude-user-model","displayName":"User Model"}]}}}'
     ;;
   *)
+    if [ ! -f "$mcp_config" ] || ! grep -q '"mcpServers"' "$mcp_config"; then
+      printf '%s\n' 'invalid MCP configuration' >&2
+      exit 10
+    fi
     printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"isolated execution"}]}}'
     printf '%s\n' '{"type":"result","subtype":"success"}'
     ;;
@@ -665,7 +692,7 @@ esac
 
     #[cfg(unix)]
     #[tokio::test]
-    async fn execution_uses_user_settings_from_an_isolated_directory() {
+    async fn execution_uses_user_settings_and_temporary_mcp_config_from_an_isolated_directory() {
         let (config, project_dir, hook_marker) = isolated_cli_test_config();
 
         let output = run_claude_code_agent(&config, "hello", run_options(), &Notify::new(), |_| {}).await.unwrap();
@@ -762,6 +789,26 @@ esac
         assert!(parse_claude_code_models(stdout).is_none());
     }
 
+    #[test]
+    fn invalid_mcp_config_is_not_reported_as_a_missing_server_package() {
+        let error = classify_claude_code_run_error(
+            r#"Invalid MCP configuration: MCP config file not found: C:\Temp\{mcpServers:{dbx:{args:[C:\node_modules\@dbx-app\mcp-server\bin\dbx-mcp-server.js]}}}"#,
+        );
+
+        assert!(error.starts_with("[claudeCodeMcpConfigInvalid]"));
+        assert!(!error.contains("[dbxMcpMissing]"));
+    }
+
+    #[test]
+    fn invalid_mcp_config_path_containing_auth_is_not_reported_as_authentication_failure() {
+        let error = classify_claude_code_run_error(
+            r#"Invalid MCP configuration: MCP config file not found: C:\Users\auth-test\AppData\Local\Temp\dbx\mcp.json"#,
+        );
+
+        assert!(error.starts_with("[claudeCodeMcpConfigInvalid]"));
+        assert!(!error.contains("[claudeCodeNotAuthenticated]"));
+    }
+
     #[test]
     fn normalizes_claude_code_cli_env() {
         let mut config = claude_code_config("default");
diff --git a/packages/app-tests/aiCliErrorI18n.test.ts b/packages/app-tests/aiCliErrorI18n.test.ts
new file mode 100644
index 0000000000..1ed3ced728
--- /dev/null
+++ b/packages/app-tests/aiCliErrorI18n.test.ts
@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import type { ComposerTranslation } from "vue-i18n";
+import { translateBackendError } from "../../apps/desktop/src/i18n/backend-errors";
+import en from "../../apps/desktop/src/i18n/locales/en";
+import es from "../../apps/desktop/src/i18n/locales/es";
+import it from "../../apps/desktop/src/i18n/locales/it";
+import ja from "../../apps/desktop/src/i18n/locales/ja";
+import ptBR from "../../apps/desktop/src/i18n/locales/pt-BR";
+import zhCN from "../../apps/desktop/src/i18n/locales/zh-CN";
+import zhTW from "../../apps/desktop/src/i18n/locales/zh-TW";
+
+const errorCodes = ["claudeCodeNotInstalled", "claudeCodeCliPathInvalid", "claudeCodeEnvInvalid", "claudeCodeEnvReserved", "claudeCodeNotAuthenticated", "claudeCodeMcpConfigInvalid", "dbxMcpMissing", "claudeCodeMcpStartupFailed", "claudeCodeCommandLineTooLong", "claudeCodeRunFailed"] as const;
+
+test("Claude Code CLI errors are localized while retaining their stable code and raw diagnostics", () => {
+  const messages: Record<string, string> = {
+    "ai.cliErrors.claudeCodeMcpConfigInvalid": "Claude MCP config could not be parsed.",
+    "ai.cliErrors.code": "Error code: {code}",
+    "ai.cliErrors.reportHint": "Include this information in the report.",
+    "ai.cliErrors.details": "Diagnostic details:",
+  };
+  const t = ((key: string, params?: Record<string, string>) => {
+    let value = messages[key] ?? key;
+    for (const [name, replacement] of Object.entries(params ?? {})) value = value.replace(`{${name}}`, replacement);
+    return value;
+  }) as ComposerTranslation;
+  const raw = "Invalid MCP configuration: MCP config file not found: C:\\Temp\\mcp.json";
+
+  const translated = translateBackendError(t, `[claudeCodeMcpConfigInvalid] ${raw}`);
+
+  assert.match(translated, /Claude MCP config could not be parsed/);
+  assert.match(translated, /Error code: claudeCodeMcpConfigInvalid/);
+  assert.match(translated, /Include this information in the report/);
+  assert.match(translated, /Diagnostic details:/);
+  assert.match(translated, /C:\\Temp\\mcp\.json/);
+});
+
+test("every current locale defines all Claude Code CLI diagnostic messages", () => {
+  const locales = { en, es, it, ja, ptBR, zhCN, zhTW } as const;
+
+  for (const [localeName, locale] of Object.entries(locales)) {
+    assert.equal(typeof locale.ai.requestFailed, "string", `${localeName}.ai.requestFailed`);
+    assert.equal(typeof locale.ai.cliErrors.code, "string", `${localeName}.ai.cliErrors.code`);
+    assert.equal(typeof locale.ai.cliErrors.details, "string", `${localeName}.ai.cliErrors.details`);
+    assert.equal(typeof locale.ai.cliErrors.reportHint, "string", `${localeName}.ai.cliErrors.reportHint`);
+    for (const code of errorCodes) {
+      assert.equal(typeof locale.ai.cliErrors[code], "string", `${localeName}.ai.cliErrors.${code}`);
+      assert.ok(locale.ai.cliErrors[code].trim().length > 0, `${localeName}.ai.cliErrors.${code} should not be empty`);
+    }
+  }
+});
diff --git a/packages/app-tests/aiMessageLayout.test.ts b/packages/app-tests/aiMessageLayout.test.ts
index a60a7aab3b..8e5251a3d4 100644
--- a/packages/app-tests/aiMessageLayout.test.ts
+++ b/packages/app-tests/aiMessageLayout.test.ts
@@ -15,6 +15,15 @@ function userMessageTemplate(): string {
   return source.slice(start, end);
 }
 
+function assistantMessageTemplate(): string {
+  const start = source.indexOf(`<div v-else-if="msg.content || msg.reasoning || msg.isThinking"`);
+  const end = source.indexOf(`</template>`, start);
+
+  assert.notEqual(start, -1, "assistant message template should exist");
+  assert.notEqual(end, -1, "assistant message template should end before the message loop");
+  return source.slice(start, end);
+}
+
 test("AI assistant template compiles", () => {
   const { descriptor, errors } = parse(source, { filename: aiAssistantPath });
   assert.deepEqual(errors, []);
@@ -42,3 +51,13 @@ test("user message edit action remains available by pointer and keyboard", () =>
   assert.match(template, /:title="t\('ai\.editMessage'\)"[\s\S]*?@click="startEditMessage\(i\)"/);
   assert.match(template, /v-if="!isGenerating"/);
 });
+
+test("assistant messages wrap long paths and continuous error text inside the bubble", () => {
+  const template = assistantMessageTemplate();
+
+  assert.match(template, /max-w-\[95%\][^"\n]*\[overflow-wrap:anywhere\]/);
+});
+
+test("AI request failures use localized backend diagnostics", () => {
+  assert.match(source, /messages\.value\[assistantIdx\]\.content = `\$\{t\("ai\.requestFailed"\)\}\\n\\n\$\{translateBackendError\(t, message\)\}`/);
+});
diff --git a/src-tauri/src/commands/mcp.rs b/src-tauri/src/commands/mcp.rs
index 9d45423ce8..c364deb96e 100644
--- a/src-tauri/src/commands/mcp.rs
+++ b/src-tauri/src/commands/mcp.rs
@@ -261,7 +261,7 @@ fn resolve_managed_mcp_command(
 fn require_managed_mcp_command(command: Option<(String, Vec<String>)>) -> Result<(String, Vec<String>), String> {
     command.ok_or_else(|| {
         format!(
-            "DBX MCP Server is unavailable: no compatible Node.js ({}) installation containing {} was found. Install MCP Server from DBX settings and try again.",
+            "[dbxMcpMissing] No compatible Node.js ({}) installation containing {} was found.",
             MCP_MIN_NODE_VERSION_REQUIREMENT, MCP_PACKAGE_NAME
         )
     })
@@ -1137,7 +1137,7 @@ mod tests {
 
         assert!(error.contains(MCP_MIN_NODE_VERSION_REQUIREMENT));
         assert!(error.contains(MCP_PACKAGE_NAME));
-        assert!(error.contains("DBX settings"));
+        assert!(error.starts_with("[dbxMcpMissing]"));
     }
 
     #[test]