drupal-mcp-connector 3.2.0 → 3.2.1

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.1] - 2026-10-07
+
+### Fixed
+- **Text formats from Sentinel context (#429).** Node writes read
+  `allowed_formats` from `GET /drupal-mcp/context` when JSON:API field
+  config is not readable. A present list is enforced, including a
+  one-element `{ value, format }` array. A missing key stays an unknown
+  list, so an older Sentinel still passes an explicit format through.
+  Entity, translation, bulk, paragraph, and media writes use the same
+  check and do not invent `full_html` for a string body. A JSON:API row
+  whose field name does not match the request is ignored. A context miss
+  is remembered for 30 seconds, and only tools that resolve text formats
+  wait on that document. Component drafts and nested paragraph children,
+  including their translations, are checked before preflight or create.
+  An update that sends a one-element text array without a format reuses
+  the stored format. Hosts stay on the previous behavior until Sentinel
+  2.32.0, which emits the key, is deployed.
+
+### Added
+- **Consumers pin a version and check advisories before upgrade (#423).**
+  The README tells operators to pin an exact version, confirm the registry
+  integrity checksum, read the changelog, and run `npm audit --omit=dev`
+  before upgrading. No separate scanner. The install and `npx` examples,
+  and the post-upgrade doctor command, name that same version.
+
 ## [3.2.0] - 2026-10-05
 
 ### Added

package/README.md

@@ -278,8 +278,8 @@ the allowlist or Sentinel profile excludes the type — run `doctor` and
 ### From npm (recommended for operators)
 
 ```bash
-npm install -g drupal-mcp-connector
-# or: npx -y drupal-mcp-connector
+npm install -g drupal-mcp-connector@3.2.1
+# or: npx -y drupal-mcp-connector@3.2.1
 ```
 
 Point your MCP client at the installed binary (path from `which drupal-mcp-connector`
@@ -287,6 +287,25 @@ or `node_modules/.bin/drupal-mcp-connector`). For multi-site or non-env config,
 clone the repo (or copy `config/config.example.json` beside a small launcher) and
 pass a config path — see **[docs/getting-started.md](docs/getting-started.md)**.
 
+### Before you upgrade
+
+Pin the version you run. Do not point a client you depend on at `latest` or an
+unbounded range.
+
+1. Pin an exact version in the lockfile (`package-lock.json` or
+   `npm-shrinkwrap.json`), or in `package.json` as
+   `"drupal-mcp-connector": "3.2.1"` (use the version you intend to run).
+2. Confirm the registry checksum before you install.
+   `npm view drupal-mcp-connector@3.2.1 dist.integrity` prints the integrity
+   npm checks. A lockfile install fails when the tarball does not match.
+3. Read [CHANGELOG.md](CHANGELOG.md) for that version.
+4. Run `npm audit --omit=dev` against the lockfile and read any advisory
+   before you upgrade. There is no separate scanner to install.
+
+Restart the MCP client after the upgrade. Run `drupal-mcp-doctor` when the
+package is on your PATH, or `npx -y drupal-mcp-connector@3.2.1 doctor` when
+you launch it with npx.
+
 ### From a git clone (development)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "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",

package/src/index.js

@@ -50,6 +50,7 @@ import { createLegacySessionHandler, createMcpRequestHandler } from "./lib/http-
 import { createConnectorServerFactory } from "./lib/mcp-server.js";
 import { createRateLimiter } from "./lib/rate-limit.js";
 import { callTool, invokeReadTool, listResolvableSiteConfigs } from "./lib/dispatch.js";
+import { fetchTextFormatContext, installTextFormatContextFetcher } from "./lib/text-format-context.js";
 import { filterDiscoverableTools } from "./lib/governance.js";
 import {
   filterPromptsByPrincipal,
@@ -75,6 +76,8 @@ import { builtinWorkflowProvider } from "./lib/workflows/builtin.js";
 import { runWizardCli } from "./lib/wizard.js";
 import { runDoctorCli } from "./lib/doctor.js";
 
+installTextFormatContextFetcher(fetchTextFormatContext);
+
 const cliCommand = process.argv[2];
 if (cliCommand === "wizard" || cliCommand === "init") {
   process.exit(await runWizardCli(process.argv.slice(3)));

package/src/lib/backends/jsonapi.js

@@ -884,7 +884,10 @@ export class JsonApiBackend extends Backend {
       try {
         const data = await drupalFetch(this.site, `/jsonapi/${resource}/${resource}?${params}`);
         const row = Array.isArray(data?.data) ? data.data[0] : data?.data;
-        return parseFieldConfigObject(row?.attributes, fieldName);
+        // A filter that is ignored would return some other field. Using that
+        // row's allowed_formats would persist the wrong format (#429).
+        if (row?.attributes?.field_name !== fieldName) return null;
+        return parseFieldConfigObject(row.attributes, fieldName);
       } catch {
         return null;
       }

package/src/lib/component-draft.js

@@ -16,6 +16,7 @@
 import { readNodeDraftInventory, assertDraftLangcode } from "./sentinel-draft.js";
 import { entityRevisionId } from "./write-revision.js";
 import { paragraphPinsFromEntity } from "./err-relationships.js";
+import { applyParagraphTextFormats } from "./field-definition.js";
 import { PREFLIGHT_SENTINEL_DRAFT, dryRunChecks } from "./dry-run-checks.js";
 
 /** Inventory operation: component paragraph changes inside a draft save. */
@@ -159,14 +160,19 @@ function pinMap(entity) {
  * @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]
+ * @param {{dryRun?: boolean, site?: object}} [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 } = {}) {
+export async function writeComponentDraft(backend, input, { dryRun = false, site = {} } = {}) {
   const { entityType, bundle, id, attributes = {}, relationships } = input;
   const components = normalizeComponents(input.components);
+  // Refuse a disallowed paragraph format before inventory or the draft preflight.
+  for (const component of components) {
+    const paragraphBundle = component.type.slice("paragraph--".length);
+    await applyParagraphTextFormats(backend, site, paragraphBundle, component.attributes);
+  }
   if (Object.hasOwn(attributes, "path")) {
     throw new Error("Aliases are not revisioned. Change the alias in a separate update; no write was attempted.");
   }

package/src/lib/dispatch.js

@@ -15,6 +15,7 @@ import { resolveSecurityConfig, assertNotReadOnly,
 import { toolError, toolResult } from "./errors.js";
 import { BackendCapabilityError, BackendResolutionError } from "./backends/errors.js";
 import { inferOperation } from "./operations.js";
+import { ensureTextFormatContext, toolNeedsTextFormatContext } from "./text-format-context.js";
 import { assertSourceGovernance, GovernanceError } from "./governance.js";
 import {
   assertPrincipalEntitlement, callerTargetHints, DIAGNOSTIC_TOOLS,
@@ -186,6 +187,12 @@ export async function securityMiddleware(toolName, args, handler, context = {})
   });
   return runWithDataFlow(flow, async () => {
     await assertCallAllowed();
+    // Content-tier tokens cannot read field_config. Load Sentinel's schema
+    // before a handler that resolves text formats (#429). Other writes do
+    // not wait. A miss leaves the historical unknown-list path in place.
+    if (toolNeedsTextFormatContext(toolName)) {
+      await ensureTextFormatContext(site);
+    }
     // Charge only after governance and policy gates pass, so an outage or a
     // local deny cannot exhaust the window. Diagnostics do not consume.
     if (!DIAGNOSTIC_TOOLS.has(toolName)) {

package/src/lib/field-definition.js

@@ -11,10 +11,15 @@
  *      `base_field_override` (node body is a base field; its allowed_formats
  *      are not on `field_config`). Internal adapter fetch, not
  *      `drupal_entity_get` (`field_config` is on the agent deny list).
- *   2. Drush `config:get field.field.{entityType}.{bundle}.{field}`, then
+ *      A row whose `field_name` is not the requested field is a miss.
+ *   2. Cached Sentinel `GET /drupal-mcp/context`, for node bundles, when the
+ *      field entry includes `allowed_formats` (#429). A content-tier token
+ *      cannot read `field_config`. Dispatch fills this cache before a tool
+ *      that resolves text formats.
+ *   3. Drush `config:get field.field.{entityType}.{bundle}.{field}`, then
  *      `core.base_field_override.{entityType}.{bundle}.{field}`, when a Drush
  *      bridge is configured.
- *   3. If the definition cannot be resolved: return null. Creates keep the
+ *   4. If the definition cannot be resolved: return null. Creates keep the
  *      historical default chain only while the list is unknown. Updates reuse
  *      the format already stored on that field (#327) so a dry run cannot
  *      preview a fallback the save will reject. Once the list is known, never
@@ -22,6 +27,7 @@
  */
 
 import { drushConfigured } from "./audit-sources.js";
+import { textFormatDefinitionFromContext } from "./text-format-context.js";
 import { validateMachineName } from "./validate.js";
 import { parseDrush, sshDrush } from "../tools/drush.js";
 
@@ -137,15 +143,19 @@ export async function resolveFieldDefinition(backend, site, entityType, bundle,
   if (typeof backend?.getFieldDefinition === "function") {
     try {
       const def = await backend.getFieldDefinition({ entityType, bundle, fieldName });
-      if (def) return parseFieldConfigObject({
-        field_name: def.fieldName,
-        field_type: def.fieldType,
-        settings: { allowed_formats: def.allowedFormats },
-      }, fieldName) ?? def;
+      if (def?.fieldName === fieldName) {
+        return parseFieldConfigObject({
+          field_name: def.fieldName,
+          field_type: def.fieldType,
+          settings: { allowed_formats: def.allowedFormats },
+        }, fieldName) ?? def;
+      }
     } catch {
-      // JSON:API field_config is optional; try Drush next.
+      // JSON:API field_config is optional; try the next source.
     }
   }
+  const fromContext = textFormatDefinitionFromContext(site, entityType, bundle, fieldName);
+  if (fromContext) return fromContext;
   if (drushConfigured(site)) {
     const def = await fieldDefinitionFromDrush(site, entityType, bundle, fieldName);
     if (def) return def;
@@ -242,8 +252,19 @@ function requestedFormatOf(value) {
   return undefined;
 }
 
+/**
+ * @param {*} value
+ * @returns {string|undefined}
+ */
+function storedFormatName(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const format = new Map(Object.entries(value)).get("format");
+  return typeof format === "string" && format && format !== "0" ? format : undefined;
+}
+
 /**
  * Format Drupal already stored for a field, if the canonical entity has one.
+ * A one-element list is the JSON:API shape of a single-value text field.
  * @param {?object} entity
  * @param {string} fieldName
  * @returns {string|undefined}
@@ -252,9 +273,31 @@ function storedTextFormat(entity, fieldName) {
   const fields = entity?.fields;
   if (!fields || typeof fields !== "object" || Array.isArray(fields)) return undefined;
   const value = new Map(Object.entries(fields)).get(fieldName);
-  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-  const format = new Map(Object.entries(value)).get("format");
-  return typeof format === "string" && format && format !== "0" ? format : undefined;
+  if (Array.isArray(value)) {
+    if (value.length !== 1) return undefined;
+    return storedFormatName(value.at(0));
+  }
+  return storedFormatName(value);
+}
+
+/**
+ * A one-element JSON:API list omits its format when the only item is a
+ * string or a `{ value }` object without `format`. A longer list of bare
+ * strings is a list field, not an omitted text format. A formatted item
+ * inside a longer list still counts.
+ * @param {unknown[]} value
+ * @returns {boolean}
+ */
+function arrayOmitsTextFormat(value) {
+  if (value.length === 1) {
+    const item = value.at(0);
+    if (typeof item === "string") return true;
+    if (!item || typeof item !== "object" || Array.isArray(item)) return false;
+    const hasValue = Object.prototype.hasOwnProperty.call(item, "value");
+    const hasFormat = Object.prototype.hasOwnProperty.call(item, "format") && item.format;
+    return hasValue && !hasFormat;
+  }
+  return value.some((item) => isFormattedShape(item) && !requestedFormatOf(item));
 }
 
 /**
@@ -267,8 +310,12 @@ export function attributesOmitTextFormat(attributes) {
   if (!attributes || typeof attributes !== "object") return false;
   for (const [name, value] of Object.entries(attributes)) {
     if (SKIP_FORMAT_FIELDS.has(name) || value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      if (arrayOmitsTextFormat(value)) return true;
+      continue;
+    }
     if (typeof value === "string") return true;
-    if (typeof value === "object" && !Array.isArray(value)) {
+    if (typeof value === "object") {
       const hasValue = Object.prototype.hasOwnProperty.call(value, "value");
       const hasFormat = Object.prototype.hasOwnProperty.call(value, "format") && value.format;
       if ((name === "body" || hasValue) && !hasFormat) return true;
@@ -294,6 +341,44 @@ function normalizeFormattedValue(raw, format) {
   return out;
 }
 
+/**
+ * Resolve one formatted value, or return it unchanged when it is not text.
+ * @param {string} fieldName
+ * @param {*} value
+ * @param {?object} def
+ * @param {boolean} treatAsBody
+ * @param {object} site
+ * @param {?object} existingEntity
+ * @returns {*}
+ */
+function resolveFormattedItem(fieldName, value, def, treatAsBody, site, existingEntity) {
+  const formattedType = Boolean(def?.fieldType && FORMATTED_FIELD_TYPES.has(def.fieldType));
+  const restricted = Boolean(def?.allowedFormats?.length);
+  const shaped = isFormattedShape(value);
+  if (typeof value !== "string" && (typeof value !== "object" || value === null || Array.isArray(value))) {
+    return value;
+  }
+  if (def && !formattedType && !restricted && !treatAsBody) return value;
+  if (!def && !shaped && !treatAsBody) return value;
+
+  const allowedFormats = def ? def.allowedFormats : null;
+  const listUnknown = !Array.isArray(allowedFormats) || allowedFormats.length === 0;
+  let requested = requestedFormatOf(value);
+  if ((requested === undefined || requested === null || requested === "") && listUnknown) {
+    const stored = storedTextFormat(existingEntity, fieldName);
+    if (stored) requested = stored;
+  }
+  const format = resolveTextFormat({
+    fieldName,
+    requested,
+    allowedFormats,
+    site,
+    defaultWhenUnknown: treatAsBody,
+  });
+  if (format === undefined && !formattedType && !treatAsBody && !shaped) return value;
+  return normalizeFormattedValue(value, format);
+}
+
 /**
  * Default and validate text formats on a write attribute map (mutates it).
  * Same checks run for dry-run and real writes so a disallowed format never
@@ -303,46 +388,66 @@ function normalizeFormattedValue(raw, format) {
  * caller omitted a format, the format already stored on that field is reused.
  * The same choice is what dryRun previews and what the save sends (#327).
  *
- * @param {{backend: object, site: object, entityType: string, bundle: string, attributes: object, existingEntity?: ?object}} input
+ * `defaultBodyFormat` is true for the node tools, which keep the historical
+ * body fallback when the list is unknown. Other write tools pass false so a
+ * string body is not rewritten to `full_html`.
+ *
+ * A one-element array is checked too (#429). Callers sometimes send the
+ * JSON:API list shape for a single-value text field; skipping the array let
+ * a disallowed format through. An update that omits the format on that
+ * one-element shape reuses the stored format when the allowed list is unknown.
+ *
+ * @param {{backend: object, site: object, entityType: string, bundle: string, attributes: object, existingEntity?: ?object, defaultBodyFormat?: boolean}} input
  * @returns {Promise<object>} The same attributes object, with formats resolved.
  */
 export async function applyAllowedFormatsToAttributes({
   backend, site, entityType, bundle, attributes, existingEntity = null,
+  defaultBodyFormat = true,
 }) {
   const names = Object.keys(attributes).filter((name) => !SKIP_FORMAT_FIELDS.has(name));
   for (const fieldName of names) {
     const value = new Map(Object.entries(attributes)).get(fieldName);
     if (value === undefined || value === null) continue;
-    if (typeof value !== "string" && (typeof value !== "object" || Array.isArray(value))) continue;
-
+    if (!Array.isArray(value) && typeof value !== "string" && typeof value !== "object") continue;
+    const treatAsBody = defaultBodyFormat && fieldName === "body";
     const def = await resolveFieldDefinition(backend, site, entityType, bundle, fieldName);
-    const formattedType = Boolean(def?.fieldType && FORMATTED_FIELD_TYPES.has(def.fieldType));
-    const restricted = Boolean(def?.allowedFormats?.length);
-    const isBody = fieldName === "body";
-    const shaped = isFormattedShape(value);
-
-    if (def && !formattedType && !restricted && !isBody) continue;
-    if (!def && !shaped && !isBody) continue;
-
-    const allowedFormats = def ? def.allowedFormats : null;
-    const listUnknown = !Array.isArray(allowedFormats) || allowedFormats.length === 0;
-    let requested = requestedFormatOf(value);
-    if ((requested === undefined || requested === null || requested === "") && listUnknown) {
-      const stored = storedTextFormat(existingEntity, fieldName);
-      if (stored) requested = stored;
+    if (Array.isArray(value)) {
+      const formattedType = Boolean(def?.fieldType && FORMATTED_FIELD_TYPES.has(def.fieldType));
+      const restricted = Boolean(def?.allowedFormats?.length);
+      const anyShaped = value.some((item) => isFormattedShape(item));
+      if (!formattedType && !restricted && !treatAsBody && !anyShaped) continue;
+      const next = value.map((item) => resolveFormattedItem(
+        fieldName, item, def, treatAsBody, site, existingEntity,
+      ));
+      Object.assign(attributes, Object.fromEntries([[fieldName, next]]));
+      continue;
+    }
+    if (typeof value !== "string" && typeof value !== "object") continue;
+    const next = resolveFormattedItem(fieldName, value, def, treatAsBody, site, existingEntity);
+    if (next !== value) {
+      Object.assign(attributes, Object.fromEntries([[fieldName, next]]));
     }
-    const format = resolveTextFormat({
-      fieldName,
-      requested,
-      allowedFormats,
-      site,
-      defaultWhenUnknown: isBody,
-    });
-
-    if (format === undefined && !formattedType && !isBody && !shaped) continue;
-    Object.assign(attributes, Object.fromEntries([
-      [fieldName, normalizeFormattedValue(value, format)],
-    ]));
   }
   return attributes;
 }
+
+/**
+ * Validate text formats on caller-supplied paragraph attributes.
+ * Paragraph writes do not invent `full_html`. Do not pass attributes copied
+ * from an existing paragraph: those already have the stored format.
+ * @param {object} backend
+ * @param {object} site
+ * @param {string} bundle Paragraph bundle machine name.
+ * @param {object} attributes Mutated in place.
+ * @returns {Promise<object>}
+ */
+export function applyParagraphTextFormats(backend, site, bundle, attributes) {
+  return applyAllowedFormatsToAttributes({
+    backend,
+    site,
+    entityType: "paragraph",
+    bundle,
+    attributes,
+    defaultBodyFormat: false,
+  });
+}

package/src/lib/nested-draft.js

@@ -21,6 +21,7 @@ import { entityRevisionId } from "./write-revision.js";
 import { embedParagraphRef, paragraphRevisionId } from "./err-relationships.js";
 import { httpStatusOf } from "./error-status.js";
 import { OPEN_DRAFT_OPERATION, MIN_SENTINEL_COMPONENTS_VERSION, valueMatches } from "./component-draft.js";
+import { applyParagraphTextFormats } from "./field-definition.js";
 import { PREFLIGHT_NONE, PREFLIGHT_SENTINEL_DRAFT, dryRunChecks } from "./dry-run-checks.js";
 
 export const NESTED_DRAFT_PARTIAL_CODE = "NESTED_DRAFT_PARTIAL";
@@ -84,11 +85,14 @@ export function nestedDraftUncertain(detail, prepared) {
 /**
  * @param {object} backend
  * @param {object} input
- * @param {{dryRun?: boolean, assertParagraphCreate?: (bundle: string) => void}} [options]
+ * @param {{dryRun?: boolean, assertParagraphCreate?: (bundle: string) => void, site?: object}} [options]
  * @returns {Promise<object>}
  */
-export async function draftNestedComponents(backend, input, { dryRun = false, assertParagraphCreate } = {}) {
+export async function draftNestedComponents(backend, input, { dryRun = false, assertParagraphCreate, site = {} } = {}) {
   const spec = normalizeNestedInput(input);
+  // Caller-supplied children and translations only. Copied parent fields are
+  // the stored paragraph, not a new format choice, and are left unchanged.
+  await applyCallerParagraphFormats(backend, site, spec.children);
   const inventory = await readNodeDraftInventory(backend, spec);
   if (!inventory) {
     throw new Error(
@@ -730,9 +734,21 @@ function assertChildren(children, childPins, requiredLangs) {
 }
 
 /**
- * @param {object} child
- * @param {Set<string>} requiredLangs
+ * @param {object} backend
+ * @param {object} site
+ * @param {object[]} children
+ * @returns {Promise<void>}
  */
+async function applyCallerParagraphFormats(backend, site, children) {
+  for (const child of children) {
+    if (child.op === "keep") continue;
+    await applyParagraphTextFormats(backend, site, child.type, child.attributes);
+    for (const translation of child.translations ?? []) {
+      await applyParagraphTextFormats(backend, site, child.type, translation.attributes);
+    }
+  }
+}
+
 function assertLangs(child, requiredLangs) {
   const supplied = new Set(child.translations.map((row) => row.langcode));
   for (const lang of requiredLangs) {

package/src/lib/text-format-context.js

@@ -0,0 +1,248 @@
+/**
+ * Text-format restrictions from MCP Sentinel's site schema (#429).
+ *
+ * A content-tier token cannot read JSON:API `field_config` (that needs
+ * "administer node fields") and this connector's production configs often
+ * have no Drush bridge. Sentinel's `GET /drupal-mcp/context` is the schema
+ * that token can read. When a field entry includes `allowed_formats`, that
+ * list is Field API's restriction: one entry is the default, any other
+ * format is refused. A missing key means an older Sentinel that does not
+ * report the restriction — the caller must not treat that as "all formats".
+ * An empty array means the field has no format restriction.
+ *
+ * Dispatch fills the process cache before a tool that resolves text formats.
+ * A failed fetch is remembered only briefly so a Sentinel outage does not
+ * add the timeout to every later write, and concurrent writes share one
+ * request. Unit tests that call handlers directly can seed a successful
+ * document with `rememberTextFormatContext`.
+ */
+
+import { authHeadersAsync, clientHeaders } from "./config.js";
+
+/** How long a successful context document is reused. */
+const CONTEXT_TTL_MS = 10 * 60 * 1000;
+
+/** How long a miss is remembered. Short, so a recovered Sentinel is retried. */
+const FAILURE_TTL_MS = 30 * 1000;
+
+/** Context fetch budget. A miss must not stall the write past this. */
+const CONTEXT_TIMEOUT_MS = 8000;
+
+/**
+ * Tools whose handlers call the text-format resolver. Other writes must not
+ * wait on this document.
+ */
+const TEXT_FORMAT_TOOLS = new Set([
+  "drupal_create_node",
+  "drupal_update_node",
+  "drupal_entity_create",
+  "drupal_entity_update",
+  "drupal_create_translation",
+  "drupal_bulk_create",
+  "drupal_bulk_update",
+  "drupal_create_paragraph",
+  "drupal_update_paragraph",
+  "drupal_create_media",
+  "drupal_update_media",
+  "drupal_draft_nested_components",
+]);
+
+/** @type {Map<string, {at: number, document: ?object, ttl: number}>} */
+const cache = new Map();
+
+/** @type {Map<string, {slot: object, promise: Promise<void>}>} */
+const inflight = new Map();
+
+/** @type {(site: object) => Promise<?object>} */
+let fetcher = async () => null;
+
+/**
+ * Cache key for one configured site. Name and base URL both matter so two
+ * sites that share a name in different processes cannot collide here, and a
+ * renamed base URL does not reuse the previous document.
+ * @param {object} site Resolved site config.
+ * @returns {string}
+ */
+function cacheKey(site) {
+  return `${site?._name ?? ""}\0${site?.baseUrl ?? ""}`;
+}
+
+/**
+ * Drop cached schema documents. Tests call this between cases.
+ * @returns {void}
+ */
+export function clearTextFormatContextCache() {
+  cache.clear();
+  inflight.clear();
+}
+
+/**
+ * Whether this tool resolves text formats and should wait for context.
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+export function toolNeedsTextFormatContext(toolName) {
+  return TEXT_FORMAT_TOOLS.has(toolName);
+}
+
+/**
+ * Seed the cache without a network call. A seeded document uses the success TTL.
+ * @param {object} site Resolved site config.
+ * @param {object} document Sentinel context JSON.
+ * @returns {void}
+ */
+export function rememberTextFormatContext(site, document) {
+  cache.set(cacheKey(site), { at: Date.now(), document, ttl: CONTEXT_TTL_MS });
+}
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function fresh(key) {
+  const hit = cache.get(key);
+  if (!hit) return false;
+  return Date.now() - hit.at < hit.ttl;
+}
+
+/**
+ * Install the process fetcher. The server entry calls this with
+ * {@link fetchTextFormatContext}. Tests leave the default, which returns
+ * null and does not touch the network.
+ * @param {(site: object) => Promise<?object>} next
+ * @returns {void}
+ */
+export function installTextFormatContextFetcher(next) {
+  fetcher = next;
+}
+
+/**
+ * Load `GET /drupal-mcp/context` when the cache is cold. A failure is cached
+ * as a miss for 30 seconds: the write keeps the historical path
+ * for an unknown format list, and the next write does not wait again.
+ * Concurrent callers share one in-flight request.
+ * @param {object} site Resolved site config.
+ * @returns {Promise<void>}
+ */
+export async function ensureTextFormatContext(site) {
+  if (!site?.baseUrl) return;
+  const key = cacheKey(site);
+  if (fresh(key)) return;
+  const pending = inflight.get(key);
+  if (pending) {
+    await pending.promise;
+    return;
+  }
+  // Identity is a plain object. Comparing the promise itself is what CodeQL
+  // reports as a missing await.
+  const slot = {};
+  const promise = loadTextFormatContext(site, key);
+  inflight.set(key, { slot, promise });
+  try {
+    await promise;
+  } finally {
+    const row = inflight.get(key);
+    if (row?.slot === slot) inflight.delete(key);
+  }
+}
+
+/**
+ * @param {object} site
+ * @param {string} key
+ * @returns {Promise<void>}
+ */
+async function loadTextFormatContext(site, key) {
+  let document = null;
+  try {
+    const loaded = await fetcher(site);
+    if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) document = loaded;
+  } catch {
+    document = null;
+  }
+  cache.set(key, {
+    at: Date.now(),
+    document,
+    ttl: document ? CONTEXT_TTL_MS : FAILURE_TTL_MS,
+  });
+}
+
+/**
+ * GET /drupal-mcp/context as the site's own principal.
+ * @param {object} site Resolved site config.
+ * @returns {Promise<?object>} The JSON document, or null on any miss.
+ */
+export async function fetchTextFormatContext(site) {
+  let headers;
+  try {
+    headers = {
+      Accept: "application/json",
+      ...clientHeaders(),
+      ...(await authHeadersAsync(site)),
+    };
+  } catch {
+    return null;
+  }
+  let res;
+  try {
+    res = await fetch(`${site.baseUrl}/drupal-mcp/context`, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(CONTEXT_TIMEOUT_MS),
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+  try {
+    const body = await res.json();
+    if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+    if (!Object.prototype.hasOwnProperty.call(body, "content_types")) return null;
+    return body;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Field definition from a cached context document.
+ * Only node bundles are present. A field with no `allowed_formats` key is
+ * unknown (older Sentinel), not unrestricted.
+ * @param {object} site Resolved site config.
+ * @param {string} entityType
+ * @param {string} bundle
+ * @param {string} fieldName
+ * @returns {?{fieldName: string, fieldType: ?string, allowedFormats: string[]}}
+ */
+export function textFormatDefinitionFromContext(site, entityType, bundle, fieldName) {
+  if (entityType !== "node") return null;
+  const hit = cache.get(cacheKey(site));
+  // A cached miss (document null) is not a schema. Do not invent a list.
+  if (!hit?.document || !fresh(cacheKey(site))) return null;
+  const types = hit.document?.content_types;
+  if (!types || typeof types !== "object" || Array.isArray(types)) return null;
+  const schema = new Map(Object.entries(types)).get(bundle);
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return null;
+  const fields = new Map(Object.entries(schema)).get("fields");
+  if (!fields || typeof fields !== "object" || Array.isArray(fields)) return null;
+  const field = new Map(Object.entries(fields)).get(fieldName);
+  if (!field || typeof field !== "object" || Array.isArray(field)) return null;
+  const attrs = new Map(Object.entries(field));
+  if (!attrs.has("allowed_formats")) return null;
+  const fieldType = attrs.get("type");
+  return {
+    fieldName,
+    fieldType: typeof fieldType === "string" ? fieldType : null,
+    allowedFormats: normalizeContextFormats(attrs.get("allowed_formats")),
+  };
+}
+
+/**
+ * @param {*} raw `allowed_formats` from the context document.
+ * @returns {string[]}
+ */
+function normalizeContextFormats(raw) {
+  const values = Array.isArray(raw)
+    ? raw
+    : (raw && typeof raw === "object" ? [...new Map(Object.entries(raw)).values()] : []);
+  return values.filter((value) => typeof value === "string" && value !== "" && value !== "0");
+}

package/src/tools/bulk.js

@@ -21,6 +21,7 @@ import {
   resolveParagraphRevisionId, missingParagraphRevisionError,
 } from "../lib/err-relationships.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
 
 /**
  * Normalize an unknown thrown value into a human-readable message.
@@ -53,11 +54,15 @@ async function bulkCreate({ site: siteName, entityType, bundle, items = [] }) {
   for (const [index, rawItem] of items.entries()) {
     const item = rawItem || {};
     try {
-      assertPublishAllowed(sec, item.attributes ?? {});
+      const formatted = await applyAllowedFormatsToAttributes({
+        backend, site, entityType, bundle, attributes: { ...(item.attributes ?? {}) },
+        defaultBodyFormat: false,
+      });
+      assertPublishAllowed(sec, formatted);
       const resolvedRelationships = await resolveErrRelationships(backend, item.relationships ?? {});
       const entity = await backend.createEntity({
         entityType, bundle,
-        attributes: withUnpublishedDefault(sec, entityType, item.attributes ?? {}),
+        attributes: withUnpublishedDefault(sec, entityType, formatted),
         relationships: resolvedRelationships,
       });
       created += 1;
@@ -107,9 +112,13 @@ async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
       const existing = await readUpdateTarget(backend, {
         entityType, bundle, id: item.id, attributes: item.attributes ?? {},
       });
+      const formatted = await applyAllowedFormatsToAttributes({
+        backend, site, entityType, bundle, attributes: { ...(item.attributes ?? {}) },
+        existingEntity: existing, defaultBodyFormat: false,
+      });
       const attributes = await applySafeDraftDefault({
         backend, entityType, bundle, id: item.id,
-        attributes: item.attributes ?? {},
+        attributes: formatted,
         existingEntity: existing,
       });
       assertPublishAllowed(sec, attributes);

package/src/tools/entities.js

@@ -19,6 +19,7 @@ import {
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 import { readUpdateTarget } from "../lib/canonical-draft.js";
+import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
 import { dryRunChecks, PREFLIGHT_NONE } from "../lib/dry-run-checks.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
@@ -70,9 +71,12 @@ async function createEntity({ site: siteName, entityType, bundle, attributes: ca
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", entityType, bundle);
-  assertPublishAllowed(sec, callerAttributes);
-  const attributes = withUnpublishedDefault(sec, entityType, callerAttributes);
   const backend = await resolveBackend(site);
+  const formatted = await applyAllowedFormatsToAttributes({
+    backend, site, entityType, bundle, attributes: { ...callerAttributes }, defaultBodyFormat: false,
+  });
+  assertPublishAllowed(sec, formatted);
+  const attributes = withUnpublishedDefault(sec, entityType, formatted);
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
   if (dryRun) {
     return {
@@ -113,8 +117,12 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   // unrequested-status-change flag. Skipped when the caller pinned the
   // moderation state explicitly (same condition the draft default uses).
   const existing = await readUpdateTarget(backend, { entityType, bundle, id, attributes });
+  const formatted = await applyAllowedFormatsToAttributes({
+    backend, site, entityType, bundle, attributes: { ...attributes }, existingEntity: existing,
+    defaultBodyFormat: false,
+  });
   const safeAttributes = await applySafeDraftDefault({
-    backend, entityType, bundle, id, attributes, existingEntity: existing,
+    backend, entityType, bundle, id, attributes: formatted, existingEntity: existing,
   });
   assertPublishAllowed(sec, safeAttributes);
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);

package/src/tools/media.js

@@ -19,6 +19,7 @@ import {
 } from "../lib/sentinel-draft.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
 import { entityRevisionId } from "../lib/write-revision.js";
+import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
 
 /**
  * List all media types (bundles of the media entity type).
@@ -110,8 +111,11 @@ async function createMedia({ site: siteName, type, name, status = false, fields
   // Layer name/status after fields so they win, matching prior behaviour.
   attributes.name = name;
   attributes.status = status;
-  assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
+  await applyAllowedFormatsToAttributes({
+    backend, site, entityType: "media", bundle: type, attributes, defaultBodyFormat: false,
+  });
+  assertPublishAllowed(sec, attributes);
   return backend.createEntity({
     entityType: "media", bundle: type, attributes,
     ...(relationships ? { relationships } : {}),
@@ -134,8 +138,11 @@ async function updateMedia({ site: siteName, type, id, name, status, fields = {}
   const { attributes, relationships } = splitReferenceFields(fields);
   if (name !== undefined) attributes.name = name;
   if (status !== undefined) attributes.status = status;
-  assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
+  await applyAllowedFormatsToAttributes({
+    backend, site, entityType: "media", bundle: type, attributes, defaultBodyFormat: false,
+  });
+  assertPublishAllowed(sec, attributes);
   if (langcode) {
     const targetLang = assertDraftLangcode(langcode);
     const patchTarget = await prepareGuardedPatch(backend, {

package/src/tools/nested.js

@@ -29,6 +29,7 @@ async function draftNestedComponentsTool({
     liveRevisionId, resumeParentId,
   }, {
     dryRun,
+    site,
     assertParagraphCreate(paragraphBundle) {
       assertWriteAllowed(sec, "create", "paragraph", paragraphBundle);
     },

package/src/tools/nodes.js

@@ -516,7 +516,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
     const written = await writeComponentDraft(backend, {
       entityType: "node", bundle: type, id, attributes, relationships: resolvedRelationships,
       components: normalizedComponents, langcode,
-    }, { dryRun });
+    }, { dryRun, site });
     const shaped = dryRun ? written : shapeWriteResponse(written, returning);
     return summaryWrite.deprecated && bodyAttr ? attachSummaryDeprecation(shaped) : shaped;
   }

package/src/tools/paragraphs.js

@@ -35,6 +35,7 @@
  */
 
 import { getSiteConfig } from "../lib/config.js";
+import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertWriteAllowed, assertReadAllowed, redactCanonicalEntity,
@@ -93,7 +94,11 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", "paragraph", paragraphType);
   const backend = await resolveBackend(site);
-  const paragraph = await backend.createEntity({ entityType: "paragraph", bundle: paragraphType, attributes });
+  const formatted = await applyAllowedFormatsToAttributes({
+    backend, site, entityType: "paragraph", bundle: paragraphType,
+    attributes: { ...attributes }, defaultBodyFormat: false,
+  });
+  const paragraph = await backend.createEntity({ entityType: "paragraph", bundle: paragraphType, attributes: formatted });
   const bundle = paragraph.bundle || paragraphType;
   const revisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
   if (revisionId === null) throw missingParagraphRevisionError(paragraph.id);
@@ -122,6 +127,10 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "paragraph", paragraphType);
   const backend = await resolveBackend(site);
+  const formatted = await applyAllowedFormatsToAttributes({
+    backend, site, entityType: "paragraph", bundle: paragraphType,
+    attributes: { ...attributes }, defaultBodyFormat: false,
+  });
   let paragraph;
   if (langcode) {
     const targetLang = assertDraftLangcode(langcode);
@@ -132,11 +141,11 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
       throw new Error("Paragraph translation update requires a paragraph revision ID (the host pin).");
     }
     paragraph = await writeDraft(backend, {
-      entityType: "paragraph", bundle: paragraphType, id, attributes, langcode: targetLang, draftState,
+      entityType: "paragraph", bundle: paragraphType, id, attributes: formatted, langcode: targetLang, draftState,
       draftRevision: { revisionId: pinned },
     });
   } else {
-    paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
+    paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes: formatted });
   }
   const bundle = paragraph.bundle || paragraphType;
   const resolvedRevisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);

package/src/tools/translations.js

@@ -28,6 +28,7 @@ import {
 } from "../lib/security.js";
 import { validateUuid, validateMachineName } from "../lib/validate.js";
 import { applySafeDraftDefault } from "../lib/moderation-default.js";
+import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
 import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 import { entityRevisionId } from "../lib/write-revision.js";
 import { paragraphRevisionId } from "../lib/err-relationships.js";
@@ -160,7 +161,10 @@ async function createTranslation({
   }
 
   let draftRevision;
-  let drafted = { ...attributes };
+  let drafted = await applyAllowedFormatsToAttributes({
+    backend, site, entityType, bundle: type, attributes: { ...attributes }, existingEntity: existing,
+    defaultBodyFormat: false,
+  });
   delete drafted.langcode;
   if (entityType === "paragraph") {
     const pinned = revisionId ?? paragraphRevisionId(existing);