drupal-mcp-connector 1.7.0 → 1.8.0

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

@@ -1,12 +1,12 @@
 ---
-description: "Create a new content node. Returns the new node UUID, integer ID, and URL. For content types under an editorial (content_moderation) workflow, set moderationState (e.g. 'draft'/'published') instead of status."
-argument-hint: "<type> <title> [site] [body] [summary] [status] [moderationState] [fields] [dryRun]"
+description: "Create a new content node. Returns the new node UUID, integer ID, and URL. For content types under an editorial (content_moderation) workflow, set moderationState (e.g. 'draft'/'published') instead of status. Entity-reference fields (taxonomy terms, related content, media) go in `relationships`, not `fields`."
+argument-hint: "<type> <title> [site] [body] [summary] [status] [moderationState] [fields] [relationships] [dryRun] [returning]"
 allowed-tools: mcp__drupal__drupal_create_node
 ---
 
 Call the `mcp__drupal__drupal_create_node` MCP tool.
 
-Create a new content node. Returns the new node UUID, integer ID, and URL. For content types under an editorial (content_moderation) workflow, set moderationState (e.g. 'draft'/'published') instead of status.
+Create a new content node. Returns the new node UUID, integer ID, and URL. For content types under an editorial (content_moderation) workflow, set moderationState (e.g. 'draft'/'published') instead of status. Entity-reference fields (taxonomy terms, related content, media) go in `relationships`, not `fields`.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 
@@ -20,7 +20,9 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `summary` (string): Body summary / teaser
 - `status` (boolean (true/false)): Published flag for NON-moderated types. true to publish immediately. Ignored if moderationState is set; on a moderated type it is dropped automatically.
 - `moderationState` (string): Moderation state for content_moderation types, e.g. 'draft' or 'published'. Takes precedence over status.
-- `fields` (object (pass as JSON)): Additional field values keyed by Drupal machine name
+- `fields` (object (pass as JSON)): Scalar/attribute field values keyed by Drupal machine name. Do NOT put entity-reference fields here — Drupal rejects them as attributes; use `relationships`.
+- `relationships` (object (pass as JSON)): Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value: { field_resource_type: { data: { type: 'taxonomy_term--resource_type', id: '<uuid>' } } }. Multi-value: { field_tags: { data: [{ type: 'taxonomy_term--tags', id: '<uuid>' }] } }.
 - `dryRun` (boolean (true/false)): Validate and return a preview of the write without committing.
+- `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 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-describe-fields.md

@@ -1,6 +1,6 @@
 ---
 description: "Introspect the fields of a Drupal entity type + bundle: returns a per-field list of { name, type, kind, cardinality?, approximate }. Read-only. Built on schema SAMPLING (an existing entity), so results are approximate — only populated fields are visible and required/cardinality/allowedValues are inferred from value shape. Authoritative field metadata comes from the Drush bridge (Field API). Use this before creating/updating entities to learn field names."
-argument-hint: "<site> <type> [bundle]"
+argument-hint: "<site> [type] [entityType] [bundle]"
 allowed-tools: mcp__drupal__drupal_describe_fields
 ---
 
@@ -12,9 +12,10 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 
 **Required:**
 - `site` (string): Configured site name.
-- `type` (string): Entity type machine name, e.g. 'node', 'taxonomy_term', 'user', 'media'.
 
 **Optional:**
+- `type` (string): Entity type machine name, e.g. 'node', 'taxonomy_term', 'user', 'media'. Alias: `entityType` (as used by the sibling tools).
+- `entityType` (string): Alias for `type` — accepted for parity with get_entity_schema / entity_create / entity_update / resolve_reference.
 - `bundle` (string): Bundle machine name, e.g. 'article'. Defaults to the entity type for single-bundle types (e.g. 'user').
 
 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-entity-create.md

@@ -1,6 +1,6 @@
 ---
 description: "Create an entity of any Drupal entity type and bundle. Use drupal_get_entity_schema first to know what fields are available. All operations checked against security config."
-argument-hint: "<entityType> <bundle> [site] [attributes] [relationships] [dryRun]"
+argument-hint: "<entityType> <bundle> [site] [attributes] [relationships] [dryRun] [returning]"
 allowed-tools: mcp__drupal__drupal_entity_create
 ---
 
@@ -19,5 +19,6 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `attributes` (object (pass as JSON)): Field values keyed by Drupal machine name
 - `relationships` (object (pass as JSON)): Relationship data keyed by field name
 - `dryRun` (boolean (true/false)): Validate and return a preview of the create without committing.
+- `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 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-entity-update.md

@@ -1,6 +1,6 @@
 ---
 description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change."
-argument-hint: "<entityType> <bundle> <id> [site] [attributes] [relationships] [dryRun]"
+argument-hint: "<entityType> <bundle> <id> [site] [attributes] [relationships] [dryRun] [returning]"
 allowed-tools: mcp__drupal__drupal_entity_update
 ---
 
@@ -20,5 +20,6 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `attributes` (object (pass as JSON))
 - `relationships` (object (pass as JSON))
 - `dryRun` (boolean (true/false)): Validate and return a preview of the update without committing.
