drupal-mcp-connector 2.14.1 → 2.15.0

package/.agents/commands/drupal-create-translation.md

@@ -1,22 +1,25 @@
 ---
-description: "Create or replace a translation of a Drupal entity for a target language (governed write). Sets the given langcode plus the supplied translated field values. Requires the content_translation module enabled and the bundle configured as translatable; otherwise Drupal rejects the write. Defaults to node."
-argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes]"
+description: "Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; continue a paragraph with drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers."
+argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [relationships] [revisionId] [dryRun]"
 ---
 
 Call the MCP tool `drupal_create_translation`.
 
-Create or replace a translation of a Drupal entity for a target language (governed write). Sets the given langcode plus the supplied translated field values. Requires the content_translation module enabled and the bundle configured as translatable; otherwise Drupal rejects the write. Defaults to node.
+Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; continue a paragraph with drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
-- `type` (string): Bundle machine name, e.g. 'article'
+- `type` (string): Bundle machine name, e.g. 'basic_page' or 'p_hero'
 - `id` (string): Entity UUID
-- `langcode` (string): Target language code, e.g. 'de', 'fr', 'pt_br'
+- `langcode` (string): Target language code, e.g. 'es', 'de', 'pt-br'
 
 **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).
-- `entityType` (string): Entity type machine name. Default: 'node'.
+- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values.
 - `attributes` (object (pass as JSON)): Translated field values keyed by Drupal machine name
+- `relationships` (object (pass as JSON)): JSON:API relationships. Use for image alt (same file UUID, meta.alt).
+- `revisionId` (string): Paragraph revision id the host already pins. Required for Home-shaped non-default pins.
+- `dryRun` (boolean (true/false)): Validate without saving
 
 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-entity-update.md

@@ -1,6 +1,6 @@
 ---
 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 a non-saving PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#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]"
+argument-hint: "<entityType> <bundle> <id> [site] [langcode] [attributes] [relationships] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_entity_update`.
@@ -16,9 +16,10 @@ 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).
+- `langcode` (string): Target language for an unpublished working translation (nodes). Continues that translation via Sentinel.
 - `attributes` (object (pass as JSON))
 - `relationships` (object (pass as JSON))
