drupal-mcp-connector 2.24.2 → 2.25.0

package/.agents/commands/drupal-list-menu-links.md

@@ -1,11 +1,11 @@
 ---
-description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, and weight. Note: this lists editable menu_link_content entities, not code-defined static links."
+description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, weight, and fields.drupal_internal__id (numeric id for /admin/structure/menu/item/{id}/edit). Note: this lists editable menu_link_content entities, not code-defined static links."
 argument-hint: "[site] [menu] [limit] [offset] [sort]"
 ---
 
 Call the MCP tool `drupal_list_menu_links`.
 
-List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, and weight. Note: this lists editable menu_link_content entities, not code-defined static links.
+List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, weight, and fields.drupal_internal__id (numeric id for /admin/structure/menu/item/{id}/edit). Note: this lists editable menu_link_content entities, not code-defined static links.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/.agents/commands/drupal-update-menu-link.md

@@ -1,11 +1,11 @@
 ---
-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."
+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. Pass langcode to update an existing translation via JSON:API language negotiation (URL prefix, then language headers). Does not create a missing translation. Responses include fields.drupal_internal__id. Checked against the site security config."
 argument-hint: "<id> [site] [title] [link] [menu] [weight] [parent] [enabled] [langcode]"
 ---
 
 Call the MCP tool `drupal_update_menu_link`.
 
-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.
+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. Pass langcode to update an existing translation via JSON:API language negotiation (URL prefix, then language headers). Does not create a missing translation. Responses include fields.drupal_internal__id. Checked against the site security config.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -20,6 +20,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `weight` (number): New ordering weight. Omit to leave unchanged.
 - `parent` (string): New parent link plugin id (e.g. 'menu_link_content:<uuid>'), or '' for top level. Omit to leave unchanged.
 - `enabled` (boolean (true/false)): Enable/disable the link. Omit to preserve the current state.
