drupal-mcp-connector 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-06-27
+
+### Fixed
+- The server-tool bridge client now performs the MCP Streamable-HTTP session handshake
+  before calling governed config tools. It POSTs `initialize`, reads the `Mcp-Session-Id`
+  response header, sends `notifications/initialized`, then issues `tools/call` carrying that
+  session id — caching the session per site and re-initialising transparently on server-side
+  expiry. Previously it POSTed a bare `tools/call` with no session, which Drupal's
+  session-mandatory `mcp_server` rejected with `-32600` ("A valid session id is REQUIRED for
+  non-initialize requests"), so `drupal_config_get` / `_list` / `_set` always failed. Responses
+  are now parsed for both `application/json` and `text/event-stream` (SSE) transports, and the
+  request advertises `MCP-Protocol-Version: 2025-06-18`. The existing 401 → token-refresh retry
+  is preserved and layered with a single session re-init/replay.
+
+## [1.3.0] - 2026-06-27
+
+### Fixed
+- `drupal_mcp_whoami` no longer over-reports configuration capabilities. Capabilities are
+  now the intersection of the connector security preset **and** the token's effective OAuth
+  scopes: `configRead` / `configWrite` require the dedicated `mcp_config` scope (config-editor
+  / Developer tier), and `write` / `delete` require `mcp_write`. Previously a content-tier
+  token (`mcp_read` / `mcp_write`) was reported with `configRead: true` even though the server
+  denies every `config_*` tool without `mcp_config`. When a site declares no OAuth scopes,
+  behaviour is unchanged (preset-only).
+
+### Changed
+- The config tools (`config_get` / `config_list` / `config_set`) now check for the
+  `mcp_config` scope up front (when OAuth scopes are configured) and fail fast with a clear
+  message instead of dispatching a call the governed server will deny — keeping connector
+  behaviour consistent with `drupal_mcp_whoami`. Aligns with mcp_sentinel isolating the config
+  tools under the dedicated `mcp_config` scope.
+
 ## [1.2.0] - 2026-06-27
 
 ### Changed

package/README.md

@@ -166,7 +166,7 @@ The connector works out of the box against Drupal core's JSON:API and a GraphQL
 - Role-bound policy profiles (operation gates, entity allow/deny, field redaction)
 - Tamper-evident audit log of every governed MCP operation, attributed to the acting account
 - Content locks that prevent edits to content a human is actively editing
-- OAuth scope enforcement (`mcp_read` / `mcp_write`) per tool
+- OAuth scope enforcement (`mcp_read` / `mcp_write` / `mcp_config`) per tool
 - HMAC-signed webhooks on MCP-driven entity changes
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "1.2.0",
+  "version": "1.3.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/lib/security.js

@@ -323,6 +323,41 @@ export function assertConfigWriteAllowed(secConfig) {
   }
 }
 
+/**
+ * Whether the site's OAuth token carries a given scope. When the site declares
+ * no OAuth scopes (no agent channel configured), scope gating is a no-op and
+ * this returns true so preset-only (non-OAuth) setups are unaffected.
+ * @param {object} site Resolved site config.
+ * @param {string} scope OAuth scope machine id (e.g. "mcp_config").
+ * @returns {boolean} True if the scope is present, or no scopes are configured.
+ */
+export function hasScope(site, scope) {
+  const scopes = site?.oauth?.scopes ?? [];
+  return scopes.length === 0 || scopes.includes(scope);
+}
+
+/**
+ * Gate the config tools (get/list/set) on the dedicated `mcp_config` OAuth
+ * scope, which the governed server requires for every config_* tool. When OAuth
+ * scopes are configured but `mcp_config` is absent, fail fast with a clear
+ * message instead of dispatching a call the server will deny — keeping the
+ * connector's behaviour and its drupal_mcp_whoami report consistent with what
+ * the token can actually exercise.
+ * @param {object} site Resolved site config.
+ * @param {string} operationLabel Label used in the error message.
+ * @returns {void}
+ * @throws {SecurityError} if scopes are configured and `mcp_config` is missing.
+ */
+export function assertConfigScope(site, operationLabel) {
+  if (!hasScope(site, "mcp_config")) {
+    throw new SecurityError(
+      "Config tools require the 'mcp_config' OAuth scope (config-editor / " +
+      "Developer tier); this token does not carry it. " +
+      `Operation blocked: ${operationLabel}.`
+    );
+  }
+}
+
 /**
  * @param {object} secConfig Resolved security config.
  * @param {string} entityType Entity type targeted by the delete.

package/src/lib/server-tools.js

@@ -7,10 +7,13 @@
  * the connector an MCP *client* of that server so config get/list/set are
  * mediated by Drupal's authoritative governance layer rather than by drush.
  *
- * Transport: JSON-RPC 2.0 over HTTPS POST to the per-site `serverTools.url`
- * endpoint, authenticated with the same OAuth bearer used for JSON:API. The
- * endpoint path is configurable so it tracks whatever route the Drupal-side
- * bridge publishes.
+ * Transport: JSON-RPC 2.0 over the MCP Streamable-HTTP transport, POSTed to the
+ * per-site `serverTools.url` endpoint and authenticated with the same OAuth
+ * bearer used for JSON:API. Drupal's `mcp_server` is session-mandatory, so each
+ * call site performs the MCP session handshake — `initialize` (read the
+ * `Mcp-Session-Id` response header) → `notifications/initialized` → `tools/call`
+ * carrying that session id. The session is cached per site and transparently
+ * re-initialised when the server expires it.
  *
  * Config (per site):
  *   "serverTools": { "url": "/mcp" }   // path is resolved against site.baseUrl
@@ -20,7 +23,7 @@
  */
 
 import fetch from "node-fetch";
-import { authHeadersAsync, clientHeaders } from "./config.js";
+import { authHeadersAsync, clientHeaders, CLIENT_VERSION } from "./config.js";
 import { clearToken } from "./oauth.js";
 
 /**
@@ -38,10 +41,20 @@ export const SERVER_TOOLS = {
   configSet:  "tool_api.mcp_sentinel_config_set",
 };
 
+/** MCP protocol version advertised on the handshake and every subsequent POST. */
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+
 // Monotonic JSON-RPC request id. A simple counter keeps ids unique per process
 // without relying on Math.random()/Date.now().
 let rpcId = 0;
 
+/**
+ * Per-site MCP session cache, keyed by site._name. Holds the `Mcp-Session-Id`
+ * issued by the server's `initialize` response; cleared and re-acquired when the
+ * server reports the session is gone (expiry).
+ */
+const sessions = new Map();
+
 /**
  * Resolve a site's server-tools endpoint, or throw a clear, actionable error
  * when the site has no `serverTools` block (mirrors the drush bridge's
@@ -63,11 +76,175 @@ function resolveEndpoint(site) {
   return /^https?:\/\//.test(url) ? url : `${site.baseUrl}${url}`;
 }
 
+/**
+ * Build the common header set for an MCP POST: JSON-RPC content type, dual Accept
+ * (the server may answer with JSON or an SSE stream), the protocol version, the
+ * outbound client identity, the site's auth, and — when present — the session id.
+ * @param {object} site Resolved site config.
+ * @param {?string} sessionId Active MCP session id, or null before initialize.
+ * @returns {Promise<Object<string,string>>} Header map.
+ */
+async function baseHeaders(site, sessionId) {
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+    "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+    ...clientHeaders(),
+    ...(await authHeadersAsync(site)),
+  };
+  if (sessionId) headers["Mcp-Session-Id"] = sessionId;
+  return headers;
+}
+
+/**
+ * Read an MCP response body once, handling both `application/json` and
+ * `text/event-stream` (SSE) transports. SSE frames are split on blank lines and
+ * each event's concatenated `data:` payload is parsed as the JSON-RPC body.
+ * @param {object} res node-fetch Response.
+ * @returns {Promise<{body: ?object, rawText: string}>} Parsed JSON-RPC body
+ *   (null for empty/unparseable bodies, e.g. a notification's 202) plus the raw text.
+ */
+async function readBody(res) {
+  const rawText = await res.text();
+  if (!rawText) return { body: null, rawText };
+
+  const contentType = res.headers.get("content-type") || "";
+  if (contentType.includes("text/event-stream")) {
+    return { body: parseSse(rawText), rawText };
+  }
+  try {
+    return { body: JSON.parse(rawText), rawText };
+  } catch {
+    return { body: null, rawText };
+  }
+}
+
+/**
+ * Parse an SSE stream into the JSON-RPC body it carries. Returns the last event
+ * whose `data:` payload parses to a JSON-RPC object (a `tools/call` reply is a
+ * single event), or null if none do.
+ * @param {string} text Raw event-stream text.
+ * @returns {?object} The decoded JSON-RPC body, or null.
+ */
+function parseSse(text) {
+  let found = null;
+  for (const event of text.split(/\r?\n\r?\n/)) {
+    const data = event
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trim())
+      .join("\n");
+    if (!data) continue;
+    try {
+      found = JSON.parse(data);
+    } catch {
+      // Skip non-JSON events (e.g. comments/keep-alives).
+    }
+  }
+  return found;
+}
+
+/**
+ * Perform the MCP session handshake against the server and cache the resulting
+ * session id: `initialize` (read the `Mcp-Session-Id` response header) followed
+ * by a best-effort `notifications/initialized`. A 401 on OAuth sites triggers a
+ * single token-refresh retry, mirroring the tools/call path.
+ * @param {object} site Resolved site config.
+ * @param {string} endpoint Fully-qualified endpoint URL.
+ * @returns {Promise<string>} The issued MCP session id.
+ * @throws {Error} on transport failure, a JSON-RPC error, or a missing session id.
+ */
+async function initializeSession(site, endpoint) {
+  const payload = {
+    jsonrpc: "2.0",
+    id: ++rpcId,
+    method: "initialize",
+    params: {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "drupal-mcp-connector", version: CLIENT_VERSION },
+    },
+  };
+
+  const post = async () =>
+    fetch(endpoint, {
+      method: "POST",
+      headers: await baseHeaders(site, null),
+      body: JSON.stringify(payload),
+    });
+
+  let res = await post();
+  if (res.status === 401 && site.oauth) {
+    clearToken(site);
+    res = await post();
+  }
+
+  const { body, rawText } = await readBody(res);
+  if (!res.ok) {
+    throw new Error(`Server-tool session initialize failed ${res.status}: ${rawText}`);
+  }
+  if (body?.error) {
+    const { code, message } = body.error;
+    const hasCode = code !== undefined && code !== null;
+    throw new Error(`Server-tool session initialize error${hasCode ? ` (${code})` : ""}: ${message}`);
+  }
+
+  const sessionId = res.headers.get("mcp-session-id");
+  if (!sessionId) {
+    throw new Error(
+      `Server-tool session initialize for site "${site._name}" returned no Mcp-Session-Id header.`
+    );
+  }
+
+  // Best-effort: the server may not require notifications/initialized, and a
+  // non-2xx here must not fail the call. Errors are swallowed deliberately.
+  try {
+    await fetch(endpoint, {
+      method: "POST",
+      headers: await baseHeaders(site, sessionId),
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+    });
+  } catch {
+    // Notification is advisory; proceed with the established session.
+  }
+
+  sessions.set(site._name, sessionId);
+  return sessionId;
+}
+
+/**
+ * Return the cached session id for a site, initialising one if absent.
+ * @param {object} site Resolved site config.
+ * @param {string} endpoint Fully-qualified endpoint URL.
+ * @returns {Promise<string>} The active MCP session id.
+ */
+async function ensureSession(site, endpoint) {
+  const cached = sessions.get(site._name);
+  return cached || initializeSession(site, endpoint);
+}
+
+/**
+ * Whether a tools/call response indicates the MCP session is gone (expired or
+ * unknown), warranting a single re-initialise and replay: an HTTP 404, or the
+ * server's `-32600` "session id is REQUIRED" JSON-RPC error.
+ * @param {object} res node-fetch Response.
+ * @param {?object} body Parsed JSON-RPC body, if any.
+ * @returns {boolean}
+ */
+function isSessionError(res, body) {
+  if (res.status === 404) return true;
+  const err = body?.error;
+  if (!err) return false;
+  return err.code === -32600 || /session id/i.test(String(err.message || ""));
+}
+
 /**
  * Call a governed MCP tool on the Drupal server via JSON-RPC `tools/call`.
  *
- * For OAuth2 sites a 401 triggers a single retry: the cached token is cleared,
- * re-acquired, and the request replayed once (mirrors drupalFetch).
+ * Establishes/reuses an MCP session (see initializeSession) and POSTs the
+ * `tools/call`. Two single-shot recoveries layer on top of each other: a 401 on
+ * OAuth sites clears and re-acquires the token then replays (same session); a
+ * server-side session expiry re-initialises the session then replays.
  * @param {object} site Resolved site config (provides baseUrl + auth).
  * @param {string} toolName Server-side MCP tool name (see SERVER_TOOLS).
  * @param {object} [args] Tool arguments object.
@@ -83,48 +260,53 @@ export async function callServerTool(site, toolName, args = {}) {
     params: { name: toolName, arguments: args },
   };
 
-  async function attempt() {
-    return fetch(endpoint, {
+  let sessionId = await ensureSession(site, endpoint);
+  let refreshedAuth = false;
+  let reinitedSession = false;
+
+  // Retry loop: at most one auth refresh and one session re-init, each replayed once.
+  while (true) {
+    const res = await fetch(endpoint, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
-        ...clientHeaders(),
-        ...(await authHeadersAsync(site)),
-      },
+      headers: await baseHeaders(site, sessionId),
       body: JSON.stringify(payload),
     });
-  }
+    const { body, rawText } = await readBody(res);
 
-  let res = await attempt();
+    // OAuth sites: a 401 may mean the token expired server-side. Refresh once.
+    if (res.status === 401 && site.oauth && !refreshedAuth) {
+      refreshedAuth = true;
+      clearToken(site);
+      continue;
+    }
 
-  // OAuth sites: a 401 may mean the token expired server-side. Refresh once.
-  if (res.status === 401 && site.oauth) {
-    clearToken(site);
-    res = await attempt();
-  }
+    // Session expired/unknown: re-initialise once and replay.
+    if (isSessionError(res, body) && !reinitedSession) {
+      reinitedSession = true;
+      sessions.delete(site._name);
+      sessionId = await ensureSession(site, endpoint);
+      continue;
+    }
 
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Server-tool call ${toolName} failed ${res.status}: ${text}`);
-  }
+    if (!res.ok) {
+      throw new Error(`Server-tool call ${toolName} failed ${res.status}: ${rawText}`);
+    }
 
-  const body = await res.json();
-
-  // JSON-RPC transport-level error.
-  if (body.error) {
-    const { code, message } = body.error;
-    const hasCode = code !== undefined && code !== null;
-    throw new Error(`Server-tool ${toolName} error${hasCode ? ` (${code})` : ""}: ${message}`);
-  }
+    // JSON-RPC transport-level error.
+    if (body?.error) {
+      const { code, message } = body.error;
+      const hasCode = code !== undefined && code !== null;
+      throw new Error(`Server-tool ${toolName} error${hasCode ? ` (${code})` : ""}: ${message}`);
+    }
 
-  // MCP tools/call result: { content: [...], isError?: boolean }.
-  const result = body.result;
-  if (result?.isError) {
-    const detail = extractTextContent(result) || "tool reported an error";
-    throw new Error(`Server-tool ${toolName} reported an error: ${detail}`);
+    // MCP tools/call result: { content: [...], isError?: boolean }.
+    const result = body?.result;
+    if (result?.isError) {
+      const detail = extractTextContent(result) || "tool reported an error";
+      throw new Error(`Server-tool ${toolName} reported an error: ${detail}`);
+    }
+    return result;
   }
-  return result;
 }
 
 /**

package/src/tools/config.js

@@ -18,6 +18,8 @@ import {
   assertNotReadOnly,
   assertConfigReadAllowed,
   assertConfigWriteAllowed,
+  assertConfigScope,
+  hasScope,
 } from "../lib/security.js";
 import { callServerTool, SERVER_TOOLS } from "../lib/server-tools.js";
 
@@ -33,6 +35,7 @@ import { callServerTool, SERVER_TOOLS } from "../lib/server-tools.js";
  */
 async function configGet({ site: siteName, name }) {
   const site = getSiteConfig(siteName);
+  assertConfigScope(site, `config:get ${name}`);
   assertConfigReadAllowed(resolveSecurityConfig(site));
   return callServerTool(site, SERVER_TOOLS.configGet, { name });
 }
@@ -45,6 +48,7 @@ async function configGet({ site: siteName, name }) {
  */
 async function configList({ site: siteName, prefix }) {
   const site = getSiteConfig(siteName);
+  assertConfigScope(site, "config:list");
   assertConfigReadAllowed(resolveSecurityConfig(site));
   const args = prefix ? { prefix } : {};
   return callServerTool(site, SERVER_TOOLS.configList, args);
@@ -60,6 +64,7 @@ async function configList({ site: siteName, prefix }) {
 async function configSet({ site: siteName, name, value }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
+  assertConfigScope(site, `config:set ${name}`);
   assertNotReadOnly(sec, `config:set ${name}`);
   assertConfigWriteAllowed(sec);
   return callServerTool(site, SERVER_TOOLS.configSet, { name, value });
@@ -100,6 +105,13 @@ async function whoami({ site: siteName }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   const summary = getSecuritySummary(site);
+  // Effective capability = connector preset AND the scope the server demands.
+  // Reporting the preset alone over-states what the token can do — e.g. the
+  // content-editor preset allows config reads locally, but every config_* tool
+  // is gated server-side on mcp_config, which the content tier does not hold.
+  // When no OAuth scopes are configured, hasScope() is a no-op (preset-only).
+  const canWrite  = !sec.readOnly && hasScope(site, "mcp_write");
+  const canConfig = hasScope(site, "mcp_config");
   return {
     site: site._name,
     tier: inferTier(site, sec),
@@ -108,11 +120,11 @@ async function whoami({ site: siteName }) {
     api: site.api ?? "auto",
     serverToolsConfigured: Boolean(site.serverTools?.url),
     capabilities: {
-      read:        true,
-      write:       !sec.readOnly,
-      delete:      sec.allowDestructive && !sec.readOnly,
-      configRead:  sec.allowConfigRead,
-      configWrite: sec.allowConfigWrite && !sec.readOnly,
+      read:        hasScope(site, "mcp_read"),
+      write:       canWrite,
+      delete:      sec.allowDestructive && canWrite,
+      configRead:  sec.allowConfigRead  && canConfig,
+      configWrite: sec.allowConfigWrite && !sec.readOnly && canConfig,
       // Publishing is always gated server-side (editorial workflow); the agent
       // never holds the publish transition. Surfaced here so it is explicit.
       publish:     false,