@i18n-agent/mcp-client 1.9.7 → 1.11.0

package/CONTRIBUTING.md

@@ -34,7 +34,7 @@ npm test
 node install.js
 
 # Test MCP client syntax
-node -c mcp-client.js
+node -c i18n-agent.js
 ```
 
 ## 📝 Types of Contributions
@@ -72,7 +72,7 @@ npm test
 node install.js
 
 # Check for syntax errors
-node -c mcp-client.js
+node -c i18n-agent.js
 node -c install.js
 ```
 

package/README.md

@@ -20,7 +20,7 @@ Professional translation service client for Claude, Cursor, VS Code, and other A
 
 ```bash
 npm install -g @i18n-agent/mcp-client
-mcp-client
+i18n-agent
 ```
 
 **Note:** Global installation is required due to npm bin naming limitations. The installer will detect all available AI IDEs and configure them automatically.
@@ -156,7 +156,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "i18n-agent": {
       "command": "node",
-      "args": ["/path/to/mcp-client.js"],
+      "args": ["/path/to/i18n-agent.js"],
       "env": {
         "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
         "API_KEY": "your-api-key-here"
@@ -174,7 +174,7 @@ Create `.cursor/mcp_settings.json` or `.vscode/mcp_settings.json`:
   "mcpServers": {
     "i18n-agent": {
       "command": "node", 
-      "args": ["/path/to/mcp-client.js"],
+      "args": ["/path/to/i18n-agent.js"],
       "env": {
         "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
         "API_KEY": "your-api-key-here"
@@ -252,7 +252,7 @@ This usually happens with Node Version Managers (nvm, fnm, n). The installer now
    #!/bin/bash
    export PATH="$(dirname $(which node)):$PATH"
    cd ~/.claude
-   exec node node_modules/@i18n-agent/mcp-client/mcp-client.js
+   exec node node_modules/@i18n-agent/mcp-client/i18n-agent.js
    ```
    
    Make it executable:

package/{mcp-client.js → i18n-agent.js}

@@ -5,7 +5,7 @@
  * Integrates with Claude Code CLI to provide translation capabilities
  */
 
-const MCP_CLIENT_VERSION = '1.9.7';
+const MCP_CLIENT_VERSION = '1.11.0';
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -43,6 +43,40 @@ if (!process.env.API_KEY) {
 const MCP_SERVER_URL = process.env.MCP_SERVER_URL;
 const API_KEY = process.env.API_KEY;
 
+// Heavy load detection - matches error message from service-mcp error-message-sanitizer
+// Exact message: 'Our system is under heavy load, please resume your job later.'
+const HEAVY_LOAD_PATTERNS = [
+  /Our system is under heavy load/i,
+  /system is under heavy load.*resume.*later/i,
+];
+
+const HEAVY_LOAD_MESSAGE = `⏳ System under heavy load
+
+The translation service is experiencing high demand. Your job has been saved and can be resumed later.
+
+⚠️ IMPORTANT FOR AI AGENTS:
+• Do NOT retry or resume immediately - this will likely fail again
+• Do NOT poll check_translation_status repeatedly
+• Wait at least 5-10 minutes before attempting to resume
+• The job is saved - no data is lost
+
+🔄 To resume later:
+1. Wait for system load to decrease (5-10 minutes minimum)
+2. Use resume_translation with the same jobId
+3. If it fails again, wait longer before retrying
+
+💡 Tip: Inform the user about the delay and let them decide when to retry.`;
+
+/**
+ * Check if an error message indicates heavy system load
+ * @param {string} errorMessage - The error message to check
+ * @returns {boolean} - True if the error indicates heavy load
+ */
+function isHeavyLoadError(errorMessage) {
+  if (!errorMessage) return false;
+  return HEAVY_LOAD_PATTERNS.some(pattern => pattern.test(errorMessage));
+}
+
 // Available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
@@ -326,7 +360,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
        */
       {
         name: 'check_translation_status',
-        description: 'Check the status and progress of an async translation job. Returns progress percentage, elapsed time, and downloads completed translation results when finished. Supports cursor-based pagination for download URLs to reduce token usage when checking jobs with many languages (recommended for jobs with >10 languages). CRITICAL: If a job fails with "quality problems" or any error stating "Retrying might encounter the same problem", do NOT automatically retry. Stop and report the failure to the user. Let them decide the next action - retrying may waste credits on repeated failures.',
+        description: 'Check async translation job status. Returns JSON with: status, progress (0-100%), elapsedTime, completedLanguages, and downloadUrls. IMPORTANT: Always report the progress percentage to the user (e.g., "Translation is 45% complete"). Supports cursor-based pagination for download URLs (recommended for jobs with >10 languages). CRITICAL: If a job fails with "quality problems" or "Retrying might encounter the same problem", do NOT automatically retry - stop and report the failure to the user first.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -689,26 +723,35 @@ async function handleTranslateText(args) {
       throw new Error(errorMsg);
     }
     
+    // Check for heavy load error (from service-mcp error-message-sanitizer)
+    const errorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                        error.response?.data?.error?.message ||
+                        error.response?.data?.message ||
+                        error.message;
+    if (isHeavyLoadError(errorDetails)) {
+      throw new Error(`${HEAVY_LOAD_MESSAGE}\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text]`);
+    }
+
     // Check if it's actually a service unavailable error (only for real infrastructure issues)
     if (error.response?.status === 503) {
       throw new Error(`i18n-agent encountered unexpected problem, and we are working on it, try again later.`);
     }
-    
-    if (error.code === 'ECONNREFUSED' || 
-        error.code === 'ETIMEDOUT' || 
+
+    if (error.code === 'ECONNREFUSED' ||
+        error.code === 'ETIMEDOUT' ||
         error.code === 'ENOTFOUND' ||
         error.response?.status === 502 ||
         error.response?.status === 504) {
-      const serviceErrorDetails = error.response?.data?.result?.content?.[0]?.text || 
-                                  error.response?.data?.error?.message || 
+      const serviceErrorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                                  error.response?.data?.error?.message ||
                                   error.message;
       const debugInfo = `Code: ${error.code || 'N/A'}\nStatus: ${error.response?.status || 'N/A'}\nStatusText: ${error.response?.statusText || 'N/A'}\nDetails: ${serviceErrorDetails}\nURL: ${error.config?.url || 'N/A'}\nTimestamp: ${new Date().toISOString()}`;
       throw new Error(`Translation service error\n${debugInfo}\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text]`);
     }
-    
+
     // For other errors, include all debug info in the error message
-    const generalErrorDetails = error.response?.data?.result?.content?.[0]?.text || 
-                               error.response?.data?.error?.message || 
+    const generalErrorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                               error.response?.data?.error?.message ||
                                error.message;
     const debugInfo = `Status: ${error.response?.status || 'N/A'}\nStatusText: ${error.response?.statusText || 'N/A'}\nDetails: ${generalErrorDetails}\nTimestamp: ${new Date().toISOString()}`;
     throw new Error(`Error\n${debugInfo}\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text]`);
@@ -1046,26 +1089,31 @@ async function handleTranslateFile(args) {
       throw new Error(errorMsg);
     }
     
+    // Check for heavy load error (from service-mcp error-message-sanitizer)
+    if (isHeavyLoadError(timeoutErrorDetails)) {
+      throw new Error(`${HEAVY_LOAD_MESSAGE}\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file]`);
+    }
+
     // Check if it's actually a service unavailable error (only for real infrastructure issues)
     if (error.response?.status === 503 && content.length <= 50000) {
       throw new Error(`i18n-agent encountered unexpected problem, and we are working on it, try again later.`);
     }
-    
-    if (error.code === 'ECONNREFUSED' || 
-        error.code === 'ETIMEDOUT' || 
+
+    if (error.code === 'ECONNREFUSED' ||
+        error.code === 'ETIMEDOUT' ||
         error.code === 'ENOTFOUND' ||
         error.response?.status === 502 ||
         error.response?.status === 504) {
-      const serviceErrorDetails = error.response?.data?.result?.content?.[0]?.text || 
-                                  error.response?.data?.error?.message || 
+      const serviceErrorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                                  error.response?.data?.error?.message ||
                                   error.message;
       const debugInfo = `Code: ${error.code || 'N/A'}\nStatus: ${error.response?.status || 'N/A'}\nStatusText: ${error.response?.statusText || 'N/A'}\nDetails: ${serviceErrorDetails}\nURL: ${error.config?.url || 'N/A'}\nTimestamp: ${new Date().toISOString()}`;
       throw new Error(`Translation service error\n${debugInfo}\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file]`);
     }
-    
+
     // For other errors, include all debug info in the error message
-    const finalErrorDetails = error.response?.data?.result?.content?.[0]?.text || 
-                              error.response?.data?.error?.message || 
+    const finalErrorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                              error.response?.data?.error?.message ||
                               error.message;
     const debugInfo = `Status: ${error.response?.status || 'N/A'}\nStatusText: ${error.response?.statusText || 'N/A'}\nDetails: ${finalErrorDetails}\nTimestamp: ${new Date().toISOString()}`;
     throw new Error(`Error\n${debugInfo}\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file]`);
@@ -1122,48 +1170,64 @@ async function pollTranslationJob(jobId, estimatedTime) {
       
       if (response.data.error) {
         const errorMsg = response.data.error.message || response.data.error;
-        const isAuthError = errorMsg.toString().toLowerCase().includes('api key') || 
+
+        // Check for heavy load error - stop polling immediately
+        if (isHeavyLoadError(errorMsg.toString())) {
+          throw new Error(`${HEAVY_LOAD_MESSAGE}\n\nJob ID: ${jobId}\n[MCP v${MCP_CLIENT_VERSION}/pollTranslationJob]`);
+        }
+
+        const isAuthError = errorMsg.toString().toLowerCase().includes('api key') ||
                            errorMsg.toString().toLowerCase().includes('api_key') ||
                            errorMsg.toString().toLowerCase().includes('unauthorized');
-        const isCreditError = errorMsg.toString().toLowerCase().includes('credit') || 
+        const isCreditError = errorMsg.toString().toLowerCase().includes('credit') ||
                              errorMsg.toString().toLowerCase().includes('quota') ||
                              errorMsg.toString().toLowerCase().includes('limit exceeded');
-        
+
         let finalErrorMsg = `Status check error: ${errorMsg}`;
         if (!isAuthError && !isCreditError) {
           finalErrorMsg += `. Please retry with a smaller chunk or split the content into multiple requests.`;
         }
         throw new Error(finalErrorMsg);
       }
-      
+
       const result = response.data.result;
       if (result && result.content && result.content[0]) {
         const status = JSON.parse(result.content[0].text);
-        
+
         if (status.status === 'completed') {
           return status.result;
         } else if (status.status === 'failed') {
           const errorMsg = status.error;
-          const isAuthError = errorMsg.toString().toLowerCase().includes('api key') || 
+
+          // Check for heavy load error - stop polling immediately
+          if (isHeavyLoadError(errorMsg.toString())) {
+            throw new Error(`${HEAVY_LOAD_MESSAGE}\n\nJob ID: ${jobId}\n[MCP v${MCP_CLIENT_VERSION}/pollTranslationJob]`);
+          }
+
+          const isAuthError = errorMsg.toString().toLowerCase().includes('api key') ||
                              errorMsg.toString().toLowerCase().includes('api_key') ||
                              errorMsg.toString().toLowerCase().includes('unauthorized');
-          const isCreditError = errorMsg.toString().toLowerCase().includes('credit') || 
+          const isCreditError = errorMsg.toString().toLowerCase().includes('credit') ||
                                errorMsg.toString().toLowerCase().includes('quota') ||
                                errorMsg.toString().toLowerCase().includes('limit exceeded');
-          
+
           let finalErrorMsg = `Translation failed: ${errorMsg}`;
           if (!isAuthError && !isCreditError) {
             finalErrorMsg += `. Please retry with a smaller chunk or split the content into multiple requests.`;
           }
           throw new Error(finalErrorMsg);
         }
-        
+
         // Still processing - continue polling
         console.error(`Translation progress: ${status.progress}% (${status.message})`);
       }
     } catch (error) {
+      // Check for heavy load error - stop polling immediately (don't continue)
+      if (isHeavyLoadError(error.message)) {
+        throw error; // Re-throw heavy load error to stop polling
+      }
       console.error(`Error polling job status: ${error.message}`);
-      // Continue polling even if status check fails
+      // Continue polling for other transient errors
     }
   }
   
@@ -1727,6 +1791,17 @@ async function handleCheckTranslationStatus(args) {
   } catch (error) {
     console.error('Check translation status error:', error);
 
+    // Extract error message from various response formats
+    const errorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                        error.response?.data?.error?.message ||
+                        error.response?.data?.message ||
+                        error.message;
+
+    // Check for heavy load error (from service-mcp error-message-sanitizer)
+    if (isHeavyLoadError(errorDetails)) {
+      throw new Error(`${HEAVY_LOAD_MESSAGE}\n\nJob ID: ${jobId}\n[MCP v${MCP_CLIENT_VERSION}/check_translation_status]`);
+    }
+
     // Handle 503 service unavailable
     if (error.response?.status === 503) {
       throw new Error(`i18n-agent encountered unexpected problem, and we are working on it, try again later.`);
@@ -1779,6 +1854,17 @@ async function handleResumeTranslation(args) {
   } catch (error) {
     console.error('Resume translation error:', error);
 
+    // Extract error message from various response formats
+    const errorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                        error.response?.data?.error?.message ||
+                        error.response?.data?.message ||
+                        error.message;
+
+    // Check for heavy load error (from service-mcp error-message-sanitizer)
+    if (isHeavyLoadError(errorDetails)) {
+      throw new Error(`${HEAVY_LOAD_MESSAGE}\n\nJob ID: ${jobId}\n[MCP v${MCP_CLIENT_VERSION}/resume_translation]`);
+    }
+
     // Handle 503 service unavailable
     if (error.response?.status === 503) {
       throw new Error(`i18n-agent encountered unexpected problem, and we are working on it, try again later.`);
@@ -1930,6 +2016,17 @@ async function handleDownloadTranslations(args) {
   } catch (error) {
     console.error('Download translations error:', error);
 
+    // Extract error message from various response formats
+    const errorDetails = error.response?.data?.result?.content?.[0]?.text ||
+                        error.response?.data?.error?.message ||
+                        error.response?.data?.message ||
+                        error.message;
+
+    // Check for heavy load error (from service-mcp error-message-sanitizer)
+    if (isHeavyLoadError(errorDetails)) {
+      throw new Error(`${HEAVY_LOAD_MESSAGE}\n\nJob ID: ${jobId}\n[MCP v${MCP_CLIENT_VERSION}/download_translations]`);
+    }
+
     // Handle 503 service unavailable
     if (error.response?.status === 503) {
       throw new Error(`i18n-agent encountered unexpected problem, and we are working on it, try again later.`);

package/install.js

@@ -83,9 +83,9 @@ Features:
 const getMcpClientPaths = () => {
   // Instead of using ephemeral npx cache, install to stable location
   const stableDir = path.join(os.homedir(), '.claude', 'mcp-servers', 'i18n-agent');
-  const mcpClientPath = path.join(stableDir, 'mcp-client.js');
+  const mcpClientPath = path.join(stableDir, 'i18n-agent.js');
   const packageDir = stableDir;
-  return { mcpClientPath, packageDir, sourceFile: path.resolve(__dirname, 'mcp-client.js') };
+  return { mcpClientPath, packageDir, sourceFile: path.resolve(__dirname, 'i18n-agent.js') };
 };
 
 function copyMcpClientToStableLocation() {
@@ -94,7 +94,7 @@ function copyMcpClientToStableLocation() {
   // Create stable directory
   fs.mkdirSync(paths.packageDir, { recursive: true });
 
-  // Copy mcp-client.js to stable location
+  // Copy i18n-agent.js to stable location
   fs.copyFileSync(paths.sourceFile, paths.mcpClientPath);
 
   // Copy package.json to stable location
@@ -808,7 +808,7 @@ Step 2: Add API key to your IDE`);
           console.log(`
    For Claude Code CLI (recommended):
    claude mcp remove --scope user i18n-agent
-   claude mcp add --transport stdio --scope user i18n-agent -e MCP_SERVER_URL=https://mcp.i18nagent.ai -e API_KEY=your_key_here -- node ~/.claude/mcp-servers/i18n-agent/mcp-client.js
+   claude mcp add --transport stdio --scope user i18n-agent -e MCP_SERVER_URL=https://mcp.i18nagent.ai -e API_KEY=your_key_here -- node ~/.claude/mcp-servers/i18n-agent/i18n-agent.js
 `);
         }
 
