drupal-mcp-connector 2.19.1 → 2.21.0

package/bin/drupal-mcp-verify.js

@@ -21,7 +21,7 @@ import process from "node:process";
 import fetch from "node-fetch";
 import { verifyStatic, verifyLive } from "../src/lib/verify.js";
 import { loadConfig, getSiteConfig, resolveOauth } from "../src/lib/config.js";
-import { callServerTool } from "../src/lib/server-tools.js";
+import { callServerTool, listServerTools } from "../src/lib/server-tools.js";
 
 /** Parses `--flag`, `--key value` and `--key=value`. */
 function parseArgs(argv) {
@@ -118,12 +118,13 @@ async function main() {
       ? resolveOauth({ ...(config.sites?.[siteName ?? config.defaultSite] ?? {}), _name: siteName ?? config.defaultSite })
       : getSiteConfig(siteName);
     // The real bridge client, so the governed-tool probes exercise the real
-    // contract (MCP session, tool_api name, tool-level refusal) rather than a
-    // hand-rolled JSON-RPC body the server would reject as malformed.
+    // contract (MCP session, advertised tool name, tool-level refusal) rather
+    // than a hand-rolled JSON-RPC body the server would reject as malformed.
     evidence.push(
       await verifyLive(site, {
         transport: fetch,
         callTool: callServerTool,
+        listTools: listServerTools,
         contentTarget: args["content-target"] ? String(args["content-target"]) : null,
         contentTargetType: args["content-target-type"] ? String(args["content-target-type"]) : null,
       }),

package/config/config.example.json

@@ -109,7 +109,7 @@
       },
       "serverTools": { "url": "/mcp" },
       "drushSsh": {
-        "_comment": "Development only. SSH target of the local web container. Whitelisted to config export/status — every other drupal_drush_* tool is blocked here. rawSql is omitted, so drupal_drush_sql_query is refused: raw SQL reads underneath Drupal's entity API and is only available via mcp_sentinel's governed command. To enable it, set rawSql:\"governed\", add \"mcp-sentinel:sql-query\" to allowedCommands, and set allow_raw_sql on the site's policy profile.",
+        "_comment": "Development only. SSH target of the local web container. Whitelisted to config export/status — every other drupal_drush_* tool is blocked here. rawSql is omitted, so drupal_drush_sql_query is refused: raw SQL reads underneath Drupal's entity API and is only available through mcp_sentinel's governed SQL tool. To enable it, set rawSql:\"governed\" here and set allow_raw_sql on the site's policy profile. Then choose one path. With serverTools.bindings.sqlQuery mapped to a module tool (see _server_tools), the query goes to mcp_sentinel over the governed MCP endpoint and uses no SSH host, key or connection. Without a bindings object it runs over this SSH bridge, so also add \"mcp-sentinel:sql-query\" to allowedCommands.",
         "host":            "<web-container-ssh-host>",
         "user":            "<web-container-ssh-user>",
         "keyPath":         "~/.ssh/id_ed25519",
@@ -154,13 +154,74 @@
   },
 
   "_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."
+    "_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. 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": {
+        "url": "/mcp",
+        "modules": {
+          "namespace": "example_site",
+          "tools": {
+            "list_activities": {
+              "name":         "tool_api__example_list_activities",
+              "scope":        "example_read",
+              "operation":    "read",
+              "capabilities": []
+            },
+            "record_activity": {
+              "name":         "tool_api__example_record_activity",
+              "scope":        "example_write",
+              "operation":    "write",
+              "capabilities": []
+            },
+            "get_config":       { "name": "tool_api__mcp_sentinel_config_get",            "scope": "mcp_config", "operation": "read",  "capabilities": ["configRead"] },
+            "list_config":      { "name": "tool_api__mcp_sentinel_config_list",           "scope": "mcp_config", "operation": "read",  "capabilities": ["configRead"] },
+            "set_config":       { "name": "tool_api__mcp_sentinel_config_set",            "scope": "mcp_config", "operation": "write", "capabilities": ["configWrite"] },
+            "codegen_inspect":  { "name": "tool_api__graphql_compose_codegen_inspect",    "scope": "mcp_config", "operation": "read",  "capabilities": ["configRead"] },
+            "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": {
+          "configGet":      "get_config",
+          "configList":     "list_config",
+          "configSet":      "set_config",
+          "codegenInspect": "codegen_inspect",
+          "codegenDiff":    "codegen_diff",
+          "codegenPreview": "codegen_preview",
+          "sqlQuery":       "sql_query"
+        }
+      }
+    }
   },
 
   "_audit_tools": {
     "_comment": "The audit tool groups (drupal_report_* links/config/content, drupal_audit_site_health) are read-only. Privileged audits (404 log, config drift/best-practices, module/permission/status) are self-sufficient via the connector's own drush bridge (drushSsh) — no companion module required; the config-inspection audits additionally prefer the governed config server-tool when serverTools is configured. They report 'unavailable' when no source is configured for the site. drupal_report_broken_links does no outbound HTTP unless called with checkLive:true; see each site's optional 'audit' block for live-check limits."
   },
 
+  "_protected_modules": {
+    "_comment": "drupal_drush_module_disable refuses governance, integrity, secrets, auth and API modules on every preset (mcp_sentinel, audit_chain, field_guard, file_gate, key, encrypt, simple_oauth, consumers, jsonapi, serialization, mcp_server, mcp_server_tool_bridge, tool, content_moderation, workflows). Two optional per-site keys under security change the list. protectedModules adds modules and cannot shrink the default. allowProtectedModuleUninstall is the explicit opt-out and removes only the modules it names. A malformed value in either key blocks every uninstall on that site. Neither key opens readOnly, allowDestructive or drushSsh.allowedCommands. An uninstall that would cascade to dependents is refused. See docs/security.md#protected-modules.",
+    "example": { "preset": "development", "protectedModules": ["my_audit_module"], "allowProtectedModuleUninstall": [] }
+  },
+
+  "_core_extension": {
+    "_comment": "core.extension lists installed modules and themes, so changing it can uninstall a protected module. On every preset drupal_config_set refuses a write to core.extension, and drupal_drush_config_import first runs `drush config:status` and imports nothing when core.extension differs or the status cannot be read. If drushSsh.allowedCommands is set it must list config:status as well as config:import. One optional per-site key under security opens both: allowCoreExtensionChange, true or false, default false. Any other value keeps both refused. With it set, drupal_config_set still refuses a value that removes or alters an installed protected module, and drupal_drush_config_import runs unchecked because the connector cannot read the sync directory. The key opens no other gate. A config import run outside the connector is out of its reach; add core.extension to denied_config_types on the MCP Sentinel policy profile for the source-side control. See docs/security.md#changes-to-coreextension.",
+    "example": { "preset": "config-editor", "allowCoreExtensionChange": false }
+  },
+
   "_mcp_client_registration": {
     "_comment": "Add under your MCP client's mcpServers config (stdio transport)",
     "drupal": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.19.1",
+  "version": "2.21.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

@@ -15,6 +15,10 @@
  * Driven from the same tool definitions as the server (src/tools/index.js), so the
  * command set never drifts from the tools. Run: `npm run generate:commands`.
  *
+ * Module-owned tools are discovered at runtime and have no committed stub. The
+ * installer writes them on request (`install:commands -- --modules`), using
+ * `moduleCommandFileName` and the `MODULE_STUB_MARKER` exported here.
+ *
  * Exports `renderCommandMarkdown`, `renderClaudeCommandMarkdown`,
  * `renderCodexSkillMarkdown`, `renderCodexToolsReference`, `CODEX_SKILL_NAME`,
  * `commandFileName`, `COMMANDS_DIR`, and `generate` for tests; the file-writing
@@ -25,7 +29,9 @@ import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs"
 import { pathToFileURL } from "url";
 
 import { allDefinitions } from "../src/tools/index.js";
-import { paramList, toolNameToPromptName } from "../src/lib/tool-prompts.js";
+import {
+  isModuleDefinition, moduleCallNotes, toolDescription, toolNameToPromptName, toolParams,
+} from "../src/lib/tool-prompts.js";
 import { isDestructiveTool } from "../src/lib/operations.js";
 
 /** Canonical, harness-agnostic command tree shipped in the repo and the npm package. */
@@ -36,6 +42,45 @@ export function commandFileName(def) {
   return `${toolNameToPromptName(def.name)}.md`;
 }
 
+/** 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_]*)$/;
+
+/**
+ * Command filename for a module-owned tool: `drupal-<namespace>-<alias>.md`. The
+ * operation is left out so the command reads as the module's action; the stub
+ * body still names the full tool.
+ *
+ * Either part may contain `__`, so a tool name cannot always be split back.
+ * Pass the configured parts when they are known; the name is parsed only as a
+ * fallback, at the first separator.
+ *
+ * @param {object} def - A tool definition.
+ * @param {{namespace: string, alias: string}} [parts] - From local config.
+ * @returns {?string} The filename, or null when the name is not a module tool.
+ */
+export function moduleCommandFileName(def, parts) {
+  const match = MODULE_TOOL_NAME.exec(def?.name ?? "");
+  if (!match) return null;
+  const [namespace, alias] = parts ? [parts.namespace, parts.alias] : [match[1], match[2]];
+  return `drupal-${namespace}-${alias}.md`.replace(/_/g, "-");
+}
+
 /** Collapse to a single-line, double-quoted YAML scalar. */
 function yamlString(value) {
   const clean = String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\s+/g, " ").trim();
@@ -60,18 +105,20 @@ function argumentHint(params) {
  * @returns {string} File contents (ends with a trailing newline).
  */
 export function renderCommandMarkdown(def, options = {}) {
-  const params   = paramList(def.inputSchema);
+  const params   = toolParams(def);
   const required = params.filter((p) => p.required);
   const optional = params.filter((p) => !p.required);
   const line = (p) => `- \`${p.name}\` (${p.hint})${p.description ? `: ${p.description}` : ""}`;
+  const isModule = isModuleDefinition(def);
   const argumentsPhrase = options.argumentsPhrase ?? "the arguments supplied with this command";
 
-  const frontmatter = ["---", `description: ${yamlString(def.description)}`];
+  const description = toolDescription(def);
+  const frontmatter = ["---", `description: ${yamlString(description)}`];
   if (params.length) frontmatter.push(`argument-hint: ${yamlString(argumentHint(params))}`);
   if (options.allowedTools) frontmatter.push(`allowed-tools: ${options.allowedTools}`);
   frontmatter.push("---");
 
-  const body = [`Call the MCP tool \`${def.name}\`.`, "", def.description];
+  const body = [`Call the MCP tool \`${def.name}\`.`, "", description];
 
   if (isDestructiveTool(def.name)) {
     body.push("", "> ⚠ **Destructive** — this permanently changes or deletes data. Confirm with the user before calling.");
@@ -79,7 +126,7 @@ export function renderCommandMarkdown(def, options = {}) {
 
   body.push("");
   if (params.length === 0) {
-    body.push("This tool takes no arguments — call it directly.");
+    body.push(isModule ? "This tool takes no parameters." : "This tool takes no arguments — call it directly.");
   } else {
     body.push(`Parse ${argumentsPhrase} into this tool's parameters:`, "");
     if (required.length) {
@@ -99,6 +146,8 @@ export function renderCommandMarkdown(def, options = {}) {
     );
   }
 
+  if (isModule) body.push("", ...moduleCallNotes(def, params.length > 0), "", MODULE_STUB_MARKER);
+
   return `${frontmatter.join("\n")}\n\n${body.join("\n")}\n`;
 }
 
@@ -109,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

@@ -14,10 +14,15 @@
  * Pass `--clients` to subset. Never writes into a project tree. Codex custom
  * prompts (`~/.codex/prompts`) are not written — they are deprecated.
  *
- * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,codex,agents]`
+ * Module-owned tools (docs/module-tools.md) are written only with `--modules`.
+ * That run discovers the tools the local config approves, from the configured
+ * sources, and writes `drupal-<namespace>-<alias>.md` stubs. Run it from the
+ * directory that holds `config/config.json`.
+ *
+ * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,codex,agents] [--modules]`
  */
 
-import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, realpathSync } from "fs";
 import { homedir } from "os";
 import { join, resolve } from "path";
 import { pathToFileURL } from "url";
@@ -25,10 +30,15 @@ import { pathToFileURL } from "url";
 import { allDefinitions } from "../src/tools/index.js";
 import {
   commandFileName,
+  moduleCommandFileName,
+  MODULE_STUB_MARKER,
+  WORKFLOW_STUB_MARKER,
   renderCommandMarkdown,
   renderClaudeCommandMarkdown,
   renderCodexSkillMarkdown,
   renderCodexToolsReference,
+  renderWorkflowCommandMarkdown,
+  workflowCommandFileName,
   CODEX_SKILL_NAME,
 } from "./generate-commands.js";
 
@@ -63,7 +73,7 @@ const DEFAULT_CLIENTS = ["claude", "grok", "codex"];
  * Parse CLI flags. Unknown flags throw.
  *
  * @param {string[]} argv - Arguments after the script name.
- * @returns {{home?: string, clients: string[], help?: boolean}}
+ * @returns {{home?: string, clients: string[], modules?: boolean, help?: boolean}}
  */
 export function parseArgs(argv) {
   const out = { clients: [...DEFAULT_CLIENTS] };
@@ -73,6 +83,10 @@ export function parseArgs(argv) {
       out.help = true;
       continue;
     }
+    if (a === "--modules") {
+      out.modules = true;
+      continue;
+    }
     if (a === "--home") {
       out.home = argv[++i];
       if (!out.home) throw new Error("--home requires a directory");
@@ -103,6 +117,83 @@ function splitClients(raw) {
   return names;
 }
 
+/**
+ * Decide which module tools get a stub. A name that matches a built-in command,
+ * or that two module tools share, is refused so no command is shadowed.
+ *
+ * @param {Array<object>} moduleDefinitions - Definitions from live discovery.
+ * @param {Array<object>} [definitions] - Built-in definitions.
+ * @param {Map<string, {namespace: string, alias: string}>} [parts] - Configured
+ *   namespace and alias per tool name, so a `__` inside either is not misread.
+ * @returns {{stubs: Array<{file: string, def: object}>, refused: Array<{name: string, file: ?string, reason: string}>}}
+ */
+export function planModuleStubs(moduleDefinitions, definitions = allDefinitions, parts = new Map()) {
+  const builtIn = new Set(definitions.map(commandFileName));
+  const byFile = new Map();
+  const refused = [];
+  for (const def of moduleDefinitions) {
+    const file = moduleCommandFileName(def, parts.get(def.name));
+    if (!file) refused.push({ name: def.name, file, reason: "not a module tool name" });
+    else if (builtIn.has(file)) refused.push({ name: def.name, file, reason: "matches a built-in command" });
+    else byFile.set(file, [...(byFile.get(file) ?? []), def]);
+  }
+  const stubs = [];
+  for (const [file, defs] of byFile) {
+    if (defs.length === 1) stubs.push({ file, def: defs[0] });
+    else defs.forEach((def) => refused.push({ name: def.name, file, reason: "shared by more than one module tool" }));
+  }
+  return { stubs, refused };
+}
+
+/**
+ * Configured tool names that discovery did not return.
+ *
+ * @param {string[]} configured - Names from local policy.
+ * @param {Array<object>} discovered - Definitions from live discovery.
+ * @returns {string[]}
+ */
+export function missingModuleTools(configured, discovered) {
+  const found = new Set(discovered.map((def) => def.name));
+  return configured.filter((name) => !found.has(name));
+}
+
+/** Whether an installed stub was written for a module-owned tool or workflow. */
+function isModuleStub(path) {
+  try {
+    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.
@@ -111,12 +202,23 @@ function splitClients(raw) {
  * @param {string} [options.home] - Install root (default: os.homedir()).
  * @param {string[]} [options.clients] - Subset of CLIENTS keys.
  * @param {Array<object>} [options.definitions]
- * @returns {Array<{client: string, dir: string, written: string[]}>}
+ * @param {Array<object>} [options.moduleDefinitions] - Module tools from live
+ *   discovery. Omitted: installed module stubs are left as they are.
+ * @param {Map<string, {namespace: string, alias: string}>} [options.moduleParts]
+ *   Configured namespace and alias per module tool name.
+ * @param {boolean} [options.pruneModules=true] - Remove module stubs that are
+ *   not rewritten. Pass false when discovery was incomplete.
+ * @returns {Array<{client: string, dir: string, written: string[], moduleWritten: string[], catalogued?: number}>}
  */
 export function install(options = {}) {
   const home = resolve(options.home || homedir());
   const names = options.clients || DEFAULT_CLIENTS;
   const definitions = options.definitions || allDefinitions;
+  const withModules = Array.isArray(options.moduleDefinitions);
+  const moduleStubs = withModules
+    ? planModuleStubs(options.moduleDefinitions, definitions, options.moduleParts).stubs
+    : [];
+  const pruneModules = withModules && options.pruneModules !== false;
 
   const results = [];
   for (const name of names) {
@@ -128,15 +230,24 @@ export function install(options = {}) {
       const dir = join(home, client.rel, client.skillName);
       rmSync(dir, { recursive: true, force: true });
       mkdirSync(join(dir, "references"), { recursive: true });
-      writeFileSync(join(dir, "SKILL.md"), client.renderSkill(definitions));
-      writeFileSync(join(dir, "references", "tools.md"), client.renderReference(definitions));
-      results.push({ client: name, dir, written: ["SKILL.md", "references/tools.md"] });
+      // The Codex skill is one catalog, so module tools join it rather than
+      // getting files of their own. It is rebuilt on every run.
+      const catalog = [...definitions, ...moduleStubs.map((stub) => stub.def)];
+      writeFileSync(join(dir, "SKILL.md"), client.renderSkill(catalog));
+      writeFileSync(join(dir, "references", "tools.md"), client.renderReference(catalog));
+      results.push({
+        client: name, dir, written: ["SKILL.md", "references/tools.md"],
+        catalogued: moduleStubs.length, moduleWritten: [],
+      });
       continue;
     }
     const dir = join(home, client.rel);
     mkdirSync(dir, { recursive: true });
     for (const f of readdirSync(dir)) {
-      if (/^drupal-.*\.md$/.test(f)) rmSync(join(dir, f));
+      if (!/^drupal-.*\.md$/.test(f)) continue;
+      // Module stubs outlive a plain install; only a complete --modules run prunes them.
+      if (isModuleStub(join(dir, f)) && !pruneModules) continue;
+      rmSync(join(dir, f));
     }
     const written = [];
     for (const def of definitions) {
@@ -144,12 +255,45 @@ export function install(options = {}) {
       writeFileSync(join(dir, file), client.render(def));
       written.push(file);
     }
-    results.push({ client: name, dir, written });
+    const moduleWritten = [];
+    for (const { file, def } of moduleStubs) {
+      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;
 }
 
-const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,codex,agents]
+/**
+ * Discover the module-owned tools the local config approves, as the local
+ * operator (no inbound principal). Sources, credentials and governance checks
+ * are the ones the server uses; a source that fails returns no tools.
+ *
+ * @returns {Promise<{definitions: Array<object>, configured: string[], parts: Map<string, {namespace: string, alias: string}>}>}
+ */
+export async function discoverModuleDefinitions() {
+  // Loaded on demand so a plain install needs no site config or network.
+  const { loadLocalSecrets } = await import("../src/lib/load-secrets.js");
+  const { listResolvableSiteConfigs } = await import("../src/lib/dispatch.js");
+  const { createModuleToolRegistry, configuredModuleTools } = await import("../src/lib/module-tools.js");
+  loadLocalSecrets();
+  const sites = listResolvableSiteConfigs();
+  const definitions = await createModuleToolRegistry().list({ sites, identity: null });
+  const tools = configuredModuleTools(sites);
+  return {
+    definitions,
+    configured: tools.map((tool) => tool.name),
+    parts: new Map(tools.map(({ name, namespace, alias }) => [name, { namespace, alias }])),
+  };
+}
+
+const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,codex,agents] [--modules]
 
 Copy generated /drupal-* command stubs (and the Codex skill) into operator
 home directories. Does not write into a project tree. Does not write
@@ -158,6 +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 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 =
@@ -169,9 +318,48 @@ if (invokedDirectly) {
       console.error(HELP);
       process.exit(0);
     }
+    if (opts.modules) {
+      const { definitions, configured, parts } = await discoverModuleDefinitions();
+      const missing = missingModuleTools(configured, definitions);
+      if (configured.length === 0) {
+        console.error("[install-commands] --modules: no site configures serverTools.modules; nothing to discover.");
+      }
+      if (configured.length > 0 && definitions.length === 0) {
+        throw new Error(
+          `--modules: ${configured.length} module tools are configured but no source returned any. ` +
+          "Check the source, its credentials and its governance status. Nothing was written."
+        );
+      }
+      for (const name of missing) {
+        console.error(`[install-commands] WARNING: configured but not returned by its source: ${name}`);
+      }
+      for (const r of planModuleStubs(definitions, allDefinitions, parts).refused) {
+        console.error(`[install-commands] WARNING: no stub for ${r.name}: ${r.reason}${r.file ? ` (${r.file})` : ""}`);
+      }
+      opts.moduleDefinitions = definitions;
+      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) {
-      console.error(`[install-commands] wrote ${r.written.length} files to ${r.dir} (${r.client})`);
+      const extra = !opts.modules ? ""
+        : r.catalogued === undefined ? ` + ${r.moduleWritten.length} module stubs`
+          : ` (${r.catalogued} module tools in the catalog)`;
+      console.error(`[install-commands] wrote ${r.written.length} files${extra} to ${r.dir} (${r.client})`);
     }
   } catch (err) {
     console.error(`[install-commands] ${err.message}`);