localization-mcp-server 1.0.0

package/src/tools/project-management.ts

@@ -0,0 +1,517 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, apiPost, ApiError } from "../api-client.js";
+import { logWrite } from "../logger.js";
+
+interface NamespaceCreated {
+  id: string;
+  slug: string;
+}
+
+interface LocaleCreated {
+  id: string;
+  code: string;
+  isDefault: boolean;
+}
+
+interface TranslationEntry {
+  key: string;
+  values: Record<string, string>;
+  createdAt: string;
+}
+
+interface EntriesPage {
+  data: TranslationEntry[];
+  meta: { total: number; page: number; limit: number; totalPages: number };
+}
+
+export function registerProjectManagementTools(server: McpServer): void {
+  // ─── create_namespace ──────────────────────────────────────────────────────
+  server.tool(
+    "create_namespace",
+    [
+      "Create a new namespace in a project.",
+      "IMPORTANT: Call get_project_details first and check existing namespaces before using this tool.",
+      "Reuse an existing namespace whenever context makes the target clear.",
+      "Do NOT create a new namespace just because the request did not name one explicitly.",
+      "Creating a namespace is an architectural decision — it must be justified.",
+      "You MUST provide a non-empty reason explaining why no existing namespace fits.",
+      "If you cannot state a clear reason, do not create — ask the user instead.",
+      "Namespace slugs must be lowercase alphanumeric with dashes.",
+    ].join(" "),
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z
+        .string()
+        .regex(/^[a-z0-9-]+$/, "Namespace slug must be lowercase alphanumeric with dashes")
+        .describe("Namespace slug (e.g. 'expenses', 'mobile-v2')"),
+      reason: z
+        .string()
+        .min(10, "Reason must be at least 10 characters — explain why no existing namespace fits")
+        .describe(
+          "Why a new namespace is needed. Mention which existing namespaces you checked and why they do not fit. " +
+          "Example: 'Project has no namespaces yet' or 'Existing: common, backoffice. This feature (payments) is a separate domain with its own release cadence.'",
+        ),
+    },
+    async ({ projectSlug, namespace, reason }) => {
+      // Soft guard: fetch existing namespaces and warn if any exist without a strong reason.
+      let existingNamespaces: string[] = [];
+      try {
+        const project = await apiGet<{ namespaces: string[] }>(`/translations/projects/${projectSlug}`);
+        existingNamespaces = project.namespaces;
+      } catch {
+        // If we can't fetch, proceed — backend will enforce access control.
+      }
+
+      try {
+        const created = await apiPost<NamespaceCreated>(
+          `/translations/projects/${projectSlug}/namespaces`,
+          { slug: namespace },
+        );
+        logWrite("create_namespace", { projectSlug, namespace, reason, existingNamespaces }, created);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: [
+                `Created namespace: ${projectSlug}/${namespace}`,
+                existingNamespaces.length > 0
+                  ? `Existing namespaces at time of creation: ${existingNamespaces.join(", ")}`
+                  : `This is the first namespace in the project.`,
+                `Reason provided: ${reason}`,
+                ``,
+                `The namespace is empty. Use set_translation to add keys, or bulk_import to load from a JSON map.`,
+                `Remember to init_sandbox after creating the namespace if you plan to use sandbox workflow.`,
+              ].join("\n"),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+
+  // ─── create_locale ─────────────────────────────────────────────────────────
+  server.tool(
+    "create_locale",
+    [
+      "Add a locale to a project.",
+      "Use full BCP 47 codes: 'nb-NO', 'da-DK', 'sv', 'en', 'uk'.",
+      "Do NOT use short codes like 'no' or 'da' — they are not stored on the server.",
+      "After adding a locale, use get_namespace_coverage to see fill gaps, then bulk_set_locale to fill them.",
+    ].join(" "),
+    {
+      projectSlug: z.string().describe("Project slug"),
+      code: z
+        .string()
+        .describe("BCP 47 locale code (e.g. 'nb-NO', 'da-DK', 'sv', 'uk')"),
+      isDefault: z
+        .boolean()
+        .default(false)
+        .describe("Whether this is the default locale for the project"),
+    },
+    async ({ projectSlug, code, isDefault }) => {
+      try {
+        // Fetch existing namespaces to guide the next step.
+        let namespaces: string[] = [];
+        try {
+          const project = await apiGet<{ namespaces: string[] }>(`/translations/projects/${projectSlug}`);
+          namespaces = project.namespaces;
+        } catch {
+          // Non-fatal — just skip the hint.
+        }
+
+        const created = await apiPost<LocaleCreated>(
+          `/translations/projects/${projectSlug}/locales`,
+          { code, isDefault },
+        );
+        logWrite("create_locale", { projectSlug, code, isDefault }, created);
+
+        const nextSteps =
+          namespaces.length > 0
+            ? [
+                ``,
+                `Next steps to fill translations for "${code}":`,
+                `1. get_namespace_coverage for each namespace to see fill gaps`,
+                `   Namespaces: ${namespaces.join(", ")}`,
+                `2. list_translations with missingLocale="${code}" to find keys needing translation`,
+                `3. bulk_set_locale to fill many keys at once for "${code}"`,
+                `   Or: set_translation for individual keys`,
+              ]
+            : [``, `No namespaces exist yet — create a namespace first, then add translations.`];
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: [
+                `Added locale: ${code}${isDefault ? " (default)" : ""} to project ${projectSlug}`,
+                ...nextSteps,
+              ].join("\n"),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+
+  // ─── export_namespace ──────────────────────────────────────────────────────
+  server.tool(
+    "export_namespace",
+    "Export all translation keys for a namespace as a flat JSON map, per locale. Use this to see the full content of a namespace, compare before/after migration, or get the data needed for bulk_import.",
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().describe("Namespace slug"),
+      env: z
+        .enum(["sandbox", "production"])
+        .default("production")
+        .describe("Which environment to export from (default: production)"),
+      locale: z
+        .string()
+        .optional()
+        .describe("Export only this locale. If omitted, exports all locales."),
+    },
+    async ({ projectSlug, namespace, env, locale }) => {
+      try {
+        // Fetch project locales
+        const project = await apiGet<{ locales: { code: string; isDefault: boolean }[]; namespaces: string[] }>(
+          `/translations/projects/${projectSlug}`,
+        );
+
+        const targetLocales = locale ? [locale] : project.locales.map((l) => l.code);
+        const basePath =
+          env === "sandbox"
+            ? `/translations/projects/${projectSlug}/sandbox/namespaces/${namespace}/entries`
+            : `/translations/projects/${projectSlug}/namespaces/${namespace}/entries`;
+
+        // Fetch all pages
+        const allEntries: TranslationEntry[] = [];
+        let page = 1;
+        while (true) {
+          const data = await apiGet<EntriesPage>(basePath, { page, limit: 100 });
+          allEntries.push(...data.data);
+          if (page >= data.meta.totalPages) break;
+          page++;
+        }
+
+        if (allEntries.length === 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Namespace ${projectSlug}/${namespace} [${env}] is empty.`,
+              },
+            ],
+          };
+        }
+
+        // Build per-locale maps
+        const result: Record<string, Record<string, string>> = {};
+        for (const loc of targetLocales) {
+          result[loc] = {};
+          for (const entry of allEntries) {
+            if (entry.values[loc] !== undefined) {
+              result[loc][entry.key] = entry.values[loc];
+            }
+          }
+        }
+
+        const lines = [
+          `Export: ${projectSlug}/${namespace} [${env}]`,
+          `Keys: ${allEntries.length}`,
+          `Locales: ${targetLocales.join(", ")}`,
+          ``,
+        ];
+
+        for (const [loc, map] of Object.entries(result)) {
+          const count = Object.keys(map).length;
+          const missing = allEntries.length - count;
+          lines.push(`[${loc}]: ${count} keys${missing > 0 ? ` (${missing} missing)` : ""}`);
+        }
+
+        lines.push(``, `JSON export:`);
+        lines.push(JSON.stringify(result, null, 2));
+
+        return {
+          content: [{ type: "text" as const, text: lines.join("\n") }],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+
+  // ─── bulk_import ───────────────────────────────────────────────────────────
+  server.tool(
+    "bulk_import",
+    "Import multiple translation keys into the sandbox at once from a JSON map. Input format: { \"locale\": { \"key\": \"value\" } }. All writes go to sandbox — production is unchanged until you promote. Use this to migrate a module's local translation files to the server.",
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().describe("Namespace slug — must already exist (use create_namespace first)"),
+      translations: z
+        .record(
+          z.string(),
+          z.record(z.string(), z.string()),
+        )
+        .describe('Locale → key → value map. Example: { "en": { "save": "Save" }, "nb-NO": { "save": "Lagre" } }'),
+      dryRun: z
+        .boolean()
+        .default(false)
+        .describe("If true, validate and preview what would be imported without writing anything"),
+    },
+    async ({ projectSlug, namespace, translations, dryRun }) => {
+      try {
+        // Validate locale codes against the project. Unknown codes are rejected — not remapped.
+        // Agent must call get_project_details first to get the exact codes for this project.
+        const project = await apiGet<{ locales: { code: string; isDefault: boolean }[] }>(
+          `/translations/projects/${projectSlug}`,
+        );
+        const validLocales = new Set(project.locales.map((l) => l.code));
+        const requestedLocales = Object.keys(translations);
+        const unknownLocales = requestedLocales.filter((l) => !validLocales.has(l));
+
+        if (unknownLocales.length > 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: [
+                  `❌ Import aborted — locale codes do not match the project.`,
+                  ``,
+                  `Unknown codes: ${unknownLocales.map((l) => `"${l}"`).join(", ")}`,
+                  `Valid locales for "${projectSlug}": ${[...validLocales].join(", ")}`,
+                  ``,
+                  `Call get_project_details to get the exact locale codes. Do not guess or remap them.`,
+                  `If the locale does not exist in the project yet, call create_locale first.`,
+                ].join("\n"),
+              },
+            ],
+          };
+        }
+
+        // Collect all unique keys across all locales
+        const allKeys = new Set<string>();
+        for (const localeMap of Object.values(translations)) {
+          for (const key of Object.keys(localeMap)) {
+            allKeys.add(key);
+          }
+        }
+
+        if (dryRun) {
+          const perLocale = requestedLocales.map(
+            (l) => `  ${l}: ${Object.keys(translations[l]).length} values`,
+          );
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: [
+                  `DRY RUN — nothing written`,
+                  ``,
+                  `Would import to sandbox: ${projectSlug}/${namespace}`,
+                  `  Unique keys: ${allKeys.size}`,
+                  `  Locales:`,
+                  ...perLocale,
+                ].join("\n"),
+              },
+            ],
+          };
+        }
+
+        const basePath = `/translations/projects/${projectSlug}/sandbox/namespaces/${namespace}/entries`;
+
+        // Group values per key across all locales, then upsert each key once
+        const keyMap = new Map<string, Record<string, string>>();
+        for (const [locale, localeMap] of Object.entries(translations)) {
+          for (const [key, value] of Object.entries(localeMap)) {
+            if (!keyMap.has(key)) keyMap.set(key, {});
+            keyMap.get(key)![locale] = value;
+          }
+        }
+
+        let created = 0;
+        let updated = 0;
+        let failed = 0;
+        const errors: string[] = [];
+
+        const { apiPatch } = await import("../api-client.js");
+
+        for (const [key, values] of keyMap.entries()) {
+          try {
+            // Try PATCH (update) first — faster if key exists
+            try {
+              await apiPatch<unknown>(`${basePath}/${encodeURIComponent(key)}`, { values });
+              updated++;
+            } catch (patchErr) {
+              if (patchErr instanceof ApiError && patchErr.status === 404) {
+                // Key does not exist yet — create it
+                await apiPost<unknown>(basePath, { key, values });
+                created++;
+              } else {
+                throw patchErr;
+              }
+            }
+          } catch (err) {
+            failed++;
+            if (err instanceof ApiError) {
+              errors.push(`  ${key}: ${err.status} ${err.message}`);
+            } else {
+              errors.push(`  ${key}: ${String(err)}`);
+            }
+            if (failed > 5) {
+              errors.push(`  ... and more errors (stopping early)`);
+              break;
+            }
+          }
+        }
+
+        logWrite("bulk_import", { projectSlug, namespace, keyCount: keyMap.size }, { created, updated, failed });
+
+        const lines = [
+          `Bulk import to sandbox: ${projectSlug}/${namespace}`,
+          `  Created: ${created}`,
+          `  Updated: ${updated}`,
+          `  Failed:  ${failed}`,
+        ];
+
+        if (errors.length > 0) {
+          lines.push(``, `Errors:`, ...errors);
+        }
+
+        lines.push(
+          ``,
+          `Use get_translation_diff to review all pending changes before promoting.`,
+        );
+
+        return {
+          content: [{ type: "text" as const, text: lines.join("\n") }],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+
+  // ─── get_namespace_coverage ────────────────────────────────────────────────
+  server.tool(
+    "get_namespace_coverage",
+    [
+      "Show per-locale fill statistics for a namespace.",
+      "Returns: total keys, how many have a non-empty value for each locale, and coverage percentage.",
+      "Also lists the first 10 keys missing each locale.",
+      "Use this after adding a new locale to understand the fill gap before starting bulk_set_locale.",
+    ].join(" "),
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().describe("Namespace slug"),
+      env: z
+        .enum(["sandbox", "production"])
+        .default("sandbox")
+        .describe("Which environment to analyze (default: sandbox)"),
+    },
+    async ({ projectSlug, namespace, env }) => {
+      try {
+        // Fetch project locales
+        const project = await apiGet<{ locales: { code: string; isDefault: boolean }[] }>(
+          `/translations/projects/${projectSlug}`,
+        );
+        const localeCodes = project.locales.map((l) => l.code);
+
+        if (localeCodes.length === 0) {
+          return {
+            content: [{ type: "text" as const, text: `Project "${projectSlug}" has no locales configured.` }],
+          };
+        }
+
+        // Fetch all entries
+        const basePath =
+          env === "sandbox"
+            ? `/translations/projects/${projectSlug}/sandbox/namespaces/${namespace}/entries`
+            : `/translations/projects/${projectSlug}/namespaces/${namespace}/entries`;
+
+        const allEntries: TranslationEntry[] = [];
+        let page = 1;
+        while (true) {
+          const data = await apiGet<EntriesPage>(basePath, { page, limit: 100 });
+          allEntries.push(...data.data);
+          if (page >= data.meta.totalPages) break;
+          page++;
+        }
+
+        if (allEntries.length === 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Namespace ${projectSlug}/${namespace} [${env}] is empty. No keys to analyze.`,
+              },
+            ],
+          };
+        }
+
+        const totalKeys = allEntries.length;
+
+        // Build per-locale stats
+        const localeStats = localeCodes.map((code) => {
+          const filled = allEntries.filter(
+            (e) => e.values[code] !== undefined && e.values[code].trim() !== "",
+          );
+          const missingKeys = allEntries
+            .filter((e) => !e.values[code] || e.values[code].trim() === "")
+            .map((e) => e.key);
+          const pct = Math.round((filled.length / totalKeys) * 100);
+          return { code, filled: filled.length, missing: missingKeys.length, pct, missingKeys };
+        });
+
+        const lines = [
+          `Namespace coverage: ${projectSlug}/${namespace} [${env}]`,
+          `Total keys: ${totalKeys}`,
+          ``,
+          `Locale coverage:`,
+          ...localeStats.map((s) => {
+            const bar = "█".repeat(Math.round(s.pct / 5)) + "░".repeat(20 - Math.round(s.pct / 5));
+            return `  ${s.code.padEnd(10)} ${bar} ${s.pct}% (${s.filled}/${totalKeys})${s.missing > 0 ? ` — ${s.missing} missing` : ""}`;
+          }),
+        ];
+
+        const incomplete = localeStats.filter((s) => s.missing > 0);
+        if (incomplete.length > 0) {
+          lines.push(``, `Sample missing keys (up to 10 per locale):`);
+          for (const s of incomplete) {
+            if (s.missingKeys.length > 0) {
+              lines.push(`  [${s.code}]:`);
+              s.missingKeys.slice(0, 10).forEach((k) => lines.push(`    • ${k}`));
+              if (s.missingKeys.length > 10) lines.push(`    ... and ${s.missingKeys.length - 10} more`);
+            }
+          }
+          lines.push(
+            ``,
+            `To fill gaps: use list_translations with missingLocale="<code>" then bulk_set_locale.`,
+          );
+        } else {
+          lines.push(``, `All locales are fully covered.`);
+        }
+
+        return {
+          content: [{ type: "text" as const, text: lines.join("\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)}` }],
+  };
+}