{
  "markdown": "# 🌍 i18n-agent MCP Client\n\nProfessional translation service client for Claude, Cursor, VS Code, Antigravity, and other AI IDEs using the Model Context Protocol (MCP).\n\n[![npm version](https://badge.fury.io/js/%40i18n-agent%2Fmcp-client.svg)](https://www.npmjs.com/package/@i18n-agent/mcp-client)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## ✨ Features\n\n- **🎯 Smart Translation**: Context-aware translations with cultural adaptation\n- **📁 File Translation**: Support for JSON, YAML, CSV, XML, Markdown, and more\n- **⚡ Large File Support**: Async processing for files >50KB with progress tracking\n- **🔄 Timeout Improvements**: Extended timeouts (5-10 min) for large translations\n- **📊 Progress Tracking**: Real-time job status and completion monitoring\n- **💰 Credit Tracking**: Real-time credit balance and word count estimates\n- **🌐 48 Languages**: Comprehensive language support with regional variants\n- **🔧 Easy Setup**: One-command installation for major AI IDEs\n\n## 🚀 Quick Installation\n\n```bash\nnpx @i18n-agent/mcp-client install\n```\n\nThe installer will detect all available AI IDEs and configure them automatically.\n\n### Claude Code Marketplace Installation\n\nFor Claude Code users, you can install directly from the marketplace:\n\n**Step 1: Get your API key**\n- Visit [app.i18nagent.ai](https://app.i18nagent.ai)\n- Sign up or log in\n- Copy your API key (starts with \"i18n_\")\n\n**Step 2: Set environment variable**\n```bash\necho 'export I18N_AGENT_API_KEY=your-api-key-here' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nReplace `your-api-key-here` with your actual API key.\n\n**Step 3: Install from marketplace**\n```bash\n/plugin marketplace add i18n-agent/mcp-client\n/plugin install i18n-agent@i18n-agent\n```\n\n**Step 4: Restart Claude Code**\n\nThat's it! The plugin will automatically use your API key from the environment variable.\n\n## 🔑 Setup API Key\n\n1. **Get your API key** from [app.i18nagent.ai](https://app.i18nagent.ai)\n\n2. **Set environment variable**:\n   ```bash\n   export I18N_AGENT_API_KEY=your-api-key-here\n   ```\n\n3. **Make it permanent** (add to ~/.bashrc or ~/.zshrc):\n   ```bash\n   echo 'export I18N_AGENT_API_KEY=your-api-key-here' >> ~/.zshrc\n   ```\n\n4. **Restart your AI IDE** to load the new configuration\n\n## 🎮 Usage Examples\n\n### Text Translation\n```\nTranslate \"Hello, how are you?\" to Spanish for a casual audience\n```\n\n### File Translation\n```\nTranslate this JSON file to French, preserving the structure\n```\n\n### Credit Check\n```\nCheck my translation credits\n```\n\n### Language Support\n```\nList supported languages with quality ratings\n```\n\n### Content Analysis\n```\nAnalyze \"Hello world! This is a test.\" for translation to Spanish\n```\n\n## 🛠 Supported AI IDEs\n\n| IDE | Status | macOS | Windows | Linux |\n|-----|--------|-------|---------|-------|\n| **Claude Desktop** | ✅ Auto-configured | `~/Library/Application Support/Claude/` | `%APPDATA%\\Claude\\` | `~/.config/Claude/` |\n| **Claude Code CLI** | ✅ Auto-configured | `~/.claude.json` | `~/.claude.json` | `~/.claude.json` |\n| **Cursor** | ✅ Auto-configured | `~/.cursor/mcp_settings.json` | `~/.cursor/mcp_settings.json` | `~/.cursor/mcp_settings.json` |\n| **VS Code** | ✅ Auto-configured | `~/.vscode/mcp_settings.json` | `~/.vscode/mcp_settings.json` | `~/.vscode/mcp_settings.json` |\n| **Codex (OpenAI)** | ✅ Auto-configured | `~/.codex/mcp_settings.json` | `~/.codex/mcp_settings.json` | `~/.codex/mcp_settings.json` |\n| **Antigravity (Google)** | ✅ Auto-configured | `~/.gemini/antigravity/mcp_config.json` | `%USERPROFILE%\\.gemini\\antigravity\\mcp_config.json` | `~/.config/antigravity/mcp_config.json` |\n\n**Note:** The installer automatically detects your platform and uses the correct config paths.\n\n## 🌐 Language Support (48 Languages)\n- **bg**: Bulgarian\n- **ca**: Catalan\n- **cs**: Czech\n- **da**: Danish\n- **de**: German\n- **el**: Greek\n- **en**: English\n- **en-AU**: English (Australia)\n- **en-CA**: English (Canada)\n- **en-GB**: English (United Kingdom)\n- **en-US**: English (United States)\n- **es**: Spanish\n- **es-MX**: Spanish (Mexico)\n- **et**: Estonian\n- **fi**: Finnish\n- **fr**: French\n- **fr-CA**: French (Canada)\n- **hi**: Hindi\n- **hr**: Croatian\n- **hu**: Hungarian\n- **id**: Indonesian\n- **is**: Icelandic\n- **it**: Italian\n- **ja**: Japanese\n- **ko**: Korean\n- **lt**: Lithuanian\n- **lv**: Latvian\n- **ms**: Malay\n- **nl**: Dutch\n- **no**: Norwegian\n- **pl**: Polish\n- **pt**: Portuguese\n- **pt-BR**: Portuguese (Brazil)\n- **ro**: Romanian\n- **ru**: Russian\n- **sk**: Slovak\n- **sl**: Slovenian\n- **sr**: Serbian\n- **sv**: Swedish\n- **th**: Thai\n- **tl**: Filipino\n- **tr**: Turkish\n- **uk**: Ukrainian\n- **vi**: Vietnamese\n- **zh-Hans**: Chinese (Simplified)\n- **zh-Hant-HK**: Chinese (Traditional, Hong Kong)\n- **zh-Hant-TW**: Chinese (Traditional, Taiwan)\n\n## 📁 Supported File Formats\n\n| Format | Extension | Features |\n|--------|-----------|----------|\n| JSON | `.json` | Preserves structure, nested objects |\n| YAML | `.yaml`, `.yml` | Maintains formatting, comments |\n| CSV | `.csv` | Handles quoted fields, commas |\n| XML/HTML | `.xml`, `.html` | Extracts text content |\n| Markdown | `.md` | Preserves formatting, skips code |\n| Properties | `.properties` | Java properties key-value pairs |\n| Plain Text | `.txt` | Direct translation |\n| PDF | `.pdf` | Text extraction and translation |\n| Word | `.docx`, `.doc` | Document translation |\n| Gettext | `.po`, `.pot`, `.mo` | Localization file formats |\n\n## 🔧 Manual Setup\n\nIf auto-installation fails, you can manually configure your IDE:\n\n### Claude Desktop\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"i18n-agent\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/i18n-agent.js\"],\n      \"env\": {\n        \"MCP_SERVER_URL\": \"https://mcp.i18nagent.ai\",\n        \"I18N_AGENT_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Cursor / VS Code\nCreate `.cursor/mcp_settings.json` or `.vscode/mcp_settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"i18n-agent\": {\n      \"command\": \"node\", \n      \"args\": [\"/path/to/i18n-agent.js\"],\n      \"env\": {\n        \"MCP_SERVER_URL\": \"https://mcp.i18nagent.ai\",\n        \"I18N_AGENT_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n## 💡 Usage Tips\n\n### Translation Context\n- **Target Audience**: Specify \"technical\", \"casual\", \"formal\", or \"general\"\n- **Industry Context**: Use \"technology\", \"healthcare\", \"finance\", \"education\"\n- **Regional Variations**: Add regions like \"Spain\", \"Mexico\", \"Brazil\"\n\n### File Translation\n- **Preserve Structure**: Keeps original file format and structure\n- **Output Format**: Convert between formats (JSON ↔ YAML ↔ CSV)\n- **Large Files**: Automatically chunks large files for processing\n- **Async Processing**: Files >50KB processed asynchronously with job tracking\n- **Progress Monitoring**: Real-time status updates for long-running translations\n- **Timeout Resilience**: Up to 10 minutes for large translation jobs\n\n### Large Translation Handling\n- **Async Processing**: >100 texts or >50KB files processed asynchronously\n- **Job Tracking**: Unique job IDs for monitoring long-running translations\n- **Progress Updates**: Real-time completion percentages and status\n- **Extended Timeouts**: 5-10 minute timeouts prevent interruptions\n- **Automatic Polling**: Client automatically polls for job completion\n\n### Credit Management\n- **Cost**: 1 credit per word ($0.01/word)\n- **Monitoring**: Check balance before large translations\n- **Estimates**: Get word count estimates before translation\n\n### Quality Warnings\n- **Source Analysis**: By default, source content is analyzed for quality issues before translation\n- **Skip Warnings**: Use `skipWarnings: true` to bypass warnings in automated workflows\n- **Trade-off**: Skipping warnings may reduce translation quality as potential issues aren't addressed\n- **Best Practice**: Keep warnings enabled (default) for production translations\n\n## 🚨 Troubleshooting\n\n### Installation Issues\n\n**Permission denied:**\n```bash\nsudo npm install -g @i18n-agent/mcp-client\n```\n\n**IDE not detected:**\n```bash\n# Check if IDE directory exists\nls ~/Library/Application\\ Support/Claude/\nls ~/.cursor/\nls ~/.vscode/\n```\n\n### MCP Connection Issues\n\n**\"Failed\" status in Claude Code:**\n\nThis 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:\n\n1. **Check your Node installation:**\n   ```bash\n   which node\n   # If output contains .nvm, you're using nvm\n   ```\n\n2. **Manual wrapper script (if auto-detection fails):**\n   Create `~/.claude/run-mcp.sh`:\n   ```bash\n   #!/bin/bash\n   export PATH=\"$(dirname $(which node)):$PATH\"\n   cd ~/.claude\n   exec node node_modules/@i18n-agent/mcp-client/i18n-agent.js\n   ```\n   \n   Make it executable:\n   ```bash\n   chmod +x ~/.claude/run-mcp.sh\n   ```\n   \n3. **Update Claude configuration:**\n   Edit `~/.claude.json`:\n   ```json\n   {\n     \"mcpServers\": {\n       \"i18n-agent\": {\n         \"command\": \"/Users/YOUR_USERNAME/.claude/run-mcp.sh\",\n         \"env\": {\n           \"MCP_SERVER_URL\": \"https://mcp.i18nagent.ai\",\n           \"I18N_AGENT_API_KEY\": \"your-api-key\"\n         }\n       }\n     }\n   }\n   ```\n\n4. **Restart Claude Code completely** (not just close window, quit the app)\n\n### Runtime Issues\n\n**API Key not found:**\n```bash\necho $I18N_AGENT_API_KEY  # Should show your key\nexport I18N_AGENT_API_KEY=your-key-here\n```\n\n**Connection errors:**\n- Check your internet connection\n- Verify API key is valid\n- Try again after a few seconds\n\n**Translation quality:**\n- Use Tier 1 languages for production\n- Add context with industry/audience parameters\n- Review Tier 2/3 translations manually\n\n## 📊 Pricing\n\n- **Pay-per-use**: 1 credit per word ($0.01/word)\n- **No subscriptions**: Only pay for what you translate  \n- **Bulk discounts**: Available for enterprise usage\n- **Free tier**: New accounts get starter credits\n\n## 🔐 Privacy & Security\n\n- **No data storage**: Translations are processed in real-time\n- **Encrypted transport**: All data sent over HTTPS\n- **API key security**: Keys are stored locally, never transmitted in logs\n- **GDPR compliant**: EU privacy standards\n\n## 🏗️ Architecture\n\nThe MCP client installer uses a modular architecture for bulletproof installation:\n\n```\nlib/\n├── config-manager.js      # Config file operations with atomic writes\n├── installer-core.js      # Installation orchestration\n├── transport-detector.js  # Auto-detect SSE vs stdio transport\n└── validator.js          # Input validation and sanitization\n```\n\n### Key Features\n\n- **Atomic Config Writes**: Use temp files + rename for crash safety\n- **Automatic Backups**: Create timestamped backups before modifications\n- **Transport Detection**: Auto-detect SSE vs stdio from config\n- **Comprehensive Validation**: Validate all inputs at module boundaries\n- **Zero External Dependencies**: Uses only Node.js built-ins\n\n### Architecture Details\n\nSee detailed documentation:\n- [Module Architecture](lib/README.md) - Module responsibilities and design\n- [Full Architecture Guide](docs/mcp-installer-architecture.md) - Complete system design\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md).\n\n### Development Setup\n\n```bash\ngit clone https://github.com/i18n-agent/mcp-client.git\ncd mcp-client\nnpm install\nnpm test\n```\n\n### Publishing\n\nUse the publishing script with built-in test gate:\n```bash\n./scripts/publish-mcp-client.sh --dry-run  # Preview package\n./scripts/publish-mcp-client.sh            # Run pre-publish checks\nnpm publish                                 # Publish to npm\n```\n\n## 📝 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 FatCouple OÜ\n\n## 🔗 Links\n\n- **Website**: [i18nagent.ai](https://i18nagent.ai)\n- **Dashboard**: [app.i18nagent.ai](https://app.i18nagent.ai)\n- **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)\n- **GitHub**: [github.com/i18n-agent/mcp-client](https://github.com/i18n-agent/mcp-client)\n- **Issues**: [github.com/i18n-agent/mcp-client/issues](https://github.com/i18n-agent/mcp-client/issues)\n\n## 🆘 Support\n\n- **Email**: support@i18nagent.ai\n- **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)\n\n## 🔧 Available MCP Tools\n\n### translate_text\nTranslate text content with cultural adaptation and context awareness.\n\n**Parameters:**\n- `texts` (array): Array of strings to translate\n- `targetLanguage` (string): Target language code\n- `targetAudience` (string): Target audience context\n- `industry` (string): Industry context\n- `namespace` (string, optional): Optional namespace identifier for backend tracking and project organization\n- `sourceLanguage` (string, optional): Source language (auto-detected if not provided)\n- `region` (string, optional): Specific region for localization\n- `skipWarnings` (boolean, optional): Skip source text quality warnings (default: false). ⚠️ WARNING: May hurt translation quality by bypassing source analysis. Only use when confident about content quality or in automated workflows.\n\n### translate_file\nTranslate files while preserving structure and format.\n\n**Parameters:**\n- `filePath` or `fileContent` (string): File path or content to translate\n- `fileType` (string): File format (json, yaml, xml, csv, txt, md, etc.)\n- `targetLanguage` (string): Target language code\n- `namespace` (string, **required**): Unique namespace identifier for backend tracking and project organization\n- `preserveKeys` (boolean): Whether to preserve object keys/structure\n- `outputFormat` (string): Output format (same, json, yaml, txt)\n- `skipWarnings` (boolean, optional): Skip source text quality warnings (default: false). ⚠️ WARNING: May hurt translation quality by bypassing source analysis. Only use when confident about content quality or in automated workflows.\n\n### analyze_content\nAnalyze content for translation readiness and get improvement suggestions before translation. This helps identify potential issues and optimize content before spending credits on translation.\n\n**Parameters:**\n- `content` (string/array/object): Content to analyze\n- `targetLanguage` (string): Target language for translation\n- `fileType` (string, optional): File type if content is from a file\n- `sourceLanguage` (string, optional): Source language (auto-detected)\n- `industry` (string): Industry context\n- `targetAudience` (string): Target audience\n- `region` (string, optional): Specific region for localization\n\n**Returns:**\n- Source language detection with confidence score\n- Content type and tone analysis\n- Translation readiness score (0-100)\n- Specific improvement suggestions\n- Quality metrics and issues\n- Warnings for potential problems\n- Estimated credits required\n\n### list_supported_languages\nGet list of all supported languages with quality ratings.\n\n**Parameters:**\n- `includeQuality` (boolean): Include quality ratings (default: true)\n\n### get_credits\nCheck remaining translation credits and word count estimates.\n\n**Parameters:**\n- `apiKey` (string): Your API key\n\n### check_translation_status\nCheck status of async translation jobs (for large files).\n\n**Parameters:**\n- `jobId` (string): Job ID from async translation\n\n---\n\nMade with ❤️ by [FatCouple OÜ](https://fireinbelly.com)",
  "bytes": 15300,
  "sha": "5e830785002ddfddaf409582662382f50104bce351dface654a6783178ab0111",
  "repo_slug": "i18n-agent/mcp-client",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_i18nagent_i18n_agent_3eb86e87/readme"
}