drupal-mcp-connector 2.15.0 → 2.15.1

package/.agents/commands/drupal-get-paragraph.md

@@ -1,11 +1,11 @@
 ---
-description: "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy."
+description: "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy."
 argument-hint: "<paragraphType> <id> [site] [langcode] [revisionId]"
 ---
 
 Call the MCP tool `drupal_get_paragraph`.
 
-Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.
+Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -16,6 +16,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `langcode` (string): Target language for the unpublished working translation (e.g. 'es').
-- `revisionId` (string): Paragraph revision id the host already pins.
+- `revisionId` (string): Paragraph revision id the host already pins (ERR meta.target_revision_id). Honored on the read; a different served vid is an error.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-list-nodes.md

@@ -1,11 +1,11 @@
 ---
-description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors."
+description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set."
 argument-hint: "<type> [site] [status] [limit] [offset] [filters] [sort]"
 ---
 
 Call the MCP tool `drupal_list_nodes`.
 
-List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors.
+List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.1] - 2026-09-10
+
+### Fixed
+- **`drupal_get_paragraph` honors `revisionId` and refuses a default-revision fallback (#292).**
+  Passing the host pin without `langcode` now reads JSON:API
+  `?resourceVersion=id:<vid>`. If Drupal serves a different
+  `drupal_internal__revision_id` (or nothing), the tool errors instead of
+  returning the live default revision. `ref.meta.target_revision_id` is the
+  served vid. `langcode` still uses Sentinel's draft read.
+- **`drupal_list_nodes` no longer reports a Drupal-capped page as the exact collection total (#291).**
+  Core JSON:API silently caps `page[limit]` at 50 and does not send `meta.count`.
+  The connector was treating that page length as `total` with `approximate: false`,
+  so a `limit: 100` call on a 54-item collection returned 50 and looked complete.
+  `listEntities` now follows `links.next` to fill a larger requested limit (up to
+  1000) and only reports an exact `total` when `meta.count` is present or the
+  window reached the end. Otherwise `approximate` is true and `hasNext` is
+  returned on the tool result.
+
 ## [2.15.0] - 2026-09-10
 
 ### Fixed
@@ -1553,6 +1571,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.
 
+[2.15.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.1
+[2.15.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.0
 [2.14.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.2
 [2.14.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.1
 [2.14.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.0

package/README.md

@@ -1,6 +1,6 @@
 # drupal-mcp-connector
 
-> A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed content tools, audit reports, and an SSH Drush bridge.
+> A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed draft translations, content tools, audit reports, and an SSH Drush bridge.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.15.0",
-  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
+  "version": "2.15.1",
+  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",
   "bin": {

package/src/lib/backends/jsonapi.js

@@ -24,14 +24,30 @@ import { isPositiveNid, normalizeAlias, PATH_ALIAS_ENTITY_TYPE } from "../path-a
 // governed read/write workflows explicitly need.
 const INTERNAL_ATTR_RE = /^drupal_internal__/;
 
-// countEntities() pagination. Drupal core JSON:API returns no total in `meta`,
-// so an exact count is obtained by walking pages until `links.next` is gone.
-// COUNT_PAGE_SIZE is Drupal's default max page size; COUNT_MAX_RECORDS bounds
-// the walk so a huge collection can't issue unbounded requests (mirrors the
-// GraphQL backend's MAX_CLIENT_RECORDS) — past it the count is approximate.
+// countEntities() / listEntities() pagination. Drupal core JSON:API returns no
+// total in `meta` and silently caps `page[limit]` at OffsetPage::SIZE_MAX
+// (50 by default). COUNT_PAGE_SIZE matches that default; COUNT_MAX_RECORDS
+// bounds a walk so a huge collection can't issue unbounded requests (mirrors
+// the GraphQL backend's MAX_CLIENT_RECORDS) — past it the count is approximate.
 const COUNT_PAGE_SIZE = 50;
 const COUNT_MAX_RECORDS = 1000;
 
+/**
+ * Whether a JSON:API collection document advertises another page.
+ * `links.next` may be a string href or a `{ href }` link object.
+ * @param {?object} data JSON:API document.
+ * @returns {boolean}
+ */
+function jsonApiHasNext(data) {
+  const next = data?.links?.next;
+  if (next === undefined || next === null || next === false) return false;
+  if (typeof next === "string") return next.length > 0;
+  if (typeof next === "object" && next.href !== undefined && next.href !== null) {
+    return String(next.href).length > 0;
+  }
+  return Boolean(next);
+}
+
 /**
  * Detect the JSON:API error Drupal returns when a write attempts to set the
  * `status` (published) field on a content_moderation-governed entity. Such
@@ -268,24 +284,72 @@ export class JsonApiBackend extends Backend {
   }
 
   /**
-   * List entities for a descriptor. Server-side filter/sort/paging means the
-   * result is always exact (`approximate`/`truncated` are false).
+   * List entities for a descriptor.
+   *
+   * Drupal core JSON:API has no `meta.count` (jsonapi_extras can add it) and
+   * silently caps `page[limit]` at OffsetPage::SIZE_MAX (50 by default). When
+   * the caller asks for more rows than one Drupal page returns and
+   * `links.next` is present, this method follows that link until the requested
+   * window is filled, the collection ends, or COUNT_MAX_RECORDS is hit.
+   * `page.total` is exact when `meta.count` is present or this window reached
+   * the end; otherwise it is the number of rows seen so far and `approximate`
+   * is true. Never report a single page's length as an exact collection total.
+   *
    * @param {import("../canonical.js").QueryDescriptor} descriptor
    * @returns {Promise<import("./backend-interface.js").ListResult>}
    */
   async listEntities(descriptor) {
-    const params = this.compileQuery(descriptor);
-    const qs = params.toString();
-    const base = this.resourcePath(descriptor.entityType, descriptor.bundle);
-    const path = qs ? `${base}?${qs}` : base;
-    const data = await drupalFetch(this.site, path);
-    const entities = (data.data || []).map((r) => this.toCanonical(r));
-    const total = data.meta?.count ?? entities.length;
+    const requestedLimit = descriptor.page?.limit;
+    const startOffset = descriptor.page?.offset ?? 0;
+    const fillTo = typeof requestedLimit === "number"
+      ? Math.min(Math.max(0, requestedLimit), COUNT_MAX_RECORDS)
+      : null;
+
+    const entities = [];
+    let offset = startOffset;
+    let hasNext = false;
+    let metaCount = null;
+
+    for (;;) {
+      const remaining = fillTo === null ? requestedLimit : fillTo - entities.length;
+      const page = {
+        ...descriptor.page,
+        offset,
+        ...(typeof remaining === "number" ? { limit: remaining } : {}),
+      };
+      const params = this.compileQuery({ ...descriptor, page });
+      const qs = params.toString();
+      const base = this.resourcePath(descriptor.entityType, descriptor.bundle);
+      const path = qs ? `${base}?${qs}` : base;
+      const data = await drupalFetch(this.site, path);
+      if (metaCount === null && typeof data?.meta?.count === "number") {
+        metaCount = data.meta.count;
+      }
+      const pageEntities = (data.data || []).map((r) => this.toCanonical(r));
+      entities.push(...pageEntities);
+      hasNext = jsonApiHasNext(data);
+
+      if (fillTo === null) break;
+      if (!hasNext || pageEntities.length === 0) break;
+      if (entities.length >= fillTo) break;
+      offset += pageEntities.length;
+    }
+
+    const truncated = fillTo !== null
+      && typeof requestedLimit === "number"
+      && entities.length < requestedLimit
+      && hasNext;
+    const seen = startOffset + entities.length;
+    const exact = typeof metaCount === "number" || !hasNext;
     return {
       entities,
-      page: { total, hasNext: Boolean(data.links?.next), cursor: null },
-      approximate: false,
-      truncated: false,
+      page: {
+        total: typeof metaCount === "number" ? metaCount : seen,
+        hasNext,
+        cursor: null,
+      },
+      approximate: !exact,
+      truncated,
     };
   }
 

package/src/tools/nodes.js

@@ -280,8 +280,9 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
  *
  * @param {object} args - { site?, type, status?, filters?, limit?, offset?, sort? }.
  *   A `status` boolean is appended to `filters` as a status equality descriptor.
- * @returns {Promise<{total: number, approximate: boolean, offset: number,
- *   nextOffset: number, nodes: object[]}>} Paged, redacted node list.
+ * @returns {Promise<{total: number, approximate: boolean, truncated: boolean,
+ *   offset: number, nextOffset: number, hasNext: boolean, nodes: object[]}>}
+ *   Paged, redacted node list. `hasNext` is the backend's `links.next` signal.
  */
 async function listNodes({ site: siteName, type, status, filters = [], limit = 20, offset = 0, sort = [{ field: "changed", dir: "desc" }] }) {
   const site = getSiteConfig(siteName);
@@ -295,8 +296,10 @@ async function listNodes({ site: siteName, type, status, filters = [], limit = 2
   return {
     total: res.page?.total ?? nodes.length,
     approximate: res.approximate ?? false,
+    truncated: res.truncated ?? false,
     offset,
     nextOffset: offset + nodes.length,
+    hasNext: Boolean(res.page?.hasNext),
     nodes,
   };
 }
@@ -528,7 +531,7 @@ export const definitions = [
   },
   {
     name: "drupal_list_nodes",
-    description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors.",
+    description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set.",
     inputSchema: {
       type: "object", required: ["type"],
       properties: {

package/src/tools/paragraphs.js

@@ -145,24 +145,85 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
+/**
+ * JSON:API `resourceVersion` selector for a paragraph host pin.
+ * Accepts a numeric vid, a numeric string, or an explicit `id:<vid>`.
+ * @param {string|number} revisionId Host pin / paragraph revision id.
+ * @returns {string} e.g. `id:6654`.
+ * @throws {Error} If the value is not a usable revision id.
+ */
+export function paragraphResourceVersion(revisionId) {
+  if (typeof revisionId === "number" && Number.isFinite(revisionId) && revisionId > 0) {
+    return `id:${revisionId}`;
+  }
+  if (typeof revisionId === "string" && revisionId.length) {
+    if (/^id:[1-9]\d*$/.test(revisionId)) return revisionId;
+    if (/^[1-9]\d*$/.test(revisionId)) return `id:${revisionId}`;
+  }
+  throw new Error(
+    `Invalid paragraph revisionId "${revisionId}". Use a numeric vid (the host pin).`,
+  );
+}
+
+/**
+ * Numeric vid from a host pin (`6654` or `id:6654`).
+ * @param {string|number} revisionId
+ * @returns {?number}
+ */
+function requestedParagraphVid(revisionId) {
+  const raw = String(revisionId).replace(/^id:/, "");
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * Fail closed when a requested paragraph revision was not the one served.
+ * Silent substitution of the default revision is the defect this guards (#292).
+ * @param {?object} entity Canonical paragraph, or null if the read missed.
+ * @param {string|number} requested Host pin that was asked for.
+ * @param {string} id Paragraph UUID.
+ * @returns {object} `entity` when the served vid matches.
+ * @throws {Error} On a miss or a mismatched vid.
+ */
+function requireServedParagraphRevision(entity, requested, id) {
+  const wanted = requestedParagraphVid(requested);
+  const served = paragraphRevisionId(entity);
+  if (!entity || wanted === null || served === null || served !== wanted) {
+    const got = !entity || served === null ? "no revision" : String(served);
+    throw new Error(
+      `Requested paragraph revision ${wanted ?? requested} for ${id} but the backend served ${got}. ` +
+      "Refusing to substitute a different revision.",
+    );
+  }
+  return entity;
+}
+
 /**
  * Fetch a single paragraph by bundle + UUID, redacted per the site policy, and
  * annotate it with the embedding ref (including `meta.target_revision_id`).
  *
- * @param {object} args - { site?, paragraphType, id }.
+ * When `revisionId` is set (the host's `meta.target_revision_id`), the read
+ * addresses that revision via JSON:API `?resourceVersion=id:<vid>` and errors
+ * if Drupal serves a different vid. Omitting `revisionId` still reads the
+ * default revision.
+ *
+ * @param {object} args - { site?, paragraphType, id, langcode?, revisionId? }.
  * @returns {Promise<(object & {ref: object})|null>}
- *   The redacted paragraph with an embedding `ref`, or null if not found.
+ *   The redacted paragraph with an embedding `ref`, or null if not found and
+ *   no `revisionId` was requested.
  * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
+ * @throws {Error} If a requested `revisionId` cannot be served.
  */
 async function getParagraph({ site: siteName, paragraphType, id, langcode, revisionId }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "paragraph", paragraphType);
   const backend = await resolveBackend(site);
+  const pinRequested = revisionId !== undefined && revisionId !== null && revisionId !== "";
   let entity;
   if (langcode) {
     const targetLang = assertDraftLangcode(langcode);
-    const pinned = revisionId ?? paragraphRevisionId(
+    const pinned = pinRequested ? revisionId : paragraphRevisionId(
       await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id }),
     );
     if (pinned === null || pinned === undefined || pinned === "") {
@@ -172,12 +233,18 @@ async function getParagraph({ site: siteName, paragraphType, id, langcode, revis
       entityType: "paragraph", bundle: paragraphType, id, langcode: targetLang,
       draftRevision: { revisionId: pinned },
     });
+  } else if (pinRequested) {
+    const resourceVersion = paragraphResourceVersion(revisionId);
+    entity = await backend.getEntity({
+      entityType: "paragraph", bundle: paragraphType, id, resourceVersion,
+    });
+    requireServedParagraphRevision(entity, revisionId, id);
   } else {
     entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
   }
   if (!entity) return null;
   const redacted = redactCanonicalEntity(entity, sec, "paragraph");
-  const resolvedRevisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted) ?? revisionId;
+  const resolvedRevisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted);
   return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, resolvedRevisionId) };
 }
 
@@ -219,7 +286,7 @@ export const definitions = [
   {
     name: "drupal_get_paragraph",
     description:
-      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
+      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
@@ -227,7 +294,7 @@ export const definitions = [
         paragraphType: { type: "string", description: "Paragraph type / bundle machine name" },
         id:            { type: "string", description: "Paragraph UUID" },
         langcode:      { type: "string", description: "Target language for the unpublished working translation (e.g. 'es')." },
-        revisionId:    { type: "string", description: "Paragraph revision id the host already pins." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins (ERR meta.target_revision_id). Honored on the read; a different served vid is an error." },
       },
     },
   },