drupal-mcp-connector 2.19.0 → 2.20.0

package/README.md

@@ -68,7 +68,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 
 ## Features
 
-### 120 Tools Across 26 Modules
+### 123 Tools Across 27 Modules
 
 | Module | Tools |
 |--------|-------|
@@ -77,6 +77,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 | **Users** | List, get, create, update, block/unblock, role management (PII-gated) |
 | **Media** | List types, CRUD, file upload, orphaned-media detection |
 | **GraphQL** | Execute a query, schema introspection (mutation-gated) |
+| **Codegen** | Optional graphql_compose_codegen inspect/diff/generate (generate is `--dry-run` text) |
 | **Entities** | Generic CRUD for *any* Drupal entity type (paragraphs, commerce, webforms, …) |
 | **Site** | Site info, content-type discovery, configured-site listing |
 | **Reports** | Content summary, stale content, field completeness, SEO/accessibility audits, taxonomy usage, user activity, revision hotspots (10 read-only reports) |
@@ -99,7 +100,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 | **Audit (composite)** | `drupal_audit_site_health` — scored content/links/config dashboard with a roll-up grade |
 | **Config & Governance** | Governed config get/list/set via the server-tool bridge; `drupal_mcp_whoami` tier/capability report |
 
-**Preview writes with `dryRun`.** The node and entity create/update/delete tools accept an optional `dryRun: true` flag that validates the request and returns a preview of exactly what would be written — without committing anything to Drupal.
+**Preview writes with `dryRun`.** The node and entity create/update/delete tools accept an optional `dryRun: true` flag that runs the connector's checks and returns a preview of the payload, without committing anything to Drupal. The result's `checks` block says what was checked. Field access and entity validation are checked only when Sentinel's non-saving draft endpoint ran; see [docs/tools-reference.md](docs/tools-reference.md#preview-writes-with-dryrun).
 
 ### MCP Resources
 Browsable, always-fresh context the client can read without calling a tool:
@@ -144,8 +145,14 @@ npm run install:commands     # copies into ~/.claude/commands, ~/.grok/commands,
 # npm run install:commands -- --clients claude
 # npm run install:commands -- --clients codex
 # npm run install:commands -- --home /path/to/fake-home   # tests / CI
+# npm run install:commands -- --modules   # also write stubs for module-owned tools
 ```
 
+Module-owned tools ([docs/module-tools.md](docs/module-tools.md)) get a prompt
+whenever they are visible to the caller. Their bare `/drupal-<namespace>-<alias>`
+stubs are written only with `--modules`, which discovers them from the sources
+in `config/config.json`.
+
 From an npm install, the same files ship at
 `node_modules/drupal-mcp-connector/.agents/commands/`. Do not copy them into an
 application repo's `.claude/` or `.grok/` directory.
@@ -308,7 +315,7 @@ an operator channel: keep the agent's credentials off it, and pin
 | [OAuth client_credentials](docs/oauth-client-credentials.md) | Production OAuth deploy: scope→role mapping, JSON:API writes, config persistence, secret handling, troubleshooting |
 | [Architecture](docs/architecture.md) | Backend abstraction, canonical model, and how to extend it |
 | [GraphQL Setup](docs/graphql-local-setup.md) | GraphQL Compose backend + local TLS notes |
-| [Tools Reference](docs/tools-reference.md) | Full reference for all 120 tools |
+| [Tools Reference](docs/tools-reference.md) | Full reference for all 123 tools |
 | [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
 | [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
 | [Verification](docs/verification.md) | Prove a secure install: static + live checks, negative probes, evidence artefact, managed residuals |

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,63 @@
   },
 
   "_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. See docs/module-tools.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"] }
+          }
+        },
+        "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.0",
+  "version": "2.20.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,31 @@ 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 -->";
+
+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 +91,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 +112,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 +132,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`;
 }
 

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,6 +30,8 @@ import { pathToFileURL } from "url";
 import { allDefinitions } from "../src/tools/index.js";
 import {
   commandFileName,
+  moduleCommandFileName,
+  MODULE_STUB_MARKER,
   renderCommandMarkdown,
   renderClaudeCommandMarkdown,
   renderCodexSkillMarkdown,
@@ -63,7 +70,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 +80,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 +114,55 @@ 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. */
+function isModuleStub(path) {
+  try {
+    return readFileSync(path, "utf8").includes(MODULE_STUB_MARKER);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Write one `drupal-*.md` per tool into each requested client directory,
  * pruning stale stubs first. Unknown client names fail closed.
@@ -111,12 +171,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 +199,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 +224,40 @@ 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);
+    }
+    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 +266,9 @@ 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.
 `;
 
 const invokedDirectly =
@@ -169,9 +280,35 @@ 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 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}`);

package/src/index.js

@@ -59,7 +59,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";
+import { buildToolPrompts, createPromptSurface } from "./lib/tool-prompts.js";
 
 // Apply config/secrets.map (or the shipped example table) before any site
 // resolution. MCP clients spawn this file directly; the shell launcher is
@@ -313,17 +313,14 @@ const buildConnectorServer = createConnectorServerFactory({
     },
     read: readResource,
   },
