mixdog 1.2.0 → 1.2.1

package/src/runtime/agent/orchestrator/mcp/client-config.mjs

@@ -3,6 +3,8 @@
  * kind, URL policy, env expansion, stdio environment, HTTP headers, timeouts,
  * and the log scrubbing that keeps credentials out of connection messages.
  */
+import { createHash } from 'node:crypto';
+import { rememberMcpToolIdentity } from '../../../shared/tool-primitives.mjs';
 
 /** Known auto-detect targets: the discovery-advert service name and the MCP
  *  endpoint path on its port.
@@ -108,30 +110,106 @@ export function scrubMcpConnectionMessage(value, cfg = {}) {
 }
 
 /**
- * Expand `${VAR}` and `${env:VAR}` references in string values using the
- * provided env map (defaults to process.env). Recurses into arrays/objects.
- * Unknown vars expand to an empty string. No shell execution.
+ * Expand `${VAR}`, `${env:VAR}` and `${VAR:-default}` references in string
+ * values using the provided env map (defaults to process.env). Recurses into
+ * arrays/objects. The default (possibly empty) applies only when the variable
+ * is unset, and runs to the first `}`. An unset variable without a default
+ * expands to an empty string and, when `missing` (a Set) is given, its name is
+ * recorded there. No shell execution.
  */
-export function expandEnvVars(value, env = process.env) {
+export function expandEnvVars(value, env = process.env, missing) {
   if (typeof value === 'string') {
-    return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => {
+    return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_m, name, fallback) => {
       const v = env?.[name];
-      return v == null ? '' : String(v);
+      if (v != null) return String(v);
+      if (fallback !== undefined) return fallback;
+      missing?.add(name);
+      return '';
     });
   }
   if (Array.isArray(value)) {
-    return value.map((v) => expandEnvVars(v, env));
+    return value.map((v) => expandEnvVars(v, env, missing));
   }
   if (value && typeof value === 'object') {
     const out = {};
     for (const [k, v] of Object.entries(value)) {
-      out[k] = expandEnvVars(v, env);
+      out[k] = expandEnvVars(v, env, missing);
     }
     return out;
   }
   return value;
 }
 
