drupal-mcp-connector 2.7.3 → 2.8.0

package/src/tools/config.js

@@ -107,7 +107,7 @@ function inferTier(site, sec) {
  * @param {object} args - { site? }.
  * @returns {Promise<object>} Effective identity + capability summary.
  */
-async function whoami({ site: siteName }) {
+async function whoami({ site: siteName, _resolvedSource }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   const summary = getSecuritySummary(site);
@@ -119,9 +119,12 @@ async function whoami({ site: siteName }) {
   const canWrite  = !sec.readOnly && hasScope(site, "mcp_write");
   const canConfig = hasScope(site, "mcp_config");
   const identity = getRequestIdentity();
+  // Dispatch may inject `site` after a default/grant resolution. Prefer the
+  // authoritative source so `target` and `_target` cannot disagree (#167).
+  const source = _resolvedSource ?? (siteName ? "hint" : "default");
   return {
     site: site._name,
-    target: describeTarget(site, siteName ? "hint" : "default"),
+    target: describeTarget(site, source),
     principal: identity
       ? { sub: identity.sub, clientId: identity.clientId, scopes: [...(identity.scopes ?? [])] }
       : null,

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.
@@ -37,14 +38,34 @@ import * as reportsConfig  from "./reports-config.js";
 import * as reportsContent from "./reports-content.js";
 import * as auditComposite from "./audit-composite.js";
 import * as config       from "./config.js";
+import { SITE_PARAM } from "../lib/site-target.js";
 
 export const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
   revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra,
   reportsLinks, reportsConfig, reportsContent, auditComposite, config];
 
+/**
+ * Stamp the shared `site` description onto every tool that accepts one so
+ * agents are not told "omit for the default" as if that meant production.
+ *
+ * @param {object} def Tool definition.
+ * @returns {object}
+ */
+function withSiteParam(def) {
+  const props = def.inputSchema?.properties;
+  if (!props?.site) return def;
+  return {
+    ...def,
+    inputSchema: {
+      ...def.inputSchema,
+      properties: { ...props, site: { ...props.site, ...SITE_PARAM } },
+    },
+  };
+}
+
 // Flatten every module's tool definitions into one ListTools payload, and merge
 // their handler maps into a single closed dispatch table keyed by tool name.
-export const allDefinitions = allModules.flatMap((m) => m.definitions);
+export const allDefinitions = allModules.flatMap((m) => m.definitions).map(withSiteParam);
 export const allHandlers    = Object.assign({}, ...allModules.map((m) => m.handlers));
 
 // Fast name → definition lookup for prompt/command rendering.

package/src/tools/moderation.js

@@ -20,6 +20,25 @@ import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertPublishAllowed,
   redactCanonicalEntity,
 } from "../lib/security.js";
+import { collectEntities } from "../lib/reports-support.js";
+
+/** Cap for the client-side scan when JSON:API cannot filter the field. */
+const SAMPLE_CAP = 500;
+
+/**
+ * Drupal core JSON:API cannot filter on the computed `moderation_state`
+ * field. The error is a 500 whose detail is `'moderation_state' not found`
+ * (#162). jsonapi_extras (or a similar alias) can make the field filterable;
+ * those sites never hit this.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isUnfilterableModerationState(err) {
+  const msg = String(err?.message || "");
+  if (!/moderation_state/i.test(msg)) return false;
+  return /not found/i.test(msg) || /not filterable/i.test(msg) || /invalid filter/i.test(msg);
+}
 
 /** Read a node's moderation_state from a canonical entity, tolerating shapes. */
 function moderationStateOf(entity) {
@@ -49,6 +68,12 @@ async function setModerationState({ site: siteName, type, id, state }) {
 
 /**
  * List nodes of a type in a given moderation state, paged + redacted.
+ *
+ * Stock JSON:API cannot filter on the computed `moderation_state` field
+ * (#162). When the site accepts the filter (jsonapi_extras or similar) the
+ * result is exact. Otherwise we scan a bounded recent set and filter
+ * client-side rather than surfacing Drupal's 500 as a transient error.
+ *
  * @param {object} args - { site?, type, state, limit?, offset? }.
  */
 async function contentByModerationState({ site: siteName, type, state, limit = 20, offset = 0 }) {
@@ -56,14 +81,68 @@ async function contentByModerationState({ site: siteName, type, state, limit = 2
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
-  const res = await backend.listEntities({
-    entityType: "node", bundle: type,
-    filters: [{ field: "moderation_state", op: "eq", value: state }],
-    sort: [{ field: "changed", dir: "desc" }],
-    page: { limit, offset },
-  });
-  const nodes = res.entities.map((e) => redactCanonicalEntity(e, sec, "node"));
-  return { type, state, total: res.page?.total ?? nodes.length, approximate: res.approximate ?? false, offset, nextOffset: offset + nodes.length, nodes };
+  const sort = [{ field: "changed", dir: "desc" }];
+  const canFilter = typeof backend.capabilities === "function"
+    ? Boolean(backend.capabilities()?.filter)
+    : true;
+
+  if (canFilter) {
+    try {
+      const res = await backend.listEntities({
+        entityType: "node", bundle: type,
+        filters: [{ field: "moderation_state", op: "eq", value: state }],
+        sort,
+        page: { limit, offset },
+      });
+      const nodes = res.entities.map((e) => redactCanonicalEntity(e, sec, "node"));
+      return {
+        type, state, source: "filter",
+        total: res.page?.total ?? nodes.length,
+        approximate: res.approximate ?? false,
+        offset, nextOffset: offset + nodes.length, nodes,
+      };
+    } catch (err) {
+      if (!isUnfilterableModerationState(err)) throw err;
+    }
+  }
+
+  const scanned = await collectEntities(
+    backend,
+    { entityType: "node", bundle: type, sort },
+    SAMPLE_CAP,
+  );
+  const wanted = String(state).toLowerCase();
+  const matches = [];
+  let sawState = false;
+  for (const entity of scanned) {
+    const got = moderationStateOf(entity);
+    if (got === null || got === undefined) continue;
+    sawState = true;
+    if (String(got).toLowerCase() === wanted) matches.push(entity);
+  }
+  if (!sawState && scanned.length > 0) {
+    return {
+      type, state, unavailable: true, source: "sampled", scanned: scanned.length,
+      reason:
+        "moderation_state is not filterable over JSON:API on this site (it is a " +
+        "computed field) and no sampled entity exposed the field. Enable " +
+        "content_moderation on the bundle, or expose a filterable alias " +
+        "(jsonapi_extras).",
+    };
+  }
+  const page = matches.slice(offset, offset + limit);
+  return {
+    type, state, source: "sampled",
+    approximate: scanned.length >= SAMPLE_CAP,
+    scanned: scanned.length,
+    total: matches.length,
+    offset, nextOffset: offset + page.length,
+    nodes: page.map((e) => redactCanonicalEntity(e, sec, "node")),
+    note:
+      "Stock JSON:API cannot filter on moderation_state (computed field). " +
+      "Results are a client-side sample of recent nodes, not a complete list. " +
+      "A filterable alias (jsonapi_extras) makes this exact.",
+  };
 }
 
 /**
@@ -101,7 +180,7 @@ export const definitions = [
   },
   {
     name: "drupal_content_by_moderation_state",
-    description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review').",
+    description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review'). Stock JSON:API cannot filter the computed moderation_state field; when the site rejects that filter the tool samples recent nodes client-side and marks the result approximate, instead of returning Drupal's 500.",
     inputSchema: {
       type: "object", required: ["type", "state"],
       properties: {

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,
       },
     },

package/.claude/commands/drupal-audit-config-best-practices.md

@@ -1,16 +0,0 @@
----
-description: "Lint key configuration for production-readiness and security: on-screen error display, CSS/JS aggregation, anonymous page cache, open user registration, missing 404/403 pages, and insecure file uploads. Severity-ranked. Requires config-read access and the server-tool bridge."
-argument-hint: "[site]"
-allowed-tools: mcp__drupal__drupal_audit_config_best_practices
----
-
-Call the `mcp__drupal__drupal_audit_config_best_practices` MCP tool.
-
-Lint key configuration for production-readiness and security: on-screen error display, CSS/JS aggregation, anonymous page cache, open user registration, missing 404/403 pages, and insecure file uploads. Severity-ranked. Requires config-read access and the server-tool bridge.
-
-Parse the request in `$ARGUMENTS` into this tool's parameters:
-
-**Optional:**
-- `site` (string): omit for the default site
-
-If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.claude/commands/drupal-block-user.md

@@ -1,20 +0,0 @@
----
-description: "Block or unblock a Drupal user account without deleting it."
-argument-hint: "<id> [site] [block]"
-allowed-tools: mcp__drupal__drupal_block_user
----
-
-Call the `mcp__drupal__drupal_block_user` MCP tool.
-
-Block or unblock a Drupal user account without deleting it.
-
-Parse the request in `$ARGUMENTS` into this tool's parameters:
-
-**Required:**
-- `id` (string): User UUID
-
-**Optional:**
-- `site` (string): omit for the default site
-- `block` (boolean (true/false)): true = block, false = unblock
-
-If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.claude/commands/drupal-config-get.md

@@ -1,19 +0,0 @@
----
-description: "Read a single Drupal configuration object by name (e.g. \"system.site\") via the governed server-side config tool. Requires config read access."
-argument-hint: "<name> [site]"
-allowed-tools: mcp__drupal__drupal_config_get
----
-
-Call the `mcp__drupal__drupal_config_get` MCP tool.
-
-Read a single Drupal configuration object by name (e.g. "system.site") via the governed server-side config tool. Requires config read access.
-
-Parse the request in `$ARGUMENTS` into this tool's parameters:
-
-**Required:**
-- `name` (string)
-
-**Optional:**
-- `site` (string): omit for the default site
-
-If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.claude/commands/drupal-config-list.md

@@ -1,17 +0,0 @@
----
-description: "List Drupal configuration object names, optionally filtered by a name prefix, via the governed server-side config tool. Requires config read access."
-argument-hint: "[site] [prefix]"
-allowed-tools: mcp__drupal__drupal_config_list
----
-
-Call the `mcp__drupal__drupal_config_list` MCP tool.
-
-List Drupal configuration object names, optionally filtered by a name prefix, via the governed server-side config tool. Requires config read access.
-
-Parse the request in `$ARGUMENTS` into this tool's parameters:
-
-**Optional:**
-- `site` (string): omit for the default site
-- `prefix` (string)
-
-If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.claude/commands/drupal-config-set.md

@@ -1,20 +0,0 @@
----
-description: "Set a Drupal configuration value via the governed server-side config tool. Audited and gated server-side; requires the config-editor (Developer) tier. Then export to YAML for a PR."
-argument-hint: "<name> <value> [site]"
-allowed-tools: mcp__drupal__drupal_config_set
----
-
-Call the `mcp__drupal__drupal_config_set` MCP tool.
-
-Set a Drupal configuration value via the governed server-side config tool. Audited and gated server-side; requires the config-editor (Developer) tier. Then export to YAML for a PR.
-
-Parse the request in `$ARGUMENTS` into this tool's parameters:
-
-**Required:**
-- `name` (string)
-- `value` (object (pass as JSON)): A map of top-level config keys to their new values (e.g. { "slogan": "Information Technology" }). Other keys in the object are preserved server-side.
-
-**Optional:**
-- `site` (string): omit for the default site
-
-If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.claude/commands/drupal-content-by-moderation-state.md

@@ -1,22 +0,0 @@
----
-description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review')."
-argument-hint: "<type> <state> [site] [limit] [offset]"
-allowed-tools: mcp__drupal__drupal_content_by_moderation_state
----
-
-Call the `mcp__drupal__drupal_content_by_moderation_state` MCP tool.
-
-List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review').
-
-Parse the request in `$ARGUMENTS` into this tool's parameters:
-
-**Required:**
-- `type` (string): Content type machine name
-- `state` (string): Moderation state machine name
-
-**Optional:**
-- `site` (string): omit for the default site
-- `limit` (number)
-- `offset` (number)
-
-If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.claude/commands/drupal-create-block.md

@@ -1,21 +0,0 @@
----
-description: "Create a custom content block of a given block type (bundle). 'info' is the administrative label; 'body' is optional rendered HTML. Checked against the site security config."
-argument-hint: "<type> <info> [site] [body]"
-allowed-tools: mcp__drupal__drupal_create_block
----
-
-Call the `mcp__drupal__drupal_create_block` MCP tool.
-
-Create a custom content block of a given block type (bundle). 'info' is the administrative label; 'body' is optional rendered HTML. Checked against the site security config.
-
-Parse the request in `$ARGUMENTS` into this tool's parameters:
-
-**Required:**
-- `type` (string): Block type (bundle) machine name, e.g. 'basic'
-- `info` (string): Administrative label / block description
-
-**Optional:**
-- `site` (string): omit for the default site
-- `body` (string): Block body HTML (optional)
-
-If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.