drupal-mcp-connector 2.20.0 → 2.22.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ 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
+- **Module-owned workflow prompts (#333).** Workflows are definitions the
+  connector loads, filters and relays. v1 sources them from built-in
+  definitions (the five connector-authored workflows, now the same format)
+  and from `serverTools.modules.workflows` next to approved module tools.
+  A workflow names tools by local alias (`{tool:alias}`), is listed only
+  when every named tool is visible, and cannot invent a tool the site did
+  not already approve. Write workflows require `mcp_write`, tell the model
+  to confirm, and append that module writes are not retried. Design:
+  `docs/module-workflows.md`. The example config ships `review_and_log` on
+  `example_site`. Drupal `prompts/list` is specified there and not
+  implemented in this change.
+
+### Fixed
+- **Remaining northbound HTTP timeouts.** Server-tool `tools/call` (including
+  governed config), the OAuth token POST, and the Sentinel readiness GET now
+  abort with `AbortSignal.timeout` so a hung Drupal/Sentinel host cannot stall
+  the MCP process. `requestServerTool` always attaches the 256 KiB body cap and
+  a 15s abort; those were previously gated on `maxBytes`, so `callGovernedServerTool`
+  could hang unbounded. Token acquisition fails as `OAuthError` after 30s.
+  A hung readiness probe stays `sentinel_unreachable`.
+
 ## [2.20.0] - 2026-09-19
 
 ### Added

package/README.md

@@ -118,6 +118,8 @@ and other MCP-aware agents). Two kinds ship with the connector:
 - `drupal-create-article` — guided article creation with all fields
 - `drupal-seo-fix` — find and fix SEO gaps
 - `drupal-user-cleanup` — identify and handle inactive accounts