+/**
+ * Names (deduplicated, first-seen order) of variables a server config needs
+ * that are unset: `${VAR}` references without a default in command, args,
+ * env, url, headers and cwd, plus the variables named directly by
+ * `bearer_token_env_var`, `env_http_headers` values and `env_vars`. Names
+ * only — never values.
+ */
+export function findMissingMcpEnvVars(cfg = {}, env = process.env) {
+  const missing = new Set();
+  expandEnvVars([cfg.command, cfg.args, cfg.env, cfg.url, cfg.headers, cfg.cwd], env, missing);
+  const named = [
+    cfg.bearer_token_env_var,
+    ...(cfg.env_http_headers && typeof cfg.env_http_headers === 'object' && !Array.isArray(cfg.env_http_headers)
+      ? Object.values(cfg.env_http_headers)
+      : []),
+    ...(Array.isArray(cfg.env_vars) ? cfg.env_vars : []),
+  ];
+  for (const value of named) {
+    const name = typeof value === 'string' ? value.trim() : '';
+    if (name && envValue(env, name) == null) missing.add(name);
+  }
+  return [...missing];
+}
+
+// Windows variable names are case-insensitive.
+function envValue(env, name) {
+  if (process.platform !== 'win32') return env?.[name];
+  const actual = Object.keys(env || {}).find((key) => key.toLowerCase() === name.toLowerCase());
+  return actual ? env[actual] : undefined;
+}
+
+// Provider tool names: at most 64 characters of [A-Za-z0-9_-] (the strictest
+// limit among the providers Mixdog talks to).
+const PROVIDER_TOOL_NAME_MAX = 64;
+const PROVIDER_TOOL_NAME_RE = /^[A-Za-z0-9_-]+$/;
+const KEPT_SERVER_PART_MAX = 40;
+
+/**
+ * `mcp__<server>__<tool>` when that already fits provider limits (unchanged
+ * for every name that fits today). Otherwise a deterministic short form:
+ * the server part kept when it is safe (sanitized and cut short when not),
+ * the tool part sanitized and cut, and a hash of the full name appended so
+ * distinct tools never meet. Callers keep the original tool name alongside
+ * to dispatch the call.
+ */
+export function providerSafeMcpToolName(serverName, toolName) {
+  const server = String(serverName || '');
+  const tool = String(toolName || '');
+  const full = `mcp__${server}__${tool}`;
+  if (full.length <= PROVIDER_TOOL_NAME_MAX && PROVIDER_TOOL_NAME_RE.test(full)) return full;
+  const hash = createHash('sha1').update(full).digest('hex').slice(0, 8);
+  const serverPart =
+    /^[A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*$/.test(server) && server.length <= KEPT_SERVER_PART_MAX
+      ? server
+      : server
+          .replace(/[^A-Za-z0-9-]+/g, '-')
+          .replace(/^-+|-+$/g, '')
+          .slice(0, 24)
+          .replace(/-+$/, '') || 'server';
+  const room = PROVIDER_TOOL_NAME_MAX - `mcp__${serverPart}__`.length - hash.length - 1;
+  const toolPart = tool
+    .replace(/[^A-Za-z0-9_-]+/g, '_')
+    .slice(0, Math.max(0, room))
+    .replace(/_+$/, '');
+  const safe = `mcp__${serverPart}__${toolPart ? `${toolPart}_` : ''}${hash}`;
+  // Name-only consumers in this process (display, guards) resolve it back.
+  rememberMcpToolIdentity(safe, server, tool);
+  return safe;
+}
+
 const DEFAULT_STDIO_ENV_KEYS =
   process.platform === 'win32'
     ? [

package/src/runtime/agent/orchestrator/mcp/client-handshake.mjs

@@ -15,12 +15,15 @@ const MAX_MCP_TOOL_PAGES = 100;
  * Every tool of a server: follows `nextCursor` until it is exhausted, repeats,
  * or MAX_MCP_TOOL_PAGES is reached. A page with an invalid shape is returned
  * as-is so the caller's shape validation reports it.
+ * The SDK rebuilds its output validators from each page alone, so after a
+ * paginated listing they are rebuilt once from every page's tools.
  */
 export async function listAllMcpTools(client, requestOptions = undefined) {
   const tools = [];
   const seen = new Set();
   let cursor = null;
-  for (let page = 0; page < MAX_MCP_TOOL_PAGES; page += 1) {
+  let pages = 0;
+  for (; pages < MAX_MCP_TOOL_PAGES; pages += 1) {
     const result = await client.listTools(cursor ? { cursor } : undefined, requestOptions);
     if (!result || !Array.isArray(result.tools)) return result;
     tools.push(...result.tools);
@@ -29,6 +32,7 @@ export async function listAllMcpTools(client, requestOptions = undefined) {
     seen.add(next);
     cursor = next;
   }
+  if (pages > 0) client.cacheToolMetadata?.(tools);
   return { tools };
 }
 

package/src/runtime/agent/orchestrator/mcp/client-transport.mjs

@@ -7,6 +7,7 @@ import { readServicePort } from '../../../shared/service-discovery.mjs';
 import {
   AUTO_DETECT_PORTS,
   expandEnvVars,
+  findMissingMcpEnvVars,
   mcpUrlForLog,
   normalizeMcpTransportUrl,
   resolveMcpHttpHeaders,
@@ -48,11 +49,58 @@ function requestInitFor(cfg) {
   return headers && Object.keys(headers).length > 0 ? { requestInit: { headers } } : undefined;
 }
 
-/** Returns { transport, autoDetectAdvert, stderrTail } — stderrTail() is the
- *  last ~4 KB of a stdio server's (scrubbed) stderr, '' for remote transports. */
-export function createMcpTransport({ name, cfg, sdk, log }) {
+// The SDK's WebSocket transport opens its socket without a way to set request
+// headers. This subclass changes only socket creation: Node's WebSocket takes
+// `{ protocols, headers }`; the guard and event wiring match the stock start().
+function createHeaderWebSocketTransport(Base, messageSchema, url, headers) {
+  return new (class extends Base {
+    start() {
+      if (this._socket) {
+        throw new Error(
+          'WebSocketClientTransport already started! If using Client class, note that connect() calls start() automatically.'
+        );
+      }
+      return new Promise((resolve, reject) => {
+        this._socket = new globalThis.WebSocket(this._url, { protocols: 'mcp', headers });
+        this._socket.onerror = (event) => {
+          const error = 'error' in event ? event.error : new Error(`WebSocket error: ${JSON.stringify(event)}`);
+          reject(error);
+          this.onerror?.(error);
+        };
+        this._socket.onopen = () => resolve();
+        this._socket.onclose = () => this.onclose?.();
+        this._socket.onmessage = (event) => {
+          let message;
+          try {
+            message = messageSchema.parse(JSON.parse(event.data));
+          } catch (error) {
+            this.onerror?.(error);
+            return;
+          }
+          this.onmessage?.(message);
+        };
+      });
+    }
+  })(url);
+}
+/** Returns { transport, autoDetectAdvert, stderrTail, warnings } — stderrTail()
+ *  is the last ~4 KB of a stdio server's (scrubbed) stderr, '' for remote
+ *  transports. `strictEnv` (the caller passes it for plugin-declared servers)
+ *  makes unset variables without a default fail the server; otherwise they
+ *  expand to empty and are reported in `warnings` (names only). */
+export function createMcpTransport({ name, cfg, sdk, log, strictEnv }) {
   const { StdioClientTransport, StreamableHTTPClientTransport, SSEClientTransport, WebSocketClientTransport } = sdk;
   const kind = resolveMcpTransportKind(cfg);
+  const warnings = [];
+  if (kind !== 'autoDetect') {
+    const missing = findMissingMcpEnvVars(cfg);
+    if (missing.length) {
+      const message = `missing environment variable(s): ${missing.join(', ')}`;
+      if (strictEnv === true) throw new Error(message);
+      warnings.push(message);
+      log(`[mcp-client] "${name}": ${message}\n`);
+    }
+  }
   if (kind === 'autoDetect') {
     const { url, advert } = resolveAutoDetectUrl(name, cfg);
     log(`[mcp-client] Connecting "${name}" via autoDetect HTTP: ${url}\n`);
@@ -60,6 +108,7 @@ export function createMcpTransport({ name, cfg, sdk, log }) {
       transport: new StreamableHTTPClientTransport(new URL(url)),
       autoDetectAdvert: advert,
       stderrTail: noStderrTail,
+      warnings,
     };
   }
   if (kind === 'http' || kind === 'sse') {
@@ -71,19 +120,28 @@ export function createMcpTransport({ name, cfg, sdk, log }) {
       transport: opts ? new Transport(new URL(url), opts) : new Transport(new URL(url)),
       autoDetectAdvert: null,
       stderrTail: noStderrTail,
+      warnings,
     };
   }
   if (kind === 'ws') {
-    // WebSocketClientTransport ctor takes only a URL; headers are ignored.
     const url = normalizeMcpTransportUrl(expandEnvVars(String(cfg.url ?? '')), 'ws');
+    const opts = requestInitFor(cfg);
     log(`[mcp-client] Connecting "${name}" via WebSocket: ${mcpUrlForLog(url)}\n`);
-    return { transport: new WebSocketClientTransport(new URL(url)), autoDetectAdvert: null, stderrTail: noStderrTail };
+    const transport = opts
+      ? createHeaderWebSocketTransport(
+          WebSocketClientTransport,
+          sdk.JSONRPCMessageSchema,
+          new URL(url),
+          opts.requestInit.headers
+        )
+      : new WebSocketClientTransport(new URL(url));
+    return { transport, autoDetectAdvert: null, stderrTail: noStderrTail, warnings };
   }
   if (kind === 'stdio') {
     const transport = new StdioClientTransport({
       command: expandEnvVars(String(cfg.command ?? '')),
       args: Array.isArray(cfg.args) ? expandEnvVars(cfg.args) : cfg.args,
-      cwd: cfg.cwd,
+      cwd: cfg.cwd == null ? cfg.cwd : expandEnvVars(String(cfg.cwd)),
       env: resolveMcpStdioEnvironment(cfg),
       stderr: cfg.stderr ?? 'pipe',
     });
@@ -93,7 +151,7 @@ export function createMcpTransport({ name, cfg, sdk, log }) {
       tail = (tail + text).slice(-MCP_STDERR_TAIL_CHARS);
       log(`[mcp:${name}:stderr] ${text}`);
     });
-    return { transport, autoDetectAdvert: null, stderrTail: () => tail.trim() };
+    return { transport, autoDetectAdvert: null, stderrTail: () => tail.trim(), warnings };
   }
   throw new Error(
     `Invalid config for "${name}": need autoDetect, type (stdio/http/sse/ws), url (http), or command (stdio)`

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -22,7 +22,13 @@ import { createKeyedSingleflight } from './reconnect-singleflight.mjs';
 import { createOwnerFairGate } from '../../../shared/owner-fair-gate.mjs';
 import { currentToolExecutionOwner } from '../../../shared/tool-execution-owner.mjs';
 import { positiveInt } from '../../../shared/numbers.mjs';
-import { resolveMcpRequestTimeouts, resolveMcpTransportKind, scrubMcpConnectionMessage } from './client-config.mjs';
+import {
+  providerSafeMcpToolName,
+  resolveMcpRequestTimeouts,
+  resolveMcpTransportKind,
+  scrubMcpConnectionMessage,
+} from './client-config.mjs';
+import { createLazyOutputValidator } from './lazy-output-validator.mjs';
 import { appendMcpStderrTail, createMcpTransport } from './client-transport.mjs';
 import { listAllMcpTools, runBoundedHandshake } from './client-handshake.mjs';
 
@@ -50,6 +56,8 @@ const MCP_TOOL_NAME_RE = /^mcp__(.+?)__(.+)$/;
 const _knownMcpScopes = new Set([DEFAULT_MCP_SCOPE_ID]);
 const _connectAbortGenerations = new Map();
 const _pendingConnects = new Set();
+// scopeId -> root path advertised by that scope's scope-following servers.
+const _scopeRoots = new Map();
 let mcpSdkPromise = null;
 // Memo for mcpToolHasField(name, field) — keyed by `${scopeId}|${toolName}|${field}`.
 // The lookup (regex parse + servers Map get + tools.find + schema property
@@ -58,8 +66,14 @@ let mcpSdkPromise = null;
 // mutation point (connectServer / disconnectAll) so a stale positive or
 // negative can never survive a tools-list change.
 const _mcpToolFieldMemo = new Map();
+let _mcpToolGeneration = 0;
 function _invalidateMcpToolFieldMemo() {
   _mcpToolFieldMemo.clear();
+  _mcpToolGeneration += 1;
+}
+/** Read-only counter bumped on every MCP tool registry mutation. */
+export function getMcpToolGeneration() {
+  return _mcpToolGeneration;
 }
 function normalizeMcpScopeId(value) {
   const raw = value && typeof value === 'object' ? value.scopeId : value;
@@ -98,12 +112,15 @@ async function loadMcpSdk() {
     import('@modelcontextprotocol/sdk/client/sse.js'),
     import('@modelcontextprotocol/sdk/client/websocket.js'),
     import('@modelcontextprotocol/sdk/types.js'),
-  ]).then(([clientMod, stdioMod, httpMod, sseMod, wsMod, typesMod]) => ({
+    import('@modelcontextprotocol/sdk/validation/ajv'),
+  ]).then(([clientMod, stdioMod, httpMod, sseMod, wsMod, typesMod, ajvMod]) => ({
     Client: clientMod.Client,
+    AjvJsonSchemaValidator: ajvMod.AjvJsonSchemaValidator,
     StdioClientTransport: stdioMod.StdioClientTransport,
     StreamableHTTPClientTransport: httpMod.StreamableHTTPClientTransport,
     SSEClientTransport: sseMod.SSEClientTransport,
     WebSocketClientTransport: wsMod.WebSocketClientTransport,
+    JSONRPCMessageSchema: typesMod.JSONRPCMessageSchema,
     ListRootsRequestSchema: typesMod.ListRootsRequestSchema,
     ToolListChangedNotificationSchema: typesMod.ToolListChangedNotificationSchema,
   }));
@@ -163,8 +180,8 @@ function mcpFeatureTools(serverName, capabilities, protocolTools) {
   const tools = [];
   const used = new Set(protocolTools.map((tool) => tool.name));
   const add = (leaf, description, properties, required, operation) => {
-    let name = `mcp__${serverName}__${leaf}`;
-    while (used.has(name)) name += '_';
+    let name = providerSafeMcpToolName(serverName, leaf);
+    for (let suffix = '_'; used.has(name); suffix += '_') name = providerSafeMcpToolName(serverName, leaf + suffix);
     used.add(name);
     tools.push({
       name,
@@ -238,6 +255,7 @@ export function getMcpServerStatus(scopeId = DEFAULT_MCP_SCOPE_ID) {
           ),
         }
       : {}),
+    warnings: Array.isArray(server.warnings) ? server.warnings : [],
     toolCount: Array.isArray(server.tools) ? server.tools.length : 0,
     tools: (server.tools || []).map((tool) => ({
       name: tool.name,
@@ -409,11 +427,12 @@ export async function reconnectSingleMcpServer(scopeId, name, cfg = undefined) {
 export async function executeMcpTool(name, args, options = {}) {
   const match = name.match(MCP_TOOL_NAME_RE);
   if (!match) throw new Error(`Not an MCP tool name: ${name}`);
-  const [, serverName, toolName] = match;
   const scopeId = normalizeMcpScopeId(options);
-  const server = scopedServer(scopeId, serverName);
-  if (!server) throw new Error(`MCP server "${serverName}" not connected`);
-  const definition = (server.tools || []).find((tool) => tool.name === name);
+  const target = resolveMcpToolTarget(scopeId, name);
+  if (!target) throw new Error(`MCP server "${match[1]}" not connected`);
+  const { server, definition } = target;
+  const serverName = server.name;
+  const toolName = definition?.mcpToolName || match[2];
   const callSignal = options?.signal || null;
   const dispatch = (target) =>
     definition?.mcpOperation
@@ -1022,12 +1041,7 @@ export function isMcpTool(name) {
 }
 /** True when the prefixed name exists on a connected MCP server. */
 export function isRegisteredMcpTool(name, scopeId = DEFAULT_MCP_SCOPE_ID) {
-  const match = name.match(MCP_TOOL_NAME_RE);
-  if (!match) return false;
-  const [, serverName] = match;
-  const server = scopedServer(scopeId, serverName);
-  if (!server || !Array.isArray(server.tools)) return false;
-  return server.tools.some((t) => t?.name === name);
+  return Boolean(resolveMcpToolTarget(scopeId, name)?.definition);
 }
 /**
  * Check whether the inputSchema for an MCP tool declares the given top-level
@@ -1040,9 +1054,7 @@ export function mcpToolHasField(name, field, scopeId = DEFAULT_MCP_SCOPE_ID) {
   const memoKey = `${normalizedScopeId}|${name}|${field}`;
   const memoized = _mcpToolFieldMemo.get(memoKey);
   if (memoized !== undefined) return memoized;
-  const match = name.match(MCP_TOOL_NAME_RE);
-  const server = match ? scopedServer(normalizedScopeId, match[1]) : null;
-  const tool = server ? server.tools.find((t) => t.name === name) : null;
+  const tool = resolveMcpToolTarget(normalizedScopeId, name)?.definition;
   const props = tool?.inputSchema?.properties;
   const result = Boolean(props && Object.hasOwn(props, field));
   _mcpToolFieldMemo.set(memoKey, result);
@@ -1163,8 +1175,14 @@ async function connectServer(
     // abort before creating a transport/child at all.
     throw new Error(`MCP server "${name}" connect aborted by shutdown`);
   }
-  const client = createMcpClient(sdk, name, cfg);
-  const { transport, autoDetectAdvert, stderrTail } = createMcpTransport({ name, cfg, sdk, log: mcpLog });
+  const client = createMcpClient(sdk, name, cfg, scopeId);
+  const { transport, autoDetectAdvert, stderrTail, warnings } = createMcpTransport({
+    name,
+    cfg,
+    sdk,
+    log: mcpLog,
+    strictEnv: cfg?._mixdogStrictEnv === true,
+  });
   const liveness = trackMcpLiveness(client, name, cfg, stderrTail);
   const pending = { scopeId, name, client, transport };
   _pendingConnects.add(pending);
@@ -1195,7 +1213,7 @@ async function connectServer(
       }
       throw new Error(`MCP server "${name}" connect aborted by shutdown`);
     }
-    const tools = mcpServerTools(name, capabilities, toolsResult.tools);
+    const tools = mcpServerTools(name, capabilities, toolsResult.tools, cfg);
     const registryKey = mcpServerRegistryKey(scopeId, name);
     servers.set(registryKey, {
       scopeId,
@@ -1209,6 +1227,7 @@ async function connectServer(
       capabilities,
       liveness,
       stderrTail,
+      warnings: warnings || [],
       generation: genAtStart,
     });
     if (capabilities?.tools?.listChanged && sdk.ToolListChangedNotificationSchema) {
@@ -1250,16 +1269,25 @@ function trackMcpLiveness(client, name, cfg, stderrTail) {
   return liveness;
 }
 
-/** The SDK client for one server, advertising the project root when known. */
-function createMcpClient(sdk, name, cfg) {
-  const projectRoot = String(cfg?._mixdogProjectRoot || cfg?.cwd || '').trim();
+/** The SDK client for one server, advertising the project root when known.
+ *  A config marked `_mixdogRootsFollowScope` advertises its scope's current
+ *  root (setMcpScopeRoot) and is told when it changes. */
+function createMcpClient(sdk, name, cfg, scopeId = DEFAULT_MCP_SCOPE_ID) {
+  const followScope = cfg?._mixdogRootsFollowScope === true;
+  const fixedRoot = String(cfg?._mixdogProjectRoot || cfg?.cwd || '').trim();
+  const currentRoot = () => (followScope ? _scopeRoots.get(normalizeMcpScopeId(scopeId)) || fixedRoot : fixedRoot);
   const client = new sdk.Client(
     { name: `mixdog-agent/${name}`, version: '1.0.0' },
-    { capabilities: projectRoot ? { roots: { listChanged: false } } : {} }
+    {
+      capabilities: followScope || fixedRoot ? { roots: { listChanged: followScope } } : {},
+      jsonSchemaValidator: createLazyOutputValidator(sdk.AjvJsonSchemaValidator),
+    }
   );
-  if (projectRoot && sdk.ListRootsRequestSchema) {
+  if ((followScope || fixedRoot) && sdk.ListRootsRequestSchema) {
     client.setRequestHandler(sdk.ListRootsRequestSchema, async () => {
-      const rootPath = resolve(projectRoot);
+      const root = currentRoot();
+      if (!root) return { roots: [] };
+      const rootPath = resolve(root);
       return {
         roots: [
           {
@@ -1273,15 +1301,62 @@ function createMcpClient(sdk, name, cfg) {
   return client;
 }
 
-/** Protocol tools under the `mcp__<server>__` prefix plus the feature tools. */
-function mcpServerTools(name, capabilities, rawTools) {
-  const protocolTools = (rawTools || []).map((t) => ({
-    name: `mcp__${name}__${t.name}`,
-    description: t.description || '',
-    inputSchema: t.inputSchema || { type: 'object', properties: {} },
-    ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
-  }));
-  return [...protocolTools, ...mcpFeatureTools(name, capabilities, protocolTools)];
+/**
+ * Set the root advertised by `scopeId`'s scope-following servers (plugin
+ * servers, whose roots track the session cwd) and notify the connected ones
+ * when it changed. No reconnect: the connection and its tools stay as they are.
+ */
+export function setMcpScopeRoot(scopeId, root) {
+  const normalized = normalizeMcpScopeId(scopeId);
+  const next = String(root || '').trim();
+  if ((_scopeRoots.get(normalized) || '') === next) return;
+  if (next) _scopeRoots.set(normalized, next);
+  else _scopeRoots.delete(normalized);
+  for (const [, server] of scopedServerEntries(normalized)) {
+    if (server.cfg?._mixdogRootsFollowScope !== true) continue;
+    Promise.resolve()
+      .then(() => server.client?.sendRootsListChanged?.())
+      .catch(() => {});
+  }
+}
+
+/** The connected server and tool definition a prefixed tool name refers to.
+ *  The name's server part finds it directly; a name shortened to fit provider
+ *  limits is found by scanning this scope's servers. A known server without
+ *  the tool still resolves (definition null) so the call reaches the server. */
+function resolveMcpToolTarget(scopeId, name) {
+  const match = MCP_TOOL_NAME_RE.exec(String(name || ''));
+  if (!match) return null;
+  const direct = scopedServer(scopeId, match[1]);
+  const directTool = direct?.tools?.find((tool) => tool.name === name);
+  if (directTool) return { server: direct, definition: directTool };
+  for (const [, server] of scopedServerEntries(scopeId)) {
+    const definition = server.tools?.find((tool) => tool.name === name);
+    if (definition) return { server, definition };
+  }
+  return direct ? { server: direct, definition: null } : null;
+}
+
+/** Protocol tools under the `mcp__<server>__` prefix plus the feature tools.
+ *  Names that would exceed provider limits are shortened deterministically
+ *  (`providerSafeMcpToolName`); a tool whose name was shortened carries the
+ *  server's own tool name as `mcpToolName` and its server as `mcpServerName`.
+ *  A plugin-declared server's tools carry its owner as `mcpPluginId`, so
+ *  scope filtering never has to infer ownership from the server name. */
+function mcpServerTools(name, capabilities, rawTools, cfg) {
+  const protocolTools = (rawTools || []).map((t) => {
+    const safeName = providerSafeMcpToolName(name, t.name);
+    return {
+      name: safeName,
+      ...(safeName === `mcp__${name}__${t.name}` ? {} : { mcpToolName: t.name, mcpServerName: name }),
+      description: t.description || '',
+      inputSchema: t.inputSchema || { type: 'object', properties: {} },
+      ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
+    };
+  });
+  const tools = [...protocolTools, ...mcpFeatureTools(name, capabilities, protocolTools)];
+  const pluginId = String(cfg?._mixdogPlugin?.id || '').trim();
+  return pluginId ? tools.map((tool) => ({ ...tool, mcpPluginId: pluginId })) : tools;
 }
 
 // tools/list_changed refreshes run one at a time per server connection, so an
@@ -1304,7 +1379,7 @@ async function runToolRefresh(registryKey, live, name, cfg, capabilities) {
       throw new Error('ListTools returned invalid shape: missing or non-array tools field');
     }
     if (servers.get(registryKey) !== live) return;
-    live.tools = mcpServerTools(name, capabilities, refreshed.tools);
+    live.tools = mcpServerTools(name, capabilities, refreshed.tools, cfg);
     _invalidateMcpToolFieldMemo();
   } catch (error) {
     mcpLog(
@@ -1317,19 +1392,28 @@ async function runToolRefresh(registryKey, live, name, cfg, capabilities) {
 export function _registerMcpServerForTest(scopeId, name, rawTools = [], options = {}) {
   const normalizedScopeId = normalizeMcpScopeId(scopeId);
   const registryKey = mcpServerRegistryKey(normalizedScopeId, name);
-  const tools = rawTools.map((tool) => ({
-    ...tool,
-    name: String(tool?.name || '').startsWith('mcp__')
-      ? String(tool.name)
-      : `mcp__${name}__${String(tool?.name || '')}`,
-    inputSchema: tool?.inputSchema || { type: 'object', properties: {} },
-  }));
+  const tools = rawTools.map((tool) => {
+    const prefixed = String(tool?.name || '').startsWith('mcp__');
+    const leaf = String(tool?.name || '');
+    const safeName = prefixed ? leaf : providerSafeMcpToolName(name, leaf);
+    const shortened = !prefixed && safeName !== `mcp__${name}__${leaf}`;
+    return {
+      ...tool,
+      name: safeName,
+      ...(shortened ? { mcpToolName: leaf, mcpServerName: name } : {}),
+      inputSchema: tool?.inputSchema || { type: 'object', properties: {} },
+    };
+  });
   const capabilities = options.capabilities || {};
+  const pluginId = String(options.cfg?._mixdogPlugin?.id || '').trim();
   const server = {
     scopeId: normalizedScopeId,
     registryKey,
     name,
-    tools: [...tools, ...mcpFeatureTools(name, capabilities, tools)],
+    tools: [...tools, ...mcpFeatureTools(name, capabilities, tools)].map((tool) =>
+      pluginId ? { ...tool, mcpPluginId: pluginId } : tool
+    ),
+    warnings: options.warnings || [],
     cfg: options.cfg || {},
     instructions: options.instructions || '',
     capabilities,

package/src/runtime/agent/orchestrator/mcp/lazy-output-validator.mjs

@@ -0,0 +1,25 @@
+// The MCP SDK Client compiles every tool's outputSchema with Ajv inside
+// listTools(), synchronously: a server listing ~180 tools held the daemon's
+// event loop for 1-2 s on every connect. This validator compiles each schema
+// on the tool's first structured result instead, and creates the SDK's Ajv
+// validator (same options and error text) on first use too.
+// A schema declaring an `$id` anywhere registers it in the client's Ajv, and a
+// schema referencing anything outside itself resolves against what is
+// registered by then (failing the listing when it is not); both still compile
+// when listed, in listing order, exactly as the SDK does.
+const LISTING_ORDER_SCHEMA = /"\$id"|"\$ref":"(?!#)/;
+
+export function createLazyOutputValidator(AjvJsonSchemaValidator) {
+  let provider = null;
+  const shared = () => (provider ??= new AjvJsonSchemaValidator());
+  return {
+    getValidator(schema) {
+      if (LISTING_ORDER_SCHEMA.test(JSON.stringify(schema))) return shared().getValidator(schema);
+      let validate = null;
+      return (input) => {
+        validate ??= shared().getValidator(schema);
+        return validate(input);
+      };
+    },
+  };
+}

package/src/runtime/agent/orchestrator/mcp/plugin-placeholders.mjs

@@ -0,0 +1,54 @@
+/**
+ * mcp/plugin-placeholders.mjs — plugin root/data placeholders in an MCP server
+ * config. Pure: no filesystem access; the caller supplies the directories.
+ */
+
+const ROOT_NAMES = ['CLAUDE_PLUGIN_ROOT', 'CODEX_PLUGIN_ROOT', 'PLUGIN_ROOT', 'MIXDOG_PLUGIN_ROOT'];
+const DATA_NAMES = ['CLAUDE_PLUGIN_DATA', 'PLUGIN_DATA', 'MIXDOG_PLUGIN_DATA'];
+const PLACEHOLDER_RE = new RegExp(`\\$\\{(${[...ROOT_NAMES, ...DATA_NAMES].join('|')})\\}`, 'g');
+const CONFIG_FIELDS = ['command', 'args', 'env', 'url', 'headers', 'cwd'];
+
+// Substituted paths use forward slashes on Windows so a path that lands in a
+// command line or argument is not read as backslash escapes; Windows accepts
+// them everywhere.
+function normalizePath(path, platform) {
+  return platform === 'win32' ? path.replace(/\\/g, '/') : path;
+}
+
+function substitute(value, replacements) {
+  if (typeof value === 'string') {
+    // Function replacement: `$` sequences in paths are inserted literally.
+    return value.replace(PLACEHOLDER_RE, (match, name) => replacements.get(name) ?? match);
+  }
+  if (Array.isArray(value)) return value.map((v) => substitute(v, replacements));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = substitute(v, replacements);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Returns a copy of `config` with plugin root/data placeholders replaced in
+ * command, args, env, url, headers and cwd. A placeholder whose directory is
+ * not supplied is left as written. Run before ordinary env expansion.
+ */
+export function resolvePluginPlaceholders(config, { root, data, platform = process.platform } = {}) {
+  const replacements = new Map();
+  if (root) for (const name of ROOT_NAMES) replacements.set(name, normalizePath(String(root), platform));
+  if (data) for (const name of DATA_NAMES) replacements.set(name, normalizePath(String(data), platform));
+  const out = { ...config };
+  for (const field of CONFIG_FIELDS) {
+    if (out[field] !== undefined) out[field] = substitute(out[field], replacements);
+  }
+  return out;
+}
+
+/** Environment variables a plugin-owned server process receives (raw paths). */
+export function pluginServerEnv({ root, data } = {}) {
+  const env = {};
+  if (root) for (const name of ['CLAUDE_PLUGIN_ROOT', 'MIXDOG_PLUGIN_ROOT', 'PLUGIN_ROOT']) env[name] = String(root);
+  if (data) for (const name of ['CLAUDE_PLUGIN_DATA', 'MIXDOG_PLUGIN_DATA', 'PLUGIN_DATA']) env[name] = String(data);
+  return env;
+}