drupal-mcp-connector 3.1.0 → 3.2.0

package/src/lib/operations.js

@@ -18,7 +18,7 @@ const WRITE_PREFIXES = ["drupal_create_", "drupal_update_", "drupal_upload_",
   "drupal_drush_updatedb", "drupal_drush_module_enable",
   "drupal_drush_module_disable", "drupal_drush_user_create",
   // v1.0 feature tools that perform writes but don't start with create_/update_:
-  "drupal_bulk_", "drupal_revert_", "drupal_schedule_", "drupal_set_",
+  "drupal_bulk_", "drupal_revert_", "drupal_schedule_", "drupal_set_", "drupal_draft_",
   // Governed config write (also gated inside the handler by the config-write cap):
   "drupal_config_set"];
 

package/src/lib/patch-preflight.js

@@ -24,6 +24,12 @@
 
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
 import { entityRevisionId } from "./write-revision.js";
+import {
+  isCanonicalDraftType,
+  preflightGovernedCanonicalDraft,
+  resolveCanonicalDraftIdentity,
+  writeCanonicalModeratedEntity,
+} from "./canonical-draft.js";
 import { httpStatusOf } from "./error-status.js";
 import {
   writeDraft,
@@ -245,6 +251,20 @@ export async function loadWorkingCopy(backend, { entityType, bundle, id }) {
  * @throws {PatchTargetAmbiguousError}
  */
 export async function resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing }) {
+  if (isCanonicalDraftType(entityType)) {
+    // A readable unmoderated block or library item has no draft alias to
+    // prove. Identity resolution stays fail-closed when the entity is
+    // moderated or could not be read.
+    if (existing && !entityLooksModerated(existing)) {
+      return {
+        resourceVersion: undefined,
+        workingCopy: null,
+        liveVid: entityRevisionId(existing, entityType),
+        workingVid: null,
+      };
+    }
+    return resolveCanonicalDraftIdentity(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);
@@ -478,6 +498,17 @@ export async function prepareGuardedPatch(backend, {
     target.preflight = PREFLIGHT_SENTINEL_DRAFT;
     return target;
   }
+  if (target.governedDraft) {
+    try {
+      await preflightGovernedCanonicalDraft(backend, {
+        entityType, bundle, id, attributes, relationships, governedDraft: target.governedDraft,
+      });
+    } catch (err) {
+      throw rewriteStaleCopyError(err);
+    }
+    target.preflight = PREFLIGHT_SENTINEL_DRAFT;
+    return target;
+  }
   if (target.resourceVersion) {
     const draftRevisionFor = (lang) => ({
       liveVid: target.liveVid,
@@ -584,6 +615,9 @@ function explainDefaultLanguageRefusal(err, inferredLangcode) {
  * @throws {PatchBlockedError|WorkingCopyStaleError|*}
  */
 export async function updateEntityGuarded(backend, input) {
+  if (isCanonicalDraftType(input?.entityType) && !input?.draftRevision && !input?.resourceVersion) {
+    return writeCanonicalModeratedEntity(backend, input);
+  }
   try {
     if (input?.draftRevision) return await writeDraft(backend, input);
     if (input?.resourceVersion) {

package/src/lib/write-revision.js

@@ -11,27 +11,73 @@
  */
 
 /**
- * Read a revision id off a canonical (or raw-ish) entity body.
- * @param {?object} entity
+ * JSON:API revision attribute for entity types whose revision key is known.
+ * `taxonomy_term`'s `drupal_internal__vid` is the vocabulary id, not a revision.
+ * Node and media revisions use `vid`. Paragraphs, library items, and custom
+ * blocks use `revision_id`.
+ */
+const REVISION_ATTRIBUTE = {
+  node: "drupal_internal__vid",
+  media: "drupal_internal__vid",
+  paragraph: "drupal_internal__revision_id",
+  paragraphs_library_item: "drupal_internal__revision_id",
+  block_content: "drupal_internal__revision_id",
+};
+
+/**
+ * @param {object} entity
+ * @param {object} fields
+ * @param {object} attrs
+ * @param {string} key
+ * @returns {unknown}
+ */
+function readRevisionAttribute(entity, fields, attrs, key) {
+  if (key === "drupal_internal__vid") {
+    return entity.vid
+      ?? fields.drupal_internal__vid
+      ?? attrs.drupal_internal__vid
+      ?? entity.drupal_internal__vid;
+  }
+  if (Object.prototype.hasOwnProperty.call(fields, key)) return fields[key];
+  if (Object.prototype.hasOwnProperty.call(attrs, key)) return attrs[key];
+  if (Object.prototype.hasOwnProperty.call(entity, key)) return entity[key];
+  return undefined;
+}
+
+/**
+ * @param {unknown} raw
  * @returns {?number|string}
  */
-export function entityRevisionId(entity) {
-  if (!entity || typeof entity !== "object") return null;
-  const fields = entity.fields && typeof entity.fields === "object"
-    ? entity.fields
-    : {};
-  const attrs = entity.attributes && typeof entity.attributes === "object"
-    ? entity.attributes
-    : {};
-  const raw = entity.vid
-    ?? fields.drupal_internal__vid
-    ?? attrs.drupal_internal__vid
-    ?? entity.drupal_internal__vid;
+function normalizeRevisionId(raw) {
   if (raw === undefined || raw === null || raw === "") return null;
   const n = Number(raw);
   return Number.isFinite(n) ? n : raw;
 }
 
+/**
+ * Read a revision id off a canonical (or raw-ish) entity body.
+ * When `entityType` is known, only that type's revision attribute is read.
+ * When it is omitted, a node-style vid is kept and `revision_id` is used
+ * only if no vid is present, so existing callers stay unchanged.
+ *
+ * @param {?object} entity
+ * @param {?string} [entityType]
+ * @returns {?number|string}
+ */
+export function entityRevisionId(entity, entityType) {
+  if (!entity || typeof entity !== "object") return null;
+  const type = entityType || entity.entityType || null;
+  const fields = entity.fields && typeof entity.fields === "object" ? entity.fields : {};
+  const attrs = entity.attributes && typeof entity.attributes === "object" ? entity.attributes : {};
+  if (type === "taxonomy_term") return null;
+  if (type && REVISION_ATTRIBUTE[type]) {
+    return normalizeRevisionId(readRevisionAttribute(entity, fields, attrs, REVISION_ATTRIBUTE[type]));
+  }
+  const vid = readRevisionAttribute(entity, fields, attrs, "drupal_internal__vid");
+  if (vid !== undefined && vid !== null && vid !== "") return normalizeRevisionId(vid);
+  return normalizeRevisionId(readRevisionAttribute(entity, fields, attrs, "drupal_internal__revision_id"));
+}
+
 /**
  * Attach distinct live vs working revision ids when both are known.
  * Does not invent vids.
@@ -65,7 +111,8 @@ export async function attachWrittenRevisionPair({
   backend, entityType, bundle, id, entity, liveVid,
 }) {
   if (liveVid === null || liveVid === undefined || !entity) return entity;
-  let workingVid = entityRevisionId(entity);
+  if (entity._revisions) return entity;
+  let workingVid = entityRevisionId(entity, entityType);
   if (workingVid !== null && String(workingVid) !== String(liveVid)) {
     return attachRevisionPair(entity, { live: liveVid, working: workingVid });
   }
@@ -74,7 +121,7 @@ export async function attachWrittenRevisionPair({
       const wc = await backend.getEntity({
         entityType, bundle, id, resourceVersion: "rel:working-copy",
       });
-      workingVid = entityRevisionId(wc);
+      workingVid = entityRevisionId(wc, entityType);
     } catch {
       workingVid = null;
     }
@@ -106,6 +153,9 @@ export async function readWrittenRevision({
   // 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 (patchResult?._revision?.source === "working-copy" || patchResult?._revision?.source === "latest-version") {
+    return patchResult;
+  }
   if (!relationshipsSent) {
     if (preferCanonical && typeof backend.getEntity === "function") {
       const fresh = await backend.getEntity({

package/src/tools/bulk.js

@@ -14,7 +14,8 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertWriteAllowed, assertPublishAllowed, withUnpublishedDefault } from "../lib/security.js";
-import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
+import { applySafeDraftDefault } from "../lib/moderation-default.js";
+import { readUpdateTarget } from "../lib/canonical-draft.js";
 import {
   resolveErrRelationships, embedParagraphRef,
   resolveParagraphRevisionId, missingParagraphRevisionError,
@@ -103,14 +104,9 @@ async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
     const item = rawItem || {};
     try {
       if (!item.id) throw new Error("Missing 'id' for update item");
-      let existing = null;
-      if (!hasExplicitModerationState(item.attributes ?? {})) {
-        try {
-          existing = (await backend.getEntity({ entityType, bundle, id: item.id })) ?? null;
-        } catch {
-          existing = null;
-        }
-      }
+      const existing = await readUpdateTarget(backend, {
+        entityType, bundle, id: item.id, attributes: item.attributes ?? {},
+      });
       const attributes = await applySafeDraftDefault({
         backend, entityType, bundle, id: item.id,
         attributes: item.attributes ?? {},

package/src/tools/entities.js

@@ -11,13 +11,14 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
-import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
+import { applySafeDraftDefault } from "../lib/moderation-default.js";
 import {
   resolveErrRelationships, relationshipsWereSent, embedParagraphRef,
   resolveParagraphRevisionId, missingParagraphRevisionError,
 } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { readUpdateTarget } from "../lib/canonical-draft.js";
 import { dryRunChecks, PREFLIGHT_NONE } from "../lib/dry-run-checks.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
@@ -111,14 +112,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   // One pre-write read serves both the #131 draft default and the #171
   // unrequested-status-change flag. Skipped when the caller pinned the
   // moderation state explicitly (same condition the draft default uses).
-  let existing = null;
-  if (!hasExplicitModerationState(attributes)) {
-    try {
-      existing = (await backend.getEntity({ entityType, bundle, id })) ?? null;
-    } catch {
-      existing = null; // Unreadable target: server-side gates stay authoritative.
-    }
-  }
+  const existing = await readUpdateTarget(backend, { entityType, bundle, id, attributes });
   const safeAttributes = await applySafeDraftDefault({
     backend, entityType, bundle, id, attributes, existingEntity: existing,
   });
@@ -297,7 +291,7 @@ export const definitions = [
   },
   {
     name: "drupal_entity_update",
-    description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change. Published moderated targets without an explicit attributes.moderation_state default to moderation_state 'draft' (forward revision). Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved. On moderated targets a non-saving PATCH preflight runs first (including 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); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran.",
+    description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change. Published moderated targets without an explicit attributes.moderation_state default to moderation_state 'draft' (forward revision). Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved. On moderated targets a non-saving PATCH preflight runs first (including 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); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran. When the draft inventory advertises open_draft, a published moderated paragraphs_library_item or block_content opens and continues through /mcp-draft with If-Match live or live:working, no mcp_components, and a re-read of the published pins. A continuation compares the forward revision with the pre-write working pins. When open_draft is not advertised, a published moderated paragraphs_library_item or block_content with no forward revision is saved by that canonical draft PATCH, then the published revision, rel:working-copy, and paragraph pins (including order) are re-read. The result fails if the published revision changed or no forward revision appeared. An existing forward draft, a missing revision id, or a denied version read is refused before any write. An unmoderated item keeps the ordinary update. A completed 4xx is returned when that re-read matches the pre-write revision and pins; a lost response stays uncertain (#420).",
     inputSchema: {
       type: "object", required: ["entityType", "bundle", "id"],
       properties: {
@@ -308,7 +302,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, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A changed/revision_timestamp gap on the default revision (possiblyPatchBlocked) is a warning on list_revisions, not a local dryRun refusal — the write proceeds to the core probe / Sentinel (#405). An actual Sentinel stale-copy refusal is still rewritten. Any refusal fails the dryRun." },
+        dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. An existing node draft (or a langcode translation draft), and a paragraphs_library_item or block_content whose inventory advertises open_draft, are checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A changed/revision_timestamp gap on the default revision (possiblyPatchBlocked) is a warning on list_revisions, not a local dryRun refusal — the write proceeds to the core probe / Sentinel (#405). An actual Sentinel stale-copy refusal is still rewritten. Any refusal fails the dryRun." },
         returning:     RETURNING_SCHEMA,
       },
     },

package/src/tools/index.js

@@ -29,6 +29,7 @@ import * as references   from "./references.js";
 import * as bulk         from "./bulk.js";
 import * as translations from "./translations.js";
 import * as paragraphs   from "./paragraphs.js";
+import * as nested       from "./nested.js";
 import * as structure    from "./structure.js";
 import * as redirects    from "./redirects.js";
 import * as search       from "./search.js";
@@ -42,7 +43,7 @@ import * as codegen      from "./codegen.js";
 import { SITE_PARAM } from "../lib/site-target.js";
 
 const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
-  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra,
+  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, nested, structure, redirects, search, reportsExtra,
   reportsLinks, reportsConfig, reportsContent, auditComposite, config, codegen];
 
 /**

package/src/tools/nested.js

@@ -0,0 +1,68 @@
+/**
+ * Tool: governed nested-paragraph draft (#421).
+ *
+ * Direct component attributes stay on drupal_update_node `components`.
+ * A nested child is a new unpublished paragraph, pinned only by the host
+ * draft. This tool never calls updateEntity on a paragraph.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import { resolveSecurityConfig, assertWriteAllowed, assertPublishAllowed } from "../lib/security.js";
+import { draftNestedComponents } from "../lib/nested-draft.js";
+
+/**
+ * @param {object} args
+ * @returns {Promise<object>}
+ */
+async function draftNestedComponentsTool({
+  site: siteName, bundle, id, field, parentId, childField, children,
+  liveRevisionId, resumeParentId, dryRun = false,
+}) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "update", "node", bundle);
+  assertPublishAllowed(sec, { moderation_state: "draft" });
+  const backend = await resolveBackend(site);
+  return draftNestedComponents(backend, {
+    entityType: "node", bundle, id, field, parentId, childField, children,
+    liveRevisionId, resumeParentId,
+  }, {
+    dryRun,
+    assertParagraphCreate(paragraphBundle) {
+      assertWriteAllowed(sec, "create", "paragraph", paragraphBundle);
+    },
+  });
+}
+
+export const definitions = [
+  {
+    name: "drupal_draft_nested_components",
+    description:
+      "Replace nested paragraphs on a node by creating new unpublished paragraphs and pinning a new direct parent from the node's unpublished draft. children is the full new list: { op: 'keep', id } copies an existing child pin, { op: 'replace', id, type, attributes, translations? } or { op: 'insert', type, attributes, translations? } creates a new child. Omitting a child leaves it off the draft only; it is not deleted. The published host and every paragraph it already pins stay unchanged. Never edits a live child and never sends nested UUIDs as mcp_components (use drupal_update_node components for a direct paragraph's attributes). Reusable library items and from_library children are refused; update the library item with drupal_entity_update. The first host draft requires MCP Sentinel 2.29.0 (open_draft). An existing working copy continues through /mcp-draft. When the host inventory advertises nested_replacement, one /mcp-draft carries meta.mcp_nested_replacement (parent is the parentId input), the connector creates no paragraphs, and it does not also send the host paragraph field. dryRun then uses that non-saving preflight (serverPreflight sentinel_draft). Hosts that do not advertise nested_replacement keep this sequence, including resumeParentId, and dryRun leaves serverPreflight none. New paragraphs are created in the host's default language. The new parent keeps the published parent's other references and replaces only the child field. Non-default translations on the component must be supplied on each replace or insert; they are created on the new paragraphs, and the component's own translations are copied onto the new parent. dryRun checks paragraph-create permission, creates nothing, and does not evaluate the host payload. If paragraph creates succeed and the host pin fails, the error lists the prepared UUIDs. When a parent was prepared, retry with resumeParentId and the same children list; that retry checks the prepared paragraph's fields, other references, and child revision pins before any host write. A failure before a parent exists says to delete the prepared paragraphs and does not offer a host retry. A lost response is uncertain until a re-read proves the prepared revision is pinned; the same UUID at another revision is not success. A second call after success is refused while the forward draft no longer pins the published component. Governed by the site security policy. Nothing is published.",
+    inputSchema: {
+      type: "object",
+      required: ["bundle", "id", "field", "parentId", "childField", "children"],
+      properties: {
+        site: { type: "string", description: "Named site (omit for default)" },
+        bundle: { type: "string", description: "Node bundle machine name, e.g. 'page'" },
+        id: { type: "string", description: "Node UUID" },
+        field: { type: "string", description: "Host entity-reference-revisions field that pins the direct parent, e.g. 'field_components'" },
+        parentId: { type: "string", description: "UUID of the direct paragraph the published host pins. Not a nested child." },
+        childField: { type: "string", description: "Entity-reference-revisions field on that direct paragraph, e.g. 'field_items'" },
+        children: {
+          type: "array",
+          description: "Full new child list, in order. keep: { op, id }. replace: { op, id, type, attributes, translations? }. insert: { op, type, attributes, translations? }. translations is [{ langcode, attributes }] for each non-default language the component already has. Relationships inside a child are refused.",
+          items: { type: "object" },
+        },
+        liveRevisionId: { type: "string", description: "Optional published revision id. Refused before any create when it is not the current live revision." },
+        resumeParentId: { type: "string", description: "Prepared parent UUID from a previous attempt whose host pin did not finish. Retries only the host pin. Must not be a paragraph the published host already pins." },
+        dryRun: { type: "boolean", default: false, description: "When nested_replacement is advertised, run that non-saving /mcp-draft preflight and create nothing (checks.serverPreflight is sentinel_draft). Otherwise read the host and component, then return without creating paragraphs or evaluating the host draft payload (checks.serverPreflight is none)." },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_draft_nested_components: draftNestedComponentsTool,
+};

package/src/tools/nodes.js

@@ -691,7 +691,7 @@ export const definitions = [
         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." },
         components: {
           type: "array",
-          description: "Field changes for paragraphs this node already references directly (hero, text blocks, CTA banners), saved in the same unpublished draft revision as the node fields. Each entry is { id: paragraph UUID, type: paragraph bundle such as 'p_hero', attributes: { field: value } }. Each changed paragraph gets a new revision that only the draft points at; the live page does not change until the draft is published. Opens the working copy from live when none exists. Default language only. Attribute values only: references (for example a media field) are refused, as are nested paragraphs and paragraphs the node does not reference. Requires MCP Sentinel 2.29.0 or later; older hosts are refused before any write, with no direct paragraph write. A `path` change is refused on this path. The connector's paragraph write policy applies to each component. After the write each component is read back at its working revision and the submitted values compared; a value that did not land is an error. The result carries `_components` (each component's live and working pins and the fields verified), which survives `returning: 'minimal'`.",
+          description: "Field changes for paragraphs this node already references directly (hero, text blocks, CTA banners), saved in the same unpublished draft revision as the node fields. Each entry is { id: paragraph UUID, type: paragraph bundle such as 'p_hero', attributes: { field: value } }. Each changed paragraph gets a new revision that only the draft points at; the live page does not change until the draft is published. Opens the working copy from live when none exists. Default language only. Attribute values only: references (for example a media field) are refused, as are paragraphs the node does not reference. A nested paragraph is refused before any write; use drupal_draft_nested_components. Requires MCP Sentinel 2.29.0 or later; older hosts are refused before any write, with no direct paragraph write. A `path` change is refused on this path. The connector's paragraph write policy applies to each component. After the write each component is read back at its working revision and the submitted values compared; a value that did not land is an error. The result carries `_components` (each component's live and working pins and the fields verified), which survives `returning: 'minimal'`.",
           items: {
             type: "object",
             required: ["id", "type", "attributes"],