drupal-mcp-connector 2.7.3 → 2.8.0

package/.agents/commands/drupal-site-info.md

@@ -0,0 +1,15 @@
+---
+description: "Get the base URL and the list of available resource/query types for a configured site (works for JSON:API and GraphQL backends)."
+argument-hint: "[site]"
+---
+
+Call the MCP tool `drupal_site_info`.
+
+Get the base URL and the list of available resource/query types for a configured site (works for JSON:API and GraphQL backends).
+
+Parse the arguments supplied with this command into this tool's parameters:
+
+**Optional:**
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+
+If a required parameter is missing, 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/.agents/commands/drupal-update-media.md

@@ -0,0 +1,22 @@
+---
+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]"
+---
+
+Call the MCP tool `drupal_update_media`.
+
+Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.
+
+Parse the arguments supplied with this command into this tool's parameters:
+
+**Required:**
+- `type` (string)
+- `id` (string)
+
+**Optional:**
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `name` (string)
+- `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, 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 → .agents}/commands/drupal-update-menu-link.md

@@ -1,20 +1,19 @@
 ---
 description: "Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Checked against the site security config."
 argument-hint: "<id> [site] [title] [link] [menu] [weight] [parent] [enabled]"
-allowed-tools: mcp__drupal__drupal_update_menu_link
 ---
 
-Call the `mcp__drupal__drupal_update_menu_link` MCP tool.
+Call the MCP tool `drupal_update_menu_link`.
 
 Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Checked against the site security config.
 
-Parse the request in `$ARGUMENTS` into this tool's parameters:
+Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
 - `id` (string): Menu link UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `title` (string): New link label. Omit to leave unchanged.
 - `link` (string): New target URI (e.g. 'entity:node/42'). Omit to leave unchanged.
 - `menu` (string): Move the link to this menu. Omit to leave unchanged.
@@ -22,4 +21,4 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `parent` (string): New parent link plugin id (e.g. 'menu_link_content:<uuid>'), or '' for top level. Omit to leave unchanged.
 - `enabled` (boolean (true/false)): Enable/disable the link. Omit to preserve the current state.
 
-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.
+If a required parameter is missing, 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 → .agents}/commands/drupal-update-node.md

@@ -1,30 +1,29 @@
 ---
-description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets an id-mismatch PATCH preflight runs first — including on dryRun — so a core working-copy guard failure is reported before the real write and no revision is saved by the probe. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents."
+description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets an id-mismatch PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents."
 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.
+Call the MCP tool `drupal_update_node`.
 
-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.
+Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets an id-mismatch PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable working copy is PATCHed via ?resourceVersion=rel:working-copy (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.
 
-Parse the request in `$ARGUMENTS` into this tool's parameters:
+Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
 - `type` (string)
 - `id` (string): Node UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `title` (string)
 - `body` (string)
-- `summary` (string): Body summary/teaser — writes the `summary` property of the body field (core `text_with_summary`). Many headless sites instead use a dedicated summary/deck field for teasers and meta descriptions; on those, set that field in `fields` — a value written here will be stored but may never be rendered.
-- `format` (string): Text format machine name for the body, e.g. 'basic_html'. Defaults to the site config's `defaultTextFormat`, then 'full_html'. Set this when the site's formats do not include full_html, or to avoid writing content into a more permissive format than intended.
+- `summary` (string): Body summary/teaser — writes body.summary on core text_with_summary only. Refused when the sampled body field has no summary property (text_long / text_formatted) or the schema cannot be determined. Prefer the site's dedicated deck/summary field via `fields`.
+- `format` (string): Text format machine name for the body, e.g. 'basic_html'. When the body field's allowed_formats lists exactly one format, that is the default. A caller format outside that list is refused before write. When allowed_formats cannot be resolved, defaults to the site config's `defaultTextFormat`, then 'full_html'.
 - `status` (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.
+- `fields` (object (pass as JSON)): Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here.
 - `relationships` (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.
+- `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, and hits the same URL as the real write (canonical, or ?resourceVersion=rel:working-copy when a draft is addressable). A working-copy 400 fails the dryRun.
 - `returning` (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.
+If a required parameter is missing, 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 → .agents}/commands/drupal-update-paragraph.md

@@ -1,21 +1,20 @@
 ---
 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.
+Call the MCP tool `drupal_update_paragraph`.
 
 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:
+Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
 - `paragraphType` (string): Paragraph type / bundle machine name, e.g. 'text', 'image', 'cta'
 - `id` (string): Paragraph UUID
 
 **Optional:**
-- `site` (string): Named site (omit for default)
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `attributes` (object (pass as JSON)): Paragraph field values to change, keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }
 
-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.
+If a required parameter is missing, 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 → .agents}/commands/drupal-update-redirect.md

@@ -1,22 +1,21 @@
 ---
 description: "Update an existing redirect by UUID: repoint its source or target, or change its status code (e.g. 301↔302). Only the fields you pass are changed (partial update). Use this to activate/fix a redirect that isn't firing (e.g. one created with a stale source). Governed by the site security policy."
 argument-hint: "<id> [site] [source] [target] [statusCode]"
-allowed-tools: mcp__drupal__drupal_update_redirect
 ---
 
-Call the `mcp__drupal__drupal_update_redirect` MCP tool.
+Call the MCP tool `drupal_update_redirect`.
 
 Update an existing redirect by UUID: repoint its source or target, or change its status code (e.g. 301↔302). Only the fields you pass are changed (partial update). Use this to activate/fix a redirect that isn't firing (e.g. one created with a stale source). Governed by the site security policy.
 
-Parse the request in `$ARGUMENTS` into this tool's parameters:
+Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
 - `id` (string): Redirect entity UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `source` (string): New source/old path (leading slash optional). Omit to leave unchanged.
 - `target` (string): New destination path/URI. Omit to leave unchanged.
 - `statusCode` (number): New HTTP redirect status code (301/302/303/307/308). Omit to leave unchanged.
 
-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.
+If a required parameter is missing, 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/.agents/commands/drupal-update-taxonomy-term.md

@@ -0,0 +1,22 @@
+---
+description: "Update an existing taxonomy term's name, description, or weight."
+argument-hint: "<vocabulary> <id> [site] [name] [description] [weight]"
+---
+
+Call the MCP tool `drupal_update_taxonomy_term`.
+
+Update an existing taxonomy term's name, description, or weight.
+
+Parse the arguments supplied with this command into this tool's parameters:
+
+**Required:**
+- `vocabulary` (string)
+- `id` (string)
+
+**Optional:**
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `name` (string)
+- `description` (string)
+- `weight` (number)
+
+If a required parameter is missing, 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/.agents/commands/drupal-update-user.md

@@ -0,0 +1,24 @@
+---
+description: "Update a Drupal user account. Only include fields you want to change. Can reassign roles by providing a full replacement role list."
+argument-hint: "<id> [site] [name] [mail] [password] [status] [roles] [timezone]"
+---
+
+Call the MCP tool `drupal_update_user`.
+
+Update a Drupal user account. Only include fields you want to change. Can reassign roles by providing a full replacement role list.
+
+Parse the arguments supplied with this command into this tool's parameters:
+
+**Required:**
+- `id` (string): User UUID
+
+**Optional:**
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `name` (string)
+- `mail` (string)
+- `password` (string)
+- `status` (boolean (true/false))
+- `roles` (array (pass as JSON)): Full replacement role UUID list
+- `timezone` (string)
+
+If a required parameter is missing, 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 → .agents}/commands/drupal-upload-file-and-create-media.md

@@ -1,14 +1,13 @@
 ---
 description: "Convenience tool: upload a local file and immediately create a Media entity in one step. Best for the common 'add an image' workflow. Media defaults to unpublished."
 argument-hint: "<filePath> <mediaType> <fieldName> [site] [mediaName] [altText] [status]"
-allowed-tools: mcp__drupal__drupal_upload_file_and_create_media
 ---
 
-Call the `mcp__drupal__drupal_upload_file_and_create_media` MCP tool.
+Call the MCP tool `drupal_upload_file_and_create_media`.
 
 Convenience tool: upload a local file and immediately create a Media entity in one step. Best for the common 'add an image' workflow. Media defaults to unpublished.
 
-Parse the request in `$ARGUMENTS` into this tool's parameters:
+Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
 - `filePath` (string): Local path to the file (must resolve under MCP_UPLOAD_ROOT or the connector working directory)
@@ -16,9 +15,9 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `fieldName` (string): Source field machine name, e.g. 'field_media_image'
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `mediaName` (string): Name for the media entity (defaults to filename)
 - `altText` (string): Alt text for image media
 - `status` (boolean (true/false)): Published flag. Defaults to false. Requires allowPublish when true.
 
