drupal-mcp-connector 2.16.0 → 2.18.0

package/.agents/commands/drupal-create-translation.md

@@ -1,11 +1,11 @@
 ---
-description: "Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; continue a paragraph with drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers."
+description: "Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers."
 argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [relationships] [revisionId] [dryRun]"
 ---
 
 Call the MCP tool `drupal_create_translation`.
 
-Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; continue a paragraph with drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers.
+Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -16,7 +16,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
-- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values.
+- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values, 'media' for media (name, caption, image alt).
 - `attributes` (object (pass as JSON)): Translated field values keyed by Drupal machine name
 - `relationships` (object (pass as JSON)): JSON:API relationships. Use for image alt (same file UUID, meta.alt).
 - `revisionId` (string): Paragraph revision id the host already pins. Required for Home-shaped non-default pins.

package/.agents/commands/drupal-get-media.md

@@ -1,11 +1,11 @@
 ---
-description: "Fetch a single media entity by UUID and media type."
-argument-hint: "<type> <id> [site]"
+description: "Fetch a single media entity by UUID and media type. Image alt/title are on the file relationship (meta.alt / meta.title). Pass langcode to read an unpublished working translation via Sentinel."
+argument-hint: "<type> <id> [site] [langcode]"
 ---
 
 Call the MCP tool `drupal_get_media`.
 
-Fetch a single media entity by UUID and media type.
+Fetch a single media entity by UUID and media type. Image alt/title are on the file relationship (meta.alt / meta.title). Pass langcode to read an unpublished working translation via Sentinel.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,5 +15,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `langcode` (string): Target language (e.g. 'es') to read the unpublished working translation instead of the default language.
 
 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/.agents/commands/drupal-list-translations.md

@@ -1,11 +1,11 @@
 ---
-description: "List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node."
+description: "List live and working translation langcodes for a Drupal node, paragraph, or media entity. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node."
 argument-hint: "<type> <id> [site] [entityType]"
 ---
 
 Call the MCP tool `drupal_list_translations`.
 
-List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node.
+List live and working translation langcodes for a Drupal node, paragraph, or media entity. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,6 +15,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
-- `entityType` (string): Entity type machine name. Default: 'node'.
+- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' or 'media' when listing those.
 
 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/.agents/commands/drupal-update-media.md

@@ -1,11 +1,11 @@
 ---
-description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched."
-argument-hint: "<type> <id> [site] [name] [status] [fields]"
+description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first."
+argument-hint: "<type> <id> [site] [name] [status] [fields] [langcode]"
 ---
 
 Call the MCP tool `drupal_update_media`.
 
-Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.
+Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -17,6 +17,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `name` (string)
 - `status` (boolean (true/false)): Published flag. Only sent when provided; requires allowPublish when true.
-- `fields` (object (pass as JSON)): Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically.
+- `fields` (object (pass as JSON)): Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically. Image alt is meta.alt on field_media_image with the existing file UUID.
+- `langcode` (string): Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode.
 
 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,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.18.0] - 2026-09-16