@@ -816,7 +816,7 @@ Step 2: Add API key to your IDE`);
           console.log(`
    For Codex CLI (recommended):
    codex mcp remove i18n-agent
-   codex mcp add --env MCP_SERVER_URL=https://mcp.i18nagent.ai --env API_KEY=your_key_here i18n-agent node ~/.claude/mcp-servers/i18n-agent/mcp-client.js
+   codex mcp add --env MCP_SERVER_URL=https://mcp.i18nagent.ai --env API_KEY=your_key_here i18n-agent node ~/.claude/mcp-servers/i18n-agent/i18n-agent.js
 `);
         }
 
@@ -873,7 +873,7 @@ Try these commands in your AI IDE:
 const isMainModule = process.argv[1] && (
   import.meta.url === `file://${process.argv[1]}` ||
   import.meta.url.endsWith(process.argv[1]) ||
-  process.argv[1].includes('mcp-client')
+  process.argv[1].includes('i18n-agent')
 );
 
 if (isMainModule) {

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@i18n-agent/mcp-client",
-  "version": "1.9.7",
+  "version": "1.11.0",
   "description": "🌍 i18n-agent MCP Client - 48 languages, AI-powered translation for Claude, Claude Code, Cursor, VS Code, Codex. Get API key at https://app.i18nagent.ai",
-  "main": "mcp-client.js",
+  "main": "i18n-agent.js",
   "bin": {
-    "mcp-client": "install.js"
+    "i18n-agent": "install.js"
   },
   "type": "module",
   "scripts": {
     "install": "node install.js",
     "test": "node test.js",
-    "postinstall": "echo '\n🌍 i18n-agent MCP Client installed successfully!\n💡 Run: mcp-client (if installed globally) or node install.js\n'"
+    "postinstall": "echo '\n🌍 i18n-agent MCP Client installed successfully!\n💡 Run: i18n-agent (if installed globally) or node install.js\n'"
   },
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
     "node": ">=16.0.0"
   },
   "files": [
-    "mcp-client.js",
+    "i18n-agent.js",
     "namespace-detector.js",
     "install.js",
     "README.md",