POEditor MCP Server

Instructions

Implementation Reference

• src/server.ts:322-355 (handler)

  The handler function for the 'add_terms_with_translations' tool. It first adds multiple terms to the POEditor project using the poeditor API, then adds translations for those terms in the specified language. It returns a combined result of terms added and translations added.

  async (args) => {
    const id = requireProjectId(args.project_id ?? null);
  
    // Step 1: Add all terms
    const termData = JSON.stringify(args.items.map(item => ({
      term: item.term,
      context: item.context,
      reference: item.reference,
      tags: item.tags
    })));
    const termRes = await poeditor("terms/add", { id: String(id), data: termData });
  
    // Step 2: Add all translations
    const translationPayload = args.items.map(item => ({
      term: item.term,
      context: item.context ?? "",
      translation: item.translation.plural
        ? { plural: item.translation.plural }
        : { content: item.translation.content, fuzzy: item.translation.fuzzy ? 1 : 0 }
    }));
    const translationData = JSON.stringify(translationPayload);
    const translationRes = await poeditor("translations/add", {
      id: String(id),
      language: args.language,
      data: translationData
    });
  
    // Return combined result
    const result = {
      terms_added: termRes.result?.terms ?? termRes.result,
      translations_added: translationRes.result ?? {}
    };
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/server.ts:82-101 (schema)

  Zod schema defining the input parameters for the add_terms_with_translations tool: optional project_id, required language code, and an array of items each with term details and translation (supporting singular, fuzzy, and plural forms).

  const AddTermsWithTranslationsInput = z.object({
    project_id: z.number().int().positive().optional(),
    language: z.string().min(2),
    items: z.array(z.object({
      term: z.string().min(1),
      context: z.string().optional(),
      reference: z.string().optional(),
      tags: z.array(z.string()).optional(),
      translation: z.object({
        content: z.string().default(""),
        fuzzy: z.boolean().optional(),
        plural: z.object({
          one: z.string().optional(),
          few: z.string().optional(),
          many: z.string().optional(),
          other: z.string().optional()
        }).partial().optional()
      })
    })).min(1)
  });

• src/server.ts:318-356 (registration)

  Registration of the 'add_terms_with_translations' tool using server.tool(), providing the tool name, description, input schema, and inline handler function.

  server.tool(
    "add_terms_with_translations",
    "PREFERRED METHOD: Create multiple new terms and add their translations in one operation. Use this instead of calling add_terms followed by add_translations separately. This ensures terms and translations are properly linked (especially important when using context).",
    AddTermsWithTranslationsInput.shape,
    async (args) => {
      const id = requireProjectId(args.project_id ?? null);
  
      // Step 1: Add all terms
      const termData = JSON.stringify(args.items.map(item => ({
        term: item.term,
        context: item.context,
        reference: item.reference,
        tags: item.tags
      })));
      const termRes = await poeditor("terms/add", { id: String(id), data: termData });
  
      // Step 2: Add all translations
      const translationPayload = args.items.map(item => ({
        term: item.term,
        context: item.context ?? "",
        translation: item.translation.plural
          ? { plural: item.translation.plural }
          : { content: item.translation.content, fuzzy: item.translation.fuzzy ? 1 : 0 }
      }));
      const translationData = JSON.stringify(translationPayload);
      const translationRes = await poeditor("translations/add", {
        id: String(id),
        language: args.language,
        data: translationData
      });
  
      // Return combined result
      const result = {
        terms_added: termRes.result?.terms ?? termRes.result,
        translations_added: translationRes.result ?? {}
      };
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );