drupal-mcp-connector 2.7.4 → 2.8.0

package/src/lib/server-tools.js

@@ -24,6 +24,7 @@
 
 import fetch from "node-fetch";
 import { authHeadersAsync, clientHeaders, CLIENT_VERSION } from "./config.js";
+import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial } from "./data-flow.js";
 import { clearToken } from "./oauth.js";
 
 /**
@@ -90,6 +91,7 @@ async function baseHeaders(site, sessionId) {
     Accept: "application/json, text/event-stream",
     "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
     ...clientHeaders(),
+    ...northboundHeaders(),
     ...(await authHeadersAsync(site)),
   };
   if (sessionId) headers["Mcp-Session-Id"] = sessionId;
@@ -263,9 +265,12 @@ export async function callServerTool(site, toolName, args = {}) {
   let sessionId = await ensureSession(site, endpoint);
   let refreshedAuth = false;
   let reinitedSession = false;
+  let paid = false;
 
   // Retry loop: at most one auth refresh and one session re-init, each replayed once.
   while (true) {
+    consumeBudgetIfEnforced("request", 1, { retry: paid });
+    paid = true;
     const res = await fetch(endpoint, {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
@@ -289,6 +294,8 @@ export async function callServerTool(site, toolName, args = {}) {
     }
 
     if (!res.ok) {
+      const mapped = sourceBudgetDenial(rawText);
+      if (mapped) throw mapped;
       throw new Error(`Server-tool call ${toolName} failed ${res.status}: ${rawText}`);
     }
 
@@ -303,6 +310,8 @@ export async function callServerTool(site, toolName, args = {}) {
     const result = body?.result;
     if (result?.isError) {
       const detail = extractTextContent(result) || "tool reported an error";
+      const mapped = sourceBudgetDenial(detail);
+      if (mapped) throw mapped;
       throw new Error(`Server-tool ${toolName} reported an error: ${detail}`);
     }
     return result;

package/src/lib/write-revision.js

@@ -5,7 +5,79 @@
  * published node — after a draft ERR attach it still shows the *old* refs.
  * Prefer `rel:working-copy`. If that alias is not addressable, return the
  * PATCH body (or the canonical re-read) plus `_revision.relationshipsUnverified`.
+ *
+ * After a write, {@link attachWrittenRevisionPair} may add `_revisions`
+ * `{ live, working }` when both vids can be read honestly (#166).
+ */
+
+/**
+ * Read a revision id off a canonical (or raw-ish) entity body.
+ * @param {?object} entity
+ * @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;
+  if (raw === undefined || raw === null || raw === "") return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
+}
+
+/**
+ * Attach distinct live vs working revision ids when both are known.
+ * Does not invent vids.
+ * @param {object} entity
+ * @param {{live: ?number|string, working: ?number|string}} pair
+ * @returns {object}
  */
