drupal-mcp-connector 2.15.2 → 2.17.0

package/src/tools/media.js

@@ -14,6 +14,11 @@ import {
   resolveSecurityConfig, redactCanonicalEntity,
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
 } from "../lib/security.js";
+import {
+  assertDraftLangcode, readDraftTranslation, readTranslationInventory, writeDraft,
+} from "../lib/draft-write.js";
+import { assertInventoryDraftLanguage } from "../lib/node-draft-inventory.js";
+import { entityRevisionId } from "../lib/write-revision.js";
 
 /**
  * List all media types (bundles of the media entity type).
@@ -51,14 +56,39 @@ async function listMedia({ site: siteName, type, status, name, limit = 20, offse
 
 /**
  * Fetch a single media entity by UUID, redacted per policy.
- * @param {object} args - { site?, type, id }.
+ * Pass langcode to read an unpublished working translation via Sentinel.
+ * @param {object} args - { site?, type, id, langcode? }.
  * @returns {Promise<object|null>} The redacted media entity, or null.
  */
-async function getMedia({ site: siteName, type, id }) {
+async function getMedia({ site: siteName, type, id, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "media", type);
   const backend = await resolveBackend(site);
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const inventory = await readTranslationInventory(backend, { entityType: "media", bundle: type, id });
+    const workingRow = (inventory.working?.translations ?? []).find((row) => row.langcode === targetLang);
+    if (workingRow && workingRow.status === false && inventory.live?.vid && inventory.working?.vid) {
+      const entity = await readDraftTranslation(backend, {
+        entityType: "media", bundle: type, id, langcode: targetLang,
+        draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
+      });
+      return redactCanonicalEntity(entity, sec, "media");
+    }
+    const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
+    if (!liveHas) return null;
+    if (targetLang !== inventory.defaultLangcode) {
+      const liveRow = (inventory.live.translations ?? []).find((row) => row.langcode === targetLang);
+      return {
+        id, entityType: "media", bundle: type, langcode: targetLang,
+        status: liveRow?.status ?? null,
+        fields: { name: liveRow?.name ?? null },
+        _revisions: { live: inventory.live.vid, working: inventory.working?.vid ?? null },
+        note: "Published non-default translations are listed on the live revision; full field reads of an unpublished working translation use langcode against the working draft.",
+      };
+    }
+  }
   const entity = await backend.getEntity({ entityType: "media", bundle: type, id });
   return entity ? redactCanonicalEntity(entity, sec, "media") : null;
 }
