i18n-sync-mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -7,17 +7,18 @@
 - 将本地 i18n 映射上传到远程语言包服务
 - 支持批量同步映射
 - 自动处理认证和项目配置
+- 对接 Hwork-Workbench 工作台多语言接口
 
 ## 安装
 
 ```bash
-npm install -g @your-org/i18n-sync-mcp-server
+npm install -g i18n-sync-mcp-server
 ```
 
 或使用 npx：
 
 ```bash
-npx @your-org/i18n-sync-mcp-server
+npx i18n-sync-mcp-server
 ```
 
 ## 配置
@@ -29,12 +30,15 @@ npx @your-org/i18n-sync-mcp-server
   "mcpServers": {
     "i18n-sync": {
       "command": "npx",
-      "args": ["-y", "@your-org/i18n-sync-mcp-server"],
+      "args": ["-y", "i18n-sync-mcp-server"],
       "env": {
-        "I18N_AUTH_TOKEN": "your-auth-token",
-        "I18N_PROJECT_CODE": "your-project-code",
-        "I18N_MODULE_CODE": "your-module-code",
-        "I18N_REMOTE_API_URL": "https://api.example.com/i18n/mapping/upload"
+        "I18N_API_KEY": "your-api-key",
+        "I18N_APP_CODE": "SP000610",
+        "I18N_MODULE_CODE": "M2024080516210622558046",
+        "I18N_GROUP_TYPE": "2",
+        "I18N_OPERATOR": "your-user-id",
+        "I18N_KEY_PREFIX": "ML_chain_app_",
+        "I18N_REMOTE_API_URL": "https://gw-qd-aliyun-stage.haier.net/gzt/hwork-backend-workbench/v1/plat/application/i18n/costom/batchSaveOrUpdate"
       }
     }
   }
@@ -45,25 +49,33 @@ npx @your-org/i18n-sync-mcp-server
 
 | 变量名 | 必需 | 说明 |
 |--------|------|------|
-| `I18N_AUTH_TOKEN` | 是 | 远程服务的认证 token |
-| `I18N_PROJECT_CODE` | 是 | 项目唯一标识 |
-| `I18N_MODULE_CODE` | 否 | 模块标识 |
-| `I18N_REMOTE_API_URL` | 否 | 远程 API 地址（默认为示例地址） |
+| `I18N_API_KEY` | 是 | Authorization ApiKey（用于调用远程语言包接口） |
+| `I18N_APP_CODE` | 是 | 应用编码，对应 applicationCode |
+| `I18N_MODULE_CODE` | 是 | 模块编码，对应 businessCode |
+| `I18N_GROUP_TYPE` | 是 | 分组类型：1-子产品；2-应用；3-组件；4-菜单 |
+| `I18N_OPERATOR` | 是 | 操作人标识，用于 X-USER 请求头 |
+| `I18N_KEY_PREFIX` | 是 | 编码前缀，如 `ML_chain_app_`，远程会自动拼接 |
+| `I18N_REMOTE_API_URL` | 是 | 远程 API 地址 |
 
 ## 可用工具
 
 ### sync_mapping_to_remote
 
-将本地映射同步到远程语言包服务。
+将本地映射和多语言翻译同步到远程语言包服务。
+
+**重要**：上传时至少需要包含英文翻译（en-US）。
 
 **参数：**
 
 - `mappings` (array, 必需): 映射数组，每项包含：
   - `text` (string): 中文文案
   - `key` (string): ML_ key
+  - `translations` (object, 可选): 多语言翻译对象
+    - key: 语言代码（如 en-US, th-TH）
+    - value: 翻译文本
 - `localeFilePath` (string, 可选): zh-CN.ts 文件路径
 
-**示例：**
+**示例 1：仅上传中文映射**
 
 ```javascript
 {
@@ -74,6 +86,77 @@ npx @your-org/i18n-sync-mcp-server
 }
 ```
 
