drupal-mcp-connector 0.9.0 → 0.10.0

package/src/tools/moderation.js

@@ -0,0 +1,129 @@
+/**
+ * Tool group: content_moderation workflow.
+ *
+ * Thin, governed operations over the canonical backend for sites using Drupal's
+ * content_moderation (editorial) workflow:
+ *   - set a node's moderation_state (the governed write; draft -> needs_review -> published -> archived)
+ *   - list content filtered by moderation_state (e.g. "what's awaiting review")
+ *   - list the moderation states observed on a bundle's content
+ *
+ * Capability note: the authoritative set of states and the *valid transitions*
+ * from a given state live in workflow config and are not exposed over JSON:API.
+ * drupal_list_moderation_states therefore degrades to the DISTINCT states
+ * observed on existing content (authoritative:false); a full transition map
+ * requires the Drush bridge.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import { resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity } from "../lib/security.js";
+
+/** Read a node's moderation_state from a canonical entity, tolerating shapes. */
+function moderationStateOf(entity) {
+  const v = entity?.fields?.moderation_state;
+  if (Array.isArray(v)) return v[0]?.value ?? v[0] ?? null;
+  if (v && typeof v === "object") return v.value ?? null;
+  return v ?? null;
+}
+
+/**
+ * Transition a node to a moderation state (governed write).
+ * @param {object} args - { site?, type, id, state }.
+ * @returns {Promise<object>} The updated, redacted node.
+ * @throws {SecurityError} If writing node/type is not permitted.
+ */
+async function setModerationState({ site: siteName, type, id, state }) {
+  if (!state) throw new Error("A moderation 'state' is required (e.g. 'draft', 'published').");
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "update", "node", type);
+  const backend = await resolveBackend(site);
+  const entity = await backend.updateEntity({ entityType: "node", bundle: type, id, attributes: { moderation_state: state } });
+  return redactCanonicalEntity(entity, sec, "node");
+}
+
+/**
+ * List nodes of a type in a given moderation state, paged + redacted.
+ * @param {object} args - { site?, type, state, limit?, offset? }.
+ */
+async function contentByModerationState({ site: siteName, type, state, limit = 20, offset = 0 }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, "node", type);
+  const backend = await resolveBackend(site);
+  const res = await backend.listEntities({
+    entityType: "node", bundle: type,
+    filters: [{ field: "moderation_state", op: "eq", value: state }],
+    sort: [{ field: "changed", dir: "desc" }],
+    page: { limit, offset },
+  });
+  const nodes = res.entities.map((e) => redactCanonicalEntity(e, sec, "node"));
+  return { type, state, total: res.page?.total ?? nodes.length, approximate: res.approximate ?? false, offset, nextOffset: offset + nodes.length, nodes };
+}
+
+/**
+ * List the moderation states observed on a bundle's content (best-effort).
+ * @param {object} args - { site?, type, sample? }.
+ */
+async function listModerationStates({ site: siteName, type, sample = 50 }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, "node", type);
+  const backend = await resolveBackend(site);
+  const res = await backend.listEntities({ entityType: "node", bundle: type, page: { limit: sample } });
+  const states = [...new Set(res.entities.map(moderationStateOf).filter(Boolean))].sort();
+  return {
+    type,
+    states,
+    authoritative: false,
+    note: "Derived from observed content (sampled). The authoritative state set and valid transitions live in workflow config and require the Drush bridge.",
+  };
+}
+
+export const definitions = [
+  {
+    name: "drupal_set_moderation_state",
+    description: "Transition a content node to a moderation state (content_moderation), e.g. 'draft', 'needs_review', 'published', 'archived'. Governed write.",
+    inputSchema: {
+      type: "object", required: ["type", "id", "state"],
+      properties: {
+        site:  { type: "string" },
+        type:  { type: "string", description: "Content type machine name" },
+        id:    { type: "string", description: "Node UUID" },
+        state: { type: "string", description: "Target moderation state machine name" },
+      },
+    },
+  },
+  {
+    name: "drupal_content_by_moderation_state",
+    description: "List nodes of a content type currently in a given moderation state (e.g. what is in 'draft' or 'needs_review').",
+    inputSchema: {
+      type: "object", required: ["type", "state"],
+      properties: {
+        site:   { type: "string" },
+        type:   { type: "string", description: "Content type machine name" },
+        state:  { type: "string", description: "Moderation state machine name" },
+        limit:  { type: "number", default: 20 },
+        offset: { type: "number", default: 0 },
+      },
+    },
+  },
+  {
+    name: "drupal_list_moderation_states",
+    description: "List the moderation states observed on a content type's content (best-effort; authoritative transitions require the Drush bridge).",
+    inputSchema: {
+      type: "object", required: ["type"],
+      properties: {
+        site:   { type: "string" },
+        type:   { type: "string", description: "Content type machine name" },
+        sample: { type: "number", default: 50, description: "How many recent items to sample" },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_set_moderation_state:       setModerationState,
+  drupal_content_by_moderation_state: contentByModerationState,
+  drupal_list_moderation_states:     listModerationStates,
+};

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,
+};