drupal-mcp-connector 2.7.4 → 2.8.0

package/config/config.example.json

@@ -7,7 +7,7 @@
   },
 
   "_security_options": {
-    "_comment": "apiTokenEnv / oauth.clientSecretEnv: read credentials from the environment, never from this file. requireSecureAuth: reject anon/basic, require HTTPS+Bearer — set it on every remote site. requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel) verifies — no ungoverned JSON:API/GraphQL fallback. Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_BIND_HOST restricts the listen interface (with TLS). Network-facing HTTPS /mcp requires the top-level auth block (issuer + audience), not MCP_AUTH_TOKEN. MCP_AUTH_TOKEN remains valid only on loopback. See docs/security-hardening.md."
+    "_comment": "apiTokenEnv / oauth.clientSecretEnv: read credentials from the environment, never from this file. requireSecureAuth: reject anon/basic, require HTTPS+Bearer — set it on every remote site. requireGovernance: deny every governed path unless the source governance contract (GET /drupal-mcp/readiness, mcp_sentinel) verifies — no ungoverned JSON:API/GraphQL fallback. Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_BIND_HOST restricts the listen interface (with TLS). Network-facing HTTPS /mcp requires the top-level auth block (issuer + audience), not MCP_AUTH_TOKEN. MCP_AUTH_TOKEN remains valid only on loopback. Optional security.declaredCeiling (narrow-only X-MCP-Declared-Ceiling) and security.readBudgets (same finite classes as mcp_sentinel) bind northbound data-flow to the inbound principal and target. See docs/security.md and docs/security-hardening.md."
   },
 
   "_governance_tiers": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.7.4",