+返回结果中的 mappings 可用于更新 zh-CN.ts（格式为 `ML_key: 中文`）：
+```typescript
+// zh-CN.ts
+export default {
+  'ML_chain_app_3APV9EU0HUVC9OX': '新增',
+  'ML_chain_app_3APODM6S81RFP9W': '编辑',
+} as Record<string, string>
+```
+
+**示例 2：上传中文映射和多语言翻译**
+
+```javascript
+{
+  "mappings": [
+    {
+      "text": "新增",
+      "key": "ML_chain_app_3APV9EU0HUVC9OX",
+      "translations": {
+        "en-US": "Add",
+        "th-TH": "เพิ่ม",
+        "ms-MY": "Tambah"
+      }
+    },
+    {
+      "text": "编辑",
+      "key": "ML_chain_app_3APODM6S81RFP9W",
+      "translations": {
+        "en-US": "Edit",
+        "th-TH": "แก้ไข",
+        "ms-MY": "Edit"
+      }
+    }
+  ]
+}
+```
+
+## 接口说明
+
+本服务器对接 Hwork-Workbench 工作台的多语言接口：
+
+**接口地址：** `/v1/plat/application/i18n/costom/batchSaveOrUpdate`
+
+**请求格式：**
+
+```json
+{
+  "applicationCode": "所属子产品编码",
+  "dataList": [
+    {
+      "businessCode": "所属分组编码",
+      "customCode": "ML_xxx (自定义编码)",
+      "customName": "中文名称",
+      "groupType": "分组类型",
+      "i18NTextVOList": [
+        {
+          "languageCode": "zh-CN",
+          "resourceText": "中文翻译"
+        }
+      ]
+    }
+  ],
+  "operator": "操作人"
+}
+```
+
+**请求头：**
+
+- `Authorization`: 认证 Token
+- `X-USER`: 操作人标识
+- `Content-Type`: application/json
+
 ## 许可证
 
 MIT

package/i18n-sync-server.cjs

@@ -2,6 +2,8 @@
 /**
  * 国际化映射同步 MCP Server
  * 用于将本地映射上传到远程语言包服务
+ * 
+ * 对接接口：/v1/plat/application/i18n/costom/batchSaveOrUpdate
  */
 
 const http = require('http');
@@ -11,35 +13,72 @@ const path = require('path');
 
 // ============= 配置区域（通过环境变量配置） =============
 const CONFIG = {
-  // 远程接口地址
-  remoteApiUrl: process.env.I18N_REMOTE_API_URL || 'https://api.example.com/i18n/mapping/upload',
-  // 认证 token
-  authToken: process.env.I18N_AUTH_TOKEN || '',
-  // 项目标识
-  projectCode: process.env.I18N_PROJECT_CODE || 'ML_chain_app',
-  // 模块标识
+  // 远程接口基础地址
+  remoteApiUrl: process.env.I18N_REMOTE_API_URL || '',
+  // 认证 ApiKey (Authorization header)
+  authToken: process.env.I18N_API_KEY || '',
+  // 项目标识 (applicationCode)
+  appCode: process.env.I18N_APP_CODE || '',
+  // 分组标识 (businessCode)
   moduleCode: process.env.I18N_MODULE_CODE || '',
+  // 分组类型 (groupType)
+  groupType: process.env.I18N_GROUP_TYPE || '',
+  // 操作人 (X-USER header)
+  operator: process.env.I18N_OPERATOR || '',
+  // 编码前缀（远程会自动拼接，请求时需去除）
+  keyPrefix: process.env.I18N_KEY_PREFIX || '',
 };
 // ===================================================
 
