drupal-mcp-connector 2.7.3 → 2.7.4

package/.claude/commands/drupal-update-menu-link.md

@@ -14,7 +14,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Menu link UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `title` (string): New link label. Omit to leave unchanged.
 - `link` (string): New target URI (e.g. 'entity:node/42'). Omit to leave unchanged.
 - `menu` (string): Move the link to this menu. Omit to leave unchanged.

package/.claude/commands/drupal-update-node.md

@@ -15,7 +15,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Node UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `title` (string)
 - `body` (string)
 - `summary` (string): Body summary/teaser — writes the `summary` property of the body field (core `text_with_summary`). Many headless sites instead use a dedicated summary/deck field for teasers and meta descriptions; on those, set that field in `fields` — a value written here will be stored but may never be rendered.

package/.claude/commands/drupal-update-paragraph.md

@@ -15,7 +15,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Paragraph UUID
 
 **Optional:**
-- `site` (string): Named site (omit for default)
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `attributes` (object (pass as JSON)): Paragraph field values to change, keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }
 
 If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.claude/commands/drupal-update-redirect.md

@@ -14,7 +14,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Redirect entity UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `source` (string): New source/old path (leading slash optional). Omit to leave unchanged.
 - `target` (string): New destination path/URI. Omit to leave unchanged.
 - `statusCode` (number): New HTTP redirect status code (301/302/303/307/308). Omit to leave unchanged.

package/.claude/commands/drupal-update-taxonomy-term.md

@@ -15,7 +15,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string)
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `name` (string)
 - `description` (string)
 - `weight` (number)

package/.claude/commands/drupal-update-user.md

@@ -14,7 +14,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): User UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `name` (string)
 - `mail` (string)
 - `password` (string)

package/.claude/commands/drupal-upload-file-and-create-media.md

@@ -16,7 +16,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `fieldName` (string): Source field machine name, e.g. 'field_media_image'
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `mediaName` (string): Name for the media entity (defaults to filename)
 - `altText` (string): Alt text for image media
 - `status` (boolean (true/false)): Published flag. Defaults to false. Requires allowPublish when true.

package/.claude/commands/drupal-upload-file.md

@@ -16,7 +16,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `fieldName` (string): Field machine name, e.g. 'field_media_image', 'field_image'
 
 **Optional:**
