drupal-mcp-connector 1.8.1 → 2.0.0

package/.claude/commands/drupal-drush-sql-query.md

@@ -1,12 +1,12 @@
 ---
-description: "Run a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN only) via Drush. Write queries are blocked by the security layer."
+description: "Run a single read-only SELECT through mcp_sentinel's governed command (`drush mcp-sentinel:sql-query`). Requires the site to set drushSsh.rawSql=\"governed\" AND the site's policy profile to set allow_raw_sql; both are off by default. The server refuses statements touching a denied entity type, a non-entity table, or a redacted field, and records every attempt in the tamper-evident audit log. Use the site-context or entity-schema tools for schema introspection."
 argument-hint: "<query> [site]"
 allowed-tools: mcp__drupal__drupal_drush_sql_query
 ---
 
 Call the `mcp__drupal__drupal_drush_sql_query` MCP tool.
 
-Run a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN only) via Drush. Write queries are blocked by the security layer.
+Run a single read-only SELECT through mcp_sentinel's governed command (`drush mcp-sentinel:sql-query`). Requires the site to set drushSsh.rawSql="governed" AND the site's policy profile to set allow_raw_sql; both are off by default. The server refuses statements touching a denied entity type, a non-entity table, or a redacted field, and records every attempt in the tamper-evident audit log. Use the site-context or entity-schema tools for schema introspection.
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/CHANGELOG.md

@@ -5,7 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.0.0] - 2026-07-29
+
+### Changed
+- **BREAKING: `drupal_drush_sql_query` no longer runs ungoverned SQL, and is off
+  by default.** It called `drush sql:query`, which executes below Drupal's
+  entity API — so a site's `mcp_sentinel` policy profile, its denied entity
+  types, its redacted fields and its audit log had no effect on anything this
+  tool read. A statement could return exactly the data the same site refused
+  over JSON:API, and nothing recorded that it had. That is not fixable on the
+  Drupal side: Drush caps `sql:query`'s bootstrap below the level at which
+  module command files are discovered, so no module hook can run on its path.
+  Nor is it fixable here — this process holds the SSH key, so a client-side
+  check is a promise made by the thing being constrained.
+
+  The tool now calls `drush mcp-sentinel:sql-query` (mcp_sentinel ≥ 1.14),
+  where Drupal is fully bootstrapped and the policy profile decides. Two
+  independent opt-ins are required, both off by default: `drushSsh.rawSql:
+  "governed"` on the site here, and `allow_raw_sql` on the policy profile
+  there. There is no ungoverned mode — keeping one behind a flag would have
+  left the bypass a config key away and still invisible when used.
+
+  **To migrate:** set both flags, add `mcp-sentinel:sql-query` to
+  `allowedCommands` if the site pins that list, and expect a narrower tool —
+  the server accepts a single `SELECT` over entity tables only (no `SHOW` /
+  `DESCRIBE` / `EXPLAIN`, no expressions, no `SELECT *` on a table carrying a
+  redacted column). Schema introspection moves to the site-context and
+  entity-schema tools. Sites that do not run mcp_sentinel lose this tool; raw
+  database access belongs to the operator's own shell, not to an agent.
+
+### Fixed
+- **Docs: redirect entities are publishable.** The `redirects.js` header claimed
+  redirect entities have no enabled/disabled flag. That has been stale since the
+  redirect module's dev-1.x made the entity publishable (`enabled` is the published
+  key). Corrected the doc and added a verify-after-create caveat for sites on older
+  `mcp_sentinel` releases (≤ 1.9), where agent-created redirects can arrive silently
+  disabled until the publish gate exempts redirects.
 
 ## [1.8.1] - 2026-07-23
 

package/README.md

@@ -209,6 +209,37 @@ drush mcp-sentinel:setup
 
 Governance keys off the authenticated account's role and OAuth scopes — not request headers. The connector sends an `X-MCP-Client` identity header purely as a log label. See the [MCP Sentinel project page](https://www.drupal.org/project/mcp_sentinel) for the full contract.
 