-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.
+If a required parameter is missing, 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 → .agents}/commands/drupal-upload-file.md

@@ -1,14 +1,13 @@
 ---
 description: "Upload a local file to Drupal and create a File entity. Returns the file UUID to use when creating a Media entity. For images, the typical flow is: drupal_upload_file → drupal_create_media."
 argument-hint: "<filePath> <bundle> <fieldName> [site] [entityType]"
-allowed-tools: mcp__drupal__drupal_upload_file
 ---
 
-Call the `mcp__drupal__drupal_upload_file` MCP tool.
+Call the MCP tool `drupal_upload_file`.
 
 Upload a local file to Drupal and create a File entity. Returns the file UUID to use when creating a Media entity. For images, the typical flow is: drupal_upload_file → drupal_create_media.
 
-Parse the request in `$ARGUMENTS` into this tool's parameters:
+Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
 - `filePath` (string): Local path to the file (must resolve under MCP_UPLOAD_ROOT or the connector working directory)
@@ -16,7 +15,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `fieldName` (string): Field machine name, e.g. 'field_media_image', 'field_image'
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `entityType` (string): Drupal entity type (usually 'media' or 'node')
 
-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.
+If a required parameter is missing, 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,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.8.0] - 2026-08-25
+
+### Fixed
+- **Iterative updates PATCH an existing working copy (#166).**
+  `drupal_update_node`, `drupal_entity_update`, and `drupal_bulk_update`
+  resolve `rel:working-copy` before the write. When that alias is
+  addressable, both the dryRun probe and the real PATCH use
+  `?resourceVersion=rel:working-copy` instead of the canonical URL, so a
+  second edit lands on the same forward revision. dryRun can no longer
+  succeed when that write would 400. An addressable draft is edited in
+  place — the connector does not discard it or tell the caller to publish
+  first. The stray-revision case (alias does not resolve, core still
+  blocks) still refuses with revision-surgery language (#201). A stale or
+  concurrent working-copy 400 is refused without retrying the canonical
+  URL. Successful writes include `_revisions: { live, working }` when both
+  vids can be read.
+- **`summary` is refused when body has no summary property (#163).**
+  `drupal_create_node` and `drupal_update_node` introspect the sampled body
+  field before writing `summary`. A `text_long` / `text_formatted` body (or
+  an undetermined schema) fails closed with an actionable message to set the
+  site's deck field via `fields`. Core `text_with_summary` still accepts
+  `summary` and returns `_warnings` with `summary_parameter_deprecated`.
+  dryRun uses the same check.
+- **Node writes honor field `allowed_formats` (#168).** Create/update (including
+  `dryRun`) resolve Field API `allowed_formats` from JSON:API `field_config`
+  and, when that is unavailable, Drush `config:get`. A single allowed format
+  is the default when the caller omits `format`. A caller format outside the
+  list is refused before mutation. The historical `defaultTextFormat` /
+  `full_html` fallback applies only while the list cannot be resolved — never
+  when `full_html` is excluded by field config.
+
+### Added
+- **Northbound data-flow budgets bind to principal and target (#179).** Every
+  governed tool call that resolves a site now carries request-scoped principal
+  and authoritative-target context. Row, byte, page, request, and chained-action
+  counters use the same finite defaults as mcp_sentinel (500 results / 8 MiB /
+  600 req/60s / 120 pages/60s) and are keyed by inbound principal + target —
+  not by MCP session — so pagination, retries, batching, and a new chain id
+  cannot reset them. JSON:API, GraphQL, and the server-tool bridge send the
+  source wire contract (`X-MCP-Declared-Ceiling`, narrow-only;
+  `X-MCP-Declared-Destination` from the entitlement pair). Denials name a
+  stable reason plus a correlation id and do not echo restricted payload.
+  Optional `security.declaredCeiling` and `security.readBudgets` override the
+  defaults. Stdio / local-operator traffic still sends the declared headers;
+  connector-side counters enforce when an inbound OAuth principal is present.
+
+### Changed
+- **Slash-command stubs moved to `.agents/commands/` (#218).** Generated
+  `/drupal-*` files are harness-agnostic (protocol tool names, no
+  `mcp__drupal__*` `allowed-tools`). `.claude/` is no longer tracked or
+  published. `npm run install:commands` copies stubs into operator home
+  directories (`~/.claude/commands` with the Claude Code adapter,
+  `~/.grok/commands` as-is) so the bare `/drupal-*` form still works
+  without a vendor folder in this repo or in a consuming project. The npm
+  `files` list now ships `.agents/commands/` instead of `.claude/commands/`.
+
+## [2.7.4] - 2026-08-18
+
+### Fixed
+- **`drupal_content_by_moderation_state` no longer 500s on stock JSON:API
+  (#162).** `moderation_state` is a computed field and is not filterable
+  over core JSON:API. The tool still tries the server-side filter (so a
+  jsonapi_extras alias keeps working), and when Drupal rejects it the
+  connector samples recent nodes and filters client-side. The payload
+  reports `source: "sampled"` and `approximate` instead of a raw Drupal
+  500. If the field is not exposed at all, the result is a gated
+  `unavailable` payload.
+- **Every tool response names the resolved site (#167).** Omitting `site`
+  still defaults to `defaultSite`, but the payload now carries
+  `_target: { name, baseUrl, source }` — the same block `drupal_mcp_whoami`
+  already returned as `target`. `source` is `hint` when the caller named a
+  site, `default` when the configured default was used, or `grant` when a
+  principal had exactly one entitled site. A list_nodes-shaped success with
+  only `_backend` is no longer claimable as production. Writes (including
+  GraphQL mutations and generic `drupal_entity_*` writes) refuse a silent
+  default when more than one site is configured; a write on the wrong site
+  is not recoverable. Single-site configs are unchanged. Array-shaped
+  results are wrapped as `{ items, _target }` so the field survives
+  `JSON.stringify`.
+
 ## [2.7.3] - 2026-08-18
 
 ### 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.7.3** (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.4** (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).
 
 ---
 
@@ -44,11 +44,14 @@ Each site declares which backend(s) it exposes via the `api` key:
 - **`api` accepts** `"jsonapi"`, `"graphql"`, or a priority array like `["graphql","jsonapi"]`. Omit it to **auto-detect** (the connector probes both once and caches the result).
 - **One canonical shape.** Both backends return entities as
   `{ id, entityType, bundle, title, status, langcode, created, changed, url, fields, relationships, _backend }`, so tool output is identical regardless of protocol.
+  Every site-addressing response also includes `_target: { name, baseUrl, source }` so a defaulted call cannot be mistaken for another environment.
 - **Capability-aware.** Each backend advertises what it supports (read, write, delete, server-side filter/sort, revisions). GraphQL via GraphQL Compose is **read-only** (no mutations) and has no server-side field filter, so filters are applied client-side over a bounded fetch and flagged `approximate`/`truncated`. Write tools against a read-only backend return a clear capability error rather than failing silently.
 - **Writes go through JSON:API.** Use a JSON:API-enabled site as the write plane; keep GraphQL as a read plane where that suits your architecture.
 - **`defaultTextFormat` sets the body text format** used by the `body` convenience
   parameter on node writes, e.g. `{ "baseUrl": "…", "defaultTextFormat": "basic_html" }`.
-  Individual calls can override it with `format`. Without either, the connector falls
+  Individual calls can override it with `format`. Field API `allowed_formats` wins
+  when it can be resolved: a single allowed format is the default, and a format
+  outside the list is refused. Without a resolved list, the connector falls
   back to `full_html`, which many governed sites deliberately do not define — and which
   is the most permissive core format, so setting this per site is the safer posture. A
   text format is Drupal's HTML-filtering boundary, so it is worth choosing deliberately
@@ -118,20 +121,27 @@ governed call to that tool. These are protocol-native, so they work everywhere t
 prompts capability is supported — the client renders them per its own convention
 (e.g. Claude Code shows `/mcp__drupal__drupal-create-node`).
 
-#### Claude Code slash commands (`/drupal-*`)
-For the literal bare `/drupal-<tool>` form in **Claude Code specifically**, the
-connector also ships generated command files under `.claude/commands/`. Because
-Claude Code project commands are per-project, copy them into your own project (or
-regenerate from the installed package):
+#### Filesystem slash commands (`/drupal-*`)
+MCP prompts (above) are the protocol-native slash surface. For the literal bare
+`/drupal-<tool>` form, the connector ships generated stubs under
+**`.agents/commands/`** — a harness-agnostic tree, not a vendor rule directory.
+Clients that scan `.agents/commands/` (including Grok Build when this repo is
+the project) pick them up automatically.
+
+Clients that only scan a vendor home path (Claude Code `~/.claude/commands`,
+Grok `~/.grok/commands`) install from that tree into the **operator home**, so
+no consuming project has to commit `.claude/` or `.grok/`:
 
 ```bash
-mkdir -p .claude/commands
-cp node_modules/drupal-mcp-connector/.claude/commands/drupal-*.md .claude/commands/
-# …or, from a clone of the connector:  npm run generate:commands
+npm run generate:commands    # refresh .agents/commands/ (from a clone)
+npm run install:commands     # copies into ~/.claude/commands and ~/.grok/commands
+# npm run install:commands -- --clients claude
+# npm run install:commands -- --home /path/to/fake-home   # tests / CI
 ```
 
-Other MCP agents don't need this step — they get the same coverage from the per-tool
-prompts above.
+From an npm install, the same files ship at
+`node_modules/drupal-mcp-connector/.agents/commands/`. Do not copy them into an
+application repo's `.claude/` or `.grok/` directory.
 
 ### Security Model
 
@@ -160,6 +170,7 @@ Additional connector-side gates (2.1+ / 2.2+):
 - **Uploads** only from `MCP_UPLOAD_ROOT` (or the process cwd); sensitive paths (`.env*`, `.ssh`, connector `config.json`) are refused.
 - **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`.
+- **Northbound data-flow budgets (2.8+):** row, byte, page, request, and chained-action counters keyed by inbound principal + authoritative target (same finite defaults as MCP Sentinel), so pagination, retries, batching, or a new chain id cannot reset them. Governed reads carry the declared-ceiling / declared-destination wire contract; tune with `security.declaredCeiling` and `security.readBudgets`.
 
 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_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."
+    "_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. Optional security.declaredCeiling (narrow-only X-MCP-Declared-Ceiling) and security.readBudgets (same finite classes as mcp_sentinel) bind northbound data-flow to the inbound principal and target. See docs/security.md and docs/security-hardening.md."
   },
 
   "_governance_tiers": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.7.3",
+  "version": "2.8.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",
@@ -11,7 +11,8 @@
   "files": [
     "src/",
     "scripts/generate-commands.js",
-    ".claude/commands/",
+    "scripts/install-commands.js",
+    ".agents/commands/",
     "config/config.example.json",
     "README.md",
     "CHANGELOG.md",
@@ -50,6 +51,7 @@
     "start:https": "MCP_TRANSPORT=https node src/index.js",
     "start:dev": "MCP_TRANSPORT=https MCP_ALLOW_HTTP=1 MCP_PORT=3443 node src/index.js",
     "generate:commands": "node scripts/generate-commands.js",
+    "install:commands": "node scripts/install-commands.js",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "test": "vitest run",

package/scripts/generate-commands.js

@@ -1,22 +1,21 @@
 #!/usr/bin/env node
 /**
- * generate-commands.js — generate Claude Code slash commands for every tool.
+ * generate-commands.js — generate harness-agnostic slash-command stubs for every tool.
  *
- * Writes one `.claude/commands/drupal-<tool>.md` per Drupal tool, giving the
- * literal `/drupal-<tool>` slash command in Claude Code (e.g.
- * `/drupal-create-node`). Each file is scoped via `allowed-tools` to only its own
- * `mcp__drupal__<tool>` and instructs the model to parse `$ARGUMENTS` into the
- * tool's parameters before making a single call.
+ * Writes one `.agents/commands/drupal-<tool>.md` per Drupal tool. The files use
+ * protocol tool names (`drupal_list_nodes`) so any MCP client can consume them;
+ * they are not a vendor rule tree. Clients that scan `.agents/commands/` (Grok
+ * Build, when this repo is the project) pick them up as `/drupal-<tool>`.
  *
- * These files are *client ergonomics* for operators using Claude Code as an MCP
- * client against this server — not provider-specific project rules. Development
- * instructions for any agent live only in AGENTS.md.
+ * Clients that only scan a vendor home directory (Claude Code `~/.claude/commands`,
+ * Grok `~/.grok/commands`) get the same files via `npm run install:commands`.
  *
  * Driven from the same tool definitions as the server (src/tools/index.js), so the
  * command set never drifts from the tools. Run: `npm run generate:commands`.
  *
- * Exports `renderCommandMarkdown`, `commandFileName`, and `generate` for tests; the
- * file-writing side effect runs only when executed directly.
+ * Exports `renderCommandMarkdown`, `renderClaudeCommandMarkdown`, `commandFileName`,
+ * `COMMANDS_DIR`, and `generate` for tests; the file-writing side effect runs only
+ * when executed directly.
  */
 
 import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
@@ -26,7 +25,8 @@ import { allDefinitions } from "../src/tools/index.js";
 import { paramList, toolNameToPromptName } from "../src/lib/tool-prompts.js";
 import { isDestructiveTool } from "../src/lib/operations.js";
 
-const COMMANDS_DIR = new URL("../.claude/commands/", import.meta.url);
+/** Canonical, harness-agnostic command tree shipped in the repo and the npm package. */
+export const COMMANDS_DIR = new URL("../.agents/commands/", import.meta.url);
 
 /** Map a tool definition to its command filename: `drupal_create_node` → `drupal-create-node.md`. */
 export function commandFileName(def) {
@@ -49,19 +49,26 @@ function argumentHint(params) {
  * Render the markdown for one tool's slash command.
  *
  * @param {object} def - The tool definition ({name, description, inputSchema}).
+ * @param {object} [options]
+ * @param {string} [options.allowedTools] - Optional Claude Code `allowed-tools` value.
+ * @param {string} [options.argumentsPhrase="the arguments supplied with this command"]
+ *   Phrase used in the parse-arguments instruction. Claude Code install rewrites
+ *   this to `` `$ARGUMENTS` `` because that client substitutes the placeholder.
  * @returns {string} File contents (ends with a trailing newline).
  */
-export function renderCommandMarkdown(def) {
+export function renderCommandMarkdown(def, options = {}) {
   const params   = paramList(def.inputSchema);
   const required = params.filter((p) => p.required);
   const optional = params.filter((p) => !p.required);
   const line = (p) => `- \`${p.name}\` (${p.hint})${p.description ? `: ${p.description}` : ""}`;
+  const argumentsPhrase = options.argumentsPhrase ?? "the arguments supplied with this command";
 
   const frontmatter = ["---", `description: ${yamlString(def.description)}`];
   if (params.length) frontmatter.push(`argument-hint: ${yamlString(argumentHint(params))}`);
-  frontmatter.push(`allowed-tools: mcp__drupal__${def.name}`, "---");
+  if (options.allowedTools) frontmatter.push(`allowed-tools: ${options.allowedTools}`);
+  frontmatter.push("---");
 
-  const body = [`Call the \`mcp__drupal__${def.name}\` MCP tool.`, "", def.description];
+  const body = [`Call the MCP tool \`${def.name}\`.`, "", def.description];
 
   if (isDestructiveTool(def.name)) {
     body.push("", "> ⚠ **Destructive** — this permanently changes or deletes data. Confirm with the user before calling.");
@@ -69,9 +76,9 @@ export function renderCommandMarkdown(def) {
 
   body.push("");
   if (params.length === 0) {
-    body.push("This tool takes no arguments — call it directly (ignore `$ARGUMENTS`).");
+    body.push("This tool takes no arguments — call it directly.");
   } else {
-    body.push("Parse the request in `$ARGUMENTS` into this tool's parameters:", "");
+    body.push(`Parse ${argumentsPhrase} into this tool's parameters:`, "");
     if (required.length) {
       body.push("**Required:**");
       required.forEach((p) => body.push(line(p)));
@@ -83,15 +90,29 @@ export function renderCommandMarkdown(def) {
       body.push("");
     }
     body.push(
-      "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."
+      "If a required parameter is missing, 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."
     );
   }
 
   return `${frontmatter.join("\n")}\n\n${body.join("\n")}\n`;
 }
 
+/**
+ * Claude Code adapter: same stub plus `allowed-tools` scoped to that client's
+ * MCP tool name, and `$ARGUMENTS` so typed `/drupal-*` args are not dropped.
+ *
+ * @param {object} def - The tool definition.
+ * @returns {string} File contents.
+ */
+export function renderClaudeCommandMarkdown(def) {
+  return renderCommandMarkdown(def, {
+    allowedTools: `mcp__drupal__${def.name}`,
+    argumentsPhrase: "`$ARGUMENTS`",
+  });
+}
+
 /**
  * Write one command file per tool, pruning stale `drupal-*.md` first so removed
  * tools leave no orphans.
@@ -118,5 +139,5 @@ const invokedDirectly =
   process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
 if (invokedDirectly) {
   const written = generate();
-  console.error(`[generate-commands] wrote ${written.length} command files to .claude/commands/`);
+  console.error(`[generate-commands] wrote ${written.length} command files to .agents/commands/`);
 }