@@ -91,12 +121,13 @@ async function createMedia({ site: siteName, type, name, status = false, fields
 /**
  * Update a media entity (partial — omitted fields are left untouched; `status`
  * is strictly opt-in, #171). Reference-shaped `fields` values are routed to
- * relationships — see splitReferenceFields.
+ * relationships — see splitReferenceFields. Pass langcode to continue an
+ * unpublished working translation via Sentinel (not a canonical live PATCH).
  *
- * @param {object} args - { site?, type, id, name?, status?, fields? }.
+ * @param {object} args - { site?, type, id, name?, status?, fields?, langcode? }.
  * @returns {Promise<object>} The updated media descriptor.
  */
-async function updateMedia({ site: siteName, type, id, name, status, fields = {} }) {
+async function updateMedia({ site: siteName, type, id, name, status, fields = {}, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "media", type);
@@ -105,6 +136,30 @@ async function updateMedia({ site: siteName, type, id, name, status, fields = {}
   if (status !== undefined) attributes.status = status;
   assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const inventory = await readTranslationInventory(backend, { entityType: "media", bundle: type, id });
+    assertInventoryDraftLanguage(inventory, targetLang);
+    const liveVid = inventory.live?.vid;
+    const workingVid = inventory.working?.vid;
+    if (!liveVid || !workingVid || String(workingVid) === String(liveVid)) {
+      throw new Error(
+        "No unpublished working translation for this language. " +
+        "Create it with drupal_create_translation first; a canonical langcode PATCH is not attempted.",
+      );
+    }
+    const result = await writeDraft(backend, {
+      entityType: "media", bundle: type, id, attributes, langcode: targetLang,
+      ...(relationships ? { relationships } : {}),
+      draftRevision: { liveVid, workingVid },
+    });
+    const redacted = redactCanonicalEntity(result, sec, "media");
+    const working = entityRevisionId(result) ?? workingVid;
+    return {
+      ...redacted,
+      _revisions: { live: liveVid, working },
+    };
+  }
   // #171: pre-read so an unrequested published-state flip is reported, not silent.
   let existing = null;
   if (status === undefined) {
@@ -241,13 +296,14 @@ export const definitions = [
   },
   {
     name: "drupal_get_media",
-    description: "Fetch a single media entity by UUID and media type.",
+    description: "Fetch a single media entity by UUID and media type. Image alt/title are on the file relationship (meta.alt / meta.title). Pass langcode to read an unpublished working translation via Sentinel.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
         site: { type: "string" },
         type: { type: "string" },
         id:   { type: "string", description: "Media entity UUID" },
+        langcode: { type: "string", description: "Target language (e.g. 'es') to read the unpublished working translation instead of the default language." },
       },
     },
   },
@@ -267,7 +323,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_media",
-    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.",
+    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -276,7 +332,8 @@ export const definitions = [
         id:     { type: "string" },
         name:   { type: "string" },
         status: { type: "boolean", description: "Published flag. Only sent when provided; requires allowPublish when true." },
-        fields: { type: "object", description: "Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically." },
+        fields: { type: "object", description: "Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically. Image alt is meta.alt on field_media_image with the existing file UUID." },
+        langcode: { type: "string", description: "Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode." },
       },
     },
   },

package/src/tools/moderation.js

@@ -21,6 +21,9 @@ import {
   redactCanonicalEntity,
 } from "../lib/security.js";
 import { collectEntities } from "../lib/reports-support.js";
+import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { assertDraftLangcode, readTranslationInventory } from "../lib/draft-write.js";
+import { inventoryRowMatching } from "../lib/translation-rows.js";
 
 /** Cap for the client-side scan when JSON:API cannot filter the field. */
 const SAMPLE_CAP = 500;
@@ -54,7 +57,7 @@ function moderationStateOf(entity) {
  * @returns {Promise<object>} The updated, redacted node.
  * @throws {SecurityError} If writing node/type is not permitted.
  */
-async function setModerationState({ site: siteName, type, id, state }) {
+async function setModerationState({ site: siteName, type, id, state, langcode }) {
   if (!state) throw new Error("A moderation 'state' is required (e.g. 'draft', 'published').");
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
@@ -62,6 +65,23 @@ async function setModerationState({ site: siteName, type, id, state }) {
   const attributes = { moderation_state: state };
   assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    let existing = null;
+    try {
+      existing = (await backend.getEntity({ entityType: "node", bundle: type, id })) ?? null;
+    } catch {
+      existing = null;
+    }
+    const patchTarget = await prepareGuardedPatch(backend, {
+      entityType: "node", bundle: type, id, existing, attributes, langcode: targetLang,
+    });
+    const patched = await updateEntityGuarded(backend, {
+      entityType: "node", bundle: type, id, attributes, langcode: targetLang,
+      ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
+    });
+    return redactCanonicalEntity(patched, sec, "node");
+  }
   const entity = await backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
   return redactCanonicalEntity(entity, sec, "node");
 }
@@ -76,12 +96,59 @@ async function setModerationState({ site: siteName, type, id, state }) {
  *
  * @param {object} args - { site?, type, state, limit?, offset? }.
  */
-async function contentByModerationState({ site: siteName, type, state, limit = 20, offset = 0 }) {
+async function contentByModerationState({ site: siteName, type, state, limit = 20, offset = 0, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
   const sort = [{ field: "changed", dir: "desc" }];
+  const targetLang = langcode ? assertDraftLangcode(langcode) : null;
+  if (targetLang) {
+    if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
+      return {
+        type, state, langcode: targetLang, unavailable: true,
+        reason: "A langcode filter requires Sentinel's translation inventory.",
+      };
+    }
+    const scanned = await collectEntities(
+      backend,
+      { entityType: "node", bundle: type, sort },
+      SAMPLE_CAP,
+    );
+    const matches = [];
+    for (const entity of scanned) {
+      try {
+        const inventory = await readTranslationInventory(backend, {
+          entityType: "node", bundle: type, id: entity.id,
+        });
+        const row = inventoryRowMatching(inventory, { langcode: targetLang, state });
+        if (row) {
+          matches.push({
+            ...entity,
+            langcode: targetLang,
+            fields: { ...entity.fields, moderation_state: row.moderation_state },
+          });
+        }
+      } catch (error) {
+        if (/does not provide Sentinel's governed draft-translation endpoint/.test(String(error?.message))) {
+          return {
+            type, state, langcode: targetLang, unavailable: true,
+            reason: "A langcode filter requires Sentinel's translation inventory.",
+          };
+        }
+        throw error;
+      }
+    }
+    const page = matches.slice(offset, offset + limit);
+    return {
+      type, state, langcode: targetLang, source: "inventory",
+      approximate: scanned.length >= SAMPLE_CAP,
+      scanned: scanned.length,
+      total: matches.length,
+      offset, nextOffset: offset + page.length,
+      nodes: page.map((e) => redactCanonicalEntity(e, sec, "node")),
+    };
+  }
   const canFilter = typeof backend.capabilities === "function"
     ? Boolean(backend.capabilities()?.filter)
     : true;
@@ -167,28 +234,30 @@ async function listModerationStates({ site: siteName, type, sample = 50 }) {
 export const definitions = [
   {
     name: "drupal_set_moderation_state",
-    description: "Transition a content node to a moderation state (content_moderation), e.g. 'draft', 'needs_review', 'published', 'archived'. Governed write.",
+    description: "Transition a content node to a moderation state (content_moderation), e.g. 'draft', 'needs_review', 'published', 'archived'. Governed write. Pass langcode to change one translation via Sentinel; omit it for the default-language / shared-state write. If moderation_state is not translatable, a langcode write is refused.",
     inputSchema: {
       type: "object", required: ["type", "id", "state"],
       properties: {
-        site:  { type: "string" },
-        type:  { type: "string", description: "Content type machine name" },
-        id:    { type: "string", description: "Node UUID" },
-        state: { type: "string", description: "Target moderation state machine name" },
+        site:     { type: "string" },
+        type:     { type: "string", description: "Content type machine name" },
+        id:       { type: "string", description: "Node UUID" },
+        state:    { type: "string", description: "Target moderation state machine name" },
+        langcode: { type: "string", description: "Target translation (e.g. 'es'). Omit for the default language. Requires Sentinel." },
       },
     },
   },
   {
     name: "drupal_content_by_moderation_state",
-    description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review'). Stock JSON:API cannot filter the computed moderation_state field; when the site rejects that filter the tool samples recent nodes client-side and marks the result approximate, instead of returning Drupal's 500.",
+    description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review'). Pass langcode to match that translation via Sentinel inventory (the editorial work queue). Omit langcode for default-language JSON:API / sampled behavior. Stock JSON:API cannot filter the computed moderation_state field; when the site rejects that filter the tool samples recent nodes client-side and marks the result approximate, instead of returning Drupal's 500.",
     inputSchema: {
       type: "object", required: ["type", "state"],
       properties: {
-        site:   { type: "string" },
-        type:   { type: "string", description: "Content type machine name" },
-        state:  { type: "string", description: "Moderation state machine name" },
-        limit:  { type: "number", default: 20 },
-        offset: { type: "number", default: 0 },
+        site:     { type: "string" },
+        type:     { type: "string", description: "Content type machine name" },
+        state:    { type: "string", description: "Moderation state machine name" },
+        langcode: { type: "string", description: "Match this translation (e.g. 'es'). Requires Sentinel. Omit for default-language listing." },
+        limit:    { type: "number", default: 20 },
+        offset:   { type: "number", default: 0 },
       },
     },
   },

package/src/tools/nodes.js

@@ -15,10 +15,11 @@ import {
 } from "../lib/security.js";
 import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
 import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA, omitLiveComputedMetatag } from "../lib/entity-response.js";
-import { resolveErrRelationships, relationshipsWereSent } from "../lib/err-relationships.js";
+import { resolveErrRelationships, relationshipsWereSent, paragraphPinsFromEntity } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
+import { paragraphResourceVersion } from "./paragraphs.js";
 import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
@@ -239,7 +240,51 @@ function pageOf({ limit = 20, offset = 0 }) {
  * @param {object} args - { site?, type, id }.
  * @returns {Promise<object|null>} The redacted node, or null if not found.
  */
-async function getNode({ site: siteName, type, id, langcode, resourceVersion }) {
+/**
+ * Load pinned paragraph translations (or default-language pins) onto a host.
+ * Per-component failures are recorded; they do not fail the host read.
+ * @param {object} backend
+ * @param {object} sec
+ * @param {object} entity
+ * @param {?string} langcode
+ * @returns {Promise<object>}
+ */
+async function withComponents(backend, sec, entity, langcode) {
+  const pins = paragraphPinsFromEntity(entity);
+  const components = [];
+  for (const pin of pins) {
+    try {
+      let para;
+      if (langcode && pin.revisionId) {
+        para = await readDraftTranslation(backend, {
+          entityType: "paragraph",
+          bundle: pin.paragraphType,
+          id: pin.id,
+          langcode,
+          draftRevision: { revisionId: pin.revisionId },
+        });
+      } else if (pin.revisionId) {
+        para = await backend.getEntity({
+          entityType: "paragraph",
+          bundle: pin.paragraphType,
+          id: pin.id,
+          resourceVersion: paragraphResourceVersion(pin.revisionId),
+          ...(langcode ? { langcode } : {}),
+        });
+      }
+      components.push({
+        ...pin,
+        entity: para ? redactCanonicalEntity(para, sec, "paragraph") : null,
+        ...(para ? {} : { note: "missing revision pin" }),
+      });
+    } catch (error) {
+      components.push({ ...pin, entity: null, error: String(error.message || error) });
+    }
+  }
+  return { ...entity, components };
+}
+
+async function getNode({ site: siteName, type, id, langcode, resourceVersion, includeComponents = false }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
@@ -253,7 +298,8 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
         entityType: "node", bundle: type, id, langcode: targetLang,
         draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
       });
-      return omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
+      const redacted = omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
+      return includeComponents ? withComponents(backend, sec, redacted, targetLang) : redacted;
     }
     const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
     if (!liveHas) {
@@ -261,7 +307,7 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
     }
     if (targetLang !== inventory.defaultLangcode) {
       const liveRow = (inventory.live.translations ?? []).find((row) => row.langcode === targetLang);
-      return {
+      const stub = {
         id, entityType: "node", bundle: type, langcode: targetLang,
         title: liveRow?.title ?? null,
         status: liveRow?.status ?? null,
@@ -269,10 +315,13 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
         _revisions: { live: inventory.live.vid, working: inventory.working?.vid ?? null },
         note: "Published non-default translations are listed on the live revision; full field reads of an unpublished working translation use langcode against the working draft.",
       };
+      return includeComponents ? { ...stub, components: [] } : stub;
     }
   }
   const entity = await backend.getEntity({ entityType: "node", bundle: type, id, resourceVersion });
-  return entity ? redactCanonicalEntity(entity, sec, "node") : null;
+  if (!entity) return null;
+  const redacted = redactCanonicalEntity(entity, sec, "node");
+  return includeComponents ? withComponents(backend, sec, redacted, langcode || null) : redacted;
 }
 
 /**
@@ -520,7 +569,7 @@ async function deleteNode({ site: siteName, type, id, dryRun = false }) {
 export const definitions = [
   {
     name: "drupal_get_node",
-    description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English).",
+    description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English). Pass includeComponents true to attach pinned paragraph translations under `components` (default false).",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -528,6 +577,7 @@ export const definitions = [
         type: { type: "string", description: "Content type machine name, e.g. 'article'" },
         id:   { type: "string", description: "Node UUID" },
         langcode: { type: "string", description: "Target language (e.g. 'es') to read the unpublished working translation instead of the default language." },
+        includeComponents: { type: "boolean", default: false, description: "If true, include pinned paragraph translations under `components` (empty array when the host has no ERR fields). Default false so existing callers are unchanged." },
       },
     },
   },

package/src/tools/reports-content.js

@@ -17,6 +17,8 @@ import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
 import { collectEntities, fieldValue, daysSince } from "../lib/reports-support.js";
 import { bodyHtml, extractAnchors, classifyLink, normalizePath } from "../lib/audit-support.js";
+import { assertDraftLangcode, readTranslationInventory } from "../lib/draft-write.js";
+import { inventoryRowMatching, inventoryTranslationRows, mapTranslationRow } from "../lib/translation-rows.js";
 
 // ---------------------------------------------------------------------------
 // Shared text helpers
@@ -99,13 +101,14 @@ async function duplicateContent({ site: siteName, type, sampleSize = 200 }) {
  * @param {object} args - { site?, type?, days?, states?, sampleSize? }.
  * @returns {Promise<object>} Stuck-content findings.
  */
-async function workflowBottlenecks({ site: siteName, type, days = 30, states, sampleSize = 200 }) {
+async function workflowBottlenecks({ site: siteName, type, days = 30, states, sampleSize = 200, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
   const contentType = type || "article";
   const targetStates = (states && states.length ? states : ["draft", "needs_review", "review"]).map((s) => s.toLowerCase());
+  const targetLang = langcode ? assertDraftLangcode(langcode) : null;
 
   const nodes = await collectEntities(
     backend,
@@ -113,17 +116,56 @@ async function workflowBottlenecks({ site: siteName, type, days = 30, states, sa
     sampleSize
   );
 
+  if (targetLang && (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function")) {
+    return {
+      contentType,
+      unavailable: true,
+      reason: "A langcode filter requires Sentinel's translation inventory.",
+    };
+  }
+
   let sawState = false;
   const findings = [];
+  let inventoried = 0;
   for (const n of nodes) {
-    const state = scalar(n, ["moderation_state"]);
+    let state = scalar(n, ["moderation_state"]);
+    if (targetLang) {
+      try {
+        const inventory = await readTranslationInventory(backend, {
+          entityType: "node", bundle: contentType, id: n.id,
+        });
+        inventoried += 1;
+        const row = inventoryRowMatching(inventory, { langcode: targetLang });
+        if (!row) continue;
+        state = row.moderation_state;
+      } catch (error) {
+        if (/does not provide Sentinel's governed draft-translation endpoint/.test(String(error?.message))) {
+          return {
+            contentType,
+            unavailable: true,
+            reason: "A langcode filter requires Sentinel's translation inventory.",
+          };
+        }
+        throw error;
+      }
+    }
     if (state === undefined || state === null) continue;
     sawState = true;
     const age = daysSince(n.changed);
     if (targetStates.includes(String(state).toLowerCase()) && age !== null && age > days) {
-      findings.push({ id: n.id, title: n.title, state, daysInState: age, path: n.url });
+      findings.push({
+        id: n.id, title: n.title, state, daysInState: age, path: n.url,
+        ...(targetLang ? { langcode: targetLang } : {}),
+      });
     }
   }
+  if (targetLang && inventoried === 0 && nodes.length > 0) {
+    return {
+      contentType,
+      unavailable: true,
+      reason: "A langcode filter requires Sentinel's translation inventory.",
+    };
+  }
 
   if (!sawState) {
     return { contentType, gated: true, reason: "No moderation_state field exposed (content_moderation not enabled or not in the API).", scanned: nodes.length };
@@ -144,16 +186,16 @@ async function workflowBottlenecks({ site: siteName, type, days = 30, states, sa
 // ---------------------------------------------------------------------------
 
 /**
- * Report content distribution by language for a content type and flag languages
- * that lag the most-populated language — a coverage signal for multilingual
- * sites. (Exact per-node missing-translation detection requires translation
- * metadata the canonical model doesn't carry; this aggregate is the best-effort
- * stand-in.)
+ * Per-node translation coverage from Sentinel inventory.
  *
- * @param {object} args - { site?, type?, gapThreshold?, sampleSize? }.
- * @returns {Promise<object>} Per-language counts and lagging languages.
+ * JSON:API serves one language per resource, so a histogram of `n.langcode`
+ * looks like 100% default language even when translations exist. Without
+ * Sentinel the report is `unavailable` rather than that misleading chart.
+ *
+ * @param {object} args - { site?, type?, sampleSize? }.
+ * @returns {Promise<object>} Coverage, or unavailable.
  */
-async function translationCoverage({ site: siteName, type, gapThreshold = 0.5, sampleSize = 500 }) {
+async function translationCoverage({ site: siteName, type, sampleSize = 100 }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
@@ -165,24 +207,71 @@ async function translationCoverage({ site: siteName, type, gapThreshold = 0.5, s
     sampleSize
   );
 
-  const byLang = new Map();
+  const missingEndpoint = /does not provide Sentinel's governed draft-translation endpoint/;
+  if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
+    return {
+      contentType,
+      scanned: nodes.length,
+      unavailable: true,
+      reason:
+        "Translation coverage requires Sentinel's GET .../mcp-translations inventory. " +
+        "JSON:API only shows the default language; a language histogram would be misleading.",
+    };
+  }
+
+  const findings = [];
+  let inventoried = 0;
   for (const n of nodes) {
-    const lang = n.langcode || "und";
-    byLang.set(lang, (byLang.get(lang) || 0) + 1);
+    try {
+      const inventory = await readTranslationInventory(backend, {
+        entityType: "node", bundle: contentType, id: n.id,
+      });
+      inventoried += 1;
+      const rows = inventoryTranslationRows(inventory);
+      const defaultLangcode = inventory.defaultLangcode ?? n.langcode ?? null;
+      const nonDefault = rows.filter((row) => row.langcode !== defaultLangcode);
+      findings.push({
+        id: n.id,
+        title: n.title,
+        defaultLangcode,
+        languages: rows.map(mapTranslationRow),
+        missingNonDefault: nonDefault.length === 0,
+        outdated: rows.some((row) => row.outdated === true),
+      });
+    } catch (error) {
+      if (!missingEndpoint.test(String(error?.message))) throw error;
+    }
+  }
+
+  if (inventoried === 0) {
+    return {
+      contentType,
+      scanned: nodes.length,
+      unavailable: true,
+      reason:
+        "Translation coverage requires Sentinel's GET .../mcp-translations inventory. " +
+        "JSON:API only shows the default language; a language histogram would be misleading.",
+    };
+  }
+
+  const languageCounts = new Map();
+  for (const finding of findings) {
+    for (const row of finding.languages) {
+      languageCounts.set(row.langcode, (languageCounts.get(row.langcode) || 0) + 1);
+    }
   }
-  const counts = [...byLang.entries()].map(([langcode, count]) => ({ langcode, count })).sort((a, b) => b.count - a.count);
-  const top = counts[0]?.count ?? 0;
-  const lagging = counts
-    .filter((c) => top > 0 && c.count / top < gapThreshold)
-    .map((c) => ({ langcode: c.langcode, count: c.count, coverage: Number((c.count / top).toFixed(2)) }));
 
   return {
     contentType,
     scanned: nodes.length,
-    approximate: nodes.length >= sampleSize,
-    languages: counts,
-    laggingLanguages: lagging,
-    note: "Coverage is a distribution-by-language signal; exact per-node missing translations require translation metadata not in the canonical model.",
+    inventoried,
+    approximate: nodes.length >= sampleSize || inventoried < nodes.length,
+    languages: [...languageCounts.entries()]
+      .map(([langcode, count]) => ({ langcode, count }))
+      .sort((a, b) => b.count - a.count),
+    missing: findings.filter((f) => f.missingNonDefault).map((f) => ({ id: f.id, title: f.title })),
+    outdated: findings.filter((f) => f.outdated).map((f) => ({ id: f.id, title: f.title })),
+    findings,
   };
 }
 
@@ -555,20 +644,20 @@ export const definitions = [
         type:       { type: "string", description: "Content type (default: article)" },
         days:       { type: "number", default: 30, description: "Days-in-state threshold" },
         states:     { type: "array", items: { type: "string" }, description: "Moderation states to treat as bottlenecks" },
+        langcode:   { type: "string", description: "Limit to this translation (Sentinel inventory). Omit for the default-language field on each node." },
         sampleSize: { type: "number", default: 200 },
       },
     },
   },
   {
     name: "drupal_report_translation_coverage",
-    description: "Report content distribution by language for a content type and flag languages lagging the most-populated language — a multilingual coverage signal.",
+    description: "Per-node translation coverage from Sentinel's inventory (missing non-default language, outdated core flag, language counts). Without Sentinel the report is unavailable — JSON:API only shows the default language, so a histogram would be misleading.",
     inputSchema: {
       type: "object",
       properties: {
-        site:         { type: "string" },
-        type:         { type: "string", description: "Content type (default: article)" },
-        gapThreshold: { type: "number", default: 0.5, description: "Flag languages below this fraction of the top language" },
-        sampleSize:   { type: "number", default: 500 },
+        site:       { type: "string" },
+        type:       { type: "string", description: "Content type (default: article)" },
+        sampleSize: { type: "number", default: 100, description: "Max nodes to inventory" },
       },
     },
   },

package/src/tools/structure.js

@@ -19,6 +19,7 @@ import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
+import { assertDraftLangcode } from "../lib/draft-write.js";
 
 const MENU_LINK_TYPE = "menu_link_content";
 const BLOCK_TYPE = "block_content";
@@ -150,12 +151,13 @@ async function createMenuLink({ site: siteName, title, link, menu, weight, paren
  * @throws {Error} If id is missing.
  * @throws {SecurityError} If updating menu_link_content is not permitted.
  */
-async function updateMenuLink({ site: siteName, id, title, link, menu, weight, parent, enabled }) {
+async function updateMenuLink({ site: siteName, id, title, link, menu, weight, parent, enabled, langcode }) {
   if (!id) throw new Error("A menu link 'id' (UUID) is required to update an existing menu link.");
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", MENU_LINK_TYPE, MENU_LINK_TYPE);
   const backend = await resolveBackend(site);
+  const language = langcode ? { langcode: assertDraftLangcode(langcode) } : {};
   const attributes = {};
   if (title !== undefined) attributes.title = title;
   if (link !== undefined) attributes.link = { uri: link };
@@ -165,12 +167,12 @@ async function updateMenuLink({ site: siteName, id, title, link, menu, weight, p
   if (enabled !== undefined) {
     attributes.enabled = enabled;
   } else {
-    const current = await backend.getEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, id });
+    const current = await backend.getEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, id, ...language });
     const currentEnabled = current?.fields?.enabled;
     attributes.enabled = currentEnabled === undefined ? true : currentEnabled;
   }
   return writeMenuLinkWithRetry(() =>
-    backend.updateEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, id, attributes }));
+    backend.updateEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, id, attributes, ...language }));
 }
 
 // ---------------------------------------------------------------------------
@@ -273,6 +275,7 @@ export const definitions = [
         weight:  { type: "number", description: "New ordering weight. Omit to leave unchanged." },
         parent:  { type: "string", description: "New parent link plugin id (e.g. 'menu_link_content:<uuid>'), or '' for top level. Omit to leave unchanged." },
         enabled: { type: "boolean", description: "Enable/disable the link. Omit to preserve the current state." },
+        langcode: { type: "string", description: "Existing translation to update (e.g. 'es'). Omit for the default language. Does not create a missing translation." },
       },
     },
   },