drupal-mcp-connector 2.19.0 → 2.20.0

package/src/lib/server-tools.js

@@ -18,8 +18,8 @@
  * Config (per site):
  *   "serverTools": { "url": "/mcp" }   // path is resolved against site.baseUrl
  *
- * Tools are NOT functional until the Drupal-side governed config tools ship;
- * until then the server returns a tool-not-found error, surfaced verbatim.
+ * The governed config tools work only when the source advertises them to this
+ * account in `tools/list`; otherwise the call fails closed before it is sent.
  */
 
 import fetch from "node-fetch";
@@ -27,6 +27,7 @@ import { createHmac, randomBytes } from "node:crypto";
 import { authHeadersAsync, clientHeaders, CLIENT_NAME, CLIENT_VERSION } from "./config.js";
 import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial, getDataFlowContext } from "./data-flow.js";
 import { clearToken } from "./oauth.js";
+import { cleanErrorText, describeErrorBody } from "./error-body.js";
 
 /** Calls a configured module binding through the registry, without fallback. */
 export async function callBoundModuleTool(site, binding, args, required) {
@@ -37,19 +38,103 @@ export async function callBoundModuleTool(site, binding, args, required) {
 }
 
 /**
- * Canonical server-side tool names for governed config operations.
+ * Tool API ids of the governed config tools (mcp_sentinel's McpConfigGet/List/Set
+ * plugins). These are ids, not wire names: the bridge decides the wire name, so
+ * it is resolved from the source's `tools/list` (see resolveServerToolName).
+ */
+export const SERVER_TOOL_IDS = Object.freeze({
+  configGet:  "mcp_sentinel_config_get",
+  configList: "mcp_sentinel_config_list",
+  configSet:  "mcp_sentinel_config_set",
+});
+
+/**
+ * Wire-name prefixes the Drupal tool bridge has used for a Tool API tool, in
+ * order of preference. Current mcp_server releases join the `tool_api` base id
+ * and the tool id with `__`; older ones used a dot.
+ */
+const WIRE_PREFIXES = ["tool_api__", "tool_api."];
+
+/** Upper bound on `tools/list` pages read while resolving a name. */
+const MAX_CATALOG_PAGES = 16;
+
+/**
+ * Wire names a bridge may advertise for a Tool API id, preferred first.
+ * @param {string} id Tool API id, e.g. `mcp_sentinel_config_set`.
+ * @returns {string[]} Candidate wire names.
+ */
+export function serverToolCandidates(id) {
+  return WIRE_PREFIXES.map((prefix) => `${prefix}${id}`);
+}
+
+/**
+ * Read every tool name the source advertises to this caller.
+ * @param {object} site Resolved site config.
+ * @param {Function} [list] Catalog page reader `(site, cursor) => {tools, nextCursor}`.
+ * @returns {Promise<Set<string>>} Advertised tool names.
+ * @throws {Error} on a malformed page, a repeated cursor, or too many pages.
+ */
+export async function advertisedServerToolNames(site, list = listServerTools) {
+  const names = new Set();
+  const seen = new Set();
+  let cursor;
+  for (let page = 0; page < MAX_CATALOG_PAGES; page++) {
+    const result = await list(site, cursor);
+    if (!Array.isArray(result?.tools)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" is malformed: tools/list returned no tools array.`);
+    }
+    for (const tool of result.tools) {
+      if (typeof tool?.name === "string") names.add(tool.name);
+    }
+    if (result.nextCursor === undefined || result.nextCursor === null) return names;
+    if (typeof result.nextCursor !== "string" || seen.has(result.nextCursor)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" returned an invalid or repeated cursor.`);
+    }
+    cursor = result.nextCursor;
+    seen.add(cursor);
+  }
+  throw new Error(`Server-tool catalog for site "${site._name}" exceeds ${MAX_CATALOG_PAGES} pages.`);
+}
+
+/**
+ * Resolve the wire name the source advertises for a governed config tool.
  *
- * Drupal's mcp_server_tool_bridge exposes every Tool-API tool through the MCP
- * protocol under the derivative name `tool_api.<mcp_tool_config id>`, so the
- * governed config tools registered against mcp_sentinel's McpConfigGet/List/Set
- * plugins surface as `tool_api.mcp_sentinel_config_*`. Keep the mapping here so
- * a server-side rename is a one-line change.
+ * Fails closed: when the catalog lists none of the candidate names, no name is
+ * guessed and nothing is called.
+ * @param {object} site Resolved site config.
+ * @param {string} binding Key of SERVER_TOOL_IDS (`configGet` | `configList` | `configSet`).
+ * @param {{list?: Function}} [deps] Injectable catalog page reader.
+ * @returns {Promise<string>} The advertised wire name.
+ * @throws {Error} if the binding is unknown or the tool is not advertised.
  */
-export const SERVER_TOOLS = {
-  configGet:  "tool_api.mcp_sentinel_config_get",
-  configList: "tool_api.mcp_sentinel_config_list",
-  configSet:  "tool_api.mcp_sentinel_config_set",
-};
+export async function resolveServerToolName(site, binding, { list = listServerTools } = {}) {
+  const id = new Map(Object.entries(SERVER_TOOL_IDS)).get(binding);
+  if (!id) throw new Error(`Unknown server tool binding "${binding}".`);
+  const candidates = serverToolCandidates(id);
+  const advertised = await advertisedServerToolNames(site, list);
+  const name = candidates.find((candidate) => advertised.has(candidate));
+  if (!name) {
+    throw new Error(
+      `Server tool "${id}" is not advertised by the source for site "${site._name}" ` +
+      `(looked for ${candidates.join(" and ")} in tools/list). No call was made. ` +
+      "Register and enable it as an mcp_tool_config entity, check that this account holds the scope the tool requires, " +
+      "or map it under serverTools.bindings. See docs/integration-contract.md."
+    );
+  }
+  return name;
+}
+
+/**
+ * Call a governed config tool by the wire name the source advertises for it.
+ * @param {object} site Resolved site config.
+ * @param {string} binding Key of SERVER_TOOL_IDS.
+ * @param {object} [args] Tool arguments.
+ * @returns {Promise<*>} The tool's structured result.
+ * @throws {Error} if the tool is not advertised, or as callServerTool.
+ */
+export async function callGovernedServerTool(site, binding, args = {}) {
+  return callServerTool(site, await resolveServerToolName(site, binding), args);
+}
 
 /** MCP protocol version advertised on the handshake and every subsequent POST. */
 const MCP_PROTOCOL_VERSION = "2025-06-18";
@@ -158,6 +243,73 @@ function parseSse(text) {
   return found;
 }
 
+/**
+ * Message for a non-2xx bridge response.
+ *
+ * The body is untrusted: an HTML error page from Drupal, PHP or a proxy, a
+ * server path or a backtrace. Only a cleaned, bounded detail is shown (see
+ * `describeErrorBody`). The prefix holds the HTTP status and always ends with a
+ * colon — the documented message shape (`httpStatusOf`, and
+ * `classifyBridgeError` when the error has no marker).
+ *
+ * A body that is a JSON-RPC error keeps its integer code and its cleaned
+ * message, so a refusal sent with a 401 or 403 stays readable.
+ * @param {string} prefix Message start, e.g. "Server-tool call x failed 502".
+ * @param {object} res node-fetch Response with `ok === false`.
+ * @param {string} rawText Response body.
+ * @param {?object} body Parsed JSON-RPC body, if any.
+ * @returns {string} Bounded message.
+ */
+function failedResponseMessage(prefix, res, rawText, body) {
+  const rpcError = body?.error;
+  if (rpcError && typeof rpcError === "object") {
+    const code = Number.isInteger(rpcError.code) ? ` ${rpcError.code}` : "";
+    const message = cleanErrorText(rpcError.message) || "the server returned no error message";
+    return `${prefix}: JSON-RPC error${code}: ${message}`;
+  }
+  const detail = describeErrorBody(rawText, res.headers?.get?.("content-type") ?? null);
+  return `${prefix}: ${detail || "the server returned an empty body"}`;
+}
+
+/**
+ * Message for a JSON-RPC `error` object.
+ *
+ * `error.code` is kept when it is an integer, because callers read it.
+ * `error.message` is cleaned and bounded. `error.data` is never read: with
+ * verbose errors on it holds a backtrace.
+ * @param {string} subject Message start, e.g. "Server-tool x".
+ * @param {*} rpcError JSON-RPC error object from the response.
+ * @returns {string} Bounded message.
+ */
+function rpcErrorMessage(subject, rpcError) {
+  const code = Number.isInteger(rpcError?.code) ? ` (${rpcError.code})` : "";
+  const detail = cleanErrorText(rpcError?.message) || "the server returned no error message";
+  return `${subject} error${code}: ${detail}`;
+}
+
+/**
+ * Build a bridge error that says what failed.
+ *
+ * The message ends with a response body or tool text, so code that branches on
+ * the failure reads these properties, never the message (#361):
+ *  - `bridgeFailure`: `"session"` (the handshake failed; no tool was reached),
+ *    `"http"` (non-2xx on the request), `"rpc"` (JSON-RPC error object) or
+ *    `"tool"` (the tool ran and its result has `isError`);
+ *  - `status`: the HTTP status, on a non-2xx response only (see `httpStatusOf`);
+ *  - `rpcCode`: the JSON-RPC `error.code`, when it is an integer.
+ * @param {string} message Error message.
+ * @param {"session"|"http"|"rpc"|"tool"} failure What failed.
+ * @param {{status?: number, rpcCode?: *}} [facts] Response status or JSON-RPC code.
+ * @returns {Error} The marked error.
+ */
+function bridgeError(message, failure, { status, rpcCode } = {}) {
+  const error = new Error(message);
+  error.bridgeFailure = failure;
+  if (Number.isInteger(status)) error.status = status;
+  if (Number.isInteger(rpcCode)) error.rpcCode = rpcCode;
+  return error;
+}
+
 /**
  * Perform the MCP session handshake against the server and cache the resulting
  * session id: `initialize` (read the `Mcp-Session-Id` response header) followed
@@ -197,18 +349,21 @@ async function initializeSession(site, endpoint, key) {
 
   const { body, rawText } = await readBody(res);
   if (!res.ok) {
-    throw new Error(`Server-tool session initialize failed ${res.status}: ${rawText}`);
+    throw bridgeError(
+      failedResponseMessage(`Server-tool session initialize failed ${res.status}`, res, rawText, body),
+      "session",
+      { status: res.status },
+    );
   }
   if (body?.error) {
-    const { code, message } = body.error;
-    const hasCode = code !== undefined && code !== null;
-    throw new Error(`Server-tool session initialize error${hasCode ? ` (${code})` : ""}: ${message}`);
+    throw bridgeError(rpcErrorMessage("Server-tool session initialize", body.error), "session", { rpcCode: body.error?.code });
   }
 
   const sessionId = res.headers.get("mcp-session-id");
   if (!sessionId) {
-    throw new Error(
-      `Server-tool session initialize for site "${site._name}" returned no Mcp-Session-Id header.`
+    throw bridgeError(
+      `Server-tool session initialize for site "${site._name}" returned no Mcp-Session-Id header.`,
+      "session",
     );
   }
 
@@ -265,7 +420,7 @@ function isSessionError(res, body) {
  * OAuth sites clears and re-acquires the token then replays (same session); a
  * server-side session expiry re-initialises the session then replays.
  * @param {object} site Resolved site config (provides baseUrl + auth).
- * @param {string} toolName Server-side MCP tool name (see SERVER_TOOLS).
+ * @param {string} toolName Server-side MCP wire name (see resolveServerToolName).
  * @param {object} [args] Tool arguments object.
  * @returns {Promise<*>} The tool's structured result.
  * @throws {Error} on transport failure, JSON-RPC error, or tool error.
@@ -330,23 +485,29 @@ async function requestServerTool(site, method, params, options) {
     if (!res.ok) {
       const mapped = sourceBudgetDenial(rawText);
       if (mapped) throw mapped;
-      throw new Error(`Server-tool call ${toolName} failed ${res.status}: ${rawText}`);
+      throw bridgeError(
+        failedResponseMessage(`Server-tool call ${toolName} failed ${res.status}`, res, rawText, body),
+        "http",
+        { status: res.status },
+      );
     }
 
     // JSON-RPC transport-level error.
     if (body?.error) {
-      const { code, message } = body.error;
-      const hasCode = code !== undefined && code !== null;
-      throw new Error(`Server-tool ${toolName} error${hasCode ? ` (${code})` : ""}: ${message}`);
+      throw bridgeError(rpcErrorMessage(`Server-tool ${toolName}`, body.error), "rpc", { rpcCode: body.error?.code });
     }
 
     // MCP tools/call result: { content: [...], isError?: boolean }.
     const result = body?.result;
     if (result?.isError && !options.preserveErrors) {
-      const detail = extractTextContent(result) || "tool reported an error";
-      const mapped = sourceBudgetDenial(detail);
+      // The budget code is looked for in the whole text, before it is cut.
+      const text = extractTextContent(result);
+      const mapped = sourceBudgetDenial(text);
       if (mapped) throw mapped;
-      throw new Error(`Server-tool ${toolName} reported an error: ${detail}`);
+      // The tool's own words are for the caller (a governed refusal explains
+      // itself), so they are kept: cleaned and bounded, never relayed raw.
+      const detail = cleanErrorText(text) || "tool reported an error";
+      throw bridgeError(`Server-tool ${toolName} reported an error: ${detail}`, "tool");
     }
     return result;
   }

package/src/lib/tool-prompts.js

@@ -14,7 +14,7 @@
  * JSON type.
  */
 
-import { isDestructiveTool } from "./operations.js";
+import { inferOperation, isDestructiveTool } from "./operations.js";
 import { SITE_PARAM } from "./site-target.js";
 
 /** Convert a tool name to its prompt/command name: `drupal_create_node` → `drupal-create-node`. */
@@ -29,8 +29,13 @@ export const promptNameToToolName = (name) => name.replace(/-/g, "_");
  * @param {object} spec - A JSON-Schema property spec.
  * @returns {string} e.g. "string", "boolean (true/false)", "object (pass as JSON)".
  */
-export function typeHint(spec) {
+function typeHint(spec) {
   const t = Array.isArray(spec?.type) ? spec.type[0] : spec?.type;
+  // A short closed list is the most useful thing to show for a string choice.
+  if (Array.isArray(spec?.enum) && spec.enum.length > 0 && spec.enum.length <= 12 &&
+      spec.enum.every((v) => typeof v === "string" && v.length <= 40)) {
+    return `one of: ${spec.enum.join(", ")}`;
+  }
   switch (t) {
     case "boolean":       return "boolean (true/false)";
     case "number":
@@ -59,6 +64,79 @@ export function paramList(inputSchema) {
   }));
 }
 
+/**
+ * Whether a definition came from the module registry (src/lib/module-tools.js).
+ * Those names are reserved, so the prefix alone identifies them.
+ *
+ * @param {object} def - A tool definition.
+ * @returns {boolean}
+ */
+export const isModuleDefinition = (def) =>
+  typeof def?.name === "string" && def.name.startsWith("drupal_module_");
+
+/** Longest source-supplied description kept in a prompt or stub. */
+const SOURCE_TEXT_LIMIT = 1024;
+
+/**
+ * Flatten and bound text that a Drupal source supplied. It ends up in
+ * instruction text and in files on the operator's disk, so it stays on one
+ * line where it cannot start a heading, a rule or a block of its own.
+ *
+ * @param {*} value - Source-supplied text.
+ * @returns {string}
+ */
+export function sourceText(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, SOURCE_TEXT_LIMIT);
+}
+
+/**
+ * A tool's description as prompts and stubs should show it. Built-in text is
+ * authored in this repo and is returned as written.
+ *
+ * @param {object} def - A tool definition.
+ * @returns {string}
+ */
+export function toolDescription(def) {
+  return isModuleDefinition(def) ? sourceText(def.description) : def.description;
+}
+
+/**
+ * Parameter catalog a person fills in for a tool. A module-owned tool wraps the
+ * module's schema in a `{ catalogRevision, arguments }` envelope, so its
+ * parameters are the properties of `arguments`, not of the envelope.
+ *
+ * @param {object} def - A tool definition.
+ * @returns {Array<{name:string, required:boolean, hint:string, description:string}>}
+ */
+export function toolParams(def) {
+  if (!isModuleDefinition(def)) return paramList(def.inputSchema);
+  return paramList(def.inputSchema?.properties?.arguments)
+    .map((param) => ({ ...param, description: sourceText(param.description) }));
+}
+
+/**
+ * Call-shape guidance shared by module tool prompts and command stubs. The
+ * revision changes with the module's schema, so text never embeds its value.
+ *
+ * @param {object} def - A module tool definition.
+ * @param {boolean} hasParams - Whether the module declares any parameters.
+ * @returns {string[]} Lines to append to the instruction.
+ */
+export function moduleCallNotes(def, hasParams) {
+  const notes = [
+    "This is a module-owned tool. Its input has exactly two properties: `catalogRevision` and `arguments`.",
+    hasParams
+      ? "Put the parameters above inside `arguments`."
+      : "Pass an empty `arguments` object.",
+    "Copy `catalogRevision` from the constant in this tool's current input schema. " +
+    "If the call reports a changed schema, refresh the tool list and use the new value.",
+  ];
+  if (inferOperation(def.name) !== "read") {
+    notes.push("Do not retry a write after an uncertain result. Report it so the outcome can be checked first.");
+  }
+  return notes;
+}
+
 /**
  * Build one MCP prompt descriptor per tool definition.
  *
@@ -68,8 +146,8 @@ export function paramList(inputSchema) {
 export function buildToolPrompts(definitions) {
   return definitions.map((def) => ({
     name: toolNameToPromptName(def.name),
-    description: `Invoke the ${def.name} tool. ${def.description}`.slice(0, 300),
-    arguments: paramList(def.inputSchema).map((p) => ({
+    description: `Invoke the ${def.name} tool. ${toolDescription(def)}`.slice(0, 300),
+    arguments: toolParams(def).map((p) => ({
       name: p.name,
       description: p.description ? `${p.hint} — ${p.description}` : p.hint,
       required: p.required,
@@ -84,13 +162,14 @@ export function buildToolPrompts(definitions) {
  * @param {object} args - Arguments supplied to the prompt (all strings per MCP).
  * @returns {string} A user-role instruction message body.
  */