-- `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. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal 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. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal 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, 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-get-node.md

@@ -1,11 +1,11 @@
 ---
-description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes."
-argument-hint: "<type> <id> [site]"
+description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English)."
+argument-hint: "<type> <id> [site] [langcode]"
 ---
 
 Call the MCP tool `drupal_get_node`.
 
-Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes.
+Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English).
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,5 +15,6 @@ 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).
+- `langcode` (string): Target language (e.g. 'es') to read the unpublished working translation instead of the default language.
 
 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-get-paragraph.md

@@ -1,11 +1,11 @@
 ---
-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]"
+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. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy."
+argument-hint: "<paragraphType> <id> [site] [langcode] [revisionId]"
 ---
 
 Call the MCP tool `drupal_get_paragraph`.
 
-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.
+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. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,5 +15,7 @@ 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).
+- `langcode` (string): Target language for the unpublished working translation (e.g. 'es').
+- `revisionId` (string): Paragraph revision id the host already pins.
 
 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-get-revision.md

@@ -1,11 +1,11 @@
 ---
-description: "Fetch a single revision of a content node by version id or alias. `version` may be a numeric vid (e.g. 42), an explicit 'id:<vid>', or the relative aliases 'rel:latest-version' / 'rel:working-copy'. Read-only; attributes are redacted per security policy."
-argument-hint: "<type> <id> <version> [site]"
+description: "Fetch a single revision of a content node by version id or alias. `version` may be a numeric vid (e.g. 42), an explicit 'id:<vid>', or the relative aliases 'rel:latest-version' / 'rel:working-copy'. Pass langcode to read the unpublished working translation of that node (Sentinel). Read-only; attributes are redacted per security policy."
+argument-hint: "<type> <id> <version> [site] [langcode]"
 ---
 
 Call the MCP tool `drupal_get_revision`.
 
-Fetch a single revision of a content node by version id or alias. `version` may be a numeric vid (e.g. 42), an explicit 'id:<vid>', or the relative aliases 'rel:latest-version' / 'rel:working-copy'. Read-only; attributes are redacted per security policy.
+Fetch a single revision of a content node by version id or alias. `version` may be a numeric vid (e.g. 42), an explicit 'id:<vid>', or the relative aliases 'rel:latest-version' / 'rel:working-copy'. Pass langcode to read the unpublished working translation of that node (Sentinel). Read-only; attributes are redacted per security policy.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -16,5 +16,6 @@ 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).
+- `langcode` (string): Target language for the unpublished working translation (e.g. 'es').
 
 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-list-translations.md

@@ -1,16 +1,16 @@
 ---
-description: "List the translation langcode(s) for a Drupal entity (multilingual / content_translation). Reports the language(s) observable on the resource. Core JSON:API serves one language per resource and does not enumerate all translations — see the returned note. Defaults to node."
+description: "List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft). Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node."
 argument-hint: "<type> <id> [site] [entityType]"
 ---
 
 Call the MCP tool `drupal_list_translations`.
 
-List the translation langcode(s) for a Drupal entity (multilingual / content_translation). Reports the language(s) observable on the resource. Core JSON:API serves one language per resource and does not enumerate all translations — see the returned note. Defaults to node.
+List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft). Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
-- `type` (string): Bundle machine name, e.g. 'article'
+- `type` (string): Bundle machine name, e.g. 'basic_page'
 - `id` (string): Entity UUID
 
 **Optional:**

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

@@ -1,11 +1,11 @@
 ---
-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 a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#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]"
+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. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. 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 a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#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] [langcode] [fields] [relationships] [dryRun] [returning]"
 ---
 
 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 a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#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.
+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. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. 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 a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#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 arguments supplied with this command into this tool's parameters:
 
@@ -21,9 +21,10 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `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'.
+- `langcode` (string): Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode.
 - `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. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun.
+- `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. Image alt on a translation uses the existing file UUID plus meta.alt; replacing the file is refused.
+- `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. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal 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, 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-paragraph.md

@@ -1,11 +1,11 @@
 ---
-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]"
+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. Pass langcode to continue an unpublished paragraph translation via Sentinel (the host pin, not a live English mutation). Omitting langcode still uses canonical JSON:API and remains gated on published-host children. 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] [langcode] [revisionId] [draftState]"
 ---
 
 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.
+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. Pass langcode to continue an unpublished paragraph translation via Sentinel (the host pin, not a live English mutation). Omitting langcode still uses canonical JSON:API and remains gated on published-host children. 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 arguments supplied with this command into this tool's parameters:
 
@@ -16,5 +16,8 @@ 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).
 - `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' } }
+- `langcode` (string): Target language for an unpublished paragraph translation (e.g. 'es'). Continues Sentinel /mcp-draft; does not create a missing translation.
+- `revisionId` (string): Paragraph revision id the host already pins. Required when that pin is not the default revision.
+- `draftState` (string): Required with langcode. Opaque draftState from the previous paragraph draft read/create/update; prevents overwriting newer edits.
 
 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,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-09-10
