drupal-mcp-connector 2.7.2 → 2.7.4

package/.claude/commands/drupal-update-menu-link.md

@@ -14,7 +14,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Menu link UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `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).
 - `title` (string): New link label. Omit to leave unchanged.
 - `link` (string): New target URI (e.g. 'entity:node/42'). Omit to leave unchanged.
 - `menu` (string): Move the link to this menu. Omit to leave unchanged.

package/.claude/commands/drupal-update-node.md

@@ -15,7 +15,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Node UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `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).
 - `title` (string)
 - `body` (string)
 - `summary` (string): Body summary/teaser — writes the `summary` property of the body field (core `text_with_summary`). Many headless sites instead use a dedicated summary/deck field for teasers and meta descriptions; on those, set that field in `fields` — a value written here will be stored but may never be rendered.

package/.claude/commands/drupal-update-paragraph.md

@@ -15,7 +15,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Paragraph UUID
 
 **Optional:**
-- `site` (string): Named site (omit for default)
+- `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).
 - `attributes` (object (pass as JSON)): Paragraph field values to change, keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }
 
 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.

package/.claude/commands/drupal-update-redirect.md

@@ -14,7 +14,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): Redirect entity UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `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).
 - `source` (string): New source/old path (leading slash optional). Omit to leave unchanged.
 - `target` (string): New destination path/URI. Omit to leave unchanged.
 - `statusCode` (number): New HTTP redirect status code (301/302/303/307/308). Omit to leave unchanged.

package/.claude/commands/drupal-update-taxonomy-term.md

@@ -15,7 +15,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string)
 
 **Optional:**
-- `site` (string): omit for the default site
+- `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).
 - `name` (string)
 - `description` (string)
 - `weight` (number)

package/.claude/commands/drupal-update-user.md

@@ -14,7 +14,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `id` (string): User UUID
 
 **Optional:**
-- `site` (string): omit for the default site
+- `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).
 - `name` (string)
 - `mail` (string)
 - `password` (string)

package/.claude/commands/drupal-upload-file-and-create-media.md

@@ -16,7 +16,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `fieldName` (string): Source field machine name, e.g. 'field_media_image'
 
 **Optional:**