-- `langcode` (string): Existing translation to update (e.g. 'es'). Omit for the default language. Does not create a missing translation.
+- `langcode` (string): Existing translation to update (e.g. 'es'). Uses /{langcode}/jsonapi/… when the site prefixes JSON:API, then language headers. Omit for the default language. Does not create a missing translation.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.25.0] - 2026-10-01
+
+### Added
+- **Menu tools return `fields.drupal_internal__id`.** The numeric menu-link
+  id is kept on JSON:API canonicalization so list/create/update responses
+  can build `/admin/structure/menu/item/{id}/edit` (and `…/edit/{langcode}`).
+
+### Fixed
+- **`drupal_update_menu_link` with `langcode` targets the translation via a JSON:API URL prefix (#398).**
+  Stock Drupal negotiates content language from `/{langcode}/jsonapi/…` (the
+  same path that returns Spanish for nodes). The connector only sent
+  `Accept-Language` / `Content-Language` headers, which most production sites
+  ignore unless Browser detection is enabled — so a Spanish menu-link
+  translation was served as English and the write refused. Reads and writes
+  with `langcode` now try the prefixed path first and fall back to the
+  unprefixed path plus headers when the prefix 404s. Taxonomy get/update
+  with `langcode` use the same backend path. A mismatch after both attempts
+  still fails loud.
+
 ## [2.24.2] - 2026-09-30
 
 ### Removed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.24.2",
+  "version": "2.25.0",
   "description": "Drupal MCP Connector — multi-site MCP server for Drupal with JSON:API and GraphQL, governed writes, draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/backends/jsonapi.js

@@ -11,6 +11,7 @@ import { drupalFetch, drupalUploadFile } from "../drupal-fetch.js";
 import { getRequestIdentity } from "../principal.js";
 import { validateUuid, validateMachineName } from "../validate.js";
 import { parseFieldConfigObject } from "../field-definition.js";
+import { httpStatusOf } from "../error-status.js";
 import { Backend } from "./backend-interface.js";
 import {
   makeCanonicalEntity,
@@ -33,8 +34,9 @@ const COUNT_PAGE_SIZE = 50;
 const COUNT_MAX_RECORDS = 1000;
 
 /**
- * JSON:API language headers. Drupal negotiates Content-Language / Accept-Language
- * when URL prefixes are not used on /jsonapi.
+ * JSON:API language headers. Stock Drupal ignores these unless Browser
+ * (Accept-Language) detection is enabled for content language. Production
+ * sites usually negotiate via URL prefixes instead — see jsonApiLanguagePath.
  * @param {?string} langcode
  * @returns {object}
  */
@@ -43,6 +45,59 @@ function languageFetchOptions(langcode) {
   return { headers: { "Content-Language": langcode, "Accept-Language": langcode } };
 }
 
+/**
+ * Prefix a JSON:API path with the language code stock Drupal URL negotiation
+ * expects (`/es/jsonapi/...`). Does not add `?langCode=` — core JSON:API
+ * rejects unknown query parameters unless jsonapi_multilingual is installed.
+ * @param {string} path JSON:API path, optionally with a query string.
+ * @param {?string} langcode
+ * @returns {string}
+ */
+export function jsonApiLanguagePath(path, langcode) {
+  if (!langcode) return path;
+  const prefix = `/${encodeURIComponent(langcode)}`;
+  if (path === prefix || path.startsWith(`${prefix}/`)) return path;
+  return `${prefix}${path}`;
+}
+
+/**
+ * Merge language headers onto a drupalFetch options object.
+ * @param {object} [options]
+ * @param {?string} langcode
+ * @returns {object}
+ */
+function languageRequestOptions(options, langcode) {
+  const lang = languageFetchOptions(langcode);
+  if (!lang.headers) return { ...options };
+  return {
+    ...options,
+    headers: { ...(options?.headers || {}), ...lang.headers },
+  };
+}
+
+/**
+ * Fetch a JSON:API resource in a requested language.
+ *
+ * Prefer the URL prefix (how `/es/jsonapi/node/...` works on multilingual
+ * Drupal). If that 404s — the site has no language prefixes — retry the
+ * unprefixed path with language headers only (#398 / #303).
+ * @param {object} site Resolved site config.
+ * @param {string} path Unprefixed JSON:API path.
+ * @param {object} [options] node-fetch options (method, body, extra headers).
+ * @param {?string} langcode
+ * @returns {Promise<object|null>}
+ */
+async function fetchJsonApiWithLanguage(site, path, options = {}, langcode) {
+  const opts = languageRequestOptions(options, langcode);
+  if (!langcode) return drupalFetch(site, path, opts);
+  try {
+    return await drupalFetch(site, jsonApiLanguagePath(path, langcode), opts);
+  } catch (err) {
+    if (httpStatusOf(err) !== 404) throw err;
+    return drupalFetch(site, path, opts);
+  }
+}
+
 /**
  * Fail if JSON:API served a different language than requested.
  * @param {?object} entity
@@ -59,7 +114,8 @@ function assertServedLanguage(entity, langcode) {
   if (entity.langcode !== langcode) {
     throw new Error(
       `JSON:API served language "${entity.langcode}" for requested langcode "${langcode}". ` +
-      "The translation may not exist, or this site does not negotiate JSON:API by language.",
+      "The translation may not exist, or this site does not negotiate JSON:API by language " +
+      `(URL prefix /${langcode}/jsonapi/… or Accept-Language).`,
     );
   }
 }
@@ -291,10 +347,12 @@ export class JsonApiBackend extends Backend {
           // while the UUID remains the canonical top-level id (#237).
           // Paragraph ERR attach needs the current revision id (#192).
           // Node / revisionable writes need the working vs live vid (#166).
+          // Menu-link admin edit URLs need the numeric id (#398).
           // Other drupal_internal__* attributes stay stripped.
           return (entityType === "node" && k === "drupal_internal__nid")
             || k === "drupal_internal__vid"
-            || (entityType === "paragraph" && k === "drupal_internal__revision_id");
+            || (entityType === "paragraph" && k === "drupal_internal__revision_id")
+            || (entityType === "menu_link_content" && k === "drupal_internal__id");
         }
         return true;
       })
@@ -397,7 +455,7 @@ export class JsonApiBackend extends Backend {
     if (resourceVersion) {
       path += `?resourceVersion=${encodeURIComponent(resourceVersion)}`;
     }
-    const data = await drupalFetch(this.site, path, languageFetchOptions(langcode));
+    const data = await fetchJsonApiWithLanguage(this.site, path, {}, langcode);
     const entity = data?.data ? this.toCanonical(data.data) : null;
     assertServedLanguage(entity, langcode);
     return entity;
@@ -514,14 +572,19 @@ export class JsonApiBackend extends Backend {
    * @returns {Promise<object>} The JSON:API response body.
    */
   async writeWithModerationFallback(path, method, buildPayload, attributes, langcode) {
-    const lang = languageFetchOptions(langcode);
+    const send = (attrs) => fetchJsonApiWithLanguage(
+      this.site,
+      path,
+      { method, body: JSON.stringify(buildPayload(attrs)) },
+      langcode,
+    );
     try {
-      return await drupalFetch(this.site, path, { method, body: JSON.stringify(buildPayload(attributes)), ...lang });
+      return await send(attributes);
     } catch (err) {
       if (!isModeratedStatusError(err) || !("status" in attributes)) throw err;
       const withoutStatus = { ...attributes };
       delete withoutStatus.status;
-      return drupalFetch(this.site, path, { method, body: JSON.stringify(buildPayload(withoutStatus)), ...lang });
+      return send(withoutStatus);
     }
   }
 

package/src/tools/structure.js

@@ -156,7 +156,7 @@ async function createMenuLink({ site: siteName, title, link, menu, weight, paren
  * 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? }.
+ * @param {object} args - { site?, id, title?, link?, menu?, weight?, parent?, enabled?, langcode? }.
  * @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.
@@ -243,7 +243,7 @@ async function createBlock({ site: siteName, type, info, body }) {
 export const definitions = [
   {
     name: "drupal_list_menu_links",
-    description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, and weight. Note: this lists editable menu_link_content entities, not code-defined static links.",
+    description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, weight, and fields.drupal_internal__id (numeric id for /admin/structure/menu/item/{id}/edit). Note: this lists editable menu_link_content entities, not code-defined static links.",
     inputSchema: {
       type: "object",
       properties: {
@@ -273,7 +273,7 @@ export const definitions = [
   },
   {
     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.",
+    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. Pass langcode to update an existing translation via JSON:API language negotiation (URL prefix, then language headers). Does not create a missing translation. Responses include fields.drupal_internal__id. Checked against the site security config.",
     inputSchema: {
       type: "object", required: ["id"],
       properties: {
@@ -285,7 +285,7 @@ export const definitions = [
         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." },
-        langcode: { type: "string", description: "Existing translation to update (e.g. 'es'). Omit for the default language. Does not create a missing translation." },
+        langcode: { type: "string", description: "Existing translation to update (e.g. 'es'). Uses /{langcode}/jsonapi/… when the site prefixes JSON:API, then language headers. Omit for the default language. Does not create a missing translation." },
       },
     },
   },