POEditor MCP Server

Instructions

Implementation Reference

• src/server.ts:173-182 (handler)

  The asynchronous handler function that implements the core logic of the 'update_translations' tool. It constructs a payload from the input items, calls the POEditor 'translations/update' API endpoint via the poeditor helper, and returns the result.
  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/update", { 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 (TranslationsInput) that validates the input parameters for the 'update_translations' tool, including optional project_id, required language, and array of translation items with term, context, content, fuzzy flag, and optional plurals.
  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:169-184 (registration)

  The server.tool() call that registers the 'update_translations' tool with the MCP server, specifying its name, description, input schema, and handler function.
  server.tool( "update_translations", "Update/overwrite translations for a language. 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/update", { 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 by the 'update_translations' handler to resolve the project_id from arguments 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; }
• src/server.ts:19-38 (helper)

  Core helper function that makes authenticated POST requests to the POEditor API, parses responses, and handles errors. Used by the 'update_translations' handler.
  export async function poeditor(endpoint: string, form: Record<string, string>) { const body = new URLSearchParams({ api_token: API_TOKEN!, ...form }); const { body: resBody } = await request(`${API_BASE}/${endpoint}`, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: body.toString() }); const text = await resBody.text(); let json: any; try { json = JSON.parse(text); } catch (e) { throw new Error(`POEditor: invalid JSON response: ${text}`); } const status = json?.response?.status; if (status !== "success") { const code = json?.response?.code; const message = json?.response?.message || "Unknown POEditor error"; throw new Error(`POEditor API error ${code ?? ""}: ${message}`); } return json; }