drupal-mcp-connector 2.7.0 → 2.7.2

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

@@ -1,12 +1,12 @@
 ---
-description: "Create many entities of a single type + bundle in one call. Permission is checked once; each item is created independently, so the batch continues past individual failures (partial success). Returns per-item { index, success, id | error } and a summary { created, failed }. Writes default to unpublished/draft."
+description: "Create many entities of a single type + bundle in one call. Permission is checked once; each item is created independently, so the batch continues past individual failures (partial success). Returns per-item { index, success, id | error } and a summary { created, failed }. Paragraph items also return relationshipData with meta.target_revision_id for a later host attach. Writes default to unpublished/draft."
 argument-hint: "<entityType> <bundle> <items> [site]"
 allowed-tools: mcp__drupal__drupal_bulk_create
 ---
 
 Call the `mcp__drupal__drupal_bulk_create` MCP tool.
 
-Create many entities of a single type + bundle in one call. Permission is checked once; each item is created independently, so the batch continues past individual failures (partial success). Returns per-item { index, success, id | error } and a summary { created, failed }. Writes default to unpublished/draft.
+Create many entities of a single type + bundle in one call. Permission is checked once; each item is created independently, so the batch continues past individual failures (partial success). Returns per-item { index, success, id | error } and a summary { created, failed }. Paragraph items also return relationshipData with meta.target_revision_id for a later host attach. Writes default to unpublished/draft.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

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

@@ -1,12 +1,12 @@
 ---
-description: "Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id: <uuid> }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy."
+description: "Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Drupal ERR items are empty without that meta key — do not send {type, id} alone. Before creating paragraphs to attach to a published moderated node, call drupal_list_revisions (possiblyPatchBlocked) and dryRun the host update so a doomed PATCH does not orphan them. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy."
 argument-hint: "<paragraphType> [site] [attributes]"
 allowed-tools: mcp__drupal__drupal_create_paragraph
 ---
 
 Call the `mcp__drupal__drupal_create_paragraph` MCP tool.
 
-Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id: <uuid> }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy.
+Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Drupal ERR items are empty without that meta key — do not send {type, id} alone. Before creating paragraphs to attach to a published moderated node, call drupal_list_revisions (possiblyPatchBlocked) and dryRun the host update so a doomed PATCH does not orphan them. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/.claude/commands/drupal-entity-update.md

@@ -1,12 +1,12 @@
 ---
-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)."
+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."
 argument-hint: "<entityType> <bundle> <id> [site] [attributes] [relationships] [dryRun] [returning]"
 allowed-tools: mcp__drupal__drupal_entity_update
 ---
 
 Call the `mcp__drupal__drupal_entity_update` MCP tool.
 
-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).
+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.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 
@@ -19,7 +19,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `site` (string): omit for the default site
 - `attributes` (object (pass as JSON))
 - `relationships` (object (pass as JSON))