+- `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 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-report-seo-audit.md

@@ -1,12 +1,12 @@
 ---
-description: "SEO audit for a content type: missing meta descriptions, title length issues, and thin content (under 300 words). Returns node lists for each issue category."
+description: "SEO audit for a content type: missing meta descriptions, title length issues, and thin content (under 300 words). Returns node lists for each issue category. Meta descriptions use the rendered Metatag output via GraphQL when available (reported as `metaSource`); when no description source is readable it reports the meta check as unavailable rather than a false zero."
 argument-hint: "[site] [type] [sampleSize]"
 allowed-tools: mcp__drupal__drupal_report_seo_audit
 ---
 
 Call the `mcp__drupal__drupal_report_seo_audit` MCP tool.
 
-SEO audit for a content type: missing meta descriptions, title length issues, and thin content (under 300 words). Returns node lists for each issue category.
+SEO audit for a content type: missing meta descriptions, title length issues, and thin content (under 300 words). Returns node lists for each issue category. Meta descriptions use the rendered Metatag output via GraphQL when available (reported as `metaSource`); when no description source is readable it reports the meta check as unavailable rather than a false zero.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

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

@@ -1,12 +1,12 @@
 ---
-description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status."
-argument-hint: "<type> <id> [site] [title] [body] [summary] [status] [moderationState] [fields] [dryRun]"
+description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. Entity-reference fields go in `relationships`, not `fields`."
+argument-hint: "<type> <id> [site] [title] [body] [summary] [status] [moderationState] [fields] [relationships] [dryRun] [returning]"
 allowed-tools: mcp__drupal__drupal_update_node
 ---
 
 Call the `mcp__drupal__drupal_update_node` MCP tool.
 
-Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status.
+Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. Entity-reference fields go in `relationships`, not `fields`.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 
@@ -21,7 +21,9 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `summary` (string)
 - `status` (boolean (true/false)): Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set.
 - `moderationState` (string): Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status.
-- `fields` (object (pass as JSON))
+- `fields` (object (pass as JSON)): Scalar/attribute field values keyed by machine name. Entity-reference fields go in `relationships`, not here.
+- `relationships` (object (pass as JSON)): Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }.
 - `dryRun` (boolean (true/false)): Validate and return a preview of the update without committing.
+- `returning` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 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,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-07-23
+
+### Added
+- **`returning: "minimal"` on write tools (#113).** `drupal_entity_create/update` and
+  `drupal_create_node/update_node` returned the complete re-read entity on every write —
+  several thousand tokens for a node with a body (included twice, `value` + `processed`),
+  most of it unrelated to the change, which made bulk content work exhaust an agent's
+  context window. A new `returning` parameter (`"full"` default, preserving today's
+  contract; `"minimal"` opt-in) returns just identity + state (id, type, bundle, title,
+  status, changed, url), recommended for bulk writes. (`drupal_bulk_create/update` already
+  return only per-item id + status.)
+- **`security.allowPublish` policy knob (#114).** A local, fail-fast publish gate,
+  symmetric with `allowDestructive`: defaults `false` in every preset except
+  `development`, and an operator opts in per site. `assertPublishAllowed` rejects a
+  write carrying `status: true` before the round-trip when publishing is not permitted.
+  `drupal_mcp_whoami` now **derives** `capabilities.publish` from it (`allowPublish &&
+  write`) instead of returning a hardcoded `false`. The remote Drupal's permissions
+  (and any server-side governance) remain the real authority — this is defence in depth.
+- **Launcher: auditor secret sourcing.** `bin/drupal-mcp-launch.sh` now optionally
+  sources the read-only **config-auditor** Keychain secrets (`drupal-mcp-auditor-secret`
+  → `MCP_AGENT_AUDITOR_SECRET`, `drupal-mcp-auditor-secret-stg` →
+  `MCP_AGENT_AUDITOR_SECRET_STG`) for the `prod-audit` and `staging-audit` connector
+  sites. Both exports are guarded — silent no-ops until the auditor consumers are
+  provisioned — matching the existing per-environment secret-sourcing pattern.
+- **Launcher: content-auditor and break-glass admin secret sourcing.**
+  `bin/drupal-mcp-launch.sh` now also sources the read-only **content-auditor**
+  secrets (`drupal-mcp-content-auditor-secret` → `MCP_AGENT_CONTENT_AUDITOR_SECRET`,
+  `drupal-mcp-content-auditor-secret-stg` → `MCP_AGENT_CONTENT_AUDITOR_SECRET_STG`) and
+  the on-demand **break-glass admin** secret (`drupal-mcp-admin-secret` →
+  `MCP_AGENT_ADMIN_SECRET`). All are guarded no-ops until the matching Keychain items
+  exist; the admin item is deliberately absent by default so the `prod-admin` site stays
+  inert until you opt in for a session and remove it afterward.
+
+### Changed
+- **`drupal-content-audit` prompt is now content-type-agnostic (#122).** The prompt
+  hardcoded `article` for its SEO and accessibility steps, so on a site without that
+  type — or one whose model was consolidated — those steps scanned zero nodes and the
+  audit reported no findings, indistinguishable from a genuinely clean scan. It now
+  derives the types to audit from `drupal_report_content_summary`'s `byContentType`
+  inventory, iterates the per-type checks across every type that has nodes, records
+  zero-node types as empty rather than clean, prefers `drupal_report_seo_meta_coverage`
+  (which reads the site's actual meta field) for the SEO step, and states which types
+  were scanned so an empty or unexpected model can't be mistaken for a passing audit.
+
+### Fixed
+- **`drupal_describe_fields` entity-type parameter name mismatch (#116).** The tool took
+  the entity type as `type` while its siblings (`get_entity_schema`, `entity_create`,
+  `entity_update`, `resolve_reference`) take `entityType`; passing the sibling name
+  slipped through as `undefined` and surfaced a misleading "Entity type 'undefined' is
+  not in the allowedEntityTypes list" access error. It now accepts `entityType` as an
+  alias for `type`, and errors clearly (naming both accepted parameters) when neither is
+  given instead of reporting a phantom access-control failure.
+- **Backend resolution misdiagnosed auth failures as unreachable (#119).** The probe
+  swallowed every error and reported "none of the configured api backends are usable —
+  check the api setting and that the endpoint is reachable," sending operators to chase
+  network/DNS when the real problem was an expired/invalid OAuth token. Resolution now
+  captures each protocol's underlying error, classifies auth failures (401,
+  invalid_client/grant, unauthorized) distinctly, includes the underlying detail in
+  every message, and on an auth failure clears the cached token so the next call
+  re-attempts the client-credentials grant instead of latching "unusable."
+- **`drupal_create_node` / `drupal_update_node` couldn't set entity-reference fields (#115).**
+  Everything in `fields` was sent as JSON:API attributes, so any create/update that set a
+  reference field (taxonomy, related content, media) failed with a 422 — the node tools
+  could only produce untagged, unclassified content. Both tools now take a `relationships`
+  parameter (JSON:API shape, same as `drupal_entity_create`) that is passed through to the
+  backend, and `fields`/`relationships` are documented so reference fields land in the right
+  place.
+- **Publish state silently dropped on writes (#111).** A write carrying `status: true`
+  at a tier that cannot publish was silently discarded (200, entity unchanged, no
+  diagnostic). Two causes, both fixed: the new `assertPublishAllowed` gate now rejects
+  such a write up front with a clear error, and the JSON:API moderated-status retry no
+  longer matches a generic `field (status)` **permission** denial — that is a real
+  refusal and now surfaces, instead of being retried away as a moderation quirk. Only
+  the unambiguous "published field of moderated entities" error still triggers the
+  status-drop retry.
+- **`dryRun` echoed input instead of validating (#112).** `dryRun` returned the request
+  parameters without applying tier policy, so it previewed writes that could not happen.
+  It now runs the same write **and publish** checks as the real call, so a dry run fails
+  exactly where the write would.
+- **`whoami` hardcoded `capabilities.publish: false` (#114).** A site-specific claim in
+  a site-agnostic tool, neither derived nor enforced. Now derived from `allowPublish`
+  (see Added).
+- **Bulk writes bypassed the publish gate.** `drupal_bulk_create`/`drupal_bulk_update` now
+  apply `assertPublishAllowed` per item (a publish-bearing item fails on its own, without
+  aborting the batch), so the new `allowPublish` policy can't be sidestepped in bulk.
+- **SEO audit: false "0 missing meta descriptions" on Metatag sites (#120).**
+  `drupal_report_seo_audit` counted the JSON:API `metatag` field as a present
+  description, but that field is an unresolved placeholder over JSON:API, so every
+  node looked covered and the audit reported zero gaps while pages shipped without a
+  description. The meta check now resolves the **rendered** description from GraphQL
+  Compose's normalized `metatag` field (`route(path:)`, no introspection required —
+  reflecting defaults *and* per-node overrides), falls back to a plain
+  `field_meta_description`/`metaDescription` field on non-Metatag sites, and when
+  neither is readable reports the check as `unavailable` rather than a false zero. The
+  result now carries a `metaSource` of `graphql` | `jsonapi` | `unavailable`.
+- **Docs: stale counts corrected.** The getting-started first-run banner and the
+  architecture/whitepaper figures still read `v1.3.0 / 93 tools / 21 modules / 4 prompts`;
+  updated to the current build — **119 tools across 26 modules, 3 resources, 124 prompts**
+  — so onboarding output matches what a new user actually sees.
+
+### Changed
+- **Docs: per-client cross-link.** `getting-started.md` §6 now points to `mcp-clients.md`
+  for copy-paste config per client (Claude Code/Desktop, Grok Build, OpenAI Codex, Cursor).
+
 ## [1.7.0] - 2026-07-01
 
 ### Added

package/package.json

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

@@ -226,14 +226,15 @@ function getPromptMessages(name, args) {
   const prompts = {
     "drupal-content-audit": [
       { role: "user", content: { type: "text", text:
-        `Please run a comprehensive content audit ${site}. Follow these steps:\n` +
-        "1. Call drupal_report_content_summary to get the full inventory.\n" +
-        "2. Call drupal_report_stale_content (days: 180) to find stale content.\n" +
-        "3. Call drupal_report_field_completeness for each major content type.\n" +
-        "4. Call drupal_report_seo_audit for the article content type.\n" +
-        "5. Call drupal_report_accessibility_audit for the article content type.\n" +
-        "6. Synthesize findings into: (a) immediate actions, (b) medium-term improvements, (c) process recommendations.\n" +
-        "Present results as a structured report with counts, severity, and specific node links where possible."
+        `Please run a comprehensive content audit ${site}. Do not assume any particular content type exists — every site has a different model, so discover it first and audit the types this site actually has.\n` +
+        "1. Call drupal_report_content_summary for the full inventory. Its byContentType list is the set of content types to audit — derive the types from it; never assume a fixed type such as \"article\".\n" +
+        "2. For each content type that has nodes, call drupal_report_stale_content (days: 180).\n" +
+        "3. For each content type that has nodes, call drupal_report_field_completeness.\n" +
+        "4. For each content type with published nodes, check SEO: prefer drupal_report_seo_meta_coverage (it reads the site's actual meta field rather than assuming one) and use drupal_report_seo_audit for title-length and thin-content checks.\n" +
+        "5. For each content type with published nodes, call drupal_report_accessibility_audit.\n" +
+        "6. For any content type reporting zero nodes, skip its per-type scans and record it as empty — an empty type is not a clean one.\n" +
+        "7. Synthesize findings into: (a) immediate actions, (b) medium-term improvements, (c) process recommendations.\n" +
+        "Present results as a structured report with counts, severity, and specific node links where possible. State which content types were scanned so an empty or unexpected model cannot be mistaken for a clean audit."
       }},
     ],
     "drupal-create-article": [

package/src/lib/backends/index.js

@@ -10,6 +10,7 @@
 
 import { drupalFetch } from "../drupal-fetch.js";
 import { drupalGraphqlFetch } from "../drupal-fetch.js";
+import { clearToken } from "../oauth.js";
 import { JsonApiBackend } from "./jsonapi.js";
 import { GraphqlBackend } from "./graphql.js";
 import { BackendResolutionError } from "./errors.js";
@@ -31,6 +32,25 @@ export function _clearBackendCache() {
   cache.clear();
 }
 
+/**
+ * Classify a probe failure as an authentication problem (expired/invalid OAuth
+ * token or bad client credentials) rather than an unreachable endpoint. This is
+ * the distinction #119 needs: an auth failure and a network failure demand
+ * different fixes, and the generic "endpoint not reachable" message sent
+ * operators to the wrong place.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isAuthError(err) {
+  const msg = String(err?.message || "");
+  return (
+    /\b401\b/.test(msg) ||
+    (/\b403\b/.test(msg) && /token|oauth|credential|scope/i.test(msg)) ||
+    /invalid_client|invalid_grant|unauthorized_client|invalid_token/i.test(msg) ||
+    /\bunauthorized\b/i.test(msg)
+  );
+}
+
 /**
  * Resolve (and cache) the backend adapter for a site.
  * @param {object} site Site config; must include `_name` and may include `api`.
@@ -41,25 +61,10 @@ export async function resolveBackend(site) {
   if (cache.has(site._name)) return cache.get(site._name);
 
   const order = normalizeApiOrder(site.api);
-  let backend;
+  const probeOrder = order ?? [...REGISTRY.keys()];
+  const { backend, failures } = await resolveFromOrder(site, probeOrder);
 
-  if (order) {
-    backend = await firstUsable(site, order);
-    if (!backend) {
-      throw new BackendResolutionError(
-        `Site "${site._name}": none of the configured api backends [${order.join(", ")}] are usable. ` +
-        "Check the \"api\" setting and that the endpoint is reachable."
-      );
-    }
-  } else {
-    backend = await probe(site);
-    if (!backend) {
-      throw new BackendResolutionError(
-        `Site "${site._name}": could not auto-detect a usable API. ` +
-        "Set \"api\" in config (e.g. \"graphql\" or \"jsonapi\")."
-      );
-    }
-  }
+  if (!backend) throw buildResolutionError(site, order, failures);
 
   cache.set(site._name, backend);
   return backend;
@@ -78,51 +83,88 @@ function normalizeApiOrder(api) {
 }
 
 /**
- * Return the first configured backend that is actually reachable.
+ * Probe each protocol in order, returning the first usable backend plus the
+ * per-protocol failures (captured, not swallowed) for diagnostics.
  * @param {object} site Site config.
  * @param {string[]} order Protocol names in preference order.
- * @returns {Promise<?import("./backend-interface.js").Backend>} Instance or null.
+ * @returns {Promise<{backend: ?import("./backend-interface.js").Backend, failures: {name: string, error: Error}[]}>}
  */
-async function firstUsable(site, order) {
+async function resolveFromOrder(site, order) {
+  const failures = [];
   for (const name of order) {
     const Cls = REGISTRY.get(name);
-    if (!Cls) continue;
-    if (await isReachable(name, site)) return new Cls(site);
-  }
-  return null;
-}
-
-/**
- * Auto-detect a backend by probing each registered protocol in order.
- * @param {object} site Site config.
- * @returns {Promise<?import("./backend-interface.js").Backend>} Instance or null.
- */
-async function probe(site) {
-  for (const [name, Cls] of REGISTRY) {
-    if (await isReachable(name, site)) return new Cls(site);
+    if (!Cls) {
+      failures.push({ name, error: new Error(`no adapter registered for "${name}"`) });
+      continue;
+    }
+    const { ok, error } = await probeProtocol(name, site);
+    if (ok) return { backend: new Cls(site), failures };
+    failures.push({ name, error });
   }
-  return null;
+  return { backend: null, failures };
 }
 
 /**
- * Probe whether a given protocol responds for a site. Any error counts as
- * unreachable so probing never throws.
+ * Probe whether a given protocol responds for a site. Unlike a boolean probe,
+ * this captures the underlying error so resolution can tell an auth failure from
+ * an unreachable endpoint (#119).
  * @param {string} name Protocol name ("jsonapi" | "graphql").
  * @param {object} site Site config.
- * @returns {Promise<boolean>} True when the endpoint answered successfully.
+ * @returns {Promise<{ok: boolean, error: ?Error}>}
  */
-async function isReachable(name, site) {
+async function probeProtocol(name, site) {
   try {
     if (name === "jsonapi") {
       await drupalFetch(site, "/jsonapi");
-      return true;
+      return { ok: true, error: null };
     }
     if (name === "graphql") {
       const json = await drupalGraphqlFetch(site, { query: "{ __typename }" });
-      return Boolean(json && !json.errors);
+      if (json && !json.errors) return { ok: true, error: null };
+      return { ok: false, error: new Error(json?.errors?.[0]?.message || "GraphQL probe returned errors") };
     }
-    return false;
-  } catch {
-    return false;
+    return { ok: false, error: new Error(`unknown backend "${name}"`) };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Build a diagnostic BackendResolutionError from the captured probe failures.
+ * An auth failure gets its own message (and clears the cached token so the next
+ * call re-attempts the grant instead of latching "unusable"); otherwise the
+ * message points at reachability/config — but always includes the underlying
+ * error so the operator is not sent to the wrong place (#119).
+ * @param {object} site Site config.
+ * @param {?string[]} order The configured api order (null when auto-detecting).
+ * @param {{name: string, error: Error}[]} failures Per-protocol failures.
+ * @returns {BackendResolutionError}
+ */
+function buildResolutionError(site, order, failures) {
+  const detail = failures.map((f) => `${f.name}: ${f.error?.message || "unknown error"}`).join(" | ");
+  const authFailure = failures.some((f) => isAuthError(f.error));
+
+  if (authFailure) {
+    // Recovery: drop any cached token so the next resolveBackend re-grants
+    // (client_credentials refresh) rather than replaying a stale/invalid token.
+    if (site.oauth) clearToken(site);
+    return new BackendResolutionError(
+      `Site "${site._name}": authentication failed against the configured backend(s) — ` +
+      "this is an auth problem (expired/invalid OAuth token or client credentials), not reachability. " +
+      `Underlying: ${detail}. ` +
+      "Check the OAuth client_id/secret and scopes. The cached token has been cleared, so the next call will re-attempt the grant."
+    );
   }
+
+  if (order) {
+    return new BackendResolutionError(
+      `Site "${site._name}": none of the configured api backends [${order.join(", ")}] are usable. ` +
+      `Check the "api" setting and that the endpoint is reachable. Underlying: ${detail}.`
+    );
+  }
+
+  return new BackendResolutionError(
+    `Site "${site._name}": could not auto-detect a usable API. ` +
+    `Set "api" in config (e.g. "graphql" or "jsonapi"). Underlying: ${detail}.`
+  );
 }

package/src/lib/backends/jsonapi.js

@@ -32,15 +32,20 @@ const COUNT_MAX_RECORDS = 1000;
  * Detect the JSON:API error Drupal returns when a write attempts to set the
  * `status` (published) field on a content_moderation-governed entity. Such
  * entities own their published state via `moderation_state`, so a direct
- * `status` write is refused with a 403 ("Cannot edit the published field of
- * moderated entities" / "not allowed to … field (status)"). Used to decide
- * whether to retry the write without `status`.
+ * `status` write is refused with "Cannot edit the published field of moderated
+ * entities." Used to decide whether to retry the write without `status`.
+ *
+ * Matched narrowly, on that moderation-specific phrase only. A generic
+ * field-access denial ("The current user is not allowed to … the field
+ * (status)") is a *permission* refusal, not a moderation quirk — matching it
+ * here would silently drop a caller's status change and return success (#111).
+ * That case must surface, so it is deliberately excluded.
  * @param {unknown} err
  * @returns {boolean}
  */
 export function isModeratedStatusError(err) {
   const msg = String(err?.message || "");
-  return /published field of moderated/i.test(msg) || /field \(status\)/i.test(msg);
+  return /published field of moderated/i.test(msg);
 }
 
 // Canonical filter op -> JSON:API condition operator.

package/src/lib/entity-response.js

@@ -0,0 +1,46 @@
+/**
+ * Shape a write tool's response.
+ *
+ * Write tools return the full re-read entity by default, which for a node with a
+ * populated body is several thousand tokens per call — most of it unrelated to
+ * the change, and with `body.value` and `body.processed` both included in full
+ * (#113). The primary consumer is an agent with a bounded context window, so a
+ * bulk operation (e.g. tagging many nodes) can exhaust the window on echoed
+ * bodies. `returning: "minimal"` opts into an identity + state summary that is
+ * enough to confirm the write.
+ */
+
+// Base fields promoted onto a canonical entity that a caller needs to verify a
+// write. Non-base fields (body, arbitrary attributes, relationships) are omitted
+// in minimal mode. Internal keys prefixed with `_` (e.g. `_redirect`) are
+// preserved separately so tool-specific metadata is not lost.
+const MINIMAL_KEYS = ["id", "entityType", "bundle", "title", "status", "moderation_state", "langcode", "changed", "url"];
+
+/**
+ * @param {object|null} entity Canonical entity (or a write result wrapping one).
+ * @param {"full"|"minimal"} [returning] Response verbosity. Defaults to "full".
+ * @returns {object|null} The entity, or a compact identity+state summary.
+ */
+export function shapeWriteResponse(entity, returning = "full") {
+  if (!entity || returning !== "minimal") return entity;
+  const out = {};
+  for (const key of MINIMAL_KEYS) {
+    if (entity[key] !== undefined && entity[key] !== null) out[key] = entity[key];
+  }
+  // Preserve tool-specific metadata keys (e.g. `_redirect` from a node rename).
+  for (const key of Object.keys(entity)) {
+    if (key.startsWith("_")) out[key] = entity[key];
+  }
+  return out;
+}
+
+/** JSON Schema fragment for the shared `returning` parameter. */
+export const RETURNING_SCHEMA = {
+  type: "string",
+  enum: ["full", "minimal"],
+  default: "full",
+  description:
+    "Response verbosity. \"full\" (default) returns the complete saved entity; " +
+    "\"minimal\" returns just identity + state (id, type, bundle, title, status, changed, url) — " +
+    "much smaller, recommended for bulk writes where the echoed body would dominate the response.",
+};

package/src/lib/metatag-audit.js

@@ -0,0 +1,117 @@
+/**
+ * Rendered meta-description resolution for the SEO audit.
+ *
+ * A Drupal site using the Metatag module computes a node's final tags at render
+ * time from bundle *defaults* (often token fallbacks like `[node:summary]`) plus
+ * any per-node override. That computed value is NOT resolved over JSON:API — the
+ * `metatag` field there is a structural placeholder with empty attributes — so a
+ * JSON:API-only audit cannot see whether a description is actually emitted, and
+ * treating the placeholder as "present" silently reports 0 missing on every node
+ * (see issue #120).
+ *
+ * The only source that reflects what the frontend renders is GraphQL Compose's
+ * normalized `metatag` field (exposed by graphql_compose_metatags). This module
+ * fetches it via `route(path:)` — the same entry point the frontend uses — with
+ * a query that needs no schema introspection (which many sites disable).
+ */
+
+import { drupalGraphqlFetch } from "./drupal-fetch.js";
+
+// Node paths are batched into aliased `route()` selections per request. Kept
+// modest so a single document stays small and one bad path can't sink a large
+// batch (each alias resolves independently).
+const CHUNK = 25;
+
+// `metatag` lives on NodeInterface, so one selection covers every node bundle
+// without knowing per-bundle GraphQL type names (unavailable when introspection
+// is disabled). `route` resolves to a union; the fragment matches the internal
+// (entity-backed) case and is simply skipped for redirects/external routes.
+const ROUTE_META_FRAGMENT = `fragment MetaOnRoute on RouteInternal {
+  entity {
+    ... on NodeInterface {
+      metatag {
+        __typename
+        ... on MetaTagValue { attributes { name content } }
+      }
+    }
+  }
+}`;
+
+/**
+ * Pull the rendered meta description out of a GraphQL `metatag` array.
+ *
+ * @param {unknown} metatag The node's normalized `metatag` field value.
+ * @returns {string} The trimmed description content, or "" when absent/empty.
+ */
+export function metaDescriptionFromMetatag(metatag) {
+  if (!Array.isArray(metatag)) return "";
+  for (const tag of metatag) {
+    if (
+      tag &&
+      tag.__typename === "MetaTagValue" &&
+      tag.attributes &&
+      tag.attributes.name === "description"
+    ) {
+      return typeof tag.attributes.content === "string" ? tag.attributes.content.trim() : "";
+    }
+  }
+  return "";
+}
+
+/**
+ * Resolve rendered meta descriptions for a set of published nodes via GraphQL.
+ *
+ * @param {object} site Resolved site config (for drupalGraphqlFetch).
+ * @param {Array<{id: string, url?: ?string}>} entities Nodes to resolve; each
+ *   must carry its path alias in `url` to be resolvable.
+ * @returns {Promise<{source: "graphql"|"unavailable", reason?: string,
+ *   byId: Map<string, {description: string}>}>}
+ *   - source "graphql": `byId` maps entity id → { description } for every node
+ *     whose route resolved to an entity. Nodes with no resolvable route are
+ *     omitted (unknown), never assumed missing.
+ *   - source "unavailable": GraphQL, `route`, or the `metatag` field is not
+ *     reachable. The caller MUST NOT treat this as "0 missing".
+ */
+export async function fetchRenderedMetaDescriptions(site, entities) {
+  const byId = new Map();
+  const withPath = entities
+    .map((e) => ({ id: e.id, path: typeof e.url === "string" ? e.url : null }))
+    .filter((e) => e.path && e.path.startsWith("/"));
+
+  if (withPath.length === 0) {
+    return { source: "unavailable", reason: "no node path aliases available to resolve", byId };
+  }
+
+  for (let i = 0; i < withPath.length; i += CHUNK) {
+    const chunk = withPath.slice(i, i + CHUNK);
+    const varDecls = chunk.map((_, j) => `$p${j}: String!`).join(", ");
+    const selections = chunk.map((_, j) => `  n${j}: route(path: $p${j}) { ...MetaOnRoute }`).join("\n");
+    const query = `query MetaAudit(${varDecls}) {\n${selections}\n}\n\n${ROUTE_META_FRAGMENT}`;
+    const variables = Object.fromEntries(chunk.map((e, j) => [`p${j}`, e.path]));
+
+    let json;
+    try {
+      json = await drupalGraphqlFetch(site, { query, variables });
+    } catch (err) {
+      // Endpoint unreachable / not configured / auth failure.
+      return { source: "unavailable", reason: `GraphQL request failed: ${err.message}`, byId };
+    }
+
+    if (Array.isArray(json.errors) && json.errors.length > 0) {
+      // A schema-level error (no `route`, no `metatag` field, graphql_compose_metatags
+      // absent) means we cannot determine descriptions — fail closed to
+      // "unavailable" rather than reporting every node as missing.
+      return { source: "unavailable", reason: json.errors[0]?.message ?? "GraphQL error", byId };
+    }
+
+    const data = json.data || {};
+    chunk.forEach((e, j) => {
+      const route = data[`n${j}`];
+      const entity = route && route.entity;
+      if (!entity) return; // route did not resolve to a node; leave unknown
+      byId.set(e.id, { description: metaDescriptionFromMetatag(entity.metatag) });
+    });
+  }
+
+  return { source: "graphql", byId };
+}

package/src/lib/security.js

@@ -31,6 +31,7 @@ import { parse } from "graphql";
  *
  *  readOnly            true  → reject all create/update/delete/graphql-mutation calls
  *  allowDestructive    false → reject all delete operations
+ *  allowPublish        false → reject a write carrying status:true (publishing)
  *  allowGraphqlMutations false → reject drupal_graphql when mutation is detected
  *  allowConfigRead     false → reject drupal_config_get / drupal_config_list
  *  allowConfigWrite    false → reject drupal_config_set
@@ -116,6 +117,7 @@ const PRESETS = {
   development: {
     readOnly: false,
     allowDestructive: true,
+    allowPublish: true,               // mirrors allowDestructive: everything allowed
     allowGraphqlMutations: true,
     allowConfigRead: true,
     allowConfigWrite: true,
@@ -230,6 +232,7 @@ export function resolveSecurityConfig(site) {
   return {
     readOnly:              raw.readOnly              ?? preset.readOnly,
     allowDestructive:      raw.allowDestructive      ?? preset.allowDestructive,
+    allowPublish:          raw.allowPublish          ?? preset.allowPublish          ?? false,
     allowGraphqlMutations: raw.allowGraphqlMutations ?? preset.allowGraphqlMutations,
     allowConfigRead:       raw.allowConfigRead       ?? preset.allowConfigRead       ?? false,
     allowConfigWrite:      raw.allowConfigWrite      ?? preset.allowConfigWrite      ?? false,
@@ -375,6 +378,42 @@ export function assertDestructiveAllowed(secConfig, entityType, id) {
   }
 }
 
+/**
+ * Whether a set of write attributes carries a publish action. Deliberately
+ * limited to the unambiguous, entity-agnostic signal `status === true`; a site's
+ * moderation-workflow state names are not knowable from a site-agnostic
+ * connector, so publishing via `moderation_state` stays gated server-side.
+ * @param {object} [attributes] Attribute map for the write.
+ * @returns {boolean}
+ */
+export function isPublishBearing(attributes = {}) {
+  return attributes?.status === true;
+}
+
+/**
+ * Local, fail-fast publish gate, symmetric with assertDestructiveAllowed. When
+ * the connector is not permitted to publish (allowPublish false — the default in
+ * every preset except `development`), a write carrying `status: true` is refused
+ * before the round-trip, rather than being silently dropped by a moderated-bundle
+ * retry or a server-side gate (see #111/#114). Client-side convenience only — the
+ * remote Drupal's own permissions remain the real authority.
+ * @param {object} secConfig Resolved security config.
+ * @param {object} [attributes] Attribute map for the write.
+ * @returns {void}
+ * @throws {SecurityError} if a publish-bearing write is attempted while allowPublish is false.
+ */
+export function assertPublishAllowed(secConfig, attributes = {}) {
+  if (secConfig.allowPublish) return;
+  if (isPublishBearing(attributes)) {
+    throw new SecurityError(
+      "Publishing is disabled for this connector (allowPublish: false). " +
+      "Blocked: a write carrying status:true. " +
+      "To enable, set security.allowPublish = true in your config; otherwise publish " +
+      "via an operator/server-gated path (e.g. a moderation transition)."
+    );
+  }
+}
+
 /**
  * Detect whether a GraphQL document contains a mutation operation.
  * Uses a real parser (robust against multi-operation docs, comments, and

package/src/tools/bulk.js

@@ -13,7 +13,7 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
-import { resolveSecurityConfig, assertWriteAllowed } from "../lib/security.js";
+import { resolveSecurityConfig, assertWriteAllowed, assertPublishAllowed } from "../lib/security.js";
 
 /**
  * Normalize an unknown thrown value into a human-readable message.
@@ -46,6 +46,7 @@ async function bulkCreate({ site: siteName, entityType, bundle, items = [] }) {
   for (const [index, rawItem] of items.entries()) {
     const item = rawItem || {};
     try {
+      assertPublishAllowed(sec, item.attributes ?? {});
       const entity = await backend.createEntity({
         entityType, bundle,
         attributes: item.attributes ?? {},
@@ -84,6 +85,7 @@ async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
     const item = rawItem || {};
     try {
       if (!item.id) throw new Error("Missing 'id' for update item");
+      assertPublishAllowed(sec, item.attributes ?? {});
       const entity = await backend.updateEntity({
         entityType, bundle, id: item.id,
         attributes: item.attributes ?? {},

package/src/tools/config.js

@@ -130,9 +130,10 @@ async function whoami({ site: siteName }) {
       delete:      sec.allowDestructive && canWrite,
       configRead:  sec.allowConfigRead  && canConfig,
       configWrite: sec.allowConfigWrite && !sec.readOnly && canConfig,
-      // Publishing is always gated server-side (editorial workflow); the agent
-      // never holds the publish transition. Surfaced here so it is explicit.
-      publish:     false,
+      // Local publish policy (allowPublish), symmetric with delete/config caps.
+      // Defaults false in every preset except `development`; the remote Drupal's
+      // own permissions (and any server-side governance) remain authoritative.
+      publish:     sec.allowPublish && canWrite,
     },
   };
 }

package/src/tools/entities.js

@@ -10,8 +10,9 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
+import { shapeWriteResponse, RETURNING_SCHEMA } from "../lib/entity-response.js";
 import {
-  resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed,
+  resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
   redactCanonicalEntity, getSecuritySummary,
 } from "../lib/security.js";
 
@@ -56,13 +57,14 @@ async function getEntity({ site: siteName, entityType, bundle, id, include = []
  * @returns {Promise<object>} The created entity descriptor.
  * @throws {SecurityError} If creating the type/bundle is not permitted.
  */
-async function createEntity({ site: siteName, entityType, bundle, attributes = {}, relationships = {}, dryRun = false }) {
+async function createEntity({ site: siteName, entityType, bundle, attributes = {}, relationships = {}, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", entityType, bundle);
+  assertPublishAllowed(sec, attributes);
   if (dryRun) return { dryRun: true, operation: "create", entityType, bundle, attributes, relationships };
   const backend = await resolveBackend(site);
-  return backend.createEntity({ entityType, bundle, attributes, relationships });
+  return shapeWriteResponse(await backend.createEntity({ entityType, bundle, attributes, relationships }), returning);
 }
 
 /**
@@ -72,13 +74,14 @@ async function createEntity({ site: siteName, entityType, bundle, attributes = {
  * @returns {Promise<object>} The updated entity descriptor.
  * @throws {SecurityError} If updating the type/bundle is not permitted.
  */
-async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {}, dryRun = false }) {
+async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {}, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", entityType, bundle);
+  assertPublishAllowed(sec, attributes);
   if (dryRun) return { dryRun: true, operation: "update", entityType, bundle, id, attributes, relationships };
   const backend = await resolveBackend(site);
-  return backend.updateEntity({ entityType, bundle, id, attributes, relationships });
+  return shapeWriteResponse(await backend.updateEntity({ entityType, bundle, id, attributes, relationships }), returning);
 }
 
 /**
@@ -213,6 +216,7 @@ export const definitions = [
         attributes:    { type: "object", description: "Field values keyed by Drupal machine name" },
         relationships: { type: "object", description: "Relationship data keyed by field name" },
         dryRun:        { type: "boolean", default: false, description: "Validate and return a preview of the create without committing." },
+        returning:     RETURNING_SCHEMA,
       },
     },
   },
@@ -229,6 +233,7 @@ export const definitions = [
         attributes:    { type: "object" },
         relationships: { type: "object" },
         dryRun:        { type: "boolean", default: false, description: "Validate and return a preview of the update without committing." },
+        returning:     RETURNING_SCHEMA,
       },
     },
   },

package/src/tools/fields.js

@@ -67,16 +67,28 @@ function relationshipField(name) {
  * Read-only. Builds on the always-available sampling schema and normalizes it
  * into a flat, per-field list with inferred hints. Always `approximate: true`.
  *
- * @param {object} args - { site?, type, bundle? }. `bundle` defaults to `type`
- *   (matching Drupal's single-bundle entity types, e.g. `user`).
+ * The entity type is accepted as either `type` or `entityType` (#116): the
+ * sibling tools (get_entity_schema, entity_create/update, resolve_reference) use
+ * `entityType`, and passing that name here previously slipped through as
+ * `undefined` and surfaced a misleading access-denied error.
+ *
+ * @param {object} args - { site?, type|entityType, bundle? }. `bundle` defaults
+ *   to the entity type (matching Drupal's single-bundle types, e.g. `user`).
  * @returns {Promise<{entityType: string, bundle: string, resourceType?: string,
  *   approximate: true, fieldCount: number, fields: object[], note: string,
  *   authoritativeSource: string}>}
  * @throws {SecurityError} If reading the type/bundle is not permitted.
+ * @throws {Error} If no entity type is given under either name.
  */
-async function describeFields({ site: siteName, type, bundle }) {
-  const entityType = type;
-  const resolvedBundle = bundle || type;
+async function describeFields({ site: siteName, type, entityType: entityTypeArg, bundle }) {
+  const entityType = type ?? entityTypeArg;
+  if (!entityType) {
+    throw new Error(
+      "drupal_describe_fields requires an entity type. Pass `type` (or its alias `entityType`), " +
+      "e.g. { type: \"node\", bundle: \"article\" }."
+    );
+  }
+  const resolvedBundle = bundle || entityType;
 
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
@@ -120,10 +132,11 @@ export const definitions = [
       "bridge (Field API). Use this before creating/updating entities to learn field names.",
     inputSchema: {
       type: "object",
-      required: ["site", "type"],
+      required: ["site"],
       properties: {
         site:   { type: "string", description: "Configured site name." },
-        type:   { type: "string", description: "Entity type machine name, e.g. 'node', 'taxonomy_term', 'user', 'media'." },
+        type:   { type: "string", description: "Entity type machine name, e.g. 'node', 'taxonomy_term', 'user', 'media'. Alias: `entityType` (as used by the sibling tools)." },
+        entityType: { type: "string", description: "Alias for `type` — accepted for parity with get_entity_schema / entity_create / entity_update / resolve_reference." },
         bundle: { type: "string", description: "Bundle machine name, e.g. 'article'. Defaults to the entity type for single-bundle types (e.g. 'user')." },
       },
     },

package/src/tools/nodes.js

@@ -9,7 +9,8 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
-import { resolveSecurityConfig, redactCanonicalEntity, assertWriteAllowed } from "../lib/security.js";
+import { resolveSecurityConfig, redactCanonicalEntity, assertWriteAllowed, assertPublishAllowed } from "../lib/security.js";
+import { shapeWriteResponse, RETURNING_SCHEMA } from "../lib/entity-response.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 
 /** Fallback language for an alias when the node exposes none. */
@@ -215,10 +216,14 @@ async function searchContent({ site: siteName, query, type, status, limit = 10 }
  * If a moderated bundle still receives `status` (the safe default), the JSON:API
  * backend transparently retries without it — see jsonapi.js.
  *
- * @param {object} args - { site?, type, title, body?, summary?, status?, moderationState?, fields? }.
+ * Entity-reference fields (taxonomy, related content, media) must be passed in
+ * `relationships` (JSON:API shape), not `fields`; Drupal rejects reference fields
+ * sent as attributes (#115).
+ *
+ * @param {object} args - { site?, type, title, body?, summary?, status?, moderationState?, fields?, relationships? }.
  * @returns {Promise<object>} The created node descriptor from the backend.
  */
-async function createNode({ site: siteName, type, title, body, summary, status, moderationState, fields = {}, dryRun = false }) {
+async function createNode({ site: siteName, type, title, body, summary, status, moderationState, fields = {}, relationships = {}, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const attributes = { title, ...fields };
   if (moderationState !== undefined) {
@@ -228,18 +233,19 @@ async function createNode({ site: siteName, type, title, body, summary, status,
   }
   const bodyAttr = buildBodyAttribute(body, summary);
   if (bodyAttr) attributes.body = bodyAttr;
-  if (dryRun) return { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes };
+  assertPublishAllowed(resolveSecurityConfig(site), attributes);
+  if (dryRun) return { dryRun: true, operation: "create", entityType: "node", bundle: type, attributes, relationships };
   const backend = await resolveBackend(site);
   // Alias handling: an explicit `path.alias` is set as a manual alias; otherwise
   // `path` is omitted so pathauto generates the alias (DEV-116).
   const { pathAttr } = await resolvePathWrite({ backend, type, id: null, providedPath: attributes.path, isCreate: true });
   if (pathAttr === undefined) delete attributes.path;
   else attributes.path = pathAttr;
-  const created = await backend.createEntity({ entityType: "node", bundle: type, attributes });
+  const created = await backend.createEntity({ entityType: "node", bundle: type, attributes, relationships });
   // Honest response: re-read so the persisted alias (explicit or pathauto-generated)
   // is reflected rather than the pre-alias write response.
   const fresh = await backend.getEntity({ entityType: "node", bundle: type, id: created.id }).catch(() => null);
-  return fresh ?? created;
+  return shapeWriteResponse(fresh ?? created, returning);
 }
 
 /**
@@ -256,10 +262,12 @@ async function createNode({ site: siteName, type, title, body, summary, status,
  * the current alias is read back and re-pinned (`{ alias, pathauto: 0 }`). Pass
  * `fields.path` explicitly to set/replace the alias yourself.
  *
- * @param {object} args - { site?, type, id, title?, body?, summary?, status?, moderationState?, fields? }.
+ * Entity-reference fields go in `relationships` (JSON:API shape), not `fields` (#115).
+ *
+ * @param {object} args - { site?, type, id, title?, body?, summary?, status?, moderationState?, fields?, relationships? }.
  * @returns {Promise<object>} The updated node descriptor.
  */
-async function updateNode({ site: siteName, type, id, title, body, summary, status, moderationState, fields = {}, dryRun = false }) {
+async function updateNode({ site: siteName, type, id, title, body, summary, status, moderationState, fields = {}, relationships = {}, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const attributes = { ...fields };
   if (title !== undefined) attributes.title = title;
@@ -267,7 +275,8 @@ async function updateNode({ site: siteName, type, id, title, body, summary, stat
   else if (status !== undefined) attributes.status = status;
   const bodyAttr = buildBodyAttribute(body, summary);
   if (bodyAttr) attributes.body = bodyAttr;
-  if (dryRun) return { dryRun: true, operation: "update", entityType: "node", bundle: type, id, attributes };
+  assertPublishAllowed(resolveSecurityConfig(site), attributes);
+  if (dryRun) return { dryRun: true, operation: "update", entityType: "node", bundle: type, id, attributes, relationships };
   const backend = await resolveBackend(site);
   const sec = resolveSecurityConfig(site);
   // Alias handling (DEV-116): an explicit `path.alias` is set in place by
@@ -277,13 +286,13 @@ async function updateNode({ site: siteName, type, id, title, body, summary, stat
   const { pathAttr, redirect } = await resolvePathWrite({ backend, type, id, providedPath: attributes.path, isCreate: false });
   if (pathAttr === undefined) delete attributes.path;
   else attributes.path = pathAttr;
-  await backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
+  await backend.updateEntity({ entityType: "node", bundle: type, id, attributes, relationships });
   const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
   // Honest response: re-read persisted state so the returned `url` is the alias
   // that actually resolves, never the just-sent value.
   const fresh = await backend.getEntity({ entityType: "node", bundle: type, id }).catch(() => null);
-  if (fresh && redirectResult) return { ...fresh, _redirect: redirectResult };
-  return fresh ?? { id };
+  if (fresh && redirectResult) return shapeWriteResponse({ ...fresh, _redirect: redirectResult }, returning);
+  return shapeWriteResponse(fresh ?? { id }, returning);
 }
 
 /**
@@ -350,7 +359,7 @@ export const definitions = [
   },
   {
     name: "drupal_create_node",
-    description: "Create a new content node. Returns the new node UUID, integer ID, and URL. For content types under an editorial (content_moderation) workflow, set moderationState (e.g. 'draft'/'published') instead of status.",
+    description: "Create a new content node. Returns the new node UUID, integer ID, and URL. For content types under an editorial (content_moderation) workflow, set moderationState (e.g. 'draft'/'published') instead of status. Entity-reference fields (taxonomy terms, related content, media) go in `relationships`, not `fields`.",
     inputSchema: {
       type: "object", required: ["type", "title"],
       properties: {
@@ -361,14 +370,16 @@ export const definitions = [
         summary: { type: "string", description: "Body summary / teaser" },
         status:  { type: "boolean", default: false, description: "Published flag for NON-moderated types. true to publish immediately. Ignored if moderationState is set; on a moderated type it is dropped automatically." },
         moderationState: { type: "string", description: "Moderation state for content_moderation types, e.g. 'draft' or 'published'. Takes precedence over status." },
-        fields:  { type: "object", description: "Additional field values keyed by Drupal machine name" },
+        fields:  { type: "object", description: "Scalar/attribute field values keyed by Drupal machine name. Do NOT put entity-reference fields here — Drupal rejects them as attributes; use `relationships`." },
+        relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value: { field_resource_type: { data: { type: 'taxonomy_term--resource_type', id: '<uuid>' } } }. Multi-value: { field_tags: { data: [{ type: 'taxonomy_term--tags', id: '<uuid>' }] } }." },
         dryRun:  { type: "boolean", default: false, description: "Validate and return a preview of the write without committing." },
+        returning: RETURNING_SCHEMA,
       },
     },
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status.",
+    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. Entity-reference fields go in `relationships`, not `fields`.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -380,8 +391,10 @@ export const definitions = [
         summary: { type: "string" },
         status:  { type: "boolean", description: "Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set." },
         moderationState: { type: "string", description: "Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status." },
-        fields:  { type: "object" },
+        fields:  { type: "object", description: "Scalar/attribute field values keyed by machine name. Entity-reference fields go in `relationships`, not here." },
+        relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }." },
         dryRun:  { type: "boolean", default: false, description: "Validate and return a preview of the update without committing." },
+        returning: RETURNING_SCHEMA,
       },
     },
   },

package/src/tools/reports.js

@@ -12,6 +12,7 @@ import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
 import { collectEntities, gatedReport, fieldValue, daysSince } from "../lib/reports-support.js";
+import { fetchRenderedMetaDescriptions } from "../lib/metatag-audit.js";
 
 // ---------------------------------------------------------------------------
 // Report implementations
@@ -395,8 +396,13 @@ async function userActivity({ site: siteName, inactiveDays = 90, limit = 50 }) {
  * (>60 too long, <20 too short) and the 300-word thin-content floor are SEO
  * heuristics, not hard Drupal limits.
  *
+ * The meta-description check reports its `metaSource`: "graphql" (rendered
+ * Metatag output — the accurate default), "jsonapi" (a plain description field
+ * on non-Metatag sites), or "unavailable" (neither could be read, in which case
+ * `missingMetaDescription` is `{ unavailable: true, reason }` — never a false 0).
+ *
  * @param {object} args - { site?, type?, sampleSize? }.
- * @returns {Promise<object>} Issue lists keyed by category, with counts.
+ * @returns {Promise<object>} Issue lists keyed by category, plus `metaSource`.
  * @throws {SecurityError} If reading the content type is not permitted.
  */
 async function seoAudit({ site: siteName, type, sampleSize = 100 }) {
@@ -412,26 +418,74 @@ async function seoAudit({ site: siteName, type, sampleSize = 100 }) {
     { entityType: "node", bundle: contentType, filters: [{ field: "status", op: "eq", value: true }] },
     sampleSize
   );
+
+  // Meta descriptions: prefer the *rendered* value from GraphQL Compose's
+  // normalized `metatag` field (defaults + overrides, resolved), which is the
+  // only source that reflects what the frontend emits. Fall back to a plain
+  // JSON:API description field for non-Metatag sites. The computed `metatag`
+  // field is deliberately NOT read over JSON:API — it is an unresolved
+  // placeholder there and counting it as "present" hides every gap (issue #120).
+  const rendered = await fetchRenderedMetaDescriptions(site, entities);
+  const metaSource = rendered.source === "graphql" ? "graphql" : resolveJsonapiMetaSource(entities);
+
   for (const n of entities) {
     const title = n.title ?? "";
     const bodyField = fieldValue(n, ["body"]);
     const body = (bodyField && typeof bodyField === "object" ? bodyField.value : bodyField) ?? "";
-    const meta = fieldValue(n, ["metaDescription", "field_meta_description", "metatag"]) ?? null;
     const wordCount = String(body).replace(/<[^>]+>/g, " ").split(/\s+/).filter(Boolean).length;
-    if (!meta) issues.get("missingMetaDescription").push({ id: n.id, title });
+    if (metaSource === "graphql") {
+      // Only nodes whose route resolved are knowable; skip the rest.
+      const hit = rendered.byId.get(n.id);
+      if (hit && !hit.description) issues.get("missingMetaDescription").push({ id: n.id, title });
+    } else if (metaSource === "jsonapi") {
+      if (!jsonapiMetaDescription(n)) issues.get("missingMetaDescription").push({ id: n.id, title });
+    }
     if (title.length > 60) issues.get("titleTooLong").push({ id: n.id, title, length: title.length });
     if (title.length < 20) issues.get("titleTooShort").push({ id: n.id, title, length: title.length });
     if (wordCount < 300 && wordCount > 0) issues.get("thinContent").push({ id: n.id, title, wordCount });
   }
-  return {
-    contentType,
-    scanned: entities.length,
-    approximate: false,
-    issues: Object.fromEntries(issueKeys.map((k) => {
-      const list = issues.get(k);
-      return [k, { count: list.length, nodes: list }];
-    })),
-  };
+
+  const issuesOut = Object.fromEntries(issueKeys.map((k) => {
+    const list = issues.get(k);
+    return [k, { count: list.length, nodes: list }];
+  }));
+  if (metaSource === "unavailable") {
+    // Do NOT emit a false "0 missing": we could not read a meta description at all.
+    issuesOut.missingMetaDescription = {
+      unavailable: true,
+      reason: rendered.reason ?? "no rendered metatag or JSON:API description field available",
+      count: null,
+      nodes: [],
+    };
+  }
+  return { contentType, scanned: entities.length, approximate: false, metaSource, issues: issuesOut };
+}
+
+/**
+ * Read a plain JSON:API description field (the non-Metatag path). The computed
+ * `metatag` field is excluded on purpose — it does not resolve over JSON:API.
+ *
+ * @param {object} n Canonical entity.
+ * @returns {string|undefined} Trimmed description, "" when the field is present
+ *   but empty, or undefined when no such field exists on the entity.
+ */
+function jsonapiMetaDescription(n) {
+  const v = fieldValue(n, ["metaDescription", "field_meta_description"]);
+  if (v === undefined) return undefined;
+  if (v && typeof v === "object") return String(v.value ?? "").trim();
+  return String(v ?? "").trim();
+}
+
+/**
+ * Decide whether a JSON:API description field is usable across the sample. If no
+ * node exposes the field at all, the field does not exist and we must report the
+ * meta check as unavailable rather than flagging every node as missing.
+ *
+ * @param {object[]} entities Canonical entities.
+ * @returns {"jsonapi"|"unavailable"}
+ */
+function resolveJsonapiMetaSource(entities) {
+  return entities.some((n) => jsonapiMetaDescription(n) !== undefined) ? "jsonapi" : "unavailable";
 }
 
 /**
@@ -580,7 +634,7 @@ export const definitions = [
   },
   {
     name: "drupal_report_seo_audit",
-    description: "SEO audit for a content type: missing meta descriptions, title length issues, and thin content (under 300 words). Returns node lists for each issue category.",
+    description: "SEO audit for a content type: missing meta descriptions, title length issues, and thin content (under 300 words). Returns node lists for each issue category. Meta descriptions use the rendered Metatag output via GraphQL when available (reported as `metaSource`); when no description source is readable it reports the meta check as unavailable rather than a false zero.",
     inputSchema: {
       type: "object",
       properties: {