@vialytics/dittomato-mcp 1.0.0

package/README.md

@@ -0,0 +1,317 @@
+# @vialytics/dittomato-mcp
+
+An [MCP](https://modelcontextprotocol.io) server over a Dittomato backend, so
+an agent in any MCP-capable editor — Claude Code, Claude Desktop, Cursor, VS
+Code — can search, read and write UI strings without leaving the codebase it's
+editing.
+
+The workflow it's for: *"is there already a string for 'Apply filter'?"* →
+*"add `filter.reset` and translate it into German and French"* — answered in
+the editor, against the live catalog, instead of tab-switching to the web
+editor and copying IDs by hand.
+
+It's a thin adapter over the same Ditto-compatible HTTP API the CLI and the
+Figma plugin use (see [docs/API.md](../docs/API.md)). No Firebase SDK, no
+service account — just a host and a `dsk_` token, the same config contract as
+[`dittomato-pull`](../cli/).
+
+## Setup
+
+Get a token first. The app's **Keys** panel gives you a personal token, which
+inherits your own role — so it can write if you're an editor or admin. That's
+the one you want for your own editor.
+
+For a shared/service token, an admin issues one from Settings → **Team API
+tokens** with access `readwrite`. Note `node tokens.js mint "<label>"` is **read-only** —
+service tokens minted from the CLI have no access level and behave as `read`, so
+the write tools will 403. Avoid `write`-only tokens here: they can't read at
+all, so search and get fail while pushes succeed.
+
+### Claude Desktop — one click (`.mcpb`)
+
+The repo ships a prebuilt extension bundle: **[`mcp/dittomato-mcp.mcpb`](./dittomato-mcp.mcpb)**
+(~175 KB). Download it, then drag it onto Claude Desktop, or use Settings →
+**Extensions** → *Install extension…*. Claude Desktop asks for four values at
+install time — no config file to edit, no Node install, no `npx` on first run:
+
+| Field | |
+| --- | --- |
+| **API Host** | `https://europe-west3-<project>.cloudfunctions.net/api` |
+| **API Key** | your own `dsk_…` token from the Keys panel |
+| **Read-only** | off by default; on hides the write tools |
+| **Allow delete** | off by default; on exposes `delete_strings` |
+
+The token is entered per person and stored by Claude Desktop, so the bundle in
+git carries no credentials — everyone installs the same file with their own key
+and their own role.
+
+The bundle is a single esbuild-bundled `index.js`; it carries no `node_modules`
+and needs only Node ≥ 18 on the machine. It's signed with a **self-signed**
+vialytics certificate (`CN=vialytics`), which is tamper-evidence, not a trust
+chain — Claude Desktop still shows it as an unverified publisher, same as any
+extension not signed by a CA.
+
+### Claude Code
+
+```bash
+claude mcp add dittomato \
+  --env DITTO_API_HOST=https://europe-west3-your-project.cloudfunctions.net/api \
+  --env DITTO_API_KEY=dsk_xxx \
+  -- npx -y @vialytics/dittomato-mcp
+```
+
+### Claude Desktop / Cursor / VS Code — manual config
+
+Add to the client's MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`,
+`.vscode/mcp.json` — the shape is the same):
+
+```json
+{
+  "mcpServers": {
+    "dittomato": {
+      "command": "npx",
+      "args": ["-y", "@vialytics/dittomato-mcp"],
+      "env": {
+        "DITTO_API_HOST": "https://europe-west3-your-project.cloudfunctions.net/api",
+        "DITTO_API_KEY": "dsk_xxx"
+      }
+    }
+  }
+}
+```
+
+| Env var | |
+| --- | --- |
+| `DITTO_API_HOST` | API base URL (required) |
+| `DITTO_API_KEY` | `dsk_…` token (required; `DITTOMATO_TOKEN` also accepted) |
+| `DITTO_MCP_READONLY=1` | Drop the write tools from the server entirely |
+| `DITTO_MCP_ALLOW_DELETE=1` | Expose `delete_strings`. Off by default — see below |
+
+`--host`, `--token`, `--readonly` and `--allow-delete` work as flags too, but env
+vars keep the token out of process listings and client config diffs.
+`DITTO_MCP_READONLY` wins over `DITTO_MCP_ALLOW_DELETE` if both are set.
+
+## Tools
+
+**Read**
+
+| Tool | |
+| --- | --- |
+| `list_variants` | Which locales exist |
+| `search_strings` | Substring search over IDs and every locale's text |
+| `get_strings` | Full detail for specific IDs: plurals, translations, missing locales |
+| `translation_coverage` | How much of a prefix is translated, plus the missing IDs |
+| `export_locale` | A slice of the catalog as a flat i18next map |
+| `list_variables` | The `{{Variable}}` placeholders and their examples |
+| `review_copy` | The team's AI style-guide check on one string |
+| `suggest_ids` | Convention-following ID naming, and reuse detection |
+
+**Write** (hidden entirely under `DITTO_MCP_READONLY=1`)
+
+| Tool | |
+| --- | --- |
+| `create_strings` | New base English strings |
+| `update_strings` | Change text or plural forms for one locale |
+
+**Delete** — off by default, needs `DITTO_MCP_ALLOW_DELETE=1` as well
+
+| Tool | |
+| --- | --- |
+| `delete_strings` | Delete entries, or clear one locale's translation |
+
+**Context** — for doing the work yourself instead of paying for a second model
+
+| Tool | |
+| --- | --- |
+| `get_instructions` | The team's style guide / translation instructions / ID conventions |
+| `get_glossary` | Canonical EN/DE/FR terminology, filtered to a given text |
+| `get_naming_context` | Namespaces, containers, existing IDs, same-text reuse candidates |
+
+`review_copy` and `suggest_ids` are read-shaped but spend the server-held
+Anthropic key, so they need a token with write access.
+
+## Don't pay for a second Claude
+
+You're already talking to one. `review_copy` and `suggest_ids` send the work to
+the Cloud Function, which calls Claude again — billed to the team's shared
+Anthropic key, two hops away, judging with none of your conversation's context.
+Those endpoints exist because the Figma plugin and the web editor have no model
+of their own and genuinely need them.
+
+The context tools serve the same inputs so the judging can happen where the
+context already is:
+
+| Instead of | Use |
+| --- | --- |
+| `review_copy` | `get_instructions(kind="review")` + `get_glossary({text})` |
+| `suggest_ids` | `get_instructions(kind="naming")` + `get_naming_context({prefix, texts})` |
+
+This stays consistent with the other surfaces, because those are the same
+admin-managed Firestore documents `/review-copy` and `/suggest-ids` read — a
+wording fix in Settings → Translation instructions governs your judgment too.
+Both prompts (`harvest_screen`, `translate_gaps`) take this path by default.
+
+Two things you give up, worth knowing:
+
+- **`ai_usage` and `ai_feedback` don't see it.** No token telemetry for work done
+  locally, and the thumbs up/down loop that tunes the server-side prompts never
+  learns from it.
+- **`suggest_ids`' server-side validation.** It verifies a proposed `reuseId`
+  actually exists, converts a colliding new ID into a reuse, and recomputes
+  `newNamespace` rather than trusting the model. Naming locally loses that,
+  though `create_strings` still refuses an ID that already exists.
+
+## Prompts: harvesting a screen
+
+Two multi-step flows ship as MCP prompts, which clients surface as slash
+commands (`/mcp__dittomato__harvest_screen` in Claude Code):
+
+| Prompt | |
+| --- | --- |
+| `harvest_screen` | Read the strings off a design, name them, catch duplicates, create the new ones |
+| `translate_gaps` | Find untranslated strings for a locale and fill them, glossary-checked |
+
+`harvest_screen` is the "paste a screenshot / point at a Figma frame" workflow:
+
+1. **You** hand the agent an image, a Figma URL, or a code file.
+2. The agent reads the visible copy — off the image with its own vision, or via
+   a Figma MCP if one is connected (which also yields real layer/frame/page
+   names, better naming context than an image can give).
+3. `suggest_ids` triages the batch: **IGNORE** (sample data, not copy), **REUSE**
+   (already in the catalog — it checks every entry for same-text matches itself,
+   no prior search needed) or **CREATE** (a new convention-following ID).
+4. The agent shows you the verdicts before writing anything, flagging
+   `reuseConfidence: "semantic"` and `newNamespace: true` rows as judgement calls.
+5. `create_strings` writes only what you approved.
+
+Note where the vision happens: **in your editor's model, not in this server.**
+This server never sees the image. That's why it works with a pasted screenshot,
+a Figma selection, a PDF, or a photo of a whiteboard without needing to know
+about any of them — it takes over once there's a list of strings.
+
+The prompts are plain text in [index.js](index.js) — worth editing if your team's
+review step differs.
+
+## It holds no catalog
+
+The first version cached the whole catalog in memory, because the API had no
+server-side search. Measured, that was **2.25 MB across 11,162 entries, served
+uncompressed** — so every session paid ~2 s before its first answer and re-paid
+it whenever the cache expired, while the search itself took 2–3 ms. The catalog
+was never the expensive part; shipping it was.
+
+`/v2/search`, `/v2/entries` and `/v2/coverage` now do that work server-side, off
+the function's own cached index, next to Firestore:
+
+| | Before | Now |
+| --- | --- | --- |
+| Startup | 2.25 MB, ~2 s | nothing fetched |
+| A search | 2.25 MB, then 2 ms | ~2.4 KB |
+| Coverage | same 2.25 MB | 485 B |
+| One entry | same 2.25 MB | 236 B |
+
+Startup is instant, there's nothing to invalidate after a write, and memory is
+flat regardless of how big the catalog gets. Only the variant list — a handful of
+rows — is cached, for five minutes.
+
+## What it still adds over raw curl
+
+**Bounded payloads.** Every tool caps its result and reports when it truncated,
+so a search can't dump the catalog into the model's context. Results are compact
+JSON, not pretty-printed — indentation alone measured 27% of a search payload.
+
+**It refuses writes the API would accept but that lose data.** `POST
+/v2/components` sets `{base, name}` wholesale at the entry key, so "creating" an
+ID that already exists silently drops its `de`/`fr` translations —
+`create_strings` looks the IDs up first and rejects the whole batch rather than
+writing part of it. IDs are validated against the same `ID_RE` the server uses,
+and plural keys against the CLDR form list, before anything is sent.
+
+**A two-step delete.** Preview the loss, then confirm — see below.
+
+For a full export of every locale to disk, don't use `export_locale` — run
+`npx dittomato-pull`, which writes the files directly without routing megabytes
+through a model.
+
+## Requires a current backend
+
+The read tools depend on `/v2/search`, `/v2/entries` and `/v2/coverage`. Against
+a Cloud Function deployed before those existed every read returns `404`, and the
+error message says so. Deploy the function first.
+
+## Note on writes
+
+The write tools change the live shared catalog. MCP clients prompt before a tool
+call, which is the real gate — but if you're handing this to a wider team,
+`DITTO_MCP_READONLY=1` (or just issuing `read` tokens) removes the question.
+Every write is attributed to the token's owner in the `changelog` collection and
+shows up in the web editor's history, same as an edit made in the UI.
+
+## Deleting
+
+`delete_strings` is gated behind its own flag and **absent from the tool list
+without it**, because it's the one operation here you can't walk back:
+
+- Deleting an entry takes its base text, every translation and every plural form
+  with it. There's no soft delete and no undo in the API. Recovery means the
+  nightly snapshot (`backups/{YYYY-MM-DD}`, 30 days, `node restore.js <date>`),
+  which costs a day of everyone else's edits.
+- **It can't check whether a string is still used.** The web editor's delete flow
+  checks GitHub code usage and Figma usages first; neither read is reachable with
+  a `dsk_` token, so this tool can't do it. Its response carries that caveat so
+  the agent repeats it to you, but the check itself is on you — in the editor.
+
+The tool refuses to write unless called with `confirm: true`. Called without it,
+it returns a preview of exactly what would be lost — including which locales the
+entry currently has — and touches nothing. That two-step is the analogue of the
+editor's type-the-ID confirmation: it forces the losses in front of a human
+before the destructive call.
+
+Pass `locale` to clear one translation instead of deleting the entry. That's the
+strictly narrower operation and usually the one you actually want when a
+translation is wrong rather than unwanted.
+
+## Development
+
+```bash
+cd mcp && yarn install && yarn test
+```
+
+To try it against a real backend without publishing anything, point your MCP
+client straight at the checkout — no `npx`, no install:
+
+```bash
+claude mcp add dittomato-local \
+  --env DITTO_API_HOST=https://europe-west3-your-project.cloudfunctions.net/api \
+  --env DITTO_API_KEY=dsk_xxx \
+  -- node /absolute/path/to/dittomato/mcp/index.js
+```
+
+`npm pack --dry-run` shows exactly which files a publish would ship.
+
+The tests run against a mock backend serving the shapes
+[docs/API.md](../docs/API.md) documents, and include an end-to-end stdio
+handshake so an SDK bump can't silently break the protocol wiring.
+
+### Rebuilding the `.mcpb`
+
+```bash
+cd mcp
+npm run signing:init   # once — writes .signing/{cert,key}.pem, both gitignored
+npm run build:mcpb     # bundle → pack → sign, writes dittomato-mcp.mcpb
+```
+
+`build:bundle` runs esbuild over `index.js` and copies `manifest.json` and this
+README into `build/`; `build:pack` zips that directory; `build:sign` appends the
+PKCS#7 block. Commit the resulting `dittomato-mcp.mcpb` — it's the file the team
+downloads. `build/` and `.signing/` stay out of git.
+
+Bump `version` in **both** `package.json` and `manifest.json` before rebuilding;
+Claude Desktop reads the manifest's version, and a bundle whose version didn't
+change won't look like an update.
+
+Note `mcpb verify` and `mcpb info` report *"Not signed"* on a correctly signed
+bundle: node-forge, which the CLI uses, throws `PKCS#7 signature verification
+not yet implemented` and the CLI swallows that into an unsigned verdict. The
+signature is there — `openssl asn1parse` over the trailing `MCPB_SIG_V1` block
+shows it. Don't chase that warning.

