drupal-mcp-connector 2.24.2 → 2.26.0

package/src/lib/workflow-prompts.js

@@ -110,7 +110,7 @@ export function normalizeWorkflow(raw) {
  * @param {string} namespace
  * @returns {string}
  */
-export function resolvedName(def, namespace) {
+function resolvedName(def, namespace) {
   return def.name || workflowPromptName(namespace, def.id);
 }
 
@@ -141,7 +141,7 @@ export function publicToolName(namespace, alias, tools) {
  * @param {{builtin?: boolean}} [opts]
  * @returns {string[]|null} Public names, or null when any tool is missing.
  */
-export function resolveToolNames(def, namespace, tools, opts = {}) {
+function resolveToolNames(def, namespace, tools, opts = {}) {
   const visible = new Set((tools ?? []).map((tool) => tool.name));
   const names = [];
   for (const alias of def.tools) {
@@ -270,7 +270,7 @@ export function renderWorkflowMessages(workflow, args = {}) {
  * @param {string} instructions
  * @returns {string[]}
  */
-export function toolAliasesInInstructions(instructions) {
+function toolAliasesInInstructions(instructions) {
   const aliases = [];
   const seen = new Set();
   for (const match of String(instructions ?? "").matchAll(/\{tool:([a-z][a-z0-9_]{0,47})\}/g)) {
@@ -287,7 +287,7 @@ export function toolAliasesInInstructions(instructions) {
  * @param {object} got
  * @returns {string}
  */
-export function instructionTextFromDrupalPrompt(got) {
+function instructionTextFromDrupalPrompt(got) {
   const messages = Array.isArray(got?.messages) ? got.messages : [];
   const parts = [];
   for (const message of messages) {
@@ -313,7 +313,7 @@ export function instructionTextFromDrupalPrompt(got) {
  * @param {object} toolsMap `serverTools.modules.tools`
  * @returns {boolean}
  */
-export function inferReadOnly(aliases, toolsMap) {
+function inferReadOnly(aliases, toolsMap) {
   for (const alias of aliases) {
     const operation = toolsMap?.[alias]?.operation;
     if (operation === "write" || operation === "delete") return false;

package/src/tools/codegen.js

@@ -18,7 +18,7 @@
 import { getSiteConfig } from "../lib/config.js";
 import { sshDrush } from "./drush.js";
 import { callBoundModuleTool, toolResultData } from "../lib/server-tools.js";
-import { SecurityError } from "../lib/security.js";
+import { SecurityError, configReadBindingScope } from "../lib/security.js";
 import { validateMachineName } from "../lib/validate.js";
 
 const INSPECT = "graphql-compose-codegen:inspect";
@@ -83,7 +83,7 @@ async function runGqcc(
     ]).get(subcommand);
     const result = toolResultData(await callBoundModuleTool(site, binding, {
       bundles: names, skip_fields: skip,
-    }, { operation: "read", scope: "mcp_config", capabilities: ["configRead"] }));
+    }, { operation: "read", scope: configReadBindingScope(site), capabilities: ["configRead"] }));
     if (result?.success !== true || !result.data || typeof result.data !== "object" || Array.isArray(result.data)) {
       throw new SecurityError("Codegen module returned an invalid result. No SSH fallback was attempted.");
     }

package/src/tools/config.js

@@ -24,6 +24,8 @@ import {
   assertCoreExtensionValueKeepsProtected,
   isCoreExtensionConfig,
   hasScope,
+  hasConfigReadScope,
+  configReadBindingScope,
   CORE_EXTENSION_CONFIG,
   SecurityError,
 } from "../lib/security.js";
@@ -36,8 +38,9 @@ import { callGovernedServerTool, callBoundModuleTool, toolResultData } from "../
  */
 async function configTool(site, binding, args, operation, capability) {
   if (site.serverTools?.bindings !== undefined) {
+    const scope = operation === "read" ? configReadBindingScope(site) : "mcp_config";
     return callBoundModuleTool(site, binding, args, {
-      operation, scope: "mcp_config", capabilities: [capability],
+      operation, scope, capabilities: [capability],
     });
   }
   return callGovernedServerTool(site, binding, args);
@@ -144,7 +147,7 @@ async function assertCoreExtensionWriteAllowed(site, sec, value) {
 async function configSet({ site: siteName, name, value }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
-  assertConfigScope(site, `config:set ${name}`);
+  assertConfigScope(site, `config:set ${name}`, { write: true });
   assertNotReadOnly(sec, `config:set ${name}`);
   assertConfigWriteAllowed(sec);
   if (isCoreExtensionConfig(name)) await assertCoreExtensionWriteAllowed(site, sec, value);
@@ -188,11 +191,13 @@ async function whoami({ site: siteName, _resolvedSource }) {
   const summary = getSecuritySummary(site);
   // Effective capability = connector preset AND the scope the server demands.
   // Reporting the preset alone over-states what the token can do — e.g. the
-  // content-editor preset allows config reads locally, but every config_* tool
-  // is gated server-side on mcp_config, which the content tier does not hold.
-  // When no OAuth scopes are configured, hasScope() is a no-op (preset-only).
+  // content-editor preset allows config reads locally, but config_* tools are
+  // gated server-side on mcp_config (writes) or mcp_config / mcp_config_read
+  // (reads). The content tier holds neither. When no OAuth scopes are
+  // configured, hasScope() is a no-op (preset-only).
   const canWrite  = !sec.readOnly && hasScope(site, "mcp_write");
   const canConfig = hasScope(site, "mcp_config");
+  const canConfigRead = hasConfigReadScope(site);
   const identity = getRequestIdentity();
   // Dispatch may inject `site` after a default/grant resolution. Prefer the
   // authoritative source so `target` and `_target` cannot disagree (#167).
@@ -212,7 +217,7 @@ async function whoami({ site: siteName, _resolvedSource }) {
       read:        hasScope(site, "mcp_read"),
       write:       canWrite,
       delete:      sec.allowDestructive && canWrite,
-      configRead:  sec.allowConfigRead  && canConfig,
+      configRead:  sec.allowConfigRead  && canConfigRead,
       configWrite: sec.allowConfigWrite && !sec.readOnly && canConfig,
       // Local publish policy (allowPublish), symmetric with delete/config caps.
       // Defaults false in every preset except `development`; the remote Drupal's

package/src/tools/entities.js

@@ -308,7 +308,7 @@ export const definitions = [
         langcode:      { type: "string", description: "Target language for an unpublished working translation (nodes). Continues that translation via Sentinel." },
         attributes:    { type: "object" },
         relationships: { type: "object" },
-        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun." },
+        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A changed/revision_timestamp gap on the default revision (possiblyPatchBlocked) is a warning on list_revisions, not a local dryRun refusal — the write proceeds to the core probe / Sentinel (#405). An actual Sentinel stale-copy refusal is still rewritten. Any refusal fails the dryRun." },
         returning:     RETURNING_SCHEMA,
       },
     },

package/src/tools/index.js

@@ -41,7 +41,7 @@ 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,
+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, codegen];
 

package/src/tools/media.js

@@ -15,7 +15,7 @@ import {
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
 } from "../lib/security.js";
 import {
-  assertDraftLangcode, readDraftTranslation, readTranslationInventory,
+  assertDraftLangcode, readDraftTranslation, readTranslationInventory, isUnpublishedWorkingDraft,
 } from "../lib/sentinel-draft.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 import { entityRevisionId } from "../lib/write-revision.js";
@@ -69,7 +69,7 @@ async function getMedia({ site: siteName, type, id, 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) {
+    if (workingRow && isUnpublishedWorkingDraft(workingRow) && 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 },

package/src/tools/nodes.js

@@ -19,7 +19,9 @@ import { resolveErrRelationships, relationshipsWereSent, paragraphPinsFromEntity
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 import { dryRunChecks, PREFLIGHT_NONE } from "../lib/dry-run-checks.js";
-import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/sentinel-draft.js";
+import {
+  assertDraftLangcode, readDraftTranslation, readTranslationInventory, isUnpublishedWorkingDraft,
+} from "../lib/sentinel-draft.js";
 import { paragraphResourceVersion } from "./paragraphs.js";
 import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
@@ -294,7 +296,7 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion, in
     const targetLang = assertDraftLangcode(langcode);
     const inventory = await readTranslationInventory(backend, { entityType: "node", bundle: type, id });
     const workingRow = (inventory.working?.translations ?? []).find((row) => row.langcode === targetLang);
-    if (workingRow && workingRow.status === false && inventory.live?.vid && inventory.working?.vid) {
+    if (workingRow && isUnpublishedWorkingDraft(workingRow) && inventory.live?.vid && inventory.working?.vid) {
       const entity = await readDraftTranslation(backend, {
         entityType: "node", bundle: type, id, langcode: targetLang,
         draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
@@ -664,7 +666,7 @@ export const definitions = [
         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." },
         fields:  { type: "object", description: "Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here." },
         relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot. Image alt on a translation uses the existing file UUID plus meta.alt; replacing the file is refused." },
-        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; Drupal does not check field access or entity validation on that probe (`core_patch_guard`). Text format is resolved before the preview returns, including on that path: a known allowed_formats list is enforced, and an unknown list reuses the format stored on the field. Other fields can still fail the real write with a field-access 403 or a validation 422. Unmoderated targets get no server-side check at all (`none`). A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun." },
+        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; Drupal does not check field access or entity validation on that probe (`core_patch_guard`). Text format is resolved before the preview returns, including on that path: a known allowed_formats list is enforced, and an unknown list reuses the format stored on the field. Other fields can still fail the real write with a field-access 403 or a validation 422. Unmoderated targets get no server-side check at all (`none`). A changed/revision_timestamp gap on the default revision (possiblyPatchBlocked) is a warning on list_revisions, not a local dryRun refusal — the write proceeds to the core probe / Sentinel (#405). An actual Sentinel stale-copy refusal is still rewritten. Any refusal fails the dryRun." },
         returning: RETURNING_SCHEMA,
       },
     },

package/src/tools/reports-config.js

@@ -18,7 +18,7 @@
  */
 
 import { getSiteConfig } from "../lib/config.js";
-import { resolveSecurityConfig, assertConfigReadAllowed } from "../lib/security.js";
+import { resolveSecurityConfig, assertConfigReadAllowed, configReadBindingScope } from "../lib/security.js";
 import { gatedReport } from "../lib/reports-support.js";
 import { callGovernedServerTool, callBoundModuleTool, toolResultData } from "../lib/server-tools.js";
 import { runPrivileged, serverToolsConfigured, drushConfigured } from "../lib/audit-sources.js";
@@ -67,7 +67,7 @@ function configSourceAvailable(site) {
 async function readConfig(site, name) {
   if (site.serverTools?.bindings !== undefined) {
     return toolResultData(await callBoundModuleTool(site, "configGet", { name }, {
-      operation: "read", scope: "mcp_config", capabilities: ["configRead"],
+      operation: "read", scope: configReadBindingScope(site), capabilities: ["configRead"],
     }));
   }
   if (serverToolsConfigured(site)) {
@@ -89,7 +89,7 @@ async function readConfig(site, name) {
 async function listConfigNames(site, prefix) {
   if (site.serverTools?.bindings !== undefined) {
     return pickConfigNames(toolResultData(await callBoundModuleTool(site, "configList", { prefix }, {
-      operation: "read", scope: "mcp_config", capabilities: ["configRead"],
+      operation: "read", scope: configReadBindingScope(site), capabilities: ["configRead"],
     })));
   }
   if (serverToolsConfigured(site)) {

package/src/tools/reports-content.js

@@ -308,9 +308,11 @@ async function scheduledContent({ site: siteName, type, sampleSize = 200 }) {
   const overdue = [];
   for (const n of nodes) {
     for (const [field, action] of [["publish_on", "publish"], ["unpublish_on", "unpublish"]]) {
-      const raw = scalar(n, [field]);
+      // Presence of the key (even null) means Scheduler is exposed (#403).
+      const { present, value } = fieldPresence(n, field);
+      if (present) sawField = true;
+      const raw = value && typeof value === "object" && "value" in value ? value.value : value;
       if (raw === undefined || raw === null || raw === "" || raw === 0) continue;
-      sawField = true;
       const ms = toMillis(raw);
       if (ms === null) continue;
       const rec = { id: n.id, title: n.title, action, when: new Date(ms).toISOString(), path: n.url };

package/src/tools/revisions.js

@@ -25,6 +25,7 @@ import {
 } from "../lib/security.js";
 import {
   assertDraftLangcode, readDraftTranslation, readNodeDraftInventory, readTranslationInventory,
+  isUnpublishedWorkingDraft,
 } from "../lib/sentinel-draft.js";
 import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 import { changedAheadOfRevision, prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
@@ -221,7 +222,7 @@ async function getRevision({ site: siteName, type, id, version, langcode }) {
     const targetLang = assertDraftLangcode(langcode);
     const inventory = await readTranslationInventory(backend, { entityType: "node", bundle: type, id });
     const workingRow = (inventory.working?.translations ?? []).find((row) => row.langcode === targetLang);
-    if (!inventory.live?.vid || !inventory.working?.vid || !workingRow || workingRow.status !== false) {
+    if (!inventory.live?.vid || !inventory.working?.vid || !workingRow || !isUnpublishedWorkingDraft(workingRow)) {
       throw new Error("No unpublished working translation is addressable for this revision.");
     }
     const entity = await readDraftTranslation(backend, {

package/src/tools/scheduler.js

@@ -6,8 +6,12 @@
  * the schedule on two entity fields — `publish_on` and `unpublish_on` — which the
  * module adds to a content type when scheduling is enabled for that bundle.
  *
+ * On a bundle under Content Moderation, Scheduler Content Moderation
+ * Integration also needs `publish_state` / `unpublish_state`. Dates without
+ * those states are accepted by Drupal and then fail at cron (#402).
+ *
  * This is a thin write over the canonical backend's updateEntity: the supplied
- * timestamps are passed straight through as those two attributes. Scheduler
+ * timestamps are passed straight through as those attributes. Scheduler
  * accepts an ISO 8601 datetime string or a Unix epoch; we accept either form and
  * forward it unchanged (the JSON:API backend coerces datetime fields as needed).
  *
@@ -20,6 +24,8 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertWriteAllowed, redactCanonicalEntity } from "../lib/security.js";
+import { entityLooksModerated } from "../lib/moderation-default.js";
+import { fieldPresence } from "../lib/reports-support.js";
 
 /**
  * Heuristic: does this backend error look like a missing/unknown field? Scheduler
@@ -31,7 +37,19 @@ import { resolveSecurityConfig, assertWriteAllowed, redactCanonicalEntity } from
  */
 export function looksLikeUnknownField(err) {
   const msg = String(err?.message || err || "");
-  return /unknown|not exist|no field|invalid field|unrecognized|publish_on|unpublish_on/i.test(msg);
+  return /unknown|not exist|no field|invalid field|unrecognized|publish_on|unpublish_on|publish_state|unpublish_state/i.test(msg);
+}
+
+/**
+ * Whether a schema or entity exposes a Scheduler attribute.
+ * @param {?object} entity Canonical entity.
+ * @param {?object} schema Bundle schema from getEntitySchema.
+ * @param {string} field Field machine name.
+ * @returns {boolean}
+ */
+function schedulerFieldPresent(entity, schema, field) {
+  if (entity && fieldPresence(entity, field).present) return true;
+  return Boolean(schema?.attributes && Object.prototype.hasOwnProperty.call(schema.attributes, field));
 }
 
 /**
@@ -41,12 +59,18 @@ export function looksLikeUnknownField(err) {
  * canonical updateEntity. At least one of publishOn / unpublishOn must be given.
  * Each value is forwarded unchanged (ISO 8601 string or epoch integer).
  *
- * @param {object} args - { site?, type, id, publishOn?, unpublishOn? }.
+ * On a moderated bundle, `publishState` / `unpublishState` are required when
+ * the matching date is set and the Scheduler CM state field exists (#402).
+ *
+ * @param {object} args - { site?, type, id, publishOn?, unpublishOn?, publishState?, unpublishState? }.
  * @returns {Promise<object>} The redacted, updated node descriptor.
  * @throws {Error} If neither timestamp is supplied, if the policy forbids the
- *   write, or — degraded — if the Scheduler fields are unknown on the bundle.
+ *   write, if a moderated schedule is missing its target state, or — degraded —
+ *   if the Scheduler fields are unknown on the bundle.
  */
-async function schedulePublish({ site: siteName, type, id, publishOn, unpublishOn }) {
+async function schedulePublish({
+  site: siteName, type, id, publishOn, unpublishOn, publishState, unpublishState,
+}) {
   if (publishOn === undefined && unpublishOn === undefined) {
     throw new Error("Provide at least one of publishOn or unpublishOn to schedule the node.");
   }
@@ -55,9 +79,65 @@ async function schedulePublish({ site: siteName, type, id, publishOn, unpublishO
   assertWriteAllowed(sec, "update", "node", type);
   const backend = await resolveBackend(site);
 
+  let existing = null;
+  if (typeof backend.getEntity === "function") {
+    try {
+      existing = await backend.getEntity({ entityType: "node", bundle: type, id }) ?? null;
+    } catch {
+      existing = null;
+    }
+  }
+  let schema = null;
+  if (existing && typeof backend.getEntitySchema === "function") {
+    try {
+      schema = await backend.getEntitySchema("node", type);
+    } catch {
+      schema = null;
+    }
+  }
+
+  const moderated = entityLooksModerated(existing);
+  if (moderated) {
+    if (publishOn !== undefined) {
+      const hasStateField = schedulerFieldPresent(existing, schema, "publish_state");
+      if (!hasStateField) {
+        throw new Error(
+          `Could not schedule publish on moderated '${type}': the publish_state field is not available. ` +
+          "Moderated bundles need the Scheduler Content Moderation Integration module, and a publishState " +
+          "(e.g. 'published') whenever publishOn is set. Without that state, cron logs 'Publishing failed' " +
+          "and the node never goes live. See connector #402."
+        );
+      }
+      if (publishState === undefined) {
+        throw new Error(
+          "Moderated content requires publishState (the workflow state to enter at publishOn, e.g. 'published'). " +
+          "Scheduler dates without a target state are accepted by Drupal and then fail at cron. See connector #402."
+        );
+      }
+    }
+    if (unpublishOn !== undefined) {
+      const hasStateField = schedulerFieldPresent(existing, schema, "unpublish_state");
+      if (!hasStateField) {
+        throw new Error(
+          `Could not schedule unpublish on moderated '${type}': the unpublish_state field is not available. ` +
+          "Moderated bundles need the Scheduler Content Moderation Integration module, and an unpublishState " +
+          "(e.g. 'draft') whenever unpublishOn is set. See connector #402."
+        );
+      }
+      if (unpublishState === undefined) {
+        throw new Error(
+          "Moderated content requires unpublishState (the workflow state to enter at unpublishOn, e.g. 'draft'). " +
+          "Scheduler dates without a target state are accepted by Drupal and then fail at cron. See connector #402."
+        );
+      }
+    }
+  }
+
   const attributes = {};
   if (publishOn !== undefined) attributes.publish_on = publishOn;
   if (unpublishOn !== undefined) attributes.unpublish_on = unpublishOn;
+  if (publishState !== undefined) attributes.publish_state = publishState;
+  if (unpublishState !== undefined) attributes.unpublish_state = unpublishState;
 
   let updated;
   try {
@@ -67,6 +147,7 @@ async function schedulePublish({ site: siteName, type, id, publishOn, unpublishO
       throw new Error(
         `Could not set Scheduler dates on '${type}': the publish_on / unpublish_on fields are not available. ` +
         "This tool requires the Drupal Scheduler module to be installed and enabled for this content type. " +
+        "Moderated bundles also need Scheduler Content Moderation Integration (publish_state / unpublish_state). " +
         `Backend error: ${err?.message || err}`,
       );
     }
@@ -85,18 +166,24 @@ export const definitions = [
     description:
       "Schedule a content node to publish and/or unpublish at a future time using the Drupal Scheduler module. " +
       "Sets the publish_on and unpublish_on fields on the node. " +
+      "On a bundle under Content Moderation, also set publishState / unpublishState " +
+      "(written as publish_state / unpublish_state) — dates alone never go live. " +
       "Requires the Scheduler module to be installed and enabled for the content type, with the publish_on / " +
       "unpublish_on fields present on the bundle — otherwise the call fails with a clear capability error. " +
+      "Moderated bundles additionally need Scheduler Content Moderation Integration; when those state fields " +
+      "exist, the matching state is required whenever a date is set. " +
       "Timestamps accept ISO 8601 (e.g. '2026-07-01T12:00:00Z') or a Unix epoch and are passed through unchanged. " +
       "Provide at least one of publishOn or unpublishOn.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
-        site:        { type: "string", description: "Named site (omit for default)" },
-        type:        { type: "string", description: "Content type machine name, e.g. 'article'" },
-        id:          { type: "string", description: "Node UUID" },
-        publishOn:   { type: ["string", "number"], description: "When to publish — ISO 8601 datetime or Unix epoch. Sets the Scheduler publish_on field." },
-        unpublishOn: { type: ["string", "number"], description: "When to unpublish — ISO 8601 datetime or Unix epoch. Sets the Scheduler unpublish_on field." },
+        site:           { type: "string", description: "Named site (omit for default)" },
+        type:           { type: "string", description: "Content type machine name, e.g. 'article'" },
+        id:             { type: "string", description: "Node UUID" },
+        publishOn:      { type: ["string", "number"], description: "When to publish — ISO 8601 datetime or Unix epoch. Sets the Scheduler publish_on field." },
+        unpublishOn:    { type: ["string", "number"], description: "When to unpublish — ISO 8601 datetime or Unix epoch. Sets the Scheduler unpublish_on field." },
+        publishState:   { type: "string", description: "Moderation state to enter at publishOn (e.g. 'published'). Required on moderated bundles when publishOn is set." },
+        unpublishState: { type: "string", description: "Moderation state to enter at unpublishOn (e.g. 'draft'). Required on moderated bundles when unpublishOn is set." },
       },
     },
   },

package/src/tools/structure.js

@@ -156,7 +156,7 @@ async function createMenuLink({ site: siteName, title, link, menu, weight, paren
  * site — so an unrelated edit (rename, re-weight, re-parent) can never silently
  * regress a live link to disabled. Set `parent` to re-nest a link.
  *
- * @param {object} args - { site?, id, title?, link?, menu?, weight?, parent?, enabled? }.
+ * @param {object} args - { site?, id, title?, link?, menu?, weight?, parent?, enabled?, langcode? }.
  * @returns {Promise<object>} The updated menu-link descriptor from the backend.
  * @throws {Error} If id is missing.
  * @throws {SecurityError} If updating menu_link_content is not permitted.
@@ -243,7 +243,7 @@ async function createBlock({ site: siteName, type, info, body }) {
 export const definitions = [
   {
     name: "drupal_list_menu_links",
-    description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, and weight. Note: this lists editable menu_link_content entities, not code-defined static links.",
+    description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, weight, and fields.drupal_internal__id (numeric id for /admin/structure/menu/item/{id}/edit). Note: this lists editable menu_link_content entities, not code-defined static links.",
     inputSchema: {
       type: "object",
       properties: {
@@ -273,7 +273,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_menu_link",
-    description: "Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Checked against the site security config.",
+    description: "Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Pass langcode to update an existing translation via JSON:API language negotiation (URL prefix, then language headers). Does not create a missing translation. Responses include fields.drupal_internal__id. Checked against the site security config.",
     inputSchema: {
       type: "object", required: ["id"],
       properties: {
@@ -285,7 +285,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." },
+        langcode: { type: "string", description: "Existing translation to update (e.g. 'es'). Uses /{langcode}/jsonapi/… when the site prefixes JSON:API, then language headers. Omit for the default language. Does not create a missing translation." },
       },
     },
   },

package/src/tools/translations.js

@@ -45,6 +45,9 @@ import {
   supportsRevisePublishedTranslation,
   supportsReviseOverWorkingCopy,
   supportsSentinelDraft,
+  isUnpublishedWorkingDraft,
+  isCarriedPublishedLanguage,
+  carriedPublishedLanguageError,
 } from "../lib/sentinel-draft.js";
 import { mapTranslationRow } from "../lib/translation-rows.js";
 import { dryRunChecks, PREFLIGHT_SENTINEL_DRAFT } from "../lib/dry-run-checks.js";
@@ -179,13 +182,16 @@ async function createTranslation({
       if (hasWorking) {
         const workingRow = (draftRevision.inventory?.working?.translations ?? [])
           .find((row) => row?.langcode === targetLang);
-        if (workingRow && workingRow.status === false) {
+        if (workingRow && isUnpublishedWorkingDraft(workingRow)) {
           const continuer = entityType === "media" ? "drupal_update_media" : "drupal_update_node";
           throw new Error(
             "This language is already an unpublished draft on the working copy. " +
             `Continue it with ${continuer} and langcode. Revise was not attempted.`,
           );
         }
+        if (workingRow && isCarriedPublishedLanguage(workingRow)) {
+          throw carriedPublishedLanguageError(targetLang);
+        }
         // Sentinel 2.25.0+ builds the draft on the named working copy; the
         // pair is sent as If-Match "live:working" by createTranslationDraft.
         if (!supportsReviseOverWorkingCopy(draftRevision)) {