drupal-mcp-connector 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,51 @@ 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
+- **Redirect tools** (`drupal_create_redirect`, `drupal_update_redirect`) for the
+  contrib Redirect module. `drupal_create_redirect` produces a redirect that serves
+  its 301 (or chosen code) immediately: the source path's leading slash is stripped
+  to the module's stored, slash-less form (the classic "redirect saved but never
+  fires" cause), the destination is normalized to a Drupal link-field URI (a bare
+  path is wrapped as `internal:`, while `entity:node/ID` and absolute URLs pass
+  through), and `status_code` defaults to 301 with 302 (and 303/307/308) accepted.
+  `drupal_update_redirect` repoints an existing redirect's source/target or changes
+  its status code via a partial update — the path to activate/fix a redirect that
+  isn't firing. Both are governed by the per-site security policy (redirect writes /
+  `administer redirects`). Resolves the gap where connector-created redirects were
+  inactive and could not be enabled (DEV-111).
+
 ## [1.3.2] - 2026-06-27
 
 ### Fixed

package/README.md

@@ -71,8 +71,9 @@ 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 |
 | **Config & Governance** | Governed config get/list/set via the server-tool bridge; `drupal_mcp_whoami` tier/capability report |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "1.3.2",
+  "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/index.js

@@ -65,6 +65,7 @@ import * as bulk         from "./tools/bulk.js";
 import * as translations from "./tools/translations.js";
 import * as paragraphs   from "./tools/paragraphs.js";
 import * as structure    from "./tools/structure.js";
+import * as redirects    from "./tools/redirects.js";
 import * as search       from "./tools/search.js";
 import * as reportsExtra from "./tools/reports-extra.js";
 import * as config       from "./tools/config.js";
@@ -74,7 +75,7 @@ import * as config       from "./tools/config.js";
 // ---------------------------------------------------------------------------
 
 const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
-  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, search, reportsExtra, config];
+  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra, config];
 
 // Flatten every module's tool definitions into one ListTools payload, and merge
 // their handler maps into a single closed dispatch table keyed by tool name.

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

