localization-mcp-server 1.0.0

package/src/tools/sandbox-writes.ts

@@ -0,0 +1,321 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, apiPost, apiPatch, apiDelete, ApiError } from "../api-client.js";
+import { assertSandboxWrite } from "../permissions.js";
+import { logWrite } from "../logger.js";
+
+interface EntryRow {
+  key: string;
+  createdAt: string;
+  values: Record<string, string>;
+}
+
+interface ProjectDetails {
+  locales: { code: string; isDefault: boolean }[];
+  namespaces: string[];
+}
+
+/**
+ * Validates that all requested locale codes exist in the project.
+ * Returns valid and unknown sets so callers can surface errors to the agent.
+ *
+ * Does NOT remap or normalise codes — unknown codes are rejected, not guessed.
+ */
+async function validateLocales(
+  projectSlug: string,
+  requestedLocales: string[],
+): Promise<{ valid: string[]; unknown: string[] }> {
+  try {
+    const project = await apiGet<ProjectDetails>(`/translations/projects/${projectSlug}`);
+    const projectLocales = new Set(project.locales.map((l) => l.code));
+    const valid = requestedLocales.filter((l) => projectLocales.has(l));
+    const unknown = requestedLocales.filter((l) => !projectLocales.has(l));
+    return { valid, unknown };
+  } catch {
+    // If we can't fetch the project, proceed — the backend will reject invalid codes.
+    return { valid: requestedLocales, unknown: [] };
+  }
+}
+
+export function registerSandboxWriteTools(server: McpServer): void {
+  // ─── set_translation ────────────────────────────────────────────────────────
+  server.tool(
+    "set_translation",
+    [
+      "Create or update a translation key in the sandbox (upsert).",
+      "PARTIAL LOCALE UPDATE: Pass only the locale(s) you want to update — other locales are untouched.",
+      "Example: values={ 'nb-NO': 'Lagre' } updates only Norwegian, leaving en/sv/da-DK unchanged.",
+      "This is the correct flow for adding a single locale to an existing key.",
+      "Locale codes must exactly match the project's locale codes — call get_project_details first.",
+      "Invalid codes are rejected, not auto-corrected. Always writes to sandbox only.",
+      "For updating many keys at once, use bulk_set_locale (single locale) or bulk_import (multiple locales).",
+    ].join(" "),
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().describe("Namespace slug (e.g. 'backoffice-translations')"),
+      key: z
+        .string()
+        .regex(/^[a-zA-Z0-9._-]+$/, "Key must contain only letters, digits, dots, underscores or dashes")
+        .describe("Translation key name (e.g. 'button.save', 'errors.notFound')"),
+      values: z
+        .record(z.string(), z.string())
+        .describe(
+          "Locale-to-value map. Pass only the locales you want to set — other locales are preserved. " +
+          "Locale codes must match the project exactly (e.g. { \"nb-NO\": \"Lagre\" } or { \"nb-NO\": \"Lagre\", \"en\": \"Save\" }).",
+        ),
+    },
+    async ({ projectSlug, namespace, key, values }) => {
+      assertSandboxWrite("sandbox");
+
+      // Validate locale codes against project — unknown codes are rejected.
+      const { unknown: unknownLocales } = await validateLocales(projectSlug, Object.keys(values));
+      if (unknownLocales.length > 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: [
+                `❌ Invalid locale codes — call get_project_details to get the exact codes for this project.`,
+                ``,
+                `Unknown codes: ${unknownLocales.map((l) => `"${l}"`).join(", ")}`,
+                ``,
+                `Do not guess or remap locale codes. Use only what get_project_details returns.`,
+              ].join("\n"),
+            },
+          ],
+        };
+      }
+
+      const basePath = `/translations/projects/${projectSlug}/sandbox/namespaces/${namespace}/entries`;
+
+      try {
+        const updated = await apiPatch<EntryRow>(`${basePath}/${encodeURIComponent(key)}`, { values });
+        logWrite("set_translation", { projectSlug, namespace, key, action: "updated" }, updated);
+        return successContent("Updated", projectSlug, namespace, key, updated.values);
+      } catch (updateError) {
+        if (!(updateError instanceof ApiError) || updateError.status !== 404) {
+          return errorContent(updateError);
+        }
+
+        try {
+          const created = await apiPost<EntryRow>(basePath, { key, values });
+          logWrite("set_translation", { projectSlug, namespace, key, action: "created" }, created);
+          return successContent("Created", projectSlug, namespace, key, created.values);
+        } catch (createError) {
+          if (createError instanceof ApiError && createError.status === 409) {
+            try {
+              const retried = await apiPatch<EntryRow>(`${basePath}/${encodeURIComponent(key)}`, { values });
+              logWrite("set_translation", { projectSlug, namespace, key, action: "updated" }, retried);
+              return successContent("Updated", projectSlug, namespace, key, retried.values);
+            } catch (retryError) {
+              return errorContent(retryError);
+            }
+          }
+          return errorContent(createError);
+        }
+      }
+    },
+  );
+
+  // ─── bulk_set_locale ────────────────────────────────────────────────────────
+  server.tool(
+    "bulk_set_locale",
+    [
+      "Bulk upsert multiple keys for a SINGLE locale in the sandbox.",
+      "Designed for the new-locale fill workflow: after adding a locale, use this to fill many keys at once.",
+      "Only the specified locale is written — all other locales on each key remain untouched.",
+      "Use list_translations with missingLocale to get the list of keys to fill.",
+      "For multi-locale bulk import use bulk_import instead.",
+    ].join(" "),
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().describe("Namespace slug — must already exist"),
+      locale: z
+        .string()
+        .describe("The single locale to write values for (e.g. 'nb-NO'). Must match the project's locale codes exactly."),
+      entries: z
+        .array(
+          z.object({
+            key: z
+              .string()
+              .regex(/^[a-zA-Z0-9._-]+$/, "Key must contain only letters, digits, dots, underscores or dashes"),
+            value: z.string(),
+          }),
+        )
+        .min(1)
+        .describe("Array of { key, value } pairs to upsert for the given locale."),
+      dryRun: z
+        .boolean()
+        .default(false)
+        .describe("If true, preview what would be written without actually writing"),
+    },
+    async ({ projectSlug, namespace, locale, entries, dryRun }) => {
+      assertSandboxWrite("sandbox");
+
+      // Validate locale code against project.
+      const { unknown: unknownLocales } = await validateLocales(projectSlug, [locale]);
+      if (unknownLocales.length > 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: [
+                `❌ Invalid locale code "${locale}" — call get_project_details to get the exact codes for this project.`,
+                `Do not guess or remap locale codes.`,
+              ].join("\n"),
+            },
+          ],
+        };
+      }
+
+      if (dryRun) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: [
+                `DRY RUN — nothing written`,
+                ``,
+                `Would write to sandbox: ${projectSlug}/${namespace} [locale: ${locale}]`,
+                `  Keys: ${entries.length}`,
+                ``,
+                entries.slice(0, 10).map((e) => `  ${e.key}: "${e.value}"`).join("\n"),
+                entries.length > 10 ? `  ... and ${entries.length - 10} more` : "",
+              ].filter(Boolean).join("\n"),
+            },
+          ],
+        };
+      }
+
+      const basePath = `/translations/projects/${projectSlug}/sandbox/namespaces/${namespace}/entries`;
+
+      let created = 0;
+      let updated = 0;
+      let failed = 0;
+      const errors: string[] = [];
+
+      for (const { key, value } of entries) {
+        try {
+          try {
+            await apiPatch<unknown>(`${basePath}/${encodeURIComponent(key)}`, { values: { [locale]: value } });
+            updated++;
+          } catch (patchErr) {
+            if (patchErr instanceof ApiError && patchErr.status === 404) {
+              await apiPost<unknown>(basePath, { key, values: { [locale]: value } });
+              created++;
+            } else {
+              throw patchErr;
+            }
+          }
+        } catch (err) {
+          failed++;
+          errors.push(`  ${key}: ${err instanceof ApiError ? `${err.status} ${err.message}` : String(err)}`);
+          if (failed > 5) {
+            errors.push(`  ... stopping early after ${failed} errors`);
+            break;
+          }
+        }
+      }
+
+      logWrite("bulk_set_locale", { projectSlug, namespace, locale, keyCount: entries.length }, { created, updated, failed });
+
+      const lines = [
+        `Bulk set locale "${locale}" in sandbox: ${projectSlug}/${namespace}`,
+        `  Created: ${created}`,
+        `  Updated: ${updated}`,
+        `  Failed:  ${failed}`,
+      ];
+
+      if (errors.length > 0) {
+        lines.push(``, `Errors:`, ...errors);
+      }
+
+      lines.push(
+        ``,
+        `Use validate_translations or get_translation_diff to review pending changes.`,
+        `Use list_translations with missingLocale="${locale}" to check remaining gaps.`,
+      );
+
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+      };
+    },
+  );
+
+  // ─── delete_translation ─────────────────────────────────────────────────────
+  server.tool(
+    "delete_translation",
+    "Delete a translation key from the sandbox (soft delete). The key remains in production until you promote the sandbox.",
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().describe("Namespace slug"),
+      key: z.string().describe("Translation key to delete"),
+    },
+    async ({ projectSlug, namespace, key }) => {
+      assertSandboxWrite("sandbox");
+
+      try {
+        await apiDelete(
+          `/translations/projects/${projectSlug}/sandbox/namespaces/${namespace}/entries/${encodeURIComponent(key)}`,
+        );
+
+        logWrite("delete_translation", { projectSlug, namespace, key }, { deleted: true });
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: [
+                `Deleted sandbox key: ${projectSlug}/${namespace}/${key}`,
+                ``,
+                `Marked for deletion in sandbox. Removed from production only after promote via Admin UI.`,
+                `Use get_translation_diff to review the pending deletion.`,
+              ].join("\n"),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+}
+
+function successContent(
+  action: "Created" | "Updated",
+  projectSlug: string,
+  namespace: string,
+  key: string,
+  values: Record<string, string>,
+): { content: { type: "text"; text: string }[] } {
+  const valueLines = Object.entries(values)
+    .map(([locale, val]) => `  [${locale}] ${val || "(empty)"}`)
+    .join("\n");
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: [
+          `${action} sandbox key: ${projectSlug}/${namespace}/${key}`,
+          ``,
+          `Values saved in sandbox:`,
+          valueLines || "  (no values set)",
+          ``,
+          `Production is unchanged. Use preview_push_to_production to review before promoting.`,
+        ].join("\n"),
+      },
+    ],
+  };
+}
+
+function errorContent(error: unknown): { content: { type: "text"; text: string }[] } {
+  if (error instanceof ApiError) {
+    return {
+      content: [{ type: "text" as const, text: `Error ${error.status}: ${error.message}` }],
+    };
+  }
+  return {
+    content: [{ type: "text" as const, text: `Unexpected error: ${String(error)}` }],
+  };
+}

