POEditor MCP Server

Instructions

Implementation Reference

• src/server.ts:190-240 (handler)

  The handler function for the 'list_terms' tool. It fetches terms from POEditor API, applies optional filters (search, fields), limits, and count-only mode, then returns a JSON-formatted response.

  async (args) => {
    const id = requireProjectId(args.project_id ?? null);
    const form: Record<string, string> = { id: String(id) };
    if (args.language) form.language = args.language;
    const res = await poeditor("terms/list", form);
  
    // Extract term and translation content to reduce response size
    let terms = res.result?.terms?.map((t: any) => ({
      term: t.term,
      context: t.context || undefined,
      translation: t.translation?.content || undefined
    })) ?? [];
  
    // Apply search filter (case-insensitive substring match on term, context, translation)
    if (args.search) {
      const searchLower = args.search.toLowerCase();
      terms = terms.filter((t: any) =>
        t.term?.toLowerCase().includes(searchLower) ||
        t.context?.toLowerCase().includes(searchLower) ||
        t.translation?.toLowerCase().includes(searchLower)
      );
    }
  
    // Apply fields selection
    if (args.fields && args.fields.length > 0) {
      const fieldSet = new Set(args.fields);
      terms = terms.map((t: any) => {
        const filtered: any = {};
        if (fieldSet.has("term")) filtered.term = t.term;
        if (fieldSet.has("context")) filtered.context = t.context;
        if (fieldSet.has("translation")) filtered.translation = t.translation;
        return filtered;
      });
    }
  
    const total = terms.length;
  
    // Return count only if requested
    if (args.count_only) {
      return { content: [{ type: "text", text: JSON.stringify({ total }) }] };
    }
  
    // Apply limit
    if (args.limit && args.limit < terms.length) {
      terms = terms.slice(0, args.limit);
    }
  
    const result = { terms, total };
  
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }

• src/server.ts:64-71 (schema)

  Zod input schema for the 'list_terms' tool defining optional parameters: project_id, language, limit, search, count_only, and fields.

  const ListTermsInput = z.object({
    project_id: z.number().int().positive().optional(),
    language: z.string().optional(),
    limit: z.number().int().positive().optional(),
    search: z.string().optional(),
    count_only: z.boolean().optional(),
    fields: z.array(z.enum(["term", "context", "translation"])).optional()
  });

• src/server.ts:186-241 (registration)

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

  server.tool(
    "list_terms",
    "List all project terms (optionally include translations for a specific language). Returns only term names, contexts, and translation content to minimize response size. Use limit, search, count_only, and fields parameters to reduce token usage.",
    ListTermsInput.shape,
    async (args) => {
      const id = requireProjectId(args.project_id ?? null);
      const form: Record<string, string> = { id: String(id) };
      if (args.language) form.language = args.language;
      const res = await poeditor("terms/list", form);
  
      // Extract term and translation content to reduce response size
      let terms = res.result?.terms?.map((t: any) => ({
        term: t.term,
        context: t.context || undefined,
        translation: t.translation?.content || undefined
      })) ?? [];
  
      // Apply search filter (case-insensitive substring match on term, context, translation)
      if (args.search) {
        const searchLower = args.search.toLowerCase();
        terms = terms.filter((t: any) =>
          t.term?.toLowerCase().includes(searchLower) ||
          t.context?.toLowerCase().includes(searchLower) ||
          t.translation?.toLowerCase().includes(searchLower)
        );
      }
  
      // Apply fields selection
      if (args.fields && args.fields.length > 0) {
        const fieldSet = new Set(args.fields);
        terms = terms.map((t: any) => {
          const filtered: any = {};
          if (fieldSet.has("term")) filtered.term = t.term;
          if (fieldSet.has("context")) filtered.context = t.context;
          if (fieldSet.has("translation")) filtered.translation = t.translation;
          return filtered;
        });
      }
  
      const total = terms.length;
  
      // Return count only if requested
      if (args.count_only) {
        return { content: [{ type: "text", text: JSON.stringify({ total }) }] };
      }
  
      // Apply limit
      if (args.limit && args.limit < terms.length) {
        terms = terms.slice(0, args.limit);
      }
  
      const result = { terms, total };
  
      return { content: [{ type: "text", text: JSON.stringify(result) }] };
    }
  );