+/**
+ * 去除 key 的前缀
+ * @param {string} key - 原始 key（可能带前缀）
+ * @returns {string} - 去除前缀后的 key
+ */
+function removeKeyPrefix(key) {
+  if (!CONFIG.keyPrefix) return key;
+  if (key.startsWith(CONFIG.keyPrefix)) {
+    return key.slice(CONFIG.keyPrefix.length);
+  }
+  return key;
+}
+
+/**
+ * 添加 key 的前缀
+ * @param {string} key - 原始 key（不带前缀）
+ * @returns {string} - 添加前缀后的完整 key
+ */
+function addKeyPrefix(key) {
+  if (!CONFIG.keyPrefix) return key;
+  if (key.startsWith(CONFIG.keyPrefix)) {
+    return key; // 已有前缀，不重复添加
+  }
+  return CONFIG.keyPrefix + key;
+}
+
 // MCP 协议实现
 class MCPServer {
   constructor() {
     this.tools = {
       'sync_mapping_to_remote': {
         name: 'sync_mapping_to_remote',
-        description: '将本地映射同步到远程语言包服务',
+        description: '将本地映射同步到远程语言包服务，支持多语言翻译',
         inputSchema: {
           type: 'object',
           properties: {
             mappings: {
               type: 'array',
-              description: '要上传的映射数组，每项包含 text（中文文案）和 key（ML_ key）',
+              description: '要上传的映射数组，每项包含 text（中文文案）、key（ML_ key）和可选的 translations（多语言翻译）',
               items: {
                 type: 'object',
                 properties: {
                   text: { type: 'string', description: '中文文案' },
-                  key: { type: 'string', description: 'ML_ key' }
+                  key: { type: 'string', description: 'ML_ key' },
+                  translations: {
+                    type: 'object',
+                    description: '可选的多语言翻译对象，key 为语言代码（如 en-US, th-TH），value 为翻译文本',
+                    additionalProperties: { type: 'string' }
+                  }
                 },
                 required: ['text', 'key']
               }
@@ -108,43 +147,165 @@ class MCPServer {
             type: 'text',
             text: JSON.stringify({
               success: false,
-              message: '请配置 I18N_AUTH_TOKEN 环境变量',
+              message: '请配置 I18N_API_KEY 环境变量',
               hint: '在项目根目录的 .env 文件或系统环境变量中设置'
             }, null, 2)
           }]
         };
       }
 
+      if (!CONFIG.appCode) {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              success: false,
+              message: '请配置 I18N_APP_CODE 环境变量',
+              hint: '这是 applicationCode，用于标识所属子产品'
+            }, null, 2)
+          }]
+        };
+      }
+
+      if (!CONFIG.keyPrefix) {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              success: false,
+              message: '请配置 I18N_KEY_PREFIX 环境变量',
+              hint: '这是编码前缀，如 ML_chain_app_，远程会自动拼接'
+            }, null, 2)
+          }]
+        };
+      }
+
+      // 构建符合 OpenAPI 规范的请求体
+      // I18NCustomBatchSaveParam 格式
+      const dataList = mappings.map(m => {
+        // 去除前缀后的编码（用于接口请求）
+        const codeWithoutPrefix = removeKeyPrefix(m.key);
+        // 带前缀的完整编码（用于 zh-CN.ts）
+        const codeWithPrefix = addKeyPrefix(codeWithoutPrefix);
+
+        // 基础的中文翻译
+        const i18NTextVOList = [
+          {
+            languageCode: 'zh-CN',
+            resourceText: m.text
+          }
+        ];
+
+        // 如果提供了多语言翻译，添加到列表中
+        if (m.translations && typeof m.translations === 'object') {
+          for (const [langCode, translation] of Object.entries(m.translations)) {
+            if (translation && typeof translation === 'string') {
+              i18NTextVOList.push({
+                languageCode: langCode,
+                resourceText: translation
+              });
+            }
+          }
+        }
+
+        return {
+          // 所属分组编码
+          businessCode: CONFIG.moduleCode,
+          // 自定义编码（去除前缀后的编码，远程会自动拼接前缀）
+          customCode: codeWithoutPrefix,
+          // 名称(中文)
+          customName: m.text,
+          // 分组类型
+          groupType: CONFIG.groupType || '2',
+          // 多语言翻译列表
+          i18NTextVOList: i18NTextVOList,
+          // 保存完整编码供返回使用
+          _fullKey: codeWithPrefix
+        };
+      });
+
       const requestBody = {
-        projectCode: CONFIG.projectCode,
-        moduleCode: CONFIG.moduleCode,
-        mappings: mappings.map(m => ({
-          key: m.key,
-          zhCN: m.text,
-        }))
+        applicationCode: CONFIG.appCode,
+        dataList: dataList,
+        operator: CONFIG.operator || 'i18n-sync-server'
       };
 