+  "version": "2.8.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",
@@ -11,7 +11,8 @@
   "files": [
     "src/",
     "scripts/generate-commands.js",
-    ".claude/commands/",
+    "scripts/install-commands.js",
+    ".agents/commands/",
     "config/config.example.json",
     "README.md",
     "CHANGELOG.md",
@@ -50,6 +51,7 @@
     "start:https": "MCP_TRANSPORT=https node src/index.js",
     "start:dev": "MCP_TRANSPORT=https MCP_ALLOW_HTTP=1 MCP_PORT=3443 node src/index.js",
     "generate:commands": "node scripts/generate-commands.js",
+    "install:commands": "node scripts/install-commands.js",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "test": "vitest run",

package/scripts/generate-commands.js

@@ -1,22 +1,21 @@
 #!/usr/bin/env node
 /**
- * generate-commands.js — generate Claude Code slash commands for every tool.
+ * generate-commands.js — generate harness-agnostic slash-command stubs for every tool.
  *
- * Writes one `.claude/commands/drupal-<tool>.md` per Drupal tool, giving the
- * literal `/drupal-<tool>` slash command in Claude Code (e.g.
- * `/drupal-create-node`). Each file is scoped via `allowed-tools` to only its own
- * `mcp__drupal__<tool>` and instructs the model to parse `$ARGUMENTS` into the
- * tool's parameters before making a single call.
+ * Writes one `.agents/commands/drupal-<tool>.md` per Drupal tool. The files use
+ * protocol tool names (`drupal_list_nodes`) so any MCP client can consume them;
+ * they are not a vendor rule tree. Clients that scan `.agents/commands/` (Grok
+ * Build, when this repo is the project) pick them up as `/drupal-<tool>`.
  *
- * These files are *client ergonomics* for operators using Claude Code as an MCP
- * client against this server — not provider-specific project rules. Development
- * instructions for any agent live only in AGENTS.md.
+ * Clients that only scan a vendor home directory (Claude Code `~/.claude/commands`,
+ * Grok `~/.grok/commands`) get the same files via `npm run install:commands`.
  *
  * Driven from the same tool definitions as the server (src/tools/index.js), so the
  * command set never drifts from the tools. Run: `npm run generate:commands`.
  *
- * Exports `renderCommandMarkdown`, `commandFileName`, and `generate` for tests; the
- * file-writing side effect runs only when executed directly.
+ * Exports `renderCommandMarkdown`, `renderClaudeCommandMarkdown`, `commandFileName`,
+ * `COMMANDS_DIR`, and `generate` for tests; the file-writing side effect runs only
+ * when executed directly.
  */
 
 import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
@@ -26,7 +25,8 @@ import { allDefinitions } from "../src/tools/index.js";
 import { paramList, toolNameToPromptName } from "../src/lib/tool-prompts.js";
 import { isDestructiveTool } from "../src/lib/operations.js";
 
-const COMMANDS_DIR = new URL("../.claude/commands/", import.meta.url);
+/** Canonical, harness-agnostic command tree shipped in the repo and the npm package. */
+export const COMMANDS_DIR = new URL("../.agents/commands/", import.meta.url);
 
 /** Map a tool definition to its command filename: `drupal_create_node` → `drupal-create-node.md`. */
 export function commandFileName(def) {
@@ -49,19 +49,26 @@ function argumentHint(params) {
  * Render the markdown for one tool's slash command.
  *
  * @param {object} def - The tool definition ({name, description, inputSchema}).
+ * @param {object} [options]
+ * @param {string} [options.allowedTools] - Optional Claude Code `allowed-tools` value.
+ * @param {string} [options.argumentsPhrase="the arguments supplied with this command"]
+ *   Phrase used in the parse-arguments instruction. Claude Code install rewrites
+ *   this to `` `$ARGUMENTS` `` because that client substitutes the placeholder.
  * @returns {string} File contents (ends with a trailing newline).
  */
-export function renderCommandMarkdown(def) {
+export function renderCommandMarkdown(def, options = {}) {
   const params   = paramList(def.inputSchema);
   const required = params.filter((p) => p.required);
   const optional = params.filter((p) => !p.required);
   const line = (p) => `- \`${p.name}\` (${p.hint})${p.description ? `: ${p.description}` : ""}`;
+  const argumentsPhrase = options.argumentsPhrase ?? "the arguments supplied with this command";
 
   const frontmatter = ["---", `description: ${yamlString(def.description)}`];
   if (params.length) frontmatter.push(`argument-hint: ${yamlString(argumentHint(params))}`);
-  frontmatter.push(`allowed-tools: mcp__drupal__${def.name}`, "---");
+  if (options.allowedTools) frontmatter.push(`allowed-tools: ${options.allowedTools}`);
+  frontmatter.push("---");
 
-  const body = [`Call the \`mcp__drupal__${def.name}\` MCP tool.`, "", def.description];
+  const body = [`Call the MCP tool \`${def.name}\`.`, "", def.description];
 
   if (isDestructiveTool(def.name)) {
     body.push("", "> ⚠ **Destructive** — this permanently changes or deletes data. Confirm with the user before calling.");
@@ -69,9 +76,9 @@ export function renderCommandMarkdown(def) {
 
   body.push("");
   if (params.length === 0) {
-    body.push("This tool takes no arguments — call it directly (ignore `$ARGUMENTS`).");
+    body.push("This tool takes no arguments — call it directly.");
   } else {
-    body.push("Parse the request in `$ARGUMENTS` into this tool's parameters:", "");
+    body.push(`Parse ${argumentsPhrase} into this tool's parameters:`, "");
     if (required.length) {
       body.push("**Required:**");
       required.forEach((p) => body.push(line(p)));
@@ -83,15 +90,29 @@ export function renderCommandMarkdown(def) {
       body.push("");
     }
     body.push(
-      "If a required parameter is missing from `$ARGUMENTS`, 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."
+      "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."
     );
   }
 
   return `${frontmatter.join("\n")}\n\n${body.join("\n")}\n`;
 }
 
+/**
+ * Claude Code adapter: same stub plus `allowed-tools` scoped to that client's
+ * MCP tool name, and `$ARGUMENTS` so typed `/drupal-*` args are not dropped.
+ *
+ * @param {object} def - The tool definition.
+ * @returns {string} File contents.
+ */
+export function renderClaudeCommandMarkdown(def) {
+  return renderCommandMarkdown(def, {
+    allowedTools: `mcp__drupal__${def.name}`,
+    argumentsPhrase: "`$ARGUMENTS`",
+  });
+}
+
 /**
  * Write one command file per tool, pruning stale `drupal-*.md` first so removed
  * tools leave no orphans.
@@ -118,5 +139,5 @@ const invokedDirectly =
   process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
 if (invokedDirectly) {
   const written = generate();
-  console.error(`[generate-commands] wrote ${written.length} command files to .claude/commands/`);
+  console.error(`[generate-commands] wrote ${written.length} command files to .agents/commands/`);
 }

package/scripts/install-commands.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * install-commands.js — copy generated `/drupal-*` stubs into an operator's
+ * client home directories.
+ *
+ * The canonical files live in `.agents/commands/` (in-repo, harness-agnostic).
+ * Claude Code and Grok only auto-load project commands from vendor paths
+ * (`.claude/commands/`, `.grok/commands/`). This script writes the *user-level*
+ * copies so `/drupal-*` works in every project without committing a vendor
+ * folder to this repo or to a consuming application.
+ *
+ * Default targets: `~/.claude/commands` (Claude adapter) and `~/.grok/commands`
+ * (canonical files). Pass `--clients` to subset. Never writes into a project
+ * tree.
+ *
+ * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,agents]`
+ */
+
+import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { pathToFileURL } from "url";
+
+import { allDefinitions } from "../src/tools/index.js";
+import {
+  commandFileName,
+  renderCommandMarkdown,
+  renderClaudeCommandMarkdown,
+} from "./generate-commands.js";
+
+/** Whitelisted install targets. `rel` is under `--home` (default: os.homedir()). */
+export const CLIENTS = {
+  claude: {
+    rel: ".claude/commands",
+    render: renderClaudeCommandMarkdown,
+  },
+  grok: {
+    rel: ".grok/commands",
+    render: renderCommandMarkdown,
+  },
+  agents: {
+    rel: ".agents/commands",
+    render: renderCommandMarkdown,
+  },
+};
+
+const DEFAULT_CLIENTS = ["claude", "grok"];
+
+/**
+ * Parse CLI flags. Unknown flags throw.
+ *
+ * @param {string[]} argv - Arguments after the script name.
+ * @returns {{home?: string, clients: string[], help?: boolean}}
+ */
+export function parseArgs(argv) {
+  const out = { clients: [...DEFAULT_CLIENTS] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (a === "--home") {
+      out.home = argv[++i];
+      if (!out.home) throw new Error("--home requires a directory");
+      continue;
+    }
+    if (a.startsWith("--home=")) {
+      out.home = a.slice("--home=".length);
+      continue;
+    }
+    if (a === "--clients") {
+      const raw = argv[++i];
+      if (!raw) throw new Error("--clients requires a comma-separated list");
+      out.clients = splitClients(raw);
+      continue;
+    }
+    if (a.startsWith("--clients=")) {
+      out.clients = splitClients(a.slice("--clients=".length));
+      continue;
+    }
+    throw new Error(`Unknown argument: ${a}`);
+  }
+  return out;
+}
+
+function splitClients(raw) {
+  const names = String(raw).split(",").map((s) => s.trim()).filter(Boolean);
+  if (!names.length) throw new Error("--clients requires at least one client");
+  return names;
+}
+
+/**
+ * Write one `drupal-*.md` per tool into each requested client directory,
+ * pruning stale stubs first. Unknown client names fail closed.
+ *
+ * @param {object} [options]
+ * @param {string} [options.home] - Install root (default: os.homedir()).
+ * @param {string[]} [options.clients] - Subset of CLIENTS keys.
+ * @param {Array<object>} [options.definitions]
+ * @returns {Array<{client: string, dir: string, written: string[]}>}
+ */
+export function install(options = {}) {
+  const home = resolve(options.home || homedir());
+  const names = options.clients || DEFAULT_CLIENTS;
+  const definitions = options.definitions || allDefinitions;
+
+  const results = [];
+  for (const name of names) {
+    const client = CLIENTS[name];
+    if (!client) {
+      throw new Error(`Unknown client "${name}". Allowed: ${Object.keys(CLIENTS).join(", ")}`);
+    }
+    const dir = join(home, client.rel);
+    mkdirSync(dir, { recursive: true });
+    for (const f of readdirSync(dir)) {
+      if (/^drupal-.*\.md$/.test(f)) rmSync(join(dir, f));
+    }
+    const written = [];
+    for (const def of definitions) {
+      const file = commandFileName(def);
+      writeFileSync(join(dir, file), client.render(def));
+      written.push(file);
+    }
+    results.push({ client: name, dir, written });
+  }
+  return results;
+}
+
+const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,agents]
+
+Copy generated /drupal-* command stubs into operator home directories.
+Does not write into a project tree.
+
+  --home DIR       Install root (default: the current user's home)
+  --clients LIST   Comma-separated subset of: claude, grok, agents
+                   (default: claude,grok)
+`;
+
+const invokedDirectly =
+  process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
+if (invokedDirectly) {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      console.error(HELP);
+      process.exit(0);
+    }
+    const results = install(opts);
+    for (const r of results) {
+      console.error(`[install-commands] wrote ${r.written.length} files to ${r.dir} (${r.client})`);
+    }
+  } catch (err) {
+    console.error(`[install-commands] ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/lib/backends/backend-interface.js

@@ -93,7 +93,10 @@ export class Backend {
 
   /**
    * Update an entity.
-   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object}} _input
+   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object, resourceVersion?: string}} _input
+   *   `resourceVersion` is a JSON:API revision selector (`rel:working-copy`,
+   *   `rel:latest-version`, `id:<vid>`). Backends that cannot address revisions
+   *   ignore it.
    * @returns {Promise<import("../canonical.js").CanonicalEntity>}
    */
   async updateEntity(_input) { return notImplemented("updateEntity"); }
@@ -139,6 +142,22 @@ export class Backend {
    */
   async getEntitySchema(_entityType, _bundle) { return notImplemented("getEntitySchema"); }
 
+  /**
+   * Resolve Field API metadata for one field (internal introspection).
+   *
+   * `getEntitySchema` is sampling-only and does NOT expose `allowed_formats`.
+   * The JSON:API adapter reads `field_config` via an internal fetch — not via
+   * agent entity tools (`field_config` is on the agent deny list). Returns
+   * null when the definition cannot be resolved. Callers must not invent
+   * `allowed_formats` from `defaultTextFormat` or `full_html`.
+   *
+   * Default: unknown. GraphQL is read-only for writes; write sites use JSON:API.
+   *
+   * @param {{entityType: string, bundle: string, fieldName: string}} _ref
+   * @returns {Promise<?{fieldName: string, fieldType: ?string, allowedFormats: string[]}>}
+   */
+  async getFieldDefinition(_ref) { return null; }
+
   /**
    * List user roles.
    * @returns {Promise<Array<{id: string, machineName: string, label: string, weight: number}>>}

package/src/lib/backends/jsonapi.js

@@ -9,6 +9,7 @@
 
 import { drupalFetch, drupalUploadFile } from "../drupal-fetch.js";
 import { validateUuid, validateMachineName } from "../validate.js";
+import { parseFieldConfigObject } from "../field-definition.js";
 import { Backend } from "./backend-interface.js";
 import {
   makeCanonicalEntity,
@@ -208,8 +209,10 @@ export class JsonApiBackend extends Backend {
         if (BASE_ATTRIBUTE_FIELDS.includes(k)) return false;
         if (INTERNAL_ATTR_RE.test(k)) {
           // Paragraph ERR attach needs the current revision id (#192).
+          // Node / revisionable writes need the working vs live vid (#166).
           // Other drupal_internal__* attributes stay stripped.
-          return entityType === "paragraph" && k === "drupal_internal__revision_id";
+          return k === "drupal_internal__vid"
+            || (entityType === "paragraph" && k === "drupal_internal__revision_id");
         }
         return true;
       })
@@ -339,17 +342,24 @@ export class JsonApiBackend extends Backend {
   /**
    * Update an entity via JSON:API PATCH. Retries without `status` on moderated
    * bundles — see writeWithModerationFallback.
-   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object}} input
+   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object, resourceVersion?: string}} input
+   *   `resourceVersion` is a JSON:API revision selector (e.g. `rel:working-copy`).
+   *   When set, it is appended so a forward revision is PATCHed instead of the
+   *   canonical default (#166 / Drupal #2795279).
    * @returns {Promise<import("../canonical.js").CanonicalEntity>} The updated entity.
    */
-  async updateEntity({ entityType, bundle, id, attributes = {}, relationships }) {
+  async updateEntity({ entityType, bundle, id, attributes = {}, relationships, resourceVersion }) {
     validateUuid(id);
     const buildPayload = (attrs) => {
       const payload = { data: { type: `${entityType}--${bundle}`, id, attributes: attrs } };
       if (relationships) payload.data.relationships = relationships;
       return payload;
     };
-    const data = await this.writeWithModerationFallback(`${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`, "PATCH", buildPayload, attributes);
+    let path = `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+    if (resourceVersion) {
+      path += `?resourceVersion=${encodeURIComponent(resourceVersion)}`;
+    }
+    const data = await this.writeWithModerationFallback(path, "PATCH", buildPayload, attributes);
     return this.toCanonical(data.data);
   }
 
@@ -512,6 +522,39 @@ export class JsonApiBackend extends Backend {
       });
   }
 
+  /**
+   * Read Field API metadata from JSON:API `field_config` (chain step 1).
+   *
+   * This is an internal introspection call, not an agent entity-tool read:
+   * `field_config` is on the connector deny list. Do not invent
+   * `allowed_formats` from `this.site.defaultTextFormat` or `full_html`.
+   * Empty / unreadable `field_config` returns null so the caller can try
+   * Drush `config:get field.field.{entityType}.{bundle}.{field}` and, if
+   * that also fails, keep the historical default chain only while the list
+   * is unknown.
+   *
+   * @param {{entityType: string, bundle: string, fieldName: string}} ref
+   * @returns {Promise<?{fieldName: string, fieldType: ?string, allowedFormats: string[]}>}
+   */
+  async getFieldDefinition({ entityType, bundle, fieldName }) {
+    validateMachineName(entityType, "entityType");
+    validateMachineName(bundle, "bundle");
+    validateMachineName(fieldName, "fieldName");
+    const params = new URLSearchParams();
+    params.set("filter[entity_type]", entityType);
+    params.set("filter[bundle]", bundle);
+    params.set("filter[field_name]", fieldName);
+    params.set("page[limit]", "1");
+    let data;
+    try {
+      data = await drupalFetch(this.site, `/jsonapi/field_config/field_config?${params}`);
+    } catch {
+      return null;
+    }
+    const row = Array.isArray(data?.data) ? data.data[0] : data?.data;
+    return parseFieldConfigObject(row?.attributes, fieldName);
+  }
+
   /**
    * Describe a bundle's fields by sampling one entity and inferring attribute
    * types from its values. JSON:API has no schema endpoint, so an empty bundle

package/src/lib/body-summary.js

@@ -0,0 +1,60 @@
+/**
+ * Decide whether the `summary` argument may be written onto `body`.
+ *
+ * Core `text_with_summary` stores a `summary` property. `text_long` and
+ * sampled `text_formatted` do not — Drupal drops an unknown property, so a
+ * silent write would lose the teaser. Fail closed when the sampled schema
+ * cannot confirm the property exists (#163).
+ */
+
+/** Warning attached when `summary` is written onto a text_with_summary body. */
+export const SUMMARY_DEPRECATED_WARNING = {
+  code: "summary_parameter_deprecated",
+  message:
+    "The `summary` argument writes body.summary on core text_with_summary. " +
+    "Prefer setting the site's dedicated deck/summary field via `fields`.",
+};
+
+/**
+ * @param {object} backend Backend with `getEntitySchema`.
+ * @param {string} bundle Node bundle machine name.
+ * @param {string|undefined} summary Caller-supplied summary; undefined = omitted.
+ * @returns {Promise<{deprecated: boolean}>} Whether a deprecation notice applies.
+ * @throws {Error} When `summary` was supplied and the body field has no
+ *   summary property, or the schema cannot be determined.
+ */
+export async function assertBodySummaryWritable(backend, bundle, summary) {
+  if (summary === undefined) return { deprecated: false };
+
+  let schema;
+  try {
+    schema = await backend.getEntitySchema("node", bundle);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Cannot write \`summary\`: the body field schema for node.${bundle} could not be determined (${detail}). Set the site's dedicated deck field via \`fields\` instead.`,
+    );
+  }
+
+  const bodyType = schema?.attributes?.body;
+  if (bodyType === "text_with_summary") {
+    return { deprecated: true };
+  }
+
+  const sampled = bodyType ? ` (sampled as ${bodyType})` : "";
+  throw new Error(
+    `This site's body field has no summary property${sampled}; set the site's deck field via \`fields\`. The \`summary\` argument is only valid for core text_with_summary body fields.`,
+  );
+}
+
+/**
+ * Attach the `summary` deprecation notice to a write (or dryRun) result.
+ *
+ * @param {object|null|undefined} result Tool response.
+ * @returns {object|null|undefined} Result with `_warnings` when result is an object.
+ */
+export function attachSummaryDeprecation(result) {
+  if (!result || typeof result !== "object") return result;
+  const existing = Array.isArray(result._warnings) ? result._warnings : [];
+  return { ...result, _warnings: [...existing, SUMMARY_DEPRECATED_WARNING] };
+}