@i18n-agent/mcp-client 1.1.2 → 1.4.0

package/README.md

@@ -69,6 +69,11 @@ Check my translation credits
 List supported languages with quality ratings
 ```
 
+### Content Analysis
+```
+Analyze content for translation readiness and get improvement suggestions
+```
+
 ## 🛠 Supported AI IDEs
 
 | IDE | Status | Config Location |
@@ -79,8 +84,6 @@ List supported languages with quality ratings
 | **Other MCP IDEs** | 🔧 Manual setup | Varies |
 
 ## 🌐 Language Support
-
-### Tier 1 - Excellent Quality
 - **en**: English
 - **fr**: French
 - **de**: German
@@ -91,8 +94,6 @@ List supported languages with quality ratings
 - **ja**: Japanese
 - **ko**: Korean
 - **zh-CN**: Chinese (Simplified)
-
-### Tier 2 - High Quality
 - **nl**: Dutch
 - **pl**: Polish
 - **cs**: Czech
@@ -104,8 +105,6 @@ List supported languages with quality ratings
 - **da**: Danish
 - **no**: Norwegian
 - **fi**: Finnish
-
-### Tier 3 - Good Quality
 - **tr**: Turkish
 - **hu**: Hungarian
 - **th**: Thai
@@ -216,6 +215,50 @@ ls ~/.cursor/
 ls ~/.vscode/
 ```
 
+### MCP Connection Issues
+
+**"Failed" status in Claude Code:**
+
+This usually happens with Node Version Managers (nvm, fnm, n). The installer now automatically detects nvm and creates a wrapper script. If you still have issues:
+
+1. **Check your Node installation:**
+   ```bash
+   which node
+   # If output contains .nvm, you're using nvm
+   ```
+
+2. **Manual wrapper script (if auto-detection fails):**
+   Create `~/.claude/run-mcp.sh`:
+   ```bash
+   #!/bin/bash
+   export PATH="$(dirname $(which node)):$PATH"
+   cd ~/.claude
+   exec node node_modules/@i18n-agent/mcp-client/mcp-client.js
+   ```
+   
+   Make it executable:
+   ```bash
+   chmod +x ~/.claude/run-mcp.sh
+   ```
+   
+3. **Update Claude configuration:**
+   Edit `~/.claude.json`:
+   ```json
+   {
+     "mcpServers": {
+       "i18n-agent": {
+         "command": "/Users/YOUR_USERNAME/.claude/run-mcp.sh",
+         "env": {
+           "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
+           "API_KEY": "your-api-key"
+         }
+       }
+     }
+   }
+   ```
+
+4. **Restart Claude Code completely** (not just close window, quit the app)
+
 ### Runtime Issues
 
 **API Key not found:**
@@ -277,10 +320,71 @@ Copyright (c) 2025 FatCouple OÜ
 
 ## 🆘 Support
 
-- **Discord**: [Join our community](https://discord.gg/i18nagent)
 - **Email**: support@i18nagent.ai
 - **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)
 
+## 🔧 Available MCP Tools
+
+### translate_text
+Translate text content with cultural adaptation and context awareness.
+
+**Parameters:**
+- `texts` (array): Array of strings to translate
+- `targetLanguage` (string): Target language code
+- `targetAudience` (string): Target audience context
+- `industry` (string): Industry context
+- `sourceLanguage` (string, optional): Source language (auto-detected if not provided)
+- `region` (string, optional): Specific region for localization
+
+### translate_file
+Translate files while preserving structure and format.
+
+**Parameters:**
+- `filePath` or `fileContent` (string): File path or content to translate
+- `fileType` (string): File format (json, yaml, xml, csv, txt, md, etc.)
+- `targetLanguage` (string): Target language code
+- `preserveKeys` (boolean): Whether to preserve object keys/structure
+- `outputFormat` (string): Output format (same, json, yaml, txt)
+
+### analyze_content
+Analyze content for translation readiness and get improvement suggestions before translation.
+
+**Parameters:**
+- `content` (string/array/object): Content to analyze
+- `targetLanguage` (string): Target language for translation
+- `fileType` (string, optional): File type if content is from a file
+- `sourceLanguage` (string, optional): Source language (auto-detected)
+- `industry` (string): Industry context
+- `targetAudience` (string): Target audience
+- `region` (string, optional): Specific region for localization
+
+**Returns:**
+- Source language detection with confidence score
+- Content type and tone analysis
+- Translation readiness score (0-100)
+- Specific improvement suggestions
+- Quality metrics and issues
+- Warnings for potential problems
+- Estimated credits required
+
+### list_supported_languages
+Get list of all supported languages with quality ratings.
+
+**Parameters:**
+- `includeQuality` (boolean): Include quality ratings (default: true)
+
+### get_credits
+Check remaining translation credits and word count estimates.
+
+**Parameters:**
+- `apiKey` (string): Your API key
+
+### check_translation_status
+Check status of async translation jobs (for large files).
+
+**Parameters:**
+- `jobId` (string): Job ID from async translation
+
 ---
 
 Made with ❤️ by [FatCouple OÜ](https://fireinbelly.com)

package/install.js

@@ -74,6 +74,45 @@ function createMCPConfig() {
   };
 }
 
