drupal-mcp-connector 2.25.0 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,120 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-10-01
+
+### Fixed
+- **`drupal_schedule_publish` site refusals (#402).** A 422 such as
+  `publish_state: You do not have access to transition from Draft to
+  Published` was rewritten as "Scheduler fields are not available", because
+  any message naming a Scheduler field counted as a missing field. Only the
+  "The attribute X does not exist on the Y resource type" form counts now. Other 4xx refusals,
+  including MCP Sentinel denials, return the site's reason verbatim with the
+  HTTP status.
+- **`drupal_schedule_publish` no longer refuses on its own (#402).** A
+  moderated bundle without `publish_state` / `unpublish_state` is written and
+  the result carries a warning; Drupal and Sentinel decide. A date without
+  its state is still refused when the bundle has the state field, since
+  Drupal accepts that schedule and it never runs. That check now also applies
+  when `moderation_state` is not visible to the account.
+- **`drupal_report_scheduled_content` on an empty bundle (#403).** A bundle
+  with no nodes reports pending 0 / overdue 0 with `schedulerFields:
+  "unknown"` instead of `gated: true`. A gated bundle that hit the sample cap
+  keeps `approximate: true`.
+- **`listContentTypes` read only the first 50 node types (JSON:API).** It
+  now follows `links.next`, so all-bundle scans and
+  `drupal_report_content_summary` see every content type.
+
+### Changed
+- **No node tool defaults to the `article` bundle any more (#403).** On a
+  site without that bundle the old default returned a 404 or scanned nothing.
+  - Require `type`: `drupal_report_duplicate_content`, `_workflow_bottlenecks`,
+    `_translation_coverage`, `_readability`, `_orphan_pages`, `_pii_exposure`,
+    `_seo_meta_coverage`, `_stale_content`, `_content_by_author`,
+    `_revision_hotspots`, `_seo_audit`, `_accessibility_audit`,
+    `_broken_links`, `_alias_coverage`, `_broken_embeds`, `_missing_field` and
+    `_orphaned_references`. `drupal_report_taxonomy_usage` requires
+    `contentType`. The error points to `drupal_list_content_types`.
+  - Scan every node bundle when `type` is omitted:
+    `drupal_report_scheduled_content` (one row per bundle in `byContentType`),
+    `drupal_report_recently_published` and `drupal_report_unpublished`
+    (merged newest first; unreadable bundles in `bundleErrors`), and
+    `drupal_search` / `drupal_search_content` (merged newest first; a bundle
+    that cannot be read fails the search and is named).
+  - `drupal_audit_site_health` without `type` reports its content-type
+    sections as unavailable and still runs the site-wide ones.
+- **Local operator files stay untracked.** `config/config.*.json` is ignored
+  except `config/config.example.json`. One-off `scripts/*-staging.mjs`
+  loaders are ignored too.
+
+## [2.26.0] - 2026-10-01
+
+### Changed
+- **Nightly leftover cleanup (#399).** CI pins Node 20 (no 1-cell matrix) and
+  runs `npm run syntax-check` recursively over `src/`. The two
+  `resources/read` URIs (`content-types`, `security-policy`) go through
+  `invokeReadTool` → `callTool`. AGENTS, CONTRIBUTING, threat-model, and
+  ops docs point middleware at `src/lib/dispatch.js`.
+
+### Removed
+- **Production-dead `redactResource`.** Canonical `redactCanonicalEntity` is
+  the only redaction path; JSON:API-shape tests folded into it.
+- **Leftover public exports** from `workflow-prompts.js`, `server-tools.js`,
+  and `allModules` (module-private after #395).
+
+### Added
+- **Terminal install wizard (`wizard` / `init`).**
+  `npx drupal-mcp-connector init` (also `wizard`, `npm run init`,
+  `drupal-mcp-wizard`) collects transport (stdio vs remote HTTPS), auth
+  (OAuth vs sealed token), and agent client id, then prints Cursor
+  `.cursor/mcp.json` and Claude Code `mcpServers` snippets. Files are
+  written only with `--write` and never clobbered without confirm unless
+  `--yes`. Post-config `whoami` + `contract_ready` print pass/fail with a
+  next fix, or a clear skip when the host is unreachable. Remote HTTPS is
+  Tailscale / local-VPN only — not a public SaaS path.
+- **`doctor` CLI.** `npx drupal-mcp-connector doctor` runs ordered
+  gates (reachability → auth/401 → agent client → allowlist →
+  `contract_ready` → version skew), prints one primary failure plus the
+  exact next fix, exits non-zero on fail, and supports `--json` with no
+  secrets.
+- **Transport presets.** Wizard `--preset local-stdio|tailscale|public-https`
+  and docs table. Public HTTPS is listed as a preset and is not a hosted service.
+- **Version skew.** Doctor and wizard print “you are on X;
+  site needs Y” when readiness reports versions. No auto-upgrade.
+- **Happy-path recipe.** README walkthrough using
+  `drupal_mcp_whoami` → `drupal_list_sites` → unpublished
+  `drupal_list_nodes` / `dryRun` `drupal_create_node`.
+
+### Fixed
+- **A `changed` / `revision_timestamp` gap on the default revision no longer blocks the next draft (#405).**
+  `#273` treated `possiblyPatchBlocked` as local proof of a hidden revision and
+  refused before Sentinel ran. When inventory `working` is null and both
+  JSON:API aliases report the same published vid, a `moderationState: draft`
+  write now proceeds to the core probe / Sentinel. An actual Sentinel
+  stale-copy refusal is still rewritten. `drupal_list_revisions` still reports
+  the warning.
+- **`drupal_report_scheduled_content` no longer reports Scheduler fields missing when every date is empty (#403).**
+  Field presence is the key on the JSON:API attributes, not a non-empty value.
+  Keys present and all null: `summary: { pending: 0, overdue: 0 }`. `gated`
+  only when the keys are actually absent.
+- **`drupal_schedule_publish` writes `publish_state` / `unpublish_state` on moderated bundles (#402).**
+  Optional `publishState` / `unpublishState` are accepted. When the bundle is
+  moderated and those fields exist, the matching state is required whenever a
+  date is set. Dates alone were accepted by Drupal and then failed at cron.
+- **Revise guard uses `moderation_state`, not `status: false`, to decide "already a draft" (#400).**
+  After revising a translation over a working copy, Sentinel copies the live
+  published moderation record onto the carried default language (`status: false`
+  + `moderation_state: published`). Neither `drupal_update_node` nor
+  `drupal_create_translation` revise can open a draft of that language while
+  the other translation draft exists (drupal.org #3626919). Both tools now
+  say so and name the manual path: publish or discard the translation draft,
+  or edit in the UI.
+- **Config reads accept the read-only `mcp_config_read` scope (#397).**
+  `drupal_config_get` / `drupal_config_list`, config reports, and codegen
+  inspect/diff accept `mcp_config` or `mcp_config_read`. Writes still require
+  `mcp_config`. `drupal_mcp_whoami` reports `configRead: true` for a
+  read-scope token. A token with neither scope is still refused.
+
 ## [2.25.0] - 2026-10-01
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # Drupal MCP Connector
 
-> Drupal MCP Connector — multi-site MCP server for Drupal with JSON:API and GraphQL, governed writes, draft translations, content tools, audit reports, and an SSH Drush bridge.
+> Multi-site MCP server for Drupal over JSON:API and GraphQL, with governed writes and an SSH Drush bridge. `init` writes a stdio or Tailscale client config from a transport preset. `doctor` checks reachability, auth, and readiness, and reports version skew. A timestamp gap on a published revision no longer blocks the next draft.
 
 [![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)
@@ -205,6 +205,62 @@ Full detail: **[docs/security.md](docs/security.md)** and **[docs/security-harde
 
 ## Quick Start
 
+### One-liner (recommended for operators)
+
+```bash
+npx -y drupal-mcp-connector init
+# aliases: npx -y drupal-mcp-connector wizard
+#          npx -y drupal-mcp-wizard
+# CI / dogfood: npx -y drupal-mcp-connector init --yes --json
+npx -y drupal-mcp-connector doctor
+# CI: npx -y drupal-mcp-connector doctor --json
+```
+
+The wizard prints Cursor (`.cursor/mcp.json`) and Claude Code `mcpServers`
+snippets, optional `auth.grants` allowlist hints, and a whoami / contract_ready
+check. It writes files only with `--write` (never clobbers without confirm
+unless `--yes`). Doctor prints **one** primary failing gate and the exact next
+fix (exit non-zero on fail; `--json` is secret-free).
+
+### Transport presets
+
+| Preset | URL shape | Notes |
+|--------|-----------|--------|
+| **Local stdio** (`--preset local-stdio`) | `https://drupal.ddev.site` | Client launches this connector as a subprocess. Drupal must be reachable from this machine. |
+| **Tailscale VPN** (`--preset tailscale`) | `https://drupal.<tailnet>.ts.net` | VPN-required. The MCP client host must be on the same tailnet. Not a public internet path. |
+| **Public HTTPS** (`--preset public-https`) | `https://mcp.example.com/mcp` | **Gated / later.** Operator-run `MCP_TRANSPORT=https` + TLS + inbound OAuth. There is **no** hosted Wilkes & Liberty SaaS MCP URL. |
+
+**Remote HTTPS is Tailscale / local-VPN only.** This package does not ship a
+public SaaS remote endpoint. stdio is the default: the client launches the
+connector on your machine and inherits VPN/Tailscale/localhost reachability to
+Drupal. See **[docs/mcp-clients.md](docs/mcp-clients.md)**.
+
+`requireGovernance: true` remains the listing default for a later marketplace
+entry — this repo does not submit listings. If the client only shows
+`drupal_list_sites` and `drupal_governance_status`, run `doctor`.
+
+### Two-minute happy path
+
+After `init` and a green `doctor`, in the MCP client (real tool names):
+
+1. **Who am I?** Call `drupal_mcp_whoami`. Confirm `tier`, `preset`, and
+   `capabilities.publish` (false on `production-strict` / `content-editor`).
+2. **What can I see?** Call `drupal_list_sites`, then `drupal_list_nodes` with
+   `{ "type": "article", "status": false, "limit": 5 }` (unpublished only) or
+   `drupal_get_node` on a staging UUID. Prefer `drupal_search_content` for a
+   title substring.
+3. **Safe unpublished write (optional, non-prod):** Preview with
+   `drupal_create_node`
+   `{ "type": "article", "title": "MCP draft", "status": false, "dryRun": true }`.
+   Commit without `dryRun` only on staging, still `status: false` (or
+   `moderationState: "draft"`). Never set `status: true` or
+   `moderationState: "published"` unless `drupal_mcp_whoami` shows
+   `capabilities.publish: true` **and** you intend to go live.
+
+Fail-closed: default `production-strict` is read-only. A deny is expected when
+the allowlist or Sentinel profile excludes the type — run `doctor` and
+`drupal_governance_status`; do not auto-widen allowlists.
+
 ### From npm (recommended for operators)
 
 ```bash

package/bin/drupal-mcp-doctor.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Connection doctor (DEV-759).
+ *
+ * npx drupal-mcp-connector doctor
+ * node bin/drupal-mcp-doctor.js --json
+ */
+
+import { runDoctorCli } from "../src/lib/doctor.js";
+
+runDoctorCli(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`doctor: ${err?.message ?? err}\n`);
+    process.exit(2);
+  });

package/bin/drupal-mcp-wizard.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Operator install wizard (DEV-758).
+ *
+ *   npx drupal-mcp-connector init
+ *   npx drupal-mcp-connector wizard
+ *   node bin/drupal-mcp-wizard.js --yes
+ */
+
+import { runWizardCli } from "../src/lib/wizard.js";
+
+runWizardCli(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`wizard: ${err?.message ?? err}\n`);
+    process.exit(2);
+  });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.25.0",
-  "description": "Drupal MCP Connector — multi-site MCP server for Drupal with JSON:API and GraphQL, governed writes, draft translations, content tools, audit reports, and an SSH Drush bridge.",
+  "version": "3.0.0",
+  "description": "Multi-site MCP server for Drupal over JSON:API and GraphQL, with governed writes and an SSH Drush bridge. init writes a stdio or Tailscale client config from a transport preset. doctor checks reachability, auth, and readiness, and reports version skew. A timestamp gap on a published revision no longer blocks the next draft.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -9,7 +9,9 @@
     "drupal-mcp-verify": "bin/drupal-mcp-verify.js",
     "drupal-mcp-edge": "bin/drupal-mcp-edge.js",
     "drupal-mcp-agent": "bin/drupal-mcp-agent.js",
-    "drupal-mcp-anchor": "bin/drupal-mcp-anchor.js"
+    "drupal-mcp-anchor": "bin/drupal-mcp-anchor.js",
+    "drupal-mcp-wizard": "bin/drupal-mcp-wizard.js",
+    "drupal-mcp-doctor": "bin/drupal-mcp-doctor.js"
   },
   "files": [
     "src/",
@@ -61,9 +63,12 @@
     "test:watch": "vitest",
     "audit": "npm audit --audit-level=high",
     "check": "npm run lint && npm run audit",
-    "syntax-check": "for f in src/lib/*.js src/tools/*.js src/index.js; do node --input-type=module --check < $f && echo \"$f ✓\"; done",
+    "syntax-check": "find src -name '*.js' -exec sh -c 'node --input-type=module --check < \"$1\" && echo \"$1 ✓\"' _ {} \\;",
     "verify": "node bin/drupal-mcp-verify.js",
-    "verify:example": "node bin/drupal-mcp-verify.js --config config/config.example.json"
+    "verify:example": "node bin/drupal-mcp-verify.js --config config/config.example.json",
+    "wizard": "node bin/drupal-mcp-wizard.js",
+    "init": "node bin/drupal-mcp-wizard.js",
+    "doctor": "node bin/drupal-mcp-doctor.js"
   },
   "dependencies": {
     "@modelcontextprotocol/node": "^2.0.0",

package/src/index.js

@@ -23,6 +23,10 @@
  *   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
+ *
+ * CLI subcommands (anything else starts the MCP server):
+ *   wizard | init     Operator install wizard — see src/lib/wizard.js
+ *   doctor            Connection doctor — see src/lib/doctor.js
  */
 
 import { createServer as createHttpsServer } from "https";
@@ -45,10 +49,9 @@ import {
 import { createLegacySessionHandler, createMcpRequestHandler } from "./lib/http-handler.js";
 import { createConnectorServerFactory } from "./lib/mcp-server.js";
 import { createRateLimiter } from "./lib/rate-limit.js";
-import { callTool, listResolvableSiteConfigs } from "./lib/dispatch.js";
+import { callTool, invokeReadTool, listResolvableSiteConfigs } from "./lib/dispatch.js";
 import { filterDiscoverableTools } from "./lib/governance.js";
 import {
-  assertPrincipalEntitlement,
   filterPromptsByPrincipal,
   filterResourcesByPrincipal,
   filterToolsByPrincipal,
@@ -57,7 +60,7 @@ import {
 } from "./lib/principal.js";
 
 // Tools — aggregated (single source of truth, side-effect-free) and per-tool prompts
-import { allDefinitions, allHandlers, definitionsByName } from "./tools/index.js";
+import { allDefinitions, definitionsByName } from "./tools/index.js";
 import { createModuleToolRegistry, isModuleTool } from "./lib/module-tools.js";
 import { buildToolPrompts, createPromptSurface } from "./lib/tool-prompts.js";
 import {
@@ -69,6 +72,16 @@ import {
   replaceModuleWorkflows,
 } from "./lib/workflow-prompts.js";
 import { builtinWorkflowProvider } from "./lib/workflows/builtin.js";
+import { runWizardCli } from "./lib/wizard.js";
+import { runDoctorCli } from "./lib/doctor.js";
+
+const cliCommand = process.argv[2];
+if (cliCommand === "wizard" || cliCommand === "init") {
+  process.exit(await runWizardCli(process.argv.slice(3)));
+}
+if (cliCommand === "doctor") {
+  process.exit(await runDoctorCli(process.argv.slice(3)));
+}
 
 // Apply config/secrets.map (or the shipped example table) before any site
 // resolution. MCP clients spawn this file directly; the shell launcher is
@@ -129,8 +142,7 @@ async function discoverableTools() {
 /**
  * Resolve a resource URI to its JSON payload. URIs are matched in order; the
  * templated forms (content-types, security-policy) capture the site name and
- * delegate to the corresponding read-only tool handler so resources and tools
- * always return the same shape.
+ * go through {@link invokeReadTool} so resources and tools share middleware.
  *
  * @param {string} uri - A drupal:// resource URI.
  * @returns {Promise<object>} The resource data (later JSON-serialized).
@@ -148,25 +160,13 @@ async function readResource(uri) {
   // drupal://{site}/content-types
   const ctMatch = uri.match(/^drupal:\/\/([^/]+)\/content-types$/);
   if (ctMatch) {
-    assertPrincipalEntitlement({
-      toolName: "drupal_list_content_types",
-      args: { site: ctMatch[1] },
-      identity,
-      sites,
-    });
-    return allHandlers.drupal_list_content_types({ site: ctMatch[1] });
+    return invokeReadTool("drupal_list_content_types", { site: ctMatch[1] });
   }
 
   // drupal://{site}/security-policy
   const spMatch = uri.match(/^drupal:\/\/([^/]+)\/security-policy$/);
   if (spMatch) {
-    assertPrincipalEntitlement({
-      toolName: "drupal_security_info",
-      args: { site: spMatch[1] },
-      identity,
-      sites,
-    });
-    return allHandlers.drupal_security_info({ site: spMatch[1] });
+    return invokeReadTool("drupal_security_info", { site: spMatch[1] });
   }
 
   throw new Error(`Unknown resource URI: ${uri}`);

package/src/lib/backends/jsonapi.js

@@ -20,6 +20,9 @@ import {
 } from "../canonical.js";
 import { isPositiveNid, normalizeAlias, PATH_ALIAS_ENTITY_TYPE } from "../path-alias.js";
 
+/** Most node_type pages read by listContentTypes (50 per page). */
+const CONTENT_TYPE_MAX_PAGES = 20;
+
 // Drupal exposes internal identifiers under drupal_internal__* attributes.
 // They are dropped from canonical `fields` except for the identifiers that
 // governed read/write workflows explicitly need.
@@ -666,13 +669,22 @@ export class JsonApiBackend extends Backend {
    * @returns {Promise<Array<{id: string, label: string, description: ?string}>>}
    */
   async listContentTypes() {
-    // page[limit]=50 is an intentional cap; matches Drupal JSON:API's default page size.
-    const data = await drupalFetch(this.site, "/jsonapi/node_type/node_type?page[limit]=50");
-    return (data.data || []).map((ct) => ({
-      id: ct.attributes.drupal_internal__type,
-      label: ct.attributes.name,
-      description: ct.attributes.description ?? null,
-    }));
+    // JSON:API caps a page at 50. Follow `links.next` so callers that scan
+    // every bundle see them all (#403); stop after a fixed number of pages.
+    const out = [];
+    for (let page = 0, offset = 0; page < CONTENT_TYPE_MAX_PAGES; page += 1, offset += 50) {
+      const data = await drupalFetch(this.site, `/jsonapi/node_type/node_type?page[limit]=50&page[offset]=${offset}`);
+      const rows = data.data || [];
+      for (const ct of rows) {
+        out.push({
+          id: ct.attributes.drupal_internal__type,
+          label: ct.attributes.name,
+          description: ct.attributes.description ?? null,
+        });
+      }
+      if (!data.links?.next || rows.length === 0) break;
+    }
+    return out;
   }
 
   /**

package/src/lib/dispatch.js

@@ -236,3 +236,25 @@ export async function callTool(name, args, context = {}) {
     return toolError(err);
   }
 }
+
+/**
+ * Run a read tool through {@link callTool} and unwrap the MCP envelope.
+ * `resources/read` uses this so those URIs cannot skip middleware.
+ *
+ * @param {string} name Tool name.
+ * @param {object} args Tool arguments.
+ * @param {object} [context] Optional inbound identity / grant overrides.
+ * @returns {Promise<*>} The tool payload.
+ * @throws {Error} When the tool is missing, denied, or returns isError.
+ */
+export async function invokeReadTool(name, args, context = {}) {
+  const result = await callTool(name, args, context);
+  if (result?.isError) {
+    throw new Error(result.content?.[0]?.text ?? `Tool "${name}" failed`);
+  }
+  const text = result?.content?.[0]?.text;
+  if (typeof text !== "string") {
+    throw new Error(`Tool "${name}" returned no payload`);
+  }
+  return JSON.parse(text);
+}