-- `dryRun` (boolean (true/false)): Validate and return a preview of the update without committing.
+- `dryRun` (boolean (true/false)): 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.
 - `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 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-get-paragraph.md

@@ -1,12 +1,12 @@
 ---
-description: "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph plus a `ref` ({ type: 'paragraph--<bundle>', id }) you can use to embed it in a host entity's paragraph / ERR field. Note: paragraphs are referenced (by target_id + target_revision_id in the entity API, or by UUID over JSON:API) from a host field rather than queried standalone in production. Governed by the site security policy."
+description: "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy."
 argument-hint: "<paragraphType> <id> [site]"
 allowed-tools: mcp__drupal__drupal_get_paragraph
 ---
 
 Call the `mcp__drupal__drupal_get_paragraph` MCP tool.
 
-Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph plus a `ref` ({ type: 'paragraph--<bundle>', id }) you can use to embed it in a host entity's paragraph / ERR field. Note: paragraphs are referenced (by target_id + target_revision_id in the entity API, or by UUID over JSON:API) from a host field rather than queried standalone in production. Governed by the site security policy.
+Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/.claude/commands/drupal-governance-status.md

@@ -1,12 +1,12 @@
 ---
-description: "Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial."
+description: "Report each configured site's source-governance condition. Always probes GET /drupal-mcp/readiness (even when this client does not require governance) and surfaces the server's reason verbatim. Never reports ok:true unless that check ran. Callable even while governed paths are denied — this is the diagnostic for that denial."
 argument-hint: "[site]"
 allowed-tools: mcp__drupal__drupal_governance_status
 ---
 
 Call the `mcp__drupal__drupal_governance_status` MCP tool.
 
-Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial.
+Report each configured site's source-governance condition. Always probes GET /drupal-mcp/readiness (even when this client does not require governance) and surfaces the server's reason verbatim. Never reports ok:true unless that check ran. Callable even while governed paths are denied — this is the diagnostic for that denial.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

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

@@ -1,12 +1,12 @@
 ---
-description: "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. NOTE: JSON:API cannot enumerate full chronological revision history — it only addresses revisions by id or the latest/working-copy aliases. Full history enumeration requires the Drush bridge. Use drupal_report_revision_hotspots for per-node revision counts."
+description: "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge."
 argument-hint: "<type> <id> [site]"
 allowed-tools: mcp__drupal__drupal_list_revisions
 ---
 
 Call the `mcp__drupal__drupal_list_revisions` MCP tool.
 
-Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. NOTE: JSON:API cannot enumerate full chronological revision history — it only addresses revisions by id or the latest/working-copy aliases. Full history enumeration requires the Drush bridge. Use drupal_report_revision_hotspots for per-node revision counts.
+Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/.claude/commands/drupal-report-orphaned-references.md

@@ -1,12 +1,12 @@
 ---
-description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. Flags 'approximate' when sampling-bounded."
+description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. A 404 (or unaddressable ref) is an orphan; 401/403 and connector policy denials are counted as unverifiable, not missing. uid/revision_uid are skipped when the policy denies user. Flags 'approximate' when sampling-bounded."
 argument-hint: "[site] [type] [sampleSize]"
 allowed-tools: mcp__drupal__drupal_report_orphaned_references
 ---
 
 Call the `mcp__drupal__drupal_report_orphaned_references` MCP tool.
 
-Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. Flags 'approximate' when sampling-bounded.
+Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. A 404 (or unaddressable ref) is an orphan; 401/403 and connector policy denials are counted as unverifiable, not missing. uid/revision_uid are skipped when the policy denies user. Flags 'approximate' when sampling-bounded.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

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

@@ -1,12 +1,12 @@
 ---
-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`."
+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."
 argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [fields] [relationships] [dryRun] [returning]"
 allowed-tools: mcp__drupal__drupal_update_node
 ---
 
 Call the `mcp__drupal__drupal_update_node` MCP tool.
 
-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`.
+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.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 
@@ -23,8 +23,8 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `status` (boolean (true/false)): Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set.
 - `moderationState` (string): 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` (object (pass as JSON)): Scalar/attribute field values keyed by machine name. Entity-reference fields go in `relationships`, not here.