+export function attachRevisionPair(entity, { live, working }) {
+  if (!entity || live === null || live === undefined || working === null || working === undefined) {
+    return entity;
+  }
+  if (String(live) === String(working)) return entity;
+  return { ...entity, _revisions: { live, working } };
+}
+
+/**
+ * After a write, attach `_revisions` when a working copy is addressable
+ * and the live vid is already known. Omits the block when either side
+ * cannot be read — never invents a vid.
+ *
+ * @param {object} args
+ * @param {object} args.backend
+ * @param {string} args.entityType
+ * @param {string} args.bundle
+ * @param {string} args.id
+ * @param {object} args.entity Write result to annotate.
+ * @param {?number|string} [args.liveVid]
+ * @returns {Promise<object>}
+ */
+export async function attachWrittenRevisionPair({
+  backend, entityType, bundle, id, entity, liveVid,
+}) {
+  if (liveVid === null || liveVid === undefined || !entity) return entity;
+  let workingVid = null;
+  if (typeof backend?.getEntity === "function") {
+    try {
+      const wc = await backend.getEntity({
+        entityType, bundle, id, resourceVersion: "rel:working-copy",
+      });
+      workingVid = entityRevisionId(wc);
+    } catch {
+      workingVid = null;
+    }
+  }
+  return attachRevisionPair(entity, { live: liveVid, working: workingVid });
+}
 
 /**
  * @param {object} args
@@ -16,15 +88,23 @@
  * @param {boolean} args.relationshipsSent
  * @param {?object} [args.patchResult] Canonicalised PATCH response body.
  * @param {boolean} [args.preferCanonical] When no relationships were sent,
- *   re-GET the canonical resource (nodes do this for the persisted alias).
+ *   re-GET the written resource (nodes do this for the persisted alias).
+ * @param {?string} [args.resourceVersion] JSON:API revision selector used
+ *   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.
  * @returns {Promise<object>} Entity to return, with `_revision` when relevant.
  */
 export async function readWrittenRevision({
   backend, entityType, bundle, id, relationshipsSent, patchResult = null, preferCanonical = false,
+  resourceVersion,
 }) {
   if (!relationshipsSent) {
     if (preferCanonical && typeof backend.getEntity === "function") {
-      const fresh = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
+      const fresh = await backend.getEntity({
+        entityType, bundle, id,
+        ...(resourceVersion ? { resourceVersion } : {}),
+      }).catch(() => null);
       return fresh ?? patchResult ?? { id };
     }
     return patchResult ?? { id };

package/src/tools/bulk.js

@@ -19,7 +19,7 @@ import {
   resolveErrRelationships, embedParagraphRef,
   resolveParagraphRevisionId, missingParagraphRevisionError,
 } from "../lib/err-relationships.js";
-import { preflightPatchWritable, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 
 /**
  * Normalize an unknown thrown value into a human-readable message.
@@ -118,13 +118,14 @@ async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
       });
       assertPublishAllowed(sec, attributes);
       const resolvedRelationships = await resolveErrRelationships(backend, item.relationships ?? {});
-      await preflightPatchWritable({
-        backend, entityType, bundle, id: item.id, existing, attributes,
+      const patchTarget = await prepareGuardedPatch(backend, {
+        entityType, bundle, id: item.id, existing, attributes,
       });
       const entity = await updateEntityGuarded(backend, {
         entityType, bundle, id: item.id,
         attributes,
         relationships: resolvedRelationships,
+        ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
       });
       updated += 1;
       results.push({ index, success: true, id: entity?.id ?? item.id });

package/src/tools/entities.js

@@ -16,8 +16,8 @@ import {
   resolveErrRelationships, relationshipsWereSent, embedParagraphRef,
   resolveParagraphRevisionId, missingParagraphRevisionError,
 } from "../lib/err-relationships.js";
-import { readWrittenRevision } from "../lib/write-revision.js";
-import { preflightPatchWritable, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
+import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
   redactCanonicalEntity, getSecuritySummary,
@@ -117,8 +117,8 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   });
   assertPublishAllowed(sec, safeAttributes);
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
-  await preflightPatchWritable({
-    backend, entityType, bundle, id, existing, attributes: safeAttributes,
+  const patchTarget = await prepareGuardedPatch(backend, {
+    entityType, bundle, id, existing, attributes: safeAttributes,
   });
   if (dryRun) {
     return {
@@ -128,6 +128,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   }
   const result = await updateEntityGuarded(backend, {
     entityType, bundle, id, attributes: safeAttributes, relationships: resolvedRelationships,
+    ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
   });
   const written = await readWrittenRevision({
     backend, entityType, bundle, id,
@@ -135,7 +136,10 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
     patchResult: result,
     preferCanonical: false,
   });
-  return shapeWriteResponse(flagUnrequestedStatusChange(written, existing, safeAttributes), returning);
+  const withRevs = await attachWrittenRevisionPair({
+    backend, entityType, bundle, id, entity: written, liveVid: patchTarget.liveVid,
+  });
+  return shapeWriteResponse(flagUnrequestedStatusChange(withRevs, existing, safeAttributes), returning);
 }
 
 /**
@@ -276,7 +280,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 an id-mismatch PATCH preflight runs first (including dryRun) so a core working-copy guard failure is reported before the real write and no revision is saved by the probe (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents.",
+    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 an id-mismatch PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#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.",
     inputSchema: {
       type: "object", required: ["entityType", "bundle", "id"],
       properties: {
@@ -286,7 +290,7 @@ export const definitions = [
         id:            { type: "string" },
         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. The probe uses a non-matching data.id so Drupal does not save. A working-copy 400 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. The probe uses a non-matching data.id so Drupal does not save, and hits the same URL as the real write (canonical, or ?resourceVersion=rel:working-copy when a draft is addressable). A working-copy 400 fails the dryRun." },
         returning:     RETURNING_SCHEMA,
       },
     },

package/src/tools/index.js

@@ -4,8 +4,9 @@
  * Each tool module exports `definitions` (the MCP `{name, description, inputSchema}`
  * descriptors) and `handlers` (a name → function dispatch map). This module flattens
  * all of them into the runtime payloads consumed by the server (src/index.js) AND by
- * the offline slash-command generator (scripts/generate-commands.js), so the tool
- * list, the per-tool MCP prompts, and the `/drupal-*` command files can never drift.
+ * the offline slash-command generator (scripts/generate-commands.js →
+ * `.agents/commands/`), so the tool list, the per-tool MCP prompts, and the
+ * `/drupal-*` command files can never drift.
  *
  * Importing this module has NO side effects (unlike src/index.js, which boots the
  * transport), so generators and tests can import it freely.

package/src/tools/nodes.js

@@ -16,9 +16,11 @@ import {
 import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
 import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
 import { resolveErrRelationships, relationshipsWereSent } from "../lib/err-relationships.js";
-import { readWrittenRevision } from "../lib/write-revision.js";
-import { preflightPatchWritable, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
+import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
+import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
 
 /** Fallback language for an alias when the node exposes none. */
 const DEFAULT_ALIAS_LANGCODE = "en";
@@ -130,22 +132,14 @@ async function createRenameRedirect(backend, sec, redirect) {
   }
 }
 
-/**
- * Fallback text format when neither the call nor the site config names one.
- *
- * Retained for backward compatibility only. A site whose text formats do not
- * include `full_html` — or whose agent account may not use it — must set
- * `defaultTextFormat` in its site config or pass `format` per call.
- */
-const FALLBACK_TEXT_FORMAT = "full_html";
-
 /**
  * Build a Drupal body field descriptor from plain HTML + optional summary.
  *
- * The text format is a security boundary in Drupal (it decides which HTML
- * survives filtering), so it is resolved explicitly rather than assumed:
- * an explicit `format` argument wins, then the site's `defaultTextFormat`,
- * then the historical fallback.
+ * Format is left omitted when the caller did not pass one so
+ * `applyAllowedFormatsToAttributes` can honor Field API `allowed_formats`
+ * before applying the historical `defaultTextFormat` / `full_html` chain.
+ * Applying that fallback first would treat `full_html` as a caller format
+ * and refuse a single-allowed-format field (#168).
  *
  * `summary` is only included when the caller supplied it. Sending an empty
  * string on every write would blank an existing body summary whenever a
@@ -154,17 +148,14 @@ const FALLBACK_TEXT_FORMAT = "full_html";
  * @param {string} [body]    - Body HTML; when undefined the field is omitted.
  * @param {string} [summary] - Teaser/summary text; omitted when undefined.
  * @param {string} [format]  - Text format machine name.
- * @param {object} [site]    - Site config, read for `defaultTextFormat`.
- * @returns {{value: string, format: string, summary?: string}|undefined}
+ * @returns {{value: string, format?: string, summary?: string}|undefined}
  *   A body attribute object, or undefined when no body was supplied (so callers
  *   can skip the field on update rather than blanking it).
  */
-function buildBodyAttribute(body, summary, format, site) {
+function buildBodyAttribute(body, summary, format) {
   if (body === undefined) return undefined;
-  const attr = {
-    value: body,
-    format: format ?? site?.defaultTextFormat ?? FALLBACK_TEXT_FORMAT,
-  };
+  const attr = { value: body };
+  if (format !== undefined) attr.format = format;
   if (summary !== undefined) attr.summary = summary;
   return attr;
 }
@@ -263,18 +254,25 @@ async function createNode({ site: siteName, type, title, body, summary, format,
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", "node", type);
+  const backend = await resolveBackend(site);
   const attributes = { title, ...fields };
   if (moderationState !== undefined) {
     attributes.moderation_state = moderationState;
   } else {
     attributes.status = status === undefined ? false : status;
   }
-  const bodyAttr = buildBodyAttribute(body, summary, format, site);
+  const bodyAttr = buildBodyAttribute(body, summary, format);
   if (bodyAttr) attributes.body = bodyAttr;
+  await applyAllowedFormatsToAttributes({
+    backend, site, entityType: "node", bundle: type, attributes,
+  });
+  const summaryWrite = await assertBodySummaryWritable(backend, type, summary);
   assertPublishAllowed(sec, attributes);
-  const backend = await resolveBackend(site);
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
-  if (dryRun) return { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes, relationships: resolvedRelationships };
+  if (dryRun) {
+    const preview = { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes, relationships: resolvedRelationships };
+    return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(preview) : preview;
+  }
   // Alias handling: an explicit `path.alias` is set as a manual alias; otherwise
   // `path` is omitted so pathauto generates the alias (DEV-116).
   const { pathAttr } = await resolvePathWrite({ backend, type, id: null, providedPath: attributes.path, isCreate: true });
@@ -284,7 +282,8 @@ async function createNode({ site: siteName, type, title, body, summary, format,
   // Honest response: re-read so the persisted alias (explicit or pathauto-generated)
   // is reflected rather than the pre-alias write response.
   const fresh = await backend.getEntity({ entityType: "node", bundle: type, id: created.id }).catch(() => null);
-  return shapeWriteResponse(fresh ?? created, returning);
+  const shaped = shapeWriteResponse(fresh ?? created, returning);
+  return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(shaped) : shaped;
 }
 
 /**
@@ -316,12 +315,16 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "node", type);
   const backend = await resolveBackend(site);
+  const summaryWrite = await assertBodySummaryWritable(backend, type, summary);
   let attributes = { ...fields };
   if (title !== undefined) attributes.title = title;
   if (moderationState !== undefined) attributes.moderation_state = moderationState;
   else if (status !== undefined) attributes.status = status;
-  const bodyAttr = buildBodyAttribute(body, summary, format, site);
+  const bodyAttr = buildBodyAttribute(body, summary, format);
   if (bodyAttr) attributes.body = bodyAttr;
+  await applyAllowedFormatsToAttributes({
+    backend, site, entityType: "node", bundle: type, attributes,
+  });
   // One pre-read serves the #131 draft default and the #171 unrequested-
   // status-change flag. Skipped when the caller pinned the moderation state.
   let existing = null;
@@ -341,16 +344,18 @@ 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);
-  // #201: the core working-copy guard runs before deserialize. A no-op probe
-  // against the same canonical URL is a true preflight, including on dryRun.
-  await preflightPatchWritable({
-    backend, entityType: "node", bundle: type, id, existing, attributes,
+  // #201 / #166: probe the same URL the write will hit. An addressable
+  // working copy is PATCHed via rel:working-copy; a stray revision still
+  // fails the probe with revision-surgery language.
+  const patchTarget = await prepareGuardedPatch(backend, {
+    entityType: "node", bundle: type, id, existing, attributes,
   });
   if (dryRun) {
-    return {
+    const preview = {
       dryRun: true, operation: "update", entityType: "node", bundle: type, id,
       attributes, relationships: resolvedRelationships,
     };
+    return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(preview) : preview;
   }
   // Alias handling (DEV-116): an explicit `path.alias` is set in place by
   // round-tripping the existing alias's pid (no duplicate); a path-less update
@@ -361,6 +366,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   else attributes.path = pathAttr;
   const patched = await updateEntityGuarded(backend, {
     entityType: "node", bundle: type, id, attributes, relationships: resolvedRelationships,
+    ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
   });
   const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
   // #169: when relationships were sent, the canonical re-read is the published
@@ -370,12 +376,18 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
     patchResult: patched,
     preferCanonical: true,
+    resourceVersion: patchTarget.resourceVersion,
+  });
+  const withRevs = await attachWrittenRevisionPair({
+    backend, entityType: "node", bundle: type, id, entity: fresh, liveVid: patchTarget.liveVid,
   });
   // #171: an unrequested published-state flip in the persisted node is
   // reported via _statusChanged rather than returned as a clean success.
-  const flagged = flagUnrequestedStatusChange(fresh, existing, attributes);
-  if (flagged && redirectResult) return shapeWriteResponse({ ...flagged, _redirect: redirectResult }, returning);
-  return shapeWriteResponse(flagged ?? { id }, returning);
+  const flagged = flagUnrequestedStatusChange(withRevs, existing, attributes);
+  const shaped = flagged && redirectResult
+    ? shapeWriteResponse({ ...flagged, _redirect: redirectResult }, returning)
+    : shapeWriteResponse(flagged ?? { id }, returning);
+  return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(shaped) : shaped;
 }
 
 /**
@@ -452,11 +464,11 @@ export const definitions = [
         type:    { type: "string", description: "Content type machine name" },
         title:   { type: "string" },
         body:    { type: "string", description: "Body field HTML" },
-        summary: { type: "string", description: "Body summary/teaser — writes the `summary` property of the body field (core `text_with_summary`). Many headless sites instead use a dedicated summary/deck field for teasers and meta descriptions; on those, set that field in `fields` — a value written here will be stored but may never be rendered." },
-        format:  { type: "string", description: "Text format machine name for the body, e.g. 'basic_html'. Defaults to the site config's `defaultTextFormat`, then 'full_html'. Set this when the site's formats do not include full_html, or to avoid writing content into a more permissive format than intended." },
+        summary: { type: "string", description: "Body summary/teaser — writes body.summary on core text_with_summary only. Refused when the sampled body field has no summary property (text_long / text_formatted) or the schema cannot be determined. Prefer the site's dedicated deck/summary field via `fields`." },
+        format:  { type: "string", description: "Text format machine name for the body, e.g. 'basic_html'. When the body field's allowed_formats lists exactly one format, that is the default. A caller format outside that list is refused before write. When allowed_formats cannot be resolved, defaults to the site config's `defaultTextFormat`, then 'full_html'." },
         status:  { type: "boolean", default: false, description: "Published flag for NON-moderated types. true to publish immediately. Ignored if moderationState is set; on a moderated type it is dropped automatically." },
         moderationState: { type: "string", description: "Moderation state for content_moderation types, e.g. 'draft' or 'published'. Takes precedence over status." },
-        fields:  { type: "object", description: "Scalar/attribute field values keyed by Drupal machine name. Do NOT put entity-reference fields here — Drupal rejects them as attributes; use `relationships`." },
+        fields:  { type: "object", description: "Scalar/attribute field values keyed by Drupal 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. Do NOT put entity-reference fields here — Drupal rejects them as attributes; use `relationships`." },
         relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value: { field_resource_type: { data: { type: 'taxonomy_term--resource_type', id: '<uuid>' } } }. Multi-value: { field_tags: { data: [{ type: 'taxonomy_term--tags', id: '<uuid>' }] } }." },
         dryRun:  { type: "boolean", default: false, description: "Validate and return a preview of the write without committing." },
         returning: RETURNING_SCHEMA,
@@ -465,7 +477,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets an id-mismatch PATCH preflight runs first — including on dryRun — so a core working-copy guard failure is reported before the real write and no revision is saved by the probe. 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. 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 an id-mismatch PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -474,13 +486,13 @@ export const definitions = [
         id:      { type: "string", description: "Node UUID" },
         title:   { type: "string" },
         body:    { type: "string" },
-        summary: { type: "string", description: "Body summary/teaser — writes the `summary` property of the body field (core `text_with_summary`). Many headless sites instead use a dedicated summary/deck field for teasers and meta descriptions; on those, set that field in `fields` — a value written here will be stored but may never be rendered." },
-        format:  { type: "string", description: "Text format machine name for the body, e.g. 'basic_html'. Defaults to the site config's `defaultTextFormat`, then 'full_html'. Set this when the site's formats do not include full_html, or to avoid writing content into a more permissive format than intended." },
+        summary: { type: "string", description: "Body summary/teaser — writes body.summary on core text_with_summary only. Refused when the sampled body field has no summary property (text_long / text_formatted) or the schema cannot be determined. Prefer the site's dedicated deck/summary field via `fields`." },
+        format:  { type: "string", description: "Text format machine name for the body, e.g. 'basic_html'. When the body field's allowed_formats lists exactly one format, that is the default. A caller format outside that list is refused before write. When allowed_formats cannot be resolved, defaults to the site config's `defaultTextFormat`, then 'full_html'." },
         status:  { type: "boolean", description: "Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set." },
         moderationState: { type: "string", description: "Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status. Required to keep or re-publish a live node — omitting it on a published moderated node defaults the write to 'draft'." },
-        fields:  { type: "object", description: "Scalar/attribute field values keyed by machine name. Entity-reference fields go in `relationships`, not here." },
+        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. The probe uses a non-matching data.id so Drupal does not save. A working-copy 400 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. The probe uses a non-matching data.id so Drupal does not save, and hits the same URL as the real write (canonical, or ?resourceVersion=rel:working-copy when a draft is addressable). A working-copy 400 fails the dryRun." },
         returning: RETURNING_SCHEMA,
       },
     },