-- `site` (string): omit for the default site
+- `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `entityType` (string): Drupal entity type (usually 'media' or 'node')
 
 If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.4] - 2026-08-18
+
+### Fixed
+- **`drupal_content_by_moderation_state` no longer 500s on stock JSON:API
+  (#162).** `moderation_state` is a computed field and is not filterable
+  over core JSON:API. The tool still tries the server-side filter (so a
+  jsonapi_extras alias keeps working), and when Drupal rejects it the
+  connector samples recent nodes and filters client-side. The payload
+  reports `source: "sampled"` and `approximate` instead of a raw Drupal
+  500. If the field is not exposed at all, the result is a gated
+  `unavailable` payload.
+- **Every tool response names the resolved site (#167).** Omitting `site`
+  still defaults to `defaultSite`, but the payload now carries
+  `_target: { name, baseUrl, source }` — the same block `drupal_mcp_whoami`
+  already returned as `target`. `source` is `hint` when the caller named a
+  site, `default` when the configured default was used, or `grant` when a
+  principal had exactly one entitled site. A list_nodes-shaped success with
+  only `_backend` is no longer claimable as production. Writes (including
+  GraphQL mutations and generic `drupal_entity_*` writes) refuse a silent
+  default when more than one site is configured; a write on the wrong site
+  is not recoverable. Single-site configs are unchanged. Array-shaped
+  results are wrapped as `{ items, _target }` so the field survives
+  `JSON.stringify`.
+
 ## [2.7.3] - 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.3** (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.4** (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).
 
 ---
 
@@ -44,6 +44,7 @@ Each site declares which backend(s) it exposes via the `api` key:
 - **`api` accepts** `"jsonapi"`, `"graphql"`, or a priority array like `["graphql","jsonapi"]`. Omit it to **auto-detect** (the connector probes both once and caches the result).
 - **One canonical shape.** Both backends return entities as
   `{ id, entityType, bundle, title, status, langcode, created, changed, url, fields, relationships, _backend }`, so tool output is identical regardless of protocol.
+  Every site-addressing response also includes `_target: { name, baseUrl, source }` so a defaulted call cannot be mistaken for another environment.
 - **Capability-aware.** Each backend advertises what it supports (read, write, delete, server-side filter/sort, revisions). GraphQL via GraphQL Compose is **read-only** (no mutations) and has no server-side field filter, so filters are applied client-side over a bounded fetch and flagged `approximate`/`truncated`. Write tools against a read-only backend return a clear capability error rather than failing silently.
 - **Writes go through JSON:API.** Use a JSON:API-enabled site as the write plane; keep GraphQL as a read plane where that suits your architecture.
 - **`defaultTextFormat` sets the body text format** used by the `body` convenience

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.7.3",
+  "version": "2.7.4",
   "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/dispatch.js

@@ -16,7 +16,10 @@ import { toolError, toolResult } from "./errors.js";
 import { BackendCapabilityError, BackendResolutionError } from "./backends/errors.js";
 import { inferOperation } from "./operations.js";
 import { assertSourceGovernance, GovernanceError, GOVERNANCE_DIAGNOSTIC_TOOLS } from "./governance.js";
-import { assertPrincipalEntitlement, getRequestIdentity } from "./principal.js";
+import {
+  assertPrincipalEntitlement, callerTargetHints, getRequestIdentity,
+} from "./principal.js";
+import { assertExplicitSiteForWrite, withResolvedTarget } from "./site-target.js";
 import { allHandlers } from "../tools/index.js";
 
 /**
@@ -39,6 +42,47 @@ export function listResolvableSiteConfigs() {
   });
 }
 
+/**
+ * Resolve which site this call addresses and how that name was chosen.
+ * Returns null for tools that do not address a single site (`list_sites`,
+ * unscoped `governance_status`).
+ *
+ * @param {string} toolName
+ * @param {object} rawArgs Caller arguments before any rewrite.
+ * @param {object} [context]
+ * @returns {?{site: object, source: string, name: string}}
+ * @throws {SecurityError}
+ */
+export function resolveCallTarget(toolName, rawArgs, context = {}) {
+  if (toolName === "drupal_list_sites") return null;
+  if (toolName === "drupal_governance_status" && callerTargetHints(rawArgs).length === 0) {
+    return null;
+  }
+
+  const identity = context.identity !== undefined ? context.identity : getRequestIdentity();
+  if (identity) {
+    return assertPrincipalEntitlement({
+      toolName,
+      args: rawArgs,
+      identity,
+      sites: context.sites ?? listResolvableSiteConfigs(),
+      grants: context.grants,
+      defaultSite: context.defaultSite,
+    });
+  }
+
+  const hints = callerTargetHints(rawArgs);
+  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 target.",
+    );
+  }
+  const source = unique.length === 1 ? "hint" : "default";
+  const site = getSiteConfig(unique[0]);
+  return { site, source, name: site._name };
+}
+
 /**
  * Derive the entity type a tool acts on, for destructive-allow assertions.
  *
@@ -72,18 +116,21 @@ export async function securityMiddleware(toolName, args, handler, context = {})
   const identity = context.identity !== undefined ? context.identity : getRequestIdentity();
   let nextArgs = rawArgs;
 
-  if (identity) {
-    const resolved = assertPrincipalEntitlement({
-      toolName,
-      args: rawArgs,
-      identity,
-      sites: context.sites ?? listResolvableSiteConfigs(),
-      grants: context.grants,
-      defaultSite: context.defaultSite,
-    });
-    if (resolved) {
-      nextArgs = { ...rawArgs, site: resolved.name };
-    }
+  const resolved = resolveCallTarget(toolName, rawArgs, { ...context, identity });
+  if (context && typeof context === "object") {
+    context.resolvedTarget = resolved;
+  }
+  assertExplicitSiteForWrite(
+    toolName,
+    rawArgs,
+    resolved,
+    context.siteNames ?? listSiteNames(),
+  );
+
+  if (resolved) {
+    // Authoritative name plus the real source. Injecting `site` alone would
+    // make whoami report source:"hint" for a defaulted call (#167 / identity path).
+    nextArgs = { ...rawArgs, site: resolved.name, _resolvedSource: resolved.source };
   }
 
   // Tools with no site context skip per-site checks. governance_status
@@ -137,8 +184,9 @@ export async function callTool(name, args, context = {}) {
   }
 
   try {
-    const result = await securityMiddleware(name, args ?? {}, handler, context);
-    return toolResult(result);
+    const ctx = { ...context };
+    const result = await securityMiddleware(name, args ?? {}, handler, ctx);
+    return toolResult(withResolvedTarget(result, ctx.resolvedTarget));
   } catch (err) {
     // Translate known error classes into clear, non-leaky isError responses;
     // anything else falls through to toolError for a generic envelope.

package/src/lib/operations.js

@@ -10,6 +10,8 @@
  * warnings surfaced to users can never drift apart.
  */
 
+import { graphqlHasMutation } from "./security.js";
+
 export const WRITE_PREFIXES = ["drupal_create_", "drupal_update_", "drupal_upload_",
   "drupal_block_",  "drupal_drush_cache", "drupal_drush_cron",
   "drupal_drush_config_export", "drupal_drush_config_import",
@@ -39,8 +41,13 @@ export function inferOperation(toolName) {
 // Generic entity tools carry their target type/bundle in ARGS, not the tool name,
 // so the security middleware gates them inside their handlers (assertDeleteAllowed /
 // assertWriteAllowed with full context) and inferOperation() intentionally leaves
-// them classified "read". For the user-facing confirm-first WARNING, though, we
-// still want the destructive hint to show, so classify them by name here.
+// them classified "read". Write-site gating and the user-facing confirm-first
+// WARNING still classify them by name.
+const ENTITY_WRITE_TOOLS = new Set([
+  "drupal_entity_create",
+  "drupal_entity_update",
+  "drupal_entity_delete",
+]);
 const DESTRUCTIVE_ENTITY_TOOLS = new Set(["drupal_entity_delete"]);
 
 /**
@@ -55,3 +62,33 @@ const DESTRUCTIVE_ENTITY_TOOLS = new Set(["drupal_entity_delete"]);
 export function isDestructiveTool(toolName) {
   return inferOperation(toolName) === "delete" || DESTRUCTIVE_ENTITY_TOOLS.has(toolName);
 }
+
+/**
+ * Whether a tool is a write or delete regardless of how inferOperation classifies it.
+ * Covers the generic `drupal_entity_{create,update,delete}` tools that self-gate
+ * inside their handlers and are therefore left as "read" by prefix inference.
+ *
+ * @param {string} toolName - The MCP tool name.
+ * @returns {boolean}
+ */
+export function isWriteLikeTool(toolName) {
+  if (ENTITY_WRITE_TOOLS.has(toolName)) return true;
+  const op = inferOperation(toolName);
+  return op === "write" || op === "delete";
+}
+
+/**
+ * Whether this invocation mutates the target. GraphQL is a write only when the
+ * document contains a mutation; a query is still a read.
+ *
+ * @param {string} toolName
+ * @param {object} [args]
+ * @returns {boolean}
+ */
+export function isWriteLikeCall(toolName, args = {}) {
+  if (isWriteLikeTool(toolName)) return true;
+  if (inferOperation(toolName) === "graphql" && typeof args.query === "string") {
+    return graphqlHasMutation(args.query);
+  }
+  return false;
+}

package/src/lib/security.js

@@ -470,7 +470,7 @@ export function assertPublishAllowed(secConfig, attributes = {}) {
  * @param {string} query GraphQL document text.
  * @returns {boolean} True if any operation is a mutation.
  */
-function graphqlHasMutation(query) {
+export function graphqlHasMutation(query) {
   try {
     const doc = parse(query);
     return doc.definitions.some(

package/src/lib/site-target.js

@@ -0,0 +1,78 @@
+/**
+ * Resolved-target disclosure and the multi-site write guard (#167).
+ *
+ * A silent default that returns plausible content from the wrong environment
+ * is the failure class: the response looks like success and every field a
+ * caller would sanity-check (id, title, url) is correct. `_target` uses the
+ * same `{ name, baseUrl, source }` block as `drupal_mcp_whoami` so there is
+ * one vocabulary. `source` is load-bearing — `hint` when the caller named a
+ * target, `default` when `defaultSite` was used, `grant` when a principal
+ * had exactly one entitled site.
+ *
+ * Reads may still default. Writes (and GraphQL mutations) may not when more
+ * than one site is configured: a write on the wrong site is not recoverable.
+ */
+
+import { describeTarget } from "./principal.js";
+import { isWriteLikeCall } from "./operations.js";
+import { SecurityError } from "./security.js";
+
+/** Shared `site` argument schema. Injected onto every tool that accepts `site`. */
+export const SITE_PARAM = {
+  type: "string",
+  description:
+    "Named site from connector config. Omit only on reads: multi-site configs " +
+    "fall back to defaultSite (often local/dev, not production). Writes require " +
+    "an explicit site when more than one site is configured. Every response " +
+    "includes `_target` { name, baseUrl, source } (`hint` when you passed site, " +
+    "`default` when you did not).",
+};
+
+/**
+ * Attach the resolved target to a tool payload so JSON.stringify keeps it.
+ *
+ * Object results get `_target` as a sibling. Arrays are wrapped as
+ * `{ items, _target }` because extra properties on an array are dropped by
+ * JSON.stringify. Tools that do not address a single site pass `resolved` as
+ * null and are returned unchanged.
+ *
+ * @param {*} result Handler return value.
+ * @param {?{site: object, source: string}} resolved
+ * @returns {*}
+ */
+export function withResolvedTarget(result, resolved) {
+  if (!resolved?.site) return result;
+  const _target = describeTarget(resolved.site, resolved.source);
+  if (result && typeof result === "object" && !Array.isArray(result)) {
+    return { ...result, _target };
+  }
+  if (Array.isArray(result)) {
+    return { items: result, _target };
+  }
+  if (result === undefined || result === null) {
+    return { _target };
+  }
+  return { result, _target };
+}
+
+/**
+ * Refuse a write that would silently land on defaultSite when more than one
+ * site is configured. Resolution behaviour for reads is unchanged.
+ *
+ * @param {string} toolName
+ * @param {object} args Raw caller arguments (before any default rewrite).
+ * @param {?{site: object, source: string, name: string}} resolved
+ * @param {string[]} siteNames Configured site names.
+ * @returns {void}
+ * @throws {SecurityError}
+ */
+export function assertExplicitSiteForWrite(toolName, args, resolved, siteNames) {
+  if (!resolved || resolved.source !== "default") return;
+  if (!Array.isArray(siteNames) || siteNames.length < 2) return;
+  if (!isWriteLikeCall(toolName, args)) return;
+  throw new SecurityError(
+    "Write tools require an explicit site when more than one site is configured. " +
+    "Omitted site would default to \"" + resolved.name + "\" (" + resolved.site.baseUrl + "). " +
+    "Pass site explicitly. Configured sites: " + siteNames.join(", ") + ".",
+  );
+}

package/src/lib/tool-prompts.js

@@ -15,6 +15,7 @@
  */
 
 import { 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`. */
 export const toolNameToPromptName = (name) => name.replace(/_/g, "-");
