drupal-mcp-connector 2.23.0 → 2.23.1

package/.agents/commands/drupal-update-node.md

@@ -1,11 +1,11 @@
 ---
-description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. A language that is already published and has no working copy is not continued here: call drupal_create_translation with revise: true. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. A published language with no working copy is not converted into a draft by this tool; use drupal_create_translation with revise: true. dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran."
+description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Omit langcode to continue the default language: when the working revision holds several languages and the default language is its unpublished draft, the connector names it for Sentinel (changing shared fields or paragraphs there needs MCP Sentinel 2.24.2). A language that is already published and has no working copy is not continued here: call drupal_create_translation with revise: true. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. A published language with no working copy is not converted into a draft by this tool; use drupal_create_translation with revise: true. dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran."
 argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [langcode] [fields] [relationships] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_update_node`.
 
-Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. A language that is already published and has no working copy is not continued here: call drupal_create_translation with revise: true. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. A published language with no working copy is not converted into a draft by this tool; use drupal_create_translation with revise: true. dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran.
+Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Omit langcode to continue the default language: when the working revision holds several languages and the default language is its unpublished draft, the connector names it for Sentinel (changing shared fields or paragraphs there needs MCP Sentinel 2.24.2). A language that is already published and has no working copy is not continued here: call drupal_create_translation with revise: true. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. A published language with no working copy is not converted into a draft by this tool; use drupal_create_translation with revise: true. dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.23.1] - 2026-09-23
+
+### Fixed
+- **Default-language draft on a multilingual node (#379).** `drupal_update_node`
+  and the other update tools without `langcode` no longer stop at Sentinel's
+  409 when the working revision holds more than one language. When the default
+  language is the unpublished draft in that revision, the connector names it in
+  `X-MCP-Draft-Langcode`, on the preflight and on the write. It reads the
+  translation inventory only after Sentinel asks for the language, so other
+  writes make no extra request. A translation-only draft over published default
+  copy still needs an explicit `langcode`. When an older Sentinel refuses a
+  shared-field or paragraph change as a translation write, the message names
+  MCP Sentinel 2.24.2.
+
 ## [2.23.0] - 2026-09-23
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.23.0",
+  "version": "2.23.1",
   "description": "Drupal MCP Connector — multi-site MCP server for Drupal with JSON:API and GraphQL, governed writes, draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/patch-preflight.js

@@ -25,7 +25,13 @@
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
 import { entityRevisionId } from "./write-revision.js";
 import { httpStatusOf } from "./error-status.js";
-import { writeDraft, readNodeDraftInventory, assertInventoryDraftLanguage } from "./sentinel-draft.js";
+import {
+  writeDraft,
+  readNodeDraftInventory,
+  assertInventoryDraftLanguage,
+  inferDefaultDraftLangcode,
+  MIN_SENTINEL_DEFAULT_LANGUAGE_DRAFT_VERSION,
+} from "./sentinel-draft.js";
 import { PREFLIGHT_NONE, PREFLIGHT_CORE_GUARD, PREFLIGHT_SENTINEL_DRAFT } from "./dry-run-checks.js";
 
 /** Stable error code for a core working-copy / not-latest-revision block. */
@@ -430,7 +436,11 @@ export async function prepareGuardedPatch(backend, {
       throw new StaleCopyError();
     }
   }
-  if (!langcode && target.inventory) assertInventoryDraftLanguage(target.inventory, langcode);
+  // An inventory already in hand names the default-language draft for free.
+  let inferredLangcode = langcode ? undefined : inferDefaultDraftLangcode(target.inventory);
+  if (!langcode && !inferredLangcode && target.inventory) {
+    assertInventoryDraftLanguage(target.inventory, langcode);
+  }
   if (langcode) {
     const noWorking = !target.workingVid || !target.liveVid
       || String(target.workingVid) === String(target.liveVid);
@@ -469,14 +479,32 @@ export async function prepareGuardedPatch(backend, {
     return target;
   }
   if (target.resourceVersion) {
-    target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
+    const draftRevisionFor = (lang) => ({
+      liveVid: target.liveVid,
+      workingVid: target.workingVid,
+      ...(lang ? { langcode: lang } : {}),
+    });
+    const preflightDraft = (lang) => writeDraft(backend, {
+      entityType, bundle, id, attributes, relationships, draftRevision: draftRevisionFor(lang),
+    }, true);
     try {
-      await writeDraft(backend, {
-        entityType, bundle, id, attributes, relationships, draftRevision: target.draftRevision,
-      }, true);
+      await preflightDraft(inferredLangcode);
     } catch (err) {
-      throw rewriteStaleCopyError(err);
+      // The working-copy alias found the draft without Sentinel's inventory.
+      // When Sentinel asks for the language of a multilingual revision, read
+      // the inventory once and name the default-language draft (#379).
+      const retryLang = !inferredLangcode && isMultilingualLanguageRefusal(err)
+        ? await discoverDefaultDraftLangcode(backend, { entityType, bundle, id }, target)
+        : undefined;
+      if (!retryLang) throw explainDefaultLanguageRefusal(rewriteStaleCopyError(err), inferredLangcode);
+      inferredLangcode = retryLang;
+      try {
+        await preflightDraft(inferredLangcode);
+      } catch (retryErr) {
+        throw explainDefaultLanguageRefusal(rewriteStaleCopyError(retryErr), inferredLangcode);
+      }
     }
+    target.draftRevision = draftRevisionFor(inferredLangcode);
     target.preflight = PREFLIGHT_SENTINEL_DRAFT;
     return target;
   }
@@ -492,6 +520,60 @@ export async function prepareGuardedPatch(backend, {
   return target;
 }
 
+/**
+ * Sentinel's 409 for a multilingual working revision sent without
+ * X-MCP-Draft-Langcode (wording before and after 2.24.2).
+ * @param {*} err
+ * @returns {boolean}
+ */
+function isMultilingualLanguageRefusal(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return /X-MCP-Draft-Langcode/.test(message)
+    && /(Translated draft continuation requires|more than one language)/.test(message);
+}
+
+/**
+ * Read Sentinel's inventory and return the default language when it is the
+ * unpublished draft of a multilingual working revision.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string}} ref
+ * @param {{liveVid: *, workingVid: *}} target The revision pair the write targets.
+ * @returns {Promise<string|undefined>}
+ * @throws {WorkingCopyStaleError} When the inventory names a different working revision.
+ */
+async function discoverDefaultDraftLangcode(backend, ref, { liveVid, workingVid }) {
+  // A missing endpoint is null; permission, transport and malformed-response
+  // failures surface as themselves rather than as the original 409.
+  const inventory = await readNodeDraftInventory(backend, ref);
+  if (!inventory) return undefined;
+  const moved = !inventory.working
+    || (workingVid !== null && workingVid !== undefined && String(inventory.working.vid) !== String(workingVid))
+    || (liveVid !== null && liveVid !== undefined && String(inventory.live.vid) !== String(liveVid));
+  if (moved) {
+    throw new WorkingCopyStaleError(new Error("Sentinel's live or working revision changed during discovery."));
+  }
+  return inferDefaultDraftLangcode(inventory);
+}
+
+/**
+ * Sentinel before 2.24.2 treats a default-language header as a translation
+ * write and refuses shared-field and paragraph changes. Say so, instead of
+ * surfacing a translation error for a default-language edit (#379).
+ * @param {*} err
+ * @param {string|undefined} inferredLangcode
+ * @returns {*}
+ */
+function explainDefaultLanguageRefusal(err, inferredLangcode) {
+  const message = err instanceof Error ? err.message : String(err);
+  const translationRule = /on a translation draft|A translation cannot replace|omit langcode to change the shared workflow state/;
+  if (!inferredLangcode || !translationRule.test(message)) return err;
+  return new Error(
+    `${message} This edit targets the default language (${inferredLangcode}) of a multilingual draft. ` +
+    "Changing shared fields or paragraph structure there needs MCP Sentinel " +
+    `${MIN_SENTINEL_DEFAULT_LANGUAGE_DRAFT_VERSION} or later. No write was attempted.`
+  );
+}
+
 /**
  * `backend.updateEntity` with the core working-copy 400 rewritten.
  * A working-copy-targeted 400 is stale/concurrent (#166). A canonical 400

package/src/lib/sentinel-draft.js

@@ -29,6 +29,8 @@ export const REVISE_PUBLISHED_TRANSLATION = "revise_published_translation";
  * Older hosts keep the create 409 and have no path in between.
  */
 export const MIN_SENTINEL_REVISE_VERSION = "2.24.0";
+/** First Sentinel release that keeps a default-language draft out of translation-write rules (#379). */
+export const MIN_SENTINEL_DEFAULT_LANGUAGE_DRAFT_VERSION = "2.24.2";
 
 /**
  * Whether a translation inventory advertises published-translation revise.
@@ -209,7 +211,8 @@ export async function writeDraft(backend, input, preflight = false) {
     "If-Match": `"${live}:${working}"`,
     "X-MCP-Draft-Preflight": preflight ? "1" : "0",
   };
-  const targetLang = langcode ? assertDraftLangcode(langcode) : null;
+  const requestedLang = langcode ?? draftRevision?.langcode;
+  const targetLang = requestedLang ? assertDraftLangcode(requestedLang) : null;
   if (targetLang) headers["X-MCP-Draft-Langcode"] = targetLang;
   const result = await sentinelDraftRequest(backend, {
     entityType, bundle, id, suffix: "mcp-draft", missingMessage: MISSING_DRAFT_ENDPOINT,
@@ -466,6 +469,27 @@ export async function readNodeDraftInventory(backend, ref) {
   return inventory;
 }
 
+/**
+ * The language to name when continuing a multilingual working revision
+ * without an explicit langcode (#379).
+ *
+ * Sentinel requires X-MCP-Draft-Langcode whenever the working revision holds
+ * more than one language, even for the default language. Infer it only when
+ * the default language is the unpublished draft in that revision; a
+ * translation-only draft over published default copy stays explicit.
+ * @param {object|null|undefined} inventory Sentinel translation inventory.
+ * @returns {string|undefined}
+ */
+export function inferDefaultDraftLangcode(inventory) {
+  const rows = inventory?.working?.translations ?? [];
+  if (rows.length < 2) return undefined;
+  const fallback = rows.find((row) => row?.default === true)?.langcode;
+  const defaultLang = typeof inventory.defaultLangcode === "string" ? inventory.defaultLangcode : fallback;
+  if (typeof defaultLang !== "string" || defaultLang === "") return undefined;
+  const row = rows.find((item) => item?.langcode === defaultLang);
+  return row && row.status === false ? defaultLang : undefined;
+}
+
 /**
  * Ensure inventory discovery does not turn a published language into a draft.
  * Sentinel still validates the revision pair and language on every request.

package/src/tools/nodes.js

@@ -644,7 +644,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. A language that is already published and has no working copy is not continued here: call drupal_create_translation with revise: true. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. A published language with no working copy is not converted into a draft by this tool; use drupal_create_translation with revise: true. dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran.",
+    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Omit langcode to continue the default language: when the working revision holds several languages and the default language is its unpublished draft, the connector names it for Sentinel (changing shared fields or paragraphs there needs MCP Sentinel 2.24.2). A language that is already published and has no working copy is not continued here: call drupal_create_translation with revise: true. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. A published language with no working copy is not converted into a draft by this tool; use drupal_create_translation with revise: true. dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {