drupal-mcp-connector 2.15.2 → 2.16.0

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." },
       },
     },
   },

package/src/tools/taxonomy.js

@@ -12,6 +12,7 @@ import {
   resolveSecurityConfig, redactCanonicalEntity,
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed,
 } from "../lib/security.js";
+import { assertDraftLangcode } from "../lib/draft-write.js";
 
 // ---------------------------------------------------------------------------
 // Implementations
@@ -58,12 +59,15 @@ async function getTaxonomyTerms({ site: siteName, vocabulary, limit = 50, offset
  * @param {object} args - { site?, vocabulary, id }.
  * @returns {Promise<object|null>} The redacted term, or null if not found.
  */
-async function getTaxonomyTerm({ site: siteName, vocabulary, id }) {
+async function getTaxonomyTerm({ site: siteName, vocabulary, id, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "taxonomy_term", vocabulary);
   const backend = await resolveBackend(site);
-  const entity = await backend.getEntity({ entityType: "taxonomy_term", bundle: vocabulary, id });
+  const entity = await backend.getEntity({
+    entityType: "taxonomy_term", bundle: vocabulary, id,
+    ...(langcode ? { langcode: assertDraftLangcode(langcode) } : {}),
+  });
   return entity ? redactCanonicalEntity(entity, sec, "taxonomy_term") : null;
 }
 
@@ -93,7 +97,7 @@ async function createTaxonomyTerm({ site: siteName, vocabulary, name, descriptio
  * @param {object} args - { site?, vocabulary, id, name?, description?, weight? }.
  * @returns {Promise<object>} The updated term descriptor.
  */
-async function updateTaxonomyTerm({ site: siteName, vocabulary, id, name, description, weight }) {
+async function updateTaxonomyTerm({ site: siteName, vocabulary, id, name, description, weight, langcode }) {
   const site = getSiteConfig(siteName);
   assertWriteAllowed(resolveSecurityConfig(site), "update", "taxonomy_term", vocabulary);
   const backend = await resolveBackend(site);
@@ -101,7 +105,10 @@ async function updateTaxonomyTerm({ site: siteName, vocabulary, id, name, descri
   if (name !== undefined) attributes.name = name;
   if (weight !== undefined) attributes.weight = weight;
   if (description !== undefined) attributes.description = { value: description, format: "plain_text" };
-  return backend.updateEntity({ entityType: "taxonomy_term", bundle: vocabulary, id, attributes });
+  return backend.updateEntity({
+    entityType: "taxonomy_term", bundle: vocabulary, id, attributes,
+    ...(langcode ? { langcode: assertDraftLangcode(langcode) } : {}),
+  });
 }
 
 /**
@@ -147,13 +154,14 @@ export const definitions = [
   },
   {
     name: "drupal_get_taxonomy_term",
-    description: "Fetch a single taxonomy term by UUID.",
+    description: "Fetch a single taxonomy term by UUID. Pass langcode to request that translation; omit for the default language. JSON:API must negotiate language or the tool errors if a different language is served.",
     inputSchema: {
       type: "object", required: ["vocabulary", "id"],
       properties: {
         site:       { type: "string" },
         vocabulary: { type: "string" },
         id:         { type: "string", description: "Term UUID" },
+        langcode:   { type: "string", description: "Translation language (e.g. 'es'). Omit for the default language." },
       },
     },
   },
@@ -174,7 +182,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_taxonomy_term",
-    description: "Update an existing taxonomy term's name, description, or weight.",
+    description: "Update an existing taxonomy term's name, description, or weight. Pass langcode to update an existing translation; this does not create a missing translation.",
     inputSchema: {
       type: "object", required: ["vocabulary", "id"],
       properties: {
@@ -184,6 +192,7 @@ export const definitions = [
         name:        { type: "string" },
         description: { type: "string" },
         weight:      { type: "number" },
+        langcode:    { type: "string", description: "Existing translation to update (e.g. 'es'). Omit for the default language." },
       },
     },
   },

package/src/tools/translations.js

@@ -34,6 +34,7 @@ import {
   readTranslationInventory,
   resolveNodeTranslationPair,
 } from "../lib/draft-write.js";
+import { mapTranslationRow } from "../lib/translation-rows.js";
 
 const LIST_NOTE =
   "Live languages are those on the default revision. Working languages are the " +
@@ -75,13 +76,7 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
         langcodes,
         live: meta.live ?? null,
         working: meta.working ?? null,
-        translations: (meta.working?.translations ?? meta.live?.translations ?? []).map((row) => ({
-          langcode: row.langcode,
-          default: Boolean(row.default),
-          status: row.status,
-          title: row.title,
-          moderation_state: row.moderation_state,
-        })),
+        translations: (meta.working?.translations ?? meta.live?.translations ?? []).map(mapTranslationRow),
         note: LIST_NOTE,
       };
     } catch (error) {
@@ -200,7 +195,8 @@ export const definitions = [
     description:
       "List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's " +
       "translation inventory when available (live default revision vs unpublished working " +
-      "draft). Core JSON:API alone serves one language and cannot prove others are absent. " +
+      "draft), including core content_translation_outdated and source when the server sends them. " +
+      "Core JSON:API alone serves one language and cannot prove others are absent. " +
       "Defaults to node.",
     inputSchema: {
       type: "object", required: ["type", "id"],