GonMCPtool

Instructions

Implementation Reference

• tools/localizationTool.ts:346-371 (handler)

  Core handler function that implements the localizationAdd tool logic: reads CSV, checks for duplicate Key, adds the new entry, writes back to file, and handles caching.

  static async addEntry(filePath: string, entry: LocalizationEntry): Promise<string> {
    try {
      // 檢查輸入是否有效
      if (!entry.Key) {
        return '錯誤: Key 不能為空';
      }
      
      const records = await this.getCSVData(filePath);
  
      // 檢查Key是否已存在
      if (records.some(e => e.Key === entry.Key)) {
        return `錯誤: Key "${entry.Key}" 已存在`;
      }
  
      // 新增項目
      records.push({...entry});
  
      // 寫回檔案並更新緩存
      await this.writeCSVData(filePath, records);
  
      return `成功新增Key "${entry.Key}"`;
    } catch (error) {
      console.error(`新增翻譯項失敗: ${error instanceof Error ? error.message : '未知錯誤'}`);
      throw error;
    }
  }

• main.ts:346-369 (registration)

  MCP server registration of the 'localizationAdd' tool, including inline input schema and handler wrapper that calls LocalizationTool.addEntry.

  server.tool("localizationAdd",
      "新增一個完整的翻譯項目",
      {
          filePath: z.string(),
          entry: z.object({
              Key: z.string(),
              "zh-TW": z.string(),
              "zh-CN": z.string(),
              en: z.string()
          }).passthrough()
      },
      async ({ filePath, entry }) => {
          try {
              const result = await LocalizationTool.addEntry(filePath, entry as LocalizationEntry);
              return {
                  content: [{ type: "text", text: result }]
              };
          } catch (error) {
              return {
                  content: [{ type: "text", text: `新增失敗: ${error instanceof Error ? error.message : "未知錯誤"}` }]
              };
          }
      }
  );

• main.ts:348-356 (schema)

  Zod input schema validation for the localizationAdd tool defining filePath and entry structure (Key, zh-TW, zh-CN, en).

  {
      filePath: z.string(),
      entry: z.object({
          Key: z.string(),
          "zh-TW": z.string(),
          "zh-CN": z.string(),
          en: z.string()
      }).passthrough()
  },

• tools/localizationTool.ts:8-14 (schema)

  TypeScript interface defining the structure of a LocalizationEntry used in the tool.

  export interface LocalizationEntry {
    Key: string;
    'zh-TW': string;
    'zh-CN': string;
    en: string;
    [key: string]: string; // 其他可能的語言欄位
  }

• tools/localizationTool.ts:212-258 (helper)

  Helper method to write updated CSV data back to file with proper column ordering, CSV stringification, and cache update, used by addEntry.

  private static async writeCSVData(filePath: string, data: LocalizationEntry[]): Promise<void> {
    try {
      // 檢查是否有數據
      if (data.length === 0) {
        throw new Error('沒有要寫入的數據');
      }
      
      // 獲取所有列名
      const columnSet = new Set<string>();
      columnSet.add('Key'); // 確保Key始終是第一列
      
      // 收集所有可能的列
      data.forEach(entry => {
        Object.keys(entry).forEach(key => columnSet.add(key));
      });
      
      // 轉換為陣列並將Key移到第一位
      const columns = Array.from(columnSet);
      if (columns[0] !== 'Key') {
        const keyIndex = columns.indexOf('Key');
        if (keyIndex > 0) {
          columns.splice(keyIndex, 1);
          columns.unshift('Key');
        }
      }
      
      // 使用csv-stringify生成CSV內容
      const output = stringify(data, {
        header: true,
        columns,
        quoted_string: true,
        quoted_empty: true
      });
      
      // 寫入檔案
      await fs.writeFile(filePath, output, 'utf-8');
      
      // 更新緩存
      this.cache.set(filePath, {
        data: [...data], // 深拷貝防止引用問題
        timestamp: Date.now()
      });
    } catch (error) {
      console.error(`寫入CSV檔案失敗: ${error instanceof Error ? error.message : '未知錯誤'}`);
      throw error;
    }
  }