drupal-mcp-connector 2.14.2 → 2.15.1

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.
@@ -305,6 +383,25 @@ export async function prepareGuardedPatch(backend, {
   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(
@@ -313,23 +410,35 @@ export async function prepareGuardedPatch(backend, {
       );
     }
     target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
-    await writeDraft(backend, {
-      entityType, bundle, id, attributes, relationships, langcode,
-      draftRevision: target.draftRevision,
-    }, true);
+    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;
 }
 
@@ -350,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

@@ -294,7 +294,7 @@ export const definitions = [
         langcode:      { type: "string", description: "Target language for an unpublished working translation (nodes). Continues that translation via Sentinel." },
         attributes:    { type: "object" },
         relationships: { type: "object" },
-        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, 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,7 +14,7 @@ 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";
@@ -22,25 +22,11 @@ import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } f
 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.
@@ -58,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(() => ({}))
     : {};
@@ -133,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.
  *
@@ -191,7 +253,7 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
         entityType: "node", bundle: type, id, langcode: targetLang,
         draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
       });
-      return redactCanonicalEntity(entity, sec, "node");
+      return omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
     }
     const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
     if (!liveHas) {
@@ -218,8 +280,9 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
  *
  * @param {object} args - { site?, type, status?, filters?, limit?, offset?, sort? }.
  *   A `status` boolean is appended to `filters` as a status equality descriptor.
- * @returns {Promise<{total: number, approximate: boolean, offset: number,
- *   nextOffset: number, nodes: object[]}>} Paged, redacted node list.
+ * @returns {Promise<{total: number, approximate: boolean, truncated: boolean,
+ *   offset: number, nextOffset: number, hasNext: boolean, nodes: object[]}>}
+ *   Paged, redacted node list. `hasNext` is the backend's `links.next` signal.
  */
 async function listNodes({ site: siteName, type, status, filters = [], limit = 20, offset = 0, sort = [{ field: "changed", dir: "desc" }] }) {
   const site = getSiteConfig(siteName);
@@ -233,8 +296,10 @@ async function listNodes({ site: siteName, type, status, filters = [], limit = 2
   return {
     total: res.page?.total ?? nodes.length,
     approximate: res.approximate ?? false,
+    truncated: res.truncated ?? false,
     offset,
     nextOffset: offset + nodes.length,
+    hasNext: Boolean(res.page?.hasNext),
     nodes,
   };
 }
@@ -399,16 +464,24 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
     ...(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,
   });
@@ -458,7 +531,7 @@ export const definitions = [
   },
   {
     name: "drupal_list_nodes",
-    description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors.",
+    description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set.",
     inputSchema: {
       type: "object", required: ["type"],
       properties: {
@@ -524,8 +597,8 @@ export const definitions = [
         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,39 +116,136 @@ 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 };
 }
 
+/**
+ * JSON:API `resourceVersion` selector for a paragraph host pin.
+ * Accepts a numeric vid, a numeric string, or an explicit `id:<vid>`.
+ * @param {string|number} revisionId Host pin / paragraph revision id.
+ * @returns {string} e.g. `id:6654`.
+ * @throws {Error} If the value is not a usable revision id.
+ */
+export function paragraphResourceVersion(revisionId) {
+  if (typeof revisionId === "number" && Number.isFinite(revisionId) && revisionId > 0) {
+    return `id:${revisionId}`;
+  }
+  if (typeof revisionId === "string" && revisionId.length) {
+    if (/^id:[1-9]\d*$/.test(revisionId)) return revisionId;
+    if (/^[1-9]\d*$/.test(revisionId)) return `id:${revisionId}`;
+  }
+  throw new Error(
+    `Invalid paragraph revisionId "${revisionId}". Use a numeric vid (the host pin).`,
+  );
+}
+
+/**
+ * Numeric vid from a host pin (`6654` or `id:6654`).
+ * @param {string|number} revisionId
+ * @returns {?number}
+ */
+function requestedParagraphVid(revisionId) {
+  const raw = String(revisionId).replace(/^id:/, "");
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * Fail closed when a requested paragraph revision was not the one served.
+ * Silent substitution of the default revision is the defect this guards (#292).
+ * @param {?object} entity Canonical paragraph, or null if the read missed.
+ * @param {string|number} requested Host pin that was asked for.
+ * @param {string} id Paragraph UUID.
+ * @returns {object} `entity` when the served vid matches.
+ * @throws {Error} On a miss or a mismatched vid.
+ */
+function requireServedParagraphRevision(entity, requested, id) {
+  const wanted = requestedParagraphVid(requested);
+  const served = paragraphRevisionId(entity);
+  if (!entity || wanted === null || served === null || served !== wanted) {
+    const got = !entity || served === null ? "no revision" : String(served);
+    throw new Error(
+      `Requested paragraph revision ${wanted ?? requested} for ${id} but the backend served ${got}. ` +
+      "Refusing to substitute a different revision.",
+    );
+  }
+  return entity;
+}
+
 /**
  * Fetch a single paragraph by bundle + UUID, redacted per the site policy, and
  * annotate it with the embedding ref (including `meta.target_revision_id`).
  *
- * @param {object} args - { site?, paragraphType, id }.
+ * When `revisionId` is set (the host's `meta.target_revision_id`), the read
+ * addresses that revision via JSON:API `?resourceVersion=id:<vid>` and errors
+ * if Drupal serves a different vid. Omitting `revisionId` still reads the
+ * default revision.
+ *
+ * @param {object} args - { site?, paragraphType, id, langcode?, revisionId? }.
  * @returns {Promise<(object & {ref: object})|null>}
- *   The redacted paragraph with an embedding `ref`, or null if not found.
+ *   The redacted paragraph with an embedding `ref`, or null if not found and
+ *   no `revisionId` was requested.
  * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
+ * @throws {Error} If a requested `revisionId` cannot be served.
  */
-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 });
+  const pinRequested = revisionId !== undefined && revisionId !== null && revisionId !== "";
+  let entity;
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const pinned = pinRequested ? 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 if (pinRequested) {
+    const resourceVersion = paragraphResourceVersion(revisionId);
+    entity = await backend.getEntity({
+      entityType: "paragraph", bundle: paragraphType, id, resourceVersion,
+    });
+    requireServedParagraphRevision(entity, revisionId, id);
+  } 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);
+  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, resolvedRevisionId) };
 }
 
 // ---------------------------------------------------------------------------
@@ -167,7 +269,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 +277,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 revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. 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 (ERR meta.target_revision_id). Honored on the read; a different served vid is an error." },
       },
     },
   },

package/src/tools/revisions.js

@@ -24,6 +24,7 @@ import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
 import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
+import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 
 // Attributes that describe the entity's identity / revision bookkeeping / paths.
 // These are read-only or server-managed and must NOT be replayed on a revert.
@@ -223,7 +224,7 @@ async function getRevision({ site: siteName, type, id, version, langcode }) {
       entityType: "node", bundle: type, id, langcode: targetLang,
       draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
     });
-    const redacted = redactCanonicalEntity(entity, sec, "node");
+    const redacted = omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
     return {
       entityType: "node",
       bundle: type,