+      const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': CONFIG.authToken,
+        'X-USER': CONFIG.operator || 'i18n-sync-server'
+      };
+
+      // 生成 curl 命令
+      const curlCommand = this.generateCurlCommand(CONFIG.remoteApiUrl, headers, requestBody);
+      
+      // 输出请求信息到 stderr（便于调试）
+      process.stderr.write('\n========== 请求信息 ==========\n');
+      process.stderr.write(`映射数量: ${mappings.length}\n`);
+      process.stderr.write(`包含翻译: ${mappings.some(m => m.translations) ? '是' : '否'}\n`);
+      if (mappings.some(m => m.translations)) {
+        const languages = new Set();
+        mappings.forEach(m => {
+          if (m.translations) {
+            Object.keys(m.translations).forEach(lang => languages.add(lang));
+          }
+        });
+        process.stderr.write(`翻译语言: ${Array.from(languages).join(', ')}\n`);
+      }
+      process.stderr.write('\n=== cURL 命令 ===\n');
+      process.stderr.write(curlCommand + '\n');
+      process.stderr.write('============================\n\n');
+
       const response = await this.httpRequest({
         url: CONFIG.remoteApiUrl,
         method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Authorization': `Bearer ${CONFIG.authToken}`
-        },
+        headers: headers,
         body: JSON.stringify(requestBody)
       });
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            success: true,
-            message: `成功同步 ${mappings.length} 个映射到远程服务`,
-            uploadedCount: mappings.length,
-            mappings: mappings
-          }, null, 2)
-        }]
-      };
+      // 解析响应 Result«ExcelResultVO»
+      if (response.code === 200 || response.code === 0) {
+        const data = response.data || {};
+        const hasErrors = data.excelParseResultVOList && data.excelParseResultVOList.length > 0;
+        
+        // 构建返回的映射信息（包含完整的 key，用于更新 zh-CN.ts）
+        const resultMappings = dataList.map((item, index) => ({
+          text: mappings[index].text,
+          key: item._fullKey,  // 带前缀的完整 key
+          requestKey: item.customCode  // 请求时使用的 key（不带前缀）
+        }));
+        
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              success: true,
+              message: `成功同步 ${mappings.length} 个映射到远程服务`,
+              uploadedCount: data.successNum || mappings.length,
+              serverMessage: data.resMessage || '同步完成',
+              hasErrors: hasErrors,
+              errors: data.excelParseResultVOList || [],
+              keyPrefix: CONFIG.keyPrefix,
+              mappings: resultMappings,
+              curlCommand: curlCommand
+            }, null, 2)
+          }]
+        };
+      } else {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              success: false,
+              message: response.message || '同步失败',
+              code: response.code,
+              response: response,
+              curlCommand: curlCommand,
+              hint: '请检查环境变量配置是否正确，或使用 curl 命令手动测试接口'
+            }, null, 2)
+          }]
+        };
+      }
     } catch (error) {
       // 如果是模拟模式（接口不存在），返回模拟成功
       if (error.message.includes('ENOTFOUND') || error.message.includes('ECONNREFUSED')) {
@@ -161,8 +322,40 @@ class MCPServer {
           }]
         };
       }
-      throw error;
+      
+      // 其他错误
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            success: false,
+            message: '请求失败: ' + error.message,
+            error: error.toString(),
+            hint: '请检查网络连接和接口地址是否正确'
+          }, null, 2)
+        }]
+      };
+    }
+  }
+
+  // 生成 curl 命令
+  generateCurlCommand(url, headers, body) {
+    let curl = `curl -X POST "${url}"`;
+    
+    // 添加请求头
+    for (const [key, value] of Object.entries(headers)) {
+      curl += ` \\\n  -H "${key}: ${value}"`;
+    }
+    
+    // 添加请求体
+    if (body) {
+      const bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
+      // 转义单引号和反斜杠
+      const escapedBody = bodyStr.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+      curl += ` \\\n  -d '${escapedBody}'`;
     }
+    
+    return curl;
   }
 
   // HTTP 请求封装

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-sync-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for syncing i18n mappings to remote service",
   "main": "i18n-sync-server.cjs",
   "bin": {