drupal-mcp-connector 2.15.1 → 2.16.0

package/src/lib/config.js

@@ -16,9 +16,26 @@ import { getAccessToken }                from "./oauth.js";
 // eslint-disable-next-line security/detect-non-literal-fs-filename -- fixed path relative to this module (the package's own package.json), not user input
 const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 
+/** npm / protocol machine name. Public identifier — not the display name. */
+export const CLIENT_NAME = "drupal-mcp-connector";
+
+/** Human-readable product name for docs and MCP `serverInfo.title`. */
+export const CLIENT_TITLE = "Drupal MCP Connector";
+
 /** Connector version, sourced from package.json so it never drifts out of sync. */
 export const CLIENT_VERSION = pkg.version;
 
+/**
+ * MCP Implementation advertised in the handshake.
+ * `name` is the protocol identifier; `title` is the display name.
+ * @type {{name: string, title: string, version: string}}
+ */
+export const SERVER_INFO = {
+  name: CLIENT_NAME,
+  title: CLIENT_TITLE,
+  version: CLIENT_VERSION,
+};
+
 /**
  * Identity headers sent on every outbound Drupal request. Lets governance layers
  * label/identify connector traffic. ON by default; set MCP_CLIENT_ID to override
@@ -26,7 +43,7 @@ export const CLIENT_VERSION = pkg.version;
  * @returns {Object<string,string>} Header map (empty when the identity is disabled).
  */
 export function clientHeaders() {
-  const id = process.env.MCP_CLIENT_ID ?? `drupal-mcp-connector/${CLIENT_VERSION}`;
+  const id = process.env.MCP_CLIENT_ID ?? `${CLIENT_NAME}/${CLIENT_VERSION}`;
   if (!id) return {};
   return { "X-MCP-Client": id, "User-Agent": id };
 }

package/src/lib/err-relationships.js

@@ -38,6 +38,28 @@ export function isParagraphResourceType(type) {
   return typeof type === "string" && type.startsWith("paragraph--");
 }
 
