drupal-mcp-connector 2.2.2 → 2.3.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-08-13
+
+### Added
+
+- **MCP 2026-07-28 transport support (#172).** HTTP and stdio now serve the
+  current request-scoped protocol through the stable 2.0.0 server, Node, and
+  client packages. Modern HTTP requests use a fresh server instance, expose
+  `server/discover`, carry client metadata/capabilities in the request envelope,
+  and do not create `Mcp-Session-Id` state.
+
+### Changed
+
+- **One `/mcp` URL now has explicit dual-era routing.** Auth and rate limiting
+  run before a POST body is read once and bounded; the SDK classifier then sends
+  that parsed body to exactly one arm. Current requests use the strict modern
+  handler. 2025-era clients keep the existing sessionful handler by default and
+  can be disabled with `MCP_LEGACY_TRANSPORT=reject`. stdio uses the same server
+  factory and preserves both eras.
+- **MCP SDK packages are migrated to stable v2.** Runtime dependencies are now
+  `@modelcontextprotocol/server` and `@modelcontextprotocol/node` 2.0.0; the
+  matching client package supplies integration evidence. Node.js 20+ remains
+  the runtime floor.
+
+### Security
+
+- Unexpected request conversion, era classification, and handler failures no
+  longer expose internal error messages. Before response headers they return a
+  generic 500; after headers they terminate the response without a second write.
+  Protocol/header/body disagreements continue to return the SDK's typed 400
+  errors, and the outbound private-Drupal bridge remains pinned to its
+  sessionful 2025-06-18 contract.
+
 ## [2.2.2] - 2026-08-12
 
 ### Security

package/README.md

@@ -5,7 +5,7 @@
 [![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)
 [![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)
+[![MCP](https://img.shields.io/badge/MCP-2026--07--28-purple)](https://modelcontextprotocol.io)
 
 Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
@@ -221,6 +221,11 @@ or remote use, run the HTTPS transport and register the endpoint instead — see
 **[docs/getting-started.md](docs/getting-started.md)** and
 **[docs/mcp-clients.md](docs/mcp-clients.md)**.
 
+The same entry point serves current MCP 2026-07-28 clients and 2025-era clients.
+Current HTTP requests are stateless and never receive `Mcp-Session-Id`; legacy
+HTTP clients retain their existing session. Set `MCP_LEGACY_TRANSPORT=reject`
+to end the compatibility window deliberately. The `/mcp` URL does not change.
+
 ---
 
 ## Companion Drupal Module — MCP Sentinel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.2.2",
+  "version": "2.3.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",
@@ -58,12 +58,14 @@
     "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": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "graphql": "^17.0.0",
     "node-fetch": "^3.3.2",
     "ssh2": "^1.16.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
     "eslint": "^10.4.1",
     "eslint-plugin-n": "^18.1.0",
     "eslint-plugin-security": "^4.0.0",

package/src/index.js

@@ -20,25 +20,21 @@
  *                     (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)
+ *   MCP_LEGACY_TRANSPORT "serve" (default) | "reject" for 2025-era clients
  */
 
 import { createServer as createHttpsServer } from "https";
 import { createServer as createHttpServer }  from "http";
 import { readFileSync }                      from "fs";
-import { randomUUID }                        from "node:crypto";
 
-import { Server }                   from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport }     from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema }   from "@modelcontextprotocol/sdk/types.js";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { toNodeHandler } from "@modelcontextprotocol/node";
 
 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 { createLegacySessionHandler, createMcpRequestHandler } from "./lib/http-handler.js";
+import { createConnectorServerFactory } from "./lib/mcp-server.js";
 import { createRateLimiter } from "./lib/rate-limit.js";
 import { resolveSecurityConfig, assertNotReadOnly,
   assertDestructiveAllowed, assertGraphqlMutationAllowed,
@@ -290,19 +286,10 @@ function getPromptMessages(name, args) {
 }
 
 // ---------------------------------------------------------------------------
-// MCP Server construction
+// MCP Server surface
 // ---------------------------------------------------------------------------
 
-const server = new Server(
-  { name: "drupal-mcp-connector", version: CLIENT_VERSION },
-  { capabilities: { tools: {}, resources: {}, prompts: {} } }
-);
-
-// Tools
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allDefinitions }));
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
+async function callTool(name, args) {
   // eslint-disable-next-line security/detect-object-injection -- name is an MCP tool name from validated schema; allHandlers is a closed dispatch table built at startup
   const handler = allHandlers[name];
 
@@ -329,32 +316,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     return toolError(err);
   }
-});
-
-// Resources
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: RESOURCES }));
-
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  const { uri } = request.params;
-  try {
-    const data = await readResource(uri);
-    return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(data, null, 2) }] };
-  } catch (err) {
-    throw new Error(`Resource read failed (${uri}): ${err.message}`);
-  }
-});
+}
 
