drupal-mcp-connector 2.2.2 → 2.4.0

package/.claude/commands/drupal-governance-status.md

@@ -0,0 +1,16 @@
+---
+description: "Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial."
+argument-hint: "[site]"
+allowed-tools: mcp__drupal__drupal_governance_status
+---
+
+Call the `mcp__drupal__drupal_governance_status` MCP tool.
+
+Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial.
+
+Parse the request in `$ARGUMENTS` into this tool's parameters:
+
+**Optional:**
+- `site` (string): omit for the default site
+
+If a required parameter is missing from `$ARGUMENTS`, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-08-14
+
+### Added
+
+- **Source governance is now enforceable on every governed product path
+  (#176).** A site with `requireGovernance: true` requires the Drupal
+  source's governance contract to verify before any tool call runs against
+  it: the connector probes `GET /drupal-mcp/readiness` as its own principal
+  (mcp_sentinel ≥ 2.4.0), caches a passing verdict for 60 seconds, and
+  re-proves it after that. A failed, stale, or unreachable verification
+  denies tool discovery and execution with the source's own stable reason —
+  it never falls back to a plain JSON:API or GraphQL path, on any backend or
+  bridge. The new `drupal_governance_status` tool stays callable while
+  governance is failing and reports which required condition failed, without
+  credentials. Ungoverned sites are untouched.
+
+### Changed
+
+- The security middleware and tools/call dispatch moved from the entry point
+  into `src/lib/dispatch.js` (side-effect-free, testable per backend); the
+  entry point now only boots transports. Tool discovery accepts a per-request
+  `list` hook so governance can gate what is discoverable.
+
+## [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/config/config.example.json

@@ -7,7 +7,7 @@
   },
 
   "_security_options": {
-    "_comment": "All optional. apiTokenEnv: read the Bearer token from this env var instead of apiToken (keeps secrets out of the config file). requireSecureAuth: reject anon/basic, require HTTPS+Bearer (recommended for production). Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_AUTH_TOKEN requires bearer auth on the HTTPS /mcp endpoint; MCP_BIND_HOST restricts the listen interface (with TLS). See docs/security-hardening.md."
+    "_comment": "All optional. apiTokenEnv: read the Bearer token from this env var instead of apiToken (keeps secrets out of the config file). requireSecureAuth: reject anon/basic, require HTTPS+Bearer (recommended for production). requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel >= 2.4.0) verifies — no ungoverned JSON:API/GraphQL fallback; recommended wherever mcp_sentinel governs the site. Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_AUTH_TOKEN requires bearer auth on the HTTPS /mcp endpoint; MCP_BIND_HOST restricts the listen interface (with TLS). See docs/security-hardening.md."
   },
 
   "_governance_tiers": {
@@ -28,6 +28,7 @@
       "_comment": "Content tier. Content/media/term CRUD; config read-only; cannot publish (server-side editorial gate). No drushSsh.",
       "baseUrl":           "https://api.int.wilkesliberty.com",
       "requireSecureAuth": true,
+      "requireGovernance": true,
       "api":               "jsonapi",
       "oauth": {
         "tokenUrl":        "/oauth/token",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.2.2",
+  "version": "2.4.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,89 +20,28 @@
  *                     (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,
-  SecurityError }            from "./lib/security.js";
-import { toolError, toolResult }    from "./lib/errors.js";
-import { BackendCapabilityError, BackendResolutionError } from "./lib/backends/errors.js";
+import { callTool } from "./lib/dispatch.js";
+import { filterDiscoverableTools } from "./lib/governance.js";
 
 // Tools — aggregated (single source of truth, side-effect-free) and per-tool prompts
 import { allDefinitions, allHandlers, definitionsByName } from "./tools/index.js";
 import { buildToolPrompts, getToolPromptMessages } from "./lib/tool-prompts.js";
-import { inferOperation } from "./lib/operations.js";
-
-// ---------------------------------------------------------------------------
-// Security middleware — runs BEFORE every tool handler
-//
-// Operation intent (read/write/delete/graphql) is inferred from the tool name
-// prefix rather than trusting per-tool metadata, so a new tool that follows the
-// naming convention is gated automatically. The matched operation drives which
-// assertions from lib/security.js run against the resolved per-site policy.
-// ---------------------------------------------------------------------------
-
-/**
- * Derive the entity type a tool acts on, for destructive-allow assertions.
- *
- * @param {string} toolName - The MCP tool name.
- * @param {object} args     - The tool arguments.
- * @returns {string} Explicit args.entityType when present, else the suffix
- *   parsed from the tool name (e.g. "node" from "drupal_delete_node"),
- *   falling back to "entity".
- */
-function extractEntityType(toolName, args) {
-  if (args?.entityType) return args.entityType;
-  const m = toolName.match(/^drupal_(?:delete|create|update|get|list)_(.+)$/);
-  return m ? m[1] : "entity";
-}
-
-/**
- * Apply per-site security assertions before dispatching to a tool handler.
- *
- * @param {string}   toolName - The MCP tool name.
- * @param {object}   args     - Tool arguments (may carry `site`, `id`, etc.).
- * @param {Function} handler  - The resolved tool handler.
- * @returns {Promise<*>} The handler's result.
- * @throws {SecurityError} If the resolved policy forbids the inferred operation.
- */
-async function securityMiddleware(toolName, args, handler) {
-  // Tools with no site context skip per-site checks
-  if (toolName === "drupal_list_sites") return handler(args);
-
-  const site = getSiteConfig(args?.site);
-  const sec  = resolveSecurityConfig(site);
-  const op   = inferOperation(toolName);
-
-  if (op === "delete") {
-    assertDestructiveAllowed(sec, extractEntityType(toolName, args), args?.id ?? "?");
-    assertNotReadOnly(sec, toolName);
-  } else if (op === "write") {
-    assertNotReadOnly(sec, toolName);
-  } else if (op === "graphql" && args?.query) {
-    assertGraphqlMutationAllowed(sec, args.query);
-  }
-
-  return handler(args);
-}
 
 // ---------------------------------------------------------------------------
 // MCP Resources — browsable, always-fresh site context
@@ -290,71 +229,23 @@ function getPromptMessages(name, args) {
 }
 
 // ---------------------------------------------------------------------------
-// MCP Server construction
+// MCP Server surface — dispatch (middleware + callTool) lives in lib/dispatch.js
 // ---------------------------------------------------------------------------
 
-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;
-  // 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];
-
-  if (!handler) {
-    return toolError(new Error(
-      `Unknown tool "${name}". Call drupal_list_entity_types to discover available resources.`
-    ));
-  }
-
-  try {
-    const result = await securityMiddleware(name, args ?? {}, handler);
-    return toolResult(result);
-  } catch (err) {
-    // Translate known error classes into clear, non-leaky isError responses;
-    // anything else falls through to toolError for a generic envelope.
-    if (err instanceof SecurityError) {
-      return { content: [{ type: "text", text: `Access denied: ${err.message}` }], isError: true };
-    }
-    if (err instanceof BackendCapabilityError) {
-      return { content: [{ type: "text", text: `Not supported by this site's backend: ${err.message}` }], isError: true };
-    }
-    if (err instanceof BackendResolutionError) {
-      return { content: [{ type: "text", text: `Backend resolution failed: ${err.message}` }], isError: true };
-    }
-    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,
+    list: () => filterDiscoverableTools(allDefinitions, listSiteNames().map((n) => getSiteConfig(n))),
+    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 +253,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 +326,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 +362,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/dispatch.js

@@ -0,0 +1,113 @@
+/**
+ * Tool dispatch — the security middleware and the tools/call entry point.
+ *
+ * Lives outside src/index.js (which boots a transport on import) so the
+ * gate order — source governance first, then per-site security assertions,
+ * then the handler — is testable per tool and per backend. Every tool call,
+ * whichever backend or bridge it ends up on, flows through here: denial in
+ * this module is denial on every path, with no ungoverned fallback below it.
+ */
+
+import { getSiteConfig } from "./config.js";
+import { resolveSecurityConfig, assertNotReadOnly,
+  assertDestructiveAllowed, assertGraphqlMutationAllowed,
+  SecurityError } from "./security.js";
+import { toolError, toolResult } from "./errors.js";
+import { BackendCapabilityError, BackendResolutionError } from "./backends/errors.js";
+import { inferOperation } from "./operations.js";
+import { assertSourceGovernance, GovernanceError, GOVERNANCE_DIAGNOSTIC_TOOLS } from "./governance.js";
+import { allHandlers } from "../tools/index.js";
+
+/**
+ * Derive the entity type a tool acts on, for destructive-allow assertions.
+ *
+ * @param {string} toolName - The MCP tool name.
+ * @param {object} args     - The tool arguments.
+ * @returns {string} Explicit args.entityType when present, else the suffix
+ *   parsed from the tool name (e.g. "node" from "drupal_delete_node"),
+ *   falling back to "entity".
+ */
+function extractEntityType(toolName, args) {
+  if (args?.entityType) return args.entityType;
+  const m = toolName.match(/^drupal_(?:delete|create|update|get|list)_(.+)$/);
+  return m ? m[1] : "entity";
+}
+
+/**
+ * Apply per-site governance and security assertions before dispatching.
+ *
+ * @param {string}   toolName - The MCP tool name.
+ * @param {object}   args     - Tool arguments (may carry `site`, `id`, etc.).
+ * @param {Function} handler  - The resolved tool handler.
+ * @returns {Promise<*>} The handler's result.
+ * @throws {GovernanceError} If the site requires source governance and the
+ *   contract is not verified — checked FIRST, so no assertion below can be
+ *   read as an ungoverned fallback verdict.
+ * @throws {SecurityError} If the resolved policy forbids the inferred operation.
+ */
+export async function securityMiddleware(toolName, args, handler) {
+  // Tools with no site context skip per-site checks
+  if (toolName === "drupal_list_sites") return handler(args);
+
+  const site = getSiteConfig(args?.site);
+
+  // Source-governance gate (#176). The diagnostic tools stay callable while
+  // governance fails — they are how an operator learns which condition failed.
+  if (!GOVERNANCE_DIAGNOSTIC_TOOLS.has(toolName)) {
+    await assertSourceGovernance(site);
+  }
+
+  const sec  = resolveSecurityConfig(site);
+  const op   = inferOperation(toolName);
+
+  if (op === "delete") {
+    assertDestructiveAllowed(sec, extractEntityType(toolName, args), args?.id ?? "?");
+    assertNotReadOnly(sec, toolName);
+  } else if (op === "write") {
+    assertNotReadOnly(sec, toolName);
+  } else if (op === "graphql" && args?.query) {
+    assertGraphqlMutationAllowed(sec, args.query);
+  }
+
+  return handler(args);
+}
+
+/**
+ * Serve one MCP tools/call request: resolve the handler, run the middleware,
+ * translate known error classes into clear, non-leaky isError envelopes.
+ *
+ * @param {string} name - The MCP tool name.
+ * @param {object} args - The tool arguments.
+ * @returns {Promise<object>} An MCP tool result payload.
+ */
+export 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];
+
+  if (!handler) {
+    return toolError(new Error(
+      `Unknown tool "${name}". Call drupal_list_entity_types to discover available resources.`
+    ));
+  }
+
+  try {
+    const result = await securityMiddleware(name, args ?? {}, handler);
+    return toolResult(result);
+  } catch (err) {
+    // Translate known error classes into clear, non-leaky isError responses;
+    // anything else falls through to toolError for a generic envelope.
+    if (err instanceof GovernanceError) {
+      return { content: [{ type: "text", text: `Source governance unavailable: ${err.message}` }], isError: true };
+    }
+    if (err instanceof SecurityError) {
+      return { content: [{ type: "text", text: `Access denied: ${err.message}` }], isError: true };
+    }
+    if (err instanceof BackendCapabilityError) {
+      return { content: [{ type: "text", text: `Not supported by this site's backend: ${err.message}` }], isError: true };
+    }
+    if (err instanceof BackendResolutionError) {
+      return { content: [{ type: "text", text: `Backend resolution failed: ${err.message}` }], isError: true };
+    }
+    return toolError(err);
+  }
+}

package/src/lib/governance.js

@@ -0,0 +1,204 @@
+/**
+ * Source-governance verification for governed sites (#176).
+ *
+ * A site with `requireGovernance: true` declares that every product path —
+ * tool discovery and execution, on every backend — depends on the Drupal
+ * source's governance layer (MCP Sentinel) being present, applicable, and
+ * enforcing. The connector verifies that claim against the source's own
+ * readiness contract (`GET /drupal-mcp/readiness`, authenticated as the
+ * connector's principal) and DENIES instead of falling back to a plain
+ * JSON:API or GraphQL path when the contract is not ready, cannot be
+ * reached, or the verification has gone stale and cannot be refreshed.
+ *
+ * The readiness endpoint answers for the whole contract: module present,
+ * an applicable active policy/profile for the requesting principal, and the
+ * enforcement wiring active. Its `reason` values are stable, non-secret
+ * diagnostics designed to be surfaced to operators verbatim.
+ */
+
+import fetch from "node-fetch";
+import { authHeadersAsync, clientHeaders } from "./config.js";
+
+/** How long a passing verification stays fresh before it must be re-proven. */
+export const OK_TTL_MS = 60_000;
+
+/** How long a failed verification is held before the next attempt re-checks. */
+export const FAIL_TTL_MS = 5_000;
+
+/** Tools that stay discoverable and callable while governance is failing —
+ * the diagnostic surface an operator needs to see WHY it is failing. */
+export const GOVERNANCE_DIAGNOSTIC_TOOLS = new Set([
+  "drupal_list_sites",
+  "drupal_governance_status",
+]);
+
+/** Denial for a governed path whose source-governance contract is not verified. */
+export class GovernanceError extends Error {
+  /**
+   * @param {string} message Operator-facing description (no secrets).
+   * @param {string} reason  Stable machine reason (e.g. "sentinel_unreachable").
+   */
+  constructor(message, reason) {
+    super(message);
+    this.name = "GovernanceError";
+    this.reason = reason;
+  }
+}
+
+/** Per-site verification cache: name → {ok, reason, checkedAt}. */
+const cache = new Map();
+
+/** Drop all cached verifications (tests, config reloads). */
+export function clearGovernanceCache() {
+  cache.clear();
+}
+
+/**
+ * Whether a site declares the source-governance requirement.
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+export function requiresGovernance(site) {
+  return site?.requireGovernance === true;
+}
+
+/**
+ * Verify the site's source-governance contract, with a short-lived cache.
+ *
+ * Never throws: the result carries `ok` plus a stable `reason` on failure.
+ * A stale cache entry is re-verified; if the re-check cannot happen the
+ * result is a failure — staleness never extends trust.
+ *
+ * @param {object} site Resolved site config.
+ * @param {{force?: boolean}} [options] `force` bypasses the cache.
+ * @returns {Promise<{ok: boolean, reason: string|null, checkedAt: number}>}
+ */
+export async function verifySourceGovernance(site, { force = false } = {}) {
+  const key = site._name ?? site.baseUrl;
+  const cached = cache.get(key);
+  if (!force && cached) {
+    const age = Date.now() - cached.checkedAt;
+    if (age <= (cached.ok ? OK_TTL_MS : FAIL_TTL_MS)) return cached;
+  }
+
+  const result = await probeReadiness(site);
+  cache.set(key, result);
+  return result;
+}
+
+/**
+ * One authenticated readiness probe; maps every outcome to {ok, reason}.
+ * @param {object} site Resolved site config.
+ * @returns {Promise<{ok: boolean, reason: string|null, checkedAt: number}>}
+ */
+async function probeReadiness(site) {
+  const checkedAt = Date.now();
+
+  // Credential construction is its own failure class: an OAuth token the
+  // connector cannot acquire is the connector's principal failing, and must
+  // not be misreported as the source being unreachable.
+  let headers;
+  try {
+    headers = {
+      Accept: "application/json",
+      ...clientHeaders(),
+      ...(await authHeadersAsync(site)),
+    };
+  } catch {
+    return { ok: false, reason: "credential_acquisition_failed", checkedAt };
+  }
+
+  let res;
+  try {
+    res = await fetch(`${site.baseUrl}/drupal-mcp/readiness`, { method: "GET", headers });
+  } catch {
+    // Network detail (addresses, DNS text) is deliberately not propagated.
+    return { ok: false, reason: "sentinel_unreachable", checkedAt };
+  }
+
+  if (res.status === 404) {
+    return { ok: false, reason: "sentinel_unavailable", checkedAt };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, reason: "not_authorized_for_governance", checkedAt };
+  }
+
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    return { ok: false, reason: "unexpected_response", checkedAt };
+  }
+
+  if (res.status === 200 && body?.contract_ready === true) {
+    return { ok: true, reason: null, checkedAt };
+  }
+  if (body?.contract_ready === false) {
+    // The server's own stable, non-secret readiness reason.
+    return { ok: false, reason: String(body.reason ?? "contract_not_ready"), checkedAt };
+  }
+  return { ok: false, reason: "unexpected_response", checkedAt };
+}
+
+/**
+ * Gate a governed product path: no-op for ungoverned sites, throws otherwise
+ * unless the source contract verifies.
+ *
+ * @param {object} site Resolved site config.
+ * @returns {Promise<void>}
+ * @throws {GovernanceError} naming the failed condition (never secrets).
+ */
+export async function assertSourceGovernance(site) {
+  if (!requiresGovernance(site)) return;
+  const result = await verifySourceGovernance(site);
+  if (result.ok) return;
+  throw new GovernanceError(
+    `Site "${site._name}" requires source governance and the contract is not verified ` +
+    `(${result.reason}). Governed paths are denied — there is no ungoverned fallback. ` +
+    "Run drupal_governance_status for per-site diagnostics.",
+    result.reason,
+  );
+}
+
+/**
+ * Per-site governance condition for operator diagnostics. No secrets: only
+ * the site name, whether governance is required, the verdict, and the reason.
+ *
+ * @param {Array<object>} sites Resolved site configs.
+ * @returns {Promise<Array<{site: string, required: boolean, ok: boolean, reason: string|null, checkedAt: number|null}>>}
+ */
+export async function governanceStatus(sites) {
+  return Promise.all(sites.map(async (site) => {
+    if (!requiresGovernance(site)) {
+      return { site: site._name, required: false, ok: true, reason: null, checkedAt: null };
+    }
+    const result = await verifySourceGovernance(site);
+    return {
+      site: site._name,
+      required: true,
+      ok: result.ok,
+      reason: result.reason,
+      checkedAt: result.checkedAt,
+    };
+  }));
+}
+
+/**
+ * Discovery gate: hide governed tools when NO configured site can serve them.
+ *
+ * A site can serve governed tools when it is either ungoverned or its source
+ * contract verifies. While at least one site qualifies the full surface stays
+ * discoverable (execution remains per-site gated); when none does, only the
+ * diagnostic tools remain, so a client sees the denial instead of a surface
+ * it cannot use.
+ *
+ * @param {Array<object>} definitions Tool definitions ({name, ...}).
+ * @param {Array<object>} sites       Resolved site configs.
+ * @returns {Promise<Array<object>>} The discoverable definitions.
+ */
+export async function filterDiscoverableTools(definitions, sites) {
+  const verdicts = await Promise.all(sites.map(async (site) =>
+    !requiresGovernance(site) || (await verifySourceGovernance(site)).ok));
+  if (verdicts.some(Boolean)) return definitions;
+  return definitions.filter((d) => GOVERNANCE_DIAGNOSTIC_TOOLS.has(d.name));
+}

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,63 @@
+/**
+ * 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>, list?: () => Promise<Array<object>>, call: (name: string, args: object, context: object) => Promise<object>}} surface.tools
+ *   `definitions` is the full static surface (schema projection); the optional
+ *   `list` hook decides what is DISCOVERABLE per request (governance gating).
+ * @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.list ? await tools.list() : 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;
+  };
+}

package/src/tools/site.js

@@ -7,6 +7,7 @@
  */
 
 import { getSiteConfig, listSiteNames } from "../lib/config.js";
