drupal-mcp-connector 2.21.0 → 2.22.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.22.0] - 2026-09-20
+
+### Added
+- **Remote Drupal workflow prompts (#371).** The module-workflow loader fetches
+  `prompts/list` and `prompts/get` from `serverTools.url` (contrib `mcp_server`
+  `McpPromptConfig` entities) and merges them into the v1 path. A remote
+  workflow is listed only when local `serverTools.modules.workflows` names it
+  and every `{tool:alias}` is already in `serverTools.modules.tools`. Local
+  bodies remain the fallback when the catalog omits an enabled id. Write
+  workflows still require `mcp_write` and append that module writes are not
+  retried. See `docs/module-workflows.md`.
+
 ## [2.21.0] - 2026-09-19
 
 ### Added

package/package.json

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

@@ -64,7 +64,7 @@ import {
   loadWorkflows,
   toPromptDescriptor,
   renderWorkflowMessages,
-  moduleWorkflowProviders,
+  moduleWorkflowProvidersWithRemote,
   registerBuiltinWorkflows,
   replaceModuleWorkflows,
 } from "./lib/workflow-prompts.js";
@@ -231,8 +231,11 @@ const buildConnectorServer = createConnectorServerFactory({
     workflowNames: WORKFLOW_PROMPT_NAMES,
     workflowMessages: getPromptMessages,
     definitionsByName,
-    extraWorkflows: (tools, taken) => {
-      const loaded = loadWorkflows(moduleWorkflowProviders(listResolvableSiteConfigs()), { tools, taken });
+    extraWorkflows: async (tools, taken) => {
+      const loaded = loadWorkflows(
+        await moduleWorkflowProvidersWithRemote(listResolvableSiteConfigs()),
+        { tools, taken },
+      );
       replaceModuleWorkflows(loaded);
       return loaded;
     },

package/src/lib/server-tools.js

@@ -13,7 +13,8 @@
  * call site performs the MCP session handshake — `initialize` (read the
  * `Mcp-Session-Id` response header) → `notifications/initialized` → `tools/call`
  * carrying that session id. The session is cached per site and transparently
- * re-initialised when the server expires it.
+ * re-initialised when the server expires it. `prompts/list` and `prompts/get`
+ * reuse the same session.
  *
  * Config (per site):
  *   "serverTools": { "url": "/mcp" }   // path is resolved against site.baseUrl
@@ -333,7 +334,7 @@ async function initializeSession(site, endpoint, key) {
     method: "initialize",
     params: {
       protocolVersion: MCP_PROTOCOL_VERSION,
-      capabilities: {},
+      capabilities: { prompts: {} },
       clientInfo: { name: CLIENT_NAME, version: CLIENT_VERSION },
     },
   };
@@ -442,6 +443,74 @@ export async function listServerTools(site, cursor) {
   });
 }
 
+/** Fetch one page of Drupal `McpPromptConfig` prompts. */
+export async function listServerPrompts(site, cursor) {
+  return requestServerTool(site, "prompts/list", cursor === undefined ? {} : { cursor }, {
+    maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
+  });
+}
+
+/**
+ * Fetch one Drupal prompt body. Pass no arguments so `{{token}}` placeholders
+ * stay intact for the connector's workflow renderer.
+ */
+export async function getServerPrompt(site, name) {
+  return requestServerTool(site, "prompts/get", { name, arguments: {} }, {
+    maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
+  });
+}
+
+/**
+ * Page `prompts/list` the same way as `tools/list`.
+ * @param {object} site Resolved site config.
+ * @param {Function} [list] Catalog page reader.
+ * @returns {Promise<object[]>} Prompt descriptors.
+ */
+export async function advertisedServerPrompts(site, list = listServerPrompts) {
+  const prompts = [];
+  const seen = new Set();
+  let cursor;
+  for (let page = 0; page < MAX_CATALOG_PAGES; page++) {
+    const result = await list(site, cursor);
+    if (!Array.isArray(result?.prompts)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" is malformed: prompts/list returned no prompts array.`);
+    }
+    for (const prompt of result.prompts) {
+      if (prompt && typeof prompt.name === "string") prompts.push(prompt);
+    }
+    if (result.nextCursor === undefined || result.nextCursor === null) return prompts;
+    if (typeof result.nextCursor !== "string" || seen.has(result.nextCursor)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" returned an invalid or repeated prompts cursor.`);
+    }
+    cursor = result.nextCursor;
+    seen.add(cursor);
+  }
+  throw new Error(`Server-tool catalog for site "${site._name}" exceeds ${MAX_CATALOG_PAGES} prompt pages.`);
+}
+
+/**
+ * Load listed prompt descriptors plus `prompts/get` bodies for the named ids.
+ * A get failure omits that id; the caller fail-closes rather than widening.
+ * @param {object} site Resolved site config.
+ * @param {string[]} names Workflow ids to fetch.
+ * @param {{list?: Function, get?: Function}} [deps]
+ * @returns {Promise<{list: object[], bodies: Map<string, object>}>}
+ */
+export async function fetchSiteWorkflowPrompts(site, names, { list = listServerPrompts, get = getServerPrompt } = {}) {
+  const listed = await advertisedServerPrompts(site, list);
+  const want = new Set(names ?? []);
+  const bodies = new Map();
+  for (const prompt of listed) {
+    if (!want.has(prompt.name)) continue;
+    try {
+      bodies.set(prompt.name, await get(site, prompt.name));
+    } catch {
+      // Fail closed for this id: no body, so the merge will not list it.
+    }
+  }
+  return { list: listed, bodies };
+}
+
 /** Shared bounded MCP request transport; size + abort are always attached. */
 async function requestServerTool(site, method, params, options) {
   const toolName = params.name ?? method;

package/src/lib/tool-prompts.js

@@ -239,7 +239,7 @@ export function getToolPromptMessages(promptName, args = {}, definitionsByName)
  * @param {Set<string>} options.workflowNames - Names of the hand-authored workflow prompts.
  * @param {(name: string, args: object) => Array<object>} options.workflowMessages
  * @param {Map<string,object>} options.definitionsByName - Built-in tool name → definition.
- * @param {(tools: Array<object>, taken: Set<string>) => object[]} [options.extraWorkflows]
+ * @param {(tools: Array<object>, taken: Set<string>) => object[]|Promise<object[]>} [options.extraWorkflows]
  *   Module-owned workflows visible for this request. Each item has name,
  *   description, arguments, and is renderable by extraWorkflowMessages.
  * @param {(workflow: object, args: object) => Array<object>} [options.extraWorkflowMessages]
@@ -256,7 +256,7 @@ export function createPromptSurface({
   async function visible() {
     const tools = await discover();
     const taken = new Set(staticPrompts.map((prompt) => prompt.name));
-    const extra = extraWorkflows ? extraWorkflows(tools, taken) : [];
+    const extra = extraWorkflows ? await extraWorkflows(tools, taken) : [];
     for (const workflow of extra) taken.add(workflow.name);
     // A reserved module name cannot match a built-in, but never let a remote
     // catalog shadow a static prompt if that invariant is ever broken.

package/src/lib/workflow-prompts.js

@@ -265,6 +265,148 @@ export function renderWorkflowMessages(workflow, args = {}) {
   return [{ role: "user", content: { type: "text", text } }];
 }
 
+/**
+ * Unique `{tool:alias}` names in instruction text, first-seen order.
+ *
+ * @param {string} instructions
+ * @returns {string[]}
+ */
+export function toolAliasesInInstructions(instructions) {
+  const aliases = [];
+  const seen = new Set();
+  for (const match of String(instructions ?? "").matchAll(/\{tool:([a-z][a-z0-9_]{0,47})\}/g)) {
+    if (seen.has(match[1])) continue;
+    seen.add(match[1]);
+    aliases.push(match[1]);
+  }
+  return aliases;
+}
+
+/**
+ * Join user-role text from a Drupal `prompts/get` result.
+ *
+ * @param {object} got
+ * @returns {string}
+ */
+export function instructionTextFromDrupalPrompt(got) {
+  const messages = Array.isArray(got?.messages) ? got.messages : [];
+  const parts = [];
+  for (const message of messages) {
+    if (message?.role !== "user") continue;
+    const content = message.content;
+    if (typeof content?.text === "string") {
+      parts.push(content.text);
+      continue;
+    }
+    if (Array.isArray(content)) {
+      for (const item of content) {
+        if (item?.type === "text" && typeof item.text === "string") parts.push(item.text);
+      }
+    }
+  }
+  return parts.join("\n").replace(/\{\{\s*([a-z][a-z0-9_]{0,47})\s*\}\}/g, "{arg:$1}");
+}
+
+/**
+ * `readOnly` is false when any named alias is a local write or delete.
+ *
+ * @param {string[]} aliases
+ * @param {object} toolsMap `serverTools.modules.tools`
+ * @returns {boolean}
+ */
+export function inferReadOnly(aliases, toolsMap) {
+  for (const alias of aliases) {
+    const operation = toolsMap?.[alias]?.operation;
+    if (operation === "write" || operation === "delete") return false;
+  }
+  return true;
+}
+
+/**
+ * Map a Drupal prompt list item + get body onto the v1 workflow definition.
+ * Returns null when the prompt cannot be a workflow (no `{tool:alias}`, an
+ * alias missing from the local tools map, or an unusable description).
+ *
+ * @param {string} id
+ * @param {object} listed
+ * @param {object} got
+ * @param {object} toolsMap
+ * @returns {object|null}
+ */
+export function workflowFromDrupalPrompt(id, listed, got, toolsMap) {
+  const instructions = instructionTextFromDrupalPrompt(got);
+  if (!instructions.trim()) return null;
+  const tools = toolAliasesInInstructions(instructions);
+  if (tools.length < 1) return null;
+  for (const alias of tools) {
+    if (!toolsMap?.[alias] || typeof toolsMap[alias] !== "object") return null;
+  }
+  const rawArgs = Array.isArray(listed?.arguments) ? listed.arguments : [];
+  const arguments_ = rawArgs.map((arg) => ({
+    name: arg?.name ?? arg?.machine_name,
+    description: arg?.description ?? "",
+    required: Boolean(arg?.required),
+  }));
+  const description = String(listed?.description ?? got?.description ?? "").trim() || "Module workflow.";
+  return {
+    id,
+    description,
+    readOnly: inferReadOnly(tools, toolsMap),
+    tools,
+    arguments: arguments_,
+    instructions,
+  };
+}
+
+/**
+ * Provider from site `serverTools.modules.workflows` maps, optionally merged
+ * with Drupal `prompts/list` + `prompts/get`. Local keys enable; remote bodies
+ * replace a local body when the catalog returns that id. A remote prompt that
+ * is not named locally is ignored. Fetch failures keep the v1 local bodies.
+ *
+ * @param {Array<object>} sites
+ * @param {{fetch?: Function}} [deps]
+ * @returns {Promise<object[]>}
+ */
+export async function moduleWorkflowProvidersWithRemote(sites, { fetch } = {}) {
+  const { fetchSiteWorkflowPrompts } = await import("./server-tools.js");
+  const load = fetch ?? fetchSiteWorkflowPrompts;
+  const providers = [];
+  for (const site of sites ?? []) {
+    const modules = site.serverTools?.modules;
+    if (!modules?.namespace || !modules.workflows || typeof modules.workflows !== "object") continue;
+    const enabled = [];
+    for (const [id, body] of Object.entries(modules.workflows)) {
+      if (id.startsWith("_") || !body || typeof body !== "object") continue;
+      enabled.push({ id: body.id ?? id, body });
+    }
+    let catalog;
+    try {
+      catalog = await load(site, enabled.map((item) => item.id));
+    } catch {
+      catalog = { list: [], bodies: new Map() };
+    }
+    const listedByName = new Map((catalog.list ?? []).map((prompt) => [prompt.name, prompt]));
+    const workflows = [];
+    for (const item of enabled) {
+      const listed = listedByName.get(item.id);
+      const got = catalog.bodies?.get(item.id);
+      if (listed && got) {
+        const mapped = workflowFromDrupalPrompt(item.id, listed, got, modules.tools ?? {});
+        if (mapped) workflows.push(mapped);
+        continue;
+      }
+      workflows.push({ ...item.body, id: item.id });
+    }
+    providers.push({
+      id: `config:${modules.namespace}`,
+      namespace: modules.namespace,
+      workflows,
+    });
+  }
+  return providers;
+}
+
 /**
  * Provider from site `serverTools.modules.workflows` maps.
  *