drupal-mcp-connector 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-29
+
+### Added
+- **`drupal_update_paragraph`** — update an existing Paragraph entity's field values
+  in place (partial JSON:API PATCH) by bundle + UUID, so component / key-capability
+  paragraphs can be maintained end-to-end without re-embedding (DEV-114).
+- **`drupal_update_menu_link`** — update a menu link by UUID (rename, re-weight,
+  re-target, re-parent, enable/disable). `enabled` is preserved across edits unless
+  passed explicitly (DEV-114).
+- **`drupal_create_menu_link`** now accepts **`parent`** (nest under a parent link
+  plugin id) and **`enabled`** on create, and creates links **enabled by default** so
+  they render immediately — closing the "menu links created disabled / no parent on
+  create" gap (DEV-114).
+
+### Fixed
+- **Menu links no longer silently regress to disabled.** Every menu-link write now
+  asserts `enabled` explicitly (default true on create; the current value re-pinned on
+  update), so an unrelated edit can't drop a live link to disabled through the JSON:API
+  write path (DEV-114).
+- **Node updates preserve the existing URL alias.** When `drupal_update_node` is called
+  without a `path`, the connector reads the current alias and re-pins it
+  (`{ alias, pathauto: 0 }`) so a save can't let Pathauto revert the alias to a stale
+  value. Pass `fields.path` to set the alias explicitly (DEV-114).
+- **Intermittent `drupal_create_menu_link` 422 "path '/…' is inaccessible".** This is a
+  transient path-validator/access-cache race in Drupal's `LinkAccessConstraint`; menu-link
+  create/update now retries once after a short delay when it hits that specific error.
+  Prefer an `entity:node/<id>` target over `internal:/<alias>` to avoid the alias
+  resolution step entirely (DEV-114).
+
 ## [1.4.0] - 2026-06-29
 
 ### Added

package/README.md

@@ -71,8 +71,8 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 | **References** | Resolve a human name/title to an entity UUID for relationship fields |
 | **Bulk** | Bulk create/update with per-item partial-failure reporting |
 | **Translations** | List + create entity translations |
-| **Paragraphs** | Create/get Paragraph components for embedding in host fields |
-| **Structure** | Menu links + custom blocks (list/create) |
+| **Paragraphs** | Create/update/get Paragraph components for embedding in host fields |
+| **Structure** | Menu links (list/create/update, incl. `parent` + `enabled`) + custom blocks (list/create) |
 | **Redirects** | Create active URL redirects (301/302) + update/repoint existing redirects (Redirect module) |
 | **Search** | Best-effort content search (title match; Search API/Solr-ready) |
 | **Reports (extra)** | Orphaned references, unpublished content, missing-field audits |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "1.4.0",
+  "version": "1.5.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/src/tools/nodes.js