+- Module-owned workflows (`drupal-<namespace>-<workflow>`) when
+  `serverTools.modules.workflows` is enabled — see `docs/module-workflows.md`
 
 **One prompt per tool** — every `drupal_*` tool is also exposed as a
 `drupal-<tool>` prompt (e.g. `drupal-create-node`, `drupal-list-nodes`,

package/config/config.example.json

@@ -155,7 +155,7 @@
 
   "_server_tools": {
     "_comment": "serverTools.url is the JSON-RPC endpoint of the Drupal-side governed MCP tools (mcp_server_tool_bridge / mcp_sentinel), resolved against baseUrl. Required for drupal_config_get/list/set. The config-inspection audits will also use it (governed path) when present, but fall back to the drush bridge, so it is optional for the audits. Authenticated with the same OAuth bearer.",
-    "_modules_comment": "Optional. serverTools.modules exposes Drupal module-owned tools through the generic registry. It is opt-in: a tool installed on the source, or listed in its catalog, is not exposed until it is named here. namespace is lowercase letters, digits and underscores, up to 24 characters. An alias follows the same rule, up to 48 characters. The namespace and alias together must be unique across configured sites. Each entry under tools is an alias with four required keys. name is the exact wire name from the source's tools/list; copy it, because bridge versions join the parts differently and the connector does not rewrite it. scope is the inbound scope a caller needs. operation is read, write or delete; it sets the public tool name (drupal_module_<operation>_<namespace>__<alias>) and the connector gate, whatever the source's own annotation says. capabilities lists extra connector gates (publish, configRead, configWrite, graphql, rawSql) and may be empty. These keys only narrow access; Drupal stays authoritative. To get slash-command stubs for the approved module tools, run `npm run install:commands -- --modules` from the directory that holds config/config.json. See docs/module-tools.md.",
+    "_modules_comment": "Optional. serverTools.modules exposes Drupal module-owned tools through the generic registry. It is opt-in: a tool installed on the source, or listed in its catalog, is not exposed until it is named here. namespace is lowercase letters, digits and underscores, up to 24 characters. An alias follows the same rule, up to 48 characters. The namespace and alias together must be unique across configured sites. Each entry under tools is an alias with four required keys. name is the exact wire name from the source's tools/list; copy it, because bridge versions join the parts differently and the connector does not rewrite it. scope is the inbound scope a caller needs. operation is read, write or delete; it sets the public tool name (drupal_module_<operation>_<namespace>__<alias>) and the connector gate, whatever the source's own annotation says. capabilities lists extra connector gates (publish, configRead, configWrite, graphql, rawSql) and may be empty. These keys only narrow access; Drupal stays authoritative. To get slash-command stubs for the approved module tools, run `npm run install:commands -- --modules` from the directory that holds config/config.json. Optional serverTools.modules.workflows enables module-owned workflow prompts (drupal-<namespace>-<workflow>); a workflow may only name aliases already under tools. See docs/module-tools.md and docs/module-workflows.md.",
     "_bindings_comment": "Optional. serverTools.bindings keeps a built-in command's public name while its implementation lives in a Drupal module. Each binding names an alias under serverTools.modules.tools on the same site. configGet, configList, configSet serve drupal_config_get/list/set and the config reports; codegenInspect, codegenDiff, codegenPreview serve drupal_codegen_inspect/diff/generate; sqlQuery serves drupal_drush_sql_query. Required alias policy: config and codegen aliases use scope mcp_config; get, list and the three codegen aliases are operation read with capability configRead; configSet is operation write with capability configWrite; sqlQuery is scope mcp_admin, operation read, capability rawSql, and still needs drushSsh.rawSql: \"governed\" on the site. Once a bindings object exists, every one of these commands resolves only through its binding: a missing or mismatched mapping refuses the command, with no fallback to another tool or to SSH. Configure the full set for the commands the site uses. Without a bindings object these commands keep their built-in transport. See docs/module-tools.md.",
     "example": {
       "serverTools": {
@@ -182,6 +182,17 @@
             "codegen_diff":     { "name": "tool_api__graphql_compose_codegen_diff",       "scope": "mcp_config", "operation": "read",  "capabilities": ["configRead"] },
             "codegen_preview":  { "name": "tool_api__graphql_compose_codegen_preview",    "scope": "mcp_config", "operation": "read",  "capabilities": ["configRead"] },
             "sql_query":        { "name": "tool_api__mcp_sentinel_sql_query",             "scope": "mcp_admin",  "operation": "read",  "capabilities": ["rawSql"] }
+          },
+          "workflows": {
+            "review_and_log": {
+              "description": "Review recent activities and, after confirmation, log a follow-up. Write is opt-in and is not retried.",
+              "readOnly": false,
+              "tools": ["list_activities", "record_activity"],
+              "arguments": [
+                { "name": "site", "description": "Target site", "required": false }
+              ],
+              "instructions": "1. Call {tool:list_activities} for recent rows.\n2. Summarize what needs a follow-up.\n3. Ask the person before calling {tool:record_activity}. Do not retry a write."
+            }
           }
         },
         "bindings": {

package/package.json

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

@@ -45,6 +45,20 @@ export function commandFileName(def) {
 /** Trailing marker that tells the installer a stub belongs to a module-owned tool. */
 export const MODULE_STUB_MARKER = "<!-- drupal-mcp-connector:module-tool -->";
 
+/** Trailing marker for a module-owned workflow stub. */
+export const WORKFLOW_STUB_MARKER = "<!-- drupal-mcp-connector:module-workflow -->";
+
+/**
+ * Command filename for a module-owned workflow prompt.
+ *
+ * @param {string} namespace
+ * @param {string} id
+ * @returns {string}
+ */
+export function workflowCommandFileName(namespace, id) {
+  return `drupal-${namespace}-${id}.md`.replace(/_/g, "-");
+}
+
 const MODULE_TOOL_NAME = /^drupal_module_(?:read|write|delete)_([a-z][a-z0-9_]*?)__([a-z][a-z0-9_]*)$/;
 
 /**
@@ -144,6 +158,35 @@ export function renderCommandMarkdown(def, options = {}) {
  * @param {object} def - The tool definition.
  * @returns {string} File contents.
  */
+/**
+ * Filesystem stub for a module-owned workflow prompt.
+ *
+ * @param {object} workflow - A loaded workflow from the #333 loader.
+ * @returns {string}
+ */
+export function renderWorkflowCommandMarkdown(workflow) {
+  const params = (workflow.arguments ?? []).map((arg) => ({
+    name: arg.name,
+    required: Boolean(arg.required),
+  }));
+  const hint = argumentHint(params);
+  const tools = (workflow.publicTools ?? []).map((name) => `\`${name}\``).join(", ");
+  const body = [
+    `# ${workflow.name}`,
+    "",
+    workflow.description,
+    "",
+    `This is a workflow prompt. Ask the MCP client for prompt \`${workflow.name}\`.`,
+    tools ? `It names these tools: ${tools}.` : "",
+    workflow.readOnly
+      ? "Read-only: do not write."
+      : "Confirm with the person before any write. Module writes are not retried.",
+    "",
+    WORKFLOW_STUB_MARKER,
+  ].filter((line, i, arr) => line !== "" || arr[i - 1] !== "");
+  return `---\ndescription: ${yamlString(workflow.description)}\nargument-hint: "${hint}"\n---\n\n${body.join("\n")}\n`;
+}
+
 export function renderClaudeCommandMarkdown(def) {
   return renderCommandMarkdown(def, {
     allowedTools: `mcp__drupal__${def.name}`,

package/scripts/install-commands.js

@@ -32,10 +32,13 @@ import {
   commandFileName,
   moduleCommandFileName,
   MODULE_STUB_MARKER,
+  WORKFLOW_STUB_MARKER,
   renderCommandMarkdown,
   renderClaudeCommandMarkdown,
   renderCodexSkillMarkdown,
   renderCodexToolsReference,
+  renderWorkflowCommandMarkdown,
+  workflowCommandFileName,
   CODEX_SKILL_NAME,
 } from "./generate-commands.js";
 
@@ -154,15 +157,43 @@ export function missingModuleTools(configured, discovered) {
   return configured.filter((name) => !found.has(name));
 }
 
-/** Whether an installed stub was written for a module-owned tool. */
+/** Whether an installed stub was written for a module-owned tool or workflow. */
 function isModuleStub(path) {
   try {
-    return readFileSync(path, "utf8").includes(MODULE_STUB_MARKER);
+    const text = readFileSync(path, "utf8");
+    return text.includes(MODULE_STUB_MARKER) || text.includes(WORKFLOW_STUB_MARKER);
   } catch {
     return false;
   }
 }
 
+/**
+ * Workflow stubs for enabled local definitions whose named tools were discovered.
+ *
+ * @param {object[]} workflows
+ * @param {Set<string>} builtInFiles
+ * @param {Set<string>} moduleFiles
+ * @returns {{stubs: Array<{file: string, workflow: object}>, refused: Array<object>}}
+ */
+export function planWorkflowStubs(workflows, builtInFiles, moduleFiles) {
+  const stubs = [];
+  const refused = [];
+  const byFile = new Map();
+  for (const workflow of workflows ?? []) {
+    const file = workflowCommandFileName(workflow.namespace, workflow.id);
+    if (builtInFiles.has(file) || moduleFiles.has(file)) {
+      refused.push({ name: workflow.name, file, reason: "matches a built-in or module-tool command" });
+      continue;
+    }
+    byFile.set(file, [...(byFile.get(file) ?? []), workflow]);
+  }
+  for (const [file, defs] of byFile) {
+    if (defs.length === 1) stubs.push({ file, workflow: defs[0] });
+    else defs.forEach((workflow) => refused.push({ name: workflow.name, file, reason: "shared by more than one workflow" }));
+  }
+  return { stubs, refused };
+}
+
 /**
  * Write one `drupal-*.md` per tool into each requested client directory,
  * pruning stale stubs first. Unknown client names fail closed.
@@ -229,6 +260,11 @@ export function install(options = {}) {
       writeFileSync(join(dir, file), client.render(def));
       moduleWritten.push(file);
     }
+    const workflowStubs = options.workflowStubs ?? [];
+    for (const { file, workflow } of workflowStubs) {
+      writeFileSync(join(dir, file), renderWorkflowCommandMarkdown(workflow));
+      moduleWritten.push(file);
+    }
     results.push({ client: name, dir, written, moduleWritten });
   }
   return results;
@@ -266,9 +302,11 @@ deprecated Codex custom prompts (~/.codex/prompts).
   --home DIR       Install root (default: the current user's home)
   --clients LIST   Comma-separated subset of: claude, grok, codex, agents
                    (default: claude,grok,codex)
-  --modules        Also write stubs for module-owned tools. Discovers them from
-                   the sources in config/config.json (run from that directory).
-                   Without this flag, installed module stubs are left alone.
+  --modules        Also write stubs for module-owned tools and workflows.
+                   Discovers tools from the sources in config/config.json
+                   (run from that directory). Workflows come from
+                   serverTools.modules.workflows. Without this flag, installed
+                   module stubs are left alone.
 `;
 
 const invokedDirectly =
@@ -302,6 +340,19 @@ if (invokedDirectly) {
       opts.moduleParts = parts;
       // An incomplete listing must not delete stubs for tools that may only be unreachable.
       opts.pruneModules = missing.length === 0;
+      const { loadWorkflows, moduleWorkflowProviders } = await import("../src/lib/workflow-prompts.js");
+      const { listResolvableSiteConfigs } = await import("../src/lib/dispatch.js");
+      const workflows = loadWorkflows(moduleWorkflowProviders(listResolvableSiteConfigs()), {
+        tools: definitions,
+        taken: new Set(allDefinitions.map((def) => def.name.replace(/_/g, "-"))),
+      });
+      const builtInFiles = new Set(allDefinitions.map(commandFileName));
+      const moduleFiles = new Set(planModuleStubs(definitions, allDefinitions, parts).stubs.map((s) => s.file));
+      const planned = planWorkflowStubs(workflows, builtInFiles, moduleFiles);
+      for (const r of planned.refused) {
+        console.error(`[install-commands] WARNING: no workflow stub for ${r.name}: ${r.reason}${r.file ? ` (${r.file})` : ""}`);
+      }
+      opts.workflowStubs = planned.stubs;
     }
     const results = install(opts);
     for (const r of results) {

package/src/index.js

@@ -60,6 +60,15 @@ import {
 import { allDefinitions, allHandlers, definitionsByName } from "./tools/index.js";
 import { createModuleToolRegistry, isModuleTool } from "./lib/module-tools.js";
 import { buildToolPrompts, createPromptSurface } from "./lib/tool-prompts.js";
+import {
+  loadWorkflows,
+  toPromptDescriptor,
+  renderWorkflowMessages,
+  moduleWorkflowProvidersWithRemote,
+  registerBuiltinWorkflows,
+  replaceModuleWorkflows,
+} from "./lib/workflow-prompts.js";
+import { builtinWorkflowProvider } from "./lib/workflows/builtin.js";
 
 // Apply config/secrets.map (or the shipped example table) before any site
 // resolution. MCP clients spawn this file directly; the shell launcher is
@@ -167,129 +176,31 @@ async function readResource(uri) {
 // MCP Prompts — common Drupal workflow templates
 // ---------------------------------------------------------------------------
 
-const PROMPTS = [
-  {
-    name:        "drupal-content-audit",
-    description: "Walk through a full content audit: inventory, staleness, SEO gaps, accessibility issues, and recommendations.",
-    arguments:   [{ name: "site", description: "Named site to audit (omit for default)", required: false }],
-  },
-  {
-    name:        "drupal-create-article",
-    description: "Guided workflow to research, draft, and publish an article node with all fields, tags, and metadata.",
-    arguments:   [
-      { name: "site",  description: "Target site",        required: false },
-      { name: "topic", description: "Article topic/brief", required: true  },
-    ],
-  },
-  {
-    name:        "drupal-seo-fix",
-    description: "Find SEO gaps in content (missing meta descriptions, thin content, title issues) and fix them interactively.",
-    arguments:   [
-      { name: "site", description: "Target site",         required: false },
-      { name: "type", description: "Content type to scan", required: false },
-    ],
-  },
-  {
-    name:        "drupal-user-cleanup",
-    description: "Identify inactive, never-logged-in, or overly permissioned user accounts and take action.",
-    arguments:   [{ name: "site", description: "Target site", required: false }],
-  },
-  {
-    name:        "drupal-full-audit",
-    description: "Run a full site-health audit — content, link/404 integrity, and configuration posture — and turn the scored dashboard into a prioritized action plan.",
-    arguments:   [
-      { name: "site", description: "Named site to audit (omit for default)", required: false },
-      { name: "type", description: "Primary content type to audit",          required: false },
-    ],
-  },
-];
+const builtinWorkflows = loadWorkflows([builtinWorkflowProvider], { tools: allDefinitions });
+registerBuiltinWorkflows(builtinWorkflows);
+const PROMPTS = builtinWorkflows.map(toPromptDescriptor);
 
 // Per-tool prompts: one slash-command prompt for every Drupal tool, derived from
 // the tool definitions so the set always matches the tools. Merged after the
-// hand-authored workflow prompts above (names never collide — workflow prompts use
-// composite verbs, tool prompts mirror the `drupal_*` tool names).
+// workflow prompts (names never collide — workflow prompts use composite verbs,
+// tool prompts mirror the `drupal_*` tool names).
 const WORKFLOW_PROMPT_NAMES = new Set(PROMPTS.map((p) => p.name));
 const TOOL_PROMPTS = buildToolPrompts(allDefinitions);
 const ALL_PROMPTS  = [...PROMPTS, ...TOOL_PROMPTS];
 
 /**
- * Build the message list for a named prompt, interpolating site/type/topic
- * args into a pre-authored multi-step workflow. Unknown prompt names fall back
- * to a generic one-line instruction so the call never fails.
+ * Build the message list for a named built-in workflow. Unknown names fall
+ * back to a generic one-line instruction so the call never fails.
  *
  * @param {string} name - The prompt name.
  * @param {object} args - Prompt arguments (site, type, topic — all optional).
  * @returns {Array<object>} MCP prompt messages.
  */
 function getPromptMessages(name, args) {
-  const site  = args?.site  ? `on the "${args.site}" site` : "on the default site";
-  const type  = args?.type  || "article";
-  const topic = args?.topic || "the requested topic";
-
-  const prompts = {
-    "drupal-content-audit": [
-      { role: "user", content: { type: "text", text:
-        `Please run a comprehensive content audit ${site}. Do not assume any particular content type exists — every site has a different model, so discover it first and audit the types this site actually has.\n` +
-        "1. Call drupal_report_content_summary for the full inventory. Its byContentType list is the set of content types to audit — derive the types from it; never assume a fixed type such as \"article\".\n" +
-        "2. For each content type that has nodes, call drupal_report_stale_content (days: 180).\n" +
-        "3. For each content type that has nodes, call drupal_report_field_completeness.\n" +
-        "4. For each content type with published nodes, check SEO: prefer drupal_report_seo_meta_coverage (it reads the site's actual meta field rather than assuming one) and use drupal_report_seo_audit for title-length and thin-content checks.\n" +
-        "5. For each content type with published nodes, call drupal_report_accessibility_audit.\n" +
-        "6. For any content type reporting zero nodes, skip its per-type scans and record it as empty — an empty type is not a clean one.\n" +
-        "7. Synthesize findings into: (a) immediate actions, (b) medium-term improvements, (c) process recommendations.\n" +
-        "Present results as a structured report with counts, severity, and specific node links where possible. State which content types were scanned so an empty or unexpected model cannot be mistaken for a clean audit."
-      }},
-    ],
-    "drupal-create-article": [
-      { role: "user", content: { type: "text", text:
-        `I need to create a new article ${site} about: ${topic}\n\n` +
-        "Please:\n" +
-        "1. Call drupal_list_content_types to confirm \"article\" exists and check its fields.\n" +
-        "2. Call drupal_get_entity_schema for node/article to see all available fields.\n" +
-        "3. Call drupal_list_vocabularies and drupal_get_taxonomy_terms for relevant vocabularies.\n" +
-        "4. Draft the article — title, body (well-structured HTML), summary, and meta description.\n" +
-        "5. Suggest appropriate taxonomy tags.\n" +
-        "6. Call drupal_create_node with status: false (draft) and show me the result.\n" +
-        "7. Ask me to review before publishing."
-      }},
-    ],
-    "drupal-seo-fix": [
-      { role: "user", content: { type: "text", text:
-        `Please find and fix SEO issues in "${type}" content ${site}.\n\n` +
-        "1. Call drupal_report_seo_audit to identify all issues.\n" +
-        "2. For nodes missing meta descriptions: generate appropriate descriptions (max 160 chars) and update them.\n" +
-        "3. For thin content (under 300 words): flag for editorial review — do not auto-expand.\n" +
-        "4. For title length issues: suggest better titles but ask before updating.\n" +
-        "5. Report what was fixed, what needs human review, and any patterns you noticed."
-      }},
-    ],
-    "drupal-user-cleanup": [
-      { role: "user", content: { type: "text", text:
-        `Please audit user accounts ${site} and recommend cleanup actions.\n\n` +
-        "1. Call drupal_report_user_activity to identify inactive and never-logged-in accounts.\n" +
-        "2. Call drupal_list_users with no filter to get the full list.\n" +
-        "3. Call drupal_list_roles to see all available roles.\n" +
-        "4. Identify: (a) accounts inactive 90+ days, (b) never-logged-in accounts, (c) accounts with admin roles that look like test/temp accounts.\n" +
-        "5. For each category, recommend action (block, delete, or keep) with reasoning.\n" +
-        "6. Ask for approval before making any changes."
-      }},
-    ],
-    "drupal-full-audit": [
-      { role: "user", content: { type: "text", text:
-        `Please run a full site-health audit ${site} and turn it into a prioritized action plan.\n\n` +
-        `1. Call drupal_audit_site_health (type: "${type}") for the scored dashboard and overall grade.\n` +
-        "2. For any section reporting high-severity findings, drill in with the matching tool for detail:\n" +
-        "   - links/404: drupal_report_404_log, drupal_report_redirect_health, drupal_report_broken_links (checkLive only with approval).\n" +
-        "   - config: drupal_audit_config_best_practices, drupal_report_module_audit, drupal_report_permission_audit.\n" +
-        "   - content: drupal_report_pii_exposure, drupal_report_duplicate_content, drupal_report_readability.\n" +
-        "3. For sections reported 'unavailable', note what (server-tool bridge or drush) would enable them — do not treat unavailable as 'passing'.\n" +
-        "4. Synthesize a prioritized plan: (a) high-severity/security fixes first, (b) content-quality improvements, (c) process recommendations.\n" +
-        "5. Present counts, severity, and specific node/config references; propose redirects for the top 404s. Ask before making any changes."
-      }},
-    ],
-  };
-
-  return new Map(Object.entries(prompts)).get(name) ?? [{ role: "user", content: { type: "text", text: `Run the ${name} workflow ${site}.` } }];
+  const workflow = builtinWorkflows.find((item) => item.name === name);
+  if (workflow) return renderWorkflowMessages(workflow, args);
+  const site = args?.site ? `on the "${args.site}" site` : "on the default site";
+  return [{ role: "user", content: { type: "text", text: `Run the ${name} workflow ${site}.` } }];
 }
 
 // ---------------------------------------------------------------------------
@@ -320,6 +231,15 @@ const buildConnectorServer = createConnectorServerFactory({
     workflowNames: WORKFLOW_PROMPT_NAMES,
     workflowMessages: getPromptMessages,
     definitionsByName,
+    extraWorkflows: async (tools, taken) => {
+      const loaded = loadWorkflows(
+        await moduleWorkflowProvidersWithRemote(listResolvableSiteConfigs()),
+        { tools, taken },
+      );
+      replaceModuleWorkflows(loaded);
+      return loaded;
+    },
+    extraWorkflowMessages: renderWorkflowMessages,
   }),
 });
 

package/src/lib/governance.js

@@ -23,6 +23,9 @@ import { DIAGNOSTIC_TOOLS } from "./principal.js";
 /** How long a passing verification stays fresh before it must be re-proven. */
 export const OK_TTL_MS = 60_000;
 
+/** Readiness GET abort timeout. Matches Drupal/Drush outbound HTTP. */
+export const READINESS_TIMEOUT_MS = 30_000;
+
 /** How long a failed verification is held before the next attempt re-checks. */
 export const FAIL_TTL_MS = 5_000;
 
@@ -81,7 +84,7 @@ export async function verifySourceGovernance(site, { force = false } = {}) {
 }
 
 /**
- * One authenticated readiness probe; maps every outcome to {ok, reason}.
+ * One authenticated readiness probe; maps every outcome (including abort) to {ok, reason}.
  * @param {object} site Resolved site config.
  * @returns {Promise<{ok: boolean, reason: string|null, checkedAt: number}>}
  */
@@ -104,7 +107,11 @@ async function probeReadiness(site) {
 
   let res;
   try {
-    res = await fetch(`${site.baseUrl}/drupal-mcp/readiness`, { method: "GET", headers });
+    res = await fetch(`${site.baseUrl}/drupal-mcp/readiness`, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(READINESS_TIMEOUT_MS),
+    });
   } catch {
     // Network detail (addresses, DNS text) is deliberately not propagated.
     return { ok: false, reason: "sentinel_unreachable", checkedAt };

package/src/lib/oauth.js

@@ -15,6 +15,9 @@ import fetch from "node-fetch";
 /** Re-acquire this many ms before the stated expiry to absorb clock skew. */
 const EXPIRY_SKEW_MS = 60_000;
 
+/** Token-endpoint abort timeout. Matches Drupal/Drush outbound HTTP. */
+export const OAUTH_TOKEN_TIMEOUT_MS = 30_000;
+
 /**
  * Per-site token cache, keyed by site._name. A value is either a resolved
  * { token, expiresAt, refreshToken } entry or an in-flight Promise of one
@@ -67,20 +70,31 @@ function buildBody(oauth, useRefresh, refreshToken) {
  * @param {boolean} useRefresh Whether to use the refresh_token grant.
  * @param {?string} refreshToken Refresh token for the refresh grant.
  * @returns {Promise<{token: string, expiresAt: number, refreshToken: ?string}>}
- * @throws {OAuthError} on a non-2xx response or a missing access_token.
+ * @throws {OAuthError} on a non-2xx response, a missing access_token, or a timeout.
  */
 async function requestToken(site, useRefresh, refreshToken) {
   const { oauth } = site;
   const url = `${site.baseUrl}${oauth.tokenUrl || "/oauth/token"}`;
 
-  const res = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/x-www-form-urlencoded",
-      Accept: "application/json",
-    },
-    body: buildBody(oauth, useRefresh, refreshToken),
-  });
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: buildBody(oauth, useRefresh, refreshToken),
+      signal: AbortSignal.timeout(OAUTH_TOKEN_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err?.name === "AbortError" || err?.name === "TimeoutError") {
+      throw new OAuthError(
+        `OAuth token request to ${site._name} timed out after ${OAUTH_TOKEN_TIMEOUT_MS / 1000}s.`
+      );
+    }
+    throw err;
+  }
 
   if (!res.ok) {
     throw new OAuthError(

package/src/lib/principal.js

@@ -17,6 +17,7 @@ import { getDefaultSiteName, getInboundGrants } from "./config.js";
 import { inferOperation } from "./operations.js";
 import { POLICY_DIGEST } from "./policy-promotion.js";
 import { resolveSecurityConfig, SecurityError } from "./security.js";
+import { lookupWorkflow } from "./workflow-prompts.js";
 
 const identityStore = new AsyncLocalStorage();
 
@@ -515,6 +516,19 @@ export function filterPromptsByPrincipal(prompts, identity, visibleTools) {
   if (!identity) return prompts;
   const visible = new Set((visibleTools ?? []).map((tool) => tool.name));
   return prompts.filter((prompt) => {
+    const wf = lookupWorkflow(prompt.name);
+    if (wf) {
+      if (wf.readOnly) {
+        if (!principalHasScope(identity, "mcp_read")) return false;
+      } else if (!principalHasScope(identity, "mcp_write")) {
+        return false;
+      }
+      if (!wf.builtin && Array.isArray(wf.publicTools) &&
+          !wf.publicTools.every((name) => visible.has(name))) {
+        return false;
+      }
+      return true;
+    }
     if (WRITE_WORKFLOW_PROMPTS.has(prompt.name)) {
       return principalHasScope(identity, "mcp_write");
     }