-export function renderToolInstruction(def, args = {}) {
-  const params   = paramList(def.inputSchema);
+function renderToolInstruction(def, args = {}) {
+  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 out = [`Call the MCP tool \`${def.name}\`.`, "", def.description];
+  const out = [`Call the MCP tool \`${def.name}\`.`, "", toolDescription(def)];
 
   if (isDestructiveTool(def.name)) {
     out.push("", "⚠ Destructive: this permanently changes or deletes data. Confirm with the user before calling.");
@@ -98,7 +177,7 @@ export function renderToolInstruction(def, args = {}) {
 
   out.push("");
   if (params.length === 0) {
-    out.push("This tool takes no arguments — call it directly.");
+    out.push(isModule ? "This tool takes no parameters." : "This tool takes no arguments — call it directly.");
   } else {
     if (required.length) {
       out.push("Required parameters (ask me for any that are missing — do not invent values):");
@@ -112,6 +191,8 @@ export function renderToolInstruction(def, args = {}) {
     }
   }
 
+  if (isModule) out.push("", ...moduleCallNotes(def, params.length > 0));
+
   const supplied = Object.entries(args ?? {}).filter(([, v]) => v !== undefined && v !== "");
   if (supplied.length) {
     out.push("", "Values I supplied:");
@@ -144,3 +225,53 @@ export function getToolPromptMessages(promptName, args = {}, definitionsByName)
   }
   return [{ role: "user", content: { type: "text", text: renderToolInstruction(def, args) } }];
 }
+
+/**
+ * Compose the server's prompt surface from the static prompts and the module
+ * tools that live discovery returns for this request. Module prompts inherit
+ * discovery's caller, site and source checks; nothing is cached across requests.
+ *
+ * @param {object} options
+ * @param {Array<object>} options.staticPrompts - Workflow prompts plus built-in tool prompts.
+ * @param {() => Promise<Array<object>>} options.discover - Tools visible to the current request.
+ * @param {(prompts: Array<object>, tools: Array<object>) => Array<object>} options.filter
+ *   Principal filter for the static prompts.
+ * @param {Set<string>} options.workflowNames - Names of the hand-authored workflow prompts.
+ * @param {(name: string, args: object) => Array<object>} options.workflowMessages
+ * @param {Map<string,object>} options.definitionsByName - Built-in tool name → definition.
+ * @returns {{definitions: Array<object>, list: Function, describe: Function, get: Function}}
+ */
+export function createPromptSurface({
+  staticPrompts, discover, filter, workflowNames, workflowMessages, definitionsByName,
+}) {
+  const get = (name, args) => workflowNames.has(name)
+    ? workflowMessages(name, args)
+    : getToolPromptMessages(name, args, definitionsByName);
+
+  async function visible() {
+    const tools = await discover();
+    const taken = new Set(staticPrompts.map((prompt) => prompt.name));
+    // A reserved module name cannot match a built-in, but never let a remote
+    // catalog shadow a static prompt if that invariant is ever broken.
+    const moduleDefs = tools.filter((tool) =>
+      isModuleDefinition(tool) && !taken.has(toolNameToPromptName(tool.name)));
+    return { prompts: [...filter(staticPrompts, tools), ...buildToolPrompts(moduleDefs)], moduleDefs };
+  }
+
+  return {
+    definitions: staticPrompts,
+    get,
+    list: async () => (await visible()).prompts,
+    /** Resolve one prompt, or null when it is not visible to this request. */
+    async describe(name, args = {}) {
+      const { prompts, moduleDefs } = await visible();
+      const known = prompts.find((prompt) => prompt.name === name);
+      if (!known) return null;
+      const live = moduleDefs.find((def) => toolNameToPromptName(def.name) === name);
+      const messages = live
+        ? getToolPromptMessages(name, args, new Map([[live.name, live]]))
+        : get(name, args);
+      return { description: known.description, messages };
+    },
+  };
+}

package/src/lib/usage.js

@@ -31,15 +31,6 @@ export const USAGE_DECISIONS = Object.freeze(["allow", "deny"]);
  */
 export const RECEIPT_OUTCOMES = Object.freeze(["ok", "failed", "unknown"]);
 
-/** Reconciliation states over one request / decision / receipt chain. */
-export const RECONCILE_STATES = Object.freeze([
-  "settled",
-  "denied",
-  "missing",
-  "duplicate",
-  "uncertain",
-]);
-
 const PHASE_SET = new Set(USAGE_PHASES);
 const DECISION_SET = new Set(USAGE_DECISIONS);
 const OUTCOME_SET = new Set(RECEIPT_OUTCOMES);