+
+### Fixed
+- Paragraph translation updates require the `draftState` returned by a previous draft read. Pass it unchanged to Sentinel for stale-write protection. Shared-status paragraphs remain pending for human editing (#280).
+- **Omit computed `metatag` on unpublished working-translation bodies (#283).**
+  JSON:API's computed `metatag` array is resolved from the live default
+  revision, so a Spanish draft response could still show English title and
+  description. The stored override (`field_metatags`) is unchanged. Draft
+  translation create/read now drop `fields.metatag` and set `_metatagOmitted`.
+
+- **`drupal_create_translation` sends live and working revision IDs when a draft exists (#282).**
+  Sentinel's translation POST 409s with "A working revision exists" if If-Match
+  is live-only. The connector now reads Sentinel's translation inventory for
+  the live/working pair (falling back to `rel:working-copy`) and sends
+  `If-Match: "live:working"`. The response includes `_revisions` so the caller
+  can see which revision the language landed on.
+
+- **`dryRun` fails when a published-node write would hit Sentinel's stale-copy check (#273).**
+  The id-mismatch PATCH probe never reaches entity validation / presave, so it
+  could not see MCP Sentinel's default-revision stale-version refusal. When
+  `rel:latest-version` and `rel:working-copy` share a vid and the default
+  revision's `changed` is later than `revision_timestamp` (`possiblyPatchBlocked`),
+  `drupal_update_node` / `drupal_entity_update` (including `dryRun`) now refuse
+  with a stable `STALE_COPY` error. The same message is rewritten if Sentinel
+  still returns it on the saving write. Governance is unchanged: the draft and
+  publish gates are not bypassed.
+- **Title-only node updates keep the existing URL alias; failed restorations error (#274).**
+  `getPathInfo` now fills `pid` / `aliasId` from the `path_alias` row when an
+  unpublished default or forward revision omits them on the computed `path`
+  field. After `drupal_update_node`, the connector re-reads the alias and, if
+  Pathauto still drifted it, PATCHes the existing `path_alias` entity. If the
+  alias still does not match, the tool throws instead of returning success or
+  creating a rename redirect. Title-only edits pin the live alias as before.
+
+### Added
+- **Codex skill target for `npm run install:commands` (#263).**
+  The installer writes `$HOME/.agents/skills/drupal-mcp/SKILL.md` (plus
+  `references/tools.md`) so Drupal MCP tools are discoverable in Codex. Custom
+  prompts under `~/.codex/prompts` are not written — OpenAI deprecated that
+  surface in favor of skills. Default clients are now `claude,grok,codex`.
+  Test with `--home` on an isolated directory.
+
+- **Unpublished paragraph field-value translation and image alt (#280).**
+  `drupal_create_translation` accepts `entityType: "paragraph"` and
+  `revisionId` (the host pin) and POSTs Sentinel's paragraph
+  `/mcp-draft/translations` surface. Continue with `drupal_update_paragraph`
+  + `langcode`; read with `drupal_get_paragraph` + `langcode`. Omitting
+  `langcode` on `drupal_update_paragraph` still uses canonical JSON:API.
+  Node translation writes forward image relationships so alt can change
+  while the file UUID stays the same. Replacing the file remains a
+  server refusal. Node-only translation create is unchanged.
+
+## [2.14.2] - 2026-09-10
+
+### Fixed
+- **`langcode` reads target only an unpublished working translation.**
+  After a Spanish draft exists, English on that working revision is still
+  the published copy. `drupal_get_node` / `drupal_get_revision` with
+  `langcode` now read the working translation only when that language is
+  unpublished, so they do not treat published English as a draft.
+- **Spanish (and other) draft translations beside published English (#276).**
+  `drupal_create_translation` no longer PATCHes `langcode` on the canonical
+  entity. It POSTs Sentinel's `/mcp-draft/translations` endpoint so Drupal
+  calls `addTranslation()` on an unpublished forward revision. The live
+  default language, revision id, title, body, status, and alias stay
+  unchanged. An existing translation is a conflict. Continue the draft with
+  `drupal_update_node` + `langcode`; read it with `drupal_get_node` /
+  `drupal_list_translations` / `drupal_get_revision` + `langcode`. Requires
+  MCP Sentinel with the draft-translation contract. Paragraph field-value
+  translation and media photo-alt translation remain pending. A content-tier
+  caller still cannot publish through this path.
+
 ## [2.14.1] - 2026-09-09
 
 ### Changed
@@ -1481,6 +1553,7 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.14.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.2
 [2.14.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.1
 [2.14.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.0
 [2.13.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.1

package/README.md

@@ -129,13 +129,15 @@ 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/`:
+Grok `~/.grok/commands`, Codex `$HOME/.agents/skills`) install from that tree
+into the **operator home**, so no consuming project has to commit `.claude/` or
+`.grok/`. Codex uses a **skill** (`drupal-mcp`), not deprecated custom prompts:
 
 ```bash
 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     # copies into ~/.claude/commands, ~/.grok/commands, and ~/.agents/skills/drupal-mcp/
 # npm run install:commands -- --clients claude
+# npm run install:commands -- --clients codex
 # npm run install:commands -- --home /path/to/fake-home   # tests / CI
 ```
 

package/package.json

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

package/scripts/generate-commands.js

@@ -8,14 +8,17 @@
  * Build, when this repo is the project) pick them up as `/drupal-<tool>`.
  *
  * Clients that only scan a vendor home directory (Claude Code `~/.claude/commands`,
- * Grok `~/.grok/commands`) get the same files via `npm run install:commands`.
+ * Grok `~/.grok/commands`, Codex `$HOME/.agents/skills`) get the same files via
+ * `npm run install:commands`. Codex receives one skill (`drupal-mcp`), not
+ * per-tool custom prompts.
  *
  * 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`, `renderClaudeCommandMarkdown`, `commandFileName`,
- * `COMMANDS_DIR`, and `generate` for tests; the file-writing side effect runs only
- * when executed directly.
+ * Exports `renderCommandMarkdown`, `renderClaudeCommandMarkdown`,
+ * `renderCodexSkillMarkdown`, `renderCodexToolsReference`, `CODEX_SKILL_NAME`,
+ * `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";
@@ -113,6 +116,62 @@ export function renderClaudeCommandMarkdown(def) {
   });
 }
 
+/** Codex user-skill directory name under `$HOME/.agents/skills/`. */
+export const CODEX_SKILL_NAME = "drupal-mcp";
+
+/**
+ * Codex skill adapter (OpenAI Skills). Custom `~/.codex/prompts` slash
+ * commands are deprecated; Codex discovers `$HOME/.agents/skills/<name>/SKILL.md`.
+ * One skill covers the whole Drupal MCP tool surface so the skills list stays
+ * inside Codex's discovery budget.
+ *
+ * @param {Array<object>} [definitions]
+ * @returns {string} SKILL.md contents.
+ */
+export function renderCodexSkillMarkdown(definitions = allDefinitions) {
+  const count = definitions.length;
+  return [
+    "---",
+    `name: ${yamlString(CODEX_SKILL_NAME)}`,
+    `description: ${yamlString(
+      "Use Drupal MCP tools (drupal_*) via drupal-mcp-connector to read or write Drupal content, media, taxonomy, reports, and config. Trigger when the user asks to work with a Drupal site over MCP.",
+    )}`,
+    "---",
+    "",
+    "Call Drupal MCP tools by their protocol names (`drupal_list_nodes`, `drupal_update_node`, …).",
+    "The MCP server is configured separately (`codex mcp add drupal`); this skill does not replace that connection and does not use deprecated Codex custom prompts.",
+    "",
+    "Parse the user's request into the tool's parameters. If a required parameter is missing, ask before calling.",
+    "Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the tool call and summarize the result.",
+    "",
+    "Destructive tools permanently change or delete data — confirm with the user before calling.",
+    "Do not invent REST paths, Drush commands, or Drupal admin URLs when an MCP tool exists.",
+    "",
+    `The connector currently exposes **${count}** tools. Full names and descriptions: [references/tools.md](references/tools.md).`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Progressive-disclosure catalog for the Codex Drupal skill.
+ * @param {Array<object>} [definitions]
+ * @returns {string} references/tools.md contents.
+ */
+export function renderCodexToolsReference(definitions = allDefinitions) {
+  const lines = [
+    "# Drupal MCP tools",
+    "",
+    "Protocol tool names for `drupal-mcp-connector`. Call these via MCP; do not invent REST paths.",
+    "",
+  ];
+  for (const def of definitions) {
+    const desc = String(def.description || "").replace(/\s+/g, " ").trim();
+    lines.push(`- \`${def.name}\`${desc ? ` — ${desc}` : ""}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
 /**
  * Write one command file per tool, pruning stale `drupal-*.md` first so removed
  * tools leave no orphans.

package/scripts/install-commands.js

@@ -9,11 +9,12 @@
  * copies so `/drupal-*` works in every project without committing a vendor
  * folder to this repo or to a consuming application.
  *
- * Default targets: `~/.claude/commands` (Claude adapter) and `~/.grok/commands`
- * (canonical files). Pass `--clients` to subset. Never writes into a project
- * tree.
+ * Default targets: `~/.claude/commands` (Claude adapter), `~/.grok/commands`
+ * (canonical files), and `$HOME/.agents/skills/drupal-mcp/` (Codex skill).
+ * Pass `--clients` to subset. Never writes into a project tree. Codex custom
+ * prompts (`~/.codex/prompts`) are not written — they are deprecated.
  *
- * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,agents]`
+ * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,codex,agents]`
  */
 
 import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
@@ -26,6 +27,9 @@ import {
   commandFileName,
   renderCommandMarkdown,
   renderClaudeCommandMarkdown,
+  renderCodexSkillMarkdown,
+  renderCodexToolsReference,
+  CODEX_SKILL_NAME,
 } from "./generate-commands.js";
 
 /** Whitelisted install targets. `rel` is under `--home` (default: os.homedir()). */
@@ -42,9 +46,18 @@ export const CLIENTS = {
     rel: ".agents/commands",
     render: renderCommandMarkdown,
   },
+  // Codex discovers user skills at `$HOME/.agents/skills/<name>/SKILL.md`.
+  // One skill for the whole tool surface — not one skill per tool.
+  codex: {
+    rel: ".agents/skills",
+    kind: "skill",
+    skillName: CODEX_SKILL_NAME,
+    renderSkill: renderCodexSkillMarkdown,
+    renderReference: renderCodexToolsReference,
+  },
 };
 
-const DEFAULT_CLIENTS = ["claude", "grok"];
+const DEFAULT_CLIENTS = ["claude", "grok", "codex"];
 
 /**
  * Parse CLI flags. Unknown flags throw.
@@ -111,6 +124,15 @@ export function install(options = {}) {
     if (!client) {
       throw new Error(`Unknown client "${name}". Allowed: ${Object.keys(CLIENTS).join(", ")}`);
     }
+    if (client.kind === "skill") {
+      const dir = join(home, client.rel, client.skillName);
+      rmSync(dir, { recursive: true, force: true });
+      mkdirSync(join(dir, "references"), { recursive: true });
+      writeFileSync(join(dir, "SKILL.md"), client.renderSkill(definitions));
+      writeFileSync(join(dir, "references", "tools.md"), client.renderReference(definitions));
+      results.push({ client: name, dir, written: ["SKILL.md", "references/tools.md"] });
+      continue;
+    }
     const dir = join(home, client.rel);
     mkdirSync(dir, { recursive: true });
     for (const f of readdirSync(dir)) {
@@ -127,14 +149,15 @@ export function install(options = {}) {
   return results;
 }
 
-const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,agents]
+const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,codex,agents]
 
-Copy generated /drupal-* command stubs into operator home directories.
-Does not write into a project tree.
+Copy generated /drupal-* command stubs (and the Codex skill) into operator
+home directories. Does not write into a project tree. Does not write
+deprecated Codex custom prompts (~/.codex/prompts).
 
   --home DIR       Install root (default: the current user's home)
-  --clients LIST   Comma-separated subset of: claude, grok, agents
-                   (default: claude,grok)
+  --clients LIST   Comma-separated subset of: claude, grok, codex, agents
+                   (default: claude,grok,codex)
 `;
 
 const invokedDirectly =

package/src/lib/backends/backend-interface.js

@@ -79,10 +79,12 @@ export class Backend {
    * for callers that must round-trip the alias `pid` on an in-place update (the
    * canonical entity only exposes `path.alias` as `url`). Optional capability:
    * the default returns nulls so read-only/path-less backends are safe. See the 1.5.1 alias fix.
-   * @param {{entityType: string, bundle: string, id: string}} _ref
-   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
+   * @param {{entityType: string, bundle: string, id: string, resourceVersion?: string}} _ref
+   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string), aliasId: ?string}>}
    */
-  async getPathInfo(_ref) { return { alias: null, pid: null, langcode: null, drupalId: null }; }
+  async getPathInfo(_ref) {
+    return { alias: null, pid: null, langcode: null, drupalId: null, aliasId: null };
+  }
 
   /**
    * Create an entity.