drupal-mcp-connector 2.15.2 → 2.16.0

package/src/lib/server-tools.js

@@ -23,7 +23,7 @@
  */
 
 import fetch from "node-fetch";
-import { authHeadersAsync, clientHeaders, CLIENT_VERSION } from "./config.js";
+import { authHeadersAsync, clientHeaders, CLIENT_NAME, CLIENT_VERSION } from "./config.js";
 import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial } from "./data-flow.js";
 import { clearToken } from "./oauth.js";
 
@@ -164,7 +164,7 @@ async function initializeSession(site, endpoint) {
     params: {
       protocolVersion: MCP_PROTOCOL_VERSION,
       capabilities: {},
-      clientInfo: { name: "drupal-mcp-connector", version: CLIENT_VERSION },
+      clientInfo: { name: CLIENT_NAME, version: CLIENT_VERSION },
     },
   };
 

package/src/lib/translation-rows.js

@@ -0,0 +1,59 @@
+/**
+ * Normalize Sentinel translation-inventory rows for tools and reports.
+ *
+ * Extra keys (`outdated`, `source`) are passed through only when present so
+ * older Sentinel versions do not grow invented `outdated: false`.
+ */
+
+/**
+ * @param {object} row Inventory translation row.
+ * @returns {object}
+ */
+export function mapTranslationRow(row) {
+  if (!row || typeof row !== "object") return row;
+  const out = {
+    langcode: row.langcode,
+    default: Boolean(row.default),
+    status: row.status,
+    title: row.title,
+    moderation_state: row.moderation_state ?? null,
+  };
+  if (Object.prototype.hasOwnProperty.call(row, "outdated")) {
+    out.outdated = Boolean(row.outdated);
+  }
+  if (typeof row.source === "string" && row.source) {
+    out.source = row.source;
+  }
+  return out;
+}
+
+/**
+ * Editorial current row per langcode: working copy wins over live.
+ * @param {?object} inventory
+ * @returns {object[]}
+ */
+export function inventoryTranslationRows(inventory) {
+  const byLang = new Map();
+  for (const row of inventory?.live?.translations ?? []) {
+    if (row?.langcode) byLang.set(row.langcode, { ...mapTranslationRow(row), revision: "live" });
+  }
+  for (const row of inventory?.working?.translations ?? []) {
+    if (row?.langcode) byLang.set(row.langcode, { ...mapTranslationRow(row), revision: "working" });
+  }
+  return [...byLang.values()];
+}
+
+/**
+ * Whether inventory has a row matching langcode and/or moderation state.
+ * @param {?object} inventory
+ * @param {{langcode?: string, state?: string}} match
+ * @returns {?object}
+ */
+export function inventoryRowMatching(inventory, { langcode, state } = {}) {
+  const wantedState = state === undefined || state === null ? null : String(state).toLowerCase();
+  return inventoryTranslationRows(inventory).find((row) => {
+    if (langcode && row.langcode !== langcode) return false;
+    if (wantedState && String(row.moderation_state || "").toLowerCase() !== wantedState) return false;
+    return true;
+  }) ?? null;
+}

package/src/tools/codegen.js