-- `relationships` (object (pass as JSON)): Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }.
-- `dryRun` (boolean (true/false)): Validate and return a preview of the update without committing.
+- `relationships` (object (pass as JSON)): Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot.
+- `dryRun` (boolean (true/false)): 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.
 - `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 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-paragraph.md

@@ -1,12 +1,12 @@
 ---
-description: "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to this paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy."
+description: "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy."
 argument-hint: "<paragraphType> <id> [site] [attributes]"
 allowed-tools: mcp__drupal__drupal_update_paragraph
 ---
 
 Call the `mcp__drupal__drupal_update_paragraph` MCP tool.
 
-Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to this paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.
+Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.2] - 2026-08-18
+
+### Fixed
+- **Orphan-reference report no longer treats 403 / policy denial as a missing
+  target (#205).** `drupal_report_orphaned_references` used to count any
+  non-OK probe as an orphan. On a site whose policy denies `user`, every
+  `uid` / `revision_uid` became a false finding — 64 "orphans" across 32
+  healthy nodes in the report that produced this issue. Only a 404 (or an
+  unaddressable ref) is an orphan. Denied targets are a third state:
+  `unverifiable` plus `reason: "target entity type denied by policy"`.
+  Author base fields are skipped when the policy denies `user`, so the
+  auditor presets stop manufacturing corruption.
+- **PATCH-blocked message names a pending draft when one is visible
+  (#201 follow-up).** The preflight added in 2.7.1 always said the blocking
+  row was invisible and needed revision surgery. That is right for a stray
+  revision with no content_moderation working copy, and wrong for an
+  ordinary open draft — the common case, and the dangerous advice. The
+  preflight now loads `rel:working-copy`: if it resolves, the error is
+  "This node has a pending draft (vid N). Publish or discard it before a
+  canonical PATCH." Surgery is mentioned only when the working copy does
+  not resolve and the guard still fires.
+- **`drupal_governance_status` no longer reports `ok: true` without a
+  check (#208).** When the client did not set `requireGovernance`, the
+  diagnostic skipped the readiness probe and returned
+  `{ required: false, ok: true, checkedAt: null }` while the same site
+  503'd every governed request with `designated_consumer_disabled`. It
+  now always probes `GET /drupal-mcp/readiness`, sets `checked: true` and
+  `checkedAt`, and surfaces the server's reason verbatim. `ok: true` only
+  after that check. Unresolved site configs report `checked: false` and
+  omit `checkedAt`.
+
+## [2.7.1] - 2026-08-18
+
+### Fixed
+- **Paragraph ERR attach sends `meta.target_revision_id` (#192).** JSON:API
+  only persists an Entity Reference Revisions item when the resource
+  identifier carries the current revision id. The connector used to send
+  `{ type, id }` and document that Drupal would fill in the vid — Drupal
+  does not, and the field is saved empty. Host writes
+  (`drupal_update_node`, `drupal_entity_update`, bulk update) now resolve
+  each paragraph identifier (preferring a vid from the create response)
+  and fail the whole write if any ref cannot be resolved. Create/update/get
+  paragraph tools return `relationshipData` / `ref` with that meta key, and
+  paragraph reads surface `drupal_internal__revision_id`. An empty array is
+  still an explicit clear.
+- **Write responses no longer treat the canonical re-read as proof a
+  relationship landed (#169).** When relationships were sent, the returned
+  body is the `rel:working-copy` revision when addressable, otherwise the
+  PATCH body plus `_revision.relationshipsUnverified`.
+- **PATCH preflight for the core working-copy guard (#201).**
+  `drupal_list_revisions` reports `possiblyPatchBlocked` when the default
+  revision's `changed` is later than its `revision_timestamp`, and never
+  treats `workingCopy: null` as an all-clear. `drupal_update_node` /
+  `drupal_entity_update` (and their `dryRun`) probe the same canonical
+  URL before the real write. The probe PATCH uses a non-matching `data.id`
+  so core's working-copy guard still runs and `$entity->save()` does not
+  (an empty-body 2xx would have written a revision). A core working-copy
+  400 is rewritten to say the stored entity is not the latest revision,
+  the JSON:API aliases cannot show the blocking row, and clearing it is
+  revision surgery outside JSON:API (Drush / the entity API). Preflight
+  on the host write does not un-orphan paragraphs already created — probe
+  the host (`possiblyPatchBlocked`, then `dryRun`) *before*
+  `drupal_create_paragraph`.
+
 ## [2.7.0] - 2026-08-17
 
 ### Security

package/README.md

@@ -9,7 +9,7 @@
 
 Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
-**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.0** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
+**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.2** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "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/backends/backend-interface.js

@@ -66,7 +66,10 @@ export class Backend {
 
   /**
    * Fetch a single entity by reference.
-   * @param {{entityType: string, bundle: string, id: string}} _ref
+   * @param {{entityType: string, bundle: string, id: string, resourceVersion?: string}} _ref
+   *   `resourceVersion` is a JSON:API revision selector (`rel:working-copy`,
+   *   `rel:latest-version`, `id:<vid>`). Backends that cannot address revisions
+   *   ignore it.
    * @returns {Promise<?import("../canonical.js").CanonicalEntity>} Entity, or null when absent.
    */
   async getEntity(_ref) { return notImplemented("getEntity"); }

package/src/lib/backends/jsonapi.js

@@ -204,9 +204,15 @@ export class JsonApiBackend extends Backend {
     const bundle = rawBundle || null;
     const attrs = resource.attributes || {};
     const fields = Object.fromEntries(
-      Object.entries(attrs).filter(
-        ([k]) => !BASE_ATTRIBUTE_FIELDS.includes(k) && !INTERNAL_ATTR_RE.test(k)
-      )
+      Object.entries(attrs).filter(([k]) => {
+        if (BASE_ATTRIBUTE_FIELDS.includes(k)) return false;
+        if (INTERNAL_ATTR_RE.test(k)) {
+          // Paragraph ERR attach needs the current revision id (#192).
+          // Other drupal_internal__* attributes stay stripped.
+          return entityType === "paragraph" && k === "drupal_internal__revision_id";
+        }
+        return true;
+      })
     );
     const relationships = Object.fromEntries(
       Object.entries(resource.relationships || {}).map(([k, rel]) => [k, normalizeRelationship(rel?.data ?? null)])
@@ -249,12 +255,16 @@ export class JsonApiBackend extends Backend {
 
   /**
    * Fetch a single entity by id.
-   * @param {{entityType: string, bundle: string, id: string}} ref
+   * @param {{entityType: string, bundle: string, id: string, resourceVersion?: string}} ref
    * @returns {Promise<?import("../canonical.js").CanonicalEntity>} Entity, or null.
    */
-  async getEntity({ entityType, bundle, id }) {
+  async getEntity({ entityType, bundle, id, resourceVersion }) {
     validateUuid(id);
-    const data = await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`);
+    let path = `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+    if (resourceVersion) {
+      path += `?resourceVersion=${encodeURIComponent(resourceVersion)}`;
+    }
+    const data = await drupalFetch(this.site, path);
     return data?.data ? this.toCanonical(data.data) : null;
   }
 

package/src/lib/canonical.js

@@ -64,7 +64,17 @@ export function normalizeRelationship(ref) {
   if (Array.isArray(ref)) return ref.map(normalizeRelationship);
   // JSON:API encodes type as "entityType--bundle"; split into the two parts.
   const [entityType = null, bundle = null] = (ref.type || "").split("--");
-  return { id: ref.id, entityType, bundle };
+  const out = { id: ref.id, entityType, bundle };
+  // ERR identifiers carry the revision id in JSON:API `meta` (#192). Dropping
+  // it made every canonical re-read look like a plain {id, type} even when the
+  // write sent target_revision_id.
+  if (ref.meta && typeof ref.meta === "object") {
+    const vid = new Map(Object.entries(ref.meta)).get("target_revision_id");
+    if (vid !== undefined && vid !== null && vid !== "") {
+      out.meta = { target_revision_id: vid };
+    }
+  }
+  return out;
 }
 
 /**

package/src/lib/err-relationships.js

@@ -0,0 +1,286 @@
+/**
+ * Resolve Entity Reference Revisions identifiers before a host write (#192).
+ *
+ * Drupal's ERR item is empty unless both `target_id` and `target_revision_id`
+ * are set. JSON:API only receives the revision id when the resource identifier
+ * carries `meta.target_revision_id`. Sending `{ type, id }` persists an empty
+ * field — not a no-op — so a draft forked from a published node with N refs
+ * lands with 0.
+ *
+ * Ordinary entity-reference fields (taxonomy, media, nodes, users) must not
+ * require a revision id. Heuristic: resource types starting with `paragraph--`
+ * are ERR targets and must resolve; anything else is left unchanged. An empty
+ * `data` array is an explicit clear and is sent as-is.
+ */
+
+/**
+ * Thrown when one or more paragraph identifiers cannot be given a
+ * `target_revision_id`. The host write must not proceed.
+ */
+export class ErrRelationshipError extends Error {
+  /**
+   * @param {string} message Human-readable reason.
+   * @param {{unresolved?: Array<{id: ?string, reason: string}>}} [details]
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "ErrRelationshipError";
+    this.details = details;
+  }
+}
+
+/**
+ * Whether a JSON:API resource type is a paragraph bundle.
+ * @param {*} type Resource type string, e.g. "paragraph--capability".
+ * @returns {boolean}
+ */
+export function isParagraphResourceType(type) {
+  return typeof type === "string" && type.startsWith("paragraph--");
+}
+
+/**
+ * Split a JSON:API resource type into entity type + bundle.
+ * @param {string} type e.g. "paragraph--capability".
+ * @returns {?{entityType: string, bundle: string}}
+ */
+export function parseResourceType(type) {
+  if (typeof type !== "string" || !type.includes("--")) return null;
+  const [entityType, ...rest] = type.split("--");
+  return { entityType, bundle: rest.join("--") };
+}
+
+/**
+ * Prefer the vid on a just-created/updated paragraph (before a follow-up GET).
+ * Fall back to an un-redacted GET when the write result did not carry it.
+ * @param {object} backend Backend with `getEntity`.
+ * @param {?object} paragraph Create/update result.
+ * @param {string} bundle Paragraph type machine name.
+ * @returns {Promise<?number>}
+ */
+export async function resolveParagraphRevisionId(backend, paragraph, bundle) {
+  const fromWrite = paragraphRevisionId(paragraph);
+  if (fromWrite !== null) return fromWrite;
+  if (!paragraph?.id || typeof backend?.getEntity !== "function") return null;
+  const fresh = await backend.getEntity({
+    entityType: "paragraph",
+    bundle: paragraph.bundle || bundle,
+    id: paragraph.id,
+  }).catch(() => null);
+  return paragraphRevisionId(fresh);
+}
+
+/**
+ * Error when a paragraph write succeeded but no revision id is readable.
+ * Returning `{type, id}` would persist an empty ERR field (#192).
+ * @param {string} id Paragraph UUID.
+ * @param {"Created"|"Updated"} [operation="Created"] The write that already landed.
+ * @returns {Error}
+ */
+export function missingParagraphRevisionError(id, operation = "Created") {
+  const verb = operation === "Updated" ? "Updated" : "Created";
+  return new Error(
+    `${verb} paragraph ${id} but could not read drupal_internal__revision_id; ` +
+    "refusing to return a relationship identifier Drupal would persist as empty (#192)."
+  );
+}
+
+/**
+ * Read `drupal_internal__revision_id` from a canonical entity (or a raw-ish
+ * object that still carries the attribute at the top level).
+ * @param {?object} entity
+ * @returns {?number}
+ */
+export function paragraphRevisionId(entity) {
+  if (!entity || typeof entity !== "object") return null;
+  const fields = entity.fields && typeof entity.fields === "object" ? entity.fields : {};
+  const raw = Object.prototype.hasOwnProperty.call(fields, "drupal_internal__revision_id")
+    ? fields.drupal_internal__revision_id
+    : entity.drupal_internal__revision_id;
+  if (raw === undefined || raw === null || raw === "") return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Build the JSON:API resource identifier used to embed a paragraph in a host
+ * ERR field. Includes `meta.target_revision_id` when a vid is known.
+ * @param {string} bundle Paragraph type machine name.
+ * @param {string} id Paragraph UUID.
+ * @param {number|string|null|undefined} revisionId Current revision id.
+ * @returns {{type: string, id: string, meta?: {target_revision_id: number}}}
+ */
+export function embedParagraphRef(bundle, id, revisionId) {
+  const ref = { type: `paragraph--${bundle}`, id };
+  if (revisionId === undefined || revisionId === null || revisionId === "") return ref;
+  const n = Number(revisionId);
+  if (!Number.isFinite(n)) return ref;
+  ref.meta = { target_revision_id: n };
+  return ref;
+}
+
+/**
+ * Whether a resource identifier already carries a usable target revision id.
+ * @param {?object} item
+ * @returns {boolean}
+ */
+export function linkageHasRevisionMeta(item) {
+  const vid = item?.meta?.target_revision_id;
+  return vid !== undefined && vid !== null && vid !== "";
+}
+
+/**
+ * Whether the caller supplied any relationship fields (including an explicit
+ * empty-array clear). An omitted / empty object is "not sent".
+ * @param {?object} relationships
+ * @returns {boolean}
+ */
+export function relationshipsWereSent(relationships) {
+  if (!relationships || typeof relationships !== "object" || Array.isArray(relationships)) {
+    return false;
+  }
+  return Object.keys(relationships).length > 0;
+}
+
+/**
+ * Clone a resource identifier, preserving `meta` when present.
+ * @param {object} item
+ * @returns {{type: *, id: *, meta?: object}}
+ */
+function cloneIdentifier(item) {
+  const out = { type: item.type, id: item.id };
+  if (item.meta && typeof item.meta === "object") out.meta = { ...item.meta };
+  return out;
+}
+
+/**
+ * Resolve one resource identifier. Paragraph refs without a vid are loaded
+ * un-redacted and stamped with `meta.target_revision_id`. Failures are
+ * recorded on `unresolved` rather than thrown so a mixed list is never
+ * half-applied.
+ * @param {object} backend Backend with `getEntity`.
+ * @param {object} item Resource identifier.
+ * @param {Map<string, number>} cache uuid → revision id (create-response vids).
+ * @param {Array<{id: ?string, reason: string}>} unresolved
+ * @returns {Promise<object>}
+ */
+async function resolveOneIdentifier(backend, item, cache, unresolved) {
+  if (!item || typeof item !== "object" || Array.isArray(item)) {
+    unresolved.push({ id: null, reason: "malformed resource identifier" });
+    return item;
+  }
+  if (typeof item.type !== "string" || typeof item.id !== "string") {
+    unresolved.push({ id: item.id ?? null, reason: "resource identifier must include type and id" });
+    return item;
+  }
+
+  const out = cloneIdentifier(item);
+
+  // Ordinary entity-reference (taxonomy, media, node, user, file): leave alone.
+  if (!isParagraphResourceType(item.type)) return out;
+
+  if (linkageHasRevisionMeta(out)) {
+    const n = Number(out.meta.target_revision_id);
+    if (Number.isFinite(n)) {
+      out.meta = { ...out.meta, target_revision_id: n };
+      cache.set(item.id, n);
+      return out;
+    }
+  }
+
+  if (cache.has(item.id)) {
+    out.meta = { ...(out.meta || {}), target_revision_id: cache.get(item.id) };
+    return out;
+  }
+
+  const parsed = parseResourceType(item.type);
+  if (!parsed) {
+    unresolved.push({ id: item.id, reason: `unparseable type "${item.type}"` });
+    return out;
+  }
+
+  let entity = null;
+  try {
+    entity = await backend.getEntity({
+      entityType: parsed.entityType,
+      bundle: parsed.bundle,
+      id: item.id,
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    unresolved.push({ id: item.id, reason: `GET failed: ${reason}` });
+    return out;
+  }
+  if (!entity) {
+    unresolved.push({ id: item.id, reason: "GET returned 404 / null" });
+    return out;
+  }
+
+  const vid = paragraphRevisionId(entity);
+  if (vid === null) {
+    // Paragraphs are revisionable. A missing vid is a connector/backend gap,
+    // not "not revisionable" — sending {type,id} would persist empty.
+    unresolved.push({ id: item.id, reason: "paragraph has no drupal_internal__revision_id" });
+    return out;
+  }
+  cache.set(item.id, vid);
+  out.meta = { ...(out.meta || {}), target_revision_id: vid };
+  return out;
+}
+
+/**
+ * Inject `meta.target_revision_id` on every paragraph identifier in a
+ * JSON:API relationships map. Throws before the caller PATCHes if any
+ * paragraph ref cannot be resolved. Empty arrays and `data: null` pass
+ * through (explicit clear). Non-paragraph refs are unchanged.
+ *
+ * @param {object} backend Backend with un-redacted `getEntity`.
+ * @param {?object} relationships JSON:API relationships map.
+ * @param {{revisionCache?: Map<string, number>}} [options]
+ * @returns {Promise<?object>} A new relationships map, or the input when empty.
+ * @throws {ErrRelationshipError} If any paragraph identifier cannot be resolved.
+ */
+export async function resolveErrRelationships(backend, relationships, options = {}) {
+  if (relationships === null || relationships === undefined) return relationships;
+  if (typeof relationships !== "object" || Array.isArray(relationships)) return relationships;
+
+  const cache = options.revisionCache instanceof Map ? options.revisionCache : new Map();
+  const unresolved = [];
+  const entries = [];
+
+  for (const [field, rel] of Object.entries(relationships)) {
+    if (!rel || typeof rel !== "object" || !Object.prototype.hasOwnProperty.call(rel, "data")) {
+      entries.push([field, rel]);
+      continue;
+    }
+    const { data } = rel;
+    if (data === null) {
+      entries.push([field, { ...rel, data: null }]);
+      continue;
+    }
+    if (Array.isArray(data)) {
+      // Empty array is an explicit clear — do not resolve, do not fail.
+      if (data.length === 0) {
+        entries.push([field, { ...rel, data: [] }]);
+        continue;
+      }
+      const items = [];
+      for (const item of data) {
+        items.push(await resolveOneIdentifier(backend, item, cache, unresolved));
+      }
+      entries.push([field, { ...rel, data: items }]);
+      continue;
+    }
+    entries.push([field, { ...rel, data: await resolveOneIdentifier(backend, data, cache, unresolved) }]);
+  }
+
+  if (unresolved.length) {
+    const listed = unresolved.map((u) => `${u.id ?? "(missing id)"}: ${u.reason}`).join("; ");
+    throw new ErrRelationshipError(
+      "Cannot attach paragraph relationship: failed to resolve target_revision_id " +
+      `for ${unresolved.length} identifier(s). The write was not sent — an unresolved ` +
+      `ERR identifier would persist an empty field. ${listed}`,
+      { unresolved }
+    );
+  }
+  return Object.fromEntries(entries);
+}