drupal-mcp-connector 2.24.2 → 2.26.0

package/.agents/commands/drupal-entity-update.md

@@ -19,7 +19,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `langcode` (string): Target language for an unpublished working translation (nodes). Continues that translation via Sentinel.
 - `attributes` (object (pass as JSON))
 - `relationships` (object (pass as JSON))
-- `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun.
+- `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; field access and entity validation are NOT checked (`core_patch_guard`), so the real write can still fail with a field-access 403 or a 422. Unmoderated targets get no server-side check at all (`none`). A changed/revision_timestamp gap on the default revision (possiblyPatchBlocked) is a warning on list_revisions, not a local dryRun refusal — the write proceeds to the core probe / Sentinel (#405). An actual Sentinel stale-copy refusal is still rewritten. Any refusal fails the dryRun.
 - `returning` (one of: full, minimal): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 If a required parameter is missing, 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/.agents/commands/drupal-list-menu-links.md

@@ -1,11 +1,11 @@
 ---
-description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, and weight. Note: this lists editable menu_link_content entities, not code-defined static links."
+description: "List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, weight, and fields.drupal_internal__id (numeric id for /admin/structure/menu/item/{id}/edit). Note: this lists editable menu_link_content entities, not code-defined static links."
 argument-hint: "[site] [menu] [limit] [offset] [sort]"
 ---
 
 Call the MCP tool `drupal_list_menu_links`.
 
-List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, and weight. Note: this lists editable menu_link_content entities, not code-defined static links.
+List custom (content) menu links, optionally scoped to a single menu (e.g. 'main', 'footer'). Returns each link's title, target URI, menu, weight, and fields.drupal_internal__id (numeric id for /admin/structure/menu/item/{id}/edit). Note: this lists editable menu_link_content entities, not code-defined static links.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/.agents/commands/drupal-schedule-publish.md

@@ -1,11 +1,11 @@
 ---
-description: "Schedule a content node to publish and/or unpublish at a future time using the Drupal Scheduler module. Sets the publish_on and unpublish_on fields on the node. Requires the Scheduler module to be installed and enabled for the content type, with the publish_on / unpublish_on fields present on the bundle — otherwise the call fails with a clear capability error. Timestamps accept ISO 8601 (e.g. '2026-07-01T12:00:00Z') or a Unix epoch and are passed through unchanged. Provide at least one of publishOn or unpublishOn."
-argument-hint: "<type> <id> [site] [publishOn] [unpublishOn]"
+description: "Schedule a content node to publish and/or unpublish at a future time using the Drupal Scheduler module. Sets the publish_on and unpublish_on fields on the node. On a bundle under Content Moderation, also set publishState / unpublishState (written as publish_state / unpublish_state) — dates alone never go live. Requires the Scheduler module to be installed and enabled for the content type, with the publish_on / unpublish_on fields present on the bundle — otherwise the call fails with a clear capability error. Moderated bundles additionally need Scheduler Content Moderation Integration; when those state fields exist, the matching state is required whenever a date is set. Timestamps accept ISO 8601 (e.g. '2026-07-01T12:00:00Z') or a Unix epoch and are passed through unchanged. Provide at least one of publishOn or unpublishOn."
+argument-hint: "<type> <id> [site] [publishOn] [unpublishOn] [publishState] [unpublishState]"
 ---
 
 Call the MCP tool `drupal_schedule_publish`.
 
-Schedule a content node to publish and/or unpublish at a future time using the Drupal Scheduler module. Sets the publish_on and unpublish_on fields on the node. Requires the Scheduler module to be installed and enabled for the content type, with the publish_on / unpublish_on fields present on the bundle — otherwise the call fails with a clear capability error. Timestamps accept ISO 8601 (e.g. '2026-07-01T12:00:00Z') or a Unix epoch and are passed through unchanged. Provide at least one of publishOn or unpublishOn.
+Schedule a content node to publish and/or unpublish at a future time using the Drupal Scheduler module. Sets the publish_on and unpublish_on fields on the node. On a bundle under Content Moderation, also set publishState / unpublishState (written as publish_state / unpublish_state) — dates alone never go live. Requires the Scheduler module to be installed and enabled for the content type, with the publish_on / unpublish_on fields present on the bundle — otherwise the call fails with a clear capability error. Moderated bundles additionally need Scheduler Content Moderation Integration; when those state fields exist, the matching state is required whenever a date is set. Timestamps accept ISO 8601 (e.g. '2026-07-01T12:00:00Z') or a Unix epoch and are passed through unchanged. Provide at least one of publishOn or unpublishOn.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -17,5 +17,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `publishOn` (string): When to publish — ISO 8601 datetime or Unix epoch. Sets the Scheduler publish_on field.
 - `unpublishOn` (string): When to unpublish — ISO 8601 datetime or Unix epoch. Sets the Scheduler unpublish_on field.
+- `publishState` (string): Moderation state to enter at publishOn (e.g. 'published'). Required on moderated bundles when publishOn is set.
+- `unpublishState` (string): Moderation state to enter at unpublishOn (e.g. 'draft'). Required on moderated bundles when unpublishOn is set.
 
 If a required parameter is missing, 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/.agents/commands/drupal-update-menu-link.md

@@ -1,11 +1,11 @@
 ---
-description: "Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Checked against the site security config."
+description: "Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Pass langcode to update an existing translation via JSON:API language negotiation (URL prefix, then language headers). Does not create a missing translation. Responses include fields.drupal_internal__id. Checked against the site security config."
 argument-hint: "<id> [site] [title] [link] [menu] [weight] [parent] [enabled] [langcode]"
 ---
 
 Call the MCP tool `drupal_update_menu_link`.
 
-Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Checked against the site security config.
+Update a custom menu link by UUID (rename, re-weight, re-target, re-parent, enable/disable). Only the fields you pass change. The link's enabled state is preserved across edits — an unrelated change will not disable a live link — unless you pass 'enabled' explicitly. Pass langcode to update an existing translation via JSON:API language negotiation (URL prefix, then language headers). Does not create a missing translation. Responses include fields.drupal_internal__id. Checked against the site security config.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -20,6 +20,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `weight` (number): New ordering weight. Omit to leave unchanged.
 - `parent` (string): New parent link plugin id (e.g. 'menu_link_content:<uuid>'), or '' for top level. Omit to leave unchanged.
 - `enabled` (boolean (true/false)): Enable/disable the link. Omit to preserve the current state.
-- `langcode` (string): Existing translation to update (e.g. 'es'). Omit for the default language. Does not create a missing translation.
+- `langcode` (string): Existing translation to update (e.g. 'es'). Uses /{langcode}/jsonapi/… when the site prefixes JSON:API, then language headers. Omit for the default language. Does not create a missing translation.
 
 If a required parameter is missing, 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/.agents/commands/drupal-update-node.md

@@ -24,7 +24,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `langcode` (string): Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode.
 - `fields` (object (pass as JSON)): Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here.
 - `relationships` (object (pass as JSON)): Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot. Image alt on a translation uses the existing file UUID plus meta.alt; replacing the file is refused.
-- `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; Drupal does not check field access or entity validation on that probe (`core_patch_guard`). Text format is resolved before the preview returns, including on that path: a known allowed_formats list is enforced, and an unknown list reuses the format stored on the field. Other fields can still fail the real write with a field-access 403 or a validation 422. Unmoderated targets get no server-side check at all (`none`). A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun.
+- `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, run the server-side preflight when one applies, and return a preview without the real write. The result's `checks` block says what was checked; `caveat` names what was not. Only an existing node draft (or a langcode translation draft) is checked with the real payload: Sentinel's non-saving draft endpoint applies the submitted fields through field access and validates the entity (`serverPreflight: sentinel_draft`). On other moderated targets an id-mismatch core PATCH with no fields checks entity update access and core's working-copy guard only; Drupal does not check field access or entity validation on that probe (`core_patch_guard`). Text format is resolved before the preview returns, including on that path: a known allowed_formats list is enforced, and an unknown list reuses the format stored on the field. Other fields can still fail the real write with a field-access 403 or a validation 422. Unmoderated targets get no server-side check at all (`none`). A changed/revision_timestamp gap on the default revision (possiblyPatchBlocked) is a warning on list_revisions, not a local dryRun refusal — the write proceeds to the core probe / Sentinel (#405). An actual Sentinel stale-copy refusal is still rewritten. Any refusal fails the dryRun.
 - `returning` (one of: full, minimal): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 If a required parameter is missing, 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,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **Menu tools return `fields.drupal_internal__id`.** The numeric menu-link
+  id is kept on JSON:API canonicalization so list/create/update responses
+  can build `/admin/structure/menu/item/{id}/edit` (and `…/edit/{langcode}`).
+
+### Fixed
+- **`drupal_update_menu_link` with `langcode` targets the translation via a JSON:API URL prefix (#398).**
+  Stock Drupal negotiates content language from `/{langcode}/jsonapi/…` (the
+  same path that returns Spanish for nodes). The connector only sent
+  `Accept-Language` / `Content-Language` headers, which most production sites
+  ignore unless Browser detection is enabled — so a Spanish menu-link
+  translation was served as English and the write refused. Reads and writes
+  with `langcode` now try the prefixed path first and fall back to the
+  unprefixed path plus headers when the prefix 404s. Taxonomy get/update
+  with `langcode` use the same backend path. A mismatch after both attempts
+  still fails loud.
+
 ## [2.24.2] - 2026-09-30
 
 ### Removed

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.24.2",
-  "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": "2.26.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

@@ -11,6 +11,7 @@ import { drupalFetch, drupalUploadFile } from "../drupal-fetch.js";
 import { getRequestIdentity } from "../principal.js";
 import { validateUuid, validateMachineName } from "../validate.js";
 import { parseFieldConfigObject } from "../field-definition.js";
+import { httpStatusOf } from "../error-status.js";
 import { Backend } from "./backend-interface.js";
 import {
   makeCanonicalEntity,
@@ -33,8 +34,9 @@ const COUNT_PAGE_SIZE = 50;
 const COUNT_MAX_RECORDS = 1000;
 
 /**
- * JSON:API language headers. Drupal negotiates Content-Language / Accept-Language
- * when URL prefixes are not used on /jsonapi.
+ * JSON:API language headers. Stock Drupal ignores these unless Browser
+ * (Accept-Language) detection is enabled for content language. Production
+ * sites usually negotiate via URL prefixes instead — see jsonApiLanguagePath.
  * @param {?string} langcode
  * @returns {object}
  */
@@ -43,6 +45,59 @@ function languageFetchOptions(langcode) {
   return { headers: { "Content-Language": langcode, "Accept-Language": langcode } };
 }
 
+/**
+ * Prefix a JSON:API path with the language code stock Drupal URL negotiation
+ * expects (`/es/jsonapi/...`). Does not add `?langCode=` — core JSON:API
+ * rejects unknown query parameters unless jsonapi_multilingual is installed.
+ * @param {string} path JSON:API path, optionally with a query string.
+ * @param {?string} langcode
+ * @returns {string}
+ */
+export function jsonApiLanguagePath(path, langcode) {
+  if (!langcode) return path;
+  const prefix = `/${encodeURIComponent(langcode)}`;
+  if (path === prefix || path.startsWith(`${prefix}/`)) return path;
+  return `${prefix}${path}`;
+}
+
+/**
+ * Merge language headers onto a drupalFetch options object.
+ * @param {object} [options]
+ * @param {?string} langcode
+ * @returns {object}
+ */
+function languageRequestOptions(options, langcode) {
+  const lang = languageFetchOptions(langcode);
+  if (!lang.headers) return { ...options };
+  return {
+    ...options,
+    headers: { ...(options?.headers || {}), ...lang.headers },
+  };
+}
+
+/**
+ * Fetch a JSON:API resource in a requested language.
+ *
+ * Prefer the URL prefix (how `/es/jsonapi/node/...` works on multilingual
+ * Drupal). If that 404s — the site has no language prefixes — retry the
+ * unprefixed path with language headers only (#398 / #303).
+ * @param {object} site Resolved site config.
+ * @param {string} path Unprefixed JSON:API path.
+ * @param {object} [options] node-fetch options (method, body, extra headers).
+ * @param {?string} langcode
+ * @returns {Promise<object|null>}
+ */
+async function fetchJsonApiWithLanguage(site, path, options = {}, langcode) {
+  const opts = languageRequestOptions(options, langcode);
+  if (!langcode) return drupalFetch(site, path, opts);
+  try {
+    return await drupalFetch(site, jsonApiLanguagePath(path, langcode), opts);
+  } catch (err) {
+    if (httpStatusOf(err) !== 404) throw err;
+    return drupalFetch(site, path, opts);
+  }
+}
+
 /**
  * Fail if JSON:API served a different language than requested.
  * @param {?object} entity
@@ -59,7 +114,8 @@ function assertServedLanguage(entity, langcode) {
   if (entity.langcode !== langcode) {
     throw new Error(
       `JSON:API served language "${entity.langcode}" for requested langcode "${langcode}". ` +
-      "The translation may not exist, or this site does not negotiate JSON:API by language.",
+      "The translation may not exist, or this site does not negotiate JSON:API by language " +
+      `(URL prefix /${langcode}/jsonapi/… or Accept-Language).`,
     );
   }
 }
@@ -291,10 +347,12 @@ export class JsonApiBackend extends Backend {
           // while the UUID remains the canonical top-level id (#237).
           // Paragraph ERR attach needs the current revision id (#192).
           // Node / revisionable writes need the working vs live vid (#166).
+          // Menu-link admin edit URLs need the numeric id (#398).
           // Other drupal_internal__* attributes stay stripped.
           return (entityType === "node" && k === "drupal_internal__nid")
             || k === "drupal_internal__vid"
-            || (entityType === "paragraph" && k === "drupal_internal__revision_id");
+            || (entityType === "paragraph" && k === "drupal_internal__revision_id")
+            || (entityType === "menu_link_content" && k === "drupal_internal__id");
         }
         return true;
       })
@@ -397,7 +455,7 @@ export class JsonApiBackend extends Backend {
     if (resourceVersion) {
       path += `?resourceVersion=${encodeURIComponent(resourceVersion)}`;
     }
-    const data = await drupalFetch(this.site, path, languageFetchOptions(langcode));
+    const data = await fetchJsonApiWithLanguage(this.site, path, {}, langcode);
     const entity = data?.data ? this.toCanonical(data.data) : null;
     assertServedLanguage(entity, langcode);
     return entity;
@@ -514,14 +572,19 @@ export class JsonApiBackend extends Backend {
    * @returns {Promise<object>} The JSON:API response body.
    */
   async writeWithModerationFallback(path, method, buildPayload, attributes, langcode) {
-    const lang = languageFetchOptions(langcode);
+    const send = (attrs) => fetchJsonApiWithLanguage(
+      this.site,
+      path,
+      { method, body: JSON.stringify(buildPayload(attrs)) },
+      langcode,
+    );
     try {
-      return await drupalFetch(this.site, path, { method, body: JSON.stringify(buildPayload(attributes)), ...lang });
+      return await send(attributes);
     } catch (err) {
       if (!isModeratedStatusError(err) || !("status" in attributes)) throw err;
       const withoutStatus = { ...attributes };
       delete withoutStatus.status;
-      return drupalFetch(this.site, path, { method, body: JSON.stringify(buildPayload(withoutStatus)), ...lang });
+      return send(withoutStatus);
     }
   }
 

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);
+}