drupal-mcp-connector 2.6.1 → 2.7.1

package/src/lib/mcp-server.js

@@ -7,6 +7,24 @@
 
 import { Server } from "@modelcontextprotocol/server";
 
+/**
+ * Whether a listed resource URI (possibly templated) covers a requested URI.
+ * @param {string} listed
+ * @param {string} requested
+ * @returns {boolean}
+ */
+function resourceUriIsListed(listed, requested) {
+  if (listed === requested) return true;
+  if (typeof listed !== "string" || !listed.includes("{site}")) return false;
+  const marker = "{site}";
+  const at = listed.indexOf(marker);
+  const prefix = listed.slice(0, at);
+  const suffix = listed.slice(at + marker.length);
+  if (!requested.startsWith(prefix) || !requested.endsWith(suffix)) return false;
+  const captured = requested.slice(prefix.length, requested.length - suffix.length);
+  return captured.length > 0 && !captured.includes("/");
+}
+
 /**
  * Create the server factory shared by HTTP and stdio transports.
  *
@@ -14,9 +32,9 @@ import { Server } from "@modelcontextprotocol/server";
  * @param {{name: string, version: string}} surface.serverInfo
  * @param {{definitions: Array<object>, list?: () => Promise<Array<object>>, call: (name: string, args: object, context: object) => Promise<object>}} surface.tools
  *   `definitions` is the full static surface (schema projection); the optional
- *   `list` hook decides what is DISCOVERABLE per request (governance gating).
- * @param {{definitions: Array<object>, read: (uri: string) => Promise<object>}} surface.resources
- * @param {{definitions: Array<object>, get: (name: string, args: object) => Array<object>}} surface.prompts
+ *   `list` hook decides what is DISCOVERABLE per request (governance + entitlement).
+ * @param {{definitions: Array<object>, list?: () => Promise<Array<object>>, read: (uri: string) => Promise<object>}} surface.resources
+ * @param {{definitions: Array<object>, list?: () => Promise<Array<object>>, get: (name: string, args: object) => Array<object>}} surface.prompts
  * @returns {(context: import("@modelcontextprotocol/server").McpRequestContext) => Server}
  */
 export function createConnectorServerFactory({ serverInfo, tools, resources, prompts }) {
@@ -37,9 +55,14 @@ export function createConnectorServerFactory({ serverInfo, tools, resources, pro
       return server.projectCallToolResult(result, toolDefinitions.get(name)?.outputSchema);
     });
 
-    server.setRequestHandler("resources/list", async () => ({ resources: resources.definitions }));
+    server.setRequestHandler("resources/list", async () => ({
+      resources: resources.list ? await resources.list() : resources.definitions,
+    }));
     server.setRequestHandler("resources/read", async (request) => {
       const { uri } = request.params;
+      const visible = resources.list ? await resources.list() : resources.definitions;
+      const listed = visible.some((resource) => resourceUriIsListed(resource.uri, uri));
+      if (!listed) throw new Error(`Unknown resource: "${uri}"`);
       try {
         const data = await resources.read(uri);
         return {
@@ -50,10 +73,13 @@ export function createConnectorServerFactory({ serverInfo, tools, resources, pro
       }
     });
 
-    server.setRequestHandler("prompts/list", async () => ({ prompts: prompts.definitions }));
+    server.setRequestHandler("prompts/list", async () => ({
+      prompts: prompts.list ? await prompts.list() : prompts.definitions,
+    }));
     server.setRequestHandler("prompts/get", async (request) => {
       const { name, arguments: args } = request.params;
-      const known = prompts.definitions.find((prompt) => prompt.name === name);
+      const visible = prompts.list ? await prompts.list() : prompts.definitions;
+      const known = visible.find((prompt) => prompt.name === name);
       if (!known) throw new Error(`Unknown prompt: "${name}"`);
       return { description: known.description, messages: prompts.get(name, args ?? {}) };
     });

package/src/lib/patch-preflight.js

@@ -0,0 +1,176 @@
+/**
+ * JSON:API PATCH preflight for Drupal core's working-copy guard (#201).
+ *
+ * `EntityResource::patchIndividual()` rejects a canonical PATCH when the
+ * stored entity is not both the latest and the default revision. That check
+ * runs against the revision table *before* the payload is deserialized.
+ * An empty-body PATCH that returns 2xx still calls `$entity->save()` (and
+ * often `setNewRevision`) — so the probe must fail *after* the guard and
+ * *before* save. Core next compares `data.id` to the URL entity UUID; a
+ * well-formed but non-matching id yields 400 "does not match the ID in the
+ * payload" with no row written. Content-moderation's `rel:latest-version` /
+ * `rel:working-copy` aliases can disagree with storage (a revision row with
+ * no `content_moderation_state`), which is how every read tool reports
+ * clean and the write then 400s.
+ *
+ * `workingCopy: null` and "latest-version vid === default vid" are not proof
+ * the node is writable. That is the #201 lie.
+ *
+ * Distinct from #166: there a working copy is visible and the fix is PATCH
+ * `?resourceVersion=rel:working-copy`. This module does not implement that.
+ */
+
+import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
+
+/** Stable error code for a core working-copy / not-latest-revision block. */
+export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
+
+const WORKING_COPY_PATCH_RE = /has a working copy is not yet supported/i;
+
+/**
+ * Actionable replacement for core's "has a working copy" 400.
+ * Clearing the blocking row is revision surgery outside JSON:API.
+ */
+export const PATCH_BLOCKED_MESSAGE =
+  "This entity cannot be updated over JSON:API because the stored entity is not " +
+  "the latest revision (Drupal core #2795279). The JSON:API aliases " +
+  "rel:latest-version and rel:working-copy cannot show the blocking row. " +
+  "Clearing it requires revision surgery outside JSON:API (Drush / the entity API). " +
+  "See connector #201. Do not retry the same canonical PATCH.";
+
+/**
+ * Thrown when the core working-copy PATCH guard rejects a write (or its probe).
+ */
+export class PatchBlockedError extends Error {
+  /** @param {?Error} [cause] The original Drupal 400. */
+  constructor(cause) {
+    super(PATCH_BLOCKED_MESSAGE);
+    this.name = "PatchBlockedError";
+    this.code = PATCH_BLOCKED_CODE;
+    if (cause) this.cause = cause;
+  }
+}
+
+/**
+ * Whether an error is Drupal core's working-copy PATCH guard (core #2795279).
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isWorkingCopyPatchError(err) {
+  return WORKING_COPY_PATCH_RE.test(String(err?.message || ""));
+}
+
+/**
+ * Rewrite a core working-copy 400 into {@link PatchBlockedError}; otherwise
+ * return the original value.
+ * @param {unknown} err
+ * @returns {unknown}
+ */
+export function rewriteWorkingCopyPatchError(err) {
+  if (!isWorkingCopyPatchError(err)) return err;
+  return new PatchBlockedError(err instanceof Error ? err : new Error(String(err)));
+}
+
+/**
+ * Whether this update should run the PATCH probe.
+ * Skip unmoderated / non-revisionable bundles — the guard is about
+ * revisionable entities under content_moderation.
+ * @param {{existing?: ?object, attributes?: object}} input
+ * @returns {boolean}
+ */
+export function shouldPreflightPatch({ existing, attributes } = {}) {
+  if (hasExplicitModerationState(attributes)) return true;
+  return entityLooksModerated(existing);
+}
+
+/**
+ * UUID used as `data.id` on the probe PATCH so it cannot match the URL
+ * entity. Core throws after the working-copy guard and before save.
+ * @see EntityResource::patchIndividual()
+ */
+export const PATCH_PROBE_MISMATCH_ID = "00000000-0000-4000-a000-000000000001";
+
+const ID_MISMATCH_RE = /does not match the ID in the payload/i;
+
+/**
+ * Whether a probe error means the working-copy guard passed and no row
+ * was written (id mismatch, or a 422 during deserialize).
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isProbePassedWithoutSave(err) {
+  const msg = String(err?.message || "");
+  return ID_MISMATCH_RE.test(msg) || /Drupal 422\b/.test(msg);
+}
+
+/**
+ * Probe the same guard core uses on the canonical PATCH URL.
+ *
+ * Sends a PATCH whose `data.id` does not match the URL entity. Core runs
+ * the working-copy check first; a match on that phrase means no row was
+ * written. An id-mismatch 400 (or deserialize 422) means the guard passed
+ * and save was not reached. A 2xx would have saved a revision and is
+ * treated as a probe failure. Do not treat "latest-version vid === default
+ * vid" as writable.
+ *
+ * @param {object} args
+ * @param {object} args.backend Backend with `rawQuery` + `resourcePath`.
+ * @param {string} args.entityType
+ * @param {string} args.bundle
+ * @param {string} args.id
+ * @param {?object} [args.existing]
+ * @param {object} [args.attributes]
+ * @returns {Promise<{probed: boolean, writable?: boolean|string, skipped?: string}>}
+ * @throws {PatchBlockedError} When the guard rejects the probe.
+ */
+export async function preflightPatchWritable({
+  backend, entityType, bundle, id, existing, attributes,
+}) {
+  if (!shouldPreflightPatch({ existing, attributes })) {
+    return { probed: false };
+  }
+  if (typeof backend?.rawQuery !== "function" || typeof backend?.resourcePath !== "function") {
+    return { probed: false, skipped: "backend cannot issue a raw PATCH probe" };
+  }
+  const path = `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+  const type = `${entityType}--${bundle}`;
+  const probeId = id === PATCH_PROBE_MISMATCH_ID
+    ? "00000000-0000-4000-a000-000000000002"
+    : PATCH_PROBE_MISMATCH_ID;
+  try {
+    await backend.rawQuery({
+      path,
+      options: {
+        method: "PATCH",
+        body: JSON.stringify({ data: { type, id: probeId } }),
+      },
+    });
+    throw new Error(
+      "PATCH probe unexpectedly succeeded (2xx). The probe must fail after " +
+      "core's working-copy guard so no revision is written."
+    );
+  } catch (err) {
+    if (isWorkingCopyPatchError(err)) {
+      throw new PatchBlockedError(err instanceof Error ? err : new Error(String(err)));
+    }
+    if (isProbePassedWithoutSave(err)) {
+      return { probed: true, writable: true };
+    }
+    throw err;
+  }
+}
+
+/**
+ * `backend.updateEntity` with the core working-copy 400 rewritten.
+ * @param {object} backend
+ * @param {object} input updateEntity argument.
+ * @returns {Promise<*>}
+ * @throws {PatchBlockedError|*}
+ */
+export async function updateEntityGuarded(backend, input) {
+  try {
+    return await backend.updateEntity(input);
+  } catch (err) {
+    throw rewriteWorkingCopyPatchError(err);
+  }
+}

package/src/lib/principal.js

@@ -0,0 +1,372 @@
+/**
+ * Inbound principal entitlement (#178).
+ *
+ * HTTPS resource-server requests carry a validated JWT identity. Discovery
+ * and invocation are filtered by that identity's server-resolved grants.
+ * Stdio, loopback shared-bearer, and unauthenticated loopback have no
+ * inbound principal and keep the existing site + source-governance filter
+ * so a local operator is not hollowed out.
+ *
+ * Caller-supplied site, environment, tenant, target, or scope fields are
+ * hints. They never become authority. Empty inbound scopes are no grants,
+ * not a wildcard.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getDefaultSiteName, getInboundGrants } from "./config.js";
+import { inferOperation } from "./operations.js";
+import { resolveSecurityConfig, SecurityError } from "./security.js";
+
+const identityStore = new AsyncLocalStorage();
+
+/** Caller fields that look like a target but are never authority. */
+export const TARGET_HINT_KEYS = Object.freeze(["site", "environment", "tenant", "target"]);
+
+/** Always discoverable; they are how an operator sees a denial. */
+export const DIAGNOSTIC_TOOLS = new Set([
+  "drupal_list_sites",
+  "drupal_governance_status",
+]);
+
+const CONFIG_TOOLS = new Set([
+  "drupal_config_get",
+  "drupal_config_list",
+  "drupal_config_set",
+  "drupal_drush_config_export",
+  "drupal_drush_config_import",
+  "drupal_drush_config_status",
+]);
+
+/** inferOperation() leaves these as "read"; they self-gate in-handler. */
+const WRITE_BY_NAME = new Set([
+  "drupal_entity_create",
+  "drupal_entity_update",
+  "drupal_entity_delete",
+]);
+
+const FREE_FORM_TOOLS = new Set([
+  "drupal_graphql",
+  "drupal_graphql_introspect",
+  "drupal_drush_sql_query",
+]);
+
+const WRITE_WORKFLOW_PROMPTS = new Set([
+  "drupal-create-article",
+  "drupal-seo-fix",
+  "drupal-user-cleanup",
+]);
+
+const READ_WORKFLOW_PROMPTS = new Set([
+  "drupal-content-audit",
+  "drupal-full-audit",
+]);
+
+/**
+ * Run `fn` with `identity` as the request principal (null = local operator).
+ * @param {object|null} identity
+ * @param {Function} fn
+ * @returns {*}
+ */
+export function runWithIdentity(identity, fn) {
+  return identityStore.run({ identity: identity ?? null }, fn);
+}
+
+/**
+ * The inbound identity for the current request, or null on stdio / loopback.
+ * @returns {object|null}
+ */
+export function getRequestIdentity() {
+  return identityStore.getStore()?.identity ?? null;
+}
+
+/**
+ * Inbound scope required to discover or invoke a tool. Diagnostics need none.
+ * @param {string} toolName
+ * @returns {string|null}
+ */
+export function requiredScopeForTool(toolName) {
+  if (DIAGNOSTIC_TOOLS.has(toolName)) return null;
+  if (toolName === "drupal_drush_sql_query") return "mcp_admin";
+  if (CONFIG_TOOLS.has(toolName)) return "mcp_config";
+  if (WRITE_BY_NAME.has(toolName)) return "mcp_write";
+  const op = inferOperation(toolName);
+  if (op === "write" || op === "delete") return "mcp_write";
+  return "mcp_read";
+}
+
+/**
+ * @param {object|null} identity
+ * @param {string|null} scope
+ * @returns {boolean}
+ */
+export function principalHasScope(identity, scope) {
+  if (!scope) return true;
+  return (identity?.scopes ?? []).includes(scope);
+}
+
+/**
+ * Site names this principal may address. Unknown names in a grant are dropped.
+ *
+ * @param {object|null} identity
+ * @param {string[]} configuredNames
+ * @param {object|null} [grants] `auth.grants` map; `undefined` reads config.
+ * @returns {string[]}
+ */
+export function resolveGrantedSiteNames(identity, configuredNames, grants) {
+  if (!identity) return [...configuredNames];
+  const known = new Set(configuredNames);
+  const grantMap = grants === undefined ? getInboundGrants() : grants;
+
+  if (grantMap) {
+    const listed = identity.clientId
+      ? new Map(Object.entries(grantMap)).get(identity.clientId)
+      : undefined;
+    if (!Array.isArray(listed)) return [];
+    return listed.map(String).filter((name) => known.has(name));
+  }
+
+  if (Array.isArray(identity.sites)) {
+    return identity.sites.map(String).filter((name) => known.has(name));
+  }
+
+  return [...configuredNames];
+}
+
+/**
+ * @param {object|null} identity
+ * @param {Array<{_name: string}>} sites
+ * @param {object|null} [grants]
+ * @returns {Array<object>}
+ */
+export function resolveGrantedSites(identity, sites, grants) {
+  const allowed = new Set(
+    resolveGrantedSiteNames(identity, sites.map((site) => site._name), grants),
+  );
+  return sites.filter((site) => allowed.has(site._name));
+}
+
+/**
+ * @param {object} site
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+function siteAllowsTool(site, toolName) {
+  const sec = resolveSecurityConfig(site);
+  if (toolName === "drupal_graphql" || toolName === "drupal_graphql_introspect") {
+    return Boolean(sec.allowGraphql);
+  }
+  if (toolName === "drupal_drush_sql_query") {
+    return site.drushSsh?.rawSql === "governed";
+  }
+  if (toolName === "drupal_config_set") {
+    return Boolean(sec.allowConfigWrite) && !sec.readOnly;
+  }
+  if (toolName === "drupal_config_get" || toolName === "drupal_config_list") {
+    return Boolean(sec.allowConfigRead);
+  }
+  const op = inferOperation(toolName);
+  const writeLike = op === "write" || op === "delete" || WRITE_BY_NAME.has(toolName);
+  if (writeLike && sec.readOnly) return false;
+  if ((op === "delete" || toolName === "drupal_entity_delete") && !sec.allowDestructive) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * @param {string} toolName
+ * @param {object|null} identity
+ * @param {Array<object>} sites
+ * @param {object|null} [grants]
+ * @returns {boolean}
+ */
+export function principalMayUseTool(toolName, identity, sites, grants) {
+  if (!identity) return true;
+  if (DIAGNOSTIC_TOOLS.has(toolName)) return true;
+  if (!principalHasScope(identity, requiredScopeForTool(toolName))) return false;
+  const entitled = resolveGrantedSites(identity, sites, grants);
+  if (!entitled.length) return false;
+  if (FREE_FORM_TOOLS.has(toolName)) {
+    return entitled.some((site) => siteAllowsTool(site, toolName));
+  }
+  return entitled.some((site) => siteAllowsTool(site, toolName));
+}
+
+/**
+ * @param {Array<{name: string}>} definitions
+ * @param {Array<object>} sites
+ * @param {object|null} identity
+ * @param {object|null} [grants]
+ * @returns {Array<object>}
+ */
+export function filterToolsByPrincipal(definitions, sites, identity, grants) {
+  if (!identity) return definitions;
+  return definitions.filter((definition) =>
+    principalMayUseTool(definition.name, identity, sites, grants));
+}
+
+/**
+ * @param {object} [args]
+ * @returns {Array<{key: string, value: string}>}
+ */
+export function callerTargetHints(args = {}) {
+  const found = [];
+  for (const key of TARGET_HINT_KEYS) {
+    const value = new Map(Object.entries(args ?? {})).get(key);
+    if (typeof value === "string" && value.trim()) {
+      found.push({ key, value: value.trim() });
+    }
+  }
+  return found;
+}
+
+/**
+ * @param {object} site
+ * @param {string} source
+ * @returns {{name: string, baseUrl?: string, source: string}}
+ */
+export function describeTarget(site, source) {
+  return {
+    name: site._name,
+    baseUrl: site.baseUrl,
+    source,
+  };
+}
+
+/**
+ * Public site list for tools/resources. Never includes credentials.
+ *
+ * @param {object|null} identity
+ * @param {Array<object>} resolvable
+ * @param {string[]} configuredNames
+ * @param {object|null} [grants]
+ * @returns {{sites: string[], targets: Array<{name: string, baseUrl?: string, source: string}>}}
+ */
+export function visibleSiteTargets(identity, resolvable, configuredNames, grants) {
+  const granted = identity ? resolveGrantedSites(identity, resolvable, grants) : resolvable;
+  const names = identity
+    ? granted.map((site) => site._name)
+    : [...configuredNames];
+  const byName = new Map(granted.map((site) => [site._name, site]));
+  const source = identity ? "grant" : "config";
+  return {
+    sites: names,
+    targets: names.map((name) => {
+      const site = byName.get(name);
+      return site ? describeTarget(site, source) : { name, source };
+    }),
+  };
+}
+
+/**
+ * Resolve the site this principal may use for a call.
+ *
+ * @param {object} args
+ * @param {object} identity
+ * @param {Array<object>} sites
+ * @param {{grants?: object|null, defaultSite?: string}} [options]
+ * @returns {{site: object, source: string, name: string}}
+ * @throws {SecurityError}
+ */
+export function resolveAuthoritativeTarget(args, identity, sites, options = {}) {
+  const grantMap = options.grants === undefined ? getInboundGrants() : options.grants;
+  const entitled = resolveGrantedSites(identity, sites, grantMap);
+  const hints = callerTargetHints(args);
+  const unique = [...new Set(hints.map((hint) => hint.value))];
+
+  if (unique.length > 1) {
+    throw new SecurityError(
+      "Conflicting caller target hints do not select a single granted target.",
+    );
+  }
+
+  if (unique.length === 1) {
+    const site = entitled.find((entry) => entry._name === unique[0]);
+    if (!site) {
+      throw new SecurityError("Not entitled to the requested target.");
+    }
+    return { site, source: "hint", name: site._name };
+  }
+
+  const defaultName = options.defaultSite ?? getDefaultSiteName();
+  const fromDefault = entitled.find((entry) => entry._name === defaultName);
+  if (fromDefault) {
+    return { site: fromDefault, source: "default", name: fromDefault._name };
+  }
+  if (entitled.length === 1) {
+    return { site: entitled[0], source: "grant", name: entitled[0]._name };
+  }
+
+  throw new SecurityError(
+    entitled.length
+      ? "No authoritative target could be resolved from the principal grant."
+      : "Principal is not entitled to any configured target.",
+  );
+}
+
+/**
+ * Deny unauthorized invocation. Returns the resolved target, or null for
+ * tools that do not address a site.
+ *
+ * @param {object} params
+ * @returns {{site: object, source: string, name: string}|null}
+ * @throws {SecurityError}
+ */
+export function assertPrincipalEntitlement({
+  toolName,
+  args,
+  identity,
+  sites,
+  grants,
+  defaultSite,
+}) {
+  if (!identity) return null;
+  if (!principalMayUseTool(toolName, identity, sites, grants)) {
+    throw new SecurityError(`Not entitled to invoke ${toolName}.`);
+  }
+  // list_sites has no target. governance_status without a hint reports every
+  // granted site — pinning it to the default would hide the rest.
+  if (toolName === "drupal_list_sites") return null;
+  if (toolName === "drupal_governance_status" && callerTargetHints(args).length === 0) {
+    return null;
+  }
+  return resolveAuthoritativeTarget(args, identity, sites, { grants, defaultSite });
+}
+
+/**
+ * @param {Array<object>} resources
+ * @param {object|null} identity
+ * @param {Array<object>} sites
+ * @param {object|null} [grants]
+ * @returns {Array<object>}
+ */
+export function filterResourcesByPrincipal(resources, identity, sites, grants) {
+  if (!identity) return resources;
+  const entitled = resolveGrantedSites(identity, sites, grants);
+  const canRead = principalHasScope(identity, "mcp_read") && entitled.length > 0;
+  return resources.filter((resource) => {
+    if (resource.uri === "drupal://sites") return true;
+    return canRead;
+  });
+}
+
+/**
+ * @param {Array<object>} prompts
+ * @param {object|null} identity
+ * @param {Array<{name: string}>} visibleTools
+ * @returns {Array<object>}
+ */
+export function filterPromptsByPrincipal(prompts, identity, visibleTools) {
+  if (!identity) return prompts;
+  const visible = new Set((visibleTools ?? []).map((tool) => tool.name));
+  return prompts.filter((prompt) => {
+    if (WRITE_WORKFLOW_PROMPTS.has(prompt.name)) {
+      return principalHasScope(identity, "mcp_write");
+    }
+    if (READ_WORKFLOW_PROMPTS.has(prompt.name)) {
+      return principalHasScope(identity, "mcp_read");
+    }
+    const toolName = prompt.name.replace(/-/g, "_");
+    return visible.has(toolName);
+  });
+}