@cloudhal/mcp-server 0.0.0-stage → 0.1.1

package/dist/src/translation-tools.js

@@ -0,0 +1,422 @@
+/**
+ * RFC-0033 §6 / ADR-0035: translating pages and entries. The agent translates with its own model;
+ * the server keeps the rules. `get_translation_source` hands over the source, the glossary terms
+ * it uses and the current translation; `save_translation` writes a draft in the target locale,
+ * linked to the source revision, with its provenance and the deterministic checks
+ * (`checkTranslation`). Agents never review: only a person does, in Studio. A translation a person
+ * wrote or reviewed is never overwritten here.
+ */
+import { forSite, holds } from "@cloudhal/agent-runtime";
+             
+               
+           
+       
+          
+       
+              
+                                  
+import {
+  checkNames,
+  checkTranslation,
+  forEdition,
+  linkedLayout,
+                        
+} from "@cloudhal/core-ts";
+import {
+  autoSnapshot,
+  id,
+  mapError,
+  obj,
+  requireSite,
+  str,
+                   
+                      
+  ToolError,
+} from "./common.js";
+import { ENTRY, mcpWriter, PAGE, SNAPSHOT, sectionInput } from "./content-shared.js";
+
+                                     
+
+const READ = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+}         ;
+
+/** A page or entry of the site by id. */
+async function nodeOf(ctx             , siteId        , nodeId        )                     {
+  const node = (await ctx.store.getPage(nodeId)) ?? (await ctx.store.getContentEntry(nodeId));
+  if (!node || node.siteId !== siteId)
+    throw new ToolError("not_found", `page or entry ${nodeId} not found`);
+  return node;
+}
+
+/** The glossary entries a text uses (all of them for a short glossary). */
+function glossaryFor(glossary                      , text        , locale        ) {
+  const lower = text.toLocaleLowerCase();
+  return (glossary?.entries ?? [])
+    .filter((e) =>
+      e.caseSensitive ? text.includes(e.term) : lower.includes(e.term.toLocaleLowerCase()),
+    )
+    .map((e) => ({
+      term: e.term,
+      ...(e.doNotTranslate ? { doNotTranslate: true } : {}),
+      ...(e.translations?.[locale] ? { translation: e.translations[locale]?.text } : {}),
+      ...(e.note ? { note: e.note } : {}),
+    }));
+}
+
+const GROUP = {
+  type: "object",
+  properties: {
+    group: { type: "string" },
+    members: { type: "array", items: { type: "object" } },
+  },
+  required: ["group", "members"],
+};
+
+const listTranslationsTool                 = {
+  name: "list_translations",
+  title: "List translations",
+  description:
+    "Every language version of a page or entry (its translation group): locale, status, method (original, human, machine, machine-reviewed), whether it is stale (its source changed since) and reviewed.",
+  inputSchema: obj({ siteId: id, nodeId: id }, ["siteId", "nodeId"]),
+  outputSchema: obj({ group: GROUP }, ["group"]),
+  annotations: READ,
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const node = await nodeOf(ctx, site.id, a.nodeId          );
+    const group                   = await ctx.store.translationGroup(
+      site,
+      node.translation?.group ?? node.id,
+    );
+    return { group };
+  },
+};
+
+const getSourceTool                 = {
+  name: "get_translation_source",
+  title: "Get translation source",
+  description:
+    "What you need to translate a page or entry into `locale`: the source (translate its title, text, summary and SEO; keep section ids, kinds, links, numbers, images and bindings), the glossary terms it uses (doNotTranslate terms stay as written, given translations are used), and the current translation in that locale if there is one (with `stale` when the source changed since, and for a linked page whose source changed its layout, `layout`: the translation's sections on the new layout, with the `untranslated` ones to translate). Then call save_translation.",
+  inputSchema: obj(
+    {
+      siteId: id,
+      nodeId: id,
+      locale: str("Target BCP 47 locale"),
+      targetSiteId: {
+        ...id,
+        description:
+          "A language edition: another site of the project the translation lives on (RFC-0034 §6); default siteId",
+      },
+    },
+    ["siteId", "nodeId", "locale"],
+  ),
+  outputSchema: obj(
+    {
+      source: { type: "object" },
+      glossary: { type: "array", items: { type: "object" } },
+      existing: { type: "object" },
+      stale: { type: "boolean" },
+      layout: {
+        type: "object",
+        description:
+          "A linked page translation rebuilt on the source's current layout: translate the sections named in `untranslated` and save these sections",
+      },
+    },
+    ["source", "glossary"],
+  ),
+  annotations: READ,
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const target = await targetOf(ctx, site, a.targetSiteId);
+    const locale = a.locale          ;
+    if (!target.locales.includes(locale))
+      throw new ToolError("locale_not_enabled", `${locale} is not one of the site's locales`);
+    const source = await nodeOf(ctx, site.id, a.nodeId          );
+    const group = await ctx.store.translationGroup(site, source.translation?.group ?? source.id);
+    const member = group.members.find((m) => m.locale === locale && m.siteId === target.id);
+    const existing = member ? await nodeOf(ctx, target.id, member.id) : undefined;
+    const text = JSON.stringify("sections" in source ? source.sections : source.body.value);
+    // RFC-0033 §4a: a linked page translation follows the source's layout; nothing is written.
+    const layout =
+      existing &&
+      "sections" in existing &&
+      "sections" in source &&
+      existing.translation?.layout !== "independent"
+        ? linkedLayout(source, existing)
+        : undefined;
+    return {
+      source,
+      glossary: glossaryFor(
+        await ctx.store.glossary.get(site.id),
+        `${source.title} ${text}`,
+        locale,
+      ),
+      ...(existing ? { existing, stale: member?.stale === true } : {}),
+      ...(layout?.changed ? { layout } : {}),
+    };
+  },
+};
+
+const saveTranslationTool                 = {
+  name: "save_translation",
+  title: "Save translation",
+  description:
+    "Save your translation of a page or entry into `locale` as a draft linked to the source's current revision, with your model as its provenance. Pages: send title, path and sections (same ids, kinds and order as the source; translated text). Entries: title, slug, body and summary. The checks (structure, links, numbers, glossary, length) run and are returned; a failed check keeps it from being published until fixed. A person reviews it in Studio before it goes live where the site asks for review. Refused for a translation a person wrote or reviewed. Snapshots afterwards.",
+  inputSchema: obj(
+    {
+      siteId: id,
+      nodeId: { ...id, description: "The source page or entry" },
+      locale: str("Target BCP 47 locale"),
+      title: str("Translated title"),
+      path: str("Pages: the translated page's path in its locale, e.g. /acerca"),
+      slug: str("Entries: the translated entry's slug"),
+      sections: sectionInput,
+      body: str("Entries: the translated markdown body"),
+      summary: str("Entries: the translated summary"),
+      coverAlt: str(
+        "Entries: the cover image's alt text in `locale`. Without it a new translation leaves the cover alt empty, so the image's own alt text in `locale` (update_asset) is shown",
+        { maxLength: 500 },
+      ),
+      seo: { type: "object", description: "Pages: the translated SEO title and description" },
+      engine: str("The model that translated, e.g. claude-opus-5-5"),
+      targetSiteId: {
+        ...id,
+        description:
+          "A language edition: another site of the project to save the translation on (RFC-0034 §6). Its images are copied there and its categories and tags become the edition's terms with the same slugs (create missing ones there first). Default siteId",
+      },
+    },
+    ["siteId", "nodeId", "locale", "title"],
+  ),
+  outputSchema: obj(
+    {
+      node: { oneOf: [PAGE, ENTRY] },
+      checks: { type: "array", items: { type: "object" } },
+      snapshot: SNAPSHOT,
+    },
+    ["node", "checks", "snapshot"],
+  ),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["content:write"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const target = await targetOf(ctx, site, a.targetSiteId);
+    const cross = target.id !== site.id;
+    const locale = a.locale          ;
+    if (cross && !target.locales.includes(locale))
+      throw new ToolError("locale_not_enabled", `${locale} is not one of the edition's locales`);
+    let source = await nodeOf(ctx, site.id, a.nodeId          );
+    if (source.locale === locale)
+      throw new ToolError("invalid", "the translation's locale differs from its source's");
+    // The source becomes the group's original the first time it is translated (a new revision).
+    if (!source.translation) source = await markOriginal(ctx, source);
+    const group = await ctx.store.translationGroup(site, source.translation?.group ?? source.id);
+    const self = group.members.find((m) => m.id === source.id);
+    const member = group.members.find((m) => m.locale === locale && m.siteId === target.id);
+    const existing = member ? await nodeOf(ctx, target.id, member.id) : undefined;
+    const t = existing?.translation;
+    if (t && (t.method === "human" || t.method === "original" || t.review))
+      throw new ToolError(
+        "denied",
+        `${existing?.id} was written or reviewed by a person; ask them to update it (or propose changes)`,
+      );
+    const translation              = {
+      group: source.translation?.group ?? source.id,
+      method: "machine",
+      layout: t?.layout ?? "linked",
+      source: {
+        id: source.id,
+        ...(cross ? { siteId: site.id } : {}),
+        locale: source.locale,
+        rev: source.rev,
+        hash: self?.hash ?? "",
+      },
+      provenance: {
+        engine:
+          (a.engine                      ) ?? ctx.principal.actor.name ?? ctx.principal.actor.id,
+        at: (ctx.now?.() ?? new Date()).toISOString(),
+      },
+    };
+    try {
+      const made = translatedNode({ a, site: target.id, locale, source, existing, translation });
+      // RFC-0034 §6: on an edition, the images come along and the terms are the edition's.
+      const draft = cross
+        ? await forEdition(ctx.store, made, {
+            fromSiteId: site.id,
+            toSiteId: target.id,
+            actor: ctx.principal.actor,
+          })
+        : made;
+      const glossary = await ctx.store.glossary.get(target.id);
+      const checks = checkTranslation({ source, draft, locale, glossary });
+      const withChecks              = {
+        ...translation,
+        provenance: {
+          ...(translation.provenance                                          ),
+          checks: checkNames(checks),
+          ...(glossary ? { glossaryRev: glossary.rev } : {}),
+        },
+      };
+      const node = await writeTranslation(
+        ctx,
+        target.id,
+        { ...draft, translation: withChecks }             ,
+        existing,
+      );
+      const snapshot = await autoSnapshot(ctx, target.id, "save_translation");
+      return { node, checks, snapshot };
+    } catch (e) {
+      mapError(e);
+    }
+  },
+};
+
+/**
+ * The site a translation lives on: `siteId`'s own, or with `targetSiteId` another site of the same
+ * project (a language edition, RFC-0034 §6) the caller may write to.
+ */
+async function targetOf(ctx             , site      , targetSiteId         )                {
+  if (typeof targetSiteId !== "string" || targetSiteId === site.id) return site;
+  const target = await ctx.store.getSite(targetSiteId);
+  const scoped = target ? forSite(ctx.principal, target.id) : undefined;
+  if (!target || target.projectId !== site.projectId || !scoped)
+    throw new ToolError("not_found", `no site ${targetSiteId} in this site's project`);
+  if (!holds(scoped.scopes, "content:write"))
+    throw new ToolError("denied", "missing scope content:write on the edition");
+  return target;
+}
+
+/** The source gains `translation: { group: its id, method: "original" }`. */
+async function markOriginal(ctx             , source           )                     {
+  const translation              = { group: source.id, method: "original" };
+  try {
+    if ("sections" in source)
+      return await ctx.store.updatePage({ ...source, translation }, { writer: mcpWriter(ctx) });
+    return await ctx.store.updateContentEntry(
+      { ...source, translation },
+      { writer: mcpWriter(ctx) },
+    );
+  } catch (e) {
+    mapError(e);
+  }
+}
+
+/** The draft node: a new translation, or the existing machine one with the new text. */
+function translatedNode(input   
+                             
+               
+                 
+                    
+                                  
+                           
+ )            {
+  const { a, site, locale, source, existing, translation } = input;
+  const common = {
+    siteId: site,
+    locale,
+    status: "draft"         ,
+    title: a.title          ,
+    translation,
+  };
+  if ("sections" in source) {
+    const base = (existing                    ) ?? { ...source, id: "", rev: 0 };
+    return {
+      ...base,
+      ...common,
+      path: (a.path                      ) ?? base.path,
+      ...(a.seo ? { seo: a.seo                } : {}),
+      sections: (a.sections                         ) ?? base.sections,
+    }        ;
+  }
+  const base = (existing                            ) ?? { ...source, id: "", rev: 0 };
+  const cover = translatedCover(base.coverImage, a.coverAlt                      , !existing);
+  const { coverImage: _cover, ...rest } = base;
+  return {
+    ...rest,
+    ...common,
+    slug: (a.slug                      ) ?? base.slug,
+    body: { format: "markdown", value: (a.body                      ) ?? base.body.value },
+    ...(a.summary !== undefined ? { summary: a.summary           } : {}),
+    ...(cover ? { coverImage: cover } : {}),
+  }                ;
+}
+
+/**
+ * The cover of a translated entry: the given alt text in its language, or — for a new translation
+ * — no copy of the source's alt override, which is in the source's language.
+ */
+function translatedCover(
+  cover                            ,
+  alt                    ,
+  fresh         ,
+)                             {
+  if (!cover) return undefined;
+  if (alt !== undefined) return { ...cover, alt };
+  // An empty alt falls back to the image's own alt text in the entry's language.
+  return fresh ? { ...cover, alt: "" } : cover;
+}
+
+/** Creates the translation or updates the existing one (CAS on its `rev`). */
+async function writeTranslation(
+  ctx             ,
+  siteId        ,
+  node           ,
+  existing                       ,
+)                     {
+  const writer = { writer: mcpWriter(ctx) };
+  if (existing && "sections" in node) return ctx.store.updatePage(node, writer);
+  if (existing) return ctx.store.updateContentEntry(node                , writer);
+  const { id: _id, rev: _rev, createdAt: _c, updatedAt: _u, schemaVersion: _s, ...fresh } = node;
+  if ("sections" in node) {
+    const site = await requireSite(ctx, siteId);
+    return (await ctx.store.createPage(site, fresh        , writer)).page;
+  }
+  const { publishedAt: _p, corrections: _k, ...entry } = fresh                ;
+  return ctx.store.createContentEntry(
+    { ...entry, author: ctx.principal.actor }                ,
+    writer,
+  );
+}
+
+const listStaleTool                 = {
+  name: "list_stale_translations",
+  title: "List stale translations",
+  description:
+    "Translations whose source changed since they were made (or whose source is gone), optionally in one locale: the work queue for keeping languages in step. Re-translate each with get_translation_source and save_translation.",
+  inputSchema: obj({ siteId: id, locale: str("Only this locale") }, ["siteId"]),
+  outputSchema: obj({ stale: { type: "array", items: { type: "object" } } }, ["stale"]),
+  annotations: READ,
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const nodes              = [
+      ...(await ctx.store.listPages(site.id)),
+      ...(await ctx.store.listContentEntries(site.id)),
+    ];
+    const groups = [...new Set(nodes.flatMap((n) => (n.translation ? [n.translation.group] : [])))];
+    const stale = [];
+    for (const g of groups)
+      for (const m of (await ctx.store.translationGroup(site, g)).members)
+        if (
+          (m.stale || m.sourceMissing) &&
+          m.siteId === site.id &&
+          (!a.locale || m.locale === a.locale)
+        )
+          stale.push({ ...m, group: g });
+    return { stale };
+  },
+};
+
+/** list_translations, list_stale_translations, get_translation_source, save_translation. */
+export function translationTools()                   {
+  return [listTranslationsTool, listStaleTool, getSourceTool, saveTranslationTool];
+}

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@cloudhal/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Cloudhal MCP server: semantic site tools (pages, articles, snapshots, preview, publish) governed by the policy engine",
+  "license": "Apache-2.0",
+  "homepage": "https://cloudhal.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudhal-dev/cloudhal.git",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/cloudhal-dev/cloudhal/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./tools": {
+      "types": "./dist/src/tools.d.ts",
+      "default": "./dist/src/tools.js"
+    },
+    "./body": {
+      "types": "./dist/src/body-tools.d.ts",
+      "default": "./dist/src/body-tools.js"
+    },
+    "./analytics": {
+      "types": "./dist/src/analytics-reports.d.ts",
+      "default": "./dist/src/analytics-reports.js"
+    },
+    "./comments": {
+      "types": "./dist/src/comments.d.ts",
+      "default": "./dist/src/comments.js"
+    },
+    "./schedules": {
+      "types": "./dist/src/schedules.d.ts",
+      "default": "./dist/src/schedules.js"
+    },
+    "./render": {
+      "types": "./dist/src/render.d.ts",
+      "default": "./dist/src/render.js"
+    },
+    "./stdio": {
+      "types": "./dist/src/stdio.d.ts",
+      "default": "./dist/src/stdio.js"
+    },
+    "./http": {
+      "types": "./dist/src/http.d.ts",
+      "default": "./dist/src/http.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@cloudhal/analytics": "0.1.1",
+    "@cloudhal/agent-runtime": "0.1.1",
+    "@cloudhal/astro-renderer": "0.1.1",
+    "@cloudhal/comments": "0.1.1",
+    "@cloudhal/core-contracts": "0.1.1",
+    "@cloudhal/core-ts": "0.1.1",
+    "@cloudhal/storage": "0.1.1",
+    "@modelcontextprotocol/server": "2.3.1",
+    "@cloudhal/schedules": "0.1.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261007.1",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@types/node": "^26.6.5",
+    "better-sqlite3": "13.0.3",
+    "happy-dom": "^21.0.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm test"
+  }
 }