@@ -0,0 +1,150 @@
+/**
+ * Tool group: GraphQL Compose Codegen (TypeScript / Next.js scaffolds).
+ *
+ * Thin Drush wrappers around `drupal/graphql_compose_codegen`. The generator
+ * lives on the Drupal site; this connector does not reimplement it and does
+ * not run GraphQL Code Generator against the SDL.
+ *
+ * All three tools are reads. `drupal_codegen_generate` always passes
+ * `--dry-run` and never `--output-dir`, so artefacts come back as text for
+ * the agent to write locally. Disk writes stay a local DDEV/script concern.
+ *
+ * Capability: missing module or unknown Drush command fails loud. If
+ * `drushSsh.allowedCommands` is set, the `graphql-compose-codegen:*`
+ * subcommand must be on that list (same exact-match rule as other Drush tools).
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { sshDrush } from "./drush.js";
+import { SecurityError } from "../lib/security.js";
+import { validateMachineName } from "../lib/validate.js";
+
+const INSPECT = "graphql-compose-codegen:inspect";
+const DIFF = "graphql-compose-codegen:diff";
+const GENERATE = "graphql-compose-codegen:generate";
+
+const GENERATE_TIMEOUT_MS = 60000;
+
+/**
+ * Parse an optional list of Drupal machine names (array or comma string).
+ *
+ * @param {string[]|string|undefined} raw Caller value.
+ * @param {string} fieldName Error label.
+ * @returns {string[]} Validated names, possibly empty.
+ */
+function parseMachineNameList(raw, fieldName) {
+  if (raw === undefined || raw === null || raw === "") return [];
+  const parts = Array.isArray(raw)
+    ? raw
+    : String(raw).split(",");
+  return parts
+    .map((v) => String(v).trim())
+    .filter(Boolean)
+    .map((v) => validateMachineName(v, fieldName));
+}
+
+/**
+ * Whether a Drush failure looks like the codegen module is absent.
+ *
+ * @param {Error} err Bridge error.
+ * @returns {boolean}
+ */
+function looksLikeMissingCodegen(err) {
+  const msg = String(err?.message || err || "");
+  return /graphql-compose-codegen|gqcc:|no commands defined in the ["']graphql-compose-codegen|command .* does not exist|could not find command/i.test(msg);
+}
+
+/**
+ * Run a codegen Drush subcommand and return stdout.
+ *
+ * @param {object} args Tool args.
+ * @param {string} [args.site] Site name.
+ * @param {string[]|string} [args.bundles] Bundle ids.
+ * @param {string[]|string} [args.skipFields] Extra field names to exclude.
+ * @param {string} subcommand Drush subcommand (first arg).
+ * @param {string[]} extra Extra flags (e.g. --dry-run).
+ * @param {number} timeoutMs SSH timeout.
+ * @returns {Promise<{output: string, command: string, wroteFiles: false}>}
+ */
+async function runGqcc(
+  { site: siteName, bundles, skipFields },
+  subcommand,
+  extra = [],
+  timeoutMs = 30000,
+) {
+  const site = getSiteConfig(siteName);
+  const names = parseMachineNameList(bundles, "bundles");
+  const skip = parseMachineNameList(skipFields, "skipFields");
+  const args = [subcommand];
+  if (names.length) args.push(`--bundles=${names.join(",")}`);
+  if (skip.length) args.push(`--skip-fields=${skip.join(",")}`);
+  args.push(...extra);
+  try {
+    const output = await sshDrush(site, args, timeoutMs);
+    return { output, command: args.join(" "), wroteFiles: false };
+  } catch (err) {
+    if (err instanceof SecurityError) throw err;
+    if (looksLikeMissingCodegen(err)) {
+      throw new Error(
+        "graphql_compose_codegen is not available on this site " +
+        `(Drush command "${subcommand}" failed). Install and enable ` +
+        "drupal/graphql_compose_codegen, and if drushSsh.allowedCommands is " +
+        `set, add "${subcommand}" to that list. ${err.message}`,
+      );
+    }
+    throw err;
+  }
+}
+
+async function inspect(args) {
+  return runGqcc(args, INSPECT);
+}
+
+async function diff(args) {
+  return runGqcc(args, DIFF);
+}
+
+async function generate(args) {
+  return runGqcc(args, GENERATE, ["--dry-run"], GENERATE_TIMEOUT_MS);
+}
+
+const LIST_PROPS = {
+  site: { type: "string" },
+  bundles: {
+    type: "array",
+    items: { type: "string", pattern: "^[a-z][a-z0-9_]*$" },
+    description: "Node/paragraph bundle ids. Omit for every bundle graphql_compose exposes.",
+  },
+  skipFields: {
+    type: "array",
+    items: { type: "string", pattern: "^[a-z][a-z0-9_]*$" },
+    description: "Extra field machine names to exclude from the scaffold.",
+  },
+};
+
+export const definitions = [
+  {
+    name: "drupal_codegen_inspect",
+    description:
+      "List node and paragraph bundles and extra fields from graphql_compose_codegen (`drush graphql-compose-codegen:inspect`). Requires the module and drushSsh. Missing command fails loud. If allowedCommands is set, include graphql-compose-codegen:inspect. Does not write files.",
+    inputSchema: { type: "object", properties: LIST_PROPS },
+  },
+  {
+    name: "drupal_codegen_diff",
+    description:
+      "Compare the live graphql_compose schema to the last gqcc:generate snapshot (`drush graphql-compose-codegen:diff`). Requires the module and drushSsh. Missing command fails loud. If allowedCommands is set, include graphql-compose-codegen:diff.",
+    inputSchema: { type: "object", properties: LIST_PROPS },
+  },
+  {
+    name: "drupal_codegen_generate",
+    description:
+      "Return TypeScript/GraphQL scaffold artefacts from graphql_compose_codegen as text (`drush graphql-compose-codegen:generate --dry-run`). Never writes on the Drupal host (no --output-dir). Copy artefacts locally. Requires the module and drushSsh. Missing command fails loud. If allowedCommands is set, include graphql-compose-codegen:generate.",
+    inputSchema: { type: "object", properties: LIST_PROPS },
+  },
+];
+
+export const handlers = {
+  drupal_codegen_inspect: inspect,
+  drupal_codegen_diff: diff,
+  drupal_codegen_generate: generate,
+};

package/src/tools/fields.js

@@ -96,11 +96,18 @@ async function describeFields({ site: siteName, type, entityType: entityTypeArg,
 
   const backend = await resolveBackend(site);
   const schema = await backend.getEntitySchema(entityType, resolvedBundle);
+  const translatable = typeof backend.listFieldTranslatability === "function"
+    ? await backend.listFieldTranslatability(entityType, resolvedBundle).catch(() => ({}))
+    : {};
+  const translatableMap = translatable && typeof translatable === "object" ? new Map(Object.entries(translatable)) : new Map();
 
   const fields = [
     ...Object.entries(schema.attributes ?? {}).map(([name, t]) => attributeField(name, t)),
     ...Object.keys(schema.relationships ?? {}).map((name) => relationshipField(name)),
-  ].sort((a, b) => a.name.localeCompare(b.name));
+  ].sort((a, b) => a.name.localeCompare(b.name)).map((field) => {
+    if (!translatableMap.has(field.name)) return field;
+    return { ...field, translatable: Boolean(translatableMap.get(field.name)) };
+  });
 
   const sampledEmpty = fields.length === 0;
 
@@ -125,11 +132,12 @@ export const definitions = [
     name: "drupal_describe_fields",
     description:
       "Introspect the fields of a Drupal entity type + bundle: returns a per-field " +
-      "list of { name, type, kind, cardinality?, approximate }. Read-only. Built on " +
+      "list of { name, type, kind, cardinality?, translatable?, approximate }. Read-only. Built on " +
       "schema SAMPLING (an existing entity), so results are approximate — only " +
       "populated fields are visible and required/cardinality/allowedValues are " +
-      "inferred from value shape. Authoritative field metadata comes from the Drush " +
-      "bridge (Field API). Use this before creating/updating entities to learn field names.",
+      "inferred from value shape. When JSON:API field_config is readable, translatable " +
+      "is copied from Field API; omitted means unknown, not false. Authoritative field " +
+      "metadata comes from the Drush bridge (Field API). Use this before creating/updating entities to learn field names.",
     inputSchema: {
       type: "object",
       required: ["site"],

package/src/tools/index.js

@@ -38,11 +38,12 @@ import * as reportsConfig  from "./reports-config.js";
 import * as reportsContent from "./reports-content.js";
 import * as auditComposite from "./audit-composite.js";
 import * as config       from "./config.js";
+import * as codegen      from "./codegen.js";
 import { SITE_PARAM } from "../lib/site-target.js";
 
 export const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
   revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra,
-  reportsLinks, reportsConfig, reportsContent, auditComposite, config];
+  reportsLinks, reportsConfig, reportsContent, auditComposite, config, codegen];
 
 /**
  * Stamp the shared `site` description onto every tool that accepts one so

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