-- `site` (string): omit for the default site
+- `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).
 - `mediaName` (string): Name for the media entity (defaults to filename)
 - `altText` (string): Alt text for image media
 - `status` (boolean (true/false)): Published flag. Defaults to false. Requires allowPublish when true.

package/.claude/commands/drupal-upload-file.md

@@ -16,7 +16,7 @@ Parse the request in `$ARGUMENTS` into this tool's parameters:
 - `fieldName` (string): Field machine name, e.g. 'field_media_image', 'field_image'
 
 **Optional:**
-- `site` (string): omit for the default site
+- `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).
 - `entityType` (string): Drupal entity type (usually 'media' or 'node')
 
 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.

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.4] - 2026-08-18
+
+### Fixed
+- **`drupal_content_by_moderation_state` no longer 500s on stock JSON:API
+  (#162).** `moderation_state` is a computed field and is not filterable
+  over core JSON:API. The tool still tries the server-side filter (so a
+  jsonapi_extras alias keeps working), and when Drupal rejects it the
+  connector samples recent nodes and filters client-side. The payload
+  reports `source: "sampled"` and `approximate` instead of a raw Drupal
+  500. If the field is not exposed at all, the result is a gated
+  `unavailable` payload.
+- **Every tool response names the resolved site (#167).** Omitting `site`
+  still defaults to `defaultSite`, but the payload now carries
+  `_target: { name, baseUrl, source }` — the same block `drupal_mcp_whoami`
+  already returned as `target`. `source` is `hint` when the caller named a
+  site, `default` when the configured default was used, or `grant` when a
+  principal had exactly one entitled site. A list_nodes-shaped success with
+  only `_backend` is no longer claimable as production. Writes (including
+  GraphQL mutations and generic `drupal_entity_*` writes) refuse a silent
+  default when more than one site is configured; a write on the wrong site
+  is not recoverable. Single-site configs are unchanged. Array-shaped
+  results are wrapped as `{ items, _target }` so the field survives
+  `JSON.stringify`.
+
+## [2.7.3] - 2026-08-18
+
+### Fixed
+- **Launcher and startup name a secret-table / config mismatch (#211).**
+  The shipped Keychain table matches `config/config.example.json`. A
+  `config.json` that uses different `clientSecretEnv` names without a
+  `config/secrets.map` left the table and the config each valid and
+  jointly inert. Per-item Keychain misses stay silent (break-glass).
+  When the table matches **no** named secret, `bin/drupal-mcp-launch.sh`
+  and `src/lib/load-secrets.js` now print one stderr line that names
+  the unmapped variables and says `secrets.map` is absent (or that the
+  map does not name them). Fail-closed start when every named secret is
+  unset is unchanged.
+
 ## [2.7.2] - 2026-08-18
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 
 Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
-**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.2** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
+**If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to **2.7.4** (or at least 2.6.1), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
 
 ---
 
@@ -44,6 +44,7 @@ Each site declares which backend(s) it exposes via the `api` key:
 - **`api` accepts** `"jsonapi"`, `"graphql"`, or a priority array like `["graphql","jsonapi"]`. Omit it to **auto-detect** (the connector probes both once and caches the result).
 - **One canonical shape.** Both backends return entities as
   `{ id, entityType, bundle, title, status, langcode, created, changed, url, fields, relationships, _backend }`, so tool output is identical regardless of protocol.
+  Every site-addressing response also includes `_target: { name, baseUrl, source }` so a defaulted call cannot be mistaken for another environment.
 - **Capability-aware.** Each backend advertises what it supports (read, write, delete, server-side filter/sort, revisions). GraphQL via GraphQL Compose is **read-only** (no mutations) and has no server-side field filter, so filters are applied client-side over a bounded fetch and flagged `approximate`/`truncated`. Write tools against a read-only backend return a clear capability error rather than failing silently.
 - **Writes go through JSON:API.** Use a JSON:API-enabled site as the write plane; keep GraphQL as a read plane where that suits your architecture.
 - **`defaultTextFormat` sets the body text format** used by the `body` convenience

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.7.2",
+  "version": "2.7.4",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -34,7 +34,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { toNodeHandler } from "@modelcontextprotocol/node";
 
 import { listSiteNames, getTlsConfig, loadConfig, CLIENT_VERSION } from "./lib/config.js";
-import { loadLocalSecrets, secretLoadFatalMessage } from "./lib/load-secrets.js";
+import { loadLocalSecrets, secretLoadFatalMessage, secretTableMismatchMessage } from "./lib/load-secrets.js";
 import {
   makeBearerCheck,
   resolveInboundAuthConfig,
@@ -68,7 +68,10 @@ if (secretFatal) {
   console.error(`[drupal-mcp-connector] FATAL: ${secretFatal}`);
   process.exit(1);
 }
-if (secretLoad.unset.length) {
+const secretMismatch = secretTableMismatchMessage(secretLoad);
+if (secretMismatch) {
+  console.error(`[drupal-mcp-connector] WARNING: ${secretMismatch}`);
+} else if (secretLoad.unset.length) {
   console.error(
     "[drupal-mcp-connector] WARNING: config.json names secret env vars that are unset: " +
     `${secretLoad.unset.join(", ")}. Those sites will fail closed.`

package/src/lib/dispatch.js

@@ -16,7 +16,10 @@ import { toolError, toolResult } from "./errors.js";
 import { BackendCapabilityError, BackendResolutionError } from "./backends/errors.js";
 import { inferOperation } from "./operations.js";
 import { assertSourceGovernance, GovernanceError, GOVERNANCE_DIAGNOSTIC_TOOLS } from "./governance.js";
-import { assertPrincipalEntitlement, getRequestIdentity } from "./principal.js";
+import {
+  assertPrincipalEntitlement, callerTargetHints, getRequestIdentity,
+} from "./principal.js";
+import { assertExplicitSiteForWrite, withResolvedTarget } from "./site-target.js";
 import { allHandlers } from "../tools/index.js";
 
 /**
@@ -39,6 +42,47 @@ export function listResolvableSiteConfigs() {
   });
 }
 
+/**
+ * Resolve which site this call addresses and how that name was chosen.
+ * Returns null for tools that do not address a single site (`list_sites`,
+ * unscoped `governance_status`).
+ *
+ * @param {string} toolName
+ * @param {object} rawArgs Caller arguments before any rewrite.
+ * @param {object} [context]
+ * @returns {?{site: object, source: string, name: string}}
+ * @throws {SecurityError}
+ */
+export function resolveCallTarget(toolName, rawArgs, context = {}) {
+  if (toolName === "drupal_list_sites") return null;
+  if (toolName === "drupal_governance_status" && callerTargetHints(rawArgs).length === 0) {
+    return null;
+  }
+
+  const identity = context.identity !== undefined ? context.identity : getRequestIdentity();
+  if (identity) {
+    return assertPrincipalEntitlement({
+      toolName,
+      args: rawArgs,
+      identity,
+      sites: context.sites ?? listResolvableSiteConfigs(),
+      grants: context.grants,
+      defaultSite: context.defaultSite,
+    });
+  }
+
+  const hints = callerTargetHints(rawArgs);
+  const unique = [...new Set(hints.map((hint) => hint.value))];
+  if (unique.length > 1) {
+    throw new SecurityError(
+      "Conflicting caller target hints do not select a single target.",
+    );
+  }
+  const source = unique.length === 1 ? "hint" : "default";
+  const site = getSiteConfig(unique[0]);
+  return { site, source, name: site._name };
+}
+
 /**
  * Derive the entity type a tool acts on, for destructive-allow assertions.
  *
@@ -72,18 +116,21 @@ export async function securityMiddleware(toolName, args, handler, context = {})
   const identity = context.identity !== undefined ? context.identity : getRequestIdentity();
   let nextArgs = rawArgs;
 
-  if (identity) {
-    const resolved = assertPrincipalEntitlement({
-      toolName,
-      args: rawArgs,
-      identity,
-      sites: context.sites ?? listResolvableSiteConfigs(),
-      grants: context.grants,
-      defaultSite: context.defaultSite,
-    });
-    if (resolved) {
-      nextArgs = { ...rawArgs, site: resolved.name };
-    }
+  const resolved = resolveCallTarget(toolName, rawArgs, { ...context, identity });
+  if (context && typeof context === "object") {
+    context.resolvedTarget = resolved;
+  }
+  assertExplicitSiteForWrite(
+    toolName,
+    rawArgs,
+    resolved,
+    context.siteNames ?? listSiteNames(),
+  );
+
+  if (resolved) {
+    // Authoritative name plus the real source. Injecting `site` alone would
+    // make whoami report source:"hint" for a defaulted call (#167 / identity path).
+    nextArgs = { ...rawArgs, site: resolved.name, _resolvedSource: resolved.source };
   }
 
   // Tools with no site context skip per-site checks. governance_status
@@ -137,8 +184,9 @@ export async function callTool(name, args, context = {}) {
   }
 
   try {
-    const result = await securityMiddleware(name, args ?? {}, handler, context);
-    return toolResult(result);
+    const ctx = { ...context };
+    const result = await securityMiddleware(name, args ?? {}, handler, ctx);
+    return toolResult(withResolvedTarget(result, ctx.resolvedTarget));
   } catch (err) {
     // Translate known error classes into clear, non-leaky isError responses;
     // anything else falls through to toolError for a generic envelope.

package/src/lib/load-secrets.js

@@ -9,8 +9,10 @@
  * The default table matches config/config.example.json. A gitignored
  * config/secrets.map replaces that table for a deployment whose env-var
  * names differ. Per-item Keychain misses stay silent (inert break-glass).
- * If the active config.json names secret env vars and none of them are set
- * after this step, the caller must refuse to start.
+ * Zero overlap between the table and the names in config.json is a
+ * distinct case — the two files are jointly inert — and the caller should
+ * say so. If every named secret is still unset after this step, the caller
+ * must refuse to start.
  */
 
 import { execFileSync } from "node:child_process";
@@ -101,7 +103,7 @@ export function lookupKeychainItem(item) {
  * @param {NodeJS.ProcessEnv} [options.env] Mutated when a lookup succeeds.
  * @param {typeof readFileSync} [options.readFile]
  * @param {(item: string) => string} [options.lookup]
- * @returns {{pairs: number, resolved: number, named: string[], unset: string[]}}
+ * @returns {{pairs: number, resolved: number, named: string[], unset: string[], tableVars: string[], source: "map"|"default"}}
  */
 export function loadLocalSecrets({
   cwd = process.cwd(),
@@ -109,11 +111,13 @@ export function loadLocalSecrets({
   readFile = readFileSync,
   lookup = lookupKeychainItem,
 } = {}) {
+  let source = "map";
   let pairs;
   try {
     pairs = parseSecretMap(readFile(join(cwd, "config", "secrets.map"), "utf8"));
   } catch {
     pairs = DEFAULT_SECRET_PAIRS;
+    source = "default";
   }
 
   let resolved = 0;
@@ -140,16 +144,47 @@ export function loadLocalSecrets({
 
   const envMap = new Map(Object.entries(env));
   const unset = named.filter((name) => !envMap.get(name));
-  return { pairs: pairs.length, resolved, named, unset };
+  const tableVars = pairs.map(([varName]) => varName);
+  return { pairs: pairs.length, resolved, named, unset, tableVars, source };
+}
+
+/**
+ * One-line diagnosis when the secret table and config.json share no names.
+ * Null when there is any overlap, or when config names no secrets.
+ * Per-item Keychain misses are not a mismatch.
+ * @param {{named: string[], tableVars?: string[], source?: "map"|"default"}} loaded
+ * @returns {string|null}
+ */
+export function secretTableMismatchMessage(loaded) {
+  if (!loaded.named.length) return null;
+  const table = new Set(loaded.tableVars || []);
+  const unmapped = loaded.named.filter((name) => !table.has(name));
+  if (unmapped.length !== loaded.named.length) return null;
+  const source = loaded.source === "map"
+    ? "config/secrets.map does not name them"
+    : "using shipped defaults; config/secrets.map is absent";
+  const unset = Array.isArray(loaded.unset) ? loaded.unset : [];
+  const closer = unset.length
+    ? "Unset: " + unset.join(", ") + ". Those sites will fail closed."
+    : "Named secrets already in the environment stay set; the table will not populate any of them.";
+  return (
+    "no secret-table entries match clientSecretEnv/apiTokenEnv names in config.json " +
+    "(" + unmapped.join(", ") + "); " + source + ". " +
+    closer
+  );
 }
 
 /**
  * Refuse to boot a server that can only advertise diagnostic tools.
- * @param {{named: string[], unset: string[]}} loaded
+ * @param {{named: string[], unset: string[], tableVars?: string[], source?: "map"|"default"}} loaded
  * @returns {string|null} Fatal message, or null when start is allowed.
  */
 export function secretLoadFatalMessage(loaded) {
   if (!loaded.named.length || loaded.unset.length !== loaded.named.length) return null;
+  const mismatch = secretTableMismatchMessage(loaded);
+  if (mismatch) {
+    return mismatch + " Refusing to start. Map those names in config/secrets.map (ENV_VAR=keychain-item) or export them before launch.";
+  }
   return (
     `every clientSecretEnv/apiTokenEnv named in config.json is unset (${loaded.unset.join(", ")}). ` +
     "Refusing to start. Map those names in config/secrets.map (ENV_VAR=keychain-item) " +

package/src/lib/operations.js

@@ -10,6 +10,8 @@
  * warnings surfaced to users can never drift apart.
  */
 
+import { graphqlHasMutation } from "./security.js";
+
 export const WRITE_PREFIXES = ["drupal_create_", "drupal_update_", "drupal_upload_",
   "drupal_block_",  "drupal_drush_cache", "drupal_drush_cron",
   "drupal_drush_config_export", "drupal_drush_config_import",
@@ -39,8 +41,13 @@ export function inferOperation(toolName) {
 // Generic entity tools carry their target type/bundle in ARGS, not the tool name,
 // so the security middleware gates them inside their handlers (assertDeleteAllowed /
 // assertWriteAllowed with full context) and inferOperation() intentionally leaves
-// them classified "read". For the user-facing confirm-first WARNING, though, we
-// still want the destructive hint to show, so classify them by name here.
+// them classified "read". Write-site gating and the user-facing confirm-first
+// WARNING still classify them by name.
+const ENTITY_WRITE_TOOLS = new Set([
+  "drupal_entity_create",
+  "drupal_entity_update",
+  "drupal_entity_delete",
+]);
 const DESTRUCTIVE_ENTITY_TOOLS = new Set(["drupal_entity_delete"]);
 
 /**
@@ -55,3 +62,33 @@ const DESTRUCTIVE_ENTITY_TOOLS = new Set(["drupal_entity_delete"]);
 export function isDestructiveTool(toolName) {
   return inferOperation(toolName) === "delete" || DESTRUCTIVE_ENTITY_TOOLS.has(toolName);
 }
+
+/**
+ * Whether a tool is a write or delete regardless of how inferOperation classifies it.
+ * Covers the generic `drupal_entity_{create,update,delete}` tools that self-gate
+ * inside their handlers and are therefore left as "read" by prefix inference.
+ *
+ * @param {string} toolName - The MCP tool name.
+ * @returns {boolean}
+ */
+export function isWriteLikeTool(toolName) {
+  if (ENTITY_WRITE_TOOLS.has(toolName)) return true;
+  const op = inferOperation(toolName);
+  return op === "write" || op === "delete";
+}
+
+/**
+ * Whether this invocation mutates the target. GraphQL is a write only when the
+ * document contains a mutation; a query is still a read.
+ *
+ * @param {string} toolName
+ * @param {object} [args]
+ * @returns {boolean}
+ */
+export function isWriteLikeCall(toolName, args = {}) {
+  if (isWriteLikeTool(toolName)) return true;
+  if (inferOperation(toolName) === "graphql" && typeof args.query === "string") {
+    return graphqlHasMutation(args.query);
+  }
+  return false;
+}

package/src/lib/security.js

@@ -470,7 +470,7 @@ export function assertPublishAllowed(secConfig, attributes = {}) {
  * @param {string} query GraphQL document text.
  * @returns {boolean} True if any operation is a mutation.
  */
-function graphqlHasMutation(query) {
+export function graphqlHasMutation(query) {
   try {
     const doc = parse(query);
     return doc.definitions.some(

package/src/lib/site-target.js

@@ -0,0 +1,78 @@
+/**
+ * Resolved-target disclosure and the multi-site write guard (#167).
+ *
+ * A silent default that returns plausible content from the wrong environment
+ * is the failure class: the response looks like success and every field a
+ * caller would sanity-check (id, title, url) is correct. `_target` uses the
+ * same `{ name, baseUrl, source }` block as `drupal_mcp_whoami` so there is
+ * one vocabulary. `source` is load-bearing — `hint` when the caller named a
+ * target, `default` when `defaultSite` was used, `grant` when a principal
+ * had exactly one entitled site.
+ *
+ * Reads may still default. Writes (and GraphQL mutations) may not when more
+ * than one site is configured: a write on the wrong site is not recoverable.
+ */
+
+import { describeTarget } from "./principal.js";
+import { isWriteLikeCall } from "./operations.js";
+import { SecurityError } from "./security.js";
+
+/** Shared `site` argument schema. Injected onto every tool that accepts `site`. */
+export const SITE_PARAM = {
+  type: "string",
+  description:
+    "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).",
+};
+
+/**
+ * Attach the resolved target to a tool payload so JSON.stringify keeps it.
+ *
+ * Object results get `_target` as a sibling. Arrays are wrapped as
+ * `{ items, _target }` because extra properties on an array are dropped by
+ * JSON.stringify. Tools that do not address a single site pass `resolved` as
+ * null and are returned unchanged.
+ *
+ * @param {*} result Handler return value.
+ * @param {?{site: object, source: string}} resolved
+ * @returns {*}
+ */
+export function withResolvedTarget(result, resolved) {
+  if (!resolved?.site) return result;
+  const _target = describeTarget(resolved.site, resolved.source);
+  if (result && typeof result === "object" && !Array.isArray(result)) {
+    return { ...result, _target };
+  }
+  if (Array.isArray(result)) {
+    return { items: result, _target };
+  }
+  if (result === undefined || result === null) {
+    return { _target };
+  }
+  return { result, _target };
+}
+
+/**
+ * Refuse a write that would silently land on defaultSite when more than one
+ * site is configured. Resolution behaviour for reads is unchanged.
+ *
+ * @param {string} toolName
+ * @param {object} args Raw caller arguments (before any default rewrite).
+ * @param {?{site: object, source: string, name: string}} resolved
+ * @param {string[]} siteNames Configured site names.
+ * @returns {void}
+ * @throws {SecurityError}
+ */
+export function assertExplicitSiteForWrite(toolName, args, resolved, siteNames) {
+  if (!resolved || resolved.source !== "default") return;
+  if (!Array.isArray(siteNames) || siteNames.length < 2) return;
+  if (!isWriteLikeCall(toolName, args)) return;
+  throw new SecurityError(
+    "Write tools require an explicit site when more than one site is configured. " +
+    "Omitted site would default to \"" + resolved.name + "\" (" + resolved.site.baseUrl + "). " +
+    "Pass site explicitly. Configured sites: " + siteNames.join(", ") + ".",
+  );
+}

package/src/lib/tool-prompts.js

@@ -15,6 +15,7 @@
  */
 
 import { isDestructiveTool } from "./operations.js";
+import { SITE_PARAM } from "./site-target.js";
 
 /** Convert a tool name to its prompt/command name: `drupal_create_node` → `drupal-create-node`. */
 export const toolNameToPromptName = (name) => name.replace(/_/g, "-");
@@ -54,7 +55,7 @@ export function paramList(inputSchema) {
     name,
     required: required.has(name),
     hint: typeHint(spec),
-    description: spec?.description || (name === "site" ? "omit for the default site" : ""),
+    description: spec?.description || (name === "site" ? SITE_PARAM.description : ""),
   }));
 }
 

package/src/tools/config.js

@@ -107,7 +107,7 @@ function inferTier(site, sec) {
  * @param {object} args - { site? }.
  * @returns {Promise<object>} Effective identity + capability summary.
  */
-async function whoami({ site: siteName }) {
+async function whoami({ site: siteName, _resolvedSource }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   const summary = getSecuritySummary(site);
@@ -119,9 +119,12 @@ async function whoami({ site: siteName }) {
   const canWrite  = !sec.readOnly && hasScope(site, "mcp_write");
   const canConfig = hasScope(site, "mcp_config");
   const identity = getRequestIdentity();
+  // Dispatch may inject `site` after a default/grant resolution. Prefer the
+  // authoritative source so `target` and `_target` cannot disagree (#167).
+  const source = _resolvedSource ?? (siteName ? "hint" : "default");
   return {
     site: site._name,
-    target: describeTarget(site, siteName ? "hint" : "default"),
+    target: describeTarget(site, source),
     principal: identity
       ? { sub: identity.sub, clientId: identity.clientId, scopes: [...(identity.scopes ?? [])] }
       : null,

package/src/tools/index.js

@@ -37,14 +37,34 @@ import * as reportsConfig  from "./reports-config.js";
 import * as reportsContent from "./reports-content.js";
 import * as auditComposite from "./audit-composite.js";
 import * as config       from "./config.js";
+import { SITE_PARAM } from "../lib/site-target.js";
 
 export const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
   revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra,
   reportsLinks, reportsConfig, reportsContent, auditComposite, config];
 
+/**
+ * Stamp the shared `site` description onto every tool that accepts one so
+ * agents are not told "omit for the default" as if that meant production.
+ *
+ * @param {object} def Tool definition.
+ * @returns {object}
+ */
+function withSiteParam(def) {
+  const props = def.inputSchema?.properties;
+  if (!props?.site) return def;
+  return {
+    ...def,
+    inputSchema: {
+      ...def.inputSchema,
+      properties: { ...props, site: { ...props.site, ...SITE_PARAM } },
+    },
+  };
+}
+
 // Flatten every module's tool definitions into one ListTools payload, and merge
 // their handler maps into a single closed dispatch table keyed by tool name.
-export const allDefinitions = allModules.flatMap((m) => m.definitions);
+export const allDefinitions = allModules.flatMap((m) => m.definitions).map(withSiteParam);
 export const allHandlers    = Object.assign({}, ...allModules.map((m) => m.handlers));
 
 // Fast name → definition lookup for prompt/command rendering.