drupal-mcp-connector 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-06-29
+
+### Fixed
+- **Node URL aliases set via the connector now actually persist (DEV-116).** Setting an
+  alias with `drupal_update_node` (`fields.path = { alias, pathauto: 0 }`) returned
+  success but silently reverted, causing nav 404s. Root cause: JSON:API deserialized the
+  `path` field without the existing alias's **`pid`**, so Drupal's `PathItem::postSave`
+  *created a duplicate* `path_alias` (the older one stayed canonical) instead of updating
+  in place. The connector now reads the current alias's `pid` (new
+  `backend.getPathInfo`) and round-trips it, so the alias is **updated in place** — one
+  canonical alias, no duplicate. Verified end-to-end over JSON:API on Drupal 11.
+- **Path-less updates no longer create duplicate aliases.** The DEV-114 "preserve" path
+  re-pinned the current alias *without* its `pid`, hitting the same duplicate bug; it now
+  round-trips the `pid` too.
+- **Honest write responses.** `drupal_create_node` / `drupal_update_node` now **re-read**
+  the node after writing and return the *persisted* `url`, instead of echoing the
+  requested value (which masked the revert).
+
+### Added
+- **Automatic rename redirect.** When an explicit alias change replaces a different
+  existing alias, the connector creates a 301 redirect from the old path to the node
+  (`entity:node/<id>`, alias-independent), so the previous URL keeps resolving. Idempotent
+  — skipped when a redirect for that source already exists or the alias is unchanged.
+- **`backend.getPathInfo(ref)`** on the backend interface — exposes the raw `path` field
+  (`alias` / `pid` / `langcode`) and internal id; default returns nulls (read-only/
+  path-less backends are unaffected). `buildRedirectAttributes()` is now exported from the
+  redirects module for reuse.
+
+### Notes
+- Connector-created nodes still rely on Pathauto to generate their alias when no explicit
+  `path` is given. A **separate, server-side** Pathauto pattern misconfiguration (some
+  `pathauto.pattern.*` had `bundles` stored as a sequential array instead of the
+  associative map the `entity_bundle` condition requires) prevented alias generation for
+  affected bundles (e.g. `industry`, `platform`); that fix lives in the Drupal site
+  (webcms), not in the connector.
+
+## [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.1",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

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