+function detectNodeEnvironment() {
+  // Check if using nvm or other version managers
+  const nvmDir = process.env.NVM_DIR || path.join(os.homedir(), '.nvm');
+  const nodeVersion = process.version;
+  const nodePath = process.execPath;
+  
+  return {
+    isNvm: nodePath.includes('.nvm') || nodePath.includes('nvm'),
+    nodePath,
+    nodeVersion
+  };
+}
+
+function createWrapperScript(targetDir) {
+  const nodeEnv = detectNodeEnvironment();
+  const wrapperPath = path.join(targetDir, 'run-mcp.sh');
+  const mcpClientPath = path.join(targetDir, 'node_modules', '@i18n-agent', 'mcp-client', 'mcp-client.js');
+  
+  let wrapperContent;
+  
+  if (nodeEnv.isNvm) {
+    // For nvm users, we need to set up the PATH properly
+    wrapperContent = `#!/bin/bash
+# Wrapper script for i18n-agent MCP client (handles nvm environments)
+export PATH="${path.dirname(nodeEnv.nodePath)}:$PATH"
+cd "${targetDir}"
+exec node "${mcpClientPath}"`;
+  } else {
+    // For system node installations
+    wrapperContent = `#!/bin/bash
+# Wrapper script for i18n-agent MCP client
+cd "${targetDir}"
+exec node "${mcpClientPath}"`;
+  }
+  
+  fs.writeFileSync(wrapperPath, wrapperContent, { mode: 0o755 });
+  return wrapperPath;
+}
+
 function updateClaudeConfig(configPath) {
   let config = {};
   
@@ -92,16 +131,36 @@ function updateClaudeConfig(configPath) {
     config.mcpServers = {};
   }
   
-  // Add i18n-agent configuration
-  const mcpClientPath = path.resolve(__dirname, 'mcp-client.js');
-  config.mcpServers["i18n-agent"] = {
-    command: "node",
-    args: [mcpClientPath],
-    env: {
-      MCP_SERVER_URL: "https://mcp.i18nagent.ai",
-      API_KEY: ""
-    }
-  };
+  // Detect if we need a wrapper script (for nvm users)
+  const nodeEnv = detectNodeEnvironment();
+  const claudeDir = path.join(os.homedir(), '.claude');
+  
+  if (nodeEnv.isNvm) {
+    // Create wrapper script for nvm users
+    console.log('   🔧 Detected nvm environment, creating wrapper script...');
+    const wrapperPath = createWrapperScript(claudeDir);
+    
+    config.mcpServers["i18n-agent"] = {
+      command: wrapperPath,
+      env: {
+        MCP_SERVER_URL: "https://mcp.i18nagent.ai",
+        API_KEY: ""
+      }
+    };
+  } else {
+    // Standard configuration for system node
+    const mcpClientPath = path.join(claudeDir, 'node_modules', '@i18n-agent', 'mcp-client', 'mcp-client.js');
+    
+    config.mcpServers["i18n-agent"] = {
+      command: "node",
+      args: [mcpClientPath],
+      cwd: claudeDir,
+      env: {
+        MCP_SERVER_URL: "https://mcp.i18nagent.ai",
+        API_KEY: ""
+      }
+    };
+  }
   
   // Write updated config
   fs.mkdirSync(path.dirname(configPath), { recursive: true });

package/mcp-client.js

@@ -5,6 +5,8 @@
  * Integrates with Claude Code CLI to provide translation capabilities
  */
 
+const MCP_CLIENT_VERSION = '1.3.0';
+
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
@@ -17,8 +19,6 @@ import axios from 'axios';
 import fs from 'fs';
 import path from 'path';
 
-const MCP_CLIENT_VERSION = '1.1.2';
-
 const server = new Server(
   {
     name: 'i18n-agent',
@@ -47,44 +47,41 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: 'translate_text',
-        description: 'Translate text from one language to another with cultural context',
+        description: 'Translate text content with cultural adaptation using AI subagents. For large requests (>100 texts or >50,000 characters), returns a jobId for async processing. Use check_translation_status to monitor progress and download results.',
         inputSchema: {
           type: 'object',
           properties: {
             texts: {
               type: 'array',
               items: { type: 'string' },
-              description: 'Array of texts to translate',
+              description: 'Array of source texts to translate (any language)',
             },
             targetLanguage: {
               type: 'string',
-              description: 'Target language code (e.g., "es", "fr", "ja", "de") or full name (e.g., "Spanish", "French")',
+              description: 'Target language code (e.g., "es", "fr", "zh-CN")',
             },
             sourceLanguage: {
               type: 'string',
-              description: 'Source language code (optional, auto-detected if not provided)',
-              default: 'auto',
+              description: 'Source language code (auto-detected if not provided)',
             },
             targetAudience: {
               type: 'string',
-              description: 'Target audience (e.g., "general", "technical", "casual", "formal")',
-              default: 'general',
+              description: 'Target audience for the content (e.g., "software developers", "marketing professionals")',
             },
             industry: {
               type: 'string',
-              description: 'Industry context (e.g., "technology", "healthcare", "finance", "education")',
-              default: 'technology',
+              description: 'Industry context (e.g., "technology", "healthcare", "finance")',
             },
             region: {
               type: 'string',
               description: 'Specific region for localization (e.g., "Spain", "Mexico", "Brazil")',
             },
-            notes: {
+            context: {
               type: 'string',
               description: 'Optional additional context or instructions for the translation (e.g., "Keep technical terms in English", "Use formal tone")',
             },
           },
-          required: ['texts', 'targetLanguage'],
+          required: ['texts', 'targetLanguage', 'targetAudience', 'industry'],
         },
       },
       {
@@ -103,7 +100,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'translate_file',
-        description: 'Translate file content while preserving structure and format. Supports JSON, YAML, XML, CSV, TXT, MD, and other text files',
+        description: 'Translate file content while preserving structure and format. Supports JSON, YAML, XML, CSV, TXT, MD, and other text files. For large files (>100KB), returns a jobId for async processing. Use check_translation_status to monitor progress and download results.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -153,7 +150,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Specific region for localization (e.g., "Spain", "Mexico", "Brazil")',
             },
-            notes: {
+            context: {
               type: 'string',
               description: 'Optional additional context or instructions for the translation (e.g., "Keep technical terms in English", "Use formal tone")',
             },
@@ -166,10 +163,55 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         description: 'Get remaining credits for the user and approximate word count available at 0.001 credits per word',
         inputSchema: {
           type: 'object',
-          properties: {},
+          properties: {
+            apiKey: {
+              type: 'string',
+              description: 'API key to get credits for (optional, will use environment variable if not provided)',
+            },
+          },
           required: [],
         },
       },
+      /*
+       * ====================================================================
+       * TOKEN USAGE TOOLS - RESTRICTED FROM MCP CLIENT ACCESS
+       * ====================================================================
+       * 
+       * HARD LIMIT POLICY: Token usage analytics tools are NOT available 
+       * through MCP client interfaces for security and privacy reasons.
+       * 
+       * Restricted Tools:
+       * - get_token_usage_stats
+       * - get_token_usage_by_translation  
+       * - get_token_usage_by_api_key
+       * 
+       * These tools contain sensitive usage data and billing information
+       * that should only be accessible through authenticated web interfaces,
+       * not through programmatic MCP access.
+       * 
+       * If you need token usage data, please use:
+       * - Web dashboard at https://app.i18nagent.ai
+       * - Direct API calls with proper authentication
+       * - Admin interfaces (for internal use only)
+       * 
+       * This restriction is enforced at the service level and cannot be
+       * bypassed through client modifications.
+       * ====================================================================
+       */
+      {
+        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.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            jobId: {
+              type: 'string',
+              description: 'The job ID returned from translate_text (>100 texts or >50,000 chars) or translate_file (>100KB) for async processing',
+            },
+          },
+          required: ['jobId'],
+        },
+      },
     ],
   };
 });
