drupal-mcp-connector 2.4.1 → 2.5.0

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

@@ -17,6 +17,6 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 **Optional:**
 - `site` (string): omit for the default site
 - `status` (boolean (true/false)): Published flag. Defaults to false (unpublished). Requires allowPublish when true.
-- `fields` (object (pass as JSON)): Additional field values — include the source field (e.g. field_media_oembed_video: 'https://youtu.be/...')
+- `fields` (object (pass as JSON)): Additional field values — include the source field (e.g. field_media_oembed_video: 'https://youtu.be/...'). Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically.
 
 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-update-media.md

@@ -1,12 +1,12 @@
 ---
-description: "Update a media entity's name, status, or field values."
+description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched."
 argument-hint: "<type> <id> [site] [name] [status] [fields]"
 allowed-tools: mcp__drupal__drupal_update_media
 ---
 
 Call the `mcp__drupal__drupal_update_media` MCP tool.
 
-Update a media entity's name, status, or field values.
+Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 
@@ -17,7 +17,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 **Optional:**
 - `site` (string): omit for the default site
 - `name` (string)
-- `status` (boolean (true/false))
-- `fields` (object (pass as JSON))
+- `status` (boolean (true/false)): Published flag. Only sent when provided; requires allowPublish when true.
+- `fields` (object (pass as JSON)): Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically.
 
 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/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-08-14
