drupal-mcp-connector 0.9.1 → 1.0.0

package/src/tools/nodes.js

@@ -107,9 +107,8 @@ async function searchContent({ site: siteName, query, type, status, limit = 10 }
  * @param {object} args - { site?, type, title, body?, summary?, status?, moderationState?, fields? }.
  * @returns {Promise<object>} The created node descriptor from the backend.
  */
-async function createNode({ site: siteName, type, title, body, summary, status, moderationState, fields = {} }) {
+async function createNode({ site: siteName, type, title, body, summary, status, moderationState, fields = {}, dryRun = false }) {
   const site = getSiteConfig(siteName);
-  const backend = await resolveBackend(site);
   const attributes = { title, ...fields };
   if (moderationState !== undefined) {
     attributes.moderation_state = moderationState;
@@ -118,6 +117,8 @@ 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 };
+  const backend = await resolveBackend(site);
   return backend.createEntity({ entityType: "node", bundle: type, attributes });
 }
 
@@ -132,15 +133,16 @@ async function createNode({ site: siteName, type, title, body, summary, status,
  * @param {object} args - { site?, type, id, title?, body?, summary?, status?, moderationState?, fields? }.
  * @returns {Promise<object>} The updated node descriptor.
  */
-async function updateNode({ site: siteName, type, id, title, body, summary, status, moderationState, fields = {} }) {
+async function updateNode({ site: siteName, type, id, title, body, summary, status, moderationState, fields = {}, dryRun = false }) {
   const site = getSiteConfig(siteName);
-  const backend = await resolveBackend(site);
   const attributes = { ...fields };
   if (title !== undefined) attributes.title = title;
   if (moderationState !== undefined) attributes.moderation_state = moderationState;
   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 };
+  const backend = await resolveBackend(site);
   return backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
 }
 
@@ -151,8 +153,9 @@ async function updateNode({ site: siteName, type, id, title, body, summary, stat
  * @param {object} args - { site?, type, id }.
  * @returns {Promise<{success: boolean, deletedId: string}>}
  */
-async function deleteNode({ site: siteName, type, id }) {
+async function deleteNode({ site: siteName, type, id, dryRun = false }) {
   const site = getSiteConfig(siteName);
+  if (dryRun) return { dryRun: true, operation: "delete", entityType: "node", bundle: type, id };
   const backend = await resolveBackend(site);
   await backend.deleteEntity({ entityType: "node", bundle: type, id });
   return { success: true, deletedId: id };
@@ -219,6 +222,7 @@ export const definitions = [
         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" },
+        dryRun:  { type: "boolean", default: false, description: "Validate and return a preview of the write without committing." },
       },
     },
   },
@@ -237,6 +241,7 @@ export const definitions = [
         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" },
+        dryRun:  { type: "boolean", default: false, description: "Validate and return a preview of the update without committing." },
       },
     },
   },
@@ -249,6 +254,7 @@ export const definitions = [
         site: { type: "string" },
         type: { type: "string" },
         id:   { type: "string", description: "Node UUID" },
+        dryRun: { type: "boolean", default: false, description: "Validate and return a preview of the delete without committing." },
       },
     },
   },

package/src/tools/paragraphs.js

@@ -0,0 +1,143 @@
+/**
+ * Tool group: Paragraphs authoring helper.
+ *
+ * Paragraphs (the contrib Paragraphs module) are content-fragment entities of
+ * the `paragraph` entity type, one bundle per paragraph type (e.g. `text`,
+ * `image`, `cta`). They are NOT standalone content: a paragraph only appears on
+ * a site when a *host* entity (usually a node) references it from an
+ * Entity Reference Revisions (ERR) field. This module gives an authoring agent a
+ * focused way to mint a paragraph and fetch it back, plus the relationship data
+ * needed to embed it into a host field.
+ *
+ * Embedding model — IMPORTANT:
+ *   - Over JSON:API (this connector's default backend) a host references a
+ *     paragraph from its ERR field by a resource identifier object
+ *     `{ type: "paragraph--<bundle>", id: "<paragraph-uuid>" }`. Drupal resolves
+ *     the correct target_id + target_revision_id server-side from the UUID. Drop
+ *     `relationshipData` (returned by drupal_create_paragraph) into the host's
+ *     relationships map and call drupal_entity_update / drupal_update_node.
+ *   - The classic entity-API pair `{ target_id, target_revision_id }` (integer
+ *     ids) is the REST/Form-API shape, not the JSON:API shape. Those numeric ids
+ *     are not surfaced by the canonical entity here; prefer the UUID relationship
+ *     form above when writing through this connector.
+ *
+ * Both tools are governed: writes assert create permission for the `paragraph`
+ * entity type + bundle, reads assert read permission and are redacted per the
+ * site security policy. Writes default to whatever the backend default is for
+ * the bundle (paragraphs have no independent publish status of their own).
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import {
+  resolveSecurityConfig, assertWriteAllowed, assertReadAllowed, redactCanonicalEntity,
+} from "../lib/security.js";
+
+/**
+ * Build the JSON:API resource type string for a paragraph bundle.
+ * @param {string} bundle Paragraph type machine name.
+ * @returns {string} e.g. "paragraph--text".
+ */
+function resourceType(bundle) {
+  return `paragraph--${bundle}`;
+}
+
+/**
+ * Build the resource-identifier ref used to embed a paragraph in a host ERR /
+ * paragraph reference field over JSON:API.
+ * @param {string} bundle Paragraph type machine name.
+ * @param {string} id Paragraph UUID.
+ * @returns {{type: string, id: string}}
+ */
+function embedRef(bundle, id) {
+  return { type: resourceType(bundle), id };
+}
+
+const EMBED_NOTE =
+  "Paragraphs are not standalone content: embed this paragraph in a host entity's " +
+  "Entity Reference Revisions (paragraph) field. Over JSON:API, add `relationshipData` " +
+  "to the host field's relationship (e.g. drupal_entity_update / drupal_update_node with " +
+  "relationships: { field_paragraphs: { data: [ relationshipData ] } }). Drupal resolves " +
+  "target_id + target_revision_id from the UUID server-side.";
+
+/**
+ * Create a paragraph entity of the given type and return a ref suitable for
+ * embedding it in a host entity's paragraph/ERR field.
+ *
+ * @param {object} args - { site?, paragraphType, attributes? }.
+ *   `attributes` are paragraph field values keyed by Drupal machine name
+ *   (e.g. { field_body: { value, format } }). Use drupal_get_entity_schema for
+ *   entityType "paragraph" + the bundle to discover available fields.
+ * @returns {Promise<{paragraph: object, ref: {id: string, type: string},
+ *   relationshipData: {type: string, id: string}, note: string}>}
+ *   The created paragraph descriptor plus the embedding ref/relationship data.
+ * @throws {SecurityError} If creating paragraphs of this bundle is not permitted.
+ */
+async function createParagraph({ site: siteName, paragraphType, attributes = {} }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "create", "paragraph", paragraphType);
+  const backend = await resolveBackend(site);
+  const paragraph = await backend.createEntity({ entityType: "paragraph", bundle: paragraphType, attributes });
+  const bundle = paragraph.bundle || paragraphType;
+  const ref = embedRef(bundle, paragraph.id);
+  return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
+}
+
+/**
+ * Fetch a single paragraph by bundle + UUID, redacted per the site policy, and
+ * annotate it with the embedding ref.
+ *
+ * @param {object} args - { site?, paragraphType, id }.
+ * @returns {Promise<(object & {ref: {id: string, type: string}})|null>}
+ *   The redacted paragraph with an embedding `ref`, or null if not found.
+ * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
+ */
+async function getParagraph({ site: siteName, paragraphType, id }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, "paragraph", paragraphType);
+  const backend = await resolveBackend(site);
+  const entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
+  if (!entity) return null;
+  const redacted = redactCanonicalEntity(entity, sec, "paragraph");
+  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id) };
+}
+
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_create_paragraph",
+    description:
+      "Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id: <uuid> }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy.",
+    inputSchema: {
+      type: "object", required: ["paragraphType"],
+      properties: {
+        site:          { type: "string", description: "Named site (omit for default)" },
+        paragraphType: { type: "string", description: "Paragraph type / bundle machine name, e.g. 'text', 'image', 'cta'" },
+        attributes:    { type: "object", description: "Paragraph field values keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }" },
+      },
+    },
+  },
+  {
+    name: "drupal_get_paragraph",
+    description:
+      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph plus a `ref` ({ type: 'paragraph--<bundle>', id }) you can use to embed it in a host entity's paragraph / ERR field. Note: paragraphs are referenced (by target_id + target_revision_id in the entity API, or by UUID over JSON:API) from a host field rather than queried standalone in production. Governed by the site security policy.",
+    inputSchema: {
+      type: "object", required: ["paragraphType", "id"],
+      properties: {
+        site:          { type: "string" },
+        paragraphType: { type: "string", description: "Paragraph type / bundle machine name" },
+        id:            { type: "string", description: "Paragraph UUID" },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_create_paragraph: createParagraph,
+  drupal_get_paragraph:    getParagraph,
+};

package/src/tools/references.js

@@ -0,0 +1,133 @@
+/**
+ * Tool group: Reference resolution.
+ *
+ * A standalone, read-only helper that turns a human-friendly name or title into
+ * a stable Drupal UUID. Editors and agents rarely know UUIDs; they know labels
+ * ("the News term", "the About page"). This tool runs a single label filter via
+ * the backend's listEntities, ranks the results, and returns the best match plus
+ * any ambiguous candidates so the caller (or a human) can disambiguate before
+ * wiring the UUID into a create/update relationship.
+ *
+ * Scope: this NEVER writes. It only reads, and every read is gated by the site
+ * security policy (assertReadAllowed) and redacted (redactCanonicalEntity) before
+ * a label is derived — so a redacted label surfaces as "[REDACTED]" rather than
+ * leaking a protected value.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import { resolveSecurityConfig, assertReadAllowed, redactCanonicalEntity } from "../lib/security.js";
+
+/**
+ * Pick the label field to filter on for a given entity type.
+ *
+ * Nodes are keyed by `title`; taxonomy terms and users (and other label-as-name
+ * entities) are keyed by `name`. Anything else defaults to `name`, which is the
+ * most common Drupal label field outside of content nodes.
+ *
+ * @param {string} entityType Entity type machine name.
+ * @returns {"title"|"name"} The JSON:API field to filter against.
+ */
+function labelFieldFor(entityType) {
+  return entityType === "node" ? "title" : "name";
+}
+
+/**
+ * Derive a human label from a (already redacted) canonical entity.
+ *
+ * Nodes promote their label to the canonical `title`; taxonomy terms / users
+ * keep it in `fields.name`. We fall back across both so the resolver returns a
+ * meaningful label regardless of entity type. Redaction runs before this, so a
+ * protected label is already "[REDACTED]" here.
+ *
+ * @param {object} entity Redacted canonical entity.
+ * @param {string} labelField The field used for filtering ("title"|"name").
+ * @returns {?string} The best available label, or null.
+ */
+function labelOf(entity, labelField) {
+  return (
+    entity.title ??
+    // eslint-disable-next-line security/detect-object-injection -- labelField is a fixed literal ("title"|"name") from labelFieldFor, not user input
+    entity.fields?.[labelField] ??
+    entity.fields?.name ??
+    entity.fields?.title ??
+    null
+  );
+}
+
+/**
+ * Resolve a human name/title to a Drupal UUID.
+ *
+ * Strategy: filter the entity type/bundle by a label-contains query, redact the
+ * results, then rank — an exact (case-insensitive, trimmed) label match wins;
+ * otherwise the first contains-match is the best guess and the result is flagged
+ * ambiguous when more than one candidate came back without an exact hit.
+ *
+ * @param {object} args - { site?, entityType, bundle, name, limit? }.
+ * @returns {Promise<{resolved: boolean, ambiguous: boolean,
+ *   match: {id: string, title: ?string}|null, candidates: {id: string, title: ?string}[]}>}
+ *   The best match and any ambiguous candidates.
+ * @throws {SecurityError} If reading the entity type/bundle is not permitted.
+ */
+async function resolveReference({ site: siteName, entityType, bundle, name, limit = 10 }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, entityType, bundle);
+  const backend = await resolveBackend(site);
+
+  const field = labelFieldFor(entityType);
+  const res = await backend.listEntities({
+    entityType,
+    bundle,
+    filters: [{ field, op: "contains", value: name }],
+    page: { limit },
+  });
+
+  const candidates = res.entities
+    .map((e) => redactCanonicalEntity(e, sec, entityType))
+    .map((e) => ({ id: e.id, title: labelOf(e, field) }));
+
+  if (candidates.length === 0) {
+    return { resolved: false, ambiguous: false, match: null, candidates: [] };
+  }
+
+  const needle = String(name).trim().toLowerCase();
+  const exact = candidates.find(
+    (c) => typeof c.title === "string" && c.title.trim().toLowerCase() === needle
+  );
+  const match = exact ?? candidates[0];
+  const ambiguous = !exact && candidates.length > 1;
+
+  return { resolved: true, ambiguous, match, candidates };
+}
+
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_resolve_reference",
+    description:
+      "Resolve a human name or title to a Drupal entity UUID. Use this before " +
+      "creating or updating an entity reference when you only know the label " +
+      "(e.g. a taxonomy term name, a user name, or a node title) and not its UUID. " +
+      "Read-only: returns the best match { id, title } plus any ambiguous candidates. " +
+      "Filters on 'title' for nodes and 'name' for taxonomy_term / user.",
+    inputSchema: {
+      type: "object",
+      required: ["entityType", "bundle", "name"],
+      properties: {
+        site:       { type: "string", description: "Named site (omit for default)" },
+        entityType: { type: "string", description: "Entity type machine name, e.g. 'node', 'taxonomy_term', 'user'" },
+        bundle:     { type: "string", description: "Bundle machine name, e.g. 'article', 'tags', 'user'" },
+        name:       { type: "string", description: "Human name/title to resolve (matched as a substring)" },
+        limit:      { type: "number", default: 10, description: "Maximum candidates to consider" },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_resolve_reference: resolveReference,
+};

package/src/tools/reports-extra.js

@@ -0,0 +1,293 @@
+/**
+ * Tool group: Additional audit & reporting (reports_extra).
+ *
+ * Read-only content-quality and referential-integrity audits that complement
+ * the core reports module. Each handler asserts read access in-handler and
+ * returns a structured finding list. Reports that are bounded by a sampling cap
+ * flag `approximate: true` so callers know the result is best-effort rather than
+ * an exhaustive scan.
+ *
+ * This module deliberately does NOT touch src/tools/reports.js — it is additive.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
+import { collectEntities, fieldValue } from "../lib/reports-support.js";
+
+/**
+ * Determine whether a canonical field/relationship value counts as "empty".
+ * Handles scalars, JSON:API value-objects ({value}), arrays, and relationship
+ * refs ({id} / [{id}, …] / null).
+ * @param {*} value A value read off an entity's base props, `fields`, or `relationships`.
+ * @returns {boolean} True when the value is absent or carries no content.
+ */
+function isEmptyValue(value) {
+  if (value === undefined || value === null || value === "") return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "object") {
+    // Relationship ref ({id, ...}) is non-empty.
+    if ("id" in value) return !value.id;
+    // JSON:API field value-object ({value, ...}); also accept {target_id}/{uri}.
+    if ("value" in value) return value.value === undefined || value.value === null || value.value === "";
+    if ("target_id" in value) return value.target_id === undefined || value.target_id === null;
+    if ("uri" in value) return !value.uri;
+    return Object.keys(value).length === 0;
+  }
+  return false;
+}
+
+/**
+ * Read a field value from a canonical entity, looking in `fields` first and then
+ * `relationships` (so a single `field` argument works for both scalar fields and
+ * entity-reference fields).
+ * @param {object} entity Canonical entity.
+ * @param {string} field Field machine name.
+ * @returns {{value: *, present: boolean}} The resolved value and whether the key existed at all.
+ */
+function readField(entity, field) {
+  const fromField = fieldValue(entity, [field]);
+  if (fromField !== undefined) return { value: fromField, present: true };
+  const rels = new Map(Object.entries(entity.relationships ?? {}));
+  if (rels.has(field)) {
+    return { value: rels.get(field), present: true };
+  }
+  return { value: undefined, present: false };
+}
+
+/**
+ * Flatten a relationship value into an array of { id, entityType, bundle } refs,
+ * dropping null/empty entries.
+ * @param {*} rel A normalized relationship value (ref, array of refs, or null).
+ * @returns {Array<{id: string, entityType: ?string, bundle: ?string}>} Concrete refs, de-duped by id.
+ */
+function refsOf(rel) {
+  if (!rel) return [];
+  const list = Array.isArray(rel) ? rel : [rel];
+  const seen = new Set();
+  const out = [];
+  for (const r of list) {
+    if (!r || !r.id || seen.has(r.id)) continue;
+    seen.add(r.id);
+    out.push(r);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Report implementations
+// ---------------------------------------------------------------------------
+
+/**
+ * Unpublished / draft content for a content type.
+ *
+ * @param {object} args - { site?, type?, limit? }. `type` defaults to "article".
+ * @returns {Promise<{contentType: string, approximate: boolean,
+ *   totalUnpublished: number, findings: object[]}>} Matching unpublished nodes.
+ * @throws {SecurityError} If reading the content type is not permitted.
+ */
+async function unpublished({ site: siteName, type, limit = 50 }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, "node", type);
+  const backend = await resolveBackend(site);
+  const contentType = type || "article";
+  const res = await backend.listEntities({
+    entityType: "node", bundle: contentType,
+    filters: [{ field: "status", op: "eq", value: false }],
+    sort: [{ field: "changed", dir: "desc" }],
+    page: { limit },
+  });
+  return {
+    contentType,
+    approximate: res.approximate ?? false,
+    totalUnpublished: res.page?.total ?? res.entities.length,
+    findings: res.entities.map((n) => ({
+      id: n.id,
+      title: n.title,
+      status: "unpublished",
+      changed: n.changed,
+      path: n.url,
+    })),
+  };
+}
+
+/**
+ * Entities of a content type where a given field is empty (e.g. a missing meta
+ * description or image). Works for scalar fields and entity-reference fields.
+ * Sampling-bounded: flags `approximate` when the scan hits the sample cap while
+ * more results remain.
+ *
+ * @param {object} args - { site?, type?, field, sampleSize? }. `field` is required.
+ * @returns {Promise<object>} Per-entity findings plus scan metadata.
+ * @throws {Error} If no field is supplied.
+ * @throws {SecurityError} If reading the content type is not permitted.
+ */
+async function missingField({ site: siteName, type, field, sampleSize = 100 }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, "node", type);
+  if (!field) throw new Error("missingField requires a field machine name.");
+  const backend = await resolveBackend(site);
+  const contentType = type || "article";
+  const entities = await collectEntities(
+    backend,
+    { entityType: "node", bundle: contentType, sort: [{ field: "changed", dir: "desc" }] },
+    sampleSize
+  );
+  const findings = [];
+  for (const e of entities) {
+    const { value } = readField(e, field);
+    if (isEmptyValue(value)) {
+      findings.push({ id: e.id, title: e.title, field, status: e.status ? "published" : "unpublished", path: e.url });
+    }
+  }
+  const approximate = entities.length >= sampleSize;
+  return {
+    contentType,
+    field,
+    scanned: entities.length,
+    sampled: entities.length,
+    sampleSize,
+    approximate,
+    totalMissing: findings.length,
+    note: approximate
+      ? "Result is sampling-bounded; more entities may exist beyond the sample cap."
+      : undefined,
+    findings,
+  };
+}
+
+/**
+ * Orphaned entity references: sampled entities whose entity-reference fields
+ * point at targets that no longer exist. Best-effort — each distinct referenced
+ * target is probed once via getEntity; a null result or a fetch error is treated
+ * as an unresolved (orphaned) target. Sampling-bounded, so `approximate` is set
+ * when the entity scan is capped.
+ *
+ * @param {object} args - { site?, type?, sampleSize? }. `type` defaults to "article".
+ * @returns {Promise<object>} Orphaned-reference findings plus scan metadata.
+ * @throws {SecurityError} If reading the content type is not permitted.
+ */
+async function orphanedReferences({ site: siteName, type, sampleSize = 50 }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, "node", type);
+  const backend = await resolveBackend(site);
+  const contentType = type || "article";
+  const entities = await collectEntities(
+    backend,
+    { entityType: "node", bundle: contentType, sort: [{ field: "changed", dir: "desc" }] },
+    sampleSize
+  );
+
+  // Cache resolution results across all sampled entities so a target is only
+  // looked up once (de-dupes both within and across entities).
+  const resolution = new Map(); // id -> boolean (true = exists)
+  /**
+   * Resolve whether a referenced target exists, caching the result.
+   * @param {{id: string, entityType: ?string, bundle: ?string}} ref Reference to probe.
+   * @returns {Promise<boolean>} True if the target resolves to an entity.
+   */
+  async function exists(ref) {
+    if (resolution.has(ref.id)) return resolution.get(ref.id);
+    let ok = false;
+    try {
+      // entityType/bundle are derived from JSON:API "type"; both required to fetch.
+      if (ref.entityType && ref.bundle) {
+        const target = await backend.getEntity({ entityType: ref.entityType, bundle: ref.bundle, id: ref.id });
+        ok = Boolean(target);
+      } else {
+        // Cannot address the target without a concrete type+bundle; treat as
+        // unresolved rather than silently passing.
+        ok = false;
+      }
+    } catch {
+      ok = false;
+    }
+    resolution.set(ref.id, ok);
+    return ok;
+  }
+
+  const findings = [];
+  for (const e of entities) {
+    for (const [fieldName, rel] of Object.entries(e.relationships ?? {})) {
+      for (const ref of refsOf(rel)) {
+        const ok = await exists(ref);
+        if (!ok) {
+          findings.push({
+            id: e.id,
+            title: e.title,
+            field: fieldName,
+            targetId: ref.id,
+            targetEntityType: ref.entityType,
+            targetBundle: ref.bundle,
+          });
+        }
+      }
+    }
+  }
+
+  const approximate = entities.length >= sampleSize;
+  return {
+    contentType,
+    scanned: entities.length,
+    sampleSize,
+    approximate,
+    totalOrphaned: findings.length,
+    note: approximate
+      ? "Best-effort: reference integrity is checked over a sampling-bounded set of entities."
+      : "Best-effort: each referenced target is probed once via JSON:API.",
+    findings,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_report_unpublished",
+    description: "List unpublished/draft content of a given type. Returns a finding list with titles, last-changed dates, and paths. Useful for surfacing forgotten drafts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        site:  { type: "string" },
+        type:  { type: "string", description: "Content type machine name (default: article)" },
+        limit: { type: "number", default: 50, description: "Max unpublished nodes to return" },
+      },
+    },
+  },
+  {
+    name: "drupal_report_missing_field",
+    description: "Find entities of a content type where a given field is empty (e.g. a missing meta description, image, or summary). Works for scalar fields and entity-reference fields. Sampling-bounded — flags 'approximate' when the scan is capped.",
+    inputSchema: {
+      type: "object", required: ["field"],
+      properties: {
+        site:       { type: "string" },
+        type:       { type: "string", description: "Content type machine name (default: article)" },
+        field:      { type: "string", description: "Field machine name to check for emptiness, e.g. 'field_meta_description', 'field_image'" },
+        sampleSize: { type: "number", default: 100, description: "Max entities to scan" },
+      },
+    },
+  },
+  {
+    name: "drupal_report_orphaned_references",
+    description: "Find entities whose entity-reference fields point at targets that no longer exist (orphaned references). Best-effort: samples entities and probes each distinct referenced target via JSON:API. Flags 'approximate' when sampling-bounded.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        site:       { type: "string" },
+        type:       { type: "string", description: "Content type machine name to scan (default: article)" },
+        sampleSize: { type: "number", default: 50, description: "Max entities to scan for broken references" },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_report_unpublished:           unpublished,
+  drupal_report_missing_field:         missingField,
+  drupal_report_orphaned_references:   orphanedReferences,
+};