@@ -0,0 +1,182 @@
+/**
+ * Tool group: URL redirects (the contrib Redirect module).
+ *
+ * A `redirect` entity maps an old/source path to a destination and fires an HTTP
+ * redirect (301 by default) when the source path is requested. Redirects are a
+ * single-bundle content entity (`redirect--redirect`) exposed over JSON:API, so
+ * they go through the shared backend like the other structural content tools.
+ *
+ * Why a dedicated tool (vs. the generic entity tools): the Redirect module's
+ * field shape is unforgiving and easy to get wrong, which produces a stored-but-
+ * dead redirect:
+ *   - `redirect_source` stores the source path WITHOUT a leading slash. A source
+ *     saved as "/old" never matches an incoming request for "old", so the
+ *     redirect silently never fires. This tool strips the leading slash so a
+ *     created redirect is live (serves its 301) immediately.
+ *   - `redirect_redirect` is a Drupal link field — a bare "/new" must be wrapped
+ *     as the URI "internal:/new". This tool normalizes destinations so callers
+ *     can pass a plain path, an `entity:node/ID`, or an absolute URL.
+ *   - `status_code` defaults to 301 and can be set to 302 (or another redirect
+ *     code) explicitly on create, and changed on an existing redirect via update.
+ *
+ * Redirect entities have no separate enabled/disabled flag — a redirect with a
+ * valid source is active. "Enable an existing redirect" therefore means: correct
+ * its fields so it matches and fires, which is exactly what drupal_update_redirect
+ * does. Both tools are governed: writes assert create/update permission for the
+ * `redirect` entity type against the per-site security policy.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import { resolveSecurityConfig, assertWriteAllowed } from "../lib/security.js";
+
+const REDIRECT_TYPE = "redirect";
+
+// Redirect status codes the Redirect module supports. 301/302 are the common
+// pair called for in the ticket; the rest are the other valid HTTP redirect
+// codes, accepted so the tool isn't needlessly restrictive. 301 is the default.
+const ALLOWED_STATUS_CODES = [301, 302, 303, 307, 308];
+
+// Drupal URI schemes a destination may already carry; anything else that is a
+// path gets wrapped as internal:.
+const URI_SCHEME_RE = /^(https?:|mailto:|tel:|internal:|entity:|route:|base:)/i;
+
+/**
+ * Normalize a source path to the Redirect module's stored form: trimmed, no
+ * leading slash. Storing a leading slash is the classic "redirect saved but
+ * never fires" bug, so this is the core of the fix.
+ *
+ * @param {string} source Raw source path, e.g. "/old-path" or "old-path".
+ * @returns {string} The source path without a leading slash.
+ */
+function normalizeSource(source) {
+  return String(source).trim().replace(/^\/+/, "");
+}
+
+/**
+ * Normalize a redirect destination into a Drupal link-field URI. Absolute URLs
+ * and explicit Drupal URI schemes (entity:, internal:, route:, …) pass through
+ * unchanged; a bare path is wrapped as `internal:`.
+ *
+ * @param {string} target Destination path or URI.
+ * @returns {string} A Drupal link-field URI.
+ */
+function normalizeTargetUri(target) {
+  const t = String(target).trim();
+  if (URI_SCHEME_RE.test(t)) return t;
+  return t.startsWith("/") ? `internal:${t}` : `internal:/${t}`;
+}
+
+/**
+ * Validate a requested status code against the supported redirect codes.
+ *
+ * @param {number} code The HTTP status code.
+ * @returns {number} The validated code.
+ * @throws {Error} If the code is not a supported redirect status code.
+ */
+function assertStatusCode(code) {
+  if (!ALLOWED_STATUS_CODES.includes(code)) {
+    throw new Error(
+      `Unsupported redirect status code ${code}. Use one of: ${ALLOWED_STATUS_CODES.join(", ")} (301 is the default).`,
+    );
+  }
+  return code;
+}
+
+/**
+ * Create an active URL redirect.
+ *
+ * @param {object} args - { site?, source, target, statusCode?, language? }.
+ *   `source` is the old path (a leading slash is fine; it is stripped to the
+ *   stored form). `target` is the destination — a path ("/new"), an
+ *   `entity:node/ID`, or an absolute URL. `statusCode` defaults to 301; pass 302
+ *   for a temporary redirect. `language` defaults to 'und' (all languages).
+ * @returns {Promise<object>} The created redirect descriptor from the backend.
+ * @throws {Error} If source/target are missing or the status code is unsupported.
+ * @throws {SecurityError} If creating redirects is not permitted.
+ */
+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 });
+}
+
+/**
+ * Update an existing redirect: repoint its source/target or change its status
+ * code. Only the provided fields are sent (a partial JSON:API PATCH), so an
+ * update that changes just the status code leaves source/target untouched.
+ *
+ * @param {object} args - { site?, id, source?, target?, statusCode? }.
+ * @returns {Promise<object>} The updated redirect descriptor from the backend.
+ * @throws {Error} If id is missing or the status code is unsupported.
+ * @throws {SecurityError} If updating redirects is not permitted.
+ */
+async function updateRedirect({ site: siteName, id, source, target, statusCode }) {
+  if (!id) throw new Error("A redirect 'id' (UUID) is required to update an existing redirect.");
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "update", REDIRECT_TYPE, REDIRECT_TYPE);
+  const backend = await resolveBackend(site);
+  const attributes = {};
+  if (source !== undefined) attributes.redirect_source = { path: normalizeSource(source), query: null };
+  if (target !== undefined) attributes.redirect_redirect = { uri: normalizeTargetUri(target) };
+  if (statusCode !== undefined) attributes.status_code = assertStatusCode(statusCode);
+  return backend.updateEntity({ entityType: REDIRECT_TYPE, bundle: REDIRECT_TYPE, id, attributes });
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_create_redirect",
+    description:
+      "Create an active URL redirect (contrib Redirect module). The redirect serves its 301 (or chosen code) immediately: 'source' is the old path (a leading slash is fine — it is normalized to the module's stored, slash-less form so the redirect actually matches and fires), and 'target' is the destination as a path ('/new'), an 'entity:node/ID', or an absolute URL. status_code defaults to 301; pass 302 for a temporary redirect. Governed by the site security policy (needs redirect write / 'administer redirects').",
+    inputSchema: {
+      type: "object", required: ["source", "target"],
+      properties: {
+        site:       { type: "string", description: "Named site (omit for default)" },
+        source:     { type: "string", description: "Source/old path to redirect from, e.g. '/old-slug'. Leading slash optional." },
+        target:     { type: "string", description: "Destination: a path ('/new-slug'), 'entity:node/42', or an absolute 'https://…' URL." },
+        statusCode: { type: "number", default: 301, description: "HTTP redirect status code. 301 (permanent, default) or 302 (temporary); 303/307/308 also accepted." },
+        language:   { type: "string", default: "und", description: "Langcode the redirect applies to. Defaults to 'und' (all languages)." },
+      },
+    },
+  },
+  {
+    name: "drupal_update_redirect",
+    description:
+      "Update an existing redirect by UUID: repoint its source or target, or change its status code (e.g. 301↔302). Only the fields you pass are changed (partial update). Use this to activate/fix a redirect that isn't firing (e.g. one created with a stale source). Governed by the site security policy.",
+    inputSchema: {
+      type: "object", required: ["id"],
+      properties: {
+        site:       { type: "string" },
+        id:         { type: "string", description: "Redirect entity UUID" },
+        source:     { type: "string", description: "New source/old path (leading slash optional). Omit to leave unchanged." },
+        target:     { type: "string", description: "New destination path/URI. Omit to leave unchanged." },
+        statusCode: { type: "number", description: "New HTTP redirect status code (301/302/303/307/308). Omit to leave unchanged." },
+      },
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Handler map
+// ---------------------------------------------------------------------------
+
+export const handlers = {
+  drupal_create_redirect: createRedirect,
+  drupal_update_redirect: updateRedirect,
+};

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