@@ -192,6 +234,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_credits':
         return await handleGetCredits(args);
       
+      /*
+       * TOKEN USAGE TOOLS - BLOCKED FOR SECURITY
+       * These cases are intentionally removed to prevent access to sensitive analytics data
+       * through MCP interfaces. See tool definition comments above for details.
+       */
+      
+      case 'check_translation_status':
+        return await handleCheckTranslationStatus(args);
+      
       default:
         throw new McpError(
           ErrorCode.MethodNotFound,
@@ -200,15 +251,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
   } catch (error) {
     console.error(`Error executing tool ${name}:`, error);
+    
+    // Check if error is about API key or credit issues
+    const errorMsg = error.message || '';
+    const isAuthError = errorMsg.toLowerCase().includes('api key') || 
+                       errorMsg.toLowerCase().includes('api_key') ||
+                       errorMsg.toLowerCase().includes('unauthorized') ||
+                       errorMsg.includes('(401)');
+    const isCreditError = errorMsg.toLowerCase().includes('credit') || 
+                         errorMsg.toLowerCase().includes('quota') ||
+                         errorMsg.toLowerCase().includes('limit exceeded') ||
+                         errorMsg.includes('(402)');
+    
+    let finalErrorMsg = error.message;
+    
+    // Add retry guidance for non-auth/credit errors
+    if (!isAuthError && !isCreditError) {
+      finalErrorMsg = `${error.message}. Please retry with smaller chunks or split the content into multiple requests.`;
+    }
+    
     throw new McpError(
       ErrorCode.InternalError,
-      `Tool execution failed: ${error.message}`
+      `Tool execution failed: ${finalErrorMsg}`
     );
   }
 });
 
 async function handleTranslateText(args) {
-  const { texts, targetLanguage, sourceLanguage, targetAudience = 'general', industry = 'technology', region, notes } = args;
+  const { texts, targetLanguage, sourceLanguage, targetAudience = 'general', industry = 'technology', region, context } = args;
   
   if (!texts || !Array.isArray(texts) || texts.length === 0) {
     throw new Error('texts must be a non-empty array');
@@ -217,18 +287,26 @@ async function handleTranslateText(args) {
   if (!targetLanguage) {
     throw new Error('targetLanguage is required');
   }
+  
+  if (!targetAudience) {
+    throw new Error('targetAudience is required');
+  }
+  
+  if (!industry) {
+    throw new Error('industry is required');
+  }
 
   // Check if this is a large translation request
   const totalChars = texts.reduce((sum, text) => sum + text.length, 0);
   const isLargeRequest = texts.length > 100 || totalChars > 50000;
 
-  // Use MCP JSON-RPC protocol for translate_content
+  // Use MCP JSON-RPC protocol for translate_text
   const mcpRequest = {
     jsonrpc: '2.0',
     id: Date.now(),
     method: 'tools/call',
     params: {
-      name: 'translate_content',
+      name: 'translate_text',
       arguments: {
         apiKey: API_KEY,
         texts: texts,
@@ -237,13 +315,12 @@ async function handleTranslateText(args) {
         targetAudience: targetAudience,
         industry: industry,
         region: region,
-        notes: notes,
+        context: context,
       }
     }
   };
 
   try {
-    console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text] Request: ${texts.length} texts, ${totalChars} chars to ${MCP_SERVER_URL}`);
     const response = await axios.post(MCP_SERVER_URL, mcpRequest, {
       headers: {
         'Content-Type': 'application/json',
@@ -252,7 +329,19 @@ async function handleTranslateText(args) {
     });
 
     if (response.data.error) {
-      throw new Error(`Translation service error: ${response.data.error.message || response.data.error}`);
+      const errorMsg = response.data.error.message || response.data.error;
+      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') || 
+                           errorMsg.toString().toLowerCase().includes('quota') ||
+                           errorMsg.toString().toLowerCase().includes('limit exceeded');
+      
+      let finalErrorMsg = `Translation service error: ${errorMsg}`;
+      if (!isAuthError && !isCreditError) {
+        finalErrorMsg += `. Please retry with a smaller text chunk or split the content into multiple smaller requests.`;
+      }
+      throw new Error(finalErrorMsg);
     }
 
     // Check if we got an async job response
@@ -308,103 +397,167 @@ async function handleTranslateText(args) {
       };
     }
     
-    // Check for payment required error
+    // Handle 401 unauthorized - invalid API key
+    if (error.response?.status === 401) {
+      const authErrorDetails = error.response.data?.message || error.response.data?.result?.content?.[0]?.text || error.message;
+      throw new Error(`❌ Invalid API key (401)\nDetails: ${authErrorDetails}\nPlease check your API key at https://app.i18nagent.ai\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text]`);
+    }
+    
+    // Handle 402 payment required with user-friendly message
     if (error.response?.status === 402) {
-      console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text] Payment required (402)`);
-      throw new Error(`⚠️ Insufficient credits. Please top up at https://app.i18nagent.ai [MCP v${MCP_CLIENT_VERSION}/STDIO]`);
+      const creditErrorDetails = error.response.data?.message || error.response.data?.result?.content?.[0]?.text || error.message;
+      throw new Error(`⚠️ Insufficient credits (402)\nDetails: ${creditErrorDetails}\nPlease top up at https://app.i18nagent.ai\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text]`);
+    }
+    
+    // Check if it's a large content issue
+    const totalChars = texts.reduce((sum, text) => sum + text.length, 0);
+    if (error.response?.status === 413 || 
+        (error.response?.status === 503 && totalChars > 50000)) {
+      const sizeErrorDetails = error.response?.data?.message || error.response?.data?.result?.content?.[0]?.text || error.message;
+      const errorMsg = `Content too large (${totalChars} characters, ${texts.length} texts)\nStatus: ${error.response?.status}\nDetails: ${sizeErrorDetails}\n\nPlease break into smaller batches:\n• Split into batches of 50-100 texts\n• Keep total size under 50KB per request\n• Process sequentially to avoid overload\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text]`;
+      throw new Error(errorMsg);
     }
     
-    // Check if it's actually a service unavailable error (503, timeout, connection issues)
+    // Check if it's actually a service unavailable error (only for real infrastructure issues)
     if (error.code === 'ECONNREFUSED' || 
         error.code === 'ETIMEDOUT' || 
-        error.response?.status === 503 ||
+        error.code === 'ENOTFOUND' ||
+        (error.response?.status === 503 && totalChars <= 50000) ||
         error.response?.status === 502 ||
         error.response?.status === 504) {
-      console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text] Infrastructure error:`, {
-        code: error.code,
-        status: error.response?.status,
-        message: error.message,
-        url: MCP_SERVER_URL
-      });
-      throw new Error(`Translation service unavailable [MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text]: ${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 (401, 404, etc), add context but don't mark as unavailable
-    console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_text] Error:`, error.message);
-    throw error;
+    // 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 || 
+                               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]`);
   }
 }
 
 async function handleListLanguages(args) {
   const { includeQuality = true } = args;
   
-  // Language support matrix based on GPT-OSS analysis
-  const languages = {
-    'Tier 1 - Production Ready (Excellent Quality 80-90%)': {
-      'en': 'English',
-      'es': 'Spanish', 
-      'fr': 'French',
-      'de': 'German',
-      'it': 'Italian',
-      'pt': 'Portuguese',
-      'nl': 'Dutch',
-    },
-    'Tier 2 - Production Viable (Good Quality 50-75%)': {
-      'ru': 'Russian',
-      'zh-CN': 'Chinese (Simplified)',
-      'ja': 'Japanese',
-      'ko': 'Korean',
-      'ar': 'Arabic',
-      'he': 'Hebrew',
-      'hi': 'Hindi',
-      'pl': 'Polish',
-      'cs': 'Czech',
-    },
-    'Tier 3 - Basic Support (Use with Caution 20-50%)': {
-      'zh-TW': 'Chinese (Traditional)',
-      'th': 'Thai',
-      'vi': 'Vietnamese',
-      'sv': 'Swedish',
-      'da': 'Danish',
-      'no': 'Norwegian',
-      'fi': 'Finnish',
-      'tr': 'Turkish',
-      'hu': 'Hungarian',
-    },
+  // Use MCP JSON-RPC protocol for list_supported_languages
+  const mcpRequest = {
+    jsonrpc: '2.0',
+    id: Date.now(),
+    method: 'tools/call',
+    params: {
+      name: 'list_supported_languages',
+      arguments: { includeQuality }
+    }
   };
-
-  let content = '🌍 Supported Languages\n';
-  content += '===================\n\n';
   
-  if (includeQuality) {
-    for (const [tier, langs] of Object.entries(languages)) {
-      content += `## ${tier}\n`;
-      for (const [code, name] of Object.entries(langs)) {
-        content += `- \`${code}\`: ${name}\n`;
-      }
-      content += '\n';
+  try {
+    const response = await axios.post(MCP_SERVER_URL, mcpRequest, {
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      timeout: 30000,
+    });
+
+    if (response.data.error) {
+      const errorMsg = response.data.error.message || response.data.error;
+      throw new Error(`Languages service error: ${errorMsg}`);
     }
-  } else {
-    const allLanguages = Object.values(languages).reduce((acc, tier) => ({ ...acc, ...tier }), {});
-    for (const [code, name] of Object.entries(allLanguages)) {
-      content += `- \`${code}\`: ${name}\n`;
+
+    const result = response.data.result;
+    if (result && result.content && result.content[0]) {
+      const textContent = result.content[0].text;
+      
+      // Try to parse as JSON for structured data
+      try {
+        const parsed = JSON.parse(textContent);
+        
+        // Format the language data nicely
+        let content = '🌍 Supported Languages\n';
+        content += '===================\n\n';
+        
+        if (parsed.languages && Array.isArray(parsed.languages)) {
+          if (includeQuality) {
+            // Group by quality levels
+            const highQuality = parsed.languages.filter(lang => lang.quality === 'high');
+            const mediumQuality = parsed.languages.filter(lang => lang.quality === 'medium');
+            
+            if (highQuality.length > 0) {
+              content += '## High Quality (Recommended for Production)\n';
+              highQuality.forEach(lang => {
+                content += `- \`${lang.code}\`: ${lang.name}\n`;
+              });
+              content += '\n';
+            }
+            
+            if (mediumQuality.length > 0) {
+              content += '## Medium Quality (Good with Review)\n';
+              mediumQuality.forEach(lang => {
+                content += `- \`${lang.code}\`: ${lang.name}\n`;
+              });
+              content += '\n';
+            }
+          } else {
+            parsed.languages.forEach(lang => {
+              content += `- \`${lang.code}\`: ${lang.name}\n`;
+            });
+            content += '\n';
+          }
+          
+          content += `📊 **Total Languages**: ${parsed.total || parsed.languages.length}\n\n`;
+          
+          if (parsed.qualityLevels) {
+            content += `Quality Breakdown:\n`;
+            content += `• High Quality: ${parsed.qualityLevels.high} languages\n`;
+            content += `• Medium Quality: ${parsed.qualityLevels.medium} languages\n\n`;
+          }
+        }
+        
+        content += '💡 Usage Tips:\n';
+        content += '- Use language codes (e.g., "es") or full names (e.g., "Spanish")\n';
+        content += '- High quality languages are recommended for production use\n';
+        content += '- Medium quality languages work well with human review\n';
+        
+        return {
+          content: [
+            {
+              type: 'text',
+              text: content,
+            },
+          ],
+        };
+      } catch {
+        // Return raw text if not JSON
+        return result;
+      }
     }
+    
+    return result;
+  } catch (error) {
+    console.error('List languages error:', error);
+    
+    // Fallback to basic language list if service is unavailable
+    const fallbackContent = `🌍 Supported Languages (Fallback)\n` +
+      `==================================\n\n` +
+      `Service temporarily unavailable. Here are the main supported languages:\n\n` +
+      `• \`es\`: Spanish\n• \`fr\`: French\n• \`de\`: German\n• \`it\`: Italian\n` +
+      `• \`pt\`: Portuguese\n• \`ja\`: Japanese\n• \`ko\`: Korean\n• \`zh\`: Chinese\n` +
+      `• \`ru\`: Russian\n• \`ar\`: Arabic\n• \`hi\`: Hindi\n• \`nl\`: Dutch\n\n` +
+      `Error: ${error.message}`;
+    
+    return {
+      content: [
+        {
+          type: 'text',
+          text: fallbackContent,
+        },
+      ],
+    };
   }
-
-  content += '\n💡 Usage Tips:\n';
-  content += '- Use language codes (e.g., "es") or full names (e.g., "Spanish")\n';
-  content += '- Tier 1 languages are recommended for production use\n';
-  content += '- Tier 2 languages work well with human review\n';
-  content += '- Tier 3 languages provide basic translation quality\n';
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: content,
-      },
-    ],
-  };
 }
 
 async function handleTranslateFile(args) {
@@ -419,7 +572,7 @@ async function handleTranslateFile(args) {
     outputFormat = 'same',
     sourceLanguage,
     region,
-    notes
+    context
   } = args;
   
   if (!filePath && !fileContent) {
@@ -461,7 +614,7 @@ async function handleTranslateFile(args) {
         targetAudience,
         industry,
         region,
-        notes,
+        context,
         preserveKeys,
         outputFormat
       }
@@ -469,7 +622,6 @@ async function handleTranslateFile(args) {
   };
 
   try {
-    console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file] Request: ${content?.length || 0} chars to ${MCP_SERVER_URL}`);
     const response = await axios.post(MCP_SERVER_URL, mcpRequest, {
       headers: {
         'Content-Type': 'application/json',
@@ -478,7 +630,19 @@ async function handleTranslateFile(args) {
     });
 
     if (response.data.error) {
-      throw new Error(`Translation service error: ${response.data.error.message || response.data.error}`);
+      const errorMsg = response.data.error.message || response.data.error;
+      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') || 
+                           errorMsg.toString().toLowerCase().includes('quota') ||
+                           errorMsg.toString().toLowerCase().includes('limit exceeded');
+      
+      let finalErrorMsg = `Translation service error: ${errorMsg}`;
+      if (!isAuthError && !isCreditError) {
+        finalErrorMsg += `. Please retry with a smaller text chunk or split the content into multiple smaller requests.`;
+      }
+      throw new Error(finalErrorMsg);
     }
 
     // Check if we got an async job response
@@ -502,6 +666,8 @@ async function handleTranslateFile(args) {
     return result;
     
   } catch (error) {
+    // Debug info will be included in error messages for visibility
+    
     if (error.code === 'ECONNABORTED') {
       return {
         content: [
@@ -524,30 +690,50 @@ async function handleTranslateFile(args) {
       };
     }
     
-    // Check for payment required error
+    // Handle 401 unauthorized - invalid API key
+    if (error.response?.status === 401) {
+      const fileAuthErrorDetails = error.response.data?.message || error.response.data?.result?.content?.[0]?.text || error.message;
+      throw new Error(`❌ Invalid API key (401)\nDetails: ${fileAuthErrorDetails}\nPlease check your API key at https://app.i18nagent.ai\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file]`);
+    }
+    
+    // Handle 402 payment required with user-friendly message
     if (error.response?.status === 402) {
-      console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file] Payment required (402)`);
-      throw new Error(`⚠️ Insufficient credits. Please top up at https://app.i18nagent.ai [MCP v${MCP_CLIENT_VERSION}/STDIO]`);
+      const fileCreditErrorDetails = error.response.data?.message || error.response.data?.result?.content?.[0]?.text || error.message;
+      throw new Error(`⚠️ Insufficient credits (402)\nDetails: ${fileCreditErrorDetails}\nPlease top up at https://app.i18nagent.ai\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file]`);
     }
     
-    // Check if it's actually a service unavailable error
+    // Check if it's a timeout issue (45-second server timeout) or large file issue
+    const timeoutErrorDetails = error.response?.data?.result?.content?.[0]?.text || 
+                               error.response?.data?.error?.message || 
+                               error.message;
+    
+    if (error.response?.status === 413 || 
+        (error.response?.status === 503 && content.length > 50000) ||
+        (error.response?.status === 503 && timeoutErrorDetails.includes('timeout after 45 seconds'))) {
+      const errorMsg = `File too large or complex (${content.length} characters)\n\nThe server has a 45-second timeout. Your file requires more processing time.\n\nPlease break into smaller chunks:\n• Split files over 50KB into multiple parts\n• Translate sections separately (e.g., split by top-level keys for JSON)\n• Use translate_text for batches of 50-100 strings\n• Each chunk should process in under 45 seconds\n\nAlternatively, wait for async job support (coming soon).\n[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file]`;
+      throw new Error(errorMsg);
+    }
+    
+    // Check if it's actually a service unavailable error (only for real infrastructure issues)
     if (error.code === 'ECONNREFUSED' || 
         error.code === 'ETIMEDOUT' || 
-        error.response?.status === 503 ||
+        error.code === 'ENOTFOUND' ||
+        (error.response?.status === 503 && content.length <= 50000) ||
         error.response?.status === 502 ||
         error.response?.status === 504) {
-      console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file] Infrastructure error:`, {
-        code: error.code,
-        status: error.response?.status,
-        message: error.message,
-        url: MCP_SERVER_URL
-      });
-      throw new Error(`Translation service unavailable [MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file]: ${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, add context but don't mark as unavailable
-    console.error(`[MCP v${MCP_CLIENT_VERSION}/STDIO/translate_file] Error:`, error.message);
-    throw error;
+    // 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 || 
+                              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]`);
   }
 }
 
@@ -599,7 +785,19 @@ async function pollTranslationJob(jobId, estimatedTime) {
       });
       
       if (response.data.error) {
-        throw new Error(`Status check error: ${response.data.error.message || response.data.error}`);
+        const errorMsg = response.data.error.message || response.data.error;
+        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') || 
+                             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;
@@ -609,7 +807,19 @@ async function pollTranslationJob(jobId, estimatedTime) {
         if (status.status === 'completed') {
           return status.result;
         } else if (status.status === 'failed') {
-          throw new Error(`Translation failed: ${status.error}`);
+          const errorMsg = status.error;
+          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') || 
+                               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
@@ -621,43 +831,86 @@ async function pollTranslationJob(jobId, estimatedTime) {
     }
   }
   
-  throw new Error(`Translation job ${jobId} timed out after ${maxPolls * pollInterval / 1000} seconds`);
+  throw new Error(`Translation job ${jobId} timed out after ${maxPolls * pollInterval / 1000} seconds. Please retry with a smaller chunk or split the content into multiple requests.`);
 }
 
 async function handleGetCredits(args) {
+  const { apiKey } = args;
+  const creditsApiKey = apiKey || API_KEY;
+  
+  // Use MCP JSON-RPC protocol for get_credits
+  const mcpRequest = {
+    jsonrpc: '2.0',
+    id: Date.now(),
+    method: 'tools/call',
+    params: {
+      name: 'get_credits',
+      arguments: {
+        apiKey: creditsApiKey
+      }
+    }
+  };
+  
   try {
-    // Get team info first using the API key
-    const teamResponse = await axios.get(`https://platform.i18nagent.ai/api/teams/by-api-key/${API_KEY}`, {
+    const response = await axios.post(MCP_SERVER_URL, mcpRequest, {
       headers: {
-        'Content-Type': 'application/json'
+        'Content-Type': 'application/json',
       },
-      timeout: 10000
+      timeout: 30000,
     });
 
-    if (!teamResponse.data.success) {
-      throw new Error(teamResponse.data.error || 'Failed to get team information');
+    if (response.data.error) {
+      const errorMsg = response.data.error.message || response.data.error;
+      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') || 
+                           errorMsg.toString().toLowerCase().includes('quota') ||
+                           errorMsg.toString().toLowerCase().includes('limit exceeded');
+      
+      let finalErrorMsg = `Credits service error: ${errorMsg}`;
+      if (!isAuthError && !isCreditError) {
+        finalErrorMsg += `. Please check the service status or contact support.`;
+      }
+      throw new Error(finalErrorMsg);
     }
 
-    const teamInfo = teamResponse.data.data;
-    const approximateWordsAvailable = Math.floor(teamInfo.credits * 1000); // 0.001 credits per word
+    const result = response.data.result;
+    if (result && result.content && result.content[0]) {
+      const textContent = result.content[0].text;
+      
+      // Try to parse as JSON for structured data
+      try {
+        const parsed = JSON.parse(textContent);
+        const approximateWordsAvailable = parsed.credits ? Math.floor(parsed.credits * 1000) : 0;
+        
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `💰 **Credits Information**\n\n` +
+                    `💳 **Credits Remaining**: ${parsed.credits || 'N/A'}\n` +
+                    `📝 **Approximate Words Available**: ${approximateWordsAvailable.toLocaleString()}\n` +
+                    `💵 **Cost per Word**: 0.001 credits\n` +
+                    `⏰ **Last Updated**: ${new Date().toLocaleString()}\n\n` +
+                    `Note: Word count is approximate and may vary based on actual content complexity and translation requirements.`,
+            },
+          ],
+        };
+      } catch {
+        // Return raw text if not JSON
+        return result;
+      }
+    }
     
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `💰 **Credits Information**
-
-🏢 **Team**: ${teamInfo.name}
-💳 **Credits Remaining**: ${teamInfo.credits}
-📝 **Approximate Words Available**: ${approximateWordsAvailable.toLocaleString()}
-💵 **Cost per Word**: 0.001 credits
-⏰ **Last Updated**: ${new Date().toLocaleString()}
-
-Note: Word count is approximate and may vary based on actual content complexity and translation requirements.`,
-        },
-      ],
-    };
+    return result;
   } catch (error) {
+    // Handle 401 unauthorized
+    if (error.response?.status === 401) {
+      const creditsAuthErrorDetails = error.response.data?.message || error.response.data?.result?.content?.[0]?.text || error.message;
+      throw new Error(`❌ Invalid API key (401)\nDetails: ${creditsAuthErrorDetails}\nPlease check your API key at https://app.i18nagent.ai\n[MCP v${MCP_CLIENT_VERSION}/STDIO/get_credits]`);
+    }
+    
     console.error('Credits check error:', error);
     throw new Error(`Unable to check credits: ${error.message}`);
   }