@@ -54,7 +55,7 @@ export function paramList(inputSchema) {
     name,
     required: required.has(name),
     hint: typeHint(spec),
-    description: spec?.description || (name === "site" ? "omit for the default site" : ""),
+    description: spec?.description || (name === "site" ? SITE_PARAM.description : ""),
   }));
 }
 

package/src/tools/config.js

@@ -107,7 +107,7 @@ function inferTier(site, sec) {
  * @param {object} args - { site? }.
  * @returns {Promise<object>} Effective identity + capability summary.
  */
-async function whoami({ site: siteName }) {
+async function whoami({ site: siteName, _resolvedSource }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   const summary = getSecuritySummary(site);
@@ -119,9 +119,12 @@ async function whoami({ site: siteName }) {
   const canWrite  = !sec.readOnly && hasScope(site, "mcp_write");
   const canConfig = hasScope(site, "mcp_config");
   const identity = getRequestIdentity();
+  // Dispatch may inject `site` after a default/grant resolution. Prefer the
+  // authoritative source so `target` and `_target` cannot disagree (#167).
+  const source = _resolvedSource ?? (siteName ? "hint" : "default");
   return {
     site: site._name,
-    target: describeTarget(site, siteName ? "hint" : "default"),
+    target: describeTarget(site, source),
     principal: identity
       ? { sub: identity.sub, clientId: identity.clientId, scopes: [...(identity.scopes ?? [])] }
       : null,

package/src/tools/index.js

@@ -37,14 +37,34 @@ import * as reportsConfig  from "./reports-config.js";
 import * as reportsContent from "./reports-content.js";
 import * as auditComposite from "./audit-composite.js";
 import * as config       from "./config.js";
+import { SITE_PARAM } from "../lib/site-target.js";
 
 export const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
   revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra,
   reportsLinks, reportsConfig, reportsContent, auditComposite, config];
 
+/**
+ * Stamp the shared `site` description onto every tool that accepts one so
+ * agents are not told "omit for the default" as if that meant production.
+ *
+ * @param {object} def Tool definition.
+ * @returns {object}
+ */
+function withSiteParam(def) {
+  const props = def.inputSchema?.properties;
+  if (!props?.site) return def;
+  return {
+    ...def,
+    inputSchema: {
+      ...def.inputSchema,
+      properties: { ...props, site: { ...props.site, ...SITE_PARAM } },
+    },
+  };
+}
+
 // Flatten every module's tool definitions into one ListTools payload, and merge
 // their handler maps into a single closed dispatch table keyed by tool name.
-export const allDefinitions = allModules.flatMap((m) => m.definitions);
+export const allDefinitions = allModules.flatMap((m) => m.definitions).map(withSiteParam);
 export const allHandlers    = Object.assign({}, ...allModules.map((m) => m.handlers));
 
 // Fast name → definition lookup for prompt/command rendering.

package/src/tools/moderation.js

@@ -20,6 +20,25 @@ import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertPublishAllowed,
   redactCanonicalEntity,
 } from "../lib/security.js";
+import { collectEntities } from "../lib/reports-support.js";
+
+/** Cap for the client-side scan when JSON:API cannot filter the field. */
+const SAMPLE_CAP = 500;
+
+/**
+ * Drupal core JSON:API cannot filter on the computed `moderation_state`
+ * field. The error is a 500 whose detail is `'moderation_state' not found`
+ * (#162). jsonapi_extras (or a similar alias) can make the field filterable;
+ * those sites never hit this.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isUnfilterableModerationState(err) {
+  const msg = String(err?.message || "");
+  if (!/moderation_state/i.test(msg)) return false;
+  return /not found/i.test(msg) || /not filterable/i.test(msg) || /invalid filter/i.test(msg);
+}
 
 /** Read a node's moderation_state from a canonical entity, tolerating shapes. */
 function moderationStateOf(entity) {
@@ -49,6 +68,12 @@ async function setModerationState({ site: siteName, type, id, state }) {
 
 /**
  * List nodes of a type in a given moderation state, paged + redacted.
+ *
+ * Stock JSON:API cannot filter on the computed `moderation_state` field
+ * (#162). When the site accepts the filter (jsonapi_extras or similar) the
+ * result is exact. Otherwise we scan a bounded recent set and filter
+ * client-side rather than surfacing Drupal's 500 as a transient error.
+ *
  * @param {object} args - { site?, type, state, limit?, offset? }.
  */
 async function contentByModerationState({ site: siteName, type, state, limit = 20, offset = 0 }) {
@@ -56,14 +81,68 @@ async function contentByModerationState({ site: siteName, type, state, limit = 2
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
-  const res = await backend.listEntities({
-    entityType: "node", bundle: type,
-    filters: [{ field: "moderation_state", op: "eq", value: state }],
-    sort: [{ field: "changed", dir: "desc" }],
-    page: { limit, offset },
-  });
-  const nodes = res.entities.map((e) => redactCanonicalEntity(e, sec, "node"));
-  return { type, state, total: res.page?.total ?? nodes.length, approximate: res.approximate ?? false, offset, nextOffset: offset + nodes.length, nodes };
+  const sort = [{ field: "changed", dir: "desc" }];
+  const canFilter = typeof backend.capabilities === "function"
+    ? Boolean(backend.capabilities()?.filter)
+    : true;
+
+  if (canFilter) {
+    try {
+      const res = await backend.listEntities({
+        entityType: "node", bundle: type,
+        filters: [{ field: "moderation_state", op: "eq", value: state }],
+        sort,
+        page: { limit, offset },
+      });
+      const nodes = res.entities.map((e) => redactCanonicalEntity(e, sec, "node"));
+      return {
+        type, state, source: "filter",
+        total: res.page?.total ?? nodes.length,
+        approximate: res.approximate ?? false,
+        offset, nextOffset: offset + nodes.length, nodes,
+      };
+    } catch (err) {
+      if (!isUnfilterableModerationState(err)) throw err;
+    }
+  }
+
+  const scanned = await collectEntities(
+    backend,
+    { entityType: "node", bundle: type, sort },
+    SAMPLE_CAP,
+  );
+  const wanted = String(state).toLowerCase();
+  const matches = [];
+  let sawState = false;
+  for (const entity of scanned) {
+    const got = moderationStateOf(entity);
+    if (got === null || got === undefined) continue;
+    sawState = true;
+    if (String(got).toLowerCase() === wanted) matches.push(entity);
+  }
+  if (!sawState && scanned.length > 0) {
+    return {
+      type, state, unavailable: true, source: "sampled", scanned: scanned.length,
+      reason:
+        "moderation_state is not filterable over JSON:API on this site (it is a " +
+        "computed field) and no sampled entity exposed the field. Enable " +
+        "content_moderation on the bundle, or expose a filterable alias " +
+        "(jsonapi_extras).",
+    };
+  }
+  const page = matches.slice(offset, offset + limit);
+  return {
+    type, state, source: "sampled",
+    approximate: scanned.length >= SAMPLE_CAP,
+    scanned: scanned.length,
+    total: matches.length,
+    offset, nextOffset: offset + page.length,
+    nodes: page.map((e) => redactCanonicalEntity(e, sec, "node")),
+    note:
+      "Stock JSON:API cannot filter on moderation_state (computed field). " +
+      "Results are a client-side sample of recent nodes, not a complete list. " +
+      "A filterable alias (jsonapi_extras) makes this exact.",
+  };
 }
 
 /**
@@ -101,7 +180,7 @@ export const definitions = [
   },
   {
     name: "drupal_content_by_moderation_state",
-    description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review').",
+    description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review'). Stock JSON:API cannot filter the computed moderation_state field; when the site rejects that filter the tool samples recent nodes client-side and marks the result approximate, instead of returning Drupal's 500.",
     inputSchema: {
       type: "object", required: ["type", "state"],
       properties: {