drupal-mcp-connector 2.7.1 → 2.7.2

package/.claude/commands/drupal-governance-status.md

@@ -1,12 +1,12 @@
 ---
-description: "Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial."
+description: "Report each configured site's source-governance condition. Always probes GET /drupal-mcp/readiness (even when this client does not require governance) and surfaces the server's reason verbatim. Never reports ok:true unless that check ran. Callable even while governed paths are denied — this is the diagnostic for that denial."
 argument-hint: "[site]"
 allowed-tools: mcp__drupal__drupal_governance_status
 ---
 
 Call the `mcp__drupal__drupal_governance_status` MCP tool.
 
-Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial.
+Report each configured site's source-governance condition. Always probes GET /drupal-mcp/readiness (even when this client does not require governance) and surfaces the server's reason verbatim. Never reports ok:true unless that check ran. Callable even while governed paths are denied — this is the diagnostic for that denial.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/.claude/commands/drupal-report-orphaned-references.md

@@ -1,12 +1,12 @@
 ---
-description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. Flags 'approximate' when sampling-bounded."
+description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. A 404 (or unaddressable ref) is an orphan; 401/403 and connector policy denials are counted as unverifiable, not missing. uid/revision_uid are skipped when the policy denies user. Flags 'approximate' when sampling-bounded."
 argument-hint: "[site] [type] [sampleSize]"
 allowed-tools: mcp__drupal__drupal_report_orphaned_references
 ---
 
 Call the `mcp__drupal__drupal_report_orphaned_references` MCP tool.
 
-Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. Flags 'approximate' when sampling-bounded.
+Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. A 404 (or unaddressable ref) is an orphan; 401/403 and connector policy denials are counted as unverifiable, not missing. uid/revision_uid are skipped when the policy denies user. Flags 'approximate' when sampling-bounded.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.2] - 2026-08-18
+
+### Fixed
+- **Orphan-reference report no longer treats 403 / policy denial as a missing
+  target (#205).** `drupal_report_orphaned_references` used to count any
+  non-OK probe as an orphan. On a site whose policy denies `user`, every
+  `uid` / `revision_uid` became a false finding — 64 "orphans" across 32
+  healthy nodes in the report that produced this issue. Only a 404 (or an
+  unaddressable ref) is an orphan. Denied targets are a third state:
+  `unverifiable` plus `reason: "target entity type denied by policy"`.
+  Author base fields are skipped when the policy denies `user`, so the
+  auditor presets stop manufacturing corruption.
+- **PATCH-blocked message names a pending draft when one is visible
+  (#201 follow-up).** The preflight added in 2.7.1 always said the blocking
+  row was invisible and needed revision surgery. That is right for a stray
+  revision with no content_moderation working copy, and wrong for an
+  ordinary open draft — the common case, and the dangerous advice. The
+  preflight now loads `rel:working-copy`: if it resolves, the error is
+  "This node has a pending draft (vid N). Publish or discard it before a
+  canonical PATCH." Surgery is mentioned only when the working copy does
+  not resolve and the guard still fires.
+- **`drupal_governance_status` no longer reports `ok: true` without a
+  check (#208).** When the client did not set `requireGovernance`, the
+  diagnostic skipped the readiness probe and returned
+  `{ required: false, ok: true, checkedAt: null }` while the same site
+  503'd every governed request with `designated_consumer_disabled`. It
+  now always probes `GET /drupal-mcp/readiness`, sets `checked: true` and
+  `checkedAt`, and surfaces the server's reason verbatim. `ok: true` only
+  after that check. Unresolved site configs report `checked: false` and
+  omit `checkedAt`.
+
 ## [2.7.1] - 2026-08-18
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 
 Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
-**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.1** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
+**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.2** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/governance.js

@@ -162,20 +162,23 @@ export async function assertSourceGovernance(site) {
 
 /**
  * Per-site governance condition for operator diagnostics. No secrets: only
- * the site name, whether governance is required, the verdict, and the reason.
+ * the site name, whether this client requires governance, whether the
+ * readiness endpoint was probed, the verdict, and the server's reason.
+ *
+ * Always probes `GET /drupal-mcp/readiness`, even when `requireGovernance`
+ * is off — the server may still refuse governed paths (#208). Never reports
+ * `ok: true` without a check.
  *
  * @param {Array<object>} sites Resolved site configs.
- * @returns {Promise<Array<{site: string, required: boolean, ok: boolean, reason: string|null, checkedAt: number|null}>>}
+ * @returns {Promise<Array<{site: string, required: boolean, checked: boolean, ok: boolean, reason: string|null, checkedAt: number}>>}
  */
 export async function governanceStatus(sites) {
   return Promise.all(sites.map(async (site) => {
-    if (!requiresGovernance(site)) {
-      return { site: site._name, required: false, ok: true, reason: null, checkedAt: null };
-    }
     const result = await verifySourceGovernance(site);
     return {
       site: site._name,
-      required: true,
+      required: requiresGovernance(site),
+      checked: true,
       ok: result.ok,
       reason: result.reason,
       checkedAt: result.checkedAt,

package/src/lib/patch-preflight.js

@@ -28,8 +28,8 @@ 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.
+ * Actionable replacement for core's "has a working copy" 400 when no
+ * content_moderation working copy is addressable — a stray revision row.
  */
 export const PATCH_BLOCKED_MESSAGE =
   "This entity cannot be updated over JSON:API because the stored entity is not " +
@@ -38,15 +38,58 @@ export const PATCH_BLOCKED_MESSAGE =
   "Clearing it requires revision surgery outside JSON:API (Drush / the entity API). " +
   "See connector #201. Do not retry the same canonical PATCH.";
 
+/**
+ * Read a revision id off a working-copy body (canonical or raw-ish).
+ * @param {?object} workingCopy
+ * @returns {?number|string}
+ */
+function workingCopyVid(workingCopy) {
+  if (!workingCopy || typeof workingCopy !== "object") return null;
+  const fields = workingCopy.fields && typeof workingCopy.fields === "object"
+    ? workingCopy.fields
+    : {};
+  const attrs = workingCopy.attributes && typeof workingCopy.attributes === "object"
+    ? workingCopy.attributes
+    : {};
+  const raw = workingCopy.vid
+    ?? fields.drupal_internal__vid
+    ?? attrs.drupal_internal__vid
+    ?? workingCopy.drupal_internal__vid;
+  if (raw === undefined || raw === null || raw === "") return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
+}
+
+/**
+ * Operator message for a core working-copy 400.
+ * A resolvable working copy is an ordinary pending draft — do not prescribe
+ * revision surgery. Surgery is only for the invisible-row case (#201 follow-up).
+ * @param {?object} [workingCopy]
+ * @returns {string}
+ */
+export function patchBlockedMessage(workingCopy) {
+  if (workingCopy) {
+    const vid = workingCopyVid(workingCopy);
+    const which = vid !== null && vid !== undefined ? ` (vid ${vid})` : "";
+    return `This node has a pending draft${which}. Publish or discard it `
+      + "before a canonical PATCH.";
+  }
+  return PATCH_BLOCKED_MESSAGE;
+}
+
 /**
  * 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);
+  /**
+   * @param {?Error} [cause] The original Drupal 400.
+   * @param {{workingCopy?: ?object}} [options]
+   */
+  constructor(cause, { workingCopy } = {}) {
+    super(patchBlockedMessage(workingCopy ?? null));
     this.name = "PatchBlockedError";
     this.code = PATCH_BLOCKED_CODE;
+    if (workingCopy) this.workingCopyVid = workingCopyVid(workingCopy);
     if (cause) this.cause = cause;
   }
 }
@@ -62,13 +105,36 @@ export function isWorkingCopyPatchError(err) {
 
 /**
  * Rewrite a core working-copy 400 into {@link PatchBlockedError}; otherwise
- * return the original value.
+ * return the original value. Pass `workingCopy` when the pending draft is
+ * addressable so the message does not prescribe revision surgery.
  * @param {unknown} err
+ * @param {{workingCopy?: ?object}} [options]
  * @returns {unknown}
  */
-export function rewriteWorkingCopyPatchError(err) {
+export function rewriteWorkingCopyPatchError(err, { workingCopy } = {}) {
   if (!isWorkingCopyPatchError(err)) return err;
-  return new PatchBlockedError(err instanceof Error ? err : new Error(String(err)));
+  return new PatchBlockedError(
+    err instanceof Error ? err : new Error(String(err)),
+    { workingCopy },
+  );
+}
+
+/**
+ * Load `rel:working-copy` so a blocked PATCH can name a pending draft.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string}} ref
+ * @returns {Promise<?object>}
+ */
+async function loadWorkingCopy(backend, { entityType, bundle, id }) {
+  if (typeof backend?.getEntity !== "function") return null;
+  try {
+    const wc = await backend.getEntity({
+      entityType, bundle, id, resourceVersion: "rel:working-copy",
+    });
+    return wc || null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -151,7 +217,11 @@ export async function preflightPatchWritable({
     );
   } catch (err) {
     if (isWorkingCopyPatchError(err)) {
-      throw new PatchBlockedError(err instanceof Error ? err : new Error(String(err)));
+      const workingCopy = await loadWorkingCopy(backend, { entityType, bundle, id });
+      throw new PatchBlockedError(
+        err instanceof Error ? err : new Error(String(err)),
+        { workingCopy },
+      );
     }
     if (isProbePassedWithoutSave(err)) {
       return { probed: true, writable: true };
@@ -171,6 +241,8 @@ export async function updateEntityGuarded(backend, input) {
   try {
     return await backend.updateEntity(input);
   } catch (err) {
-    throw rewriteWorkingCopyPatchError(err);
+    if (!isWorkingCopyPatchError(err)) throw err;
+    const workingCopy = await loadWorkingCopy(backend, input);
+    throw rewriteWorkingCopyPatchError(err, { workingCopy });
   }
 }

package/src/tools/reports-extra.js

@@ -12,9 +12,49 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
-import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
+import { resolveSecurityConfig, assertReadAllowed, assertEntityTypeAllowed } from "../lib/security.js";
 import { collectEntities, fieldValue } from "../lib/reports-support.js";
 
+/** Author base fields that only ever point at `user`. */
+const AUTHOR_BASE_FIELDS = new Set(["uid", "revision_uid"]);
+
+const POLICY_DENIED_REASON = "target entity type denied by policy";
+const ACCESS_DENIED_REASON = "target access denied";
+const UNVERIFIED_REASON = "target could not be verified";
+
+/**
+ * Whether connector policy forbids reading this entity type.
+ * @param {object} sec Resolved security config.
+ * @param {string} entityType Entity type machine name.
+ * @returns {boolean}
+ */
+function isEntityTypeDenied(sec, entityType) {
+  if (!entityType) return false;
+  try {
+    assertEntityTypeAllowed(sec, entityType);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Classify a getEntity failure. Only a 404 (or an unaddressable ref) is an
+ * orphan. Connector policy, Drupal 401/403, and other failures are
+ * unverifiable — and must not share one reason.
+ * @param {unknown} err
+ * @returns {"missing"|"forbidden"|"failed"}
+ */
+function classifyTargetError(err) {
+  const msg = String(err?.message || err || "");
+  const statusMatch = msg.match(/\bDrupal (\d{3})\b/i);
+  const status = statusMatch ? Number(statusMatch[1]) : NaN;
+  if (status === 404) return "missing";
+  if (status === 401 || status === 403) return "forbidden";
+  if (/\b404\b/.test(msg) && !/\b40[13]\b/.test(msg)) return "missing";
+  return "failed";
+}
+
 /**
  * Determine whether a canonical field/relationship value counts as "empty".
  * Handles scalars, JSON:API value-objects ({value}), arrays, and relationship
@@ -161,9 +201,9 @@ async function missingField({ site: siteName, type, field, sampleSize = 100 }) {
 /**
  * Orphaned entity references: sampled entities whose entity-reference fields
  * point at targets that no longer exist. Best-effort — each distinct referenced
- * target is probed once via getEntity; a null result or a fetch error is treated
- * as an unresolved (orphaned) target. Sampling-bounded, so `approximate` is set
- * when the entity scan is capped.
+ * target is probed once via getEntity. Only a 404 / unaddressable ref is an
+ * orphan; 401/403 and connector policy denials are unverifiable (#205).
+ * Sampling-bounded, so `approximate` is set when the entity scan is capped.
  *
  * @param {object} args - { site?, type?, sampleSize? }. `type` defaults to "article".
  * @returns {Promise<object>} Orphaned-reference findings plus scan metadata.
@@ -181,40 +221,56 @@ async function orphanedReferences({ site: siteName, type, sampleSize = 50 }) {
     sampleSize
   );
 
+  const userDenied = isEntityTypeDenied(sec, "user");
+
   // Cache resolution results across all sampled entities so a target is only
   // looked up once (de-dupes both within and across entities).
-  const resolution = new Map(); // id -> boolean (true = exists)
+  const resolution = new Map(); // id -> "ok" | "missing" | "denied" | "forbidden" | "failed"
   /**
-   * Resolve whether a referenced target exists, caching the result.
+   * Resolve a referenced target, caching the classification.
    * @param {{id: string, entityType: ?string, bundle: ?string}} ref Reference to probe.
-   * @returns {Promise<boolean>} True if the target resolves to an entity.
+   * @param {string} fieldName Host field that holds the ref.
+   * @returns {Promise<"ok"|"missing"|"denied"|"forbidden"|"failed">}
    */
-  async function exists(ref) {
+  async function classifyRef(ref, fieldName) {
     if (resolution.has(ref.id)) return resolution.get(ref.id);
-    let ok = false;
+
+    const typeDenied = isEntityTypeDenied(sec, ref.entityType)
+      || (AUTHOR_BASE_FIELDS.has(fieldName) && userDenied);
+    if (typeDenied) {
+      resolution.set(ref.id, "denied");
+      return "denied";
+    }
+
+    if (!ref.entityType || !ref.bundle) {
+      resolution.set(ref.id, "missing");
+      return "missing";
+    }
+
     try {
-      // entityType/bundle are derived from JSON:API "type"; both required to fetch.
-      if (ref.entityType && ref.bundle) {
-        const target = await backend.getEntity({ entityType: ref.entityType, bundle: ref.bundle, id: ref.id });
-        ok = Boolean(target);
-      } else {
-        // Cannot address the target without a concrete type+bundle; treat as
-        // unresolved rather than silently passing.
-        ok = false;
-      }
-    } catch {
-      ok = false;
+      const target = await backend.getEntity({
+        entityType: ref.entityType, bundle: ref.bundle, id: ref.id,
+      });
+      const state = target ? "ok" : "missing";
+      resolution.set(ref.id, state);
+      return state;
+    } catch (err) {
+      const state = classifyTargetError(err);
+      resolution.set(ref.id, state);
+      return state;
     }
-    resolution.set(ref.id, ok);
-    return ok;
   }
 
   const findings = [];
+  let unverifiable = 0;
+  let deniedByPolicy = 0;
+  let accessDenied = 0;
   for (const e of entities) {
     for (const [fieldName, rel] of Object.entries(e.relationships ?? {})) {
       for (const ref of refsOf(rel)) {
-        const ok = await exists(ref);
-        if (!ok) {
+        const state = await classifyRef(ref, fieldName);
+        if (state === "ok") continue;
+        if (state === "missing") {
           findings.push({
             id: e.id,
             title: e.title,
@@ -223,21 +279,34 @@ async function orphanedReferences({ site: siteName, type, sampleSize = 50 }) {
             targetEntityType: ref.entityType,
             targetBundle: ref.bundle,
           });
+          continue;
         }
+        unverifiable += 1;
+        if (state === "denied") deniedByPolicy += 1;
+        if (state === "forbidden") accessDenied += 1;
       }
     }
   }
 
   const approximate = entities.length >= sampleSize;
+  const orphaned = findings.length;
+  let reason;
+  if (deniedByPolicy > 0) reason = POLICY_DENIED_REASON;
+  else if (accessDenied > 0) reason = ACCESS_DENIED_REASON;
+  else if (unverifiable > 0) reason = UNVERIFIED_REASON;
   return {
     contentType,
     scanned: entities.length,
     sampleSize,
     approximate,
-    totalOrphaned: findings.length,
+    orphaned,
+    unverifiable,
+    totalOrphaned: orphaned,
+    reason,
     note: approximate
       ? "Best-effort: reference integrity is checked over a sampling-bounded set of entities."
-      : "Best-effort: each referenced target is probed once via JSON:API.",
+      : "Best-effort: each referenced target is probed once via JSON:API. "
+        + "401/403 and policy-denied types are unverifiable, not orphans.",
     findings,
   };
 }
@@ -274,7 +343,7 @@ export const definitions = [
   },
   {
     name: "drupal_report_orphaned_references",
-    description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. Flags 'approximate' when sampling-bounded.",
+    description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. A 404 (or unaddressable ref) is an orphan; 401/403 and connector policy denials are counted as unverifiable, not missing. uid/revision_uid are skipped when the policy denies user. Flags 'approximate' when sampling-bounded.",
     inputSchema: {
       type: "object",
       properties: {

package/src/tools/site.js

@@ -61,14 +61,6 @@ async function listConfiguredSites() {
   return visibleSiteTargets(getRequestIdentity(), resolvable, names);
 }
 
-/**
- * Per-site source-governance condition (#176). The one governed-path
- * diagnostic that stays callable while governance is failing, so an operator
- * can see WHICH required condition failed. Never includes credentials.
- *
- * @param {object} args - { site? } (a named site narrows the report).
- * @returns {Promise<{sites: object[]}>} required/ok/reason per site.
- */
 /**
  * Classify a getSiteConfig failure so the diagnostic reason matches the cause.
  * @param {string} message
@@ -81,6 +73,14 @@ export function classifySiteResolutionFailure(message) {
   return "site_unresolved";
 }
 
+/**
+ * Per-site source-governance condition (#176, #208). Stays callable while
+ * governed paths are denied. Always probes the source readiness endpoint
+ * for resolved sites; never reports ok:true without that check.
+ *
+ * @param {object} [args] - { site? } (a named site narrows the report).
+ * @returns {Promise<{sites: object[]}>} required/checked/ok/reason per site.
+ */
 async function getGovernanceStatus({ site: siteName } = {}) {
   const identity = getRequestIdentity();
   const configured = listSiteNames();
@@ -96,10 +96,10 @@ async function getGovernanceStatus({ site: siteName } = {}) {
       unresolved.push({
         site: name,
         required: null,
+        checked: false,
         ok: false,
         reason: classifySiteResolutionFailure(detail),
         detail,
-        checkedAt: null,
       });
     }
   }
@@ -129,7 +129,7 @@ export const definitions = [
   },
   {
     name: "drupal_governance_status",
-    description: "Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial.",
+    description: "Report each configured site's source-governance condition. Always probes GET /drupal-mcp/readiness (even when this client does not require governance) and surfaces the server's reason verbatim. Never reports ok:true unless that check ran. Callable even while governed paths are denied — this is the diagnostic for that denial.",
     inputSchema: {
       type: "object",
       properties: { site: { type: "string" } },