+import { governanceStatus } from "../lib/governance.js";
 import { resolveBackend } from "../lib/backends/index.js";
 
 // ---------------------------------------------------------------------------
@@ -49,6 +50,19 @@ async function listConfiguredSites() {
   return { sites: listSiteNames() };
 }
 
+/**
+ * Per-site source-governance condition (#176). The one governed-path
+ * diagnostic that stays callable while governance is failing, so an operator
+ * can see WHICH required condition failed. Never includes credentials.
+ *
+ * @param {object} args - { site? } (a named site narrows the report).
+ * @returns {Promise<{sites: object[]}>} required/ok/reason per site.
+ */
+async function getGovernanceStatus({ site: siteName } = {}) {
+  const names = siteName ? [siteName] : listSiteNames();
+  return { sites: await governanceStatus(names.map((n) => getSiteConfig(n))) };
+}
+
 // ---------------------------------------------------------------------------
 // Definitions
 // ---------------------------------------------------------------------------
@@ -70,6 +84,14 @@ export const definitions = [
       properties: { site: { type: "string" } },
     },
   },
+  {
+    name: "drupal_governance_status",
+    description: "Report each configured site's source-governance condition: whether governance is required, whether the source contract verifies, and the failed condition when it does not. Callable even while governed paths are denied — this is the diagnostic for that denial.",
+    inputSchema: {
+      type: "object",
+      properties: { site: { type: "string" } },
+    },
+  },
   {
     name: "drupal_list_sites",
     description: "List all named Drupal sites configured in config.json. Useful for multi-site setups.",
@@ -84,4 +106,5 @@ export const handlers = {
   drupal_site_info:          getSiteInfo,
   drupal_list_content_types: listContentTypes,
   drupal_list_sites:         listConfiguredSites,
+  drupal_governance_status:  getGovernanceStatus,
 };