drupal-mcp-connector 2.14.2 → 2.15.1

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

@@ -1,23 +1,25 @@
 ---
-description: "Create a translation as an unpublished non-default draft revision (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. English live title, body, status, alias, and default revision stay unchanged. An existing translation is a conflict, not an overwrite. Continue the draft with drupal_update_node and langcode. Requires Sentinel's draft-translation endpoint and a translatable bundle. Paragraph field values are not translated on this path. Defaults to node. Publication stays denied for content-tier callers."
-argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [dryRun]"
+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 a translation as an unpublished non-default draft revision (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. English live title, body, status, alias, and default revision stay unchanged. An existing translation is a conflict, not an overwrite. Continue the draft with drupal_update_node and langcode. Requires Sentinel's draft-translation endpoint and a translatable bundle. Paragraph field values are not translated on this path. Defaults to node. Publication stays denied for content-tier callers.
+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. 'basic_page'
+- `type` (string): Bundle machine name, e.g. 'basic_page' or 'p_hero'
 - `id` (string): Entity UUID
 - `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

@@ -19,7 +19,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `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-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 revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. 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 revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. 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 (ERR meta.target_revision_id). Honored on the read; a different served vid is an error.
 
 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-nodes.md

@@ -1,11 +1,11 @@
 ---
-description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors."
+description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set."
 argument-hint: "<type> [site] [status] [limit] [offset] [filters] [sort]"
 ---
 
 Call the MCP tool `drupal_list_nodes`.
 
-List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors.
+List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/.agents/commands/drupal-list-translations.md

@@ -1,11 +1,11 @@
 ---
-description: "List live and working translation langcodes for a Drupal node. 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."
+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 live and working translation langcodes for a Drupal node. 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.
+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:
 

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

@@ -23,8 +23,8 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `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,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.1] - 2026-09-10
+
+### Fixed
+- **`drupal_get_paragraph` honors `revisionId` and refuses a default-revision fallback (#292).**
+  Passing the host pin without `langcode` now reads JSON:API
+  `?resourceVersion=id:<vid>`. If Drupal serves a different
+  `drupal_internal__revision_id` (or nothing), the tool errors instead of
+  returning the live default revision. `ref.meta.target_revision_id` is the
+  served vid. `langcode` still uses Sentinel's draft read.
+- **`drupal_list_nodes` no longer reports a Drupal-capped page as the exact collection total (#291).**
+  Core JSON:API silently caps `page[limit]` at 50 and does not send `meta.count`.
+  The connector was treating that page length as `total` with `approximate: false`,
+  so a `limit: 100` call on a 54-item collection returned 50 and looked complete.
+  `listEntities` now follows `links.next` to fill a larger requested limit (up to
+  1000) and only reports an exact `total` when `meta.count` is present or the
+  window reached the end. Otherwise `approximate` is true and `hasNext` is
+  returned on the tool result.
+
+## [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
@@ -1501,6 +1571,8 @@ 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.15.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.1
+[2.15.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.0
 [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

package/README.md

@@ -1,6 +1,6 @@
 # drupal-mcp-connector
 
-> A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed content tools, audit reports, and an SSH Drush bridge.
+> A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed draft translations, content tools, audit reports, and an SSH Drush bridge.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
@@ -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,7 +1,7 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.14.2",
-  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
+  "version": "2.15.1",
+  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",
   "bin": {

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.