drupal-mcp-connector 3.0.1 → 3.1.0

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

@@ -1,6 +1,6 @@
 ---
 description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Omit langcode to continue the default language: when the working revision holds several languages and the default language is its unpublished draft, the connector names it for Sentinel (changing shared fields or paragraphs there needs MCP Sentinel 2.24.2). A language that is still published (on live, or on the working copy) is not continued here: call drupal_create_translation with revise: true. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. A published language is not converted into a draft by this tool; use drupal_create_translation with revise: true. dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents. A dryRun that returns without a refusal is not proof the write will succeed: field access and entity validation are checked only when Sentinel's draft endpoint ran, and the result's `checks` block says which checks ran."
-argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [langcode] [fields] [relationships] [dryRun] [returning]"
+argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [langcode] [fields] [relationships] [components] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_update_node`.
@@ -24,6 +24,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `langcode` (string): 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` (object (pass as JSON)): 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` (object (pass as JSON)): 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` (array (pass as JSON)): 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'`.
 - `dryRun` (boolean (true/false)): 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; Drupal does not check field access or entity validation on that probe (`core_patch_guard`). Text format is resolved before the preview returns, including on that path: a known allowed_formats list is enforced, and an unknown list reuses the format stored on the field. Other fields can still fail the real write with a field-access 403 or a validation 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` (one of: full, minimal): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-10-03
+
+### Added
+- **`drupal_update_node` `components` (#416).** Field changes for paragraphs
+  the node references (hero, text blocks, CTA banners) are saved in the same
+  unpublished draft revision as the node fields. The live page does not
+  change until the draft is published. Opens the working copy from live when
+  none exists. Requires MCP Sentinel 2.29.0 (`draft_components`,
+  `open_draft`); older hosts are refused before any write, and there is no
+  fallback to a direct paragraph write. The paragraph write policy applies to
+  each component. After the write, each component is read back at its
+  working revision and the submitted values are compared; a value that did
+  not land is reported as an error, not a success.
+- **stdio Cursor plugin scaffold.** `.cursor-plugin/plugin.json`,
+  root `mcp.json` (`npx -y drupal-mcp-connector`, no `url`), one short
+  skill, and [PRIVACY.md](PRIVACY.md). No hosted MCP URL and no listing
+  submit.
+
+### Changed
+- **SECURITY.md supported versions** now list 3.x (not 0.x).
+- **CI and release run the advertised quality gate.** `npm run check` is
+  lint + high-severity `npm audit` + `syntax-check` + test. CI and the
+  release workflow both run that command, so a high advisory fails CI and
+  a tag that fails syntax-check does not publish. Lockfile pins
+  `brace-expansion` `5.0.12` so the new audit step is clean.
+
 ## [3.0.1] - 2026-10-01
 
 ### Fixed

package/README.md

@@ -239,6 +239,20 @@ Drupal. See **[docs/mcp-clients.md](docs/mcp-clients.md)**.
 entry — this repo does not submit listings. If the client only shows
 `drupal_list_sites` and `drupal_governance_status`, run `doctor`.
 
+### Cursor plugin (stdio)
+
+Local skeleton only (`.cursor-plugin/plugin.json` + root `mcp.json`): the client
+launches `npx -y drupal-mcp-connector` on this machine. No hosted URL.
+
+```bash
+npx -y drupal-mcp-connector init --preset local-stdio
+npx -y drupal-mcp-connector doctor
+```
+
+`requireGovernance: true` is the listing default. `--preset public-https` stays
+gated. Marketplace listing submit is **operator-only** — this repo does not submit.
+See [PRIVACY.md](PRIVACY.md).
+
 ### Two-minute happy path
 
 After `init` and a green `doctor`, in the MCP client (real tool names):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Multi-site MCP server for Drupal over JSON:API and GraphQL, with governed writes and an SSH Drush bridge. init writes a stdio or Tailscale client config from a transport preset. doctor checks reachability, auth, and readiness, and reports version skew. A timestamp gap on a published revision no longer blocks the next draft.",
   "type": "module",
   "main": "src/index.js",
@@ -62,7 +62,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "audit": "npm audit --audit-level=high",
-    "check": "npm run lint && npm run audit",
+    "check": "npm run lint && npm run audit && npm run syntax-check && npm test",
     "syntax-check": "find src -name '*.js' -exec sh -c 'node --input-type=module --check < \"$1\" && echo \"$1 ✓\"' _ {} \\;",
     "verify": "node bin/drupal-mcp-verify.js",
     "verify:example": "node bin/drupal-mcp-verify.js --config config/config.example.json",

package/src/lib/component-draft.js

@@ -0,0 +1,283 @@
+/**
+ * Component paragraph changes carried in one governed node draft
+ * (drupal-mcp-connector #416, MCP Sentinel d.o #3627742).
+ *
+ * The node edit form saves a draft once: each changed paragraph becomes a
+ * new non-default revision and the draft points at it, while the live
+ * revision keeps its pins. Sentinel's `/mcp-draft` does the same when the
+ * request carries `meta.mcp_components`. This module validates the
+ * components, checks that the host advertises the operations, preflights the
+ * exact payload, writes it, and verifies the working copy moved each pin.
+ *
+ * There is no fallback. A host without the operations is refused before any
+ * write; a direct paragraph PATCH would change the live page.
+ */
+
+import { readNodeDraftInventory, assertDraftLangcode } from "./sentinel-draft.js";
+import { entityRevisionId } from "./write-revision.js";
+import { paragraphPinsFromEntity } from "./err-relationships.js";
+import { PREFLIGHT_SENTINEL_DRAFT, dryRunChecks } from "./dry-run-checks.js";
+
+/** Inventory operation: component paragraph changes inside a draft save. */
+export const DRAFT_COMPONENTS_OPERATION = "draft_components";
+/** Inventory operation: open the first working copy from live (`If-Match: "live"`). */
+export const OPEN_DRAFT_OPERATION = "open_draft";
+/** First MCP Sentinel release with both operations. */
+export const MIN_SENTINEL_COMPONENTS_VERSION = "2.29.0";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const BUNDLE_RE = /^[a-z][a-z0-9_]*$/;
+
+/**
+ * Validate component entries and normalize `type` to `paragraph--<bundle>`.
+ * @param {unknown} components
+ * @returns {Array<{type: string, id: string, attributes: object}>}
+ */
+export function normalizeComponents(components) {
+  if (!Array.isArray(components) || components.length === 0) {
+    throw new Error("components must be a non-empty list of { id, type, attributes }.");
+  }
+  const seen = new Set();
+  return components.map((component, index) => {
+    const where = `components[${index}]`;
+    if (!component || typeof component !== "object" || Array.isArray(component)) {
+      throw new Error(`${where} must be an object with id, type and attributes.`);
+    }
+    if (Object.hasOwn(component, "relationships")) {
+      throw new Error(`${where}: a component change cannot change references. Send attribute values only.`);
+    }
+    const id = String(component.id ?? "");
+    if (!UUID_RE.test(id)) throw new Error(`${where}.id must be the paragraph UUID.`);
+    // UUID text is case-insensitive; dedupe on one canonical form.
+    const key = id.toLowerCase();
+    if (seen.has(key)) throw new Error(`${where}: paragraph ${id} is listed more than once.`);
+    seen.add(key);
+    const rawType = String(component.type ?? "");
+    const bundle = rawType.startsWith("paragraph--") ? rawType.slice("paragraph--".length) : rawType;
+    if (rawType.includes("--") && !rawType.startsWith("paragraph--")) {
+      throw new Error(`${where}.type must be a paragraph bundle, not ${rawType}.`);
+    }
+    if (!BUNDLE_RE.test(bundle)) throw new Error(`${where}.type must be a paragraph bundle such as "p_hero".`);
+    const attributes = component.attributes;
+    if (!attributes || typeof attributes !== "object" || Array.isArray(attributes)
+      || Object.keys(attributes).length === 0) {
+      throw new Error(`${where}.attributes must name at least one field.`);
+    }
+    return { type: `paragraph--${bundle}`, id, attributes };
+  });
+}
+
+/**
+ * @param {string} operation
+ * @returns {Error}
+ */
+function capabilityError(operation) {
+  return new Error(
+    `This Sentinel host cannot save component changes in a draft (missing ${operation}). ` +
+    `Update MCP Sentinel to ${MIN_SENTINEL_COMPONENTS_VERSION} or later. ` +
+    "No write was attempted, and no direct paragraph write was tried: it would change the live page.",
+  );
+}
+
+/**
+ * One `/mcp-draft` request carrying node attributes and components.
+ * @param {object} backend
+ * @param {object} spec
+ * @returns {Promise<object>}
+ */
+function draftRequest(backend, { entityType, bundle, id, data, components, live, working, langcode, preflight }) {
+  return backend.rawQuery({
+    path: `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}/mcp-draft`,
+    options: {
+      method: "PATCH",
+      headers: {
+        "If-Match": working ? `"${live}:${working}"` : `"${live}"`,
+        "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+        "X-MCP-Draft-Langcode": langcode,
+      },
+      body: JSON.stringify({ data, meta: { mcp_components: components } }),
+    },
+  });
+}
+
+/**
+ * Whether a stored field value carries every submitted part.
+ *
+ * Submitted objects are compared key by key, so read-only extras such as
+ * `processed` or `resolvable_uri` do not count. An empty submitted `options`
+ * matches any stored empty options. A single submitted item matches a
+ * single-value field read back as an object.
+ * @param {unknown} submitted
+ * @param {unknown} actual
+ * @returns {boolean}
+ */
+export function valueMatches(submitted, actual) {
+  if (submitted === null || typeof submitted !== "object") {
+    if (actual !== null && typeof actual === "object" && !Array.isArray(actual) && "value" in actual) {
+      return valueMatches(submitted, actual.value);
+    }
+    return submitted === actual;
+  }
+  if (Array.isArray(submitted)) {
+    const list = Array.isArray(actual) ? actual : actual === null || actual === undefined ? [] : [actual];
+    return list.length === submitted.length && submitted.every((item, i) => valueMatches(item, list.at(i)));
+  }
+  if (actual === null || typeof actual !== "object") return false;
+  const stored = new Map(Object.entries(actual));
+  return Object.entries(submitted).every(([key, part]) => {
+    const isEmpty = (v) => v === null || v === undefined
+      || (Array.isArray(v) && v.length === 0)
+      || (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0);
+    if (key === "options" && isEmpty(part)) return isEmpty(stored.get(key));
+    return valueMatches(part, stored.get(key));
+  });
+}
+
+/**
+ * Pins keyed by paragraph UUID.
+ * @param {?object} entity
+ * @returns {Map<string, string>}
+ */
+function pinMap(entity) {
+  const pins = new Map();
+  for (const pin of paragraphPinsFromEntity(entity)) {
+    if (pin.revisionId !== null && pin.revisionId !== undefined) pins.set(pin.id, String(pin.revisionId));
+  }
+  return pins;
+}
+
+/**
+ * Save node attributes and component paragraph changes as one unpublished
+ * draft revision, opening the working copy from live when none exists.
+ *
+ * @param {object} backend JSON:API backend with Sentinel draft routes.
+ * @param {object} input
+ * @param {string} input.entityType Always "node" today.
+ * @param {string} input.bundle
+ * @param {string} input.id Node UUID.
+ * @param {object} input.attributes Node attributes, including moderation_state.
+ * @param {object} [input.relationships]
+ * @param {Array} input.components Entries for {@link normalizeComponents}.
+ * @param {string} [input.langcode] Must be the default language when given.
+ * @param {{dryRun?: boolean}} [options]
+ * @returns {Promise<object>} Preview on dryRun; otherwise the written entity
+ *   plus `_components` (live and working pins and verified fields per
+ *   paragraph).
+ */
+export async function writeComponentDraft(backend, input, { dryRun = false } = {}) {
+  const { entityType, bundle, id, attributes = {}, relationships } = input;
+  const components = normalizeComponents(input.components);
+  if (Object.hasOwn(attributes, "path")) {
+    throw new Error("Aliases are not revisioned. Change the alias in a separate update; no write was attempted.");
+  }
+  const inventory = await readNodeDraftInventory(backend, { entityType, bundle, id });
+  if (!inventory) throw capabilityError(DRAFT_COMPONENTS_OPERATION);
+  const operations = Array.isArray(inventory.operations) ? inventory.operations : [];
+  if (!operations.includes(DRAFT_COMPONENTS_OPERATION)) throw capabilityError(DRAFT_COMPONENTS_OPERATION);
+
+  const defaultLang = typeof inventory.defaultLangcode === "string" ? inventory.defaultLangcode : undefined;
+  if (!defaultLang) throw new Error("Sentinel did not report the default language. No write was attempted.");
+  if (input.langcode !== undefined && input.langcode !== null && input.langcode !== ""
+    && assertDraftLangcode(input.langcode) !== defaultLang) {
+    throw new Error(`Component changes apply to the default language (${defaultLang}) only. No write was attempted.`);
+  }
+
+  const live = String(inventory.live.vid);
+  const working = inventory.working?.vid && String(inventory.working.vid) !== live
+    ? String(inventory.working.vid)
+    : "";
+  if (!working && !operations.includes(OPEN_DRAFT_OPERATION)) throw capabilityError(OPEN_DRAFT_OPERATION);
+  if (working) {
+    const row = (inventory.working.translations ?? []).find((r) => r?.langcode === defaultLang);
+    const state = typeof row?.moderation_state === "string" ? row.moderation_state : "";
+    if (!row || row.status === true || state === "published") {
+      throw new Error(
+        `The default language (${defaultLang}) is still published on the working copy, so it cannot be continued. ` +
+        "Publish or discard the other language's draft first. No write was attempted.",
+      );
+    }
+  }
+
+  const data = { type: `${entityType}--${bundle}`, id, attributes };
+  if (relationships && Object.keys(relationships).length) data.relationships = relationships;
+  const request = { entityType, bundle, id, data, components, live, working, langcode: defaultLang };
+
+  const checked = await draftRequest(backend, { ...request, preflight: true });
+  const meta = checked?.meta;
+  if (meta?.draft_preflight !== true || String(meta.live) !== live || String(meta.working ?? "") !== working
+    || (!working && meta.operation !== OPEN_DRAFT_OPERATION)) {
+    throw new Error("The site did not confirm a non-saving draft preflight for these components. No write was attempted.");
+  }
+  if (dryRun) {
+    return {
+      dryRun: true, operation: "update", entityType, bundle, id, attributes,
+      relationships: data.relationships ?? {}, components,
+      opensWorkingCopy: !working,
+      ...dryRunChecks({ operation: "update", preflight: PREFLIGHT_SENTINEL_DRAFT }),
+    };
+  }
+
+  // The pins each component held before this save. Continuing a working copy
+  // starts from that copy's pins, not live's.
+  const baselineEntity = working
+    ? await backend.getEntity({ entityType, bundle, id, resourceVersion: `id:${working}` })
+    : null;
+
+  const result = await draftRequest(backend, { ...request, preflight: false });
+  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
+    throw new Error("The draft write response did not identify the node. The outcome is uncertain; re-read before retrying.");
+  }
+  const entity = backend.toCanonical(result.data);
+  const workingVid = entityRevisionId(entity) ?? entityRevisionId(result.data);
+  if (workingVid === null) {
+    throw new Error("The draft write response carried no revision ID. Re-read the working copy before retrying.");
+  }
+  const [liveEntity, workingEntity] = await Promise.all([
+    backend.getEntity({ entityType, bundle, id }),
+    backend.getEntity({ entityType, bundle, id, resourceVersion: `id:${workingVid}` }),
+  ]);
+  const livePins = pinMap(liveEntity);
+  const workingPins = pinMap(workingEntity);
+  const baselinePins = working ? pinMap(baselineEntity) : livePins;
+  // Every paragraph on the host gets a new revision when the host does, so a
+  // moved pin alone proves nothing. Read each component at its working pin and
+  // compare the submitted values.
+  const report = [];
+  for (const { id: uuid, type, attributes: submitted } of components) {
+    const livePin = livePins.get(uuid) ?? null;
+    const workingPin = workingPins.get(uuid) ?? null;
+    const baselinePin = baselinePins.get(uuid) ?? null;
+    if (!workingPin || workingPin === livePin || workingPin === baselinePin) {
+      throw new Error(
+        `The draft was saved as revision ${workingVid}, but it still pins the earlier revision of component ${uuid}. ` +
+        "Re-read the working copy before retrying.",
+      );
+    }
+    const paragraph = await backend.getEntity({
+      entityType: "paragraph", bundle: type.slice("paragraph--".length), id: uuid, resourceVersion: `id:${workingPin}`,
+    });
+    if (!paragraph) {
+      throw new Error(
+        `The draft was saved as revision ${workingVid}, but component ${uuid} could not read back at revision ${workingPin}. ` +
+        "Check the working copy before retrying.",
+      );
+    }
+    const values = new Map(Object.entries({ ...(paragraph.attributes ?? {}), ...(paragraph.fields ?? {}) }));
+    const mismatched = Object.entries(submitted)
+      .filter(([name, value]) => !valueMatches(value, values.get(name)))
+      .map(([name]) => name);
+    if (mismatched.length) {
+      throw new Error(
+        `The draft was saved as revision ${workingVid}, but component ${uuid} does not hold the submitted ` +
+        `${mismatched.join(", ")} at revision ${workingPin}. Check the working copy before retrying.`,
+      );
+    }
+    report.push({ id: uuid, type, livePin, workingPin, verified: Object.keys(submitted) });
+  }
+  // `_`-prefixed keys survive `returning: "minimal"`.
+  return {
+    ...entity,
+    _revisions: { live, working: workingVid },
+    _components: report,
+  };
+}

package/src/tools/nodes.js

@@ -28,6 +28,7 @@ import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 import { applyAllowedFormatsToAttributes, attributesOmitTextFormat } from "../lib/field-definition.js";
 import { normalizeAlias, PATH_ALIAS_ENTITY_TYPE } from "../lib/path-alias.js";
+import { writeComponentDraft, normalizeComponents } from "../lib/component-draft.js";
 
 /** Fallback language for an alias when the node exposes none. */
 const DEFAULT_ALIAS_LANGCODE = "en";
@@ -464,10 +465,16 @@ 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, langcode, fields = {}, relationships = {}, dryRun = false, returning = "full" }) {
+async function updateNode({ site: siteName, type, id, title, body, summary, format, status, moderationState, langcode, fields = {}, relationships = {}, components, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "node", type);
+  // #416: a component change is a paragraph write; the paragraph policy
+  // applies to each one, as it does on drupal_update_paragraph.
+  const normalizedComponents = components === undefined ? undefined : normalizeComponents(components);
+  for (const component of normalizedComponents ?? []) {
+    assertWriteAllowed(sec, "update", "paragraph", component.type.slice("paragraph--".length));
+  }
   const backend = await resolveBackend(site);
   const summaryWrite = await assertBodySummaryWritable(backend, type, summary);
   let attributes = { ...fields };
@@ -503,6 +510,16 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   // #192: resolve paragraph ERR identifiers before any host PATCH. An unresolved
   // list would persist empty — fail the whole write instead.
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
+  // #416: component paragraph changes ride the same draft save as the node
+  // fields through Sentinel. There is no core PATCH or alias step on this path.
+  if (normalizedComponents !== undefined) {
+    const written = await writeComponentDraft(backend, {
+      entityType: "node", bundle: type, id, attributes, relationships: resolvedRelationships,
+      components: normalizedComponents, langcode,
+    }, { dryRun });
+    const shaped = dryRun ? written : shapeWriteResponse(written, returning);
+    return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(shaped) : shaped;
+  }
   // #201 / #166: probe the write endpoint. Addressable drafts use Sentinel's
   // governed continuation endpoint; stray revisions still fail the probe.
   const patchTarget = await prepareGuardedPatch(backend, {
@@ -672,6 +689,19 @@ export const definitions = [
         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. 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'`.",
+          items: {
+            type: "object",
+            required: ["id", "type", "attributes"],
+            properties: {
+              id: { type: "string", description: "Paragraph UUID" },
+              type: { type: "string", description: "Paragraph bundle, e.g. 'p_hero' (or 'paragraph--p_hero')" },
+              attributes: { type: "object", description: "Paragraph field values keyed by machine name" },
+            },
+          },
+        },
         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; Drupal does not check field access or entity validation on that probe (`core_patch_guard`). Text format is resolved before the preview returns, including on that path: a known allowed_formats list is enforced, and an unknown list reuses the format stored on the field. Other fields can still fail the real write with a field-access 403 or a validation 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,
       },