drupal-mcp-connector 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-06-15
+
+### Added
+- Docs: an OAuth2 `client_credentials` deployment guide
+  (`docs/oauth-client-credentials.md`) covering scope→role mapping, JSON:API
+  write enablement, config persistence across deploys, and secret handling, plus
+  a reusable `examples/launch-with-secret.sh` secret-manager launcher. Linked
+  from the README and getting-started.
+- `drupal_create_node` and `drupal_update_node` accept a `moderationState`
+  argument (e.g. `"draft"`/`"published"`) for content types under a
+  content_moderation workflow. When set, `moderation_state` is sent and `status`
+  is omitted (moderated entities own their published state).
+- CI: a `Changelog` workflow blocks any pull request that doesn't update
+  `CHANGELOG.md`. Trivial PRs that genuinely need no entry can carry the
+  `no-changelog` label to bypass the check.
+- CI: a `dependabot.yml` enabling weekly version updates for npm (dev
+  dependencies grouped) and GitHub Actions.
+- CI: a `changelog-autoupdate` workflow (org reusable) that writes a CHANGELOG
+  entry on Dependabot PRs and pushes it via a GitHub App token, so the required
+  `CHANGELOG updated` check passes without manual edits. No-ops until the
+  `CHANGELOG_APP_*` Dependabot secrets are configured.
+- CI: Dependabot patch/minor PRs now auto-merge once checks pass (majors still
+  reviewed), via the org reusable workflow.
+
+### Changed
+- CI: bumped `actions/checkout` and `actions/setup-node` to `v6` (Node 24
+  runtime) ahead of GitHub's June 2026 deprecation of Node 20 actions.
+- CI: added a `concurrency` group so superseded in-progress runs are cancelled,
+  matching the sibling repos' CI hygiene.
+- Dependency: bumped `graphql` 16.14.0 → 16.14.1 (patch).
+- Dev dependencies: bumped `eslint` `^9`→`^10`, `eslint-plugin-security` `^3`→`^4`,
+  `eslint-plugin-n` `^17`→`^18`, and `globals` `^15`→`^17` (Dependabot
+  dev-dependencies group). Lint and the full test suite pass on the new majors.
+
+### Fixed
+- Create/update no longer fail on content_moderation bundles. The JSON:API
+  backend now transparently retries a write without the `status` attribute when
+  Drupal rejects it as a moderated entity's published field (HTTP 403), so the
+  safe default `status:false` works on moderated types (Drupal applies the
+  workflow's default state). Affects all entity create/update paths (nodes,
+  entities, media), not just nodes. (#23)
+- Docs: replaced a personal email with the `opensource@wilkesliberty.com` role
+  address (README, `package.json`); corrected whitepaper tool counts (Drush
+  ~10→15, Nodes ~12→6).
+
+## [0.7.1] - 2026-06-08
+
+### Fixed
+- The connector now reports its real version — sourced from `package.json` at
+  runtime — in the MCP handshake, the `X-MCP-Client` identity header, and the
+  startup logs. A hardcoded version literal had drifted and under-reported it
+  (0.7.0 still announced itself as `0.6.0`).
+
+### Documentation
+- Corrected Node version references (18 → 20) in the README and getting-started
+  guide to match `engines.node >=20.0.0`, and updated the example startup banner
+  to the current version.
+- Rewrote CONTRIBUTING.md: prerequisites, full dev-script list, a tests section,
+  accurate PR/CI gates, and the PR-then-tag release flow for protected `master`.
+
+### Changed
+- Restored the column-aligned `package.json` `scripts` formatting that
+  `npm version` re-flattened while cutting 0.7.0.
+
 ## [0.7.0] - 2026-06-08
 
 ### Added
@@ -16,6 +80,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (GitHub Actions OIDC — no token/secret), gated on a tag↔`package.json` version
   match. Provenance is attached automatically. One-time trusted-publisher setup
   on npmjs.com (see CONTRIBUTING.md → Releasing).
+- Branch protection on `master`: merges require a pull request with passing CI
+  (lint, unit tests on Node 20/22, Drupal integration, CodeQL) and resolved
+  review conversations; force-pushes and branch deletion are blocked.
+
+### Fixed
+- CI now runs on the `master` default branch. The workflow had been configured
+  for a nonexistent `main` branch, so lint/syntax/unit and integration never
+  executed on pushes or PRs.
 
 ### Removed
 - **BREAKING:** dropped support for Node 18 (`engines.node` is now `>=20.0.0`).
@@ -108,6 +180,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.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
 [0.7.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.7.0
 [0.6.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.6.1
 [0.6.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.6.0

package/README.md

@@ -3,11 +3,11 @@
 > 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.
 
 [![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%3D18-green)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
 [![Drupal](https://img.shields.io/badge/drupal-10%20%7C%2011-blue)](https://drupal.org)
 [![MCP](https://img.shields.io/badge/MCP-2025--11--25-purple)](https://modelcontextprotocol.io)
 
-Built by **Jeremy Michael Cerda** (jmcerda@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
+Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
 ---
 
@@ -98,7 +98,7 @@ Presets layer with entity allow/deny lists, per-bundle operation rules, and fiel
 
 ## Requirements
 
-- **Node.js** 18+
+- **Node.js** 20+
 - **Drupal** 10 or 11 (JSON:API ships in core)
 - For the **GraphQL backend**: [GraphQL Compose](https://www.drupal.org/project/graphql_compose)
 - For **token auth** (recommended): [Simple OAuth](https://www.drupal.org/project/simple_oauth)
@@ -170,6 +170,7 @@ Governance keys off the authenticated account's role and OAuth scopes — not re
 | Doc | Description |
 |-----|-------------|
 | [Getting Started](docs/getting-started.md) | Full setup: DDEV/Lando, Simple OAuth, multi-site, transports |
+| [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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "0.7.0",
+  "version": "0.8.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",
@@ -35,7 +35,7 @@
     "url": "https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues"
   },
   "license": "MIT",
-  "author": "Jeremy Michael Cerda <jmcerda@wilkesliberty.com> (https://wilkesliberty.com)",
+  "author": "Jeremy Michael Cerda <opensource@wilkesliberty.com> (https://wilkesliberty.com)",
   "contributors": [
     "Wilkes & Liberty, LLC <opensource@wilkesliberty.com> (https://wilkesliberty.com)"
   ],
@@ -61,10 +61,10 @@
     "ssh2": "^1.16.0"
   },
   "devDependencies": {
-    "eslint": "^9.0.0",
-    "eslint-plugin-security": "^3.0.0",
-    "eslint-plugin-n": "^17.0.0",
-    "globals": "^15.0.0",
+    "eslint": "^10.4.1",
+    "eslint-plugin-security": "^4.0.0",
+    "eslint-plugin-n": "^18.1.0",
+    "globals": "^17.6.0",
     "vitest": "^4.1.8"
   }
 }

package/src/index.js

@@ -34,7 +34,7 @@ import { CallToolRequestSchema,
   ListPromptsRequestSchema,
   GetPromptRequestSchema }   from "@modelcontextprotocol/sdk/types.js";
 
-import { getSiteConfig, listSiteNames, getTlsConfig } from "./lib/config.js";
+import { getSiteConfig, listSiteNames, getTlsConfig, CLIENT_VERSION } from "./lib/config.js";
 import { makeBearerCheck } from "./lib/http-auth.js";
 import { resolveSecurityConfig, assertNotReadOnly,
   assertDestructiveAllowed, assertGraphqlMutationAllowed,
@@ -298,7 +298,7 @@ function getPromptMessages(name, args) {
 // ---------------------------------------------------------------------------
 
 const server = new Server(
-  { name: "drupal-mcp-connector", version: "0.6.0" },
+  { name: "drupal-mcp-connector", version: CLIENT_VERSION },
   { capabilities: { tools: {}, resources: {}, prompts: {} } }
 );
 
@@ -368,7 +368,7 @@ if (transport === "stdio") {
   const stdioTransport = new StdioServerTransport();
   await server.connect(stdioTransport);
   console.error(
-    "[drupal-mcp-connector v0.6.0] stdio transport active. " +
+    `[drupal-mcp-connector v${CLIENT_VERSION}] stdio transport active. ` +
     `${allDefinitions.length} tools · ${RESOURCES.length} resources · ${PROMPTS.length} prompts`
   );
 
@@ -488,7 +488,7 @@ if (transport === "stdio") {
   nodeServer.listen(port, bindHost, () => {
     const proto = hasTls ? "https" : "http";
     console.error(
-      `[drupal-mcp-connector v0.6.0] Listening on ${proto}://${bindHost}:${port}/mcp\n` +
+      `[drupal-mcp-connector v${CLIENT_VERSION}] Listening on ${proto}://${bindHost}:${port}/mcp\n` +
       `  ${allDefinitions.length} tools · ${RESOURCES.length} resources · ${PROMPTS.length} prompts`
     );
   });

package/src/lib/backends/jsonapi.js

@@ -19,6 +19,21 @@ import {
 // these are dropped from canonical `fields` (the canonical id is the UUID).
 const INTERNAL_ATTR_RE = /^drupal_internal__/;
 
+/**
+ * Detect the JSON:API error Drupal returns when a write attempts to set the
+ * `status` (published) field on a content_moderation-governed entity. Such
+ * entities own their published state via `moderation_state`, so a direct
+ * `status` write is refused with a 403 ("Cannot edit the published field of
+ * moderated entities" / "not allowed to … field (status)"). Used to decide
+ * whether to retry the write without `status`.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isModeratedStatusError(err) {
+  const msg = String(err?.message || "");
+  return /published field of moderated/i.test(msg) || /field \(status\)/i.test(msg);
+}
+
 // Canonical filter op -> JSON:API condition operator.
 const OP_MAP = new Map([
   ["neq", "<>"], ["gt", ">"], ["gte", ">="], ["lt", "<"], ["lte", "<="],
@@ -209,32 +224,63 @@ export class JsonApiBackend extends Backend {
   }
 
   /**
-   * Create an entity via JSON:API POST.
+   * Issue a JSON:API write, transparently retrying once without the `status`
+   * attribute if the target bundle is under a content_moderation workflow.
+   *
+   * Moderated entities derive their published state from `moderation_state` and
+   * reject a direct `status` write with a 403. This lets create/update "just
+   * work" on moderated bundles using the connector's safe default `status:false`:
+   * the retry drops `status` and Drupal applies the workflow's default state
+   * (typically draft — i.e. still unpublished, preserving the no-auto-publish
+   * guarantee). Callers that need a specific state pass `moderation_state`
+   * explicitly, in which case `status` is absent and no retry occurs.
+   *
+   * @param {string} path JSON:API resource path.
+   * @param {"POST"|"PATCH"} method HTTP method.
+   * @param {(attrs: object) => object} buildPayload Builds the request body from an attribute map.
+   * @param {object} attributes Entity attributes (may include `status`).
+   * @returns {Promise<object>} The JSON:API response body.
+   */
+  async writeWithModerationFallback(path, method, buildPayload, attributes) {
+    try {
+      return await drupalFetch(this.site, path, { method, body: JSON.stringify(buildPayload(attributes)) });
+    } catch (err) {
+      if (!isModeratedStatusError(err) || !("status" in attributes)) throw err;
+      const withoutStatus = { ...attributes };
+      delete withoutStatus.status;
+      return drupalFetch(this.site, path, { method, body: JSON.stringify(buildPayload(withoutStatus)) });
+    }
+  }
+
+  /**
+   * Create an entity via JSON:API POST. Retries without `status` on moderated
+   * bundles — see writeWithModerationFallback.
    * @param {{entityType: string, bundle: string, attributes?: object, relationships?: object}} input
    * @returns {Promise<import("../canonical.js").CanonicalEntity>} The created entity.
    */
   async createEntity({ entityType, bundle, attributes = {}, relationships }) {
-    const payload = { data: { type: `${entityType}--${bundle}`, attributes } };
-    if (relationships) payload.data.relationships = relationships;
-    const data = await drupalFetch(this.site, this.resourcePath(entityType, bundle), {
-      method: "POST",
-      body: JSON.stringify(payload),
-    });
+    const buildPayload = (attrs) => {
+      const payload = { data: { type: `${entityType}--${bundle}`, attributes: attrs } };
+      if (relationships) payload.data.relationships = relationships;
+      return payload;
+    };
+    const data = await this.writeWithModerationFallback(this.resourcePath(entityType, bundle), "POST", buildPayload, attributes);
     return this.toCanonical(data.data);
   }
 
   /**
-   * Update an entity via JSON:API PATCH.
+   * Update an entity via JSON:API PATCH. Retries without `status` on moderated
+   * bundles — see writeWithModerationFallback.
    * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object}} input
    * @returns {Promise<import("../canonical.js").CanonicalEntity>} The updated entity.
    */
   async updateEntity({ entityType, bundle, id, attributes = {}, relationships }) {
-    const payload = { data: { type: `${entityType}--${bundle}`, id, attributes } };
-    if (relationships) payload.data.relationships = relationships;
-    const data = await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${id}`, {
-      method: "PATCH",
-      body: JSON.stringify(payload),
-    });
+    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);
     return this.toCanonical(data.data);
   }
 

package/src/lib/config.js

@@ -13,8 +13,11 @@ import { validateBaseUrl }               from "./validate.js";
 import { SecurityError }                 from "./security.js";
 import { getAccessToken }                from "./oauth.js";
 
-/** Connector version for the X-MCP-Client identity label. Keep in sync with package.json. */
-export const CLIENT_VERSION = "0.6.0";
+// eslint-disable-next-line security/detect-non-literal-fs-filename -- fixed path relative to this module (the package's own package.json), not user input
+const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+
+/** Connector version, sourced from package.json so it never drifts out of sync. */
+export const CLIENT_VERSION = pkg.version;
 
 /**
  * Identity headers sent on every outbound Drupal request. Lets governance layers

package/src/tools/nodes.js

@@ -92,16 +92,30 @@ async function searchContent({ site: siteName, query, type, status, limit = 10 }
 
 /**
  * Create a node. Caller-supplied `fields` are spread into the attribute map;
- * title/status/body are layered on top so they win over any same-named field.
+ * title/status/moderation_state/body are layered on top so they win over any
+ * same-named field.
  *
- * @param {object} args - { site?, type, title, body?, summary?, status?, fields? }.
- *   Defaults to status=false (draft) so content is never auto-published.
+ * Publish state — two mutually exclusive paths:
+ *   - `moderationState` (e.g. "draft"/"published"): for content types under a
+ *     content_moderation workflow. When given, `moderation_state` is sent and
+ *     `status` is omitted (moderated entities reject a direct `status` write).
+ *   - `status` (boolean): for non-moderated types. Defaults to false (draft) so
+ *     content is never auto-published. `moderationState` takes precedence.
+ * If a moderated bundle still receives `status` (the safe default), the JSON:API
+ * backend transparently retries without it — see jsonapi.js.
+ *
+ * @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 = false, fields = {} }) {
+async function createNode({ site: siteName, type, title, body, summary, status, moderationState, fields = {} }) {
   const site = getSiteConfig(siteName);
   const backend = await resolveBackend(site);
-  const attributes = { title, status, ...fields };
+  const attributes = { title, ...fields };
+  if (moderationState !== undefined) {
+    attributes.moderation_state = moderationState;
+  } else {
+    attributes.status = status === undefined ? false : status;
+  }
   const bodyAttr = buildBodyAttribute(body, summary);
   if (bodyAttr) attributes.body = bodyAttr;
   return backend.createEntity({ entityType: "node", bundle: type, attributes });
@@ -111,15 +125,20 @@ async function createNode({ site: siteName, type, title, body, summary, status =
  * Update a node. Only supplied attributes are sent, so omitted fields are left
  * untouched (partial update). `fields` is spread first, then known scalars.
  *
- * @param {object} args - { site?, type, id, title?, body?, summary?, status?, fields? }.
+ * Publish state mirrors createNode: pass `moderationState` for content_moderation
+ * bundles (sends `moderation_state`, omits `status`) or `status` for non-moderated
+ * types. `moderationState` takes precedence; both are optional on update.
+ *
+ * @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, fields = {} }) {
+async function updateNode({ site: siteName, type, id, title, body, summary, status, moderationState, fields = {} }) {
   const site = getSiteConfig(siteName);
   const backend = await resolveBackend(site);
   const attributes = { ...fields };
   if (title !== undefined) attributes.title = title;
-  if (status !== undefined) attributes.status = status;
+  if (moderationState !== undefined) attributes.moderation_state = moderationState;
+  else if (status !== undefined) attributes.status = status;
   const bodyAttr = buildBodyAttribute(body, summary);
   if (bodyAttr) attributes.body = bodyAttr;
   return backend.updateEntity({ entityType: "node", bundle: type, id, attributes });
@@ -188,7 +207,7 @@ export const definitions = [
   },
   {
     name: "drupal_create_node",
-    description: "Create a new content node. Returns the new node UUID, integer ID, and URL.",
+    description: "Create a new content node. Returns the new node UUID, integer ID, and URL. For content types under an editorial (content_moderation) workflow, set moderationState (e.g. 'draft'/'published') instead of status.",
     inputSchema: {
       type: "object", required: ["type", "title"],
       properties: {
@@ -197,14 +216,15 @@ export const definitions = [
         title:   { type: "string" },
         body:    { type: "string", description: "Body field HTML" },
         summary: { type: "string", description: "Body summary / teaser" },
-        status:  { type: "boolean", default: false, description: "true to publish immediately" },
+        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" },
       },
     },
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change.",
+    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -214,7 +234,8 @@ export const definitions = [
         title:   { type: "string" },
         body:    { type: "string" },
         summary: { type: "string" },
-        status:  { type: "boolean", description: "true = publish, false = unpublish" },
+        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" },
       },
     },