package/index.js

@@ -0,0 +1,996 @@
+#!/usr/bin/env node
+/**
+ * dittomato-mcp — an MCP server over a Dittomato backend, so an agent in any
+ * MCP-capable editor (Claude Code, Claude Desktop, Cursor, VS Code, …) can
+ * search, read and write UI strings without leaving the codebase it's editing.
+ *
+ * A thin adapter over the same Ditto-compatible HTTP API the CLI and the Figma
+ * plugin use — see docs/API.md. No Firebase SDK, no service account: just a
+ * host and a `dsk_` token, same config contract as `dittomato-pull`.
+ *
+ *   DITTO_API_HOST   https://europe-west3-<project>.cloudfunctions.net/api
+ *   DITTO_API_KEY    dsk_…   (DITTOMATO_TOKEN also accepted)
+ *   DITTO_MCP_READONLY=1      hide the write tools entirely
+ *   DITTO_MCP_ALLOW_DELETE=1  expose delete_strings (off by default)
+ *
+ * ── Why there is no catalog cache here ────────────────────────────────────────
+ * The first version fetched `/v1/components?format=structured` once and answered
+ * search/get/coverage from memory, because the API had no server-side search.
+ * Measured, that was 2.25MB across 11,162 entries, served UNCOMPRESSED, so every
+ * session paid ~2s before its first answer and re-paid it whenever the cache
+ * expired — while the search itself took 2-3ms. The catalog was never the
+ * interesting part; shipping it was.
+ *
+ * `/v2/search`, `/v2/entries` and `/v2/coverage` now do that work in-region next
+ * to Firestore, off the server's own cached index, and answer in about a
+ * kilobyte. So this process holds no catalog at all: startup is instant, there's
+ * nothing to invalidate after a write, and memory is flat regardless of catalog
+ * size. Only the variant list (a handful of rows) is cached, briefly.
+ *
+ * What this layer still adds over raw curl:
+ *  - Bounded payloads. Every tool caps its result and says when it truncated, so
+ *    a search can't dump the catalog into the model's context.
+ *  - Refusing writes the API would accept but that lose data. POST
+ *    /v2/components sets {base, name} wholesale at the entry key (see
+ *    createComponents), so "creating" an existing ID silently drops its de/fr
+ *    translations — checked here first. IDs are validated against the same
+ *    ID_RE the server uses, plural keys against the CLDR form list.
+ *  - A two-step delete: preview the loss, then confirm.
+ *
+ * stdio protocol note: stdout carries JSON-RPC frames and nothing else. All
+ * diagnostics go to stderr.
+ */
+
+"use strict";
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const {
+  StdioServerTransport,
+} = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+
+const { version: VERSION } = require("./package.json");
+
+// ── config ────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--host") args.host = argv[++i];
+    else if (argv[i] === "--token") args.token = argv[++i];
+    else if (argv[i] === "--readonly") args.readonly = true;
+    else if (argv[i] === "--allow-delete") args.allowDelete = true;
+  }
+  return args;
+}
+
+const argv = parseArgs(process.argv.slice(2));
+const HOST = (argv.host || process.env.DITTO_API_HOST || "").replace(/\/$/, "");
+const TOKEN =
+  argv.token || process.env.DITTO_API_KEY || process.env.DITTOMATO_TOKEN || "";
+const READONLY = !!argv.readonly || process.env.DITTO_MCP_READONLY === "1";
+// Delete is opt-in separately from create/update, and off by default. It's the
+// one irreversible operation here — removing an entry takes every translation
+// with it — and the web editor gates its own delete behind a type-the-ID
+// confirmation plus a code-usage check. Most installs have no reason to expose
+// it at all, so the safe default is "the tool doesn't exist".
+const ALLOW_DELETE =
+  !READONLY &&
+  (!!argv.allowDelete || process.env.DITTO_MCP_ALLOW_DELETE === "1");
+
+// Mirrors functions/index.js ID_RE — lowercase dot-segmented, hyphens allowed.
+const ID_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$/;
+const ID_MAX = 80;
+// CLDR forms, same list as figma-plugin/ui.html PLURAL_FORMS and editor.js
+// PLURAL_ORDER. Kept here so a typo'd form is rejected before it reaches
+// Firestore, where it would become a permanent junk key in the plural map.
+const PLURAL_FORMS = ["zero", "one", "two", "few", "many", "other"];
+
+// ── HTTP ──────────────────────────────────────────────────────────────────────
+
+class ApiError extends Error {}
+
+// Batch caps are refused, never silently trimmed: an agent that asked to write
+// 150 strings and got 100 back with no complaint has no way to notice the 50.
+function requireBatch(value, field, max) {
+  const list = Array.isArray(value) ? value : [];
+  if (!list.length) throw new ApiError(`\`${field}\` must be a non-empty array.`);
+  if (list.length > max)
+    throw new ApiError(
+      `Too many items in \`${field}\`: ${list.length}, max ${max} per call. Split into batches.`,
+    );
+  return list;
+}
+
+async function api(pathname, { method = "GET", body, withHeaders } = {}) {
+  if (!HOST || !TOKEN)
+    throw new ApiError(
+      "Not configured: set DITTO_API_HOST and DITTO_API_KEY in the MCP server's env.",
+    );
+  const res = await fetch(HOST + pathname, {
+    method,
+    headers: {
+      Authorization: TOKEN,
+      // The catalog routes gzip ~6x. Node's fetch sends this by default and
+      // decompresses transparently; stated explicitly so it survives a runtime
+      // that doesn't.
+      "Accept-Encoding": "gzip",
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    let detail = text.slice(0, 300);
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && parsed.error) detail = parsed.error;
+    } catch {
+      /* not JSON — keep the raw excerpt */
+    }
+    // The API's status codes are meaningful (docs/API.md → Errors); translate
+    // the ones an agent can actually act on rather than surfacing a bare code.
+    if (res.status === 401)
+      throw new ApiError(
+        "Invalid API token (401). Check DITTO_API_KEY — it should be a dsk_… token.",
+      );
+    if (res.status === 403)
+      throw new ApiError(
+        `Forbidden (403): ${detail}. Reading needs a token with read or readwrite ` +
+          `access; writing needs readwrite, or a personal token owned by an editor/admin.`,
+      );
+    if (res.status === 404)
+      throw new ApiError(
+        `Not found (404): ${detail}. If this is a route the tool expects, the ` +
+          `backend may predate it — deploy the Cloud Function.`,
+      );
+    if (res.status === 501)
+      throw new ApiError(
+        `Not configured on the server (501): ${detail}. This endpoint's dependency ` +
+          `(e.g. the shared Anthropic key) isn't set up.`,
+      );
+    throw new ApiError(`${method} ${pathname} → HTTP ${res.status}: ${detail}`);
+  }
+  const json = await res.json();
+  return withHeaders ? { json, headers: res.headers } : json;
+}
+
+const qs = (params) => {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params))
+    if (v !== undefined && v !== null && v !== "") sp.set(k, String(v));
+  return sp.toString();
+};
+
+// The variant list is a handful of rows and changes when someone adds a
+// language, so a short TTL keeps a long session current without re-asking on
+// every call. This is the only thing cached in this process.
+const VARIANTS_TTL_MS = 5 * 60 * 1000;
+let variantsCache = null;
+let variantsAt = 0;
+async function variants() {
+  if (!variantsCache || Date.now() - variantsAt >= VARIANTS_TTL_MS) {
+    variantsCache = await api("/v1/variants");
+    variantsAt = Date.now();
+  }
+  return variantsCache;
+}
+async function localeIds() {
+  return ["base", ...(await variants()).map((v) => v.id)];
+}
+async function assertLocale(locale) {
+  const all = await localeIds();
+  if (!all.includes(locale))
+    throw new ApiError(`Unknown locale '${locale}'. Known: ${all.join(", ")}.`);
+}
+
+// Existence + current content for specific IDs, straight from the server. This
+// is what the write tools check against instead of a local catalog copy.
+async function lookup(ids) {
+  const out = await api(`/v2/entries?${qs({ ids: ids.join(",") })}`);
+  const byId = new Map((out.strings || []).map((s) => [s.id, s]));
+  return { byId, notFound: out.notFound || [] };
+}
+
+// ── tools ─────────────────────────────────────────────────────────────────────
+
+const READ_TOOLS = [
+  {
+    name: "list_variants",
+    description:
+      "List the locales this catalog carries (base plus every translation variant). Call first if you don't know the locale codes.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => ({
+      locales: await localeIds(),
+      variants: (await variants()).map((v) => ({ id: v.id, name: v.name })),
+    }),
+  },
+
+  {
+    name: "search_strings",
+    description:
+      "Search the catalog by text or ID. Use before creating anything — duplicates are the most common mistake. Results are capped; narrow with id_prefix rather than raising the limit.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "Case-insensitive substring, matched against the ID and against the text in every locale (or just `locale`).",
+        },
+        id_prefix: { type: "string", description: "Only IDs starting with this." },
+        locale: {
+          type: "string",
+          description: "Restrict text matching to this locale. Default: all.",
+        },
+        limit: { type: "integer", description: "Max results (default 25, max 100)." },
+      },
+    },
+    handler: async ({ query, id_prefix, locale, limit }) => {
+      if (!query && !id_prefix)
+        throw new ApiError("Pass at least one of `query` or `id_prefix`.");
+      if (locale) await assertLocale(locale);
+      return api(
+        `/v2/search?${qs({ q: query, prefix: id_prefix, locale, limit })}`,
+      );
+    },
+  },
+
+  {
+    name: "get_strings",
+    description:
+      "Full detail for specific IDs: base text, every translation, plural forms, and which locales are missing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "String IDs (max 100).",
+        },
+      },
+      required: ["ids"],
+    },
+    handler: async ({ ids }) =>
+      api(`/v2/entries?${qs({ ids: requireBatch(ids, "ids", 100).join(",") })}`),
+  },
+
+  {
+    name: "translation_coverage",
+    description:
+      "How much of the catalog (or one ID prefix) is translated into a locale, plus a sample of the missing IDs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        locale: { type: "string", description: "Locale to measure, e.g. 'de'." },
+        id_prefix: { type: "string", description: "Restrict to this prefix." },
+        sample_limit: {
+          type: "integer",
+          description: "How many missing IDs to list (default 50, max 200).",
+        },
+      },
+      required: ["locale"],
+    },
+    handler: async ({ locale, id_prefix, sample_limit }) =>
+      api(
+        `/v2/coverage?${qs({ locale, prefix: id_prefix, sample: sample_limit })}`,
+      ),
+  },
+
+  {
+    name: "export_locale",
+    description:
+      "Export a slice of the catalog as a flat i18next key→text map (plurals unfolded to key_one/key_other plus a bare key), ready to write to a file. For a FULL export of every locale, run `npx dittomato-pull` instead — it writes files directly without routing megabytes through the model.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        locale: { type: "string", description: "Locale to export." },
+        id_prefix: {
+          type: "string",
+          description:
+            "Restrict to this prefix. Strongly recommended — the full catalog is far larger than the limit.",
+        },
+        limit: { type: "integer", description: "Max keys (default 200, max 1000)." },
+      },
+      required: ["locale"],
+    },
+    handler: async ({ locale, id_prefix, limit }) => {
+      await assertLocale(locale);
+      const cap = Math.min(Math.max(Number(limit) || 200, 1), 1000);
+      const { json, headers } = await api(
+        `/v1/components?${qs({
+          variant: locale === "base" ? "" : locale,
+          prefix: id_prefix,
+          limit: cap,
+        })}`,
+        { withHeaders: true },
+      );
+      const truncated = headers.get("x-truncated") === "true";
+      return {
+        locale,
+        idPrefix: id_prefix || null,
+        keysReturned: Object.keys(json).length,
+        totalKeys: Number(headers.get("x-total-keys")) || Object.keys(json).length,
+        truncated,
+        ...(truncated
+          ? {
+              note: "Truncated. Narrow with id_prefix, or run `npx dittomato-pull` for a full export to disk.",
+            }
+          : {}),
+        keys: json,
+      };
+    },
+  },
+
+  {
+    name: "list_variables",
+    description:
+      "The interpolation variables available to string text (the {{Variable}} placeholders), with example values.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Substring filter on the name." },
+        limit: { type: "integer", description: "Max results (default 50, max 200)." },
+      },
+    },
+    handler: async ({ query, limit }) => {
+      const cap = Math.min(Math.max(Number(limit) || 50, 1), 200);
+      const vars = await api("/v2/variables");
+      const needle = query ? String(query).toLowerCase() : null;
+      const hits = vars.filter(
+        (v) => !needle || String(v.name).toLowerCase().includes(needle),
+      );
+      return {
+        totalMatches: hits.length,
+        truncated: hits.length > cap,
+        variables: hits
+          .slice(0, cap)
+          .map((v) => ({ name: v.name, type: v.type, data: v.data })),
+      };
+    },
+  },
+
+  // ── context tools ──────────────────────────────────────────────────────────
+  // You are already talking to a capable model. Calling review_copy or
+  // suggest_ids sends the work to a SECOND Claude on the server — billed to the
+  // team's shared Anthropic key, two hops away, and judging with none of this
+  // conversation's context. These serve the same admin-managed instructions,
+  // glossary and catalog slice so the judging can happen here instead.
+  {
+    name: "get_instructions",
+    description:
+      "Fetch the team's admin-managed instructions so YOU can do the work rather than paying for a second model to do it on the server. kind=review is the copy style guide, kind=translate the translation instructions, kind=naming the ID conventions and triage rules. These are the exact same documents /review-copy and /suggest-ids use, so following them keeps you consistent with the web editor and the Figma plugin. Fetch once and reuse for the rest of the conversation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: {
+          type: "string",
+          enum: ["review", "translate", "naming"],
+          description: "Which instruction set to fetch.",
+        },
+      },
+      required: ["kind"],
+    },
+    handler: async ({ kind }) => api(`/v2/instructions?${qs({ kind })}`),
+  },
+
+  {
+    name: "get_glossary",
+    description:
+      "The team's canonical EN/DE/FR terminology. Pass `text` to get only the terms that text actually mentions — the same filter the server applies, which cuts ~99.8% because most UI strings mention no term. Omit `text` for the whole table (~184 terms) if you're about to work through many strings. Use these terms verbatim; they include product names that must never be translated or substituted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: {
+          type: "string",
+          description:
+            "Filter to terms this text mentions. Omit for the full table.",
+        },
+      },
+    },
+    handler: async ({ text }) => api(`/v2/glossary?${qs({ text })}`),
+  },
+
+  {
+    name: "get_naming_context",
+    description:
+      "The catalog slice needed to name new string IDs yourself: which namespaces exist and how big they are, the cross-cutting containers (toast./tooltip./modal./emptystate./…) with examples, everything already under a given prefix, and — per input text — existing entries with the SAME text, which are reuse candidates. Combine with get_instructions(kind=naming). Use `namespaceNames` (the full list) to judge whether a namespace is new; `namespaces` is ranked and truncated for readability.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prefix: {
+          type: "string",
+          description:
+            "Feature namespace you're naming into, e.g. 'checkout' — returns up to 40 existing IDs under it.",
+        },
+        texts: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "The string texts you're about to name (max 50). Each is checked against the whole catalog for identical existing text.",
+        },
+      },
+    },
+    handler: async ({ prefix, texts }) =>
+      api(
+        `/v2/naming-context?${qs({
+          prefix,
+          texts: (Array.isArray(texts) ? texts : []).slice(0, 50).join("\n"),
+        })}`,
+      ),
+  },
+
+  {
+    name: "review_copy",
+    description:
+      "Server-side AI style-guide check. Prefer doing this yourself with get_instructions(kind=review) + get_glossary — you have more context than the server-side model and it costs the team nothing. Use this when you want the same verdict the web editor and Figma plugin would produce, or a second opinion. Each issue carries a severity (error | warning | suggestion) and the result carries maxSeverity — gate on that, not on `ok`, which is true only when there are no issues at all and so treats a punctuation preference like a mistranslation. Spends the shared Anthropic key; needs a token with write access.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "The text to review." },
+        target_language: {
+          type: "string",
+          description:
+            "Set for a translation review, e.g. 'German'. Omit to review English base copy.",
+        },
+        base_text: {
+          type: "string",
+          description: "The English source, when reviewing a translation.",
+        },
+        siblings: {
+          type: "array",
+          description:
+            "Other strings from the SAME component ({id, text}), so drift between them can be flagged. Max 8.",
+          items: {
+            type: "object",
+            properties: { id: { type: "string" }, text: { type: "string" } },
+          },
+        },
+      },
+      required: ["text"],
+    },
+    handler: async ({ text, target_language, base_text, siblings }) =>
+      api("/review-copy", {
+        method: "POST",
+        body: {
+          text,
+          ...(target_language ? { targetLanguage: target_language } : {}),
+          ...(base_text ? { baseText: base_text } : {}),
+          ...(Array.isArray(siblings) && siblings.length
+            ? { siblings: siblings.slice(0, 8) }
+            : {}),
+        },
+      }),
+  },
+
+  {
+    name: "suggest_ids",
+    description:
+      "Server-side AI triage of strings read off a design: IGNORE (sample data), REUSE (an existing component means this) or CREATE (a new convention-following ID). Prefer naming them yourself with get_naming_context + get_instructions(kind=naming) — cheaper, and you can see the design and the code. Use this when you want the editor/plugin-consistent answer, or its server-side validation of reuse IDs and namespaces. Spends the shared Anthropic key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prefix: {
+          type: "string",
+          description:
+            "Feature namespace hint, e.g. 'checkout'. Worth setting — it puts existing IDs from that namespace in front of the model.",
+        },
+        strings: {
+          type: "array",
+          description:
+            "Strings to triage (max 50). Include everything you read, even apparent sample data — deciding that is what IGNORE is for.",
+          items: {
+            type: "object",
+            properties: {
+              text: { type: "string" },
+              layer_name: { type: "string", description: "The design layer's name." },
+              page: { type: "string", description: "Design page, e.g. 'PCI Report'." },
+              frame: { type: "string", description: "Enclosing frame or component." },
+              candidates: {
+                type: "array",
+                items: { type: "string" },
+                description:
+                  "IDs you believe this may duplicate (max 10). Supplying these makes it a disambiguation: the model must pick one or nothing. Exact-text matches are found server-side anyway.",
+              },
+            },
+            required: ["text"],
+          },
+        },
+      },
+      required: ["strings"],
+    },
+    handler: async ({ prefix, strings }) => {
+      const out = await api("/suggest-ids", {
+        method: "POST",
+        body: {
+          ...(prefix ? { prefix } : {}),
+          strings: requireBatch(strings, "strings", 50).map((s) => ({
+            text: String(s.text || ""),
+            ...(s.layer_name ? { layerName: String(s.layer_name) } : {}),
+            ...(s.page ? { page: String(s.page) } : {}),
+            ...(s.frame ? { frame: String(s.frame) } : {}),
+            ...(Array.isArray(s.candidates) && s.candidates.length
+              ? { candidates: s.candidates.slice(0, 10).map(String) }
+              : {}),
+          })),
+        },
+      });
+      // Spelled out in the RESULT rather than the tool description: this is
+      // ~120 tokens that only matters once a triage has actually run, and a
+      // description is re-sent on every turn whether the tool is used or not.
+      return {
+        ...out,
+        howToApply: {
+          ignore: "Not UI copy. Don't add it.",
+          reuse:
+            'Use the existing `reuseId`; create nothing. reuseConfidence "exact" means identical catalog text and is safe to apply; "semantic" is meaning-level only — confirm with a human.',
+          create:
+            "Pass `suggestedId` to create_strings. `newNamespace: true` opens a new top-level namespace — worth confirming first.",
+          null: "Nothing valid was produced. Name it yourself or re-ask with more context.",
+        },
+      };
+    },
+  },
+];
+
+const WRITE_TOOLS = [
+  {
+    name: "create_strings",
+    description:
+      "Create new base (English) strings. Refuses IDs that already exist, because overwriting an entry would discard its translations — search first. IDs are lowercase dot-segmented, e.g. 'checkout.cta.confirm'. If you're naming strings read off a design, run suggest_ids first. Writes to the live shared catalog and appears in the team's edit history.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        strings: {
+          type: "array",
+          description: "Strings to create (max 100).",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Lowercase dot-segmented, max 80 chars." },
+              text: { type: "string", description: "The base English text." },
+              name: { type: "string", description: "Optional component name." },
+            },
+            required: ["id", "text"],
+          },
+        },
+      },
+      required: ["strings"],
+    },
+    handler: async ({ strings }) => {
+      const list = requireBatch(strings, "strings", 100);
+      const rejected = [];
+      const shaped = [];
+      for (const s of list) {
+        const id = String(s.id || "");
+        if (!id || !ID_RE.test(id) || id.length > ID_MAX)
+          rejected.push({
+            id,
+            reason:
+              "Invalid ID: lowercase letters/digits/hyphens in dot-separated segments, max 80 chars.",
+          });
+        else if (typeof s.text !== "string")
+          rejected.push({ id, reason: "`text` is required." });
+        else
+          shaped.push({
+            developerId: id,
+            text: s.text,
+            ...(s.name ? { name: String(s.name) } : {}),
+          });
+      }
+      // Only the shape-valid IDs are worth a round trip.
+      if (shaped.length) {
+        const { byId } = await lookup(shaped.map((c) => c.developerId));
+        for (const c of shaped.filter((c) => byId.has(c.developerId)))
+          rejected.push({
+            id: c.developerId,
+            reason: `Already exists (base text: ${JSON.stringify(
+              byId.get(c.developerId).base,
+            )}). Use update_strings, or pick a different ID — creating over it would erase its translations.`,
+          });
+      }
+      // All-or-nothing on validation: a partial create is the confusing case,
+      // where the agent believes it pushed N strings and N-2 landed.
+      if (rejected.length)
+        return { created: [], rejected, note: "Nothing was written." };
+      const out = await api("/v2/components", {
+        method: "POST",
+        body: { components: shaped },
+      });
+      return { created: (out.components || []).map((c) => c.id), rejected: [] };
+    },
+  },
+
+  {
+    name: "update_strings",
+    description:
+      "Update existing strings' text for one locale — base English, or a translation. Each update carries either `text` or `plurals`, never both.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        locale: {
+          type: "string",
+          description: "Locale to write, e.g. 'de'. Omit (or 'base') for English.",
+        },
+        updates: {
+          type: "array",
+          description: "Updates to apply (max 100).",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              text: { type: "string", description: "Plain replacement text." },
+              plurals: {
+                type: "object",
+                description:
+                  'Full plural map, e.g. {"one": "1 item", "other": "{{count}} items"}. Keys must be CLDR forms: zero, one, two, few, many, other.',
+                additionalProperties: { type: "string" },
+              },
+            },
+            required: ["id"],
+          },
+        },
+      },
+      required: ["updates"],
+    },
+    handler: async ({ locale, updates }) => {
+      const list = requireBatch(updates, "updates", 100);
+      const target = !locale || locale === "base" ? "base" : String(locale);
+      await assertLocale(target);
+      const rejected = [];
+      const shaped = [];
+      for (const u of list) {
+        const id = String(u.id || "");
+        const hasText = typeof u.text === "string";
+        const hasPlurals = !!(u.plurals && typeof u.plurals === "object");
+        if (hasText === hasPlurals)
+          rejected.push({ id, reason: "Provide exactly one of `text` or `plurals`." });
+        else if (hasPlurals) {
+          const bad = Object.keys(u.plurals).filter((f) => !PLURAL_FORMS.includes(f));
+          if (bad.length)
+            rejected.push({
+              id,
+              reason: `Not CLDR plural forms: ${bad.join(", ")}. Allowed: ${PLURAL_FORMS.join(", ")}.`,
+            });
+          else shaped.push({ developerId: id, plurals: u.plurals });
+        } else shaped.push({ developerId: id, text: u.text });
+      }
+      if (shaped.length) {
+        const { notFound } = await lookup(shaped.map((u) => u.developerId));
+        for (const id of notFound)
+          rejected.push({ id, reason: "No such string. Use create_strings for new IDs." });
+      }
+      if (rejected.length)
+        return { updated: 0, rejected, note: "Nothing was written." };
+      const out = await api("/v2/components", {
+        method: "PATCH",
+        body: { variantId: target, updates: shaped },
+      });
+      return { locale: target, updated: out.updated, rejected: [] };
+    },
+  },
+];
+
+const DELETE_TOOLS = [
+  {
+    name: "delete_strings",
+    description:
+      "Delete strings, or clear one locale's translation. IRREVERSIBLE — deleting an entry takes every translation with it and there is no undo. Call FIRST without `confirm` to preview what would be lost, show that to the user, and pass `confirm: true` only once they've agreed to those IDs. This cannot check whether the strings are still referenced in code or Figma — say so when you present the preview.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "String IDs to delete (max 25).",
+        },
+        locale: {
+          type: "string",
+          description:
+            "Clear only this locale's value and keep the entry. Omit to delete the whole entry.",
+        },
+        confirm: {
+          type: "boolean",
+          description:
+            "Must be true to write. Omitted or false returns a preview and deletes nothing.",
+        },
+      },
+      required: ["ids"],
+    },
+    handler: async ({ ids, locale, confirm }) => {
+      const list = requireBatch(ids, "ids", 25);
+      const target = !locale || locale === "base" ? null : String(locale);
+      if (target) await assertLocale(target);
+
+      // Build the loss report from the server BEFORE touching anything — after
+      // the delete this information doesn't exist anywhere reachable from here.
+      const { byId, notFound } = await lookup(list);
+      const found = [];
+      const missing = [...notFound];
+      for (const id of list) {
+        const e = byId.get(id);
+        if (!e) continue;
+        if (target) {
+          const v = e.translations ? e.translations[target] : undefined;
+          if (v === undefined) {
+            missing.push(`${id} (no ${target} value)`);
+            continue;
+          }
+          found.push({ id, locale: target, losing: v });
+        } else {
+          found.push({
+            id,
+            base: e.base,
+            losingTranslations: Object.keys(e.translations || {}),
+          });
+        }
+      }
+
+      const caveat =
+        "This server cannot check whether these IDs are still referenced in code or Figma — the editor's delete flow does that check, this one can't. Verify there before deleting anything that might still be live.";
+
+      if (!confirm)
+        return {
+          preview: true,
+          deleted: [],
+          wouldDelete: found,
+          notFound: missing,
+          scope: target
+            ? `Clears the ${target} value only; the entry and its other locales survive.`
+            : "Deletes the whole entry: base text, every translation, all plural forms.",
+          caveat,
+          nextStep:
+            "Show this to the user. If they approve, call again with the same ids and `confirm: true`.",
+        };
+
+      if (!found.length)
+        return { deleted: [], notFound: missing, note: "Nothing matched; nothing written." };
+
+      const out = await api("/v2/components", {
+        method: "DELETE",
+        body: {
+          ids: found.map((f) => f.id),
+          ...(target ? { variantId: target } : {}),
+        },
+      });
+      const deleted = out.deleted || [];
+      return {
+        deleted,
+        notFound: [...missing, ...(out.missing || [])],
+        lost: found.filter((f) => deleted.includes(f.id)),
+        caveat,
+      };
+    },
+  },
+];
+
+const TOOLS = READONLY
+  ? READ_TOOLS
+  : [...READ_TOOLS, ...WRITE_TOOLS, ...(ALLOW_DELETE ? DELETE_TOOLS : [])];
+const BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+
+// ── prompts ───────────────────────────────────────────────────────────────────
+//
+// Harvesting a screen is a five-step chain (read the design → triage → confirm
+// → create → report) and no tool description can carry that on its own. An MCP
+// prompt can: clients surface these as slash commands (`/mcp__dittomato__…` in
+// Claude Code), so the whole flow becomes one invocation — and unlike a tool
+// description, the text is only sent when someone invokes it.
+//
+// Note what ISN'T here: anything about reading images or Figma files. The host
+// model already has vision and, if configured, a Figma MCP — this server never
+// sees the design. Its job starts once there's a list of strings.
+
+const HARVEST_SCREEN = `Harvest the UI strings from this design into the Dittomato catalog.
+
+**1. Read the strings.** Take them from whatever the user gave you:
+- an image or screenshot → read the visible copy off it directly
+- a Figma URL or selection → use your Figma tools (get_design_context / get_metadata) to pull the text layers, which also gives you real layer, frame and page names
+- a code file → the literal strings in it
+
+Collect everything that renders as text, including things that look like sample
+data (dates, addresses, numbers). Do NOT pre-filter those out — step 2 decides.
+
+**2. Name them yourself.** Fetch the context once:
+- \`get_instructions(kind="naming")\` — the team's ID conventions and the rules for
+  what counts as copy vs sample data
+- \`get_naming_context({prefix, texts})\` — which namespaces exist, the
+  cross-cutting containers, what's already under the prefix, and per text any
+  existing entry with identical text (those are reuse candidates)
+- \`get_glossary({text})\` for anything whose wording you're unsure about
+
+Then decide, for each string: **IGNORE** (sample/demo data — dates, addresses,
+measurements — not UI copy), **REUSE** (an existing entry already means this) or
+**CREATE** (a new ID following the conventions).
+
+Do this rather than calling \`suggest_ids\`: you can see the design, the code and
+this conversation, and \`suggest_ids\` sends the same job to a second model on the
+server, billed to the team's Anthropic key, with none of that context. Reach for
+it only if you want the answer the web editor and Figma plugin would give, or its
+server-side validation of reuse IDs.
+
+Two rules the conventions won't state for you:
+- An ID always has a namespace. Never propose a bare one-word ID — if no feature
+  owns the string, that's what the generic containers are for.
+- Check \`namespaceNames\` (the full list) before calling a namespace new;
+  \`namespaces\` is ranked and truncated.
+
+**3. Show the user a table before writing anything.** Group by verdict:
+- **REUSE** — show the existing ID and its text, so the user can confirm it
+  really means the same thing. Identical text is safe; a meaning-level match is a
+  judgement call — flag it rather than assuming.
+- **CREATE** — show the proposed ID and one line of reasoning. Call out anything
+  opening a new top-level namespace; that's worth a human decision.
+- **IGNORE** — list them briefly so the user can spot a misfire, e.g. real copy
+  mistaken for sample data.
+
+**4. Create only what the user approves.** Call \`create_strings\` with the
+approved CREATE rows only. Never create an ID for a REUSE row — that's the
+duplicate this whole flow exists to prevent. This writes to the live shared
+catalog and appears in the team's edit history.
+
+**5. Report** which IDs were created, which existing IDs to reuse, and anything
+left unresolved. If the user is wiring these into code, give them the IDs in the
+form their codebase uses.`;
+
+const TRANSLATE_GAPS = `Find and fill translation gaps in the Dittomato catalog.
+
+**1. Scope it.** Ask which locale, and which ID prefix or feature area, unless
+the user already said. Then call \`translation_coverage\` to see how big the gap
+actually is before doing anything.
+
+**2. Pull the source text** for the missing IDs with \`get_strings\`. Watch for
+pluralized entries — those need a full CLDR form map, not a single string.
+
+**3. Translate against the house rules, yourself.** Fetch
+\`get_instructions(kind="translate")\` once, and \`get_glossary({text})\` per string
+(it filters to the terms that string actually mentions). Follow the glossary
+verbatim — it carries product names that must never be translated or swapped for
+a synonym. That's the difference between a plausible translation and one that
+matches the rest of the product.
+
+\`review_copy\` does the same check on the server with a second model call. Use it
+for a second opinion on something you're unsure of, not as the default.
+
+**4. Show the user the proposed translations for review**, then write the
+approved ones with \`update_strings\` for that locale. Plural entries take
+\`plurals\` (a full form map), plain ones take \`text\` — never both.
+
+Do not machine-translate a whole namespace and push it unreviewed. Small
+reviewed batches.`;
+
+const PROMPTS = [
+  {
+    name: "harvest_screen",
+    description:
+      "Read the UI strings off a design (image, Figma selection, or code), name them per the team's conventions, catch duplicates, and create the new ones.",
+    arguments: [
+      {
+        name: "prefix",
+        description: "Feature namespace hint, e.g. 'checkout' — improves the suggested IDs.",
+        required: false,
+      },
+    ],
+    build: ({ prefix } = {}) =>
+      HARVEST_SCREEN +
+      (prefix
+        ? `\n\nThe user says this screen belongs to the **${prefix}** feature area — pass that as \`prefix\`.`
+        : ""),
+  },
+  {
+    name: "translate_gaps",
+    description:
+      "Find untranslated strings for a locale and fill them, checked against the team's glossary and style guide.",
+    arguments: [
+      { name: "locale", description: "Target locale, e.g. 'de'.", required: false },
+      { name: "prefix", description: "Restrict to IDs under this prefix.", required: false },
+    ],
+    build: ({ locale, prefix } = {}) =>
+      TRANSLATE_GAPS +
+      (locale || prefix
+        ? `\n\nScope for this run:${locale ? ` locale **${locale}**.` : ""}${
+            prefix ? ` prefix **${prefix}**.` : ""
+          }`
+        : ""),
+  },
+];
+
+const PROMPTS_BY_NAME = new Map(PROMPTS.map((p) => [p.name, p]));
+
+// ── server ────────────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: "dittomato", version: VERSION },
+  { capabilities: { tools: {}, prompts: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({
+    name,
+    description,
+    inputSchema,
+  })),
+}));
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: PROMPTS.map(({ name, description, arguments: args }) => ({
+    name,
+    description,
+    arguments: args,
+  })),
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+  const prompt = PROMPTS_BY_NAME.get(req.params.name);
+  if (!prompt) throw new Error(`Unknown prompt: ${req.params.name}`);
+  return {
+    description: prompt.description,
+    messages: [
+      {
+        role: "user",
+        content: { type: "text", text: prompt.build(req.params.arguments || {}) },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = BY_NAME.get(req.params.name);
+  if (!tool)
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+    };
+  try {
+    const result = await tool.handler(req.params.arguments || {});
+    // Compact, not pretty-printed. Indentation measured at 27% of a
+    // search_strings payload, and nothing reads these but a model.
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  } catch (e) {
+    // Hand the message back as tool output rather than a protocol error, so the
+    // model can read "read-only token" / "no such locale" and correct itself.
+    return { isError: true, content: [{ type: "text", text: `${e.message}` }] };
+  }
+});
+
+// Exported for index.test.js — the handlers carry all the validation worth
+// testing, and reaching them through a spawned stdio process for every case
+// would be slow and hide assertion detail. DELETE_TOOLS separately because it's
+// normally absent from TOOLS.
+module.exports = {
+  TOOLS,
+  BY_NAME,
+  DELETE_TOOLS,
+  PROMPTS,
+  ID_RE,
+  PLURAL_FORMS,
+  _resetCache: () => {
+    variantsCache = null;
+    variantsAt = 0;
+  },
+};
+
+async function main() {
+  if (!HOST || !TOKEN)
+    process.stderr.write(
+      "dittomato-mcp: DITTO_API_HOST and/or DITTO_API_KEY are unset — every tool " +
+        "call will fail until they're configured in the MCP server's env.\n",
+    );
+  process.stderr.write(
+    `dittomato-mcp ${VERSION} ready (${TOOLS.length} tools${
+      READONLY ? ", read-only" : ALLOW_DELETE ? ", delete ENABLED" : ""
+    })\n`,
+  );
+  await server.connect(new StdioServerTransport());
+}
+
+if (require.main === module)
+  main().catch((e) => {
+    process.stderr.write(`dittomato-mcp: fatal: ${e.message}\n`);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@vialytics/dittomato-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for a Dittomato backend — search, read and write UI strings from any MCP-capable editor or agent.",
+  "bin": {
+    "dittomato-mcp": "index.js"
+  },
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test",
+    "build:bundle": "npx -y esbuild@0.28.2 index.js --bundle --platform=node --target=node18 --format=cjs --minify --legal-comments=none --outfile=build/index.js && cp manifest.json README.md build/",
+    "build:pack": "npx -y @anthropic-ai/mcpb@2.1.2 pack build dittomato-mcp.mcpb",
+    "build:sign": "npx -y @anthropic-ai/mcpb@2.1.2 sign -c .signing/cert.pem -k .signing/key.pem dittomato-mcp.mcpb",
+    "build:mcpb": "npm run build:bundle && npm run build:pack && npm run build:sign",
+    "signing:init": "mkdir -p .signing && openssl req -x509 -newkey rsa:2048 -keyout .signing/key.pem -out .signing/cert.pem -days 3650 -nodes -subj \"/CN=vialytics/O=vialytics GmbH/C=DE\" && chmod 600 .signing/key.pem"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vialytics/dittomato.git",
+    "directory": "mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ditto",
+    "dittomato",
+    "i18n",
+    "translations"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}