@@ -71,6 +71,16 @@ export class Backend {
    */
   async getEntity(_ref) { return notImplemented("getEntity"); }
 
+  /**
+   * Read the raw `path` field (alias/pid/langcode) and internal id of an entity,
+   * 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 DEV-116.
+   * @param {{entityType: string, bundle: string, id: string}} _ref
+   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
+   */
+  async getPathInfo(_ref) { return { alias: null, pid: null, langcode: null, drupalId: null }; }
+
   /**
    * Create an entity.
    * @param {{entityType: string, bundle: string, attributes?: object, relationships?: object}} _input

package/src/lib/backends/jsonapi.js

@@ -253,6 +253,29 @@ export class JsonApiBackend extends Backend {
     return data?.data ? this.toCanonical(data.data) : null;
   }
 
+  /**
+   * Read the raw `path` field (alias + pid + langcode) and internal id of an
+   * entity. The canonical entity only surfaces `path.alias` as `url`, but a
+   * correct in-place alias *update* must round-trip the existing alias's `pid`
+   * (Drupal `PathItem::postSave` creates a duplicate alias when `pid` is absent)
+   * — so this method exposes it. Returns nulls for entities/backends without a
+   * path field. See DEV-116.
+   * @param {{entityType: string, bundle: string, id: string}} ref
+   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
+   */
+  async getPathInfo({ entityType, bundle, id }) {
+    validateUuid(id);
+    const data = await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`);
+    const attrs = data?.data?.attributes ?? {};
+    const path = attrs.path ?? null;
+    return {
+      alias: path?.alias ?? null,
+      pid: path?.pid ?? null,
+      langcode: path?.langcode ?? attrs.langcode ?? null,
+      drupalId: attrs.drupal_internal__nid ?? attrs.drupal_internal__id ?? null,
+    };
+  }
+
   /**
    * Issue a JSON:API write, transparently retrying once without the `status`
    * attribute if the target bundle is under a content_moderation workflow.

package/src/tools/nodes.js

@@ -9,7 +9,118 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
-import { resolveSecurityConfig, redactCanonicalEntity } from "../lib/security.js";
+import { resolveSecurityConfig, redactCanonicalEntity, assertWriteAllowed } from "../lib/security.js";
+import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
+
+/** Fallback language for an alias when the node exposes none. */
+const DEFAULT_ALIAS_LANGCODE = "en";
+
+/**
+ * Normalize a URL-alias path for storage/comparison: trim, ensure a single
+ * leading slash, drop a trailing slash (except root).
+ * @param {*} value A raw alias.
+ * @returns {?string} The normalized alias, or null when empty.
+ */
+function normalizeAlias(value) {
+  if (value === undefined || value === null) return null;
+  let s = String(value).trim();
+  if (!s) return null;
+  if (!s.startsWith("/")) s = `/${s}`;
+  if (s.length > 1) s = s.replace(/\/+$/, "");
+  return s;
+}
+
+/**
+ * Resolve the `path` attribute to send on an alias-aware node write so the alias
+ * actually persists, and decide whether a rename redirect is needed.
+ *
+ * The bug (DEV-116): JSON:API deserializes `{ alias, pathauto }` onto the node's
+ * `path` field, dropping the existing alias's `pid`; Drupal's `PathItem::postSave`
+ * then *creates a duplicate* `path_alias` (the older one stays canonical) instead
+ * of updating in place. The fix is to round-trip the existing `pid` so the update
+ * is in place. DEV-114's path-omitted "preserve" had the same defect (no `pid`),
+ * so it is fixed here too.
+ *
+ * @param {object} args - { backend, type, id, providedPath, isCreate }.
+ * @returns {Promise<{pathAttr: (object|undefined), redirect: ?object}>}
+ *   `pathAttr` is the `path` value to send (or undefined to omit, letting pathauto
+ *   run on create); `redirect` is `{ from, to, nid }` when a rename redirect is due.
+ */
+async function resolvePathWrite({ backend, type, id, providedPath, isCreate }) {
+  const info = id
+    ? await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}))
+    : {};
+  const oldAlias = normalizeAlias(info.alias);
+  const langcode = info.langcode || DEFAULT_ALIAS_LANGCODE;
+
+  if (providedPath && typeof providedPath === "object") {
+    // Explicit alias set/replace → manual alias, round-trip the existing pid so
+    // Drupal updates in place rather than creating a duplicate.
+    if (providedPath.alias) {
+      const newAlias = normalizeAlias(providedPath.alias);
+      const pathAttr = { alias: newAlias, pathauto: false, langcode };
+      if (info.pid !== undefined && info.pid !== null) pathAttr.pid = info.pid;
+      const redirect = !isCreate && oldAlias && oldAlias !== newAlias
+        ? { from: oldAlias, to: newAlias, nid: info.drupalId }
+        : null;
+      return { pathAttr, redirect };
+    }
+    // Caller passed `path` without an alias (e.g. re-enabling pathauto) — respect it as-is.
+    return { pathAttr: providedPath, redirect: null };
+  }
+
+  // No explicit path on update → preserve the current alias *with its pid* so the
+  // save can neither revert nor duplicate it.
+  if (!isCreate && oldAlias) {
+    const pathAttr = { alias: oldAlias, pathauto: false, langcode };
+    if (info.pid !== undefined && info.pid !== null) pathAttr.pid = info.pid;
+    return { pathAttr, redirect: null };
+  }
+
+  // Create without an explicit path → omit it so pathauto generates the alias.
+  return { pathAttr: undefined, redirect: null };
+}
+
+/**
+ * Best-effort create a 301 redirect from a node's old alias to the node after a
+ * rename, so the previous URL keeps resolving. Governed like any redirect write;
+ * never fails the node update (failures are reported, not thrown). Idempotent:
+ * skips when a redirect already exists for the source.
+ *
+ * @param {object} backend Resolved backend.
+ * @param {object} sec Resolved security config.
+ * @param {{from: string, to: string, nid: ?(number|string)}} redirect
+ * @returns {Promise<object>} Outcome `{ created, ... }` for the response.
+ */
+async function createRenameRedirect(backend, sec, redirect) {
+  try {
+    assertWriteAllowed(sec, "create", REDIRECT_ENTITY_TYPE, REDIRECT_ENTITY_TYPE);
+  } catch {
+    return { created: false, reason: "redirect creation not permitted by policy", source: redirect.from };
+  }
+  // Prefer an alias-independent target so a future rename can't break the redirect.
+  const target = redirect.nid !== undefined && redirect.nid !== null
+    ? `entity:node/${redirect.nid}`
+    : redirect.to;
+  const sourceStored = redirect.from.replace(/^\/+/, "");
+  try {
+    const existing = await backend.listEntities({
+      entityType: REDIRECT_ENTITY_TYPE, bundle: REDIRECT_ENTITY_TYPE,
+      filters: [{ field: "redirect_source.path", op: "eq", value: sourceStored }],
+      page: { limit: 1 },
+    }).catch(() => null);
+    if (existing?.entities?.length) {
+      return { created: false, reason: "redirect already exists", source: redirect.from };
+    }
+    await backend.createEntity({
+      entityType: REDIRECT_ENTITY_TYPE, bundle: REDIRECT_ENTITY_TYPE,
+      attributes: buildRedirectAttributes(redirect.from, target, 301),
+    });
+    return { created: true, source: redirect.from, target };
+  } catch (err) {
+    return { created: false, reason: err?.message || String(err), source: redirect.from };
+  }
+}
 
 /**
  * Build a Drupal body field descriptor from plain HTML + optional summary.
@@ -119,7 +230,16 @@ async function createNode({ site: siteName, type, title, body, summary, status,
   if (bodyAttr) attributes.body = bodyAttr;
   if (dryRun) return { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes };
   const backend = await resolveBackend(site);
-  return backend.createEntity({ entityType: "node", bundle: type, attributes });
+  // Alias handling: an explicit `path.alias` is set as a manual alias; otherwise
+  // `path` is omitted so pathauto generates the alias (DEV-116).
+  const { pathAttr } = await resolvePathWrite({ backend, type, id: null, providedPath: attributes.path, isCreate: true });
+  if (pathAttr === undefined) delete attributes.path;
+  else attributes.path = pathAttr;
+  const created = await backend.createEntity({ entityType: "node", bundle: type, attributes });
+  // Honest response: re-read so the persisted alias (explicit or pathauto-generated)
+  // is reflected rather than the pre-alias write response.
+  const fresh = await backend.getEntity({ entityType: "node", bundle: type, id: created.id }).catch(() => null);
+  return fresh ?? created;
 }
 
 /**
@@ -130,6 +250,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,7 +269,21 @@ 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);
-  return backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
+  const sec = resolveSecurityConfig(site);
+  // Alias handling (DEV-116): an explicit `path.alias` is set in place by
+  // round-tripping the existing alias's pid (no duplicate); a path-less update
+  // re-pins the current alias *with its pid* so the save can't revert/duplicate
+  // it. A rename (alias changed) also gets a 301 redirect from the old path.
+  const { pathAttr, redirect } = await resolvePathWrite({ backend, type, id, providedPath: attributes.path, isCreate: false });
+  if (pathAttr === undefined) delete attributes.path;
+  else attributes.path = pathAttr;
+  await backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
+  const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
+  // Honest response: re-read persisted state so the returned `url` is the alias
+  // that actually resolves, never the just-sent value.
+  const fresh = await backend.getEntity({ entityType: "node", bundle: type, id }).catch(() => null);
+  if (fresh && redirectResult) return { ...fresh, _redirect: redirectResult };
+  return fresh ?? { id };
 }
 
 /**

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

@@ -83,6 +83,32 @@ function assertStatusCode(code) {
   return code;
 }
 
+/** Entity type id for redirects, exported so side-effect callers can reuse it. */
+export const REDIRECT_ENTITY_TYPE = REDIRECT_TYPE;
+
+/**
+ * Build the JSON:API attribute map for a `redirect` entity from a plain
+ * source/target, applying the leading-slash and link-URI normalization that
+ * keeps a created redirect live. Exported so other tools (e.g. the node
+ * rename-redirect side-effect in nodes.js) create redirects identically.
+ *
+ * @param {string} source Old path (leading slash optional; stripped).
+ * @param {string} target Destination path / `entity:node/ID` / absolute URL.
+ * @param {number} [statusCode] HTTP redirect code (default 301).
+ * @param {string} [language] Redirect language (default 'und').
+ * @returns {object} The redirect attribute map for backend.createEntity.
+ * @throws {Error} If the status code is unsupported.
+ */
+export function buildRedirectAttributes(source, target, statusCode = 301, language = "und") {
+  assertStatusCode(statusCode);
+  return {
+    redirect_source: { path: normalizeSource(source), query: null },
+    redirect_redirect: { uri: normalizeTargetUri(target) },
+    status_code: statusCode,
+    language,
+  };
+}
+
 /**
  * Create an active URL redirect.
  *
@@ -98,18 +124,14 @@ function assertStatusCode(code) {
 async function createRedirect({ site: siteName, source, target, statusCode = 301, language = "und" }) {
   if (!source) throw new Error("A redirect 'source' path is required (e.g. '/old-path').");
   if (!target) throw new Error("A redirect 'target' is required (a path, 'entity:node/ID', or an absolute URL).");
-  assertStatusCode(statusCode);
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", REDIRECT_TYPE, REDIRECT_TYPE);
   const backend = await resolveBackend(site);
-  const attributes = {
-    redirect_source: { path: normalizeSource(source), query: null },
-    redirect_redirect: { uri: normalizeTargetUri(target) },
-    status_code: statusCode,
-    language,
-  };
-  return backend.createEntity({ entityType: REDIRECT_TYPE, bundle: REDIRECT_TYPE, attributes });
+  return backend.createEntity({
+    entityType: REDIRECT_TYPE, bundle: REDIRECT_TYPE,
+    attributes: buildRedirectAttributes(source, target, statusCode, language),
+  });
 }
 
 /**

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,
 };