+
+### Fixed
+- **Nullable module inputs (#320).** The generic registry accepts composed nullable
+  schemas while retaining runtime type, length, required and unknown-field checks.
+
+### Added
+- **Module compatibility bindings (#317).** Existing config commands and reports
+  can use locally approved module tools through generic discovery and schema
+  validation. Configured bindings never fall back after a refusal. The live
+  verifier probes the configured source tool directly.
+- **Module-owned tools (#317).** An opt-in registry discovers typed Drupal MCP
+  tools and routes them through explicit site, scope and operation policy. Module
+  actions need no dedicated JavaScript handler. Catalog revisions, schema checks,
+  bounded results and refusal without a valid source prevent silent fallbacks.
+
+### Changed
+- Server-tool sessions are bounded and isolated by endpoint, credential and caller.
+  Module writes do not automatically retry after an authentication/session refusal.
+- **Remaining writes use `prepareGuardedPatch`.** `langcode` always resolves
+  Sentinel inventory and draft-preflights, including unmoderated media.
+  `drupal_update_media` + `langcode`, unscoped `drupal_set_moderation_state`,
+  and `drupal_revert_revision` share the same preflight / `writeDraft` path
+  as node updates. `revisions.js` uses the shared `changedAheadOfRevision`.
+- **One Sentinel HTTP client and fail-closed inventory policy.** Draft,
+  translation, and inventory requests share `src/lib/sentinel-draft.js`
+  (paths, If-Match, lang/state headers, missing-endpoint classifiers,
+  validated inventory). Missing 404/405 stays unavailable / no canonical
+  langcode PATCH. Permission, 5xx, and malformed inventory now throw from
+  `resolveNodeTranslationPair` instead of falling through to
+  `rel:working-copy`. JSON:API advertises `capabilities().sentinelDraft`;
+  GraphQL `rawQuery` does not count as Sentinel-capable.
+
+## [2.17.0] - 2026-09-11
+
+### Added
+- **Governed media draft translation (#296).** `drupal_create_translation` and
+  `drupal_list_translations` accept `entityType: "media"`. Continue with
+  `drupal_update_media` + `langcode`; read with `drupal_get_media` + `langcode`.
+  Same Sentinel `/mcp-draft` live/working pair as nodes (d.o #3622412). Image
+  alt/title are kept on the file relationship (`meta.alt` / `meta.title`) so a
+  translator can read the source. Canonical media writes without `langcode` are
+  unchanged. Requires MCP Sentinel with media draft routes.
+
+### Security
+- Bump transitive `hono` 4.13.1 → 4.13.7 (via `@modelcontextprotocol/node`)
+  and override it to `^4.13.5`, clearing three moderate advisories:
+  GHSA-gqvv-2mrq-wpjv (`toSSG()` path traversal), GHSA-g6gw-c38x-mqfc
+  (`parseBody()` unbounded nesting), and GHSA-crvj-82cr-hjcx (query parser
+  after URL fragment). `npm audit` reports 0 vulnerabilities (#299).
+
 ## [2.16.0] - 2026-09-11
 
 ### Added
@@ -1620,6 +1671,7 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.17.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.17.0
 [2.16.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.16.0
 [2.15.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.2
 [2.15.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.1

package/README.md

@@ -31,6 +31,11 @@ The connector speaks **two Drupal backends interchangeably** — Drupal core's *
 
 ## Dual-Protocol Backends
 
+Drupal modules can also supply their own typed MCP actions through an opt-in
+[module-tool registry](docs/module-tools.md). The module owns business rules and
+schemas; the connector discovers and forwards approved tools under Sentinel and
+connector policy. Existing built-in tools remain available during migration.
+
 Each site declares which backend(s) it exposes via the `api` key:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.16.0",
+  "version": "2.18.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",
@@ -68,6 +68,8 @@
   "dependencies": {
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "graphql": "^17.0.0",
     "jose": "^6.2.9",
     "node-fetch": "^3.3.2",
@@ -83,6 +85,7 @@
   },
   "overrides": {
     "@hono/node-server": "^2.0.5",
+    "hono": "^4.13.5",
     "postcss": "^8.5.18"
   }
 }

package/src/index.js

@@ -58,6 +58,7 @@ import {
 
 // Tools — aggregated (single source of truth, side-effect-free) and per-tool prompts
 import { allDefinitions, allHandlers, definitionsByName } from "./tools/index.js";
+import { createModuleToolRegistry, isModuleTool } from "./lib/module-tools.js";
 import { buildToolPrompts, getToolPromptMessages } from "./lib/tool-prompts.js";
 
 // Apply config/secrets.map (or the shipped example table) before any site
@@ -104,6 +105,18 @@ const RESOURCES = [
   },
 ];
 
+const moduleTools = createModuleToolRegistry();
+
+async function discoverableTools() {
+  const sites = listResolvableSiteConfigs();
+  const identity = getRequestIdentity();
+  const governed = await filterDiscoverableTools(allDefinitions, sites);
+  return [
+    ...filterToolsByPrincipal(governed, sites, identity),
+    ...await moduleTools.list({ sites, identity }),
+  ];
+}
+
 /**
  * Resolve a resource URI to its JSON payload. URIs are matched in order; the
  * templated forms (content-types, security-policy) capture the site name and
@@ -114,13 +127,6 @@ const RESOURCES = [
  * @returns {Promise<object>} The resource data (later JSON-serialized).
  * @throws {Error} If the URI matches no known resource.
  */
-async function discoverableTools() {
-  const sites = listResolvableSiteConfigs();
-  const identity = getRequestIdentity();
-  const governed = await filterDiscoverableTools(allDefinitions, sites);
-  return filterToolsByPrincipal(governed, sites, identity);
-}
-
 async function readResource(uri) {
   const identity = getRequestIdentity();
   const sites = listResolvableSiteConfigs();
@@ -295,7 +301,9 @@ const buildConnectorServer = createConnectorServerFactory({
   tools: {
     definitions: allDefinitions,
     list: discoverableTools,
-    call: callTool,
+    call: (name, args, context) => isModuleTool(name)
+      ? moduleTools.call(name, args, context)
+      : callTool(name, args, context),
   },
   resources: {
     definitions: RESOURCES,

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

@@ -23,6 +23,9 @@
  * @property {"full"|"enum"|"none"} sort Server-side sort support: arbitrary
  *   fields ("full"), a fixed enum of keys ("enum"), or none ("none").
  * @property {boolean} revisions Adapter exposes entity revisions.
+ * @property {boolean} [sentinelDraft] Adapter can issue Sentinel's JSON:API
+ *   `/mcp-draft` and `/mcp-translations` routes (`rawQuery({ path, options })`
+ *   plus `resourcePath`). GraphQL `rawQuery({ query })` must be false.
  * @property {((entityType: string, bundle: string) => string[])|null} fieldAvailability
  *   Optional resolver returning the known field names for a bundle, or null
  *   when the adapter cannot cheaply enumerate fields.

package/src/lib/backends/graphql.js

@@ -65,6 +65,7 @@ export class GraphqlBackend extends Backend {
     return {
       read: true, write: false, delete: false,
       count: false, filter: false, sort: "enum", revisions: false,
+      sentinelDraft: false,
       fieldAvailability: (entityType, bundle) => this._fieldNames(entityType, bundle),
     };
   }

package/src/lib/backends/jsonapi.js

@@ -228,6 +228,7 @@ export class JsonApiBackend extends Backend {
     return {
       read: true, write: true, delete: true,
       count: true, filter: true, sort: "full", revisions: true,
+      sentinelDraft: true,
       fieldAvailability: null,
     };
   }

package/src/lib/canonical.js

@@ -65,14 +65,19 @@ export function normalizeRelationship(ref) {
   // JSON:API encodes type as "entityType--bundle"; split into the two parts.
   const [entityType = null, bundle = null] = (ref.type || "").split("--");
   const out = { id: ref.id, entityType, bundle };
-  // ERR identifiers carry the revision id in JSON:API `meta` (#192). Dropping
-  // it made every canonical re-read look like a plain {id, type} even when the
-  // write sent target_revision_id.
+  // ERR identifiers carry the revision id in JSON:API `meta` (#192). Image
+  // fields carry alt/title the same way (#296). Dropping either made a
+  // canonical re-read look like a plain {id, type}.
   if (ref.meta && typeof ref.meta === "object") {
-    const vid = new Map(Object.entries(ref.meta)).get("target_revision_id");
+    const entries = new Map(Object.entries(ref.meta));
+    const meta = {};
+    const vid = entries.get("target_revision_id");
     if (vid !== undefined && vid !== null && vid !== "") {
-      out.meta = { target_revision_id: vid };
+      meta.target_revision_id = vid;
     }
+    if (typeof entries.get("alt") === "string") meta.alt = entries.get("alt");
+    if (typeof entries.get("title") === "string") meta.title = entries.get("title");
+    if (Object.keys(meta).length > 0) out.meta = meta;
   }
   return out;
 }

package/src/lib/dispatch.js

@@ -18,6 +18,7 @@ import { inferOperation } from "./operations.js";
 import { assertSourceGovernance, GovernanceError, GOVERNANCE_DIAGNOSTIC_TOOLS } from "./governance.js";
 import {
   assertPrincipalEntitlement, callerTargetHints, getRequestIdentity,
+  principalHasScope, resolveAuthoritativeTarget,
 } from "./principal.js";
 import { assertExplicitSiteForWrite, withResolvedTarget } from "./site-target.js";
 import { buildDataFlowContext, consumeBudgetIfEnforced, runWithDataFlow } from "./data-flow.js";
@@ -62,6 +63,15 @@ export function resolveCallTarget(toolName, rawArgs, context = {}) {
 
   const identity = context.identity !== undefined ? context.identity : getRequestIdentity();
   if (identity) {
+    if (context.moduleTool) {
+      if (!principalHasScope(identity, context.moduleTool.scope)) {
+        throw new SecurityError("Not entitled to invoke this module tool.");
+      }
+      return resolveAuthoritativeTarget(rawArgs, identity,
+        context.sites ?? listResolvableSiteConfigs(), {
+          grants: context.grants, defaultSite: context.defaultSite,
+        });
+    }
     return assertPrincipalEntitlement({
       toolName,
       args: rawArgs,