drupal-mcp-connector 2.14.1 → 2.15.0

package/src/lib/patch-preflight.js

@@ -35,6 +35,9 @@ export const PATCH_WORKING_COPY_STALE_CODE = "PATCH_WORKING_COPY_STALE";
 /** Stable error code when the working-copy resource does not match the target. */
 export const PATCH_TARGET_AMBIGUOUS_CODE = "PATCH_TARGET_AMBIGUOUS";
 
+/** Stable error code for Sentinel's save-time stale-default-revision refusal. */
+export const STALE_COPY_CODE = "STALE_COPY";
+
 const WORKING_COPY_PATCH_RE = /has a working copy is not yet supported/i;
 
 /**
@@ -98,6 +101,81 @@ export class WorkingCopyStaleError extends Error {
   }
 }
 
+/**
+ * Sentinel's save-time stale-default check (McpWritePreconditions) is not
+ * exercised by the id-mismatch PATCH probe — that probe fails before
+ * entity validation / presave. A published node with no distinct working
+ * copy and a changed timestamp later than its own revision_timestamp is
+ * the readable fingerprint (`possiblyPatchBlocked`). dryRun and the real
+ * write must refuse the same way; reloading and retrying does not help.
+ * Do not bypass the draft or publish gate. See connector #273.
+ */
+export const STALE_COPY_MESSAGE =
+  "This entity cannot be updated: MCP Sentinel refused a stale default-revision " +
+  "write (the content changed after this copy was loaded). dryRun and the real " +
+  "write share this check. rel:latest-version and rel:working-copy report the " +
+  "same vid, but the default revision's changed timestamp is later than its " +
+  "revision_timestamp (possiblyPatchBlocked). Reloading and retrying the same " +
+  "canonical PATCH will not help. Do not bypass the draft or publish gate. " +
+  "See connector #273 / #201.";
+
+const STALE_COPY_RE = /changed after this copy was loaded/i;
+
+/**
+ * Thrown when a canonical write (or its dryRun) would hit Sentinel's
+ * stale-default-revision check (#273).
+ */
+export class StaleCopyError extends Error {
+  /**
+   * @param {?Error} [cause]
+   */
+  constructor(cause) {
+    super(STALE_COPY_MESSAGE);
+    this.name = "StaleCopyError";
+    this.code = STALE_COPY_CODE;
+    if (cause) this.cause = cause;
+  }
+}
+
+/**
+ * Whether an error is Sentinel's stale-version refusal (or our rewrite).
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isStaleCopyError(err) {
+  if (err instanceof StaleCopyError) return true;
+  return STALE_COPY_RE.test(String(err?.message || ""));
+}
+
+/**
+ * Whether a canonical entity's `changed` is later than its own
+ * `revision_timestamp` — the same fingerprint `drupal_list_revisions`
+ * reports as `possiblyPatchBlocked`.
+ * @param {?object} entity Canonical entity or revision summary.
+ * @returns {boolean}
+ */
+export function changedAheadOfRevision(entity) {
+  if (!entity || typeof entity !== "object") return false;
+  const fields = entity.fields && typeof entity.fields === "object" ? entity.fields : {};
+  const changed = entity.changed;
+  const rev = entity.revisionTimestamp ?? fields.revision_timestamp;
+  if (!changed || !rev) return false;
+  const changedMs = Date.parse(changed);
+  const revMs = Date.parse(rev);
+  if (!Number.isFinite(changedMs) || !Number.isFinite(revMs)) return false;
+  return changedMs > revMs;
+}
+
+/**
+ * Rewrite Sentinel's save-time stale-version refusal into {@link StaleCopyError}.
+ * @param {unknown} err
+ * @returns {unknown}
+ */
+export function rewriteStaleCopyError(err) {
+  if (!isStaleCopyError(err) || err instanceof StaleCopyError) return err;
+  return new StaleCopyError(err instanceof Error ? err : new Error(String(err)));
+}
+
 /**
  * Thrown when `rel:working-copy` resolves to a different UUID than the
  * entity being updated.
@@ -300,22 +378,67 @@ export async function preflightPatchWritable({
  * @returns {Promise<{resourceVersion: ?string, workingCopy: ?object, liveVid: ?number|string, workingVid: ?number|string}>}
  */
 export async function prepareGuardedPatch(backend, {
-  entityType, bundle, id, existing, attributes, relationships,
+  entityType, bundle, id, existing, attributes, relationships, langcode,
 }) {
   const target = shouldPreflightPatch({ existing, attributes })
     ? await resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing })
     : { resourceVersion: undefined, workingCopy: null, liveVid: null, workingVid: null };