+/**
+ * Paragraph ERR pins on a canonical host entity.
+ * @param {object} entity Canonical node (or other host).
+ * @returns {Array<{field: string, id: string, paragraphType: string, revisionId: ?string}>}
+ */
+export function paragraphPinsFromEntity(entity) {
+  const pins = [];
+  const rels = entity?.relationships && typeof entity.relationships === "object" ? entity.relationships : {};
+  for (const [field, value] of Object.entries(rels)) {
+    const list = Array.isArray(value) ? value : value ? [value] : [];
+    for (const ref of list) {
+      if (!ref?.id) continue;
+      const paragraphType = ref.bundle || parseResourceType(ref.type)?.bundle;
+      if (ref.entityType !== "paragraph" && !isParagraphResourceType(ref.type)) continue;
+      if (!paragraphType) continue;
+      const revisionId = ref.meta?.target_revision_id ?? null;
+      pins.push({ field, id: ref.id, paragraphType, revisionId });
+    }
+  }
+  return pins;
+}
+
 /**
  * Split a JSON:API resource type into entity type + bundle.
  * @param {string} type e.g. "paragraph--capability".

package/src/lib/mcp-server.js

@@ -29,7 +29,7 @@ function resourceUriIsListed(listed, requested) {
  * Create the server factory shared by HTTP and stdio transports.
  *
  * @param {object} surface
- * @param {{name: string, version: string}} surface.serverInfo
+ * @param {{name: string, title?: string, version: string}} surface.serverInfo
  * @param {{definitions: Array<object>, list?: () => Promise<Array<object>>, call: (name: string, args: object, context: object) => Promise<object>}} surface.tools
  *   `definitions` is the full static surface (schema projection); the optional
  *   `list` hook decides what is DISCOVERABLE per request (governance + entitlement).

package/src/lib/node-draft-inventory.js

@@ -0,0 +1,47 @@
+/** Sentinel discovery for translation-only node revisions (#297). */
+import { readTranslationInventory } from "./draft-write.js";
+
+/**
+ * Read optional inventory, falling back only when the endpoint is unsupported.
+ * Permission, transport and malformed-response failures are not absence.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string}} ref
+ * @returns {Promise<object|null>}
+ */
+export async function readNodeDraftInventory(backend, ref) {
+  if (ref.entityType !== "node" || typeof backend.rawQuery !== "function"
+    || typeof backend.resourcePath !== "function") return null;
+  let inventory;
+  try {
+    inventory = await readTranslationInventory(backend, ref);
+  } catch (error) {
+    if (/does not provide Sentinel's governed draft-translation endpoint/.test(error.message)) return null;
+    throw error;
+  }
+  const validVid = (vid) => /^[1-9]\d*$/.test(String(vid ?? "")) && Number.isSafeInteger(Number(vid));
+  if (!validVid(inventory.live?.vid)
+    || (inventory.working && (!validVid(inventory.working.vid)
+      || !Array.isArray(inventory.working.translations)
+      || inventory.working.translations.some((row) => !row || typeof row.langcode !== "string"
+        || typeof row.status !== "boolean")))) {
+    throw new Error("Sentinel returned an invalid node revision inventory. Re-read before updating.");
+  }
+  return inventory;
+}
+
+/**
+ * Ensure inventory discovery does not turn a published language into a draft.
+ * Sentinel still validates the revision pair and language on every request.
+ * @param {object} inventory
+ * @param {string|undefined} langcode
+ */
+export function assertInventoryDraftLanguage(inventory, langcode) {
+  const rows = inventory.working?.translations ?? [];
+  if (!langcode && rows.length !== 1) {
+    throw new Error("This working revision contains translations. Pass an explicit langcode for an existing unpublished language; no draft was created.");
+  }
+  const row = langcode ? rows.find((item) => item.langcode === langcode) : rows[0];
+  if (!row || row.status !== false) {
+    throw new Error("The requested language is not an existing unpublished working draft. Published languages and other drafts were left unchanged.");
+  }
+}

package/src/lib/patch-preflight.js

@@ -16,8 +16,8 @@
  *   Sentinel's /mcp-draft endpoint with verified live/working revision IDs.
  *   Core rejects resourceVersion on PATCH. Never retry the canonical URL.
  * - **#201** — the working-copy alias does not resolve, but core still
- *   blocks. That is a stray revision row. Refuse with revision-surgery
- *   language. `workingCopy: null` is not proof the node is writable.
+ *   blocks. Consult Sentinel inventory for translation-only revisions before
+ *   refusing the unresolved revision conflict. `workingCopy: null` is not proof the node is writable.
  *
  * Unsupported endpoints and stale revisions fail closed, without discard.
  */
@@ -25,6 +25,7 @@
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
 import { entityRevisionId } from "./write-revision.js";
 import { writeDraft } from "./draft-write.js";
+import { readNodeDraftInventory, assertInventoryDraftLanguage } from "./node-draft-inventory.js";
 
 /** Stable error code for a core working-copy / not-latest-revision block. */
 export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
@@ -48,7 +49,7 @@ export const PATCH_BLOCKED_MESSAGE =
   "This entity cannot be updated over JSON:API because the stored entity is not " +
   "the latest revision (Drupal core #2795279). The JSON:API aliases " +
   "rel:latest-version and rel:working-copy cannot show the blocking row. " +
-  "Clearing it requires revision surgery outside JSON:API (Drush / the entity API). " +
+  "Inspect the translation inventory and revision history before considering repair; do not delete drafts. " +
   "See connector #201. Do not retry the same canonical PATCH.";
 
 /**
@@ -248,17 +249,32 @@ export async function loadWorkingCopy(backend, { entityType, bundle, id }) {
  */
 export async function resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing }) {
   const workingCopy = await loadWorkingCopy(backend, { entityType, bundle, id });
+  if (workingCopy?.id && workingCopy.id !== id) {
+    throw new PatchTargetAmbiguousError(id, workingCopy.id);
+  }
   let liveVid = entityRevisionId(existing);
   if (workingCopy && (liveVid === null || liveVid === undefined) && typeof backend?.getEntity === "function") {
     const live = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
     liveVid = entityRevisionId(live);
   }
+  const aliasVid = entityRevisionId(workingCopy);
+  if (!workingCopy || (liveVid !== null && String(aliasVid) === String(liveVid))) {
+    const inventory = await readNodeDraftInventory(backend, { entityType, bundle, id });
+    if (inventory) {
+      if (liveVid !== null && String(liveVid) !== String(inventory.live.vid)) {
+        throw new WorkingCopyStaleError(new Error("Sentinel's live revision changed during discovery."));
+      }
+      liveVid = Number(inventory.live.vid);
+      const workingVid = inventory.working ? Number(inventory.working.vid) : null;
+      if (workingVid !== null && workingVid !== liveVid) {
+        return { resourceVersion: `id:${workingVid}`, workingCopy: null,
+          liveVid, workingVid, inventory };
+      }
+    }
+  }
   if (!workingCopy) {
     return { resourceVersion: undefined, workingCopy: null, liveVid, workingVid: null };
   }
-  if (workingCopy.id && workingCopy.id !== id) {
-    throw new PatchTargetAmbiguousError(id, workingCopy.id);
-  }
   const workingVid = entityRevisionId(workingCopy);
   if (workingVid !== null && liveVid !== null && String(workingVid) === String(liveVid)) {
     return { resourceVersion: undefined, workingCopy, liveVid, workingVid };
@@ -402,6 +418,7 @@ export async function prepareGuardedPatch(backend, {
       throw new StaleCopyError();
     }
   }
+  if (target.inventory) assertInventoryDraftLanguage(target.inventory, langcode);
   if (langcode) {
     if (!target.workingVid || !target.liveVid || String(target.workingVid) === String(target.liveVid)) {
       throw new Error(

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/lib/write-revision.js

@@ -65,7 +65,10 @@ export async function attachWrittenRevisionPair({
   backend, entityType, bundle, id, entity, liveVid,
 }) {
   if (liveVid === null || liveVid === undefined || !entity) return entity;
-  let workingVid = null;
+  let workingVid = entityRevisionId(entity);
+  if (workingVid !== null && String(workingVid) !== String(liveVid)) {
+    return attachRevisionPair(entity, { live: liveVid, working: workingVid });
+  }
   if (typeof backend?.getEntity === "function") {
     try {
       const wc = await backend.getEntity({
@@ -93,12 +96,16 @@ export async function attachWrittenRevisionPair({
  *   for the write (e.g. `rel:working-copy`). PreferCanonical re-reads this
  *   resource instead of the default revision so a draft PATCH is not
  *   replaced by the live body.
+ * @param {?string} [args.langcode] Language returned by governed draft continuation.
  * @returns {Promise<object>} Entity to return, with `_revision` when relevant.
  */
 export async function readWrittenRevision({
   backend, entityType, bundle, id, relationshipsSent, patchResult = null, preferCanonical = false,
-  resourceVersion,
+  resourceVersion, langcode,
 }) {
+  // Sentinel returned the requested translation; a canonical read would replace
+  // it with live English, and the core working-copy alias may not address it.
+  if (langcode && patchResult) return patchResult;
   if (!relationshipsSent) {
     if (preferCanonical && typeof backend.getEntity === "function") {
       const fresh = await backend.getEntity({

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/entities.js

@@ -136,6 +136,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   const written = await readWrittenRevision({
     backend, entityType, bundle, id,
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
+    langcode,
     patchResult: result,
     preferCanonical: false,
   });

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