drupal-mcp-connector 2.1.0 → 2.2.0

package/.claude/commands/drupal-graphql-introspect.md

@@ -1,12 +1,12 @@
 ---
-description: "Introspect the Drupal GraphQL schema. Omit typeName for a full schema overview; provide typeName to get detailed fields and args for a specific type."
+description: "Introspect the Drupal GraphQL schema. Omit typeName for a full schema overview; provide typeName to get detailed fields and args for a specific type. Requires security.allowGraphql (off outside the development preset by default)."
 argument-hint: "[site] [typeName]"
 allowed-tools: mcp__drupal__drupal_graphql_introspect
 ---
 
 Call the `mcp__drupal__drupal_graphql_introspect` MCP tool.
 
-Introspect the Drupal GraphQL schema. Omit typeName for a full schema overview; provide typeName to get detailed fields and args for a specific type.
+Introspect the Drupal GraphQL schema. Omit typeName for a full schema overview; provide typeName to get detailed fields and args for a specific type. Requires security.allowGraphql (off outside the development preset by default).
 
 Parse the request in `$ARGUMENTS` into this tool's parameters:
 

package/.claude/commands/drupal-graphql.md

@@ -1,5 +1,5 @@
 ---
-description: "Execute a GraphQL query against a Drupal site. Requires the GraphQL Compose module (drupal.org/project/graphql_compose), which exposes a read-only schema; mutations are gated by \"allowGraphqlMutations\". Use drupal_graphql_introspect first to discover available types and fields. Example query: query GetArticle($id: String!) { nodeById(id: $id) { title ... on NodeArticle { body { value } } } } Example mutation (only if your GraphQL Compose schema enables mutations): mutation CreateArticle($title: String!, $body: String!) { createNodeArticle(data: { title: $title, body: { value: $body, format: \"full_html\" } }) { entity { title uuid } errors { message } } }"
+description: "Execute a GraphQL query against a Drupal site. Requires the GraphQL Compose module (drupal.org/project/graphql_compose), which exposes a read-only schema. GraphQL is off unless security.allowGraphql is true (development preset only by default) because raw results bypass entity allowlists and field redaction. Mutations also require allowGraphqlMutations. Use drupal_graphql_introspect first to discover available types and fields. Example query: query GetArticle($id: String!) { nodeById(id: $id) { title ... on NodeArticle { body { value } } } } Example mutation (only if your GraphQL Compose schema enables mutations): mutation CreateArticle($title: String!, $body: String!) { createNodeArticle(data: { title: $title, body: { value: $body, format: \"full_html\" } }) { entity { title uuid } errors { message } } }"
 argument-hint: "<query> [site] [variables] [operationName]"
 allowed-tools: mcp__drupal__drupal_graphql
 ---
@@ -8,7 +8,9 @@ Call the `mcp__drupal__drupal_graphql` MCP tool.
 
 Execute a GraphQL query against a Drupal site.
 Requires the GraphQL Compose module (drupal.org/project/graphql_compose), which
