drupal-mcp-connector 2.15.1 → 2.15.2

package/.agents/commands/drupal-list-revisions.md

@@ -1,11 +1,11 @@
 ---
-description: "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge."
+description: "Surface the latest default and working node revisions. When the core working-copy alias is absent or echoes live, consult Sentinel translation inventory; workingCopy then includes source and language-specific translations instead of a misleading aggregate status. Continue an unpublished translation with explicit langcode. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge."
 argument-hint: "<type> <id> [site]"
 ---
 
 Call the MCP tool `drupal_list_revisions`.
 
-Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.
+Surface the latest default and working node revisions. When the core working-copy alias is absent or echoes live, consult Sentinel translation inventory; workingCopy then includes source and language-specific translations instead of a misleading aggregate status. Continue an unpublished translation with explicit langcode. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.
 
 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. 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. 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."
 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. 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.
+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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.2] - 2026-09-11
+
+### Fixed
+- **Discover and continue translation-only forward revisions (#297).** When core's
+  working-copy alias is absent or echoes live, node revision listing and guarded
+  updates consult Sentinel's translation inventory. Existing unpublished languages
+  continue through the governed endpoint with explicit language and live/working
+  preconditions. Published languages and ambiguous multilingual edits remain refused.
+  Permission and transport failures stop discovery rather than becoming “no draft”.
+  Update responses preserve the saved translation instead of replacing it with live
+  English. An unresolved revision conflict no longer prescribes revision surgery.
+
 ## [2.15.1] - 2026-09-10
 
 ### Fixed
@@ -1571,6 +1583,7 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.15.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.2
 [2.15.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.1
 [2.15.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.0
 [2.14.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.15.1",
+  "version": "2.15.2",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/node-draft-inventory.js

@@ -0,0 +1,47 @@
+/** Sentinel discovery for translation-only node revisions (#297). */
+import { readTranslationInventory } from "./draft-write.js";
+
+/**
+ * Read optional inventory, falling back only when the endpoint is unsupported.
+ * Permission, transport and malformed-response failures are not absence.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string}} ref
+ * @returns {Promise<object|null>}
+ */
+export async function readNodeDraftInventory(backend, ref) {
+  if (ref.entityType !== "node" || typeof backend.rawQuery !== "function"
+    || typeof backend.resourcePath !== "function") return null;
+  let inventory;
+  try {
+    inventory = await readTranslationInventory(backend, ref);
+  } catch (error) {
+    if (/does not provide Sentinel's governed draft-translation endpoint/.test(error.message)) return null;
+    throw error;
+  }
+  const validVid = (vid) => /^[1-9]\d*$/.test(String(vid ?? "")) && Number.isSafeInteger(Number(vid));
+  if (!validVid(inventory.live?.vid)
+    || (inventory.working && (!validVid(inventory.working.vid)
+      || !Array.isArray(inventory.working.translations)
+      || inventory.working.translations.some((row) => !row || typeof row.langcode !== "string"
+        || typeof row.status !== "boolean")))) {
+    throw new Error("Sentinel returned an invalid node revision inventory. Re-read before updating.");
+  }
+  return inventory;
+}
+
+/**
+ * Ensure inventory discovery does not turn a published language into a draft.
+ * Sentinel still validates the revision pair and language on every request.
+ * @param {object} inventory
+ * @param {string|undefined} langcode
+ */
+export function assertInventoryDraftLanguage(inventory, langcode) {
+  const rows = inventory.working?.translations ?? [];
+  if (!langcode && rows.length !== 1) {
+    throw new Error("This working revision contains translations. Pass an explicit langcode for an existing unpublished language; no draft was created.");
+  }
+  const row = langcode ? rows.find((item) => item.langcode === langcode) : rows[0];
+  if (!row || row.status !== false) {
+    throw new Error("The requested language is not an existing unpublished working draft. Published languages and other drafts were left unchanged.");
+  }
+}

package/src/lib/patch-preflight.js

@@ -16,8 +16,8 @@
  *   Sentinel's /mcp-draft endpoint with verified live/working revision IDs.
  *   Core rejects resourceVersion on PATCH. Never retry the canonical URL.
  * - **#201** — the working-copy alias does not resolve, but core still
- *   blocks. That is a stray revision row. Refuse with revision-surgery
- *   language. `workingCopy: null` is not proof the node is writable.
+ *   blocks. Consult Sentinel inventory for translation-only revisions before
+ *   refusing the unresolved revision conflict. `workingCopy: null` is not proof the node is writable.
  *
  * Unsupported endpoints and stale revisions fail closed, without discard.
  */
@@ -25,6 +25,7 @@
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
 import { entityRevisionId } from "./write-revision.js";
 import { writeDraft } from "./draft-write.js";
+import { readNodeDraftInventory, assertInventoryDraftLanguage } from "./node-draft-inventory.js";
 
 /** Stable error code for a core working-copy / not-latest-revision block. */
 export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
@@ -48,7 +49,7 @@ export const PATCH_BLOCKED_MESSAGE =
   "This entity cannot be updated over JSON:API because the stored entity is not " +
   "the latest revision (Drupal core #2795279). The JSON:API aliases " +
   "rel:latest-version and rel:working-copy cannot show the blocking row. " +
-  "Clearing it requires revision surgery outside JSON:API (Drush / the entity API). " +
+  "Inspect the translation inventory and revision history before considering repair; do not delete drafts. " +
   "See connector #201. Do not retry the same canonical PATCH.";
 
 /**
@@ -248,17 +249,32 @@ export async function loadWorkingCopy(backend, { entityType, bundle, id }) {
  */
 export async function resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing }) {
   const workingCopy = await loadWorkingCopy(backend, { entityType, bundle, id });
+  if (workingCopy?.id && workingCopy.id !== id) {
+    throw new PatchTargetAmbiguousError(id, workingCopy.id);
+  }
   let liveVid = entityRevisionId(existing);
   if (workingCopy && (liveVid === null || liveVid === undefined) && typeof backend?.getEntity === "function") {
     const live = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
     liveVid = entityRevisionId(live);
   }
+  const aliasVid = entityRevisionId(workingCopy);
+  if (!workingCopy || (liveVid !== null && String(aliasVid) === String(liveVid))) {
+    const inventory = await readNodeDraftInventory(backend, { entityType, bundle, id });
+    if (inventory) {
+      if (liveVid !== null && String(liveVid) !== String(inventory.live.vid)) {
+        throw new WorkingCopyStaleError(new Error("Sentinel's live revision changed during discovery."));
+      }
+      liveVid = Number(inventory.live.vid);
+      const workingVid = inventory.working ? Number(inventory.working.vid) : null;
+      if (workingVid !== null && workingVid !== liveVid) {
+        return { resourceVersion: `id:${workingVid}`, workingCopy: null,
+          liveVid, workingVid, inventory };
+      }
+    }
+  }
   if (!workingCopy) {
     return { resourceVersion: undefined, workingCopy: null, liveVid, workingVid: null };
   }
-  if (workingCopy.id && workingCopy.id !== id) {
-    throw new PatchTargetAmbiguousError(id, workingCopy.id);
-  }
   const workingVid = entityRevisionId(workingCopy);
   if (workingVid !== null && liveVid !== null && String(workingVid) === String(liveVid)) {
     return { resourceVersion: undefined, workingCopy, liveVid, workingVid };
@@ -402,6 +418,7 @@ export async function prepareGuardedPatch(backend, {
       throw new StaleCopyError();
     }
   }
+  if (target.inventory) assertInventoryDraftLanguage(target.inventory, langcode);
   if (langcode) {
     if (!target.workingVid || !target.liveVid || String(target.workingVid) === String(target.liveVid)) {
       throw new Error(

package/src/lib/write-revision.js

@@ -65,7 +65,10 @@ export async function attachWrittenRevisionPair({
   backend, entityType, bundle, id, entity, liveVid,
 }) {
   if (liveVid === null || liveVid === undefined || !entity) return entity;
-  let workingVid = null;
+  let workingVid = entityRevisionId(entity);
+  if (workingVid !== null && String(workingVid) !== String(liveVid)) {
+    return attachRevisionPair(entity, { live: liveVid, working: workingVid });
+  }
   if (typeof backend?.getEntity === "function") {
     try {
       const wc = await backend.getEntity({
@@ -93,12 +96,16 @@ export async function attachWrittenRevisionPair({
  *   for the write (e.g. `rel:working-copy`). PreferCanonical re-reads this
  *   resource instead of the default revision so a draft PATCH is not
  *   replaced by the live body.
+ * @param {?string} [args.langcode] Language returned by governed draft continuation.
  * @returns {Promise<object>} Entity to return, with `_revision` when relevant.
  */
 export async function readWrittenRevision({
   backend, entityType, bundle, id, relationshipsSent, patchResult = null, preferCanonical = false,
-  resourceVersion,
+  resourceVersion, langcode,
 }) {
+  // Sentinel returned the requested translation; a canonical read would replace
+  // it with live English, and the core working-copy alias may not address it.
+  if (langcode && patchResult) return patchResult;
   if (!relationshipsSent) {
     if (preferCanonical && typeof backend.getEntity === "function") {
       const fresh = await backend.getEntity({

package/src/tools/entities.js

@@ -136,6 +136,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   const written = await readWrittenRevision({
     backend, entityType, bundle, id,
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
+    langcode,
     patchResult: result,
     preferCanonical: false,
   });

package/src/tools/nodes.js

@@ -469,16 +469,18 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   let fresh = await readWrittenRevision({
     backend, entityType: "node", bundle: type, id,
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
+    langcode,
     patchResult: patched,
     preferCanonical: true,
     resourceVersion: patchTarget.resourceVersion,
   });
   const intendedAlias = pathAttr?.alias ? normalizeAlias(pathAttr.alias) : null;
   if (intendedAlias) {
-    fresh = await assertAliasPersisted({
+    const aliasChecked = await assertAliasPersisted({
       backend, sec, type, id, intendedAlias,
       resourceVersion: patchTarget.resourceVersion, written: fresh,
     });
+    fresh = langcode ? { ...fresh, url: aliasChecked.url } : aliasChecked;
   }
   // Redirect only after the new alias is what re-reads show (#274).
   const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
@@ -582,7 +584,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. 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. 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.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {

package/src/tools/revisions.js

@@ -23,6 +23,7 @@ import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
+import { readNodeDraftInventory } from "../lib/node-draft-inventory.js";
 import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
 import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 
@@ -177,13 +178,28 @@ async function listRevisions({ site: siteName, type, id }) {
 
   // The working-copy alias only resolves on entities under a content_moderation
   // workflow with a pending forward revision; absence is expected, not an error.
-  const workingCopy = await fetchRevisionResource(backend, "node", type, id, "rel:working-copy")
+  let workingCopy = await fetchRevisionResource(backend, "node", type, id, "rel:working-copy")
     .then(summarizeRevision)
     .catch(() => null);
 
+  if (!workingCopy || String(workingCopy.vid) === String(latestVersion?.vid)) {
+    const inventory = await readNodeDraftInventory(backend, { entityType: "node", bundle: type, id });
+    if (inventory?.working && String(inventory.working.vid) !== String(inventory.live.vid)) {
+      if (latestVersion && String(latestVersion.vid) !== String(inventory.live.vid)) {
+        throw new Error("The live revision changed during discovery. Re-read the revision inventory.");
+      }
+      // No aggregate publication flag: English may be published while Spanish is draft.
+      workingCopy = { vid: Number(inventory.working.vid), source: "sentinel-inventory",
+        translations: inventory.working.translations.map(({ langcode, status, moderation_state, default: isDefault }) => ({
+          langcode, status, moderation_state, default: isDefault,
+        })) };
+    }
+  }
+
   const possiblyPatchBlocked = Boolean(latestVersion && changedAheadOfRevision(latestVersion));
   let note = LIST_REVISIONS_BASE_NOTE;
   if (!workingCopy) note += LIST_REVISIONS_NULL_WC_NOTE;
+  if (workingCopy?.source === "sentinel-inventory") note += " Working revision discovered through Sentinel; publication state is language-specific. Continue an unpublished translation with explicit langcode.";
   if (possiblyPatchBlocked) note += LIST_REVISIONS_FINGERPRINT_NOTE;
 
   return {
@@ -332,7 +348,7 @@ export const definitions = [
   {
     name: "drupal_list_revisions",
     description:
-      "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.",
+      "Surface the latest default and working node revisions. When the core working-copy alias is absent or echoes live, consult Sentinel translation inventory; workingCopy then includes source and language-specific translations instead of a misleading aggregate status. Continue an unpublished translation with explicit langcode. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {