localization-mcp-server 1.0.0

package/src/api-client.ts

@@ -0,0 +1,68 @@
+import axios, { AxiosError } from "axios";
+
+const client = axios.create({
+  baseURL: process.env.BACKEND_URL ?? "http://localhost:8080",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${process.env.MCP_TOKEN ?? ""}`,
+  },
+  timeout: 30_000,
+});
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly message: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+function handleError(error: unknown): never {
+  if (error instanceof AxiosError) {
+    const status = error.response?.status ?? 0;
+    const message =
+      (error.response?.data as { message?: string })?.message ??
+      error.message ??
+      "Unknown API error";
+    throw new ApiError(status, String(message), error.response?.data);
+  }
+  throw error;
+}
+
+export async function apiGet<T>(path: string, params?: Record<string, unknown>): Promise<T> {
+  try {
+    const response = await client.get<T>(path, { params });
+    return response.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function apiPost<T>(path: string, data?: unknown): Promise<T> {
+  try {
+    const response = await client.post<T>(path, data);
+    return response.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function apiPatch<T>(path: string, data?: unknown): Promise<T> {
+  try {
+    const response = await client.patch<T>(path, data);
+    return response.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function apiDelete(path: string): Promise<void> {
+  try {
+    await client.delete(path);
+  } catch (error) {
+    handleError(error);
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+
+// Load .env from the mcp-server directory (one level above dist/)
+if (process.env.NODE_ENV !== "production") {
+  const { default: dotenv } = await import("dotenv");
+  const { fileURLToPath } = await import("url");
+  const { dirname, resolve } = await import("path");
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  dotenv.config({ path: resolve(__dirname, "..", ".env") });
+}
+
+if (!process.env.MCP_TOKEN) {
+  process.stderr.write(
+    "[localization-mcp] WARNING: MCP_TOKEN is not set. All API calls will fail with 401.\n",
+  );
+}
+
+if (!process.env.BACKEND_URL) {
+  process.stderr.write(
+    "[localization-mcp] BACKEND_URL not set, defaulting to http://localhost:3000\n",
+  );
+}
+
+const server = createServer();
+const transport = new StdioServerTransport();
+
+await server.connect(transport);

package/src/logger.ts

@@ -0,0 +1,31 @@
+import fs from "fs";
+import path from "path";
+
+const LOG_FILE =
+  process.env.AUDIT_LOG_PATH ?? path.join(process.cwd(), "mcp-audit.log");
+
+export interface AuditEntry {
+  timestamp: string;
+  operation: string;
+  params: Record<string, unknown>;
+  result: unknown;
+}
+
+export function logWrite(
+  operation: string,
+  params: Record<string, unknown>,
+  result: unknown,
+): void {
+  const entry: AuditEntry = {
+    timestamp: new Date().toISOString(),
+    operation,
+    params,
+    result,
+  };
+  try {
+    fs.appendFileSync(LOG_FILE, JSON.stringify(entry) + "\n");
+  } catch {
+    // Log to stderr if file write fails — do not crash the MCP server
+    process.stderr.write(`[audit] Failed to write to ${LOG_FILE}: ${JSON.stringify(entry)}\n`);
+  }
+}

package/src/permissions.ts

@@ -0,0 +1,89 @@
+/**
+ * MCP Server — Environment Access Policy
+ *
+ * Policy:
+ *   sandbox    → full read + write (all tools available)
+ *   production → read-only (no production-write tools exist by design)
+ *
+ * This file is the single source of truth for which tools write where.
+ * All write tools are hardcoded to sandbox API endpoints.
+ * There are no production-write endpoints in this MCP server — intentionally.
+ *
+ * ── Where this logic lives ───────────────────────────────────────────────────
+ *   mcp-server/src/permissions.ts       ← this file (policy + registry + guard)
+ *   mcp-server/src/tools/sandbox-writes.ts  ← write tools (always sandbox)
+ *   mcp-server/src/tools/translations.ts    ← list_translations (env param)
+ *
+ * ── How to verify ────────────────────────────────────────────────────────────
+ *   Sandbox write:
+ *     set_translation({ projectSlug, namespace, key, values: { en: "Hello" } })
+ *     → should succeed and appear in get_translation_diff
+ *
+ *   Production read-only:
+ *     list_translations({ ..., env: "production" }) → OK (read allowed)
+ *     set_translation does not accept an env param → always sandbox
+ *
+ *   Guard:
+ *     assertSandboxWrite("production") → throws Error
+ *     assertSandboxWrite("sandbox")    → no-op
+ */
+
+export type Environment = "sandbox" | "production";
+export type Access = "read" | "write";
+export type ToolEnv = "sandbox" | "production" | "both";
+
+export interface ToolMeta {
+  env: ToolEnv;
+  access: Access;
+}
+
+/**
+ * Registry of all MCP tools with their environment scope and access level.
+ * Add every new tool here.
+ */
+export const TOOL_REGISTRY = {
+  // ── Read — available for both environments ──────────────────────────
+  list_projects: { env: "both", access: "read" },
+  get_project_details: { env: "both", access: "read" },
+  get_environment_status: { env: "both", access: "read" },
+  list_translations: { env: "both", access: "read" },
+  get_translation_diff: { env: "both", access: "read" },
+  validate_translations: { env: "both", access: "read" },
+  list_snapshots: { env: "both", access: "read" },
+  preview_push_to_production: { env: "both", access: "read" },
+  // ── Write — sandbox only; no production-write tools exist ───────────
+  init_sandbox: { env: "sandbox", access: "write" },
+  reset_sandbox: { env: "sandbox", access: "write" },
+  set_translation: { env: "sandbox", access: "write" },
+  delete_translation: { env: "sandbox", access: "write" },
+  bulk_import: { env: "sandbox", access: "write" },
+  bulk_set_locale: { env: "sandbox", access: "write" },
+  // ── Project structure management ──────────────────────────────────────────
+  create_namespace: { env: "both", access: "write" },
+  create_locale: { env: "both", access: "write" },
+  // ── Read-only export / analysis ───────────────────────────────────────────
+  export_namespace: { env: "both", access: "read" },
+  get_namespace_coverage: { env: "both", access: "read" },
+} as const satisfies Record<string, ToolMeta>;
+
+export type ToolName = keyof typeof TOOL_REGISTRY;
+
+/**
+ * Guard for write operations. Call at the start of every write tool handler.
+ * Throws a descriptive error if env is 'production', enforcing read-only production.
+ *
+ * @throws Error if env === 'production'
+ *
+ * @example
+ *   assertSandboxWrite("sandbox");    // no-op
+ *   assertSandboxWrite("production"); // throws
+ */
+export function assertSandboxWrite(env: Environment): void {
+  if (env === "production") {
+    throw new Error(
+      "Production is read-only. " +
+        "All writes must target the sandbox environment. " +
+        "Make changes in sandbox, then promote to production via the Admin UI.",
+    );
+  }
+}

package/src/prompts.ts

@@ -0,0 +1,159 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, ApiError } from "./api-client.js";
+
+interface ProjectListItem {
+  id: string;
+  slug: string;
+  name: string | null;
+  sandboxInitializedAt: string | null;
+  sandboxHasChanges: boolean;
+}
+
+export function registerPrompts(server: McpServer): void {
+  // ─── /setup ─────────────────────────────────────────────────────────────────
+  server.prompt(
+    "setup",
+    "Quick-start guide: how to explore projects, work with sandbox, and push translations.",
+    {},
+    () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Give me a quick-start guide for working with the localization MCP server.",
+              "Include: how to discover projects, namespaces, and locales; how to read and write translations in sandbox;",
+              "how to review and push changes to production. Keep it concise and practical.",
+            ].join(" "),
+          },
+        },
+        {
+          role: "assistant",
+          content: {
+            type: "text",
+            text: [
+              "## Localization MCP — Quick Start",
+              "",
+              "### 1. Discover",
+              "- `list_projects` — see all projects and sandbox state",
+              "- `get_project_details <slug>` — get exact locale codes and namespaces (**always call this before writing**)",
+              "",
+              "### 2. Read translations",
+              "- `list_translations <slug> <namespace>` — browse keys; filter with `missingLocale`, `search`",
+              "- `get_translation_diff <slug>` — see what changed in sandbox vs production",
+              "",
+              "### 3. Write to sandbox",
+              "- `set_translation` — upsert one key (pass only the locales you want to update)",
+              "- `bulk_set_locale` — fill many keys for a single locale at once",
+              "- `bulk_import` — import multiple locales from a JSON map",
+              "- `delete_translation` — soft-delete a key in sandbox",
+              "",
+              "### 4. Review & push",
+              "- `validate_translations <slug>` — check for missing translations before pushing",
+              "- `get_translation_diff <slug>` — final review of pending changes",
+              "- Promote via the Admin UI — MCP has no push tool by design (human approval required)",
+              "",
+              "### Rules",
+              "- All writes go to **sandbox only** — production is never touched directly",
+              "- Locale codes must match exactly what `get_project_details` returns — never guess",
+              "- Prefer existing namespaces — only create a new one with a clear justification",
+            ].join("\n"),
+          },
+        },
+      ],
+    }),
+  );
+
+  // ─── /diagnostic ────────────────────────────────────────────────────────────
+  server.prompt(
+    "diagnostic",
+    "Run a live health check: verify API connectivity, token validity, and list project states.",
+    { projectSlug: z.string().optional().describe("Optional: also check sandbox status for this project") },
+    async ({ projectSlug }) => {
+      const lines: string[] = ["## Localization MCP — Diagnostic", ""];
+
+      // 1. Config
+      const backendUrl = process.env.BACKEND_URL ?? "http://localhost:8080 (default)";
+      const tokenSet = !!process.env.MCP_TOKEN;
+      lines.push("### Config");
+      lines.push(`- BACKEND_URL: \`${backendUrl}\``);
+      lines.push(`- MCP_TOKEN: ${tokenSet ? "set ✅" : "NOT SET ❌ — all API calls will fail with 401"}`);
+      lines.push("");
+
+      // 2. API connectivity + project list
+      lines.push("### API");
+      try {
+        const data = await apiGet<{ data: ProjectListItem[]; meta: { total: number } }>(
+          "/translations/projects",
+          { page: 1, limit: 100 },
+        );
+        lines.push(`- Connection: ✅ OK`);
+        lines.push(`- Token: ✅ valid`);
+        lines.push(`- Projects accessible: ${data.meta.total}`);
+        lines.push("");
+
+        if (data.data.length > 0) {
+          lines.push("### Projects");
+          for (const p of data.data) {
+            const sandboxState = p.sandboxInitializedAt
+              ? p.sandboxHasChanges
+                ? "sandbox: ⚠️  HAS PENDING CHANGES"
+                : "sandbox: ✅ no changes"
+              : "sandbox: not initialized";
+            lines.push(`- \`${p.slug}\`${p.name ? ` (${p.name})` : ""} — ${sandboxState}`);
+          }
+          lines.push("");
+        }
+
+        // 3. Optional per-project sandbox check
+        if (projectSlug) {
+          lines.push(`### Sandbox: ${projectSlug}`);
+          try {
+            const status = await apiGet<{
+              initialized: boolean;
+              initializedAt: string | null;
+              hasChanges: boolean;
+              snapshotCount: number;
+            }>(`/translations/projects/${projectSlug}/sandbox/status`);
+
+            lines.push(`- Initialized: ${status.initialized ? `✅ yes (since ${status.initializedAt})` : "❌ NO — call init_sandbox before writing"}`);
+            lines.push(`- Has pending changes: ${status.hasChanges ? "⚠️  YES" : "✅ no"}`);
+            lines.push(`- Snapshots available: ${status.snapshotCount}`);
+          } catch (err) {
+            lines.push(`- ❌ Could not fetch sandbox status: ${err instanceof ApiError ? `${err.status} ${err.message}` : String(err)}`);
+          }
+          lines.push("");
+        }
+      } catch (err) {
+        if (err instanceof ApiError) {
+          if (err.status === 401) {
+            lines.push(`- Connection: ✅ reached backend`);
+            lines.push(`- Token: ❌ INVALID or missing (401 Unauthorized)`);
+            lines.push(`  → Regenerate token in Admin UI → API Tokens`);
+          } else {
+            lines.push(`- ❌ API error ${err.status}: ${err.message}`);
+          }
+        } else {
+          lines.push(`- ❌ Cannot reach backend at \`${backendUrl}\``);
+          lines.push(`  → Is the backend running? Check BACKEND_URL env var.`);
+        }
+        lines.push("");
+      }
+
+      return {
+        messages: [
+          {
+            role: "user",
+            content: { type: "text", text: "Run diagnostic on the localization MCP server." },
+          },
+          {
+            role: "assistant",
+            content: { type: "text", text: lines.join("\n") },
+          },
+        ],
+      };
+    },
+  );
+}