+  if (shouldPreflightPatch({ existing, attributes }) && !target.resourceVersion) {
+    // Canonical path (no distinct working copy). The id-mismatch probe never
+    // reaches Sentinel's save-time stale-default check; refuse here when the
+    // possiblyPatchBlocked fingerprint is already readable (#273).
+    let fingerprint = existing;
+    const fields = fingerprint?.fields && typeof fingerprint.fields === "object" ? fingerprint.fields : {};
+    const hasTimestamps = Boolean(
+      fingerprint?.changed && (fingerprint.revisionTimestamp || fields.revision_timestamp),
+    );
+    if (!hasTimestamps && typeof backend?.getEntity === "function") {
+      const latest = await backend.getEntity({
+        entityType, bundle, id, resourceVersion: "rel:latest-version",
+      }).catch(() => null);
+      if (latest) fingerprint = latest;
+    }
+    if (changedAheadOfRevision(fingerprint)) {
+      throw new StaleCopyError();
+    }
+  }
+  if (langcode) {
+    if (!target.workingVid || !target.liveVid || String(target.workingVid) === String(target.liveVid)) {
+      throw new Error(
+        "No unpublished working translation for this language. " +
+        "Create it with drupal_create_translation first; a canonical langcode PATCH is not attempted."
+      );
+    }
+    target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
+    try {
+      await writeDraft(backend, {
+        entityType, bundle, id, attributes, relationships, langcode,
+        draftRevision: target.draftRevision,
+      }, true);
+    } catch (err) {
+      throw rewriteStaleCopyError(err);
+    }
+    return target;
+  }
   if (target.resourceVersion) {
     target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
-    await writeDraft(backend, {
-      entityType, bundle, id, attributes, relationships, draftRevision: target.draftRevision,
-    }, true);
+    try {
+      await writeDraft(backend, {
+        entityType, bundle, id, attributes, relationships, draftRevision: target.draftRevision,
+      }, true);
+    } catch (err) {
+      throw rewriteStaleCopyError(err);
+    }
     return target;
   }
-  await preflightPatchWritable({
-    backend, entityType, bundle, id, existing, attributes,
-    resourceVersion: target.resourceVersion,
-  });
+  try {
+    await preflightPatchWritable({
+      backend, entityType, bundle, id, existing, attributes,
+      resourceVersion: target.resourceVersion,
+    });
+  } catch (err) {
+    throw rewriteStaleCopyError(err);
+  }
   return target;
 }
 