@@ -130,6 +130,12 @@ async function createNode({ site: siteName, type, title, body, summary, status,
  * bundles (sends `moderation_state`, omits `status`) or `status` for non-moderated
  * types. `moderationState` takes precedence; both are optional on update.
  *
+ * Alias hardening: a partial update that doesn't touch `path` can still lose the
+ * node's URL alias when a module (e.g. Pathauto, in automatic mode) regenerates
+ * it on save. To preserve the existing alias, when the caller supplies no `path`
+ * the current alias is read back and re-pinned (`{ alias, pathauto: 0 }`). Pass
+ * `fields.path` explicitly to set/replace the alias yourself.
+ *
  * @param {object} args - { site?, type, id, title?, body?, summary?, status?, moderationState?, fields? }.
  * @returns {Promise<object>} The updated node descriptor.
  */
@@ -143,6 +149,12 @@ async function updateNode({ site: siteName, type, id, title, body, summary, stat
   if (bodyAttr) attributes.body = bodyAttr;
   if (dryRun) return { dryRun: true, operation: "update", entityType: "node", bundle: type, id, attributes };
   const backend = await resolveBackend(site);
+  // Preserve the existing URL alias when the caller didn't set `path`: read the
+  // current alias and re-pin it (pathauto off) so the save can't revert it.
+  if (attributes.path === undefined) {
+    const current = await backend.getEntity({ entityType: "node", bundle: type, id });
+    if (current?.url) attributes.path = { alias: current.url, pathauto: 0 };
+  }
   return backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
 }
 

package/src/tools/paragraphs.js

@@ -84,6 +84,34 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
+/**
+ * Update an existing paragraph's field values. Mirrors createParagraph but
+ * targets an existing paragraph by UUID via a partial JSON:API PATCH, so only
+ * the supplied attributes are changed. The host entity's reference to the
+ * paragraph is unaffected (same UUID), so updating a paragraph in place is the
+ * way to maintain component / key-capability paragraphs without re-embedding.
+ *
+ * @param {object} args - { site?, paragraphType, id, attributes? }.
+ *   `attributes` are the paragraph field values to change, keyed by Drupal
+ *   machine name (e.g. { field_body: { value, format } }).
+ * @returns {Promise<{paragraph: object, ref: {id: string, type: string},
+ *   relationshipData: {type: string, id: string}, note: string}>}
+ *   The updated paragraph plus the (unchanged) embedding ref.
+ * @throws {Error} If id is missing.
+ * @throws {SecurityError} If updating paragraphs of this bundle is not permitted.
+ */
+async function updateParagraph({ site: siteName, paragraphType, id, attributes = {} }) {
+  if (!id) throw new Error("A paragraph 'id' (UUID) is required to update an existing paragraph.");
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "update", "paragraph", paragraphType);
+  const backend = await resolveBackend(site);
+  const paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
+  const bundle = paragraph.bundle || paragraphType;
+  const ref = embedRef(bundle, paragraph.id);
+  return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
+}
+
 /**
  * Fetch a single paragraph by bundle + UUID, redacted per the site policy, and
  * annotate it with the embedding ref.
@@ -122,6 +150,20 @@ export const definitions = [
       },
     },
   },
+  {
+    name: "drupal_update_paragraph",
+    description:
+      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to this paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
+    inputSchema: {
+      type: "object", required: ["paragraphType", "id"],
+      properties: {
+        site:          { type: "string", description: "Named site (omit for default)" },
+        paragraphType: { type: "string", description: "Paragraph type / bundle machine name, e.g. 'text', 'image', 'cta'" },
+        id:            { type: "string", description: "Paragraph UUID" },
+        attributes:    { type: "object", description: "Paragraph field values to change, keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }" },
+      },
+    },
+  },
   {
     name: "drupal_get_paragraph",
     description:
@@ -139,5 +181,6 @@ export const definitions = [
 
 export const handlers = {
   drupal_create_paragraph: createParagraph,
+  drupal_update_paragraph: updateParagraph,
   drupal_get_paragraph:    getParagraph,
 };

package/src/tools/structure.js

@@ -23,6 +23,40 @@ import {
 const MENU_LINK_TYPE = "menu_link_content";
 const BLOCK_TYPE = "block_content";
 
+// The intermittent menu-link create failure: Drupal's LinkAccessConstraint
+// rejects a link whose target it can't (yet) resolve/access, surfacing as a
+// "422 … path '/…' is inaccessible" error. For a valid, published alias this is
+// a transient path-validator/access-cache race (it warms during the first
+// attempt), so a single retry clears it. Prefer an `entity:node/<id>` target
+// over `internal:/<alias>` to avoid the alias-resolution step entirely.
+const INACCESSIBLE_PATH_RE = /\b422\b[\s\S]*inaccessible/i;
+const MENU_LINK_RETRY_DELAY_MS = 250;
+
+/**
+ * Resolve after `ms` milliseconds.
+ * @param {number} ms Delay in milliseconds.
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Run a menu-link write, retrying once on the transient "422 path inaccessible"
+ * race. Any other error propagates immediately (no blind retries).
+ * @param {() => Promise<object>} fn The backend write to attempt.
+ * @returns {Promise<object>} The write result.
+ */
+async function writeMenuLinkWithRetry(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!INACCESSIBLE_PATH_RE.test(String(err?.message))) throw err;
+    await sleep(MENU_LINK_RETRY_DELAY_MS);
+    return fn();
+  }
+}
+
 /**
  * Normalize limit/offset args into the backend's page descriptor.
  *
@@ -73,13 +107,21 @@ async function listMenuLinks({ site: siteName, menu, limit = 20, offset = 0, sor
  *
  * The `link` field is a Drupal link field: it takes a `{ uri }` object where the
  * URI is a Drupal-style target, e.g. `internal:/about`, `entity:node/42`, or an
- * absolute `https://…` URL.
+ * absolute `https://…` URL. Prefer the `entity:node/<id>` form when linking to a
+ * node — it avoids the alias-resolution step that can trip the intermittent
+ * "path inaccessible" race.
+ *
+ * The link is created **enabled by default** so it renders immediately, and the
+ * `enabled` flag is always sent explicitly (the JSON:API write path could
+ * otherwise land the link disabled — the "menu links created disabled" gap).
+ * `parent` (a parent link plugin id such as `menu_link_content:<uuid>`) can be
+ * set at creation so child links nest without a follow-up update.
  *
- * @param {object} args - { site?, title, link, menu, weight? }.
+ * @param {object} args - { site?, title, link, menu, weight?, parent?, enabled? }.
  * @returns {Promise<object>} The created menu-link descriptor from the backend.
  * @throws {SecurityError} If creating menu_link_content is not permitted.
  */
