drupal-mcp-connector 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- 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
@@ -180,6 +229,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.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
 [0.7.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.7.0

package/README.md

@@ -170,13 +170,17 @@ 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 |
+| [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 |
 | [Whitepaper](docs/whitepaper.md) | Vision, personas, and use cases |
 
 ---

package/package.json

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

@@ -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

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