+### Raw SQL is governed, or it is off
+
+The Drush bridge runs over SSH, which is *below* everything above: a `drush`
+subprocess does not make a request Drupal can govern, and most Drush commands
+never load Drupal's module system at all. `drupal_drush_sql_query` used to
+exploit that without meaning to — it called `drush sql:query`, so no policy
+profile, no denied entity type, no field redaction and no audit entry applied
+to anything it read.
+
+It now calls `drush mcp-sentinel:sql-query` (mcp_sentinel ≥ 1.14), which runs
+with Drupal fully bootstrapped and enforces the same profile that governs
+JSON:API. **Two opt-ins, both off by default**, are required:
+
+```jsonc
+// this connector, per site
+"drushSsh": {
+  "rawSql": "governed",                          // no other value enables it
+  "allowedCommands": ["mcp-sentinel:sql-query"]  // only if you pin this list
+}
+```
+
+…plus `allow_raw_sql` on the policy profile in Drupal. Expect a much narrower
+tool than before: one `SELECT`, entity tables only, no expressions, and no
+`SELECT *` on a table carrying a redacted column. Every attempt — permitted or
+refused — lands in the audit chain with its statement text.
+
+The rest of the bridge (`sql:cli`, `sql:dump`, `php:eval` and anything else you
+reach over SSH) is **outside Drupal governance by construction**. Treat SSH as
+an operator channel: keep the agent's credentials off it, and pin
+`allowedCommands` per site.
+
 ---
 
 ## Documentation

package/config/config.example.json