-  prompts: {
-    definitions: ALL_PROMPTS,
-    list: async () => {
-      const identity = getRequestIdentity();
-      const tools = await discoverableTools();
-      return filterPromptsByPrincipal(ALL_PROMPTS, identity, tools);
-    },
-    get: (name, args) => WORKFLOW_PROMPT_NAMES.has(name)
-      ? getPromptMessages(name, args)
-      : getToolPromptMessages(name, args, definitionsByName),
-  },
+  prompts: createPromptSurface({
+    staticPrompts: ALL_PROMPTS,
+    discover: discoverableTools,
+    filter: (prompts, tools) => filterPromptsByPrincipal(prompts, getRequestIdentity(), tools),
+    workflowNames: WORKFLOW_PROMPT_NAMES,
+    workflowMessages: getPromptMessages,
+    definitionsByName,
+  }),
 });
 
 // ---------------------------------------------------------------------------

package/src/lib/backends/graphql-schema.js

@@ -8,6 +8,7 @@
  */
 
 import { drupalGraphqlFetch } from "../drupal-fetch.js";
+import { describeGraphqlErrors } from "../error-body.js";
 import { graphqlTypeToEntity } from "./graphql-names.js";
 
 // Introspection is intentionally nested four `ofType` levels deep: a field type
@@ -150,9 +151,16 @@ class SchemaMap {
  * Build a SchemaMap from a raw introspection response.
  * @param {object} introspection The `{ data: { __schema } }` response.
  * @returns {SchemaMap}
+ * @throws {Error} When the response has no schema. The message carries the
+ *   server's cleaned, bounded errors (see `describeGraphqlErrors`).
  */
 function buildSchemaMap(introspection) {
-  const schema = introspection.data.__schema;
+  const schema = introspection?.data?.__schema;
+  if (!schema) {
+    // A 200 with `errors` and no schema (introspection off, access denied).
+    const detail = describeGraphqlErrors(introspection?.errors) || "the response has no schema";
+    throw new Error(`GraphQL introspection failed: ${detail}`);
+  }
   const typesByName = new Map(schema.types.map((t) => [t.name, t]));
   const queryType = typesByName.get(schema.queryType.name);
   const map = new SchemaMap();

package/src/lib/backends/graphql.js

@@ -12,6 +12,7 @@
  */
 
 import { drupalGraphqlFetch } from "../drupal-fetch.js";
+import { describeGraphqlErrors } from "../error-body.js";
 import { Backend } from "./backend-interface.js";
 import { BackendCapabilityError } from "./errors.js";
 import { loadSchemaMap } from "./graphql-schema.js";
@@ -129,14 +130,15 @@ export class GraphqlBackend extends Backend {
    * them so a backend failure surfaces as an error, not a silently-empty result.
    * @param {string} query GraphQL query document.
    * @returns {Promise<object>} The raw `{ data, errors? }` response.
-   * @throws {Error} When the response contains GraphQL errors.
+   * @throws {Error} When the response contains GraphQL errors. The messages are
+   *   cleaned and bounded (see `describeGraphqlErrors`).
    */
   async _query(query) {
     const json = await drupalGraphqlFetch(this.site, { query });
     if (json?.errors?.length) {
       throw new Error(
         `GraphQL query failed on site "${this.site._name}": ` +
-        json.errors.map((e) => e.message).join("; ")
+        describeGraphqlErrors(json.errors)
       );
     }
     return json;

package/src/lib/backends/index.js

@@ -11,6 +11,8 @@
 import { drupalFetch } from "../drupal-fetch.js";
 import { drupalGraphqlFetch } from "../drupal-fetch.js";
 import { clearToken } from "../oauth.js";
+import { describeGraphqlErrors } from "../error-body.js";
+import { httpStatusOf } from "../error-status.js";
 import { JsonApiBackend } from "./jsonapi.js";
 import { GraphqlBackend } from "./graphql.js";
 import { BackendResolutionError } from "./errors.js";
@@ -43,9 +45,11 @@ export function _clearBackendCache() {
  */
 export function isAuthError(err) {
   const msg = String(err?.message || "");
+  // The response status, never a bare "401" in the path or the detail (#355).
+  const status = httpStatusOf(err);
   return (
-    /\b401\b/.test(msg) ||
-    (/\b403\b/.test(msg) && /token|oauth|credential|scope/i.test(msg)) ||
+    status === 401 ||
+    (status === 403 && /token|oauth|credential|scope/i.test(msg)) ||
     /invalid_client|invalid_grant|unauthorized_client|invalid_token/i.test(msg) ||
     /\bunauthorized\b/i.test(msg)
   );
@@ -121,7 +125,9 @@ async function probeProtocol(name, site) {
     if (name === "graphql") {
       const json = await drupalGraphqlFetch(site, { query: "{ __typename }" });
       if (json && !json.errors) return { ok: true, error: null };
-      return { ok: false, error: new Error(json?.errors?.[0]?.message || "GraphQL probe returned errors") };
+      // The probe error ends up in the resolution error the client sees, and
+      // isAuthError() reads it: cleaned and bounded, keywords intact (#356).
+      return { ok: false, error: new Error(describeGraphqlErrors(json?.errors?.[0]) || "GraphQL probe returned errors") };
     }
     return { ok: false, error: new Error(`unknown backend "${name}"`) };
   } catch (error) {

package/src/lib/backends/jsonapi.js

@@ -804,6 +804,8 @@ export class JsonApiBackend extends Backend {
    * Describe a bundle's fields by sampling one entity and inferring attribute
    * types from its values. JSON:API has no schema endpoint, so an empty bundle
    * yields a `note` and empty maps.
+   * JSON:API leaves a field the account may not view out of the resource, so
+   * such a field is not in the result; an empty field keeps its key (#337).
    * @param {string} entityType
    * @param {string} bundle
    * @returns {Promise<{entityType: string, bundle: string, resourceType?: string, note?: string, attributes: object, relationships: object}>}