drupal-mcp-connector 2.17.0 → 2.18.0

package/src/lib/sentinel-draft.js

@@ -0,0 +1,530 @@
+/**
+ * One Sentinel HTTP client and one fail-closed absence policy
+ * (d.o #3621022 / GitHub #176).
+ *
+ * Path builders, If-Match, lang/state headers, missing-endpoint classifiers,
+ * validated inventory, and working-revision rewrites live here. Tools call
+ * these functions; they must not sniff GraphQL `rawQuery` or copy the
+ * missing-endpoint English sentence.
+ */
+
+import { entityRevisionId } from "./write-revision.js";
+
+const LANGCODE_RE = /^[a-z][a-z0-9_-]{0,11}$/;
+const MISSING_DRAFT_ENDPOINT =
+  "The site does not provide Sentinel's governed draft endpoint (d.o #3621022). " +
+  "Update the server-side module; the draft was not discarded and no canonical fallback was attempted.";
+const MISSING_TRANSLATION_ENDPOINT =
+  "The site does not provide Sentinel's governed draft-translation endpoint. " +
+  "Update MCP Sentinel; no canonical langcode PATCH was attempted.";
+const MISSING_DRAFT_RE = /does not provide Sentinel's governed draft endpoint/;
+const MISSING_TRANSLATION_RE = /does not provide Sentinel's governed draft-translation endpoint/;
+const DRUPAL_ABSENCE_RE = /Drupal (404|405)\b/;
+
+/**
+ * Whether a backend can issue Sentinel's JSON:API draft/translation routes.
+ * Requires `capabilities().sentinelDraft` when that flag is present.
+ * Otherwise requires JSON:API `resourcePath` plus `rawQuery`. GraphQL
+ * `rawQuery({ query })` does not count.
+ * @param {object} [backend]
+ * @returns {boolean}
+ */
+export function supportsSentinelDraft(backend) {
+  if (!backend || typeof backend !== "object") return false;
+  if (typeof backend.capabilities === "function") {
+    let caps;
+    try {
+      caps = backend.capabilities();
+    } catch {
+      caps = undefined;
+    }
+    if (caps && typeof caps === "object" && Object.hasOwn(caps, "sentinelDraft")) {
+      return caps.sentinelDraft === true;
+    }
+  }
+  return typeof backend.rawQuery === "function" && typeof backend.resourcePath === "function";
+}
+
+/**
+ * Whether an error is Sentinel's missing governed draft endpoint (404/405).
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isMissingDraftEndpoint(error) {
+  return MISSING_DRAFT_RE.test(String(error?.message ?? ""));
+}
+
+/**
+ * Whether an error is Sentinel's missing governed draft-translation endpoint
+ * (404/405). Permission, transport, and malformed inventory are not absence.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isMissingTranslationEndpoint(error) {
+  return MISSING_TRANSLATION_RE.test(String(error?.message ?? ""));
+}
+
+/**
+ * @param {unknown} error
+ * @param {string} message
+ * @returns {Error}
+ */
+function missingEndpointError(error, message) {
+  if (DRUPAL_ABSENCE_RE.test(String(error?.message))) {
+    return new Error(message, { cause: error });
+  }
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * @param {string} langcode
+ * @returns {string}
+ */
+export function assertDraftLangcode(langcode) {
+  const value = String(langcode || "").trim();
+  if (!LANGCODE_RE.test(value)) {
+    throw new Error("A valid target langcode is required (for example 'es' or 'pt-br').");
+  }
+  return value;
+}
+
+/**
+ * @param {object} [draftRevision]
+ * @returns {{live: string, working: string}}
+ */
+function requireWorkingPair(draftRevision) {
+  const live = String(draftRevision?.liveVid ?? "");
+  const working = String(draftRevision?.workingVid ?? "");
+  if (!/^[1-9]\d*$/.test(live) || !/^[1-9]\d*$/.test(working) || live === working) {
+    throw new Error("Draft continuation requires distinct, verified live and working revision IDs.");
+  }
+  return { live, working };
+}
+
+/**
+ * @param {object} [draftRevision]
+ * @returns {string}
+ */
+function requireParagraphRevisionId(draftRevision) {
+  const revisionId = String(draftRevision?.revisionId ?? draftRevision?.workingVid ?? "");
+  if (!/^[1-9]\d*$/.test(revisionId)) {
+    throw new Error("Paragraph translation requires a verified paragraph revision ID.");
+  }
+  return revisionId;
+}
+
+/**
+ * @param {object} backend
+ * @param {string} entityType
+ * @param {string} bundle
+ * @param {string} id
+ * @returns {string}
+ */
+function draftResource(backend, entityType, bundle, id) {
+  if (entityType !== "node" && entityType !== "paragraph" && entityType !== "media") {
+    throw new Error("Governed draft translation is implemented for nodes, paragraphs, and media.");
+  }
+  if (!supportsSentinelDraft(backend)) {
+    throw new Error("This backend does not support governed draft continuation.");
+  }
+  return `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+}
+
+/**
+ * One Sentinel HTTP request. Node/media vs paragraph differ only in the
+ * If-Match value and optional `X-MCP-Draft-State` — callers build those.
+ * @param {object} backend
+ * @param {object} spec
+ * @param {string} spec.entityType
+ * @param {string} spec.bundle
+ * @param {string} spec.id
+ * @param {string} spec.suffix Path after the entity UUID (`mcp-draft`,
+ *   `mcp-draft/translations`, `mcp-translations`).
+ * @param {object} [spec.options] Passed to JSON:API `rawQuery`.
+ * @param {string} spec.missingMessage Absence rewrite for Drupal 404/405.
+ * @returns {Promise<*>}
+ */
+async function sentinelDraftRequest(backend, {
+  entityType, bundle, id, suffix, options, missingMessage,
+}) {
+  const base = draftResource(backend, entityType, bundle, id);
+  try {
+    return await backend.rawQuery({
+      path: `${base}/${suffix}`,
+      options,
+    });
+  } catch (error) {
+    throw missingEndpointError(error, missingMessage);
+  }
+}
+
+/**
+ * Validate or continue a draft, using the same payload and revision precondition.
+ * No canonical fallback: an absent endpoint or refused precondition stops work.
+ * @param {object} backend JSON:API backend.
+ * @param {object} input Canonical update input plus draftRevision.
+ * @param {boolean} preflight Validate without saving.
+ * @returns {Promise<object>} Preflight metadata or the written canonical entity.
+ */
+export async function writeDraft(backend, input, preflight = false) {
+  const { entityType, bundle, id, attributes = {}, relationships, draftRevision, langcode } = input;
+  if (entityType === "paragraph") {
+    return writeParagraphDraft(backend, input, preflight);
+  }
+  const { live, working } = requireWorkingPair(draftRevision);
+  const data = { type: `${entityType}--${bundle}`, id, attributes };
+  if (relationships) data.relationships = relationships;
+  const headers = {
+    "If-Match": `"${live}:${working}"`,
+    "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+  };
+  const targetLang = langcode ? assertDraftLangcode(langcode) : null;
+  if (targetLang) headers["X-MCP-Draft-Langcode"] = targetLang;
+  const result = await sentinelDraftRequest(backend, {
+    entityType, bundle, id, suffix: "mcp-draft", missingMessage: MISSING_DRAFT_ENDPOINT,
+    options: { method: "PATCH", headers, body: JSON.stringify({ data }) },
+  });
+  if (preflight) {
+    if (result?.meta?.draft_preflight !== true
+      || String(result.meta.live) !== live || String(result.meta.working) !== working) {
+      throw new Error("The site did not confirm a non-saving draft preflight. Refusing to continue.");
+    }
+    if (targetLang && result.meta.langcode && String(result.meta.langcode) !== targetLang) {
+      throw new Error("The site did not confirm the requested translation language. Refusing to continue.");
+    }
+    return result;
+  }
+  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
+    throw new Error("Draft write response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+  }
+  return backend.toCanonical(result.data);
+}
+
+/**
+ * Create a target-language translation as an unpublished forward revision.
+ * If-Match is `"live"` when there is no working copy, or `"live:working"` when
+ * adding the language onto an existing unpublished English draft.
+ * @param {object} backend
+ * @param {object} input
+ * @param {boolean} [preflight]
+ * @returns {Promise<object>}
+ */
+export async function createTranslationDraft(backend, input, preflight = false) {
+  const { entityType, bundle, id, attributes = {}, relationships, draftRevision } = input;
+  const langcode = assertDraftLangcode(input.langcode);
+  if (entityType === "paragraph") {
+    return createParagraphTranslationDraft(backend, {
+      entityType, bundle, id, attributes, relationships, draftRevision, langcode,
+    }, preflight);
+  }
+  const live = String(draftRevision?.liveVid ?? "");
+  const workingRaw = draftRevision?.workingVid;
+  const working = workingRaw === undefined || workingRaw === null || workingRaw === ""
+    ? ""
+    : String(workingRaw);
+  if ((entityType !== "node" && entityType !== "media") || !/^[1-9]\d*$/.test(live)) {
+    throw new Error("Translation create requires a verified live revision ID.");
+  }
+  if (working && (!/^[1-9]\d*$/.test(working) || working === live)) {
+    throw new Error("Translation create requires distinct live and working revision IDs when a working copy exists.");
+  }
+  const safeAttributes = { ...attributes };
+  delete safeAttributes.langcode;
+  const data = { type: `${entityType}--${bundle}`, id, attributes: safeAttributes };
+  if (relationships) data.relationships = relationships;
+  const ifMatch = working ? `"${live}:${working}"` : `"${live}"`;
+  let result;
+  try {
+    result = await sentinelDraftRequest(backend, {
+      entityType, bundle, id, suffix: "mcp-draft/translations",
+      missingMessage: MISSING_TRANSLATION_ENDPOINT,
+      options: {
+        method: "POST",
+        headers: {
+          "If-Match": ifMatch,
+          "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+          "X-MCP-Draft-Langcode": langcode,
+        },
+        body: JSON.stringify({ data }),
+      },
+    });
+  } catch (error) {
+    throw rewriteTranslationWorkingRevisionError(error);
+  }
+  if (preflight) {
+    if (result?.meta?.draft_preflight !== true || String(result.meta.live) !== live) {
+      throw new Error("The site did not confirm a non-saving translation preflight. Refusing to continue.");
+    }
+    return result;
+  }
+  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
+    throw new Error("Translation create response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+  }
+  return backend.toCanonical(result.data);
+}
+
+/**
+ * Live + working revision ids for a node translation create.
+ * Prefers Sentinel's mcp-translations inventory over JSON:API
+ * `rel:working-copy`, which 403s on some unpublished drafts even when a
+ * working revision exists (#282).
+ *
+ * Missing 404/405 inventory is absence and may fall back to the working-copy
+ * alias. Permission, 5xx, and malformed inventory are not absence — they throw.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string, existing?: ?object}} ref
+ * @returns {Promise<{liveVid: ?(number|string), workingVid: ?(number|string)}>}
+ */
+export async function resolveNodeTranslationPair(backend, { entityType, bundle, id, existing }) {
+  const fromEntity = existing ? entityRevisionId(existing) : null;
+  let meta;
+  try {
+    meta = await readTranslationInventory(backend, { entityType, bundle, id });
+  } catch (error) {
+    if (!isMissingTranslationEndpoint(error)) throw error;
+    if (typeof backend.getEntity !== "function") {
+      return { liveVid: fromEntity, workingVid: undefined };
+    }
+    let workingCopy = null;
+    try {
+      workingCopy = await backend.getEntity({
+        entityType, bundle, id, resourceVersion: "rel:working-copy",
+      });
+    } catch {
+      workingCopy = null;
+    }
+    const workingVid = workingCopy ? entityRevisionId(workingCopy) : null;
+    const distinct = workingVid !== null && fromEntity !== null && String(workingVid) !== String(fromEntity);
+    return { liveVid: fromEntity, workingVid: distinct ? workingVid : undefined };
+  }
+  const liveVid = meta.live?.vid ?? fromEntity;
+  const workingVid = meta.working?.vid;
+  const distinct = workingVid !== undefined && workingVid !== null && workingVid !== ""
+    && liveVid !== undefined && liveVid !== null
+    && String(workingVid) !== String(liveVid);
+  return { liveVid, workingVid: distinct ? workingVid : undefined };
+}
+
+/**
+ * Rewrite Sentinel's live-only 409 into an actionable connector error.
+ * @param {unknown} error
+ * @returns {Error}
+ */
+export function rewriteTranslationWorkingRevisionError(error) {
+  if (/A working revision exists\. Reload and send both revision IDs/i.test(String(error?.message || ""))) {
+    return new Error(
+      "Translation create sent only the live revision, but a working draft exists. " +
+      "The connector should have sent both live and working revision IDs (If-Match). " +
+      "Reload with drupal_list_translations and retry. See connector #282.",
+      { cause: error instanceof Error ? error : undefined },
+    );
+  }
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Read live/working translation inventory from Sentinel.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string, revisionId?: string|number}} ref
+ * @returns {Promise<object>}
+ */
+export async function readTranslationInventory(backend, { entityType, bundle, id, revisionId }) {
+  const headers = {};
+  if (revisionId !== undefined && revisionId !== null && revisionId !== "") {
+    headers["If-Match"] = `"${requireParagraphRevisionId({ revisionId })}"`;
+  }
+  const result = await sentinelDraftRequest(backend, {
+    entityType, bundle, id, suffix: "mcp-translations",
+    missingMessage: MISSING_TRANSLATION_ENDPOINT,
+    options: Object.keys(headers).length ? { method: "GET", headers } : undefined,
+  });
+  if (!result?.meta?.live) {
+    throw new Error("The site did not return a translation inventory.");
+  }
+  return result.meta;
+}
+
+/**
+ * Read optional inventory, falling back only when the endpoint is unsupported.
+ * Permission, transport and malformed-response failures are not absence.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string}} ref
+ * @returns {Promise<object|null>}
+ */
+export async function readNodeDraftInventory(backend, ref) {
+  if ((ref.entityType !== "node" && ref.entityType !== "media")
+    || !supportsSentinelDraft(backend)) return null;
+  let inventory;
+  try {
+    inventory = await readTranslationInventory(backend, ref);
+  } catch (error) {
+    if (isMissingTranslationEndpoint(error)) return null;
+    throw error;
+  }
+  const validVid = (vid) => /^[1-9]\d*$/.test(String(vid ?? "")) && Number.isSafeInteger(Number(vid));
+  if (!validVid(inventory.live?.vid)
+    || (inventory.working && (!validVid(inventory.working.vid)
+      || !Array.isArray(inventory.working.translations)
+      || inventory.working.translations.some((row) => !row || typeof row.langcode !== "string"
+        || typeof row.status !== "boolean")))) {
+    throw new Error("Sentinel returned an invalid revision inventory. Re-read before updating.");
+  }
+  return inventory;
+}
+
+/**
+ * Ensure inventory discovery does not turn a published language into a draft.
+ * Sentinel still validates the revision pair and language on every request.
+ * @param {object} inventory
+ * @param {string|undefined} langcode
+ */
+export function assertInventoryDraftLanguage(inventory, langcode) {
+  const rows = inventory.working?.translations ?? [];
+  if (!langcode && rows.length !== 1) {
+    throw new Error("This working revision contains translations. Pass an explicit langcode for an existing unpublished language; no draft was created.");
+  }
+  const row = langcode ? rows.find((item) => item.langcode === langcode) : rows[0];
+  if (!row || row.status !== false) {
+    throw new Error("The requested language is not an existing unpublished working draft. Published languages and other drafts were left unchanged.");
+  }
+}
+
+/**
+ * Read one unpublished working translation.
+ * @param {object} backend
+ * @param {object} input
+ * @returns {Promise<object>}
+ */
+export async function readDraftTranslation(backend, input) {
+  const { entityType, bundle, id, draftRevision } = input;
+  const langcode = assertDraftLangcode(input.langcode);
+  if (entityType === "paragraph") {
+    return readParagraphDraftTranslation(backend, input);
+  }
+  const { live, working } = requireWorkingPair(draftRevision);
+  const result = await sentinelDraftRequest(backend, {
+    entityType, bundle, id, suffix: "mcp-draft",
+    missingMessage: MISSING_TRANSLATION_ENDPOINT,
+    options: {
+      method: "GET",
+      headers: {
+        "If-Match": `"${live}:${working}"`,
+        "X-MCP-Draft-Langcode": langcode,
+      },
+    },
+  });
+  if (!result?.data || result.data.id !== id) {
+    throw new Error("Draft translation read did not identify the requested entity.");
+  }
+  return backend.toCanonical(result.data);
+}
+
+/**
+ * Continue an unpublished paragraph translation on a pinned revision.
+ * @param {object} backend
+ * @param {object} input
+ * @param {boolean} [preflight]
+ * @returns {Promise<object>}
+ */
+async function writeParagraphDraft(backend, input, preflight = false) {
+  const { entityType, bundle, id, attributes = {}, relationships, draftRevision } = input;
+  const langcode = assertDraftLangcode(input.langcode);
+  const revisionId = requireParagraphRevisionId(draftRevision);
+  const draftState = input.draftState;
+  if (typeof draftState !== "string" || !/^[a-f0-9]{64}$/.test(draftState)) {
+    throw new Error("Paragraph translation update requires draftState from the previous draft read. Re-read the draft; do not retry old copy with a refreshed token.");
+  }
+  const data = { type: `${entityType}--${bundle}`, id, attributes };
+  if (relationships) data.relationships = relationships;
+  const result = await sentinelDraftRequest(backend, {
+    entityType, bundle, id, suffix: "mcp-draft", missingMessage: MISSING_DRAFT_ENDPOINT,
+    options: {
+      method: "PATCH",
+      headers: {
+        "If-Match": `"${revisionId}"`,
+        "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+        "X-MCP-Draft-Langcode": langcode,
+        "X-MCP-Draft-State": draftState,
+      },
+      body: JSON.stringify({ data }),
+    },
+  });
+  if (preflight) {
+    if (result?.meta?.draft_preflight !== true
+      || String(result.meta.live) !== revisionId
+      || (result.meta.langcode && String(result.meta.langcode) !== langcode)) {
+      throw new Error("The site did not confirm a non-saving paragraph translation preflight. Refusing to continue.");
+    }
+    return result;
+  }
+  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
+    throw new Error("Paragraph translation write did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+  }
+  return { ...backend.toCanonical(result.data), draftState: result.meta?.draft_state };
+}
+
+/**
+ * Create an unpublished paragraph translation on a pinned revision.
+ * @param {object} backend
+ * @param {object} input
+ * @param {boolean} [preflight]
+ * @returns {Promise<object>}
+ */
+async function createParagraphTranslationDraft(backend, input, preflight = false) {
+  const { entityType, bundle, id, attributes = {}, relationships, draftRevision, langcode } = input;
+  const revisionId = requireParagraphRevisionId(draftRevision);
+  const safeAttributes = { ...attributes };
+  delete safeAttributes.langcode;
+  const data = { type: `${entityType}--${bundle}`, id, attributes: safeAttributes };
+  if (relationships) data.relationships = relationships;
+  const result = await sentinelDraftRequest(backend, {
+    entityType, bundle, id, suffix: "mcp-draft/translations",
+    missingMessage: MISSING_TRANSLATION_ENDPOINT,
+    options: {
+      method: "POST",
+      headers: {
+        "If-Match": `"${revisionId}"`,
+        "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+        "X-MCP-Draft-Langcode": langcode,
+      },
+      body: JSON.stringify({ data }),
+    },
+  });
+  if (preflight) {
+    if (result?.meta?.draft_preflight !== true || String(result.meta.live) !== revisionId) {
+      throw new Error("The site did not confirm a non-saving paragraph translation preflight. Refusing to continue.");
+    }
+    return result;
+  }
+  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
+    throw new Error("Paragraph translation create did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+  }
+  return { ...backend.toCanonical(result.data), draftState: result.meta?.draft_state };
+}
+
+/**
+ * Read one unpublished paragraph translation of a pinned revision.
+ * @param {object} backend
+ * @param {object} input
+ * @returns {Promise<object>}
+ */
+async function readParagraphDraftTranslation(backend, input) {
+  const { entityType, bundle, id, draftRevision } = input;
+  const langcode = assertDraftLangcode(input.langcode);
+  const revisionId = requireParagraphRevisionId(draftRevision);
+  const result = await sentinelDraftRequest(backend, {
+    entityType, bundle, id, suffix: "mcp-draft",
+    missingMessage: MISSING_TRANSLATION_ENDPOINT,
+    options: {
+      method: "GET",
+      headers: {
+        "If-Match": `"${revisionId}"`,
+        "X-MCP-Draft-Langcode": langcode,
+      },
+    },
+  });
+  if (!result?.data || result.data.id !== id) {
+    throw new Error("Paragraph draft translation read did not identify the requested entity.");
+  }
+  return { ...backend.toCanonical(result.data), draftState: result.meta?.draft_state };
+}

package/src/lib/server-tools.js

@@ -23,10 +23,19 @@
  */
 
 import fetch from "node-fetch";
+import { createHmac, randomBytes } from "node:crypto";
 import { authHeadersAsync, clientHeaders, CLIENT_NAME, CLIENT_VERSION } from "./config.js";
-import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial } from "./data-flow.js";
+import { consumeBudgetIfEnforced, northboundHeaders, sourceBudgetDenial, getDataFlowContext } from "./data-flow.js";
 import { clearToken } from "./oauth.js";
 
+/** Calls a configured module binding through the registry, without fallback. */
+export async function callBoundModuleTool(site, binding, args, required) {
+  // Load at invocation: built-in tool definitions are also consumed by the
+  // registry's dispatch middleware, so a static import would create a cycle.
+  const { createModuleToolRegistry } = await import("./module-tools.js");
+  return createModuleToolRegistry().callBinding(site, binding, args, required);
+}
+
 /**
  * Canonical server-side tool names for governed config operations.
  *
@@ -50,11 +59,14 @@ const MCP_PROTOCOL_VERSION = "2025-06-18";
 let rpcId = 0;
 
 /**
- * Per-site MCP session cache, keyed by site._name. Holds the `Mcp-Session-Id`
+ * MCP session cache, keyed by site, endpoint, credentials and principal. Holds the `Mcp-Session-Id`
  * issued by the server's `initialize` response; cleared and re-acquired when the
  * server reports the session is gone (expiry).
  */
 const sessions = new Map();
+// Ephemeral cache identity only, never a persisted password verifier. A keyed
+// digest also prevents offline guessing if a diagnostic exposes a cache key.
+const sessionIdentityKey = randomBytes(32);
 
 /**
  * Resolve a site's server-tools endpoint, or throw a clear, actionable error
@@ -156,7 +168,7 @@ function parseSse(text) {
  * @returns {Promise<string>} The issued MCP session id.
  * @throws {Error} on transport failure, a JSON-RPC error, or a missing session id.
  */
-async function initializeSession(site, endpoint) {
+async function initializeSession(site, endpoint, key) {
   const payload = {
     jsonrpc: "2.0",
     id: ++rpcId,
@@ -173,6 +185,8 @@ async function initializeSession(site, endpoint) {
       method: "POST",
       headers: await baseHeaders(site, null),
       body: JSON.stringify(payload),
+      size: 262144,
+      signal: AbortSignal.timeout(15000),
     });
 
   let res = await post();
@@ -205,12 +219,15 @@ async function initializeSession(site, endpoint) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+      size: 262144,
+      signal: AbortSignal.timeout(15000),
     });
   } catch {
     // Notification is advisory; proceed with the established session.
   }
 
-  sessions.set(site._name, sessionId);
+  if (sessions.size >= 128) sessions.delete(sessions.keys().next().value);
+  sessions.set(key, sessionId);
   return sessionId;
 }
 
@@ -220,9 +237,9 @@ async function initializeSession(site, endpoint) {
  * @param {string} endpoint Fully-qualified endpoint URL.
  * @returns {Promise<string>} The active MCP session id.
  */
-async function ensureSession(site, endpoint) {
-  const cached = sessions.get(site._name);
-  return cached || initializeSession(site, endpoint);
+async function ensureSession(site, endpoint, key) {
+  const cached = sessions.get(key);
+  return cached || initializeSession(site, endpoint, key);
 }
 
 /**
@@ -253,16 +270,32 @@ function isSessionError(res, body) {
  * @returns {Promise<*>} The tool's structured result.
  * @throws {Error} on transport failure, JSON-RPC error, or tool error.
  */
-export async function callServerTool(site, toolName, args = {}) {
+export async function callServerTool(site, toolName, args = {}, options = {}) {
+  return requestServerTool(site, "tools/call", { name: toolName, arguments: args }, options);
+}
+
+/** Fetch one page of the authenticated module tool catalog. */
+export async function listServerTools(site, cursor) {
+  return requestServerTool(site, "tools/list", cursor === undefined ? {} : { cursor }, {
+    maxBytes: 262144, preserveErrors: true,
+  });
+}
+
+/** Shared bounded MCP request transport; retries only explicit auth/session rejection. */
+async function requestServerTool(site, method, params, options) {
+  const toolName = params.name ?? method;
   const endpoint = resolveEndpoint(site);
   const payload = {
     jsonrpc: "2.0",
     id: ++rpcId,
-    method: "tools/call",
-    params: { name: toolName, arguments: args },
+    method,
+    params,
   };
 
-  let sessionId = await ensureSession(site, endpoint);
+  const sessionKey = createHmac("sha256", sessionIdentityKey).update(JSON.stringify([
+    site._name, endpoint, await authHeadersAsync(site), getDataFlowContext()?.principalKey ?? null,
+  ])).digest("hex");
+  let sessionId = await ensureSession(site, endpoint, sessionKey);
   let refreshedAuth = false;
   let reinitedSession = false;
   let paid = false;
@@ -275,21 +308,22 @@ export async function callServerTool(site, toolName, args = {}) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify(payload),
+      ...(options.maxBytes ? { size: options.maxBytes, signal: AbortSignal.timeout(15000) } : {}),
     });
     const { body, rawText } = await readBody(res);
 
     // OAuth sites: a 401 may mean the token expired server-side. Refresh once.
-    if (res.status === 401 && site.oauth && !refreshedAuth) {
+    if (res.status === 401 && site.oauth && !refreshedAuth && options.retryRejected !== false) {
       refreshedAuth = true;
       clearToken(site);
       continue;
     }
 
     // Session expired/unknown: re-initialise once and replay.
-    if (isSessionError(res, body) && !reinitedSession) {
+    if (isSessionError(res, body) && !reinitedSession && options.retryRejected !== false) {
       reinitedSession = true;
-      sessions.delete(site._name);
-      sessionId = await ensureSession(site, endpoint);
+      sessions.delete(sessionKey);
+      sessionId = await ensureSession(site, endpoint, sessionKey);
       continue;
     }
 
@@ -308,7 +342,7 @@ export async function callServerTool(site, toolName, args = {}) {
 
     // MCP tools/call result: { content: [...], isError?: boolean }.
     const result = body?.result;
-    if (result?.isError) {
+    if (result?.isError && !options.preserveErrors) {
       const detail = extractTextContent(result) || "tool reported an error";
       const mapped = sourceBudgetDenial(detail);
       if (mapped) throw mapped;