package/src/tools/snapshots.ts

@@ -0,0 +1,68 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, ApiError } from "../api-client.js";
+
+interface SnapshotItem {
+  id: string;
+  label: string | null;
+  createdAt: string;
+  entryCount: number;
+}
+
+export function registerSnapshotTools(server: McpServer): void {
+  server.tool(
+    "list_snapshots",
+    "List available production snapshots for a project. Snapshots are created automatically before each push to production and can be used to revert.",
+    {
+      projectSlug: z.string().describe("Project slug"),
+    },
+    async ({ projectSlug }) => {
+      try {
+        const snapshots = await apiGet<SnapshotItem[]>(
+          `/translations/projects/${projectSlug}/sandbox/snapshots`,
+        );
+
+        if (snapshots.length === 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `No snapshots available for project "${projectSlug}".\n\nSnapshots are created automatically when sandbox changes are pushed to production.`,
+              },
+            ],
+          };
+        }
+
+        const rows = snapshots.map((s, i) => {
+          const date = new Date(s.createdAt).toLocaleString("en-GB", {
+            dateStyle: "short",
+            timeStyle: "short",
+          });
+          return `${i + 1}. ${s.label ?? "(no label)"}\n   ID: ${s.id}\n   Created: ${date}\n   Entries: ${s.entryCount}`;
+        });
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Snapshots for "${projectSlug}" (${snapshots.length} available, max 5):\n\n${rows.join("\n\n")}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+}
+
+function errorContent(error: unknown): { content: { type: "text"; text: string }[] } {
+  if (error instanceof ApiError) {
+    return {
+      content: [{ type: "text" as const, text: `Error ${error.status}: ${error.message}` }],
+    };
+  }
+  return {
+    content: [{ type: "text" as const, text: `Unexpected error: ${String(error)}` }],
+  };
+}

