@i18n-agent/mcp-client 1.0.0 → 1.0.2

package/CONTRIBUTING.md

@@ -0,0 +1,218 @@
+# Contributing to i18n-agent MCP Client
+
+Thank you for your interest in contributing to the i18n-agent MCP client! We welcome contributions from the community.
+
+## 🚀 Quick Start
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/mcp-client.git
+   cd mcp-client
+   ```
+3. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## 🛠 Development Setup
+
+### Prerequisites
+- Node.js 16+ 
+- npm or yarn
+- Git
+
+### Local Development
+```bash
+# Install dependencies (if any are added)
+npm install
+
+# Run tests
+npm test
+
+# Test the installer locally
+node install.js
+
+# Test MCP client syntax
+node -c mcp-client.js
+```
+
+## 📝 Types of Contributions
+
+### 🐛 Bug Reports
+- Use the [GitHub Issues](https://github.com/i18n-agent/mcp-client/issues) page
+- Include steps to reproduce
+- Mention your OS, IDE, and Node.js version
+- Include error messages and logs
+
+### 💡 Feature Requests  
+- Check existing issues first
+- Describe the use case and expected behavior
+- Consider backward compatibility
+
+### 🔧 Code Contributions
+
+#### Areas for Contribution:
+- **IDE Support**: Add support for new AI IDEs
+- **Installation**: Improve cross-platform compatibility
+- **Error Handling**: Better error messages and recovery
+- **Documentation**: Improve README, add examples
+- **Testing**: Add more test cases
+- **Localization**: Translate installation messages
+
+## 🧪 Testing
+
+Before submitting a PR, ensure:
+
+```bash
+# Run the test suite
+npm test
+
+# Test installation process
+node install.js
+
+# Check for syntax errors
+node -c mcp-client.js
+node -c install.js
+```
+
+### Test Coverage Areas:
+- ✅ Configuration generation
+- ✅ IDE detection
+- ✅ File validation
+- ✅ Package.json validation  
+- ✅ MCP client syntax
+- 🔧 Cross-platform testing needed
+- 🔧 Error condition testing needed
+
+## 📋 Coding Standards
+
+### JavaScript Style
+- Use ES6+ modules (`import`/`export`)
+- Use modern JavaScript features
+- Add JSDoc comments for functions
+- Use descriptive variable names
+
+### Security
+- **Never commit API keys** or secrets
+- Use environment variables for configuration
+- Validate user input
+- Handle errors gracefully
+
+### Example Code Style:
+```javascript
+/**
+ * Detect available AI IDEs on the system
+ * @returns {Promise<Array>} List of available IDEs with config paths
+ */
+async function detectAvailableIDEs() {
+  const available = [];
+  
+  for (const [key, config] of Object.entries(IDE_CONFIGS)) {
+    const configDir = path.dirname(config.configPath);
+    if (fs.existsSync(configDir)) {
+      available.push({ key, ...config });
+    }
+  }
+  
+  return available;
+}
+```
+
+## 🚦 Pull Request Process
+
+1. **Create a feature branch** from `main`
+2. **Make your changes** with clear, focused commits
+3. **Add tests** if applicable
+4. **Update documentation** if needed
+5. **Run tests** and ensure they pass
+6. **Create a Pull Request** with:
+   - Clear title and description
+   - Reference any related issues
+   - Include testing steps
+
+### PR Title Format:
+- `feat: add support for WebStorm IDE`
+- `fix: handle Windows path separators correctly` 
+- `docs: improve installation instructions`
+- `test: add cross-platform installation tests`
+
+## 🌟 Adding IDE Support
+
+To add support for a new AI IDE:
+
+1. **Add IDE config** to `IDE_CONFIGS` in `install.js`:
+   ```javascript
+   newIDE: {
+     name: 'New IDE Name',
+     configPath: path.join(os.homedir(), '.newIDE/mcp_config.json'),
+     displayPath: '~/.newIDE/mcp_config.json'
+   }
+   ```
+
+2. **Add configuration logic** if the IDE uses a different config format
+
+3. **Test on the target platform**
+
+4. **Update README** with IDE support information
+
+## 🐛 Debugging
+
+### Common Issues:
+- **Permission errors**: Check file permissions for config directories
+- **Path issues**: Ensure paths work on Windows/macOS/Linux  
+- **JSON parsing**: Validate config file structure
+- **Node.js version**: Ensure compatibility with Node 16+
+
+### Debug Environment Variables:
+```bash
+# Enable verbose logging (if implemented)
+DEBUG=i18n-agent:* node install.js
+
+# Test with different home directories
+HOME=/tmp/test-home node install.js
+```
+
+## 📚 Documentation
+
+### README Updates
+- Keep installation instructions current
+- Add new IDE support to the table
+- Update feature lists
+- Include troubleshooting for new scenarios
+
+### Code Comments
+- Document complex logic
+- Explain IDE-specific quirks
+- Add TODO comments for future improvements
+
+## 🌍 Internationalization
+
+We welcome contributions to translate the installer messages:
+
+1. **Add language files** in `locales/` directory
+2. **Use i18n library** for message formatting
+3. **Test with different system locales**
+
+## ⚖️ License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+## 🆘 Getting Help
+
+- **GitHub Issues**: https://github.com/i18n-agent/mcp-client/issues
+- **Discord**: [Join our community](https://discord.gg/i18nagent)
+- **Email**: support@i18nagent.ai
+
+## 🎉 Recognition
+
+Contributors will be:
+- Listed in the README
+- Mentioned in release notes
+- Invited to our contributors Discord channel
+
+Thank you for helping make i18n-agent better for everyone! 🌟
+
+---
+
+Made with ❤️ by the i18n-agent community

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FatCouple OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# 🌍 i18n-agent MCP Client
+
+Professional translation service client for Claude, Cursor, VS Code, and other AI IDEs using the Model Context Protocol (MCP).
+
+[![npm version](https://badge.fury.io/js/%40i18n-agent%2Fmcp-client.svg)](https://www.npmjs.com/package/@i18n-agent/mcp-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- **🎯 Smart Translation**: Context-aware translations with cultural adaptation
+- **📁 File Translation**: Support for JSON, YAML, CSV, XML, Markdown, and more
+- **💰 Credit Tracking**: Real-time credit balance and word count estimates
+- **🌐 30+ Languages**: Multi-tier language support with quality ratings
+- **🔧 Easy Setup**: One-command installation for major AI IDEs
+
+## 🚀 Quick Installation
+
+Install via npx (recommended):
+
+```bash
+npx @i18n-agent/mcp-client install
+```
+
+Or install globally:
+
+```bash
+npm install -g @i18n-agent/mcp-client
+i18n-agent-install
+```
+
+## 🔑 Setup API Key
+
+1. **Get your API key** from [app.i18nagent.ai](https://app.i18nagent.ai)
+
+2. **Set environment variable**:
+   ```bash
+   export API_KEY=your-api-key-here
+   ```
+
+3. **Make it permanent** (add to ~/.bashrc or ~/.zshrc):
+   ```bash
+   echo 'export API_KEY=your-api-key-here' >> ~/.zshrc
+   ```
+
+4. **Restart your AI IDE** to load the new configuration
+
+## 🎮 Usage Examples
+
+### Text Translation
+```
+Translate "Hello, how are you?" to Spanish for a casual audience
+```
+
+### File Translation
+```
+Translate this JSON file to French, preserving the structure
+```
+
+### Credit Check
+```
+Check my translation credits
+```
+
+### Language Support
+```
+List supported languages with quality ratings
+```
+
+## 🛠 Supported AI IDEs
+
+| IDE | Status | Config Location |
+|-----|--------|----------------|
+| **Claude Desktop** | ✅ Auto-configured | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Cursor** | ✅ Auto-configured | `~/.cursor/mcp_settings.json` |
+| **VS Code** | ✅ Auto-configured | `~/.vscode/mcp_settings.json` |
+| **Other MCP IDEs** | 🔧 Manual setup | Varies |
+
+## 🌐 Language Support
+
+### Tier 1 - Production Ready (80-90% Quality)
+- **en**: English
+- **es**: Spanish  
+- **fr**: French
+- **de**: German
+- **it**: Italian
+- **pt**: Portuguese
+- **nl**: Dutch
+
+### Tier 2 - Production Viable (50-75% Quality)
+- **ru**: Russian
+- **zh-CN**: Chinese (Simplified)
+- **ja**: Japanese
+- **ko**: Korean
+- **ar**: Arabic
+- **he**: Hebrew
+- **hi**: Hindi
+- **pl**: Polish
+- **cs**: Czech
+
+### Tier 3 - Basic Support (20-50% Quality)
+- **zh-TW**: Chinese (Traditional)
+- **th**: Thai
+- **vi**: Vietnamese
+- **sv**: Swedish
+- **da**: Danish
+- **no**: Norwegian
+- **fi**: Finnish
+- **tr**: Turkish
+- **hu**: Hungarian
+
+## 📁 Supported File Formats
+
+| Format | Extension | Features |
+|--------|-----------|----------|
+| JSON | `.json` | Preserves structure, nested objects |
+| YAML | `.yaml`, `.yml` | Maintains formatting, comments |
+| CSV | `.csv` | Handles quoted fields, commas |
+| XML/HTML | `.xml`, `.html` | Extracts text content |
+| Markdown | `.md` | Preserves formatting, skips code |
+| Properties | `.properties` | Key-value pairs |
+| Plain Text | `.txt` | Direct translation |
+
+## 🔧 Manual Setup
+
+If auto-installation fails, you can manually configure your IDE:
+
+### Claude Desktop
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "i18n-agent": {
+      "command": "node",
+      "args": ["/path/to/mcp-client.js"],
+      "env": {
+        "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
+        "API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+Create `.cursor/mcp_settings.json` or `.vscode/mcp_settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "i18n-agent": {
+      "command": "node", 
+      "args": ["/path/to/mcp-client.js"],
+      "env": {
+        "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
+        "API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## 💡 Usage Tips
+
+### Translation Context
+- **Target Audience**: Specify "technical", "casual", "formal", or "general"
+- **Industry Context**: Use "technology", "healthcare", "finance", "education"
+- **Regional Variations**: Add regions like "Spain", "Mexico", "Brazil"
+
+### File Translation
+- **Preserve Structure**: Keeps original file format and structure
+- **Output Format**: Convert between formats (JSON ↔ YAML ↔ CSV)
+- **Large Files**: Automatically chunks large files for processing
+
+### Credit Management
+- **Cost**: 0.001 credits per word
+- **Monitoring**: Check balance before large translations
+- **Estimates**: Get word count estimates before translation
+
+## 🚨 Troubleshooting
+
+### Installation Issues
+
+**Permission denied:**
+```bash
+sudo npm install -g @i18n-agent/mcp-client
+```
+
+**IDE not detected:**
+```bash
+# Check if IDE directory exists
+ls ~/Library/Application\ Support/Claude/
+ls ~/.cursor/
+ls ~/.vscode/
+```
+
+### Runtime Issues
+
+**API Key not found:**
+```bash
+echo $API_KEY  # Should show your key
+export API_KEY=your-key-here
+```
+
+**Connection errors:**
+- Check your internet connection
+- Verify API key is valid
+- Try again after a few seconds
+
+**Translation quality:**
+- Use Tier 1 languages for production
+- Add context with industry/audience parameters
+- Review Tier 2/3 translations manually
+
+## 📊 Pricing
+
+- **Pay-per-use**: 0.001 credits per word
+- **No subscriptions**: Only pay for what you translate  
+- **Bulk discounts**: Available for enterprise usage
+- **Free tier**: New accounts get starter credits
+
+## 🔐 Privacy & Security
+
+- **No data storage**: Translations are processed in real-time
+- **Encrypted transport**: All data sent over HTTPS
+- **API key security**: Keys are stored locally, never transmitted in logs
+- **GDPR compliant**: EU privacy standards
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md).
+
+### Development Setup
+
+```bash
+git clone https://github.com/i18n-agent/mcp-client.git
+cd mcp-client
+npm install
+npm test
+```
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2025 FatCouple OÜ
+
+## 🔗 Links
+
+- **Website**: [i18nagent.ai](https://i18nagent.ai)
+- **Dashboard**: [app.i18nagent.ai](https://app.i18nagent.ai)
+- **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)
+- **GitHub**: [github.com/i18n-agent/mcp-client](https://github.com/i18n-agent/mcp-client)
+- **Issues**: [github.com/i18n-agent/mcp-client/issues](https://github.com/i18n-agent/mcp-client/issues)
+
+## 🆘 Support
+
+- **Discord**: [Join our community](https://discord.gg/i18nagent)
+- **Email**: support@i18nagent.ai
+- **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)
+
+---
+
+Made with ❤️ by [FatCouple OÜ](https://fireinbelly.com)

package/install.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+/**
+ * i18n-agent MCP Client Installer
+ * Installs the MCP client to work with Claude, Cursor, VS Code and other AI IDEs
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Supported IDE configurations
+const IDE_CONFIGS = {
+  claude: {
+    name: 'Claude Desktop',
+    configPath: path.join(os.homedir(), 'Library/Application Support/Claude/claude_desktop_config.json'),
+    displayPath: '~/Library/Application Support/Claude/claude_desktop_config.json'
+  },
+  cursor: {
+    name: 'Cursor',
+    configPath: path.join(os.homedir(), '.cursor/mcp_settings.json'),
+    displayPath: '~/.cursor/mcp_settings.json'
+  },
+  vscode: {
+    name: 'VS Code (with MCP extension)',
+    configPath: path.join(os.homedir(), '.vscode/mcp_settings.json'),
+    displayPath: '~/.vscode/mcp_settings.json'
+  }
+};
+
+console.log(`
+🌍 i18n-agent MCP Client Installer
+===================================
+
+This installer will set up the i18n-agent MCP client for your AI IDE.
+
+Features:
+✨ Text translation with cultural context
+📁 File translation (JSON, YAML, CSV, MD, etc.)
+💰 Credit balance checking
+🌐 30+ language support with quality tiers
+`);
+
+async function detectAvailableIDEs() {
+  const available = [];
+  
+  for (const [key, config] of Object.entries(IDE_CONFIGS)) {
+    const configDir = path.dirname(config.configPath);
+    if (fs.existsSync(configDir)) {
+      available.push({ key, ...config });
+    }
+  }
+  
+  return available;
+}
+
+function createMCPConfig() {
+  const mcpClientPath = path.resolve(__dirname, 'mcp-client.js');
+  
+  return {
+    mcpServers: {
+      "i18n-agent": {
+        command: "node",
+        args: [mcpClientPath],
+        env: {
+          MCP_SERVER_URL: "https://mcp.i18nagent.ai",
+          API_KEY: ""
+        }
+      }
+    }
+  };
+}
+
+function updateClaudeConfig(configPath) {
+  let config = {};
+  
+  // Read existing config if it exists
+  if (fs.existsSync(configPath)) {
+    try {
+      const content = fs.readFileSync(configPath, 'utf8');
+      config = JSON.parse(content);
+    } catch (error) {
+      console.warn(`Warning: Could not parse existing config at ${configPath}`);
+    }
+  }
+  
+  // Ensure mcpServers exists
+  if (!config.mcpServers) {
+    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: ""
+    }
+  };
+  
+  // Write updated config
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  
+  return config;
+}
+
+function updateGenericMCPConfig(configPath) {
+  const config = createMCPConfig();
+  
+  // Write config
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  
+  return config;
+}
+
+async function main() {
+  try {
+    console.log('🔍 Detecting available AI IDEs...\n');
+    
+    const availableIDEs = await detectAvailableIDEs();
+    
+    if (availableIDEs.length === 0) {
+      console.log(`❌ No supported AI IDEs detected.
+
+Supported IDEs:
+- Claude Desktop (macOS)
+- Cursor
+- VS Code (with MCP extension)
+
+Manual setup:
+1. Create the configuration file for your IDE
+2. Add the i18n-agent MCP server configuration
+3. Set your API_KEY environment variable
+
+For manual setup instructions, visit: https://docs.i18nagent.ai/setup
+`);
+      process.exit(1);
+    }
+    
+    console.log('✅ Available AI IDEs:');
+    availableIDEs.forEach((ide, index) => {
+      console.log(`${index + 1}. ${ide.name}`);
+    });
+    
+    console.log('\n📝 Installing for all available IDEs...\n');
+    
+    let installCount = 0;
+    
+    for (const ide of availableIDEs) {
+      try {
+        console.log(`⚙️  Configuring ${ide.name}...`);
+        
+        if (ide.key === 'claude') {
+          updateClaudeConfig(ide.configPath);
+        } else {
+          updateGenericMCPConfig(ide.configPath);
+        }
+        
+        console.log(`✅ ${ide.name} configured successfully!`);
+        console.log(`   Config: ${ide.displayPath}\n`);
+        installCount++;
+        
+      } catch (error) {
+        console.error(`❌ Failed to configure ${ide.name}: ${error.message}\n`);
+      }
+    }
+    
+    if (installCount > 0) {
+      console.log(`🎉 Installation complete! Configured ${installCount} IDE(s).
+
+🔑 Important: Set your API key
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+You need to set your API key to use the translation service:
+
+1. Get your API key from: https://app.i18nagent.ai
+2. Set it as an environment variable:
+
+   export API_KEY=your-api-key-here
+
+   Or add it to your shell profile (~/.bashrc, ~/.zshrc):
+   echo 'export API_KEY=your-api-key-here' >> ~/.zshrc
+
+🔄 Restart your IDE
+After setting the API key, restart your AI IDE to load the new configuration.
+
+🧪 Test the installation
+Try these commands in your AI IDE:
+- "Translate 'Hello world' to Spanish"
+- "Check my translation credits"
+- "List supported languages"
+
+📚 Documentation: https://docs.i18nagent.ai
+🐛 Issues: https://github.com/i18n-agent/mcp-client/issues
+`);
+    } else {
+      console.error('❌ Installation failed for all IDEs. Please check the error messages above.');
+      process.exit(1);
+    }
+    
+  } catch (error) {
+    console.error(`❌ Installation failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Handle command line execution
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { main, IDE_CONFIGS, createMCPConfig };