drupal-mcp-connector 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -7,6 +7,42 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "1.5.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;
 }
 
 /**
@@ -149,13 +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);
-  // 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 });
+  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/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),
+  });
 }
 
 /**