-async function createMenuLink({ site: siteName, title, link, menu, weight }) {
+async function createMenuLink({ site: siteName, title, link, menu, weight, parent, enabled }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", MENU_LINK_TYPE, MENU_LINK_TYPE);
@@ -89,8 +131,46 @@ async function createMenuLink({ site: siteName, title, link, menu, weight }) {
     link: { uri: link },
     menu_name: menu,
     weight: weight === undefined ? 0 : weight,
+    enabled: enabled === undefined ? true : enabled,
   };
-  return backend.createEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, attributes });
+  if (parent !== undefined) attributes.parent = parent;
+  return writeMenuLinkWithRetry(() =>
+    backend.createEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, attributes }));
+}
+
+/**
+ * Update a custom menu link by UUID. Only the supplied fields are sent (partial
+ * update). Crucially, `enabled` is always re-asserted — to the caller's value
+ * when changing it, otherwise to the link's current value read back from the
+ * site — so an unrelated edit (rename, re-weight, re-parent) can never silently
+ * regress a live link to disabled. Set `parent` to re-nest a link.
+ *
+ * @param {object} args - { site?, id, title?, link?, menu?, weight?, parent?, enabled? }.
+ * @returns {Promise<object>} The updated menu-link descriptor from the backend.
+ * @throws {Error} If id is missing.
+ * @throws {SecurityError} If updating menu_link_content is not permitted.
+ */
+async function updateMenuLink({ site: siteName, id, title, link, menu, weight, parent, enabled }) {
+  if (!id) throw new Error("A menu link 'id' (UUID) is required to update an existing menu link.");
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "update", MENU_LINK_TYPE, MENU_LINK_TYPE);
+  const backend = await resolveBackend(site);
+  const attributes = {};
+  if (title !== undefined) attributes.title = title;
+  if (link !== undefined) attributes.link = { uri: link };
+  if (menu !== undefined) attributes.menu_name = menu;
+  if (weight !== undefined) attributes.weight = weight;
+  if (parent !== undefined) attributes.parent = parent;
+  if (enabled !== undefined) {
+    attributes.enabled = enabled;
+  } else {
+    const current = await backend.getEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, id });
+    const currentEnabled = current?.fields?.enabled;
+    attributes.enabled = currentEnabled === undefined ? true : currentEnabled;
+  }
+  return writeMenuLinkWithRetry(() =>
+    backend.updateEntity({ entityType: MENU_LINK_TYPE, bundle: MENU_LINK_TYPE, id, attributes }));
 }
 
 // ---------------------------------------------------------------------------
@@ -165,15 +245,34 @@ export const definitions = [
   },
   {
     name: "drupal_create_menu_link",
-    description: "Create a custom menu link. The link target is a Drupal URI such as 'internal:/about', 'entity:node/42', or an absolute 'https://…' URL. Checked against the site security config.",
+    description: "Create a custom menu link, enabled by default so it renders immediately. The link target is a Drupal URI such as 'internal:/about', 'entity:node/42', or an absolute 'https://…' URL — prefer 'entity:node/<id>' when linking to a node (avoids the alias-resolution 'path inaccessible' race). Set 'parent' (a parent link plugin id like 'menu_link_content:<uuid>') to nest the link, and 'enabled: false' to create it disabled. Checked against the site security config.",
     inputSchema: {
       type: "object", required: ["title", "link", "menu"],
       properties: {
-        site:   { type: "string" },
-        title:  { type: "string", description: "Link label shown in the menu" },
-        link:   { type: "string", description: "Target URI, e.g. 'internal:/about', 'entity:node/42', or 'https://example.com'" },
-        menu:   { type: "string", description: "Menu machine name to place the link in, e.g. 'main' or 'footer'" },
-        weight: { type: "number", default: 0, description: "Ordering weight within the menu (lower sorts first)" },
+        site:    { type: "string" },
+        title:   { type: "string", description: "Link label shown in the menu" },
+        link:    { type: "string", description: "Target URI, e.g. 'entity:node/42', 'internal:/about', or 'https://example.com'" },
+        menu:    { type: "string", description: "Menu machine name to place the link in, e.g. 'main' or 'footer'" },
+        weight:  { type: "number", default: 0, description: "Ordering weight within the menu (lower sorts first)" },
+        parent:  { type: "string", description: "Parent link plugin id to nest under, e.g. 'menu_link_content:<uuid>'. Omit for a top-level link." },
+        enabled: { type: "boolean", default: true, description: "Whether the link is enabled (renders). Defaults to true." },
+      },
+    },
+  },
+  {
+    name: "drupal_update_menu_link",
+    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.",
+    inputSchema: {
+      type: "object", required: ["id"],
+      properties: {
+        site:    { type: "string" },
+        id:      { type: "string", description: "Menu link UUID" },
+        title:   { type: "string", description: "New link label. Omit to leave unchanged." },
+        link:    { type: "string", description: "New target URI (e.g. 'entity:node/42'). Omit to leave unchanged." },
+        menu:    { type: "string", description: "Move the link to this menu. Omit to leave unchanged." },
+        weight:  { type: "number", description: "New ordering weight. Omit to leave unchanged." },
+        parent:  { type: "string", description: "New parent link plugin id (e.g. 'menu_link_content:<uuid>'), or '' for top level. Omit to leave unchanged." },
+        enabled: { type: "boolean", description: "Enable/disable the link. Omit to preserve the current state." },
       },
     },
   },
@@ -213,6 +312,7 @@ export const definitions = [
 export const handlers = {
   drupal_list_menu_links:  listMenuLinks,
   drupal_create_menu_link: createMenuLink,
+  drupal_update_menu_link: updateMenuLink,
   drupal_list_blocks:      listBlocks,
   drupal_create_block:     createBlock,
 };