-// Prompts — hand-authored workflows + one generated prompt per tool
-server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: ALL_PROMPTS }));
-
-server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-  const known = ALL_PROMPTS.find((p) => p.name === name);
-  if (!known) throw new Error(`Unknown prompt: "${name}"`);
-  const messages = WORKFLOW_PROMPT_NAMES.has(name)
-    ? getPromptMessages(name, args)
-    : getToolPromptMessages(name, args, definitionsByName);
-  return { description: known.description, messages };
+const buildConnectorServer = createConnectorServerFactory({
+  serverInfo: { name: "drupal-mcp-connector", version: CLIENT_VERSION },
+  tools: { definitions: allDefinitions, call: callTool },
+  resources: { definitions: RESOURCES, read: readResource },
+  prompts: {
+    definitions: ALL_PROMPTS,
+    get: (name, args) => WORKFLOW_PROMPT_NAMES.has(name)
+      ? getPromptMessages(name, args)
+      : getToolPromptMessages(name, args, definitionsByName),
+  },
 });
 
 // ---------------------------------------------------------------------------
@@ -362,22 +335,21 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 // ---------------------------------------------------------------------------
 
 const transport = process.env.MCP_TRANSPORT || "stdio";
+const reportMcpTransportStage = (stage) => {
+  console.error(`[drupal-mcp-connector] MCP ${stage} failed.`);
+};
 
 if (transport === "stdio") {
-  const stdioTransport = new StdioServerTransport();
-  await server.connect(stdioTransport);
+  serveStdio(buildConnectorServer, {
+    legacy: "serve",
+    onerror: () => reportMcpTransportStage("stdio-dispatch"),
+  });
   console.error(
     `[drupal-mcp-connector v${CLIENT_VERSION}] stdio transport active. ` +
     `${allDefinitions.length} tools · ${RESOURCES.length} resources · ${ALL_PROMPTS.length} prompts`
   );
 
 } else if (transport === "https" || transport === "http") {
-
-  // Dynamically import the HTTP transport — only needed in server mode
-  const { StreamableHTTPServerTransport } = await import(
-    "@modelcontextprotocol/sdk/server/streamableHttp.js"
-  );
-
   const tlsCfg     = getTlsConfig();
   const port       = tlsCfg.port;
   const allowHttp  = process.env.MCP_ALLOW_HTTP === "1";
@@ -436,21 +408,6 @@ if (transport === "stdio") {
     });
   }
 
-  // Map of sessionId → transport for multi-client support
-  const sessions = new Map();
-
-  // 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;
-  }
-
   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.
@@ -487,10 +444,22 @@ if (transport === "stdio") {
     );
   }
 
+  const legacyMode = process.env.MCP_LEGACY_TRANSPORT || "serve";
+  const modernMcpHandler = createMcpHandler(buildConnectorServer, {
+    legacy: "reject",
+    onerror: () => reportMcpTransportStage("modern-protocol"),
+  });
+  const modernHandler = toNodeHandler(modernMcpHandler, {
+    onerror: () => reportMcpTransportStage("modern-adapter"),
+  });
+  const legacyHandler = createLegacySessionHandler({
+    buildServer: buildConnectorServer,
+    mode: legacyMode,
+  });
   const requestHandler = createMcpRequestHandler({
     checkAuth,
-    sessions,
-    openSession,
+    modernHandler,
+    legacyHandler,
     toolCount: allDefinitions.length,
     rateLimiter,
   });

package/src/lib/http-handler.js

@@ -2,39 +2,178 @@
  * 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.
+ * testable without standing up a real server. The entry point wires the bearer
+ * check plus strict modern and sessionful legacy handler arms; tests inject
+ * stubs around that same required pair.
  */
 