package/src/tools/translations.ts

@@ -0,0 +1,167 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, ApiError } from "../api-client.js";
+
+interface TranslationEntry {
+  key: string;
+  values: Record<string, string>;
+  createdAt: string;
+}
+
+interface EntriesResponse {
+  data: TranslationEntry[];
+  meta: { total: number; page: number; limit: number; totalPages: number };
+}
+
+export function registerTranslationTools(server: McpServer): void {
+  server.tool(
+    "list_translations",
+    [
+      "Browse translation entries in a namespace.",
+      "Use env='sandbox' (default) to see the working sandbox view, or env='production' to see what is currently live.",
+      "Supports pagination and full-text search.",
+      "Use missingLocale to find all keys that do not have a value for a specific locale — essential for the new-locale fill workflow.",
+      "Example: missingLocale='nb-NO' returns only keys where Norwegian is empty or absent.",
+    ].join(" "),
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().describe("Namespace slug (e.g. 'common', 'backoffice')"),
+      env: z
+        .enum(["sandbox", "production"])
+        .default("sandbox")
+        .describe("Which environment to read from. Default: sandbox (the editable working copy)."),
+      page: z.number().int().min(1).default(1).describe("Page number (default: 1)"),
+      limit: z.number().int().min(1).max(100).default(50).describe("Items per page (default: 50, max: 100)"),
+      search: z.string().optional().describe("Search string (min 2 chars) — searches keys and values"),
+      searchLocale: z.string().optional().describe("Restrict value search to a specific locale (e.g. 'en')"),
+      missingLocale: z
+        .string()
+        .optional()
+        .describe(
+          "Return only entries where this locale has no value or an empty value. " +
+          "Use this to find gaps after adding a new locale. Locale code must match the project exactly.",
+        ),
+      sortBy: z.enum(["key", "createdAt"]).default("key").describe("Sort field"),
+      sortOrder: z.enum(["asc", "desc"]).default("asc").describe("Sort direction"),
+    },
+    async ({ projectSlug, namespace, env, page, limit, search, searchLocale, missingLocale, sortBy, sortOrder }) => {
+      try {
+        // When filtering by missingLocale we must fetch all pages to filter correctly,
+        // then re-paginate manually. Otherwise we fetch a single page and return it directly.
+        const basePath =
+          env === "sandbox"
+            ? `/translations/projects/${projectSlug}/sandbox/namespaces/${namespace}/entries`
+            : `/translations/projects/${projectSlug}/namespaces/${namespace}/entries`;
+
+        if (missingLocale) {
+          // Fetch all pages so we can filter by missing locale correctly.
+          const allEntries: TranslationEntry[] = [];
+          let currentPage = 1;
+          while (true) {
+            const params: Record<string, unknown> = { page: currentPage, limit: 100, sortBy, sortOrder };
+            if (search) params.search = search;
+            const data = await apiGet<EntriesResponse>(basePath, params);
+            allEntries.push(...data.data);
+            if (currentPage >= data.meta.totalPages) break;
+            currentPage++;
+          }
+
+          const missing = allEntries.filter(
+            (e) => !e.values[missingLocale] || e.values[missingLocale].trim() === "",
+          );
+
+          if (missing.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text:
+                    `No missing entries for locale "${missingLocale}" in ${projectSlug}/${namespace} [${env}]. ` +
+                    `All ${allEntries.length} keys have a value for this locale.`,
+                },
+              ],
+            };
+          }
+
+          const rows = missing.map((entry) => {
+            const otherValues = Object.entries(entry.values)
+              .filter(([l]) => l !== missingLocale)
+              .slice(0, 3)
+              .map(([locale, value]) => `  [${locale}] ${value || "(empty)"}`)
+              .join("\n");
+            return `${entry.key}:${otherValues ? `\n${otherValues}` : ""}`;
+          });
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: [
+                  `Keys missing "${missingLocale}" in ${projectSlug}/${namespace} [${env}]: ${missing.length} of ${allEntries.length} total`,
+                  ``,
+                  `Use bulk_set_locale or set_translation to fill these values.`,
+                  ``,
+                  rows.join("\n\n"),
+                ].join("\n"),
+              },
+            ],
+          };
+        }
+
+        // Normal paginated fetch (no missingLocale filter).
+        const params: Record<string, unknown> = { page, limit, sortBy, sortOrder };
+        if (search) params.search = search;
+        if (searchLocale) params.searchLocale = searchLocale;
+
+        const data = await apiGet<EntriesResponse>(basePath, params);
+
+        if (data.data.length === 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text:
+                  `No entries found in ${projectSlug}/${namespace} [${env}]` +
+                  (search ? ` matching "${search}"` : "") +
+                  `. Total: 0.`,
+              },
+            ],
+          };
+        }
+
+        const rows = data.data.map((entry) => {
+          const valuesStr = Object.entries(entry.values)
+            .map(([locale, value]) => `  [${locale}] ${value || "(empty)"}`)
+            .join("\n");
+          return `${entry.key}:\n${valuesStr}`;
+        });
+
+        const header =
+          `Entries in ${projectSlug}/${namespace} [${env}] — page ${data.meta.page}, ` +
+          `showing ${data.data.length} of ${data.meta.total}${search ? ` (search: "${search}")` : ""}`;
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `${header}\n\n${rows.join("\n\n")}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+}
+
+function errorContent(error: unknown): { content: { type: "text"; text: string }[] } {
+  if (error instanceof ApiError) {
+    return {
+      content: [{ type: "text" as const, text: `Error ${error.status}: ${error.message}` }],
+    };
+  }
+  return {
+    content: [{ type: "text" as const, text: `Unexpected error: ${String(error)}` }],
+  };
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}