drupal-mcp-connector 2.22.0 → 2.23.1

package/.agents/commands/drupal-create-translation.md

@@ -1,11 +1,11 @@
 ---
-description: "Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers."
-argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [relationships] [revisionId] [dryRun]"
+description: "Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. Pass revise: true to open an unpublished draft over a language that is already published on the live revision and has no working copy (Sentinel X-MCP-Draft-Mode: revise). That requires MCP Sentinel 2.24.0 or later; an older host is refused before any write and the message names that version. dryRun uses the same translations endpoint and Sentinel's non-saving preflight. A working copy is refused. Paragraph revise is not supported. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers."
+argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [relationships] [revisionId] [dryRun] [revise]"
 ---
 
 Call the MCP tool `drupal_create_translation`.
 
-Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers.
+Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. Pass revise: true to open an unpublished draft over a language that is already published on the live revision and has no working copy (Sentinel X-MCP-Draft-Mode: revise). That requires MCP Sentinel 2.24.0 or later; an older host is refused before any write and the message names that version. dryRun uses the same translations endpoint and Sentinel's non-saving preflight. A working copy is refused. Paragraph revise is not supported. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -20,6 +20,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `attributes` (object (pass as JSON)): Translated field values keyed by Drupal machine name
 - `relationships` (object (pass as JSON)): JSON:API relationships. Use for image alt (same file UUID, meta.alt).
 - `revisionId` (string): Paragraph revision id the host already pins. Required for Home-shaped non-default pins.
-- `dryRun` (boolean (true/false)): Validate without saving. Sentinel's non-saving translation preflight receives the real fields, applies them through field access and validates the entity. The result's `checks` block says what was checked.
+- `dryRun` (boolean (true/false)): Validate without saving. Sentinel's non-saving translation preflight receives the real fields, applies them through field access and validates the entity. The result's `checks` block says what was checked. With revise: true the preflight is the same translations endpoint.
+- `revise` (boolean (true/false)): Open an unpublished draft over a translation that is already published on the live default revision and has no working copy. Requires MCP Sentinel 2.24.0 or later. Omit it to create a language that does not exist yet.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

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

@@ -1,11 +1,11 @@
 ---
-description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first."
+description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. A published translation with no working copy is opened with drupal_create_translation and revise: true, not with this tool."
 argument-hint: "<type> <id> [site] [name] [status] [fields] [langcode]"
 ---
 
 Call the MCP tool `drupal_update_media`.
 
-Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first.
+Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. A published translation with no working copy is opened with drupal_create_translation and revise: true, not with this tool.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

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. 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. Published languages are not converted into drafts; 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. 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. Published languages are not converted into drafts; 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,35 @@ 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
+- **Revise a published translation (#376).** `drupal_create_translation` accepts
+  `revise: true` to open an unpublished draft over a language that is already
+  published on the live revision and has no working copy. The call uses
+  Sentinel's translations endpoint and `X-MCP-Draft-Mode: revise`, including
+  on `dryRun`. A host that does not advertise `revise_published_translation`
+  is refused before any write; the message names MCP Sentinel 2.24.0.
+  `drupal_update_node` and `drupal_update_media` with `langcode` name that
+  flag instead of sending the caller to a create that is certain to 409.
+  A plain create that hits the existing-language 409 says to pass `revise: true`
+  when the language is published and there is no working copy, and to continue
+  with the update tool when an unpublished working translation already exists.
+
 ## [2.22.0] - 2026-09-20
 
 ### Added

package/README.md

@@ -88,7 +88,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 | **Fields** | Describe a bundle's fields (type/required/cardinality, best-effort) |
 | **References** | Resolve a human name/title to an entity UUID for relationship fields |
 | **Bulk** | Bulk create/update with per-item partial-failure reporting |
-| **Translations** | List + create entity translations |
+| **Translations** | List, create, and revise published entity translations (`revise: true` on `drupal_create_translation`, MCP Sentinel 2.24.0+) |
 | **Paragraphs** | Create/update/get Paragraph components for embedding in host fields |
 | **Structure** | Menu links (list/create/update, incl. `parent` + `enabled`) + custom blocks (list/create) |
 | **Redirects** | Create active URL redirects (301/302) + update/repoint existing redirects (Redirect module) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.22.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. */
@@ -261,6 +267,11 @@ export async function resolveWorkingCopyPatchTarget(backend, { entityType, bundl
         return { resourceVersion: `id:${workingVid}`, workingCopy: null,
           liveVid, workingVid, inventory };
       }
+      if (!workingCopy) {
+        return {
+          resourceVersion: undefined, workingCopy: null, liveVid, workingVid: null, inventory,
+        };
+      }
     }
   }
   if (!workingCopy) {
@@ -425,14 +436,36 @@ export async function prepareGuardedPatch(backend, {
       throw new StaleCopyError();
     }
   }
-  if (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) {
-    if (!target.workingVid || !target.liveVid || String(target.workingVid) === String(target.liveVid)) {
+    const noWorking = !target.workingVid || !target.liveVid
+      || String(target.workingVid) === String(target.liveVid);
+    if (noWorking) {
+      const liveRow = (target.inventory?.live?.translations ?? [])
+        .find((row) => row?.langcode === langcode);
+      if (liveRow && liveRow.status === true) {
+        if (langcode === target.inventory?.defaultLangcode || liveRow.default === true) {
+          throw new Error(
+            "The default language is not opened with drupal_create_translation. " +
+            "Omit langcode to draft it. A canonical langcode PATCH is not attempted."
+          );
+        }
+        throw new Error(
+          "This language is published on the live revision and has no working copy. " +
+          "Revise it with drupal_create_translation and revise: true. " +
+          "A canonical langcode PATCH is not attempted."
+        );
+      }
       throw new Error(
         "No unpublished working translation for this language. " +
         "Create it with drupal_create_translation first; a canonical langcode PATCH is not attempted."
       );
     }
+    if (target.inventory) assertInventoryDraftLanguage(target.inventory, langcode);
     target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
     try {
       await writeDraft(backend, {
@@ -446,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;
   }
@@ -469,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

@@ -21,6 +21,38 @@ const MISSING_TRANSLATION_ENDPOINT =
 const MISSING_DRAFT_RE = /does not provide Sentinel's governed draft endpoint/;
 const MISSING_TRANSLATION_RE = /does not provide Sentinel's governed draft-translation endpoint/;
 
+/** Inventory operation that opens a draft over a published translation. */
+export const REVISE_PUBLISHED_TRANSLATION = "revise_published_translation";
+
+/**
+ * First MCP Sentinel release that honors `X-MCP-Draft-Mode: revise`.
+ * 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.
+ * Absent on Sentinel releases before 2.24.0.
+ * @param {object} [meta] Inventory `meta`, or an object with `operations`.
+ * @returns {boolean}
+ */
+export function supportsRevisePublishedTranslation(meta) {
+  return Array.isArray(meta?.operations) && meta.operations.includes(REVISE_PUBLISHED_TRANSLATION);
+}
+
+/**
+ * Refusal when the host cannot revise a published translation.
+ * @returns {Error}
+ */
+export function reviseCapabilityError() {
+  return new Error(
+    `This Sentinel host cannot revise a published translation (missing ${REVISE_PUBLISHED_TRANSLATION}). ` +
+    `Update MCP Sentinel to ${MIN_SENTINEL_REVISE_VERSION} or later. No write was attempted.`,
+  );
+}
+
 /**
  * Whether a backend can issue Sentinel's JSON:API draft/translation routes.
  * Requires `capabilities().sentinelDraft` when that flag is present.
@@ -179,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,
@@ -212,6 +245,7 @@ export async function writeDraft(backend, input, preflight = false) {
  */
 export async function createTranslationDraft(backend, input, preflight = false) {
   const { entityType, bundle, id, attributes = {}, relationships, draftRevision } = input;
+  const revise = input.revise === true;
   const langcode = assertDraftLangcode(input.langcode);
   if (entityType === "paragraph") {
     return createParagraphTranslationDraft(backend, {
@@ -234,6 +268,12 @@ export async function createTranslationDraft(backend, input, preflight = false)
   const data = { type: `${entityType}--${bundle}`, id, attributes: safeAttributes };
   if (relationships) data.relationships = relationships;
   const ifMatch = working ? `"${live}:${working}"` : `"${live}"`;
+  const headers = {
+    "If-Match": ifMatch,
+    "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+    "X-MCP-Draft-Langcode": langcode,
+  };
+  if (revise) headers["X-MCP-Draft-Mode"] = "revise";
   let result;
   try {
     result = await sentinelDraftRequest(backend, {
@@ -241,11 +281,7 @@ export async function createTranslationDraft(backend, input, preflight = false)
       missingMessage: MISSING_TRANSLATION_ENDPOINT,
       options: {
         method: "POST",
-        headers: {
-          "If-Match": ifMatch,
-          "X-MCP-Draft-Preflight": preflight ? "1" : "0",
-          "X-MCP-Draft-Langcode": langcode,
-        },
+        headers,
         body: JSON.stringify({ data }),
       },
     });
@@ -256,6 +292,9 @@ export async function createTranslationDraft(backend, input, preflight = false)
     if (result?.meta?.draft_preflight !== true || String(result.meta.live) !== live) {
       throw new Error("The site did not confirm a non-saving translation preflight. Refusing to continue.");
     }
+    if (revise && result.meta.operation !== REVISE_PUBLISHED_TRANSLATION) {
+      throw reviseCapabilityError();
+    }
     return result;
   }
   if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
@@ -274,7 +313,7 @@ export async function createTranslationDraft(backend, input, preflight = false)
  * alias. Permission, 5xx, and malformed inventory are not absence — they throw.
  * @param {object} backend
  * @param {{entityType: string, bundle: string, id: string, existing?: ?object}} ref
- * @returns {Promise<{liveVid: ?(number|string), workingVid: ?(number|string)}>}
+ * @returns {Promise<{liveVid: ?(number|string), workingVid: ?(number|string), operations: string[], inventory: ?object}>}
  */
 export async function resolveNodeTranslationPair(backend, { entityType, bundle, id, existing }) {
   const fromEntity = existing ? entityRevisionId(existing) : null;
@@ -284,7 +323,7 @@ export async function resolveNodeTranslationPair(backend, { entityType, bundle,
   } catch (error) {
     if (!isMissingTranslationEndpoint(error)) throw error;
     if (typeof backend.getEntity !== "function") {
-      return { liveVid: fromEntity, workingVid: undefined };
+      return { liveVid: fromEntity, workingVid: undefined, operations: [], inventory: null };
     }
     let workingCopy = null;
     try {
@@ -296,14 +335,71 @@ export async function resolveNodeTranslationPair(backend, { entityType, bundle,
     }
     const workingVid = workingCopy ? entityRevisionId(workingCopy) : null;
     const distinct = workingVid !== null && fromEntity !== null && String(workingVid) !== String(fromEntity);
-    return { liveVid: fromEntity, workingVid: distinct ? workingVid : undefined };
+    return {
+      liveVid: fromEntity,
+      workingVid: distinct ? workingVid : undefined,
+      operations: [],
+      inventory: null,
+    };
   }
   const liveVid = meta.live?.vid ?? fromEntity;
   const workingVid = meta.working?.vid;
   const distinct = workingVid !== undefined && workingVid !== null && workingVid !== ""
     && liveVid !== undefined && liveVid !== null
     && String(workingVid) !== String(liveVid);
-  return { liveVid, workingVid: distinct ? workingVid : undefined };
+  return {
+    liveVid,
+    workingVid: distinct ? workingVid : undefined,
+    operations: Array.isArray(meta.operations) ? meta.operations : [],
+    inventory: meta,
+  };
+}
+
+/**
+ * Turn Sentinel's create-conflict 409 into the next step that can succeed.
+ * Revise on a host that still says "already exists" did not honor the mode.
+ * @param {unknown} error
+ * @param {{revise?: boolean, inventory?: object|null, langcode?: string, entityType?: string}} [context]
+ * @returns {Error}
+ */
+export function explainExistingTranslation(error, { revise = false, inventory = null, langcode, entityType = "node" } = {}) {
+  const current = error instanceof Error ? error : new Error(String(error));
+  // The create conflict only. "A working copy already exists" is a different 409.
+  if (!/translation for this language already exists/i.test(current.message)) return current;
+  if (revise) {
+    return new Error(
+      "Sentinel did not revise the published translation; it still reports that the language already exists. " +
+      `Update MCP Sentinel to ${MIN_SENTINEL_REVISE_VERSION} or later. No draft was opened.`,
+      { cause: current },
+    );
+  }
+  const continuer = entityType === "media"
+    ? "drupal_update_media"
+    : entityType === "paragraph"
+      ? "drupal_update_paragraph"
+      : "drupal_update_node";
+  const liveRow = (inventory?.live?.translations ?? []).find((row) => row?.langcode === langcode);
+  const workingDistinct = inventory?.working?.vid && inventory?.live?.vid
+    && String(inventory.working.vid) !== String(inventory.live.vid);
+  const workingRow = (inventory?.working?.translations ?? []).find((row) => row?.langcode === langcode);
+  const defaultLang = inventory?.defaultLangcode;
+  if (liveRow && liveRow.status === true && !workingDistinct && langcode !== defaultLang && liveRow.default !== true) {
+    return new Error(
+      "A published translation for this language already exists and there is no working copy. " +
+      "Pass revise: true to drupal_create_translation to open an unpublished draft over it. " +
+      `${continuer} cannot open that draft.`,
+      { cause: current },
+    );
+  }
+  if (workingDistinct && workingRow && workingRow.status === false) {
+    return new Error(
+      "An unpublished working translation for this language already exists. " +
+      `Continue it with ${continuer} and langcode. ` +
+      "Do not create it again.",
+      { cause: current },
+    );
+  }
+  return current;
 }
 
 /**
@@ -373,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/media.js

@@ -319,7 +319,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_media",
-    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first.",
+    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. A published translation with no working copy is opened with drupal_create_translation and revise: true, not with this tool.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {

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. 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. Published languages are not converted into drafts; 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: {

package/src/tools/translations.js

@@ -34,9 +34,13 @@ import { paragraphRevisionId } from "../lib/err-relationships.js";
 import {
   assertDraftLangcode,
   createTranslationDraft,
+  explainExistingTranslation,
   isMissingTranslationEndpoint,
+  MIN_SENTINEL_REVISE_VERSION,
   readTranslationInventory,
   resolveNodeTranslationPair,
+  reviseCapabilityError,
+  supportsRevisePublishedTranslation,
   supportsSentinelDraft,
 } from "../lib/sentinel-draft.js";
 import { mapTranslationRow } from "../lib/translation-rows.js";
@@ -123,7 +127,7 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
  */
 async function createTranslation({
   site: siteName, entityType = "node", type, id, langcode, attributes = {},
-  relationships, revisionId, dryRun = false,
+  relationships, revisionId, dryRun = false, revise = false,
 }) {
   validateMachineName(entityType, "entityType");
   validateMachineName(type, "type");
@@ -137,6 +141,12 @@ async function createTranslation({
   if (entityType !== "node" && entityType !== "paragraph" && entityType !== "media") {
     throw new Error("Governed translation create is implemented for nodes, paragraphs, and media.");
   }
+  if (revise && entityType === "paragraph") {
+    throw new Error(
+      "Revising a published paragraph translation is not supported. " +
+      "Paragraph draft writes continue an unpublished translation on the pinned revision only.",
+    );
+  }
 
   const backend = await resolveBackend(site);
   const existing = await backend.getEntity({ entityType, bundle: type, id });
@@ -158,6 +168,18 @@ async function createTranslation({
     draftRevision = await resolveNodeTranslationPair(backend, {
       entityType, bundle: type, id, existing,
     });
+    if (revise) {
+      if (!supportsRevisePublishedTranslation(draftRevision)) {
+        throw reviseCapabilityError();
+      }
+      if (draftRevision.workingVid) {
+        const continuer = entityType === "media" ? "drupal_update_media" : "drupal_update_node";
+        throw new Error(
+          "A working copy already exists. Continue that draft with " +
+          `${continuer} and langcode. Revise was not attempted.`,
+        );
+      }
+    }
     if (entityType === "node") {
       if (drafted.status === undefined && drafted.moderation_state === undefined) {
         drafted.moderation_state = "draft";
@@ -169,22 +191,46 @@ async function createTranslation({
     assertPublishAllowed(sec, drafted);
   }
 
+  const draftInput = {
+    entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
+    revise: revise === true,
+  };
   if (dryRun) {
-    await createTranslationDraft(backend, {
-      entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
-    }, true);
+    try {
+      await createTranslationDraft(backend, draftInput, true);
+    } catch (error) {
+      throw explainExistingTranslation(error, {
+        revise: revise === true,
+        inventory: draftRevision.inventory,
+        langcode: targetLang,
+        entityType,
+      });
+    }
     return {
-      dryRun: true, operation: "create_translation", entityType, bundle: type, id,
-      langcode: targetLang, attributes: drafted, ...(relationships ? { relationships } : {}),
+      dryRun: true,
+      operation: revise ? "revise_translation" : "create_translation",
+      entityType, bundle: type, id,
+      langcode: targetLang,
+      ...(revise ? { revise: true } : {}),
+      attributes: drafted,
+      ...(relationships ? { relationships } : {}),
       // createTranslationDraft throws unless the site confirmed a non-saving
       // preflight of this exact payload, so the claim holds when we get here.
-      ...dryRunChecks({ operation: "create_translation", preflight: PREFLIGHT_SENTINEL_DRAFT }),
+      ...dryRunChecks({ operation: revise ? "revise_translation" : "create_translation", preflight: PREFLIGHT_SENTINEL_DRAFT }),
     };
   }
 
-  const created = await createTranslationDraft(backend, {
-    entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
-  });
+  let created;
+  try {
+    created = await createTranslationDraft(backend, draftInput);
+  } catch (error) {
+    throw explainExistingTranslation(error, {
+      revise: revise === true,
+      inventory: draftRevision.inventory,
+      langcode: targetLang,
+      entityType,
+    });
+  }
   const redacted = omitLiveComputedMetatag(redactCanonicalEntity(created, sec, entityType));
   if (entityType === "paragraph") return redacted;
   const workingVid = entityRevisionId(created) ?? draftRevision.workingVid;
@@ -229,6 +275,12 @@ export const definitions = [
       "working revision IDs are sent (If-Match) so Sentinel will add the language on that " +
       "draft (#282). English live title, body, status, alias, default revision, and " +
       "paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. " +
+      "Pass revise: true to open an unpublished draft over a language that is already published " +
+      "on the live revision and has no working copy (Sentinel X-MCP-Draft-Mode: revise). " +
+      `That requires MCP Sentinel ${MIN_SENTINEL_REVISE_VERSION} or later; an older host is refused ` +
+      "before any write and the message names that version. dryRun uses the same translations " +
+      "endpoint and Sentinel's non-saving preflight. A working copy is refused. " +
+      "Paragraph revise is not supported. " +
       "The response includes `_revisions.live` / `_revisions.working` when known. " +
       "Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. " +
       "Continue a node draft with drupal_update_node and langcode; a paragraph with " +
@@ -248,7 +300,8 @@ export const definitions = [
         attributes:    { type: "object", description: "Translated field values keyed by Drupal machine name" },
         relationships: { type: "object", description: "JSON:API relationships. Use for image alt (same file UUID, meta.alt)." },
         revisionId:    { type: "string", description: "Paragraph revision id the host already pins. Required for Home-shaped non-default pins." },
-        dryRun:        { type: "boolean", description: "Validate without saving. Sentinel's non-saving translation preflight receives the real fields, applies them through field access and validates the entity. The result's `checks` block says what was checked." },
+        dryRun:        { type: "boolean", description: "Validate without saving. Sentinel's non-saving translation preflight receives the real fields, applies them through field access and validates the entity. The result's `checks` block says what was checked. With revise: true the preflight is the same translations endpoint." },
+        revise:        { type: "boolean", description: "Open an unpublished draft over a translation that is already published on the live default revision and has no working copy. Requires MCP Sentinel 2.24.0 or later. Omit it to create a language that does not exist yet." },
       },
     },
   },