drupal-mcp-connector 0.9.1 → 1.0.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-06-15
+
+First stable release. The tool surface, security model, and configuration
+schema are now considered stable and will follow semantic versioning.
+
+### Added
+- Stable **1.0** milestone: 89 tools across 20 modules with full read +
+  governed-write coverage (node/entity CRUD, revisions, moderation, scheduler,
+  fields, references, bulk operations, translations, paragraphs, structure,
+  search, and reports), `dryRun` preview on every write tool, the JSON:API and
+  GraphQL backends, the `write-plane` security preset, and multi-client launch
+  support (Claude Code, Claude Desktop, Grok Build).
+
+### Changed
+- No functional changes since 0.10.0 — this release promotes the 0.10.x feature
+  set to a stable 1.0 line.
+
+## [0.10.0] - 2026-06-15
+
+### Added
+- **`dryRun` option** on the node + generic-entity write tools (`drupal_create_node`,
+  `drupal_update_node`, `drupal_delete_node`, `drupal_entity_create`,
+  `drupal_entity_update`, `drupal_entity_delete`) (#42). When `true`, the tool runs
+  the security checks and builds the final payload, then returns a preview
+  (`{ dryRun: true, operation, entityType, bundle, id?, attributes }`) **without
+  writing** — no backend call is made. Lets an agent confirm intent safely.
+- **23 new tools across 11 modules** (66 → 89 tools), toward 1.0 feature coverage:
+  - **Revisions** (#37): `drupal_list_revisions`, `drupal_get_revision`, `drupal_revert_revision` (governed revert; JSON:API addresses revisions by id / latest-version / working-copy — full history enumeration needs the Drush bridge).
+  - **Moderation** (#38): `drupal_set_moderation_state`, `drupal_content_by_moderation_state`, `drupal_list_moderation_states` (content_moderation).
+  - **Scheduler** (#39): `drupal_schedule_publish` (publish_on / unpublish_on).
+  - **Fields** (#40): `drupal_describe_fields` (bundle field schema; best-effort, Drush-enhanced).
+  - **References** (#41): `drupal_resolve_reference` (name/title → UUID).
+  - **Bulk** (#43): `drupal_bulk_create`, `drupal_bulk_update` (per-item partial-failure reporting).
+  - **Translations** (#45): `drupal_list_translations`, `drupal_create_translation`.
+  - **Paragraphs** (#44): `drupal_create_paragraph`, `drupal_get_paragraph`.
+  - **Structure** (#46): `drupal_list_menu_links`, `drupal_create_menu_link`, `drupal_list_blocks`, `drupal_create_block`.
+  - **Search** (#47): `drupal_search` (best-effort title match; Search API/Solr-ready).
+  - **Reports (extra)** (#48): `drupal_report_orphaned_references`, `drupal_report_unpublished`, `drupal_report_missing_field`.
+  - All reads are policy-redacted; all writes assert the security policy. New write verbs (`bulk_`/`revert_`/`schedule_`/`set_`) added to the middleware write-gating prefixes.
+
 ## [0.9.1] - 2026-06-15
 
 ### Security
@@ -229,6 +269,8 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[1.0.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v1.0.0
+[0.10.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.10.0
 [0.9.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.9.1
 [0.9.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.9.0
 [0.8.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.8.0

package/README.md

@@ -51,7 +51,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 
 ## Features
 
-### 66 Tools Across 9 Modules
+### 89 Tools Across 20 Modules
 
 | Module | Tools |
 |--------|-------|
@@ -64,6 +64,17 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 | **Site** | Site info, content-type discovery, configured-site listing |
 | **Reports** | Content summary, stale content, field completeness, SEO/accessibility audits, taxonomy usage, user activity, revision hotspots (10 read-only reports) |
 | **Drush** | Cache rebuild, cron, config sync, module management, DB updates via SSH |
+| **Revisions** | List/get entity revisions; governed revert to a prior revision |
+| **Moderation** | Set moderation state; list content by state; observed-state discovery (content_moderation) |
+| **Scheduler** | Set publish-on / unpublish-on dates (Scheduler module) |
+| **Fields** | Describe a bundle's fields (type/required/cardinality, best-effort) |
+| **References** | Resolve a human name/title to an entity UUID for relationship fields |
+| **Bulk** | Bulk create/update with per-item partial-failure reporting |
+| **Translations** | List + create entity translations |
+| **Paragraphs** | Create/get Paragraph components for embedding in host fields |
+| **Structure** | Menu links + custom blocks (list/create) |
+| **Search** | Best-effort content search (title match; Search API/Solr-ready) |
+| **Reports (extra)** | Orphaned references, unpublished content, missing-field audits |
 
 ### MCP Resources
 Browsable, always-fresh context the client can read without calling a tool:
@@ -174,7 +185,7 @@ Governance keys off the authenticated account's role and OAuth scopes — not re
 | [OAuth client_credentials](docs/oauth-client-credentials.md) | Production OAuth deploy: scope→role mapping, JSON:API writes, config persistence, secret handling, troubleshooting |
 | [Architecture](docs/architecture.md) | Backend abstraction, canonical model, and how to extend it |
 | [GraphQL Setup](docs/graphql-local-setup.md) | GraphQL Compose backend + local TLS notes |
-| [Tools Reference](docs/tools-reference.md) | Full reference for all 66 tools |
+| [Tools Reference](docs/tools-reference.md) | Full reference for all 89 tools |
 | [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
 | [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
 | [Threat Model](docs/threat-model.md) | Trust boundaries, threats & mitigations, residual risks, and the security-pass results |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "0.9.1",
+  "version": "1.0.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

@@ -56,12 +56,24 @@ import * as site     from "./tools/site.js";
 import * as entities from "./tools/entities.js";
 import * as reports  from "./tools/reports.js";
 import * as drush    from "./tools/drush.js";
+import * as revisions    from "./tools/revisions.js";
+import * as moderation   from "./tools/moderation.js";
+import * as scheduler    from "./tools/scheduler.js";
+import * as fields       from "./tools/fields.js";
+import * as references   from "./tools/references.js";
+import * as bulk         from "./tools/bulk.js";
+import * as translations from "./tools/translations.js";
+import * as paragraphs   from "./tools/paragraphs.js";
+import * as structure    from "./tools/structure.js";
+import * as search       from "./tools/search.js";
+import * as reportsExtra from "./tools/reports-extra.js";
 
 // ---------------------------------------------------------------------------
 // Aggregate tools
 // ---------------------------------------------------------------------------
 
-const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush];
+const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
+  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, search, reportsExtra];
 
 // Flatten every module's tool definitions into one ListTools payload, and merge
 // their handler maps into a single closed dispatch table keyed by tool name.
@@ -81,7 +93,9 @@ const WRITE_PREFIXES       = ["drupal_create_", "drupal_update_", "drupal_upload
   "drupal_block_",  "drupal_drush_cache", "drupal_drush_cron",
   "drupal_drush_config_export", "drupal_drush_config_import",
   "drupal_drush_updatedb", "drupal_drush_module_enable",
-  "drupal_drush_module_disable", "drupal_drush_user_create"];
+  "drupal_drush_module_disable", "drupal_drush_user_create",
+  // v1.0 feature tools that perform writes but don't start with create_/update_:
+  "drupal_bulk_", "drupal_revert_", "drupal_schedule_", "drupal_set_"];
 const DESTRUCTIVE_PREFIXES = ["drupal_delete_", "drupal_drush_module_disable"];
 
 /**

package/src/tools/bulk.js

@@ -0,0 +1,154 @@
+/**
+ * Tool group: Bulk operations.
+ *
+ * Create or update many entities of a single type + bundle in one call. The
+ * write permission is asserted ONCE up front (the whole batch targets one
+ * type/bundle), then each item is processed in its own try/catch so a single
+ * failure does not abort the batch — callers get partial success with a
+ * per-item result and a roll-up summary.
+ *
+ * The hardened JSON:API backend is reused as-is (path validation, the
+ * content_moderation status-on-403 fallback, etc. all apply per item).
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import { resolveSecurityConfig, assertWriteAllowed } from "../lib/security.js";
+
+/**
+ * Normalize an unknown thrown value into a human-readable message.
+ *
+ * @param {unknown} err - The caught error.
+ * @returns {string} A message string.
+ */
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Bulk-create entities of one type + bundle. Write permission is asserted once;
+ * each item is created independently so the batch continues past failures.
+ *
+ * @param {object} args - { site?, entityType, bundle, items: [{ attributes?, relationships? }] }.
+ * @returns {Promise<{results: object[], summary: {created: number, failed: number}}>}
+ *   Per-item { index, success, id? | error } plus a roll-up summary.
+ * @throws {SecurityError} If creating the type/bundle is not permitted.
+ */
+async function bulkCreate({ site: siteName, entityType, bundle, items = [] }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "create", entityType, bundle);
+  const backend = await resolveBackend(site);
+
+  const results = [];
+  let created = 0;
+  let failed = 0;
+  for (const [index, rawItem] of items.entries()) {
+    const item = rawItem || {};
+    try {
+      const entity = await backend.createEntity({
+        entityType, bundle,
+        attributes: item.attributes ?? {},
+        relationships: item.relationships ?? {},
+      });
+      created += 1;
+      results.push({ index, success: true, id: entity?.id });
+    } catch (err) {
+      failed += 1;
+      results.push({ index, success: false, error: errorMessage(err) });
+    }
+  }
+  return { results, summary: { created, failed } };
+}
+
+/**
+ * Bulk-update entities of one type + bundle. Write permission is asserted once;
+ * each item is updated independently so the batch continues past failures. An
+ * item missing an id is reported as a per-item failure rather than aborting.
+ *
+ * @param {object} args - { site?, entityType, bundle, items: [{ id, attributes?, relationships? }] }.
+ * @returns {Promise<{results: object[], summary: {updated: number, failed: number}}>}
+ *   Per-item { index, success, id? | error } plus a roll-up summary.
+ * @throws {SecurityError} If updating the type/bundle is not permitted.
+ */
+async function bulkUpdate({ site: siteName, entityType, bundle, items = [] }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "update", entityType, bundle);
+  const backend = await resolveBackend(site);
+
+  const results = [];
+  let updated = 0;
+  let failed = 0;
+  for (const [index, rawItem] of items.entries()) {
+    const item = rawItem || {};
+    try {
+      if (!item.id) throw new Error("Missing 'id' for update item");
+      const entity = await backend.updateEntity({
+        entityType, bundle, id: item.id,
+        attributes: item.attributes ?? {},
+        relationships: item.relationships ?? {},
+      });
+      updated += 1;
+      results.push({ index, success: true, id: entity?.id ?? item.id });
+    } catch (err) {
+      failed += 1;
+      results.push({ index, success: false, error: errorMessage(err) });
+    }
+  }
+  return { results, summary: { updated, failed } };
+}
+
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+
+const itemAttributesSchema = {
+  attributes:    { type: "object", description: "Field values keyed by Drupal machine name" },
+  relationships: { type: "object", description: "Relationship data keyed by field name" },
+};
+
+export const definitions = [
+  {
+    name: "drupal_bulk_create",
+    description: "Create many entities of a single type + bundle in one call. Permission is checked once; each item is created independently, so the batch continues past individual failures (partial success). Returns per-item { index, success, id | error } and a summary { created, failed }. Writes default to unpublished/draft.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle", "items"],
+      properties: {
+        site:       { type: "string" },
+        entityType: { type: "string", description: "Entity type machine name, e.g. 'node', 'taxonomy_term'" },
+        bundle:     { type: "string", description: "Bundle machine name, e.g. 'article'" },
+        items: {
+          type: "array",
+          description: "Entities to create. Each is { attributes?, relationships? }.",
+          items: { type: "object", properties: { ...itemAttributesSchema } },
+        },
+      },
+    },
+  },
+  {
+    name: "drupal_bulk_update",
+    description: "Update many entities of a single type + bundle in one call. Permission is checked once; each item is updated independently, so the batch continues past individual failures (partial success). Each item requires an 'id' (UUID); items missing an id are reported as per-item failures. Returns per-item { index, success, id | error } and a summary { updated, failed }.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle", "items"],
+      properties: {
+        site:       { type: "string" },
+        entityType: { type: "string", description: "Entity type machine name" },
+        bundle:     { type: "string", description: "Bundle machine name" },
+        items: {
+          type: "array",
+          description: "Entities to update. Each is { id, attributes?, relationships? }.",
+          items: {
+            type: "object", required: ["id"],
+            properties: { id: { type: "string", description: "Entity UUID" }, ...itemAttributesSchema },
+          },
+        },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_bulk_create: bulkCreate,
+  drupal_bulk_update: bulkUpdate,
+};

package/src/tools/entities.js

@@ -56,10 +56,11 @@ 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 = {} }) {
+async function createEntity({ site: siteName, entityType, bundle, attributes = {}, relationships = {}, dryRun = false }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "create", entityType, bundle);
+  if (dryRun) return { dryRun: true, operation: "create", entityType, bundle, attributes, relationships };
   const backend = await resolveBackend(site);
   return backend.createEntity({ entityType, bundle, attributes, relationships });
 }
@@ -71,10 +72,11 @@ 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 = {} }) {
+async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {}, dryRun = false }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", entityType, bundle);
+  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 });
 }
@@ -86,10 +88,11 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
  * @returns {Promise<{success: boolean, deletedId: string, entityType: string, bundle: string}>}
  * @throws {SecurityError} If deleting the type/bundle is not permitted.
  */
-async function deleteEntity({ site: siteName, entityType, bundle, id }) {
+async function deleteEntity({ site: siteName, entityType, bundle, id, dryRun = false }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertDeleteAllowed(sec, entityType, bundle, id);
+  if (dryRun) return { dryRun: true, operation: "delete", entityType, bundle, id };
   const backend = await resolveBackend(site);
   await backend.deleteEntity({ entityType, bundle, id });
   return { success: true, deletedId: id, entityType, bundle };
@@ -209,6 +212,7 @@ export const definitions = [
         bundle:        { type: "string" },
         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." },
       },
     },
   },
@@ -224,6 +228,7 @@ export const definitions = [
         id:            { type: "string" },
         attributes:    { type: "object" },
         relationships: { type: "object" },
+        dryRun:        { type: "boolean", default: false, description: "Validate and return a preview of the update without committing." },
       },
     },
   },
@@ -237,6 +242,7 @@ export const definitions = [
         entityType: { type: "string" },
         bundle:     { type: "string" },
         id:         { type: "string" },
+        dryRun:     { type: "boolean", default: false, description: "Validate and return a preview of the delete without committing." },
       },
     },
   },

package/src/tools/fields.js

@@ -0,0 +1,135 @@
+/**
+ * Tool group: Field introspection.
+ *
+ * Read-only discovery of the fields available on a Drupal entity type + bundle.
+ *
+ * The always-available source is `backend.getEntitySchema(entityType, bundle)`,
+ * which derives a schema by SAMPLING an existing entity over JSON:API/GraphQL.
+ * Sampling can only observe the fields a sampled entity happens to populate and
+ * the runtime shape of their values — it CANNOT see authoritative Field API
+ * metadata. So every result is flagged `approximate: true`, and per-field
+ * `required` / `cardinality` / `allowedValues` are best-effort hints derived
+ * from the sampled value shape (e.g. an `array<…>` sampled type implies a
+ * multi-valued field). Authoritative metadata comes from the Drush bridge
+ * (Field API: `field_config` / `base_field_definitions`), which these tools do
+ * not require — see the `note` on the response.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
+
+const SAMPLING_NOTE =
+  "Schema derived by sampling an existing entity, so it is APPROXIMATE: only " +
+  "fields populated on the sampled entity are visible, and required/cardinality/" +
+  "allowedValues are inferred from value shape rather than read from Drupal's " +
+  "Field API. For authoritative field definitions (required flags, exact " +
+  "cardinality, allowed values, widget/storage settings) use the Drush bridge " +
+  "(field config), which reads the Field API directly.";
+
+const EMPTY_SCHEMA_NOTE =
+  "No entities of this type/bundle exist yet, so sampling found no fields. " +
+  "Create one entity, or use the Drush bridge (Field API), to introspect fields.";
+
+/**
+ * Infer a cardinality hint from a sampled attribute type string.
+ * `getEntitySchema` reports list-valued fields as `array<...>`; a leading
+ * `array<` is the only cheap multi-value signal sampling can give us.
+ * @param {string} type Sampled type string from the backend schema.
+ * @returns {{cardinality: number}|{}} `{cardinality: -1}` for arrays, else `{}`.
+ */
+function cardinalityHint(type) {
+  return typeof type === "string" && type.startsWith("array<") ? { cardinality: -1 } : {};
+}
+
+/**
+ * Build a per-field descriptor from a sampled attribute entry.
+ * @param {string} name Field machine name.
+ * @param {string} type Sampled type string.
+ * @returns {object} `{ name, type, kind:'attribute', approximate, [cardinality] }`.
+ */
+function attributeField(name, type) {
+  return { name, type, kind: "attribute", ...cardinalityHint(type), approximate: true };
+}
+
+/**
+ * Build a per-field descriptor from a sampled relationship entry.
+ * @param {string} name Relationship field machine name.
+ * @returns {object} `{ name, type:'relationship', kind:'relationship', approximate }`.
+ */
+function relationshipField(name) {
+  return { name, type: "relationship", kind: "relationship", approximate: true };
+}
+
+/**
+ * Describe the fields of a Drupal entity type + bundle.
+ *
+ * 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`).
+ * @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.
+ */
+async function describeFields({ site: siteName, type, bundle }) {
+  const entityType = type;
+  const resolvedBundle = bundle || type;
+
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, entityType, resolvedBundle);
+
+  const backend = await resolveBackend(site);
+  const schema = await backend.getEntitySchema(entityType, resolvedBundle);
+
+  const fields = [
+    ...Object.entries(schema.attributes ?? {}).map(([name, t]) => attributeField(name, t)),
+    ...Object.keys(schema.relationships ?? {}).map((name) => relationshipField(name)),
+  ].sort((a, b) => a.name.localeCompare(b.name));
+
+  const sampledEmpty = fields.length === 0;
+
+  return {
+    entityType: schema.entityType ?? entityType,
+    bundle: schema.bundle ?? resolvedBundle,
+    ...(schema.resourceType ? { resourceType: schema.resourceType } : {}),
+    approximate: true,
+    fieldCount: fields.length,
+    fields,
+    note: sampledEmpty ? EMPTY_SCHEMA_NOTE : SAMPLING_NOTE,
+    authoritativeSource: "drush-bridge (Drupal Field API)",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_describe_fields",
+    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.",
+    inputSchema: {
+      type: "object",
+      required: ["site", "type"],
+      properties: {
+        site:   { type: "string", description: "Configured site name." },
+        type:   { type: "string", description: "Entity type machine name, e.g. 'node', 'taxonomy_term', 'user', 'media'." },
+        bundle: { type: "string", description: "Bundle machine name, e.g. 'article'. Defaults to the entity type for single-bundle types (e.g. 'user')." },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_describe_fields: describeFields,
+};

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