@@ -336,6 +459,8 @@ export async function updateEntityGuarded(backend, input) {
     }
     return await backend.updateEntity(input);
   } catch (err) {
+    const stale = rewriteStaleCopyError(err);
+    if (stale !== err) throw stale;
     if (!isWorkingCopyPatchError(err)) throw err;
     const cause = err instanceof Error ? err : new Error(String(err));
     if (input?.resourceVersion === "rel:working-copy") {

package/src/lib/path-alias.js

@@ -0,0 +1,37 @@
+/**
+ * URL-alias helpers shared by node writes and the JSON:API path reader.
+ *
+ * Path aliases are not revisioned. The node's `path` field is a computed
+ * view of `path_alias` rows; unpublished / forward revisions often omit
+ * `pid` even when a row exists. Round-tripping that pid (and verifying
+ * after save) is how title-only edits keep the existing alias (#274).
+ */
+
+/** JSON:API entity type + bundle for a path alias row. */
+export const PATH_ALIAS_ENTITY_TYPE = "path_alias";
+
+/**
+ * Normalize a URL-alias path for storage/comparison: trim, ensure a single
+ * leading slash, drop a trailing slash (except root).
+ * @param {*} value A raw alias.
+ * @returns {?string} The normalized alias, or null when empty.
+ */
+export function normalizeAlias(value) {
+  if (value === undefined || value === null) return null;
+  let s = String(value).trim();
+  if (!s) return null;
+  if (!s.startsWith("/")) s = `/${s}`;
+  if (s.length > 1) s = s.replace(/\/+$/, "");
+  return s;
+}
+
+/**
+ * Whether a value is a positive integer node id suitable for `/node/{nid}`.
+ * @param {*} value Raw drupal internal id.
+ * @returns {boolean}
+ */
+export function isPositiveNid(value) {
+  if (value === undefined || value === null || value === "") return false;
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0;
+}

package/src/tools/entities.js

@@ -96,7 +96,7 @@ async function createEntity({ site: siteName, entityType, bundle, attributes = {
  * @returns {Promise<object>} The updated entity descriptor.
  * @throws {SecurityError} If updating the type/bundle is not permitted.
  */
-async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {}, dryRun = false, returning = "full" }) {
+async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {}, langcode, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", entityType, bundle);
@@ -119,6 +119,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
   const patchTarget = await prepareGuardedPatch(backend, {
     entityType, bundle, id, existing, attributes: safeAttributes, relationships: resolvedRelationships,
+    langcode,
   });
   if (dryRun) {
     return {
@@ -128,6 +129,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   }
   const result = await updateEntityGuarded(backend, {
     entityType, bundle, id, attributes: safeAttributes, relationships: resolvedRelationships,
+    ...(langcode ? { langcode } : {}),
     ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
     ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
   });
@@ -289,9 +291,10 @@ export const definitions = [
         entityType:    { type: "string" },
         bundle:        { type: "string" },
         id:            { type: "string" },
+        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, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun." },
+        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. 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." },
         returning:     RETURNING_SCHEMA,
       },
     },

package/src/tools/nodes.js

@@ -14,32 +14,19 @@ import {
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
 } from "../lib/security.js";
 import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
-import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
+import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA, omitLiveComputedMetatag } from "../lib/entity-response.js";
 import { resolveErrRelationships, relationshipsWereSent } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
 import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
+import { normalizeAlias, PATH_ALIAS_ENTITY_TYPE } from "../lib/path-alias.js";
 
 /** Fallback language for an alias when the node exposes none. */
 const DEFAULT_ALIAS_LANGCODE = "en";
 
-/**
- * Normalize a URL-alias path for storage/comparison: trim, ensure a single
- * leading slash, drop a trailing slash (except root).
- * @param {*} value A raw alias.
- * @returns {?string} The normalized alias, or null when empty.
- */
-function normalizeAlias(value) {
-  if (value === undefined || value === null) return null;
-  let s = String(value).trim();
-  if (!s) return null;
-  if (!s.startsWith("/")) s = `/${s}`;
-  if (s.length > 1) s = s.replace(/\/+$/, "");
-  return s;
-}
-
 /**
  * Resolve the `path` attribute to send on an alias-aware node write so the alias
  * actually persists, and decide whether a rename redirect is needed.
@@ -57,6 +44,8 @@ function normalizeAlias(value) {
  *   run on create); `redirect` is `{ from, to, nid }` when a rename redirect is due.
  */
 async function resolvePathWrite({ backend, type, id, providedPath, isCreate }) {
+  // Always read the default revision + path_alias row. Aliases are not
+  // revisioned; a working-copy GET often omits pid on unpublished drafts (#274).
   const info = id
     ? await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}))
     : {};
@@ -132,6 +121,80 @@ async function createRenameRedirect(backend, sec, redirect) {
   }
 }
 
