drupal-mcp-connector 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-06-15
+
+### Added
+- Docs: an [MCP client setup guide](docs/mcp-clients.md) with copy-paste config
+  **and per-platform management commands** for Claude (Code `claude mcp …` /
+  Desktop), Grok (Build `grok mcp …` + API Remote MCP Tools), and OpenAI (Codex
+  `codex mcp …` + ChatGPT/Responses API), plus generic stdio and remote-HTTP
+  patterns and the local-vs-remote reachability/secret tradeoffs.
+- Test coverage for the Streamable-HTTP transport's request routing (bearer-auth
+  gate, session open/reuse, `/health`, 404) via an extracted, unit-tested
+  `http-handler` module.
+- Regression tests confirming **non-content-moderation Drupal sites are
+  unaffected** by the moderation fallback: a plain create sends `status` and
+  succeeds on the first request with no retry (the fallback only engages on the
+  specific moderated-entity 403).
+- Optional built-in **rate limiting** for the HTTPS transport: set
+  `MCP_RATE_LIMIT` (per-IP requests per window) and `MCP_RATE_WINDOW_SEC`
+  (default 60). Over-limit `/mcp` requests get `429` + `Retry-After`; the check
+  runs before auth (throttling brute force) and never limits `/health`. Off by
+  default. (#4)
+- Reference deployment for the HTTPS transport: a `Dockerfile` (+ `.dockerignore`),
+  systemd unit, launchd plist + launcher, a Caddy reverse-proxy example, and a
+  [Deployment guide](docs/deployment.md) with a pre-exposure checklist.
+- [Versioning & Stability policy](docs/versioning.md) defining the stable public
+  surface (tool names/inputs, resource/prompt URIs, config + env vars, transports,
+  presets), the deprecation process, MCP-protocol negotiation behavior, and Node
+  support — the contract that 1.0 will lock.
+
+### Changed
+- Refactor: the HTTP transport's request handler is extracted from `index.js`
+  into `src/lib/http-handler.js` (no behavior change), making the routing/auth
+  path unit-testable and ready for additional middleware (e.g. rate limiting).
+
+## [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
@@ -22,6 +100,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
@@ -31,6 +113,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`).
@@ -123,6 +213,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.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
 [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

package/README.md

@@ -7,7 +7,7 @@
 [![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).
 
 ---
 
@@ -170,12 +170,16 @@ 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 |
+| [MCP Clients](docs/mcp-clients.md) | Wire the connector into Claude (Code/Desktop), Grok (Build/API), and OpenAI (Codex/ChatGPT) — copy-paste config per client |
+| [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 |
 | [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
 | [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
+| [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 |
 | [Whitepaper](docs/whitepaper.md) | Vision, personas, and use cases |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "0.7.1",
+  "version": "0.9.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)"
   ],
@@ -43,15 +43,15 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "start":        "node src/index.js",
-    "start:https":  "MCP_TRANSPORT=https node src/index.js",
-    "start:dev":    "MCP_TRANSPORT=https MCP_ALLOW_HTTP=1 MCP_PORT=3443 node src/index.js",
-    "lint":         "eslint src/",
-    "lint:fix":     "eslint src/ --fix",
-    "test":         "vitest run",
-    "test:watch":   "vitest",
-    "audit":        "npm audit --audit-level=high",
-    "check":        "npm run lint && npm run audit",
+    "start": "node src/index.js",
+    "start:https": "MCP_TRANSPORT=https node src/index.js",
+    "start:dev": "MCP_TRANSPORT=https MCP_ALLOW_HTTP=1 MCP_PORT=3443 node src/index.js",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "audit": "npm audit --audit-level=high",
+    "check": "npm run lint && npm run audit",
     "syntax-check": "for f in src/lib/*.js src/tools/*.js src/index.js; do node --input-type=module --check < $f && echo \"$f ✓\"; done"
   },
   "dependencies": {
@@ -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

@@ -18,6 +18,8 @@
  *   MCP_AUTH_TOKEN    Bearer token required on /mcp in https mode (warns if unset)
  *   MCP_BIND_HOST     Bind address for https mode when TLS is present
  *                     (default: "0.0.0.0"; ignored without TLS, which forces loopback)
+ *   MCP_RATE_LIMIT    Max /mcp requests per window per client IP (0/unset = off)
+ *   MCP_RATE_WINDOW_SEC  Rate-limit window in seconds (default: 60)
  */
 
 import { createServer as createHttpsServer } from "https";
@@ -36,6 +38,8 @@ import { CallToolRequestSchema,
 
 import { getSiteConfig, listSiteNames, getTlsConfig, CLIENT_VERSION } from "./lib/config.js";
 import { makeBearerCheck } from "./lib/http-auth.js";
+import { createMcpRequestHandler } from "./lib/http-handler.js";
+import { createRateLimiter } from "./lib/rate-limit.js";
 import { resolveSecurityConfig, assertNotReadOnly,
   assertDestructiveAllowed, assertGraphqlMutationAllowed,
   SecurityError }            from "./lib/security.js";
@@ -439,47 +443,42 @@ if (transport === "stdio") {
   // Map of sessionId → transport for multi-client support
   const sessions = new Map();
 
-  const nodeServer = createNodeServer(async (req, res) => {
-    if (req.url === "/mcp" && (req.method === "POST" || req.method === "GET")) {
-      if (!checkAuth(req.headers["authorization"])) {
-        res.writeHead(401, { "WWW-Authenticate": "Bearer" }).end("Unauthorized");
-        return;
-      }
-    }
+  // Create + connect a new Streamable-HTTP transport, registering it in the
+  // session map on initialize and pruning it on close.
+  async function openSession() {
+    const mcpTransport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (id) => sessions.set(id, mcpTransport),
+    });
+    mcpTransport.onclose = () => sessions.delete(mcpTransport.sessionId);
+    await server.connect(mcpTransport);
+    return mcpTransport;
+  }
 
-    if (req.method === "POST" && req.url === "/mcp") {
-      const sessionId = req.headers["mcp-session-id"];
-      let mcpTransport;
-
-      if (sessionId && sessions.has(sessionId)) {
-        mcpTransport = sessions.get(sessionId);
-      } else {
-        mcpTransport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => randomUUID(),
-          onsessioninitialized: (id) => sessions.set(id, mcpTransport),
-        });
-        mcpTransport.onclose = () => sessions.delete(mcpTransport.sessionId);
-        await server.connect(mcpTransport);
-      }
-      await mcpTransport.handleRequest(req, res);
-
-    } else if (req.method === "GET" && req.url === "/mcp") {
-      const sessionId = req.headers["mcp-session-id"];
-      if (!sessionId || !sessions.has(sessionId)) {
-        res.writeHead(400).end("Missing or unknown MCP-Session-Id");
-        return;
-      }
-      await sessions.get(sessionId).handleRequest(req, res);
-
-    } else if (req.url === "/health") {
-      res.writeHead(200, { "Content-Type": "application/json" })
-        .end(JSON.stringify({ status: "ok", tools: allDefinitions.length }));
-
-    } else {
-      res.writeHead(404).end("Not found");
-    }
+  // Optional fixed-window rate limiting on /mcp, keyed by client IP. Off unless
+  // MCP_RATE_LIMIT > 0. Counts are per-process; for multi-replica deployments
+  // prefer rate limiting at the reverse proxy.
+  const rateLimit     = Number(process.env.MCP_RATE_LIMIT || 0);
+  const rateWindowSec = Number(process.env.MCP_RATE_WINDOW_SEC || 60);
+  const rateLimiter   = rateLimit > 0
+    ? createRateLimiter({ limit: rateLimit, windowMs: rateWindowSec * 1000 })
+    : null;
+  if (rateLimiter) {
+    console.error(
+      `[drupal-mcp-connector] Rate limiting: ${rateLimit} req / ${rateWindowSec}s per client IP on /mcp.`
+    );
+  }
+
+  const requestHandler = createMcpRequestHandler({
+    checkAuth,
+    sessions,
+    openSession,
+    toolCount: allDefinitions.length,
+    rateLimiter,
   });
 
+  const nodeServer = createNodeServer(requestHandler);
+
   const hasTls   = Boolean(tlsCfg.certPath && tlsCfg.keyPath);
   // Unauthenticated plain HTTP must never bind beyond loopback. A non-loopback
   // bind is allowed only alongside TLS, via an explicit MCP_BIND_HOST opt-in.

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/http-handler.js

@@ -0,0 +1,78 @@
+/**
+ * HTTP request handler for the Streamable-HTTP MCP transport.
+ *
+ * Extracted from index.js so the routing/auth/health/404 behavior is unit
+ * testable without standing up a real server or the MCP SDK. The entry point
+ * wires the concrete dependencies (bearer check, session map, session factory);
+ * tests inject stubs.
+ */
+
+/**
+ * Build the `(req, res)` handler for the MCP HTTP endpoint.
+ *
+ * Routes:
+ *   - `POST /mcp`  — bearer-gated; reuses a session by `Mcp-Session-Id` or opens
+ *     a new one, then delegates to the transport's `handleRequest`.
+ *   - `GET /mcp`   — bearer-gated; requires a known session, else 400.
+ *   - `GET /health`— unauthenticated liveness probe (`{status, tools}`).
+ *   - everything else — 404.
+ *
+ * @param {object} deps
+ * @param {(authHeader: any) => boolean} deps.checkAuth Bearer predicate (see http-auth.js).
+ * @param {Map<string, {handleRequest: Function, sessionId?: string}>} deps.sessions Session id → transport.
+ * @param {() => Promise<{handleRequest: Function}>} deps.openSession Create+connect a new transport.
+ * @param {number} deps.toolCount Tool count reported by /health.
+ * @param {?{check: (key: string) => {allowed: boolean, retryAfterSec: number}}} [deps.rateLimiter]
+ *   Optional rate limiter (see rate-limit.js). Omit/null to disable.
+ * @param {(req: import("http").IncomingMessage) => string} [deps.clientKey]
+ *   Maps a request to a rate-limit key (default: client IP).
+ * @returns {(req: import("http").IncomingMessage, res: import("http").ServerResponse) => Promise<void>}
+ */
+export function createMcpRequestHandler({
+  checkAuth, sessions, openSession, toolCount,
+  rateLimiter = null,
+  clientKey = (req) => req.socket?.remoteAddress || "unknown",
+}) {
+  return async function handle(req, res) {
+    if (req.url === "/mcp" && (req.method === "POST" || req.method === "GET")) {
+      // Rate limit BEFORE auth so repeated bad-token attempts are throttled too.
+      if (rateLimiter) {
+        const verdict = rateLimiter.check(clientKey(req));
+        if (!verdict.allowed) {
+          res.writeHead(429, { "Retry-After": String(verdict.retryAfterSec) }).end("Too Many Requests");
+          return;
+        }
+      }
+      // Auth gate: only the /mcp endpoint requires a token; /health stays open.
+      if (!checkAuth(req.headers["authorization"])) {
+        res.writeHead(401, { "WWW-Authenticate": "Bearer" }).end("Unauthorized");
+        return;
+      }
+    }
+
+    if (req.method === "POST" && req.url === "/mcp") {
+      const sessionId = req.headers["mcp-session-id"];
+      const transport = (sessionId && sessions.get(sessionId)) || (await openSession());
+      await transport.handleRequest(req, res);
+      return;
+    }
+
+    if (req.method === "GET" && req.url === "/mcp") {
+      const sessionId = req.headers["mcp-session-id"];
+      if (!sessionId || !sessions.has(sessionId)) {
+        res.writeHead(400).end("Missing or unknown MCP-Session-Id");
+        return;
+      }
+      await sessions.get(sessionId).handleRequest(req, res);
+      return;
+    }
+
+    if (req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" })
+        .end(JSON.stringify({ status: "ok", tools: toolCount }));
+      return;
+    }
+
+    res.writeHead(404).end("Not found");
+  };
+}

package/src/lib/rate-limit.js

@@ -0,0 +1,56 @@
+/**
+ * Minimal, dependency-free fixed-window rate limiter for the HTTPS transport.
+ *
+ * Opt-in: with a falsy/non-positive `limit` it's a no-op (always allows), so the
+ * default behavior is unchanged. Counts are kept in-memory per process and keyed
+ * by an arbitrary string (the caller chooses, e.g. client IP). Suited to a
+ * single-process connector fronting one Drupal; for multi-replica deployments
+ * put a shared limiter in the reverse proxy instead.
+ */
+
+/**
+ * @typedef {object} RateVerdict
+ * @property {boolean} allowed     Whether the request may proceed.
+ * @property {number}  remaining   Requests left in the current window (Infinity when disabled).
+ * @property {number}  retryAfterSec Seconds until the window resets (0 when allowed).
+ */
+
+/**
+ * Create a fixed-window rate limiter.
+ * @param {object} opts
+ * @param {?number} opts.limit       Max requests per window per key. Falsy/<=0 disables limiting.
+ * @param {number}  [opts.windowMs]  Window length in ms (default 60_000).
+ * @param {() => number} [opts.now]  Clock (injectable for tests; default Date.now).
+ * @param {number}  [opts.maxKeys]   Soft cap on tracked keys before expired ones are pruned (default 10_000).
+ * @returns {{ check: (key: string) => RateVerdict, size: () => number }}
+ */
+export function createRateLimiter({ limit, windowMs = 60_000, now = () => Date.now(), maxKeys = 10_000 } = {}) {
+  const enabled = typeof limit === "number" && limit > 0;
+  /** @type {Map<string, {count: number, resetAt: number}>} */
+  const buckets = new Map();
+
+  function prune(t) {
+    for (const [k, b] of buckets) {
+      if (t >= b.resetAt) buckets.delete(k);
+    }
+  }
+
+  return {
+    check(key) {
+      if (!enabled) return { allowed: true, remaining: Infinity, retryAfterSec: 0 };
+      const t = now();
+      let b = buckets.get(key);
+      if (!b || t >= b.resetAt) {
+        if (buckets.size >= maxKeys) prune(t);
+        b = { count: 0, resetAt: t + windowMs };
+        buckets.set(key, b);
+      }
+      b.count += 1;
+      if (b.count > limit) {
+        return { allowed: false, remaining: 0, retryAfterSec: Math.ceil((b.resetAt - t) / 1000) };
+      }
+      return { allowed: true, remaining: limit - b.count, retryAfterSec: 0 };
+    },
+    size() { return buckets.size; },
+  };
+}

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" },
       },
     },