package/src/server.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerEnvironmentTools } from "./tools/environment.js";
+import { registerTranslationTools } from "./tools/translations.js";
+import { registerSandboxWriteTools } from "./tools/sandbox-writes.js";
+import { registerProjectManagementTools } from "./tools/project-management.js";
+import { registerDiffTools } from "./tools/diff.js";
+import { registerSnapshotTools } from "./tools/snapshots.js";
+import { registerProductionTools } from "./tools/production.js";
+import { registerPrompts } from "./prompts.js";
+
+export function createServer(): McpServer {
+  const server = new McpServer({
+    name: "localization-mcp-server",
+    version: "1.0.0",
+  });
+
+  registerEnvironmentTools(server);
+  registerTranslationTools(server);
+  registerSandboxWriteTools(server);
+  registerProjectManagementTools(server);
+  registerDiffTools(server);
+  registerSnapshotTools(server);
+  registerProductionTools(server);
+  registerPrompts(server);
+
+  return server;
+}

package/src/tools/diff.ts

@@ -0,0 +1,225 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, ApiError } from "../api-client.js";
+
+type DiffStatus = "added" | "changed" | "deleted";
+
+interface DiffEntry {
+  namespace: string;
+  key: string;
+  locale: string;
+  status: DiffStatus;
+  productionValue: string | null;
+  sandboxValue: string | null;
+}
+
+interface DiffResponse {
+  total: number;
+  added: number;
+  changed: number;
+  deleted: number;
+  entries: DiffEntry[];
+}
+
+export function registerDiffTools(server: McpServer): void {
+  server.tool(
+    "get_translation_diff",
+    "Get the full diff between sandbox and production for a project. Shows all added, changed, and deleted entries.",
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().optional().describe("Filter diff to a specific namespace (optional)"),
+      locale: z.string().optional().describe("Filter diff to a specific locale (optional)"),
+      statusFilter: z
+        .enum(["added", "changed", "deleted", "all"])
+        .default("all")
+        .describe("Filter by change type (default: all)"),
+    },
+    async ({ projectSlug, namespace, locale, statusFilter }) => {
+      try {
+        const diff = await apiGet<DiffResponse>(
+          `/translations/projects/${projectSlug}/sandbox/diff`,
+        );
+
+        let entries = diff.entries;
+        if (namespace) entries = entries.filter((e) => e.namespace === namespace);
+        if (locale) entries = entries.filter((e) => e.locale === locale);
+        if (statusFilter !== "all") entries = entries.filter((e) => e.status === statusFilter);
+
+        const summary = `Diff for ${projectSlug}: ${diff.total} total changes — ${diff.added} added, ${diff.changed} changed, ${diff.deleted} deleted`;
+
+        if (entries.length === 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `${summary}\n\nNo entries match the current filters.`,
+              },
+            ],
+          };
+        }
+
+        const grouped = groupByNamespace(entries);
+        const sections = Object.entries(grouped).map(([ns, nsEntries]) => {
+          const lines = nsEntries.map((e) => formatDiffEntry(e));
+          return `[${ns}]\n${lines.join("\n")}`;
+        });
+
+        const filterNote =
+          namespace || locale || statusFilter !== "all"
+            ? `\nFilters: ${[namespace && `namespace=${namespace}`, locale && `locale=${locale}`, statusFilter !== "all" && `status=${statusFilter}`].filter(Boolean).join(", ")}`
+            : "";
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `${summary}${filterNote}\n\n${sections.join("\n\n")}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+
+  server.tool(
+    "validate_translations",
+    "Analyze the sandbox diff for potential issues: empty values, locales missing translations that others have, and keys only partially translated.",
+    {
+      projectSlug: z.string().describe("Project slug"),
+      namespace: z.string().optional().describe("Limit validation to a specific namespace (optional)"),
+    },
+    async ({ projectSlug, namespace }) => {
+      try {
+        const diff = await apiGet<DiffResponse>(
+          `/translations/projects/${projectSlug}/sandbox/diff`,
+        );
+
+        let entries = diff.entries;
+        if (namespace) entries = entries.filter((e) => e.namespace === namespace);
+
+        // Only check entries that will exist in production after push (not deleted)
+        const activeEntries = entries.filter((e) => e.status !== "deleted");
+
+        const issues: string[] = [];
+
+        // 1. Check for empty sandbox values in added/changed entries
+        const emptyValues = activeEntries.filter(
+          (e) => e.sandboxValue === null || e.sandboxValue.trim() === "",
+        );
+        if (emptyValues.length > 0) {
+          issues.push(
+            `Empty translation values (${emptyValues.length} entries):\n` +
+              emptyValues
+                .slice(0, 10)
+                .map((e) => `  • ${e.namespace}/${e.key} [${e.locale}]`)
+                .join("\n") +
+              (emptyValues.length > 10 ? `\n  ... and ${emptyValues.length - 10} more` : ""),
+          );
+        }
+
+        // 2. Check for keys that are only partially translated across locales
+        const keyLocaleMap = new Map<string, Set<string>>();
+        for (const entry of activeEntries) {
+          const k = `${entry.namespace}/${entry.key}`;
+          if (!keyLocaleMap.has(k)) keyLocaleMap.set(k, new Set());
+          keyLocaleMap.get(k)!.add(entry.locale);
+        }
+
+        const allLocales = new Set(activeEntries.map((e) => e.locale));
+        const partialKeys: string[] = [];
+
+        for (const [key, locales] of keyLocaleMap.entries()) {
+          const missing = [...allLocales].filter((l) => !locales.has(l));
+          if (missing.length > 0 && missing.length < allLocales.size) {
+            partialKeys.push(`  • ${key} — missing locales: ${missing.join(", ")}`);
+          }
+        }
+
+        if (partialKeys.length > 0) {
+          issues.push(
+            `Partially translated keys in diff (${partialKeys.length}):\n` +
+              partialKeys.slice(0, 10).join("\n") +
+              (partialKeys.length > 10 ? `\n  ... and ${partialKeys.length - 10} more` : ""),
+          );
+        }
+
+        // 3. Check deleted entries — flag keys being deleted for all locales
+        const deletedKeys = new Map<string, number>();
+        for (const e of entries.filter((e) => e.status === "deleted")) {
+          const k = `${e.namespace}/${e.key}`;
+          deletedKeys.set(k, (deletedKeys.get(k) ?? 0) + 1);
+        }
+
+        if (deletedKeys.size > 0) {
+          issues.push(
+            `Keys being deleted from production (${deletedKeys.size}):\n` +
+              [...deletedKeys.entries()]
+                .slice(0, 10)
+                .map(([k, count]) => `  • ${k} (${count} locale values)`)
+                .join("\n") +
+              (deletedKeys.size > 10 ? `\n  ... and ${deletedKeys.size - 10} more` : ""),
+          );
+        }
+
+        const header = `Validation for ${projectSlug}${namespace ? `/${namespace}` : ""} (${diff.total} pending changes)`;
+
+        if (issues.length === 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `${header}\n\nNo issues found. All pending translations look complete.`,
+              },
+            ],
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `${header}\n\nFound ${issues.length} issue(s):\n\n${issues.join("\n\n")}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return errorContent(error);
+      }
+    },
+  );
+}
+
+function groupByNamespace(entries: DiffEntry[]): Record<string, DiffEntry[]> {
+  const result: Record<string, DiffEntry[]> = {};
+  for (const entry of entries) {
+    if (!result[entry.namespace]) result[entry.namespace] = [];
+    result[entry.namespace].push(entry);
+  }
+  return result;
+}
+
+function formatDiffEntry(e: DiffEntry): string {
+  const statusSymbol = e.status === "added" ? "+" : e.status === "deleted" ? "-" : "~";
+  const label = `${statusSymbol} ${e.key} [${e.locale}]`;
+
+  if (e.status === "added") {
+    return `  ${label}\n    → "${e.sandboxValue}"`;
+  }
+  if (e.status === "deleted") {
+    return `  ${label}\n    was: "${e.productionValue}"`;
+  }
+  return `  ${label}\n    before: "${e.productionValue}"\n    after:  "${e.sandboxValue}"`;
+}
+
+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)}` }],
+  };
+}