+import { randomUUID } from "node:crypto";
+import { isInitializeRequest, isJsonContentType, isLegacyRequest } from "@modelcontextprotocol/server";
+import { NodeStreamableHTTPServerTransport, toWebRequest } from "@modelcontextprotocol/node";
+
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+
+class McpHttpClientError extends Error {
+  constructor(statusCode, publicMessage) {
+    super(publicMessage);
+    this.name = "McpHttpClientError";
+    this.statusCode = statusCode;
+    this.publicMessage = publicMessage;
+  }
+}
+
+function defaultOnError({ stage }) {
+  console.error(`[drupal-mcp-connector] MCP ${stage} failed.`);
+}
+
+function reportUnexpected(onError, stage) {
+  try {
+    onError({ stage });
+  } catch {
+    // Diagnostics must never replace the controlled transport response.
+  }
+}
+
+function respondAfterFailure(res, error, onError, stage) {
+  if (error instanceof McpHttpClientError && !res.headersSent) {
+    res.writeHead(error.statusCode).end(error.publicMessage);
+    return;
+  }
+
+  reportUnexpected(onError, stage);
+  if (res.headersSent) {
+    res.destroy();
+    return;
+  }
+  res.writeHead(500).end("Internal Server Error");
+}
+
+async function readJsonBody(req, maxBodyBytes) {
+  const declared = Number(req.headers["content-length"] || 0);
+  if (Number.isFinite(declared) && declared > maxBodyBytes) {
+    throw new McpHttpClientError(413, "Request body exceeds the configured limit");
+  }
+
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += bytes.length;
+    if (size > maxBodyBytes) {
+      throw new McpHttpClientError(413, "Request body exceeds the configured limit");
+    }
+    chunks.push(bytes);
+  }
+
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new McpHttpClientError(400, "Malformed JSON request body");
+  }
+}
+
+/**
+ * Build the bounded 2025-era sessionful transport arm.
+ *
+ * @param {object} deps
+ * @param {(ctx: {era: "legacy"}) => object|Promise<object>} deps.buildServer
+ * @param {Map<string, object>} [deps.sessions]
+ * @param {"serve"|"reject"} [deps.mode]
+ * @param {(options: object) => object} [deps.transportFactory]
+ * @returns {(req: import("http").IncomingMessage, res: import("http").ServerResponse, body?: unknown) => Promise<void>}
+ */
+export function createLegacySessionHandler({
+  buildServer,
+  sessions = new Map(),
+  mode = "serve",
+  transportFactory = (options) => new NodeStreamableHTTPServerTransport(options),
+}) {
+  if (mode !== "serve" && mode !== "reject") {
+    throw new Error(`Invalid legacy MCP transport mode: "${mode}". Use "serve" or "reject".`);
+  }
+
+  async function openSession() {
+    const transport = transportFactory({
+      sessionIdGenerator: randomUUID,
+      onsessioninitialized: (id) => sessions.set(id, transport),
+    });
+    transport.onclose = () => {
+      if (transport.sessionId) sessions.delete(transport.sessionId);
+    };
+    const server = await buildServer({ era: "legacy" });
+    await server.connect(transport);
+    return transport;
+  }
+
+  return async function handleLegacy(req, res, body) {
+    if (mode === "reject") {
+      res.writeHead(400).end("Legacy MCP transport is disabled");
+      return;
+    }
+
+    const sessionId = req.headers["mcp-session-id"];
+    if (sessionId) {
+      const transport = sessions.get(sessionId);
+      if (!transport) {
+        res.writeHead(404).end("Unknown MCP-Session-Id");
+        return;
+      }
+      await transport.handleRequest(req, res, body);
+      return;
+    }
+
+    if (req.method !== "POST" || !isInitializeRequest(body)) {
+      res.writeHead(400).end("MCP-Session-Id is required for legacy session requests");
+      return;
+    }
+
+    const transport = await openSession();
+    await transport.handleRequest(req, res, body);
+  };
+}
+
 /**
  * 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}`).
+ *   - `POST /mcp` — rate- and bearer-gated, bounded/body-parsed once, then
+ *     classified into exactly one modern-stateless or legacy-sessionful arm.
+ *   - `GET|DELETE /mcp` — rate- and bearer-gated legacy session operations.
+ *   - `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 {(req: object, res: object, body?: unknown) => Promise<void>} deps.modernHandler
+ * @param {(req: object, res: object, body?: unknown) => Promise<void>} deps.legacyHandler
  * @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).
+ * @param {number} [deps.maxBodyBytes] Maximum accepted POST body size.
+ * @param {typeof toWebRequest} [deps.toWebRequestFn] Injectable Node-to-Web adapter.
+ * @param {typeof isLegacyRequest} [deps.isLegacyRequestFn] Injectable SDK era classifier.
+ * @param {(event: {stage: string}) => void} [deps.onError] Sanitized diagnostics sink.
  * @returns {(req: import("http").IncomingMessage, res: import("http").ServerResponse) => Promise<void>}
  */
 export function createMcpRequestHandler({
-  checkAuth, sessions, openSession, toolCount,
+  checkAuth, toolCount,
+  modernHandler = null,
+  legacyHandler = null,
   rateLimiter = null,
   clientKey = (req) => req.socket?.remoteAddress || "unknown",
+  maxBodyBytes = DEFAULT_MAX_BODY_BYTES,
+  toWebRequestFn = toWebRequest,
+  isLegacyRequestFn = isLegacyRequest,
+  onError = defaultOnError,
 }) {
+  if (!modernHandler || !legacyHandler) {
+    throw new Error("modernHandler and legacyHandler must be configured together for dual-era routing");
+  }
+
   return async function handle(req, res) {
-    if (req.url === "/mcp" && (req.method === "POST" || req.method === "GET")) {
+    if (req.url === "/mcp" && ["POST", "GET", "DELETE"].includes(req.method)) {
       // Rate limit BEFORE auth so repeated bad-token attempts are throttled too.
       if (rateLimiter) {
         const verdict = rateLimiter.check(clientKey(req));
@@ -50,20 +189,33 @@ export function createMcpRequestHandler({
       }
     }
 
-    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);
+    if (req.url === "/mcp" && (req.method === "GET" || req.method === "DELETE")) {
+      try {
+        await legacyHandler(req, res);
+      } catch (error) {
+        respondAfterFailure(res, error, onError, "legacy-dispatch");
+      }
       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");
+    if (req.method === "POST" && req.url === "/mcp") {
+      if (!isJsonContentType(req.headers["content-type"])) {
+        res.writeHead(415).end("Content-Type must be application/json");
         return;
       }
-      await sessions.get(sessionId).handleRequest(req, res);
+      let stage = "body-read";
+      try {
+        const body = await readJsonBody(req, maxBodyBytes);
+        stage = "request-conversion";
+        const request = await toWebRequestFn(req, body);
+        stage = "classification";
+        const legacy = await isLegacyRequestFn(request, body);
+        const selectedHandler = legacy ? legacyHandler : modernHandler;
+        stage = legacy ? "legacy-dispatch" : "modern-dispatch";
+        await selectedHandler(req, res, body);
+      } catch (error) {
+        respondAfterFailure(res, error, onError, stage);
+      }
       return;
     }
 

package/src/lib/mcp-server.js

@@ -0,0 +1,59 @@
+/**
+ * Transport-neutral MCP server construction.
+ *
+ * The returned factory creates one low-level SDK server for each serving unit:
+ * one request on modern HTTP and one connection on legacy HTTP or stdio.
+ */
+
+import { Server } from "@modelcontextprotocol/server";
+
+/**
+ * Create the server factory shared by HTTP and stdio transports.
+ *
+ * @param {object} surface
+ * @param {{name: string, version: string}} surface.serverInfo
+ * @param {{definitions: Array<object>, call: (name: string, args: object, context: object) => Promise<object>}} surface.tools
+ * @param {{definitions: Array<object>, read: (uri: string) => Promise<object>}} surface.resources
+ * @param {{definitions: Array<object>, get: (name: string, args: object) => Array<object>}} surface.prompts
+ * @returns {(context: import("@modelcontextprotocol/server").McpRequestContext) => Server}
+ */
+export function createConnectorServerFactory({ serverInfo, tools, resources, prompts }) {
+  const toolDefinitions = new Map(tools.definitions.map((definition) => [definition.name, definition]));
+
+  return function buildConnectorServer(_context) {
+    const server = new Server(
+      serverInfo,
+      { capabilities: { tools: {}, resources: {}, prompts: {} } }
+    );
+
+    server.setRequestHandler("tools/list", async () => ({ tools: tools.definitions }));
+    server.setRequestHandler("tools/call", async (request, context) => {
+      const { name, arguments: args } = request.params;
+      const result = await tools.call(name, args ?? {}, context);
+      return server.projectCallToolResult(result, toolDefinitions.get(name)?.outputSchema);
+    });
+
+    server.setRequestHandler("resources/list", async () => ({ resources: resources.definitions }));
+    server.setRequestHandler("resources/read", async (request) => {
+      const { uri } = request.params;
+      try {
+        const data = await resources.read(uri);
+        return {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(data, null, 2) }],
+        };
+      } catch {
+        throw new Error(`Resource read failed (${uri})`);
+      }
+    });
+
+    server.setRequestHandler("prompts/list", async () => ({ prompts: prompts.definitions }));
+    server.setRequestHandler("prompts/get", async (request) => {
+      const { name, arguments: args } = request.params;
+      const known = prompts.definitions.find((prompt) => prompt.name === name);
+      if (!known) throw new Error(`Unknown prompt: "${name}"`);
+      return { description: known.description, messages: prompts.get(name, args ?? {}) };
+    });
+
+    return server;
+  };
+}