drupal-mcp-connector 2.6.1 → 2.7.1

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-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-list-sites.md

@@ -1,10 +1,10 @@
 ---
-description: "List all named Drupal sites configured in config.json. Useful for multi-site setups."
+description: "List the Drupal sites this principal may address. Each target includes the authoritative site name and base URL."
 allowed-tools: mcp__drupal__drupal_list_sites
 ---
 
 Call the `mcp__drupal__drupal_list_sites` MCP tool.
 
-List all named Drupal sites configured in config.json. Useful for multi-site setups.
+List the Drupal sites this principal may address. Each target includes the authoritative site name and base URL.
 
 This tool takes no arguments — call it directly (ignore `$ARGUMENTS`).

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,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **Discovery and invocation follow the inbound principal (#178).** On
+  HTTPS resource-server requests the validated JWT — not caller `site`,
+  `environment`, `tenant`, `target`, or `scope` arguments — decides which
+  tools, resources, prompts, and sites are visible or callable. Empty
+  inbound scopes are no grants. `auth.grants` maps a client id to site
+  names; a present map is fail-closed for unknown clients. GraphQL and
+  raw SQL stay hidden unless an entitled site's preset actually allows
+  them. Stdio and loopback without a resource-server identity keep the
+  existing local-operator surface. `drupal_list_sites` now also returns
+  `targets` with the authoritative name and base URL.
+- **Network-facing HTTPS is an OAuth protected resource (#177).** `/mcp`
+  validates inbound JWTs against a configured issuer (RFC 8414 / OIDC
+  discovery + JWKS): issuer, audience/resource, expiry and required scopes.
+  RFC 9728 metadata is served at `/.well-known/oauth-protected-resource`.
+  A revocation file (`jti` / `sub`) is re-read when it changes, so a revoke
+  does not require a restart. Optional RFC 7662 introspection is fail-closed
+  when configured. Discovery requires the metadata `issuer` to match the
+  configured identifier (RFC 8414 §3.3), uses the RFC 8414 well-known path
+  for issuers that have a path component, and refuses HTTP issuers,
+  `jwks_uri`s, and introspection URLs. Trailing slashes on the issuer
+  identifier do not break JWT verification. RFC 9728 `authorization_servers`
+  advertises the issuer string returned by discovery. A thrown authenticator, a corrupt revocation file, or a
+  failed introspection returns `401` instead of hanging the request.
+  Caller-supplied identity headers never become the principal. The inbound
+  access token is never forwarded to Drupal. `MCP_AUTH_TOKEN` remains valid
+  only on loopback; a network-facing bind that still relies on the shared
+  secret refuses to start.
+
+### Changed
+- **Versioning policy states the post-1.0 guarantees it actually operates under
+  (#195).** `docs/versioning.md` still opened with a pre-1.0 section explaining
+  that minor releases might break the stable surface because the project was on
+  `0.x`, and pointed at a closed tracking issue. The package has been past 1.0
+  for some time, so the document told operators the compatibility guarantees
+  were not yet in force when they were. The stable-surface list, deprecation
+  policy and runtime support were already correct and are unchanged.
+
+### Fixed
+- **Whitepaper no longer calls the companion governance module pre-1.0/alpha
+  (#195).** `docs/whitepaper.md` described `drupal/mcp_sentinel` as alpha and
+  requiring Drupal `^10.3 || ^11`. It is a shipping module at 2.9.0 with a floor
+  of `^10.6 || ^11.3` on PHP 8.3 or newer — the stale constraint would have sent
+  a reader to install it on a combination it does not support.
+
 ## [2.6.1] - 2026-08-17
 
 ### Fixed

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.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.1** (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).
 
 ---
 
@@ -158,7 +158,7 @@ Additional connector-side gates (2.1+ / 2.2+):
 - **Entity allowlists** apply to specialized tools (`drupal_*_node`, media, taxonomy), not only `drupal_entity_*`.
 - **Publish gate:** `status: true` and `moderation_state: "published"` require `allowPublish`. Media create defaults **unpublished**. Published moderated node updates without a moderation state default to **draft** (forward revision).
 - **Uploads** only from `MCP_UPLOAD_ROOT` (or the process cwd); sensitive paths (`.env*`, `.ssh`, connector `config.json`) are refused.
-- **HTTPS:** non-loopback binds require `MCP_AUTH_TOKEN` (or `MCP_ALLOW_UNAUTHENTICATED=1` behind a trusted proxy); non-loopback TLS defaults to 120 req/min rate limiting.
+- **HTTPS:** non-loopback binds require an inbound OAuth resource server (`auth.issuer` + `auth.audience`), not `MCP_AUTH_TOKEN`. `MCP_AUTH_TOKEN` remains valid on loopback. `MCP_ALLOW_UNAUTHENTICATED=1` is only for a trusted proxy. Non-loopback TLS defaults to 120 req/min rate limiting. Inbound JWT scopes (and optional `auth.grants`) filter which tools, resources, prompts, and sites a principal can discover or invoke.
 - **GraphQL is off by default.** `drupal_graphql` / introspect require `security.allowGraphql` (true only on the `development` preset). Raw GraphQL results still bypass entity allowlists and field redaction — prefer JSON:API entity tools when connector policy must hold. Mutations also need `allowGraphqlMutations`.
 
 Full detail: **[docs/security.md](docs/security.md)** and **[docs/security-hardening.md](docs/security-hardening.md)**.

package/config/config.example.json

@@ -7,7 +7,7 @@
   },
 
   "_security_options": {
-    "_comment": "apiTokenEnv / oauth.clientSecretEnv: read credentials from the environment, never from this file. requireSecureAuth: reject anon/basic, require HTTPS+Bearer — set it on every remote site. requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel) verifies — no ungoverned JSON:API/GraphQL fallback. Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_AUTH_TOKEN requires bearer auth on the HTTPS /mcp endpoint; MCP_BIND_HOST restricts the listen interface (with TLS). See docs/security-hardening.md."
+    "_comment": "apiTokenEnv / oauth.clientSecretEnv: read credentials from the environment, never from this file. requireSecureAuth: reject anon/basic, require HTTPS+Bearer — set it on every remote site. requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel) verifies — no ungoverned JSON:API/GraphQL fallback. Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_BIND_HOST restricts the listen interface (with TLS). Network-facing HTTPS /mcp requires the top-level auth block (issuer + audience), not MCP_AUTH_TOKEN. MCP_AUTH_TOKEN remains valid only on loopback. See docs/security-hardening.md."
   },
 
   "_governance_tiers": {
@@ -23,6 +23,21 @@
     "port":     3443
   },
 
+  "auth": {
+    "_comment": "Inbound OAuth resource-server for MCP_TRANSPORT=https when the process binds beyond loopback. The issuer is any standards-based authorization server (RFC 8414 / OIDC) — not a vendor-specific product. Tokens are JWTs validated against the issuer's JWKS. Optional: revocationFile (JSON {jti,sub}, re-read without restart) and introspectionUrl (RFC 7662). Env overrides: MCP_RESOURCE_ISSUER, MCP_RESOURCE_AUDIENCE, MCP_RESOURCE, MCP_REVOCATION_FILE, MCP_INTROSPECTION_URL.",
+    "issuer":   "https://idp.example.com",
+    "audience": "https://mcp.example.com/mcp",
+    "resource": "https://mcp.example.com/mcp",
+    "requiredScopes": ["mcp_read"],
+    "grants": {
+      "_comment": "Optional. Map inbound OAuth client_id (azp) to site names, e.g. \"content-agent\": [\"production\", \"staging\"]. When the map names any client, unknown clients receive no sites. Omit this object (or leave only this comment) to let every resolvable site stay visible; inbound scopes still gate the tool surface."
+    },
+    "revocationFile": "",
+    "introspectionUrl": "",
+    "introspectionClientIdEnv": "",
+    "introspectionClientSecretEnv": ""
+  },
+
   "sites": {
     "production": {
       "_comment": "Content tier. Content/media/term CRUD; config read-only; cannot publish (the source-side editorial gate decides publication, not the agent). No drushSsh.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.6.1",
-  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal \u2014 dual-protocol JSON:API and GraphQL.",
+  "version": "2.7.1",
+  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -56,7 +56,7 @@
     "test:watch": "vitest",
     "audit": "npm audit --audit-level=high",
     "check": "npm run lint && npm run audit",
-    "syntax-check": "for f in src/lib/*.js src/tools/*.js src/index.js; do node --input-type=module --check < $f && echo \"$f \u2713\"; done",
+    "syntax-check": "for f in src/lib/*.js src/tools/*.js src/index.js; do node --input-type=module --check < $f && echo \"$f ✓\"; done",
     "verify": "node bin/drupal-mcp-verify.js",
     "verify:example": "node bin/drupal-mcp-verify.js --config config/config.example.json"
   },
@@ -64,6 +64,7 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "graphql": "^17.0.0",
+    "jose": "^6.2.9",
     "node-fetch": "^3.3.2",
     "ssh2": "^1.16.0"
   },

package/src/index.js

@@ -15,7 +15,9 @@
  *   DRUPAL_BASE_URL   Single-site fallback baseUrl
  *   DRUPAL_API_TOKEN  Single-site fallback Bearer token
  *   MCP_ALLOW_HTTP    Set to "1" to allow plain HTTP on localhost only (dev)
- *   MCP_AUTH_TOKEN    Bearer token required on /mcp in https mode (warns if unset)
+ *   MCP_AUTH_TOKEN    Loopback-only shared bearer for /mcp (not accepted network-facing)
+ *   MCP_RESOURCE_ISSUER / MCP_RESOURCE_AUDIENCE / MCP_RESOURCE
+ *                     Inbound OAuth resource-server (required beyond loopback)
  *   MCP_BIND_HOST     Bind address for https mode when TLS is present
  *                     (default: "0.0.0.0"; ignored without TLS, which forces loopback)
  *   MCP_RATE_LIMIT    Max /mcp requests per window per client IP (0/unset = off)
@@ -31,14 +33,27 @@ import { createMcpHandler } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { toNodeHandler } from "@modelcontextprotocol/node";
 
-import { listSiteNames, getTlsConfig, CLIENT_VERSION } from "./lib/config.js";
+import { listSiteNames, getTlsConfig, loadConfig, CLIENT_VERSION } from "./lib/config.js";
 import { loadLocalSecrets, secretLoadFatalMessage } from "./lib/load-secrets.js";
-import { makeBearerCheck } from "./lib/http-auth.js";
+import {
+  makeBearerCheck,
+  resolveInboundAuthConfig,
+  resolveInboundAuthMode,
+  createInboundHttpsAuth,
+} from "./lib/http-auth.js";
 import { createLegacySessionHandler, createMcpRequestHandler } from "./lib/http-handler.js";
 import { createConnectorServerFactory } from "./lib/mcp-server.js";
 import { createRateLimiter } from "./lib/rate-limit.js";
 import { callTool, listResolvableSiteConfigs } from "./lib/dispatch.js";
 import { filterDiscoverableTools } from "./lib/governance.js";
+import {
+  assertPrincipalEntitlement,
+  filterPromptsByPrincipal,
+  filterResourcesByPrincipal,
+  filterToolsByPrincipal,
+  getRequestIdentity,
+  visibleSiteTargets,
+} from "./lib/principal.js";
 
 // Tools — aggregated (single source of truth, side-effect-free) and per-tool prompts
 import { allDefinitions, allHandlers, definitionsByName } from "./tools/index.js";
@@ -95,21 +110,43 @@ const RESOURCES = [
  * @returns {Promise<object>} The resource data (later JSON-serialized).
  * @throws {Error} If the URI matches no known resource.
  */
+async function discoverableTools() {
+  const sites = listResolvableSiteConfigs();
+  const identity = getRequestIdentity();
+  const governed = await filterDiscoverableTools(allDefinitions, sites);
+  return filterToolsByPrincipal(governed, sites, identity);
+}
+
 async function readResource(uri) {
+  const identity = getRequestIdentity();
+  const sites = listResolvableSiteConfigs();
+
   // drupal://sites
   if (uri === "drupal://sites") {
-    return { sites: listSiteNames() };
+    return visibleSiteTargets(identity, sites, listSiteNames());
   }
 
   // drupal://{site}/content-types
   const ctMatch = uri.match(/^drupal:\/\/([^/]+)\/content-types$/);
   if (ctMatch) {
+    assertPrincipalEntitlement({
+      toolName: "drupal_list_content_types",
+      args: { site: ctMatch[1] },
+      identity,
+      sites,
+    });
     return allHandlers.drupal_list_content_types({ site: ctMatch[1] });
   }
 
   // drupal://{site}/security-policy
   const spMatch = uri.match(/^drupal:\/\/([^/]+)\/security-policy$/);
   if (spMatch) {
+    assertPrincipalEntitlement({
+      toolName: "drupal_security_info",
+      args: { site: spMatch[1] },
+      identity,
+      sites,
+    });
     return allHandlers.drupal_security_info({ site: spMatch[1] });
   }
 
@@ -253,12 +290,24 @@ const buildConnectorServer = createConnectorServerFactory({
   serverInfo: { name: "drupal-mcp-connector", version: CLIENT_VERSION },
   tools: {
     definitions: allDefinitions,
-    list: () => filterDiscoverableTools(allDefinitions, listResolvableSiteConfigs()),
+    list: discoverableTools,
     call: callTool,
   },
-  resources: { definitions: RESOURCES, read: readResource },
+  resources: {
+    definitions: RESOURCES,
+    list: async () => {
+      const sites = listResolvableSiteConfigs();
+      return filterResourcesByPrincipal(RESOURCES, getRequestIdentity(), sites);
+    },
+    read: readResource,
+  },
   prompts: {
     definitions: ALL_PROMPTS,
+    list: async () => {
+      const identity = getRequestIdentity();
+      const tools = await discoverableTools();
+      return filterPromptsByPrincipal(ALL_PROMPTS, identity, tools);
+    },
     get: (name, args) => WORKFLOW_PROMPT_NAMES.has(name)
       ? getPromptMessages(name, args)
       : getToolPromptMessages(name, args, definitionsByName),
@@ -290,15 +339,7 @@ if (transport === "stdio") {
   const allowHttp  = process.env.MCP_ALLOW_HTTP === "1";
 
   const authToken   = process.env.MCP_AUTH_TOKEN || "";
-  const checkAuth   = makeBearerCheck(authToken);
   const allowUnauth = process.env.MCP_ALLOW_UNAUTHENTICATED === "1";
-  if (!authToken) {
-    console.error(
-      "[drupal-mcp-connector] WARNING: the /mcp endpoint is UNAUTHENTICATED. " +
-      "Set MCP_AUTH_TOKEN to require a bearer token, or front it with a trusted " +
-      "boundary (private network / auth proxy). Acceptable only behind such a boundary."
-    );
-  }
 
   // Security headers applied to every response
   function applySecurityHeaders(res) {
@@ -349,15 +390,42 @@ if (transport === "stdio") {
   const bindHost = hasTls ? (process.env.MCP_BIND_HOST || "0.0.0.0") : "127.0.0.1";
   const isLoopbackBind = bindHost === "127.0.0.1" || bindHost === "::1" || bindHost === "localhost";
 
-  // #141: fail closed when HTTPS is network-facing without a bearer token.
-  // Loopback binds and explicit MCP_ALLOW_UNAUTHENTICATED=1 remain for local/proxy setups.
-  if (!authToken && !isLoopbackBind && !allowUnauth) {
+  const inboundCfg = resolveInboundAuthConfig(loadConfig());
+  const inboundMode = resolveInboundAuthMode({
+    bindHost,
+    allowUnauth,
+    sharedToken: authToken,
+    resourceServer: inboundCfg,
+  });
+  if (inboundMode.mode === "fatal") {
+    console.error(`[drupal-mcp-connector] FATAL: ${inboundMode.reason}`);
+    process.exit(1);
+  }
+
+  let checkAuth = makeBearerCheck(inboundMode.mode === "shared_bearer" ? authToken : "");
+  let authenticate = null;
+  let protectedResource = null;
+  if (inboundMode.mode === "resource_server") {
+    try {
+      const inbound = await createInboundHttpsAuth({ inboundCfg });
+      authenticate = inbound.authenticate;
+      protectedResource = inbound.protectedResource;
+      checkAuth = () => false;
+      console.error(
+        `[drupal-mcp-connector] Inbound OAuth resource server: issuer ${inboundCfg.issuer}`
+      );
+    } catch (error) {
+      console.error(
+        "[drupal-mcp-connector] FATAL: inbound issuer discovery failed.\n" +
+        `  ${error instanceof Error ? error.message : "unknown error"}`
+      );
+      process.exit(1);
+    }
+  } else if (inboundMode.mode === "unauthenticated" && !allowUnauth) {
     console.error(
-      "[drupal-mcp-connector] FATAL: MCP_AUTH_TOKEN is required when binding beyond loopback.\n" +
-      "  Set MCP_AUTH_TOKEN, bind to 127.0.0.1 (default without MCP_BIND_HOST), or set\n" +
-      "  MCP_ALLOW_UNAUTHENTICATED=1 only behind a trusted auth boundary."
+      "[drupal-mcp-connector] WARNING: the /mcp endpoint is UNAUTHENTICATED. " +
+      "Acceptable only on loopback or behind a trusted auth boundary."
     );
-    process.exit(1);
   }
 
   // Optional fixed-window rate limiting on /mcp, keyed by client IP.
@@ -393,6 +461,8 @@ if (transport === "stdio") {
   });
   const requestHandler = createMcpRequestHandler({
     checkAuth,
+    authenticate,
+    protectedResource,
     modernHandler,
     legacyHandler,
     toolCount: allDefinitions.length,

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/config.js

@@ -221,6 +221,29 @@ export function listSiteNames() {
   return Object.keys(loadConfig().sites);
 }
 
+/**
+ * Configured default site name (used only as a hint after entitlement).
+ * @returns {string}
+ */
+export function getDefaultSiteName() {
+  return loadConfig().defaultSite;
+}
+
+/**
+ * Server-resolved inbound site grants keyed by OAuth client id.
+ * A missing or empty map means "no grant table" (every resolvable site).
+ * A present map is fail-closed: unknown clients receive no sites.
+ * @returns {object|null}
+ */
+export function getInboundGrants() {
+  const grants = loadConfig().auth?.grants;
+  if (!grants || typeof grants !== "object" || Array.isArray(grants)) return null;
+  const entries = Object.entries(grants)
+    .filter(([clientId, sites]) => !clientId.startsWith("_") && Array.isArray(sites))
+    .map(([clientId, sites]) => [clientId, sites.map(String)]);
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
 // ---------------------------------------------------------------------------
 // Auth headers — never logged, never exposed in tool responses
 // ---------------------------------------------------------------------------