@@ -990,6 +1243,72 @@ function getCodeBlockLanguage(fileType) {
   return languageMap[fileType] || 'text';
 }
 
+/*
+ * =====================================================================
+ * TOKEN USAGE HANDLERS - INTENTIONALLY REMOVED FOR SECURITY
+ * =====================================================================
+ * 
+ * The following handler functions have been permanently removed from 
+ * the MCP client to prevent unauthorized access to sensitive analytics:
+ * 
+ * - handleGetTokenUsageStats()
+ * - handleGetTokenUsageByTranslation() 
+ * - handleGetTokenUsageByApiKey()
+ * 
+ * SECURITY RATIONALE:
+ * Token usage data contains sensitive billing and usage information
+ * that should not be accessible through programmatic MCP clients.
+ * This data includes:
+ * - Detailed usage patterns and costs
+ * - API key performance metrics
+ * - Translation volume analytics
+ * - Billing-related information
+ * 
+ * ACCESS ALTERNATIVES:
+ * - Use the web dashboard at https://app.i18nagent.ai
+ * - Contact support for usage reports
+ * - Use admin interfaces (internal only)
+ * 
+ * This restriction is enforced as a hard security boundary and 
+ * cannot be bypassed through client modifications.
+ * =====================================================================
+ */
+
+// Handler for checking translation status
+async function handleCheckTranslationStatus(args) {
+  const { jobId } = args;
+  
+  if (!jobId) {
+    throw new Error('jobId is required');
+  }
+  
+  const mcpRequest = {
+    jsonrpc: '2.0',
+    id: Date.now(),
+    method: 'tools/call',
+    params: {
+      name: 'check_translation_status',
+      arguments: { jobId }
+    }
+  };
+  
+  try {
+    const response = await axios.post(MCP_SERVER_URL, mcpRequest, {
+      headers: { 'Content-Type': 'application/json' },
+      timeout: 30000
+    });
+    
+    if (response.data.error) {
+      throw new Error(`Translation status error: ${response.data.error.message || response.data.error}`);
+    }
+    
+    return response.data.result;
+  } catch (error) {
+    console.error('Check translation status error:', error);
+    throw new Error(`Unable to check translation status: ${error.message}`);
+  }
+}
+
 // Start the server
 async function main() {
   const transport = new StdioServerTransport();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@i18n-agent/mcp-client",
-  "version": "1.1.2",
-  "description": "MCP client for i18n-agent translation service - supports Claude, Cursor, VS Code, and other AI IDEs",
+  "version": "1.4.0",
+  "description": "MCP client for i18n-agent translation service with async job support and enhanced progress tracking - supports Claude, Cursor, VS Code, and other AI IDEs",
   "main": "mcp-client.js",
   "bin": {
     "i18n-agent-install": "install.js"