+/**
+ * Update the existing path_alias row in place when a node PATCH did not stick
+ * the intended alias (Pathauto regenerating on title save, missing pid on
+ * unpublished drafts).
+ * @param {object} backend
+ * @param {object} sec
+ * @param {{aliasId?: ?string}} info
+ * @param {string} intendedAlias
+ * @returns {Promise<{repaired: boolean, reason?: string}>}
+ */
+async function repairAliasViaPathAlias(backend, sec, info, intendedAlias) {
+  if (!info?.aliasId) return { repaired: false, reason: "no path_alias id to update" };
+  try {
+    assertWriteAllowed(sec, "update", PATH_ALIAS_ENTITY_TYPE, PATH_ALIAS_ENTITY_TYPE);
+  } catch {
+    return { repaired: false, reason: "path_alias update not permitted by policy" };
+  }
+  try {
+    await backend.updateEntity({
+      entityType: PATH_ALIAS_ENTITY_TYPE,
+      bundle: PATH_ALIAS_ENTITY_TYPE,
+      id: info.aliasId,
+      attributes: { alias: intendedAlias },
+    });
+    return { repaired: true };
+  } catch (err) {
+    return { repaired: false, reason: err?.message || String(err) };
+  }
+}
+
+/**
+ * Confirm the intended alias is what canonical / working-copy reads return.
+ * If the node PATCH drifted (Pathauto), restore the path_alias row and
+ * re-read. Still-wrong reads throw — never report success for a failed
+ * restoration (#274).
+ * @param {object} args
+ * @returns {Promise<object>} The entity to return (possibly a post-repair re-read).
+ */
+async function assertAliasPersisted({
+  backend, sec, type, id, intendedAlias, resourceVersion, written,
+}) {
+  const shown = normalizeAlias(written?.url);
+  if (shown === intendedAlias) return written;
+
+  const info = await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}));
+  if (normalizeAlias(info.alias) === intendedAlias && shown === null) {
+    // Re-read omitted url but the alias row matches; treat as persisted.
+    return written;
+  }
+
+  const repair = await repairAliasViaPathAlias(backend, sec, info, intendedAlias);
+  const fresh = await backend.getEntity({
+    entityType: "node", bundle: type, id,
+    ...(resourceVersion ? { resourceVersion } : {}),
+  }).catch(() => null);
+  const afterInfo = await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}));
+  const entityUrl = normalizeAlias(fresh?.url);
+  const aliasUrl = normalizeAlias(afterInfo.alias);
+  // The path_alias row is router-visible; the node's computed path field can
+  // lag. Persist if either re-read matches. Never return a drifted url.
+  if (entityUrl === intendedAlias || aliasUrl === intendedAlias) {
+    const entity = fresh ?? written;
+    if (normalizeAlias(entity?.url) === intendedAlias) return entity;
+    return { ...(entity && typeof entity === "object" ? entity : { id }), url: intendedAlias };
+  }
+  const reported = entityUrl || aliasUrl || shown || "(none)";
+  throw new Error(
+    `Alias restoration failed: requested "${intendedAlias}" but canonical ` +
+    `and working-copy reads still show "${reported}"` +
+    (repair.reason ? ` (${repair.reason})` : "") +
+    ". Update the path_alias entity directly. See connector #274."
+  );
+}
+
 /**
  * Build a Drupal body field descriptor from plain HTML + optional summary.
  *
@@ -176,12 +239,39 @@ function pageOf({ limit = 20, offset = 0 }) {
  * @param {object} args - { site?, type, id }.
  * @returns {Promise<object|null>} The redacted node, or null if not found.
  */
-async function getNode({ site: siteName, type, id }) {
+async function getNode({ site: siteName, type, id, langcode, resourceVersion }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
-  const entity = await backend.getEntity({ entityType: "node", bundle: type, id });
+  if (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 (workingRow && workingRow.status === false && 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 },
+      });
+      return omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
+    }
+    const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
+    if (!liveHas) {
+      return null;
+    }
+    if (targetLang !== inventory.defaultLangcode) {
+      const liveRow = (inventory.live.translations ?? []).find((row) => row.langcode === targetLang);
+      return {
+        id, entityType: "node", bundle: type, langcode: targetLang,
+        title: liveRow?.title ?? null,
+        status: liveRow?.status ?? null,
+        fields: { moderation_state: liveRow?.moderation_state },
+        _revisions: { live: inventory.live.vid, working: inventory.working?.vid ?? null },
+        note: "Published non-default translations are listed on the live revision; full field reads of an unpublished working translation use langcode against the working draft.",
+      };
+    }
+  }
+  const entity = await backend.getEntity({ entityType: "node", bundle: type, id, resourceVersion });
   return entity ? redactCanonicalEntity(entity, sec, "node") : null;
 }
 
