POEditor MCP Server

Instructions

Implementation Reference

• src/server.ts:156-166 (handler)

  The handler function for the add_translations tool. It processes the input arguments, constructs a payload for multiple translation items (handling singular and plural translations), stringifies it, and calls the POEditor API 'translations/add' endpoint.

  async (args) => {
    const id = requireProjectId(args.project_id ?? null);
    const payload = args.items.map((i) => ({
      term: i.term,
      context: i.context ?? "",
      translation: i.plural ? { plural: i.plural } : { content: i.content, fuzzy: i.fuzzy ? 1 : 0 }
    }));
    const data = JSON.stringify(payload);
    const res = await poeditor("translations/add", { id: String(id), language: args.language, data });
    return { content: [{ type: "text", text: JSON.stringify(res.result ?? {}, null, 2) }] };
  }

• src/server.ts:47-62 (schema)

  Zod schema defining the input structure for the add_translations tool (and update_translations). Includes optional project_id, required language code, and array of translation items with term, optional context, content (default empty), optional fuzzy flag, and optional plural forms.

  const TranslationsInput = 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(),
      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:152-167 (registration)

  Registration of the add_translations tool on the MCP server using server.tool(), including name, description, input schema, and inline handler function.

  server.tool(
    "add_translations",
    "Add translations for EXISTING terms in a language (does not overwrite). Use this only when terms already exist. If you need to create new terms AND add their translations, prefer using add_terms_with_translations instead. Important: if a term was created with a context, you must provide the same context value to match that term.",
    TranslationsInput.shape,
    async (args) => {
      const id = requireProjectId(args.project_id ?? null);
      const payload = args.items.map((i) => ({
        term: i.term,
        context: i.context ?? "",
        translation: i.plural ? { plural: i.plural } : { content: i.content, fuzzy: i.fuzzy ? 1 : 0 }
      }));
      const data = JSON.stringify(payload);
      const res = await poeditor("translations/add", { id: String(id), language: args.language, data });
      return { content: [{ type: "text", text: JSON.stringify(res.result ?? {}, null, 2) }] };
    }
  );

• src/server.ts:40-44 (helper)

  Helper function used in the handler to resolve or require the project ID from args or environment variable.

  function requireProjectId(argProjectId?: number | null) {
    const id = argProjectId ?? (PROJECT_ID ? Number(PROJECT_ID) : null);
    if (!id) throw new Error("project_id is required (either pass it to the tool or set POEDITOR_PROJECT_ID)");
    return id;
  }