-exposes a read-only schema; mutations are gated by "allowGraphqlMutations".
+exposes a read-only schema. GraphQL is off unless security.allowGraphql is true
+(development preset only by default) because raw results bypass entity allowlists
+and field redaction. Mutations also require allowGraphqlMutations.
 Use drupal_graphql_introspect first to discover available types and fields.
 
 Example query:

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-07-30
+
+### Security
+- **Default security preset is `production-strict` (#140).** Omitting `security`
+  or passing `{}` no longer opens the site under the `development` preset.
+  Local and integration work must set `"preset": "development"` (or another
+  explicit preset) deliberately. Migration: add
+  `"security": { "preset": "development" }` to any site config that relied on
+  the old open default.
+- **GraphQL tools fail closed (#142).** `drupal_graphql` and
+  `drupal_graphql_introspect` require `security.allowGraphql` (true only on the
+  `development` preset). Mutations still need `allowGraphqlMutations` as well.
+  When GraphQL is opted in, results remain raw (no entity allowlist/redaction
+  on that path); prefer JSON:API entity tools for policy-bound reads.
+- **Dependency advisories cleared (#128).** Bump
+  `@modelcontextprotocol/sdk` to `^1.30.0` and pin overrides for
+  `@hono/node-server` `^2.0.5` and `postcss` `^8.5.18` so `npm audit` reports
+  zero vulnerabilities.
+
+### Documentation
+- README, security guide, threat model, architecture, tools reference, and
+  SECURITY.md updated for the secure default, GraphQL gate, and residual-risk
+  table.
+
+## [2.1.1] - 2026-07-31
+
+### Documentation
+- **npm package page / README.** Security model table lists all six presets and
+  the 2.1 connector-side gates (entity policy on specialized tools, publish/draft
+  defaults, upload roots, fail-closed HTTPS). Quick start leads with `npm install`
+  for package consumers; clone path remains for development.
+- Normalize `package.json` `repository.url` to the form npm expects
+  (`git+https://…`).
+
 ## [2.1.0] - 2026-07-31
 
 ### Security

package/README.md

@@ -125,7 +125,11 @@ Other MCP agents don't need this step — they get the same coverage from the pe
 prompts above.
 
 ### Security Model
-Defense-in-depth with four one-line presets, enforced connector-side and complemented by Drupal-side governance:
+
+Defense-in-depth presets, enforced connector-side and complemented by Drupal-side
+governance (MCP Sentinel). **Default when `security` is omitted:**
+`production-strict` (read-only, sensitive types denied). Local development must
+set `"preset": "development"` explicitly.
 
 ```json
 "security": { "preset": "auditor" }
@@ -133,12 +137,22 @@ Defense-in-depth with four one-line presets, enforced connector-side and complem
 
 | Preset | What it does |
 |--------|-------------|
-| `development` | Everything allowed — local development only |
-| `content-editor` | Create/edit nodes, media, terms; no deletes; no publishing (`allowPublish` off); no user access |
-| `auditor` | Read-only, all entity types, PII fields redacted |
-| `production-strict` | Read-only, no user entities, broad PII redaction |
+| `development` | Everything allowed, including GraphQL — local development only |
+| `content-editor` | Create/edit content + structural entities; no deletes; no publishing; secrets/governance/account types denied |
+| `config-editor` | content-editor + site-building config read + governed config write (developer tier) |
+| `auditor` | Read-only; secrets/governance/account types denied; user PII redacted when user is allowed |
+| `production-strict` | Read-only; same sensitive denylist as auditor; broad PII field redaction (**default**) |
+| `write-plane` | Create/update content set for agents; no deletes; no GraphQL; publish off by default |
+
+Additional connector-side gates (2.1+ / 2.2+):
+
+- **Entity allowlists** apply to specialized tools (`drupal_*_node`, media, taxonomy), not only `drupal_entity_*`.
+- **Publish gate:** `status: true` and `moderation_state: "published"` require `allowPublish`. Media create defaults **unpublished**. Published moderated node updates without a moderation state default to **draft** (forward revision).
+- **Uploads** only from `MCP_UPLOAD_ROOT` (or the process cwd); sensitive paths (`.env*`, `.ssh`, connector `config.json`) are refused.
+- **HTTPS:** non-loopback binds require `MCP_AUTH_TOKEN` (or `MCP_ALLOW_UNAUTHENTICATED=1` behind a trusted proxy); non-loopback TLS defaults to 120 req/min rate limiting.
+- **GraphQL is off by default.** `drupal_graphql` / introspect require `security.allowGraphql` (true only on the `development` preset). Raw GraphQL results still bypass entity allowlists and field redaction — prefer JSON:API entity tools when connector policy must hold. Mutations also need `allowGraphqlMutations`.
 
-Presets layer with entity allow/deny lists, per-bundle operation rules, and field-level redaction. Optional transport hardening (bearer-authenticated HTTPS, bind-address restriction, secrets-from-env) is covered in **[docs/security-hardening.md](docs/security-hardening.md)**.
+Full detail: **[docs/security.md](docs/security.md)** and **[docs/security-hardening.md](docs/security-hardening.md)**.
 
 ---
 
@@ -154,30 +168,38 @@ Presets layer with entity allow/deny lists, per-bundle operation rules, and fiel
 
 ## Quick Start
 
+### From npm (recommended for operators)
+
+```bash
+npm install -g drupal-mcp-connector
+# or: npx -y drupal-mcp-connector
+```
+
+Point your MCP client at the installed binary (path from `which drupal-mcp-connector`
+or `node_modules/.bin/drupal-mcp-connector`). For multi-site or non-env config,
+clone the repo (or copy `config/config.example.json` beside a small launcher) and
+pass a config path — see **[docs/getting-started.md](docs/getting-started.md)**.
+
+### From a git clone (development)
+
 ```bash
-# 1. Clone and install
 git clone https://github.com/Wilkes-Liberty/drupal-mcp-connector
 cd drupal-mcp-connector
 npm install
-
-# 2. Configure
 cp config/config.example.json config/config.json
-# Edit config/config.json — add your site's baseUrl, api backend, and auth
-
-# 3. Run (stdio transport)
+# Edit config/config.json — baseUrl, api backend, auth, security preset
 node src/index.js
 ```
 
 ### Register with an MCP client
 
-Most desktop and CLI MCP clients launch the connector over **stdio**. Add an entry to your client's MCP server configuration:
+Most desktop and CLI MCP clients launch the connector over **stdio**:
 
 ```json
 {
   "mcpServers": {
     "drupal": {
-      "command": "node",
-      "args": ["/absolute/path/to/drupal-mcp-connector/src/index.js"],
+      "command": "drupal-mcp-connector",
       "env": {
         "DRUPAL_BASE_URL": "https://mysite.com",
         "DRUPAL_API_TOKEN": "your-token-here"
@@ -187,7 +209,10 @@ Most desktop and CLI MCP clients launch the connector over **stdio**. Add an ent
 }
 ```
 
-For multi-client or remote use, run the HTTPS transport and register the endpoint instead — see **[docs/getting-started.md](docs/getting-started.md)**.
+Or with an absolute path to `src/index.js` / the installed package. For multi-client
+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)**.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.1.0",
+  "version": "2.2.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",
@@ -31,7 +31,7 @@
   "homepage": "https://github.com/Wilkes-Liberty/drupal-mcp-connector",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Wilkes-Liberty/drupal-mcp-connector.git"
+    "url": "git+https://github.com/Wilkes-Liberty/drupal-mcp-connector.git"
   },
   "bugs": {
     "url": "https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues"
@@ -58,16 +58,20 @@
     "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.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "graphql": "^17.0.0",
     "node-fetch": "^3.3.2",
     "ssh2": "^1.16.0"
   },
   "devDependencies": {
     "eslint": "^10.4.1",
-    "eslint-plugin-security": "^4.0.0",
     "eslint-plugin-n": "^18.1.0",
+    "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",
     "vitest": "^4.1.8"
+  },
+  "overrides": {
+    "@hono/node-server": "^2.0.5",
+    "postcss": "^8.5.18"
   }
 }

package/src/lib/security.js

@@ -12,13 +12,14 @@ import { parse } from "graphql";
  *
  * ─── Quick presets ────────────────────────────────────────────────────────
  *
- *   "preset": "development"        Everything allowed. Default if no security key.
+ *   "preset": "development"        Everything allowed. Opt-in only — set explicitly.
  *   "preset": "content-editor"     Create/edit content (nodes, media, terms, paragraphs, blocks,
  *                                  menu links, redirects, aliases, files). No deletes. Config read-only.
  *   "preset": "config-editor"      content-editor + site-building config READ + governed config
  *                                  read/write (Developer tier). Model changes go via the config bridge.
- *   "preset": "auditor"            Read-only. All entity types. User fields redacted.
- *   "preset": "production-strict"  Read-only. Explicit allowlist required. Redacts PII.
+ *   "preset": "auditor"            Read-only. Sensitive entity types denied. User fields redacted.
+ *   "preset": "production-strict"  Read-only. Sensitive types denied. Redacts PII. **Default** when
+ *                                  security is omitted or has no preset (#140).
  *   "preset": "write-plane"        Governed writes (no delete/mutations) on the content set
  *                                  (node, term, media + structural content entities).
  *
@@ -31,7 +32,8 @@ import { parse } from "graphql";
  *
  *  readOnly            true  → reject all create/update/delete/graphql-mutation calls
  *  allowDestructive    false → reject all delete operations
- *  allowPublish        false → reject a write carrying status:true (publishing)
+ *  allowPublish        false → reject a write carrying status:true / moderation_state:published
+ *  allowGraphql        false → reject drupal_graphql + introspect (raw GraphQL is policy-free, #142)
  *  allowGraphqlMutations false → reject drupal_graphql when mutation is detected
  *  allowConfigRead     false → reject drupal_config_get / drupal_config_list
  *  allowConfigWrite    false → reject drupal_config_set
@@ -118,6 +120,7 @@ const PRESETS = {
     readOnly: false,
     allowDestructive: true,
     allowPublish: true,               // mirrors allowDestructive: everything allowed
+    allowGraphql: true,               // raw GraphQL allowed only in open mode (#142)
     allowGraphqlMutations: true,
     allowConfigRead: true,
     allowConfigWrite: true,
@@ -130,6 +133,7 @@ const PRESETS = {
   "content-editor": {
     readOnly: false,
     allowDestructive: false,          // no deletes
+    allowGraphql: false,              // freeform GraphQL bypasses entity denylists (#142)
     allowGraphqlMutations: false,
     allowConfigRead: true,            // config read-only
     allowConfigWrite: false,
@@ -151,6 +155,7 @@ const PRESETS = {
     // The Drupal-side governance layer remains authoritative; this is defence in depth.
     readOnly: false,
     allowDestructive: false,          // no deletes
+    allowGraphql: false,
     allowGraphqlMutations: false,
     allowConfigRead: true,
     allowConfigWrite: true,           // governed config writes via drupal_config_set
@@ -171,6 +176,7 @@ const PRESETS = {
   auditor: {
     readOnly: true,
     allowDestructive: false,
+    allowGraphql: false,
     allowGraphqlMutations: false,
     allowConfigRead: true,            // read-only inspection of config
     allowConfigWrite: false,
@@ -189,6 +195,7 @@ const PRESETS = {
   "production-strict": {
     readOnly: true,
     allowDestructive: false,
+    allowGraphql: false,
     allowGraphqlMutations: false,
     allowConfigRead: false,           // nothing implicit; opt in per site
     allowConfigWrite: false,
@@ -203,6 +210,7 @@ const PRESETS = {
     // Drupal-side governance layer remains authoritative; this is defence in depth.
     readOnly: false,
     allowDestructive: false,          // no deletes
+    allowGraphql: false,              // JSON:API write plane; GraphQL is policy-free (#142)
     allowGraphqlMutations: false,     // writes go through the JSON:API plane
     allowConfigRead: true,            // config read-only
     allowConfigWrite: false,
@@ -225,15 +233,22 @@ const PRESETS = {
  * @param {object} site Site config (reads site.security).
  * @returns {object} Effective security config used by the assert/redact helpers.
  */
+/** Default when `security.preset` is omitted — least privilege, not open mode (#140). */
+export const DEFAULT_SECURITY_PRESET = "production-strict";
+
 export function resolveSecurityConfig(site) {
   const raw = site.security ?? {};
-  const preset = PRESETS[raw.preset ?? "development"] ?? PRESETS.development;
+  // Explicit preset wins; bare {} / missing security → production-strict (#140).
+  // Open mode requires `preset: "development"` (or another named preset).
+  const presetName = raw.preset ?? DEFAULT_SECURITY_PRESET;
+  const preset = PRESETS[presetName] ?? PRESETS[DEFAULT_SECURITY_PRESET];
 
   // Merge: explicit keys in site.security override the preset
   return {
     readOnly:              raw.readOnly              ?? preset.readOnly,
     allowDestructive:      raw.allowDestructive      ?? preset.allowDestructive,
     allowPublish:          raw.allowPublish          ?? preset.allowPublish          ?? false,
+    allowGraphql:          raw.allowGraphql          ?? preset.allowGraphql          ?? false,
     allowGraphqlMutations: raw.allowGraphqlMutations ?? preset.allowGraphqlMutations,
     allowConfigRead:       raw.allowConfigRead       ?? preset.allowConfigRead       ?? false,
     allowConfigWrite:      raw.allowConfigWrite      ?? preset.allowConfigWrite      ?? false,
@@ -450,7 +465,30 @@ function graphqlHasMutation(query) {
  * @returns {void} No-op for read-only (query) documents.
  * @throws {SecurityError} if the document is a mutation and writes/mutations are disabled.
  */
+/**
+ * Gate GraphQL queries and schema introspection. Freeform GraphQL returns raw
+ * data that does not pass through entity allowlists or field redaction (#142),
+ * so it is off by default outside the development preset. Opt in with
+ * `security.allowGraphql: true`.
+ *
+ * @param {object} secConfig Resolved security config.
+ * @param {string} [operationLabel] Label for the error message.
+ * @returns {void}
+ * @throws {SecurityError} if GraphQL is disabled for this site.
+ */
+export function assertGraphqlAllowed(secConfig, operationLabel = "graphql") {
+  if (secConfig.allowGraphql) return;
+  throw new SecurityError(
+    "GraphQL tools are disabled for this site (allowGraphql: false). " +
+    "Raw GraphQL responses bypass connector entity allowlists and field redaction. " +
+    `Blocked: ${operationLabel}. ` +
+    "Set security.allowGraphql = true to enable (prefer development preset or an explicit opt-in)."
+  );
+}
+
 export function assertGraphqlMutationAllowed(secConfig, query) {
+  // Queries still require allowGraphql (#142); mutations require both flags.
+  assertGraphqlAllowed(secConfig, "graphql mutation");
   const isMutation = graphqlHasMutation(query);
   if (!isMutation) return;
 
@@ -681,9 +719,11 @@ export function getSecuritySummary(site) {
   const cfg = resolveSecurityConfig(site);
   return {
     site:                  site._name,
-    preset:                site.security?.preset ?? "development (default)",
+    preset:                site.security?.preset ?? `${DEFAULT_SECURITY_PRESET} (default)`,
     readOnly:              cfg.readOnly,
     allowDestructive:      cfg.allowDestructive,
+    allowPublish:          cfg.allowPublish,
+    allowGraphql:          cfg.allowGraphql,
     allowGraphqlMutations: cfg.allowGraphqlMutations,
     allowConfigRead:       cfg.allowConfigRead,
     allowConfigWrite:      cfg.allowConfigWrite,

package/src/tools/graphql.js

@@ -3,9 +3,12 @@
  *
  * Raw GraphQL execution and schema introspection against a Drupal site. Require
  * the GraphQL Compose module (drupal.org/project/graphql_compose), which
- * exposes a read-only schema (no mutations); any mutation in a query is
- * additionally gated by the per-site "allowGraphqlMutations" security flag,
- * enforced by the middleware in index.js before the handler runs.
+ * exposes a read-only schema (no mutations).
+ *
+ * Policy: responses are raw GraphQL data — they do **not** pass connector entity
+ * allowlists or field redaction (#142). Tools are gated by `allowGraphql`
+ * (false outside the development preset unless opted in). Mutations also require
+ * `allowGraphqlMutations` (enforced in the handler and by index.js middleware).
  *
  * Per-site config: set "graphqlEndpoint" to override "/graphql".
  * Auth reuses the same credentials as the JSON:API tools.
@@ -13,6 +16,9 @@
 
 import { getSiteConfig } from "../lib/config.js";
 import { drupalGraphqlFetch } from "../lib/drupal-fetch.js";
+import {
+  resolveSecurityConfig, assertGraphqlAllowed, assertGraphqlMutationAllowed,
+} from "../lib/security.js";
 
 // ---------------------------------------------------------------------------
 // Implementations
@@ -29,6 +35,9 @@ import { drupalGraphqlFetch } from "../lib/drupal-fetch.js";
  */
 async function runGraphql({ site: siteName, query, variables = {}, operationName }) {
   const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertGraphqlAllowed(sec, "drupal_graphql");
+  assertGraphqlMutationAllowed(sec, query);
   const json = await drupalGraphqlFetch(site, { query, variables, operationName });
 
   if (json.errors?.length) {
@@ -54,6 +63,7 @@ async function runGraphql({ site: siteName, query, variables = {}, operationName
  */
 async function introspectGraphql({ site: siteName, typeName }) {
   const site = getSiteConfig(siteName);
+  assertGraphqlAllowed(resolveSecurityConfig(site), "drupal_graphql_introspect");
 
   // If a specific type is requested, get detailed field info for it.
   if (typeName) {
@@ -128,7 +138,9 @@ export const definitions = [
     name: "drupal_graphql",
     description: `Execute a GraphQL query against a Drupal site.
 Requires the GraphQL Compose module (drupal.org/project/graphql_compose), which
-exposes a read-only schema; mutations are gated by "allowGraphqlMutations".
+exposes a read-only schema. GraphQL is off unless security.allowGraphql is true
+(development preset only by default) because raw results bypass entity allowlists
+and field redaction. Mutations also require allowGraphqlMutations.
 Use drupal_graphql_introspect first to discover available types and fields.
 
 Example query:
@@ -158,7 +170,7 @@ Example mutation (only if your GraphQL Compose schema enables mutations):
   },
   {
     name: "drupal_graphql_introspect",
-    description: "Introspect the Drupal GraphQL schema. Omit typeName for a full schema overview; provide typeName to get detailed fields and args for a specific type.",
+    description: "Introspect the Drupal GraphQL schema. Omit typeName for a full schema overview; provide typeName to get detailed fields and args for a specific type. Requires security.allowGraphql (off outside the development preset by default).",
     inputSchema: {
       type: "object",
       properties: {