+
+### Fixed
+- **An unrequested published-state change is no longer silent (#171).**
+  `status` stays strictly opt-in on updates — the connector never adds it to a
+  PATCH — but a server-side gate can still flip it (an unmoderated-entity
+  publish backstop, or a write landing as an unpublished forward revision).
+  `drupal_entity_update`, `drupal_update_node`, and `drupal_update_media` now
+  compare the written state against a pre-write read and, when the caller sent
+  neither `status` nor an explicit moderation state, report a flip via a
+  `_statusChanged` marker (`from`/`to` plus a verification note) instead of
+  returning a clean success. The marker survives `returning: "minimal"`.
+  Regression tests pin that relationships-only and field-only updates send
+  neither `status` nor `moderation_state` across the entity, media, node, and
+  bulk update tools.
+- **Media tools route reference-shaped `fields` to relationships (#171).**
+  `drupal_update_media` and `drupal_create_media` forwarded entity-reference
+  values under `fields` as JSON:API attributes, which Drupal rejects with a 422
+  ("relationship fields were provided as attributes"). Values in linkage shape
+  (`{ data: { type, id } }`, an array of those, or `{ data: null }` to clear)
+  are now sent as relationships, matching what `drupal_entity_update` accepts;
+  composite attribute values (`{ value, format }` and friends) are untouched.
+  The linkage-shape helpers live in `src/lib/canonical.js` for reuse.
+
 ## [2.4.1] - 2026-08-14
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/canonical.js

@@ -66,3 +66,51 @@ export function normalizeRelationship(ref) {
   const [entityType = null, bundle = null] = (ref.type || "").split("--");
   return { id: ref.id, entityType, bundle };
 }
+
+/**
+ * Whether a field value is a JSON:API relationship linkage (`{ data: ... }`
+ * where data is null, one `{ type, id }` reference, or an array of them —
+ * an empty array clears a multi-value reference).
+ *
+ * Composite attribute values (e.g. `{ value, format }` text fields) have no
+ * `data` key and are never matched, so ordinary attributes pass through.
+ *
+ * @param {*} value A caller-supplied field value.
+ * @returns {boolean} True when the value is relationship-shaped.
+ */
+export function isRelationshipLinkage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  if (!Object.prototype.hasOwnProperty.call(value, "data")) return false;
+  const isRef = (d) => Boolean(d) && typeof d === "object" && !Array.isArray(d)
+    && typeof d.type === "string" && typeof d.id === "string";
+  const { data } = value;
+  if (data === null) return true;
+  if (Array.isArray(data)) return data.every(isRef);
+  return isRef(data);
+}
+
+/**
+ * Split a caller field map into JSON:API attributes and relationships (#171).
+ *
+ * Entity-reference values passed under a `fields` map used to be forwarded as
+ * attributes, which Drupal rejects with a 422 ("relationship fields were
+ * provided as attributes"). Relationship-shaped values are routed to the
+ * `relationships` document member instead, so field-map tools accept the same
+ * reference shape as `drupal_entity_update`.
+ *
+ * @param {object} fields Caller-supplied field map.
+ * @returns {{attributes: object, relationships: ?object}} Split maps;
+ *   `relationships` is null when no value was relationship-shaped.
+ */
+export function splitReferenceFields(fields) {
+  const attrEntries = [];
+  const relEntries = [];
+  for (const entry of Object.entries(fields)) {
+    const [, value] = entry;
+    (isRelationshipLinkage(value) ? relEntries : attrEntries).push(entry);
+  }
+  return {
+    attributes: Object.fromEntries(attrEntries),
+    relationships: relEntries.length ? Object.fromEntries(relEntries) : null,
+  };
+}

package/src/lib/entity-response.js

@@ -34,6 +34,47 @@ export function shapeWriteResponse(entity, returning = "full") {
   return out;
 }
 
+/**
+ * Flag a published-state change the caller never requested (#171).
+ *
+ * `status` is strictly opt-in on updates: the connector never adds it to a
+ * PATCH. A server-side gate can still flip it (e.g. a governance backstop
+ * unpublishing an unmoderated entity, or a write landing as an unpublished
+ * forward revision), and a silent success that also changed live state is the
+ * failure class that surfaces only when content goes missing. When a
+ * pre-write read is available and the sent attributes carry neither `status`
+ * nor `moderation_state` (an explicit moderation transition legitimately
+ * changes the published state, as does the #131 injected draft default), a
+ * different `status` in the write result is surfaced as `_statusChanged` — an
+ * `_`-prefixed key, so it survives `returning: "minimal"`.
+ *
+ * Best-effort by design: it requires a readable pre-write entity, and the
+ * server-side gate stays authoritative either way.
+ *
+ * @param {?object} result The entity returned by (or re-read after) the write.
+ * @param {?object} existing The pre-write entity, when it could be read.
+ * @param {object} sentAttributes The attribute map that was sent.
+ * @returns {?object} The result, with `_statusChanged` attached when it applies.
+ */
+export function flagUnrequestedStatusChange(result, existing, sentAttributes) {
+  if (!result || !existing) return result;
+  const sent = (key) => Object.prototype.hasOwnProperty.call(sentAttributes, key);
+  if (sent("status") || sent("moderation_state")) return result;
+  if (typeof existing.status !== "boolean" || typeof result.status !== "boolean") return result;
+  if (existing.status === result.status) return result;
+  return {
+    ...result,
+    _statusChanged: {
+      from: existing.status,
+      to: result.status,
+      note: "The returned published status differs from the pre-write state although the request did not " +
+        "include `status`. A server-side gate intervened — the write may have landed as an unpublished " +
+        "forward revision (live revision unchanged) or the entity may have been unpublished. Verify which " +
+        "revision is live before relying on this content's visibility.",
+    },
+  };
+}
+
 /** JSON Schema fragment for the shared `returning` parameter. */
 export const RETURNING_SCHEMA = {
   type: "string",

package/src/tools/entities.js

@@ -10,8 +10,8 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
-import { shapeWriteResponse, RETURNING_SCHEMA } from "../lib/entity-response.js";
-import { applySafeDraftDefault } from "../lib/moderation-default.js";
+import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
+import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
   redactCanonicalEntity, getSecuritySummary,
@@ -75,6 +75,10 @@ async function createEntity({ site: siteName, entityType, bundle, attributes = {
  * `moderation_state` get `moderation_state: draft` so the write is a forward
  * revision rather than a live default-revision mutation.
  *
+ * Live-state mediation (#171): `status` is never added to the PATCH unless the
+ * caller passed it, and an unrequested published-state flip in the write result
+ * is reported via `_statusChanged` rather than returned silently.
+ *
  * @param {object} args - { site?, entityType, bundle, id, attributes?, relationships? }.
  * @returns {Promise<object>} The updated entity descriptor.
  * @throws {SecurityError} If updating the type/bundle is not permitted.
@@ -84,12 +88,24 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", entityType, bundle);
   const backend = await resolveBackend(site);
+  // One pre-write read serves both the #131 draft default and the #171
+  // unrequested-status-change flag. Skipped when the caller pinned the
+  // moderation state explicitly (same condition the draft default uses).
+  let existing = null;
+  if (!hasExplicitModerationState(attributes)) {
+    try {
+      existing = (await backend.getEntity({ entityType, bundle, id })) ?? null;
+    } catch {
+      existing = null; // Unreadable target: server-side gates stay authoritative.
+    }
+  }
   const safeAttributes = await applySafeDraftDefault({
-    backend, entityType, bundle, id, attributes,
+    backend, entityType, bundle, id, attributes, existingEntity: existing,
   });
   assertPublishAllowed(sec, safeAttributes);
   if (dryRun) return { dryRun: true, operation: "update", entityType, bundle, id, attributes: safeAttributes, relationships };
-  return shapeWriteResponse(await backend.updateEntity({ entityType, bundle, id, attributes: safeAttributes, relationships }), returning);
+  const result = await backend.updateEntity({ entityType, bundle, id, attributes: safeAttributes, relationships });
+  return shapeWriteResponse(flagUnrequestedStatusChange(result, existing, safeAttributes), returning);
 }
 
 /**

package/src/tools/media.js

@@ -8,6 +8,8 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
+import { splitReferenceFields } from "../lib/canonical.js";
+import { flagUnrequestedStatusChange } from "../lib/entity-response.js";
 import {
   resolveSecurityConfig, redactCanonicalEntity,
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
@@ -62,9 +64,10 @@ async function getMedia({ site: siteName, type, id }) {
 }
 
 /**
- * Create a media entity. Caller `fields` are spread into attributes; name and
- * status are layered on top. Defaults to unpublished (`status: false`) so
- * media is never auto-published under non-publishing presets (#139).
+ * Create a media entity. Caller `fields` are split into attributes and
+ * relationship-shaped references (#171); name and status are layered on top of
+ * the attributes. Defaults to unpublished (`status: false`) so media is never
+ * auto-published under non-publishing presets (#139).
  *
  * @param {object} args - { site?, type, name, status?, fields? }.
  * @returns {Promise<object>} The created media descriptor.
@@ -73,17 +76,23 @@ async function createMedia({ site: siteName, type, name, status = false, fields
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", "media", type);
-  const attributes = { name, status, ...fields };
+  const { attributes, relationships } = splitReferenceFields(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);
-  return backend.createEntity({ entityType: "media", bundle: type, attributes });
+  return backend.createEntity({
+    entityType: "media", bundle: type, attributes,
+    ...(relationships ? { relationships } : {}),
+  });
 }
 
 /**
- * Update a media entity (partial — omitted fields are left untouched).
+ * Update a media entity (partial — omitted fields are left untouched; `status`
+ * is strictly opt-in, #171). Reference-shaped `fields` values are routed to
+ * relationships — see splitReferenceFields.
+ *
  * @param {object} args - { site?, type, id, name?, status?, fields? }.
  * @returns {Promise<object>} The updated media descriptor.
  */
@@ -91,12 +100,25 @@ async function updateMedia({ site: siteName, type, id, name, status, fields = {}
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "media", type);
-  const attributes = { ...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);
-  return backend.updateEntity({ entityType: "media", bundle: type, id, attributes });
+  // #171: pre-read so an unrequested published-state flip is reported, not silent.
+  let existing = null;
+  if (status === undefined) {
+    try {
+      existing = (await backend.getEntity({ entityType: "media", bundle: type, id })) ?? null;
+    } catch {
+      existing = null; // Unreadable target: server-side gates stay authoritative.
+    }
+  }
+  const result = await backend.updateEntity({
+    entityType: "media", bundle: type, id, attributes,
+    ...(relationships ? { relationships } : {}),
+  });
+  return flagUnrequestedStatusChange(result, existing, attributes);
 }
 
 /**
@@ -239,13 +261,13 @@ export const definitions = [
         type:   { type: "string", description: "Media type machine name" },
         name:   { type: "string", description: "Media entity name / label" },
         status: { type: "boolean", default: false, description: "Published flag. Defaults to false (unpublished). Requires allowPublish when true." },
-        fields: { type: "object", description: "Additional field values — include the source field (e.g. field_media_oembed_video: 'https://youtu.be/...')" },
+        fields: { type: "object", description: "Additional field values — include the source field (e.g. field_media_oembed_video: 'https://youtu.be/...'). Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically." },
       },
     },
   },
   {
     name: "drupal_update_media",
-    description: "Update a media entity's name, status, or field values.",
+    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -253,8 +275,8 @@ export const definitions = [
         type:   { type: "string" },
         id:     { type: "string" },
         name:   { type: "string" },
-        status: { type: "boolean" },
-        fields: { type: "object" },
+        status: { type: "boolean", description: "Published flag. Only sent when provided; requires allowPublish when true." },
+        fields: { type: "object", description: "Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically." },
       },
     },
   },

package/src/tools/nodes.js

@@ -13,8 +13,8 @@ import {
   resolveSecurityConfig, redactCanonicalEntity,
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
 } from "../lib/security.js";
-import { applySafeDraftDefault } from "../lib/moderation-default.js";
-import { shapeWriteResponse, RETURNING_SCHEMA } from "../lib/entity-response.js";
+import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
+import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 
 /** Fallback language for an alias when the node exposes none. */
@@ -318,10 +318,20 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   else if (status !== undefined) attributes.status = status;
   const bodyAttr = buildBodyAttribute(body, summary, format, site);
   if (bodyAttr) attributes.body = bodyAttr;
+  // 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;
+  if (!hasExplicitModerationState(attributes)) {
+    try {
+      existing = (await backend.getEntity({ entityType: "node", bundle: type, id })) ?? null;
+    } catch {
+      existing = null; // Unreadable target: server-side gates stay authoritative.
+    }
+  }
   // #131: published moderated nodes without an explicit state → draft forward revision.
   // Runs before the publish gate and on dryRun so previews match the real write.
   attributes = await applySafeDraftDefault({
-    backend, entityType: "node", bundle: type, id, attributes,
+    backend, entityType: "node", bundle: type, id, attributes, existingEntity: existing,
   });
   assertPublishAllowed(sec, attributes);
   if (dryRun) return { dryRun: true, operation: "update", entityType: "node", bundle: type, id, attributes, relationships };
@@ -337,8 +347,11 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   // Honest response: re-read persisted state so the returned `url` is the alias
   // that actually resolves, never the just-sent value.
   const fresh = await backend.getEntity({ entityType: "node", bundle: type, id }).catch(() => null);
-  if (fresh && redirectResult) return shapeWriteResponse({ ...fresh, _redirect: redirectResult }, returning);
-  return shapeWriteResponse(fresh ?? { id }, returning);
+  // #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);
 }
 
 /**