@@ -310,13 +400,14 @@ async function createNode({ site: siteName, type, title, body, summary, format,
  * @param {object} args - { site?, type, id, title?, body?, summary?, format?, status?, moderationState?, fields?, relationships? }.
  * @returns {Promise<object>} The updated node descriptor.
  */
-async function updateNode({ site: siteName, type, id, title, body, summary, format, status, moderationState, fields = {}, relationships = {}, dryRun = false, returning = "full" }) {
+async function updateNode({ site: siteName, type, id, title, body, summary, format, status, moderationState, langcode, fields = {}, relationships = {}, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "node", type);
   const backend = await resolveBackend(site);
   const summaryWrite = await assertBodySummaryWritable(backend, type, summary);
   let attributes = { ...fields };
+  delete attributes.langcode;
   if (title !== undefined) attributes.title = title;
   if (moderationState !== undefined) attributes.moderation_state = moderationState;
   else if (status !== undefined) attributes.status = status;
@@ -348,6 +439,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   // governed continuation endpoint; stray revisions still fail the probe.
   const patchTarget = await prepareGuardedPatch(backend, {
     entityType: "node", bundle: type, id, existing, attributes, relationships: resolvedRelationships,
+    langcode,
   });
   if (dryRun) {
     const preview = {
@@ -365,19 +457,28 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   else attributes.path = pathAttr;
   const patched = await updateEntityGuarded(backend, {
     entityType: "node", bundle: type, id, attributes, relationships: resolvedRelationships,
+    ...(langcode ? { langcode } : {}),
     ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
     ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
   });
-  const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
   // #169: when relationships were sent, the canonical re-read is the published
   // revision and is not proof an ERR field landed. Prefer rel:working-copy.
-  const fresh = await readWrittenRevision({
+  let fresh = await readWrittenRevision({
     backend, entityType: "node", bundle: type, id,
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
     patchResult: patched,
     preferCanonical: true,
     resourceVersion: patchTarget.resourceVersion,
   });
+  const intendedAlias = pathAttr?.alias ? normalizeAlias(pathAttr.alias) : null;
+  if (intendedAlias) {
+    fresh = await assertAliasPersisted({
+      backend, sec, type, id, intendedAlias,
+      resourceVersion: patchTarget.resourceVersion, written: fresh,
+    });
+  }
+  // Redirect only after the new alias is what re-reads show (#274).
+  const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
   const withRevs = await attachWrittenRevisionPair({
     backend, entityType: "node", bundle: type, id, entity: fresh, liveVid: patchTarget.liveVid,
   });
@@ -414,13 +515,14 @@ async function deleteNode({ site: siteName, type, id, dryRun = false }) {
 export const definitions = [
   {
     name: "drupal_get_node",
-    description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes.",
+    description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English).",
     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" },
+        langcode: { type: "string", description: "Target language (e.g. 'es') to read the unpublished working translation instead of the default language." },
       },
     },
   },
@@ -477,7 +579,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. 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. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that 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.",
+    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. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that 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.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -490,9 +592,10 @@ export const definitions = [
         format:  { type: "string", description: "Text format machine name for the body, e.g. 'basic_html'. When the body field's allowed_formats lists exactly one format, that is the default. A caller format outside that list is refused before write. When allowed_formats cannot be resolved, defaults to the site config's `defaultTextFormat`, then 'full_html'." },
         status:  { type: "boolean", description: "Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set." },
         moderationState: { type: "string", description: "Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status. Required to keep or re-publish a live node — omitting it on a published moderated node defaults the write to 'draft'." },
+        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." },
-        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun." },
+        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, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. 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." },
         returning: RETURNING_SCHEMA,
       },
     },

package/src/tools/paragraphs.js

@@ -42,6 +42,11 @@ import {
 import {
   embedParagraphRef, paragraphRevisionId, resolveParagraphRevisionId, missingParagraphRevisionError,
 } from "../lib/err-relationships.js";
+import {
+  assertDraftLangcode,
+  readDraftTranslation,
+  writeDraft,
+} from "../lib/draft-write.js";
 
 /**
  * Build the resource-identifier ref used to embed a paragraph in a host ERR /
@@ -111,17 +116,32 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
  * @throws {Error} If id is missing or the revision id cannot be read.
  * @throws {SecurityError} If updating paragraphs of this bundle is not permitted.
  */
-async function updateParagraph({ site: siteName, paragraphType, id, attributes = {} }) {
+async function updateParagraph({ site: siteName, paragraphType, id, attributes = {}, langcode, revisionId, draftState }) {
   if (!id) throw new Error("A paragraph 'id' (UUID) is required to update an existing paragraph.");
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "paragraph", paragraphType);
   const backend = await resolveBackend(site);
-  const paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
+  let paragraph;
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const pinned = revisionId ?? paragraphRevisionId(
+      await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id }),
+    );
+    if (pinned === null || pinned === undefined || pinned === "") {
+      throw new Error("Paragraph translation update requires a paragraph revision ID (the host pin).");
+    }
+    paragraph = await writeDraft(backend, {
+      entityType: "paragraph", bundle: paragraphType, id, attributes, langcode: targetLang, draftState,
+      draftRevision: { revisionId: pinned },
+    });
+  } else {
+    paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
+  }
   const bundle = paragraph.bundle || paragraphType;
-  const revisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
-  if (revisionId === null) throw missingParagraphRevisionError(id, "Updated");
-  const ref = embedRef(bundle, paragraph.id, revisionId);
+  const resolvedRevisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
+  if (resolvedRevisionId === null) throw missingParagraphRevisionError(id, "Updated");
+  const ref = embedRef(bundle, paragraph.id, resolvedRevisionId);
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
@@ -134,16 +154,31 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
  *   The redacted paragraph with an embedding `ref`, or null if not found.
  * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
  */
-async function getParagraph({ site: siteName, paragraphType, id }) {
+async function getParagraph({ site: siteName, paragraphType, id, langcode, revisionId }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "paragraph", paragraphType);
   const backend = await resolveBackend(site);
-  const entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
+  let entity;
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const pinned = revisionId ?? paragraphRevisionId(
+      await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id }),
+    );
+    if (pinned === null || pinned === undefined || pinned === "") {
+      throw new Error("Paragraph translation read requires a paragraph revision ID (the host pin).");
+    }
+    entity = await readDraftTranslation(backend, {
+      entityType: "paragraph", bundle: paragraphType, id, langcode: targetLang,
+      draftRevision: { revisionId: pinned },
+    });
+  } else {
+    entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
+  }
   if (!entity) return null;
   const redacted = redactCanonicalEntity(entity, sec, "paragraph");
-  const revisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted);
-  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, revisionId) };
+  const resolvedRevisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted) ?? revisionId;
+  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, resolvedRevisionId) };
 }
 
 // ---------------------------------------------------------------------------
@@ -167,7 +202,7 @@ export const definitions = [
   {
     name: "drupal_update_paragraph",
     description:
-      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
+      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Pass langcode to continue an unpublished paragraph translation via Sentinel (the host pin, not a live English mutation). Omitting langcode still uses canonical JSON:API and remains gated on published-host children. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
@@ -175,19 +210,24 @@ export const definitions = [
         paragraphType: { type: "string", description: "Paragraph type / bundle machine name, e.g. 'text', 'image', 'cta'" },
         id:            { type: "string", description: "Paragraph UUID" },
         attributes:    { type: "object", description: "Paragraph field values to change, keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }" },
+        langcode:      { type: "string", description: "Target language for an unpublished paragraph translation (e.g. 'es'). Continues Sentinel /mcp-draft; does not create a missing translation." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins. Required when that pin is not the default revision." },
+        draftState:    { type: "string", pattern: "^[a-f0-9]{64}$", description: "Required with langcode. Opaque draftState from the previous paragraph draft read/create/update; prevents overwriting newer edits." },
       },
     },
   },
   {
     name: "drupal_get_paragraph",
     description:
-      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
+      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
         site:          { type: "string" },
         paragraphType: { type: "string", description: "Paragraph type / bundle machine name" },
         id:            { type: "string", description: "Paragraph UUID" },
+        langcode:      { type: "string", description: "Target language for the unpublished working translation (e.g. 'es')." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins." },
       },
     },
   },