drupal-mcp-connector 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Validate and URL-encode JSON:API path segments. The entity `id` is now checked
+  with `validateUuid` and `entityType`/`bundle` with `validateMachineName` (both
+  previously unused), and every segment is `encodeURIComponent`'d. This closes a
+  path-traversal vector where a crafted `id` (e.g. `../../user/user/<uuid>`) could
+  reach a different resource type and bypass the connector's entity-type/PII
+  policy. (Drupal core permissions were always still enforced.)
+
+### Added
+- A [Threat Model](docs/threat-model.md) documenting trust boundaries, threats &
+  mitigations, residual risks (drush SQL bridge; why filter-field names are not
+  machine-name-validated), and the 1.0 security-pass results (`npm audit` clean,
+  adversarial review).
+
 ## [0.9.0] - 2026-06-15
 
 ### Added
@@ -213,6 +252,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.
 
+[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
 [0.7.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.7.1

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,9 +185,10 @@ 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 |
 | [Deployment](docs/deployment.md) | Run the HTTPS transport in production: Docker, systemd, launchd, reverse proxy, pre-exposure checklist |
 | [Integration Contract](docs/integration-contract.md) | The connector ↔ Drupal-governance contract (identity, OAuth scopes, compatibility) |
 | [Versioning & Stability](docs/versioning.md) | Semver policy: the stable surface, deprecation process, MCP protocol + Node support |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "0.9.0",
+  "version": "0.10.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/lib/backends/jsonapi.js

@@ -8,6 +8,7 @@
  */
 
 import { drupalFetch, drupalUploadFile } from "../drupal-fetch.js";
+import { validateUuid, validateMachineName } from "../validate.js";
 import { Backend } from "./backend-interface.js";
 import {
   makeCanonicalEntity,
@@ -132,7 +133,12 @@ export class JsonApiBackend extends Backend {
    * @returns {string} e.g. "/jsonapi/node/article".
    */
   resourcePath(entityType, bundle) {
-    return `/jsonapi/${entityType}/${bundle}`;
+    // Validate before interpolating into the URL: machine names cannot contain
+    // path separators or `..`, so this blocks path-traversal to other resources
+    // (e.g. id="../../user/user/…"). Encoding is belt-and-suspenders.
+    validateMachineName(entityType, "entityType");
+    validateMachineName(bundle, "bundle");
+    return `/jsonapi/${encodeURIComponent(entityType)}/${encodeURIComponent(bundle)}`;
   }
 
   /**
@@ -219,7 +225,8 @@ export class JsonApiBackend extends Backend {
    * @returns {Promise<?import("../canonical.js").CanonicalEntity>} Entity, or null.
    */
   async getEntity({ entityType, bundle, id }) {
-    const data = await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${id}`);
+    validateUuid(id);
+    const data = await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`);
     return data?.data ? this.toCanonical(data.data) : null;
   }
 
@@ -275,12 +282,13 @@ export class JsonApiBackend extends Backend {
    * @returns {Promise<import("../canonical.js").CanonicalEntity>} The updated entity.
    */
   async updateEntity({ entityType, bundle, id, attributes = {}, relationships }) {
+    validateUuid(id);
     const buildPayload = (attrs) => {
       const payload = { data: { type: `${entityType}--${bundle}`, id, attributes: attrs } };
       if (relationships) payload.data.relationships = relationships;
       return payload;
     };
-    const data = await this.writeWithModerationFallback(`${this.resourcePath(entityType, bundle)}/${id}`, "PATCH", buildPayload, attributes);
+    const data = await this.writeWithModerationFallback(`${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`, "PATCH", buildPayload, attributes);
     return this.toCanonical(data.data);
   }
 
@@ -290,7 +298,8 @@ export class JsonApiBackend extends Backend {
    * @returns {Promise<void>}
    */
   async deleteEntity({ entityType, bundle, id }) {
-    await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${id}`, { method: "DELETE" });
+    validateUuid(id);
+    await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`, { method: "DELETE" });
   }
 
   /**

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