@@ -70,7 +70,7 @@
       },
       "serverTools": { "url": "/mcp" },
       "drushSsh": {
-        "_comment": "Dev only. DDEV web-container SSH target. Whitelisted to config export/status — every other drupal_drush_* tool is blocked here.",
+        "_comment": "Dev only. DDEV web-container SSH target. Whitelisted to config export/status — every other drupal_drush_* tool is blocked here. rawSql is omitted, so drupal_drush_sql_query is refused: raw SQL reads underneath Drupal's entity API and is only available via mcp_sentinel's governed command. To enable it, set rawSql:\"governed\", add \"mcp-sentinel:sql-query\" to allowedCommands, and set allow_raw_sql on the site's policy profile.",
         "host":            "<ddev-web-container-ssh-host>",
         "user":            "<ddev-ssh-user>",
         "keyPath":         "~/.ssh/id_ed25519",

package/package.json

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

package/src/lib/validate.js

@@ -66,7 +66,13 @@ export function validateUuid(value, fieldName = "id") {
 // SQL query validation (read-only enforcement for Drush bridge)
 // ---------------------------------------------------------------------------
 
-const SAFE_SQL_PREFIXES = ["select ", "show ", "describe ", "explain ", "desc "];
+// SELECT only. SHOW / DESCRIBE / EXPLAIN used to be accepted here, but raw SQL
+// now runs through mcp_sentinel's governed command, which accepts SELECT alone
+// — schema introspection has a governed home on the /drupal-mcp/context
+// endpoint and the entity-schema tools. Keeping the wider list here would mean
+// this check passed statements the server then refused, i.e. two policies
+// disagreeing, which is the failure mode this whole change exists to remove.
+const SAFE_SQL_PREFIXES = ["select "];
 
 // Patterns that indicate write operations even within SELECT contexts
 const DANGEROUS_SQL_PATTERNS = [
@@ -80,7 +86,14 @@ const DANGEROUS_SQL_PATTERNS = [
 
 /**
  * Validate that a SQL query is read-only.
- * Checks both the query prefix AND secondary injection patterns.
+ *
+ * This is a fast local reject, NOT the authority. The authority is
+ * mcp_sentinel's McpRawSqlGuard, which runs inside Drupal where the policy
+ * profile lives and can resolve denied entity types and redacted fields down
+ * to real tables and columns — something no client-side check can do. This
+ * check exists only to fail obvious cases without an SSH round trip, so it is
+ * deliberately kept coarser than, and never wider than, the server's.
+ *
  * @param {string} query The SQL query to validate.
  * @returns {string} The validated query.
  * @throws {Error} if the query is empty or exceeds the length cap.
@@ -95,8 +108,9 @@ export function validateSqlQuery(query) {
 
   if (!SAFE_SQL_PREFIXES.some((prefix) => normalised.startsWith(prefix))) {
     throw new SecurityError(
-      "drupal_drush_sql_query only permits SELECT, SHOW, DESCRIBE, and EXPLAIN statements. " +
-      "Use the JSON:API tools for write operations."
+      "drupal_drush_sql_query only permits SELECT statements. " +
+      "Use the JSON:API tools for write operations, and the site-context or " +
+      "entity-schema tools for schema introspection."
     );
   }
 

package/src/tools/drush.js

@@ -7,7 +7,11 @@
  *   1. SSH key auth only — password-based SSH is deliberately unsupported.
  *   2. All command arguments are validated before being passed to SSH.
  *   3. Module names are validated as machine names (a-z, 0-9, _) only.
- *   4. SQL tool enforces SELECT-only allowlist — no DDL/DML permitted.
+ *   4. Raw SQL runs ONLY through mcp_sentinel's governed command, and only for
+ *      a site that opts in with drushSsh.rawSql="governed". The SELECT-only
+ *      check here is a fast local reject; the site's policy profile is the
+ *      authority, because this process holds the SSH key and cannot police
+ *      itself.
  *   5. Key path is validated against path traversal.
  *   6. All operations are logged to stderr with site name and command.
  *   7. Write operations assert non-readOnly via the security layer.
@@ -58,6 +62,32 @@ function assertCommandAllowed(sshCfg, subcommand) {
   }
 }
 
+/**
+ * Enforce the per-site opt-in for raw SQL.
+ *
+ * Raw SQL is off unless a site sets `drushSsh.rawSql: "governed"`. There is no
+ * ungoverned mode: the previous behaviour — running the statement through
+ * `drush sql:query` — bypassed the site's entire policy and left no audit
+ * record, so it was removed rather than kept behind a flag. A flag would have
+ * meant the bypass was one config key away and still invisible when used.
+ *
+ * @param {object} sshCfg Resolved drushSsh config block.
+ * @param {string} siteName Site name, for the error message.
+ * @returns {void}
+ * @throws {SecurityError} if the site has not opted in.
+ */
+function assertGovernedRawSql(sshCfg, siteName) {
+  if (sshCfg.rawSql !== "governed") {
+    throw new SecurityError(
+      `Raw SQL is disabled for site "${siteName}". Raw SQL reads underneath Drupal's ` +
+      "entity API, so it is only available through mcp_sentinel's governed command. " +
+      "To enable it: install mcp_sentinel on the site, set `allow_raw_sql` on the policy " +
+      "profile that governs the agent, and set `rawSql: \"governed\"` in this site's " +
+      "drushSsh config (plus `mcp-sentinel:sql-query` in allowedCommands if that list is set)."
+    );
+  }
+}
+
 /**
  * Resolve and validate the SSH key path. Prevents path traversal.
  */
@@ -400,18 +430,45 @@ async function drushCreateUser({ site: siteName, name, mail, password, roles = [
 }
 
 /**
- * Run a read-only SQL query (`drush sql:query`). The query is validated against
- * a SELECT-only allowlist before execution.
+ * Run a read-only SQL query through mcp_sentinel's governed command.
+ *
+ * This used to call `drush sql:query`, which was a hole straight through the
+ * site's policy: `sql:query` runs below Drupal's entity API, so no policy
+ * profile, no denied_entity_types, no redacted_fields and no audit entry ever
+ * applied to it. That is not a fixable property of the command — Drush caps
+ * its bootstrap below the level at which Drupal discovers module command
+ * files, so no module code can run on its path at all.
+ *
+ * `mcp-sentinel:sql-query` is a module-provided command, so Drupal is fully
+ * bootstrapped: the policy profile applies, the statement is checked against
+ * the same deny and redaction lists that govern JSON:API, and every attempt —
+ * permitted or refused — is written to the tamper-evident audit chain with its
+ * statement text. Enforcement is therefore server-side, which matters because
+ * this process holds the SSH key and cannot be trusted to police itself.
+ *
  * @param {object} args - { site?, query }.
- * @returns {Promise<{rows: *}>}
- * @throws {SecurityError} If the query is not read-only.
+ * @returns {Promise<object>} The server's payload: { rows, row_count, truncated, profile }.
+ * @throws {SecurityError} If the site has not opted in, or the query is not read-only.
  */
 async function sqlQuery({ site: siteName, query }) {
-  const site = getSiteConfig(siteName);
-  // Throws SecurityError if query is not read-only
+  const site   = getSiteConfig(siteName);
+  const sshCfg = getDrushConfig(site);
+  assertGovernedRawSql(sshCfg, site._name);
+  // Fast local reject only; mcp_sentinel's guard is the authority.
   validateSqlQuery(query);
-  const out = await sshDrush(site, ["sql:query", query]);
-  return { rows: parseDrush(out) };
+  const out = await sshDrush(site, ["mcp-sentinel:sql-query", query]);
+  // The command emits a JSON object; a non-JSON reply means the command was
+  // not found (mcp_sentinel absent or too old), which must not be reported as
+  // an empty result set.
+  const payload = parseDrush(out);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload) || !Array.isArray(payload.rows)) {
+    throw new Error(
+      `Raw SQL on site "${site._name}" did not return a governed result. ` +
+      "Confirm mcp_sentinel >= 1.14 is installed and enabled on the target site — " +
+      "`drush mcp-sentinel:sql-query` must exist there."
+    );
+  }
+  return payload;
 }
 
 /**
@@ -477,7 +534,7 @@ export const definitions = [
   },
   {
     name: "drupal_drush_sql_query",
-    description: "Run a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN only) via Drush. Write queries are blocked by the security layer.",
+    description: "Run a single read-only SELECT through mcp_sentinel's governed command (`drush mcp-sentinel:sql-query`). Requires the site to set drushSsh.rawSql=\"governed\" AND the site's policy profile to set allow_raw_sql; both are off by default. The server refuses statements touching a denied entity type, a non-entity table, or a redacted field, and records every attempt in the tamper-evident audit log. Use the site-context or entity-schema tools for schema introspection.",
     inputSchema: { type: "object", required: ["query"], properties: { site: { type: "string" }, query: { type: "string" } } },
   },
   {

package/src/tools/redirects.js

@@ -19,11 +19,15 @@
  *   - `status_code` defaults to 301 and can be set to 302 (or another redirect
  *     code) explicitly on create, and changed on an existing redirect via update.
  *
- * Redirect entities have no separate enabled/disabled flag — a redirect with a
- * valid source is active. "Enable an existing redirect" therefore means: correct
- * its fields so it matches and fires, which is exactly what drupal_update_redirect
- * does. Both tools are governed: writes assert create/update permission for the
- * `redirect` entity type against the per-site security policy.
+ * Redirect module ≥ dev-1.x makes redirects publishable: an `enabled` base field
+ * (the published key) decides whether the redirect fires. This connector does not
+ * send `enabled` — sites govern that flag server-side (mcp_sentinel's publish
+ * gate exempted it as routing metadata as of its post-1.9 release; on older
+ * sentinel releases a deny-publish profile silently disables agent-created
+ * redirects — verify `enabled` after create on such sites). On pre-publishable
+ * redirect releases the field is absent and every redirect with a valid source
+ * is active. Both tools are governed: writes assert create/update permission for
+ * the `redirect` entity type against the per-site security policy.
  */
 
 import { getSiteConfig } from "../lib/config.js";