mcp-stdio-guard 0.3.0 → 0.4.0

package/src/index.js

@@ -6,17 +6,36 @@ import { spawn, spawnSync } from 'node:child_process';
 function loadVersion() {
   try {
     const packageJson = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-    return typeof packageJson.version === 'string' ? packageJson.version : '0.3.0';
+    return typeof packageJson.version === 'string' ? packageJson.version : '0.4.0';
   } catch {
-    return '0.3.0';
+    return '0.4.0';
   }
 }
 
 const DEFAULT_PROTOCOL = '2025-11-25';
 const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_PROFILE = 'custom';
 const VERSION = loadVersion();
 const JSON_SCHEMA_VERSION = 1;
 const REDACTED = '<redacted>';
+const GUARD_PROFILES = Object.freeze({
+  custom: {
+    description: 'preserve explicit CLI flags and legacy defaults'
+  },
+  smoke: {
+    description: 'initialize only; skip advertised capability list probes'
+  },
+  registry: {
+    description: 'initialize, advertised list probes, fingerprint, and repeat consistency'
+  },
+  ci: {
+    description: 'stable JSON output with static findings treated as failures when scanned'
+  },
+  strict: {
+    description: 'deep deterministic checks; reserved for opt-in adversarial probes'
+  }
+});
+const GUARD_PROFILE_NAMES = Object.keys(GUARD_PROFILES);
 const VERSION_PROBE_CACHE = new Map();
 const NODE_OPTIONS_WITH_VALUES = new Set([
   '--conditions',
@@ -70,6 +89,23 @@ const JSON_RPC_ISSUE_CODES = new Set([
   'stdout-invalid-json-rpc',
   'stdout-unexpected-request-id'
 ]);
+const CAPABILITY_DEFINITIONS = Object.freeze([
+  { name: 'tools', method: 'tools/list' },
+  { name: 'resources', method: 'resources/list' },
+  { name: 'prompts', method: 'prompts/list' }
+]);
+const CAPABILITY_ISSUE_CODES = new Set([
+  'capability-list-error',
+  'capability-list-missing-response',
+  'capability-list-timeout',
+  'capability-list-unsupported'
+]);
+const REPEAT_DRIFT_ISSUE_CODES = new Set([
+  'repeat-capability-drift',
+  'repeat-list-shape-drift',
+  'repeat-protocol-drift',
+  'repeat-tool-drift'
+]);
 const INITIALIZE_ISSUE_CODES = new Set([
   'initialize-error',
   'initialize-invalid-capabilities',
@@ -88,6 +124,15 @@ const OPERATION_ISSUE_CODES = new Set([
   'operation-missing-response',
   'operation-timeout'
 ]);
+const TOOL_SCHEMA_ISSUE_CODES = new Set([
+  'tool-description-missing',
+  'tool-input-schema-invalid',
+  'tool-input-schema-required-missing',
+  'tool-name-duplicate',
+  'tool-name-invalid',
+  'tools-list-invalid-result'
+]);
+const JSON_SCHEMA_TYPES = new Set(['array', 'boolean', 'integer', 'null', 'number', 'object', 'string']);
 const PROCESS_ISSUE_CODES = new Set([
   'server-crashed',
   'server-exited',
@@ -117,6 +162,20 @@ const ISSUE_CLASS_BY_CODE = new Map([
   ['initialize-missing-protocol-version', ISSUE_CLASSES.MCP_PROTOCOL],
   ['initialize-missing-server-info', ISSUE_CLASSES.MCP_PROTOCOL],
   ['operation-error', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['capability-list-error', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['capability-list-missing-response', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['capability-list-timeout', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['capability-list-unsupported', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['repeat-capability-drift', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['repeat-list-shape-drift', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['repeat-protocol-drift', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['repeat-tool-drift', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['tool-description-missing', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['tool-input-schema-invalid', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['tool-input-schema-required-missing', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['tool-name-duplicate', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['tool-name-invalid', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['tools-list-invalid-result', ISSUE_CLASSES.MCP_PROTOCOL],
   ['notification-response', ISSUE_CLASSES.MCP_PROTOCOL],
   ['response-id-mismatch', ISSUE_CLASSES.MCP_PROTOCOL],
   ['response-id-type-mismatch', ISSUE_CLASSES.MCP_PROTOCOL],
@@ -142,13 +201,18 @@ export async function runCli(argv) {
   }
 
   const guardOptions = {
+    config: options.config,
+    profile: options.profile,
     protocol: options.protocol,
     timeoutMs: options.timeoutMs,
     cwd: options.cwd,
-    operation: options.requestMethod
+    env: options.env,
+    probeCapabilities: options.probeCapabilities,
+    operations: options.operations,
+    operation: options.operations.length === 1
       ? {
-          method: options.requestMethod,
-          params: options.requestParams
+          method: options.operations[0].method,
+          params: options.operations[0].params
         }
       : null
   };
@@ -194,8 +258,15 @@ export async function runCli(argv) {
 export function parseArgs(argv) {
   const options = {
     command: [],
+    configPath: '',
+    config: defaultConfigMetadata(),
+    env: {},
+    operations: [],
+    configOperations: [],
     protocol: DEFAULT_PROTOCOL,
     timeoutMs: DEFAULT_TIMEOUT,
+    profile: DEFAULT_PROFILE,
+    probeCapabilities: true,
     scanPath: '',
     failOnStatic: false,
     requestMethod: '',
@@ -206,12 +277,14 @@ export function parseArgs(argv) {
     version: false,
     cwd: process.cwd()
   };
+  const specifiedOptions = new Set();
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
 
     if (arg === '--') {
       options.command = argv.slice(index + 1);
+      specifiedOptions.add('command');
       break;
     }
 
@@ -221,34 +294,61 @@ export function parseArgs(argv) {
       options.version = true;
     } else if (arg === '--json') {
       options.json = true;
+      specifiedOptions.add('json');
+    } else if (arg === '--config') {
+      options.configPath = path.resolve(readOptionValue(argv, index, arg));
+      specifiedOptions.add('configPath');
+      index += 1;
+    } else if (arg === '--profile') {
+      options.profile = readOptionValue(argv, index, arg);
+      specifiedOptions.add('profile');
+      index += 1;
     } else if (arg === '--fail-on-static') {
       options.failOnStatic = true;
+      specifiedOptions.add('failOnStatic');
     } else if (arg === '--request') {
       options.requestMethod = readOptionValue(argv, index, arg);
+      specifiedOptions.add('requestMethod');
       index += 1;
     } else if (arg === '--params') {
       options.requestParams = parseJsonOption(readOptionValue(argv, index, arg), arg);
+      specifiedOptions.add('requestParams');
       index += 1;
     } else if (arg === '--protocol') {
       options.protocol = readOptionValue(argv, index, arg);
+      specifiedOptions.add('protocol');
       index += 1;
     } else if (arg === '--timeout') {
       options.timeoutMs = Number(readOptionValue(argv, index, arg));
+      specifiedOptions.add('timeoutMs');
       index += 1;
     } else if (arg === '--repeat') {
       options.repeat = Number(readOptionValue(argv, index, arg));
+      specifiedOptions.add('repeat');
       index += 1;
     } else if (arg === '--scan') {
       options.scanPath = path.resolve(readOptionValue(argv, index, arg));
+      specifiedOptions.add('scanPath');
       index += 1;
     } else if (arg === '--cwd') {
       options.cwd = path.resolve(readOptionValue(argv, index, arg));
+      specifiedOptions.add('cwd');
       index += 1;
     } else {
       throw new Error(`Unknown option before --: ${arg}`);
     }
   }
 
+  if (options.help || options.version) {
+    return options;
+  }
+
+  if (options.configPath) {
+    applyConfigFile(options, loadConfigFile(options.configPath), specifiedOptions);
+  }
+  applyProfileDefaults(options, specifiedOptions);
+  options.operations = buildConfiguredOperations(options);
+
   if (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 100) {
     throw new Error('--timeout must be an integer >= 100');
   }
@@ -264,6 +364,275 @@ export function parseArgs(argv) {
   return options;
 }
 
+function applyProfileDefaults(options, specifiedOptions) {
+  if (!GUARD_PROFILE_NAMES.includes(options.profile)) {
+    throw new Error(`--profile must be one of: ${GUARD_PROFILE_NAMES.join(', ')}`);
+  }
+
+  if (options.profile === 'smoke') {
+    options.probeCapabilities = false;
+    return options;
+  }
+
+  options.probeCapabilities = true;
+
+  if (options.profile === 'registry' && !specifiedOptions.has('repeat')) {
+    options.repeat = 2;
+  }
+
+  if (options.profile === 'ci') {
+    options.json = true;
+    options.failOnStatic = true;
+  }
+
+  if (options.profile === 'strict') {
+    options.json = true;
+    options.failOnStatic = true;
+    if (!specifiedOptions.has('repeat')) {
+      options.repeat = 2;
+    }
+  }
+
+  return options;
+}
+
+function loadConfigFile(configPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, 'utf8');
+  } catch (error) {
+    throw new Error(`Failed to read --config ${configPath}: ${error.message}`);
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isObjectRecord(parsed)) {
+      throw new Error('top-level value must be an object');
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`--config ${configPath} must be valid JSON: ${error.message}`);
+  }
+}
+
+function applyConfigFile(options, config, specifiedOptions) {
+  const configDir = path.dirname(options.configPath);
+  const command = normalizeConfigCommand(config);
+  const env = normalizeConfigEnv(config);
+  const requests = normalizeConfigRequests(config);
+  const safeToolCalls = normalizeSafeToolCalls(config);
+  const usesConfigCommand = command.length > 0 && !specifiedOptions.has('command');
+  const usesConfigCwd = typeof config.cwd === 'string' && !specifiedOptions.has('cwd');
+  const usesConfigOperations = !specifiedOptions.has('requestMethod') && !specifiedOptions.has('requestParams');
+
+  if (usesConfigCommand) {
+    options.command = command;
+  }
+
+  if (usesConfigCwd) {
+    options.cwd = resolveConfigPath(config.cwd, configDir);
+  } else if (config.cwd !== undefined && typeof config.cwd !== 'string') {
+    throw new Error('--config cwd must be a string');
+  }
+
+  if (config.protocol !== undefined && !specifiedOptions.has('protocol')) {
+    if (typeof config.protocol !== 'string' || !config.protocol) {
+      throw new Error('--config protocol must be a non-empty string');
+    }
+    options.protocol = config.protocol;
+  }
+
+  const timeoutField = Object.hasOwn(config, 'timeoutMs') ? 'timeoutMs' : 'timeout';
+  const timeoutValue = config[timeoutField];
+  if (timeoutValue !== undefined && !specifiedOptions.has('timeoutMs')) {
+    options.timeoutMs = normalizeConfigInteger(timeoutValue, timeoutField, 100);
+  }
+
+  if (config.repeat !== undefined && !specifiedOptions.has('repeat')) {
+    options.repeat = normalizeConfigInteger(config.repeat, 'repeat', 1);
+  }
+
+  if (config.profile !== undefined && !specifiedOptions.has('profile')) {
+    if (typeof config.profile !== 'string') {
+      throw new Error('--config profile must be a string');
+    }
+    options.profile = config.profile;
+  }
+
+  if (config.json !== undefined && !specifiedOptions.has('json')) {
+    if (typeof config.json !== 'boolean') {
+      throw new Error('--config json must be a boolean');
+    }
+    options.json = config.json;
+  }
+
+  const scanPath = config.scanPath ?? config.scan;
+  if (scanPath !== undefined && !specifiedOptions.has('scanPath')) {
+    if (typeof scanPath !== 'string') {
+      throw new Error('--config scan must be a string path');
+    }
+    options.scanPath = resolveConfigPath(scanPath, configDir);
+  }
+
+  if (config.failOnStatic !== undefined && !specifiedOptions.has('failOnStatic')) {
+    if (typeof config.failOnStatic !== 'boolean') {
+      throw new Error('--config failOnStatic must be a boolean');
+    }
+    options.failOnStatic = config.failOnStatic;
+  }
+
+  if (Object.keys(env).length) {
+    options.env = { ...env, ...options.env };
+  }
+
+  if (usesConfigOperations) {
+    options.configOperations = [...requests, ...safeToolCalls];
+  }
+
+  options.config = {
+    enabled: true,
+    path: options.configPath,
+    resolvedPath: options.configPath,
+    checks: {
+      command: usesConfigCommand,
+      cwd: usesConfigCwd,
+      envNames: Object.keys(env).sort(),
+      requests: usesConfigOperations ? requests.map((request) => request.method) : [],
+      safeToolCalls: usesConfigOperations ? safeToolCalls.map((request) => request.safeToolCallName) : []
+    }
+  };
+}
+
+function normalizeConfigCommand(config) {
+  if (config.command === undefined && config.args === undefined) return [];
+
+  if (Array.isArray(config.command)) {
+    if (!config.command.every((entry) => typeof entry === 'string' && entry)) {
+      throw new Error('--config command array entries must be non-empty strings');
+    }
+    if (config.args !== undefined) {
+      throw new Error('--config args cannot be used when command is an array');
+    }
+    return config.command;
+  }
+
+  if (typeof config.command === 'string' && config.command) {
+    const args = config.args ?? [];
+    if (!Array.isArray(args) || !args.every((entry) => typeof entry === 'string')) {
+      throw new Error('--config args must be an array of strings');
+    }
+    return [config.command, ...args];
+  }
+
+  throw new Error('--config command must be a non-empty string or array of strings');
+}
+
+function normalizeConfigEnv(config) {
+  if (config.env === undefined) return {};
+  if (!isObjectRecord(config.env)) {
+    throw new Error('--config env must be an object');
+  }
+
+  return Object.fromEntries(Object.entries(config.env).map(([name, value]) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      throw new Error(`--config env contains invalid variable name: ${name}`);
+    }
+    if (!['string', 'number', 'boolean'].includes(typeof value)) {
+      throw new Error(`--config env.${name} must be a string, number, or boolean`);
+    }
+    return [name, String(value)];
+  }));
+}
+
+function normalizeConfigInteger(value, field, minimum) {
+  const normalized = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+  if (!Number.isInteger(normalized) || normalized < minimum) {
+    throw new Error(`--config ${field} must be an integer >= ${minimum}`);
+  }
+  return normalized;
+}
+
+function normalizeConfigRequests(config) {
+  const values = [];
+  if (config.request !== undefined) {
+    values.push(config.request);
+  }
+  if (config.requests !== undefined) {
+    if (!Array.isArray(config.requests)) {
+      throw new Error('--config requests must be an array');
+    }
+    values.push(...config.requests);
+  }
+
+  return values.map((request, index) => {
+    if (!isObjectRecord(request)) {
+      throw new Error(`--config requests[${index}] must be an object`);
+    }
+    if (typeof request.method !== 'string' || !request.method) {
+      throw new Error(`--config requests[${index}].method must be a non-empty string`);
+    }
+    return {
+      source: 'config-request',
+      method: request.method,
+      params: request.params
+    };
+  });
+}
+
+function normalizeSafeToolCalls(config) {
+  if (config.safeToolCalls === undefined) return [];
+  if (!Array.isArray(config.safeToolCalls)) {
+    throw new Error('--config safeToolCalls must be an array');
+  }
+
+  return config.safeToolCalls.map((call, index) => {
+    if (!isObjectRecord(call)) {
+      throw new Error(`--config safeToolCalls[${index}] must be an object`);
+    }
+    if (typeof call.name !== 'string' || !call.name) {
+      throw new Error(`--config safeToolCalls[${index}].name must be a non-empty string`);
+    }
+    const argumentsValue = call.arguments ?? {};
+    if (!isObjectRecord(argumentsValue)) {
+      throw new Error(`--config safeToolCalls[${index}].arguments must be an object`);
+    }
+    return {
+      source: 'safe-tool-call',
+      method: 'tools/call',
+      params: {
+        name: call.name,
+        arguments: argumentsValue
+      },
+      safeToolCallName: call.name
+    };
+  });
+}
+
+function buildConfiguredOperations(options) {
+  if (options.requestMethod) {
+    return [{
+      source: 'cli-request',
+      method: options.requestMethod,
+      params: options.requestParams
+    }];
+  }
+
+  return options.configOperations;
+}
+
+function normalizeGuardOperations(operations) {
+  return operations.map((operation) => ({
+    source: operation.source ?? 'request',
+    method: operation.method,
+    params: operation.params,
+    safeToolCallName: operation.safeToolCallName ?? ''
+  }));
+}
+
+function resolveConfigPath(value, configDir) {
+  return path.resolve(configDir, value);
+}
+
 export async function guardRepeatedStdioServer(commandWithArgs, options = {}) {
   const startedAt = Date.now();
   const repeat = options.repeat ?? 1;
@@ -285,18 +654,28 @@ export async function guardRepeatedStdioServer(commandWithArgs, options = {}) {
     }
   }
 
+  const drift = buildRepeatDrift(runs);
+  for (const issue of repeatDriftIssues(drift)) {
+    issues.push(issue);
+  }
+
   const durationMs = Date.now() - startedAt;
   const result = {
     schemaVersion: JSON_SCHEMA_VERSION,
     ok: !issues.some((issue) => issue.severity === 'error'),
+    profile: options.profile ?? DEFAULT_PROFILE,
     command: commandWithArgs,
+    config: options.config ?? defaultConfigMetadata(),
     protocol: options.protocol ?? DEFAULT_PROTOCOL,
     repeat,
     runs,
     issues,
     checks: {},
+    capabilityProbes: options.probeCapabilities ?? true,
+    drift,
     staticScan: defaultStaticScan(),
     staticFindings: [],
+    toolSchema: aggregateRunToolSchemaValidation(runs),
     durationMs,
     fingerprint: createFingerprint(commandWithArgs, options)
   };
@@ -310,7 +689,8 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
   const args = commandWithArgs.slice(1);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT;
   const protocol = options.protocol ?? DEFAULT_PROTOCOL;
-  const operation = options.operation || null;
+  const operations = normalizeGuardOperations(options.operations ?? (options.operation ? [options.operation] : []));
+  const probeCapabilities = options.probeCapabilities ?? true;
   const env = { ...process.env, ...(options.env ?? {}) };
   const issues = [];
   const frames = [];
@@ -319,36 +699,58 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
   let initialized = false;
   let endedByGuard = false;
   let initializeResponseAt = 0;
+  let currentRequest = null;
+  let requestQueue = [];
+  let nextRequestId = 2;
   let timer;
   let child;
 
   const result = {
     schemaVersion: JSON_SCHEMA_VERSION,
     ok: false,
+    profile: options.profile ?? DEFAULT_PROFILE,
     command: commandWithArgs,
+    config: options.config ?? defaultConfigMetadata(),
     protocol,
     negotiatedProtocol: '',
     initialized: false,
-    operation: operation
+    operation: operations.length === 1
       ? {
-          method: operation.method,
+          method: operations[0].method,
+          source: operations[0].source,
+          safeToolCallName: operations[0].safeToolCallName,
           responded: false,
           error: null
         }
       : null,
+    operations: operations.map((operation, index) => ({
+      index,
+      source: operation.source,
+      method: operation.method,
+      safeToolCallName: operation.safeToolCallName,
+      responded: false,
+      error: null
+    })),
     frames,
     issues,
     checks: {},
+    capabilityProbes: probeCapabilities,
+    capabilityKeys: [],
+    capabilityChecks: defaultCapabilityChecks(),
     stderr: '',
     process: defaultProcessInfo(timeoutMs),
     staticScan: defaultStaticScan(),
     staticFindings: [],
+    toolSchema: defaultToolSchemaValidation(),
     durationMs: 0,
     fingerprint: createFingerprint(commandWithArgs, {
       protocol,
       timeoutMs,
       cwd: options.cwd,
-      operation,
+      config: options.config,
+      profile: options.profile,
+      probeCapabilities,
+      operations,
       env: options.env
     })
   };
@@ -358,7 +760,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       issues.push({ ...details, severity, code, message });
     }
 
-    function armTimeout(code, message, timeoutPhase) {
+    function armTimeout(code, message, timeoutPhase, details = {}) {
       clearTimeout(timer);
       result.process.phase = timeoutPhase;
       timer = setTimeout(() => {
@@ -366,7 +768,10 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
         result.process.timeoutCode = code;
         result.process.timeoutMs = timeoutMs;
         result.process.outcome = 'timeout';
-        addIssue('error', code, message, timeoutIssueDetails(code, timeoutMs, timeoutPhase));
+        addIssue('error', code, message, {
+          ...timeoutIssueDetails(code, timeoutMs, timeoutPhase),
+          ...details
+        });
         finish();
       }, timeoutMs);
     }
@@ -406,6 +811,162 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       child.stdin.write(`${JSON.stringify(message)}\n`);
     }
 
+    function enqueueRequest(request) {
+      requestQueue.push({
+        ...request,
+        id: nextRequestId
+      });
+      nextRequestId += 1;
+    }
+
+    function startNextRequest() {
+      if (result.durationMs || currentRequest) return;
+      currentRequest = requestQueue.shift() || null;
+      if (!currentRequest) {
+        result.process.phase = 'post-initialize';
+        finishSoon();
+        return;
+      }
+
+      result.process.phase = 'operation';
+      const request = {
+        jsonrpc: '2.0',
+        id: currentRequest.id,
+        method: currentRequest.method
+      };
+      if (currentRequest.params !== undefined) {
+        request.params = currentRequest.params;
+      }
+      send(request);
+      armTimeout(
+        currentRequest.timeoutCode,
+        currentRequest.timeoutMessage,
+        'operation',
+        currentRequest.timeoutDetails
+      );
+    }
+
+    function configureCapabilityChecks(capabilities) {
+      result.capabilityKeys = capabilityKeys(capabilities);
+      for (const definition of CAPABILITY_DEFINITIONS) {
+        const check = result.capabilityChecks[definition.name];
+        check.advertised = result.capabilityKeys.includes(definition.name);
+      }
+    }
+
+    function enqueuePostInitializeRequests() {
+      const operationCapabilities = new Set(operations.map((operation) => capabilityNameForMethod(operation.method)).filter(Boolean));
+      for (let operationIndex = 0; operationIndex < operations.length; operationIndex += 1) {
+        const operation = operations[operationIndex];
+        const operationCapability = capabilityNameForMethod(operation.method);
+        enqueueRequest({
+          kind: 'operation',
+          operationIndex,
+          capability: result.capabilityChecks[operationCapability]?.advertised ? operationCapability : '',
+          method: operation.method,
+          params: operation.params,
+          timeoutCode: 'operation-timeout',
+          timeoutMessage: `no ${operation.method} response within ${timeoutMs}ms`,
+          timeoutDetails: {}
+        });
+      }
+
+      if (!probeCapabilities) return;
+
+      for (const definition of CAPABILITY_DEFINITIONS) {
+        const check = result.capabilityChecks[definition.name];
+        if (!check.advertised || operationCapabilities.has(definition.name)) continue;
+        enqueueRequest({
+          kind: 'capability',
+          capability: definition.name,
+          method: definition.method,
+          timeoutCode: 'capability-list-timeout',
+          timeoutMessage: `${definition.method} did not receive a response for advertised ${definition.name} capability within ${timeoutMs}ms`,
+          timeoutDetails: {
+            capability: definition.name,
+            method: definition.method,
+            detailCode: 'capability-request-timeout'
+          }
+        });
+      }
+    }
+
+    function handleCurrentRequestResponse(message) {
+      clearTimeout(timer);
+      const request = currentRequest;
+      if (!isJsonRpcResponse(message)) {
+        addIssue('error', 'stdout-unexpected-request-id', `stdout frame with id ${request.id} is not a ${request.method} response`);
+        finish();
+        return;
+      }
+
+      if (request.kind === 'operation') {
+        const operationResult = result.operations[request.operationIndex];
+        operationResult.responded = true;
+        if (result.operation && request.operationIndex === 0) {
+          result.operation.responded = true;
+        }
+        if (message.error) {
+          operationResult.error = message.error;
+          if (result.operation && request.operationIndex === 0) {
+            result.operation.error = message.error;
+          }
+          addIssue('warning', 'operation-error', `${request.method} returned error: ${message.error.message || JSON.stringify(message.error)}`);
+        }
+      }
+
+      if (!message.error && request.method === 'tools/list') {
+        const validation = validateToolsListResult(message.result);
+        result.toolSchema = validation.summary;
+        for (const issue of validation.issues) {
+          addIssue(issue.severity, issue.code, issue.message, issue.details);
+        }
+      }
+
+      if (request.capability) {
+        recordCapabilityListShape(request, message.result);
+        handleCapabilityResponse(request, message);
+      }
+
+      currentRequest = null;
+      startNextRequest();
+    }
+
+    function handleCapabilityResponse(request, message) {
+      const check = result.capabilityChecks[request.capability];
+      check.responded = true;
+      if (!message.error) return;
+
+      check.error = message.error;
+      const unsupported = isUnsupportedMethodError(message.error);
+      const code = unsupported ? 'capability-list-unsupported' : 'capability-list-error';
+      const messageText = unsupported
+        ? `${request.capability} capability is advertised but ${request.method} returned Method not found`
+        : `${request.capability} capability is advertised but ${request.method} returned error: ${message.error.message || JSON.stringify(message.error)}`;
+      addIssue('error', code, messageText, {
+        capability: request.capability,
+        method: request.method,
+        errorCode: message.error.code ?? null
+      });
+    }
+
+    function recordCapabilityListShape(request, responseResult) {
+      if (!isObjectRecord(responseResult)) return;
+      const check = result.capabilityChecks[request.capability];
+      const items = responseResult[request.capability];
+      if (check && Array.isArray(items)) {
+        check.itemCount = items.length;
+      }
+    }
+
+    function addCapabilityMissingResponseIssue(request) {
+      addIssue('error', 'capability-list-missing-response', `${request.method} did not receive a response before server exit`, {
+        capability: request.capability,
+        method: request.method,
+        detailCode: 'capability-missing-response'
+      });
+    }
+
     const pythonBufferingIssue = detectPythonBufferingIssue(commandWithArgs, env);
     if (pythonBufferingIssue) {
       addIssue('warning', 'python-buffered-stdio', pythonBufferingIssue);
@@ -462,7 +1023,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       if (result.durationMs) return;
       clearTimeout(timer);
       const exitPhase = initialized
-        ? result.operation && !result.operation.responded
+        ? currentRequest
           ? 'operation'
           : 'post-initialize'
         : 'initialize';
@@ -473,8 +1034,18 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       if (stdoutBuffer.trim()) {
         addIssue('error', 'stdout-without-newline', `stdout ended with an incomplete JSON-RPC frame: ${quote(stdoutBuffer)}`);
       }
-      if (!endedByGuard && initialized && result.operation && !result.operation.responded) {
-        addIssue('error', 'operation-missing-response', `${result.operation.method} did not receive a response before server exit`, exitIssueDetails('during-operation', code, signal));
+      if (!endedByGuard && initialized && currentRequest?.kind === 'operation') {
+        const operationResult = result.operations[currentRequest.operationIndex];
+        if (operationResult && !operationResult.responded) {
+          addIssue('error', 'operation-missing-response', `${operationResult.method} did not receive a response before server exit`, {
+            ...exitIssueDetails('during-operation', code, signal),
+            operationIndex: currentRequest.operationIndex,
+            method: operationResult.method
+          });
+        }
+      }
+      if (!endedByGuard && initialized && currentRequest?.capability) {
+        addCapabilityMissingResponseIssue(currentRequest);
       }
       if (!endedByGuard && initialized && isAbnormalExit(code, signal)) {
         addIssue('error', 'server-crashed', `server exited after initialize (code ${code ?? 'null'}, signal ${signal ?? 'null'})`, exitIssueDetails('after-initialize', code, signal));
@@ -566,50 +1137,26 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
         }
 
         initialized = true;
-        result.process.phase = operation ? 'operation' : 'post-initialize';
+        configureCapabilityChecks(message.result.capabilities);
+        result.process.phase = 'post-initialize';
         result.negotiatedProtocol = message.result?.protocolVersion || '';
         send({ jsonrpc: '2.0', method: 'notifications/initialized' });
-        if (operation) {
-          const request = {
-            jsonrpc: '2.0',
-            id: 2,
-            method: operation.method
-          };
-          if (operation.params !== undefined) {
-            request.params = operation.params;
-          }
-          send(request);
-          armTimeout('operation-timeout', `no ${operation.method} response within ${timeoutMs}ms`, 'operation');
-        } else {
-          finishSoon();
-        }
-      } else if (initialized && !operation && isJsonRpcResponse(message)) {
+        enqueuePostInitializeRequests();
+        startNextRequest();
+      } else if (initialized && currentRequest && isResponseIdTypeMismatch(message, currentRequest.id)) {
         clearTimeout(timer);
-        addIssue('error', 'notification-response', 'server sent a JSON-RPC response after notifications/initialized without an outstanding request');
+        addIssue('error', 'response-id-type-mismatch', `${currentRequest.method} response id ${JSON.stringify(message.id)} does not exactly match request id ${currentRequest.id}`);
         finish();
-      } else if (initialized && operation && isResponseIdTypeMismatch(message, 2)) {
+      } else if (initialized && currentRequest && isResponseIdMismatch(message, currentRequest.id)) {
         clearTimeout(timer);
-        addIssue('error', 'response-id-type-mismatch', `${operation.method} response id ${JSON.stringify(message.id)} does not exactly match request id 2`);
+        addIssue('error', 'response-id-mismatch', `${currentRequest.method} response id ${JSON.stringify(message.id)} does not match request id ${currentRequest.id}`);
         finish();
-      } else if (initialized && operation && isResponseIdMismatch(message, 2)) {
+      } else if (initialized && currentRequest && message.id === currentRequest.id) {
+        handleCurrentRequestResponse(message);
+      } else if (initialized && !currentRequest && isJsonRpcResponse(message)) {
         clearTimeout(timer);
-        addIssue('error', 'response-id-mismatch', `${operation.method} response id ${JSON.stringify(message.id)} does not match request id 2`);
+        addIssue('error', 'notification-response', 'server sent a JSON-RPC response after notifications/initialized without an outstanding request');
         finish();
-      } else if (initialized && operation && message.id === 2) {
-        clearTimeout(timer);
-        if (!isJsonRpcResponse(message)) {
-          addIssue('error', 'stdout-unexpected-request-id', `stdout frame with id 2 is not a ${operation.method} response`);
-          finish();
-          return;
-        }
-
-        result.operation.responded = true;
-        result.process.phase = 'post-initialize';
-        if (message.error) {
-          result.operation.error = message.error;
-          addIssue('warning', 'operation-error', `${operation.method} returned error: ${message.error.message || JSON.stringify(message.error)}`);
-        }
-        finishSoon();
       }
     }
   });
@@ -655,12 +1202,41 @@ function defaultProcessInfo(timeoutMs) {
 
 function timeoutIssueDetails(code, timeoutMs, phase) {
   return {
-    detailCode: code === 'operation-timeout' ? 'request-timeout' : 'startup-timeout',
+    detailCode: code === 'operation-timeout'
+      ? 'request-timeout'
+      : code === 'capability-list-timeout'
+        ? 'capability-request-timeout'
+        : 'startup-timeout',
     phase,
     timeoutMs
   };
 }
 
+function defaultCapabilityChecks() {
+  return Object.fromEntries(CAPABILITY_DEFINITIONS.map((definition) => [
+    definition.name,
+    {
+      advertised: false,
+      method: definition.method,
+      responded: false,
+      itemCount: null,
+      error: null
+    }
+  ]));
+}
+
+function capabilityNameForMethod(method) {
+  return CAPABILITY_DEFINITIONS.find((definition) => definition.method === method)?.name ?? '';
+}
+
+function capabilityKeys(capabilities) {
+  return isObjectRecord(capabilities) ? Object.keys(capabilities).sort() : [];
+}
+
+function isUnsupportedMethodError(error) {
+  return error?.code === -32601 || /method not found/i.test(error?.message || '');
+}
+
 function exitIssueDetails(position, code, signal) {
   return {
     detailCode: exitDetailCode(position, code, signal),
@@ -817,13 +1393,264 @@ function validateInitializeResult(result) {
   return issues;
 }
 
+function validateToolsListResult(result) {
+  const summary = {
+    ...defaultToolSchemaValidation(),
+    checked: true
+  };
+  const issues = [];
+
+  if (!isObjectRecord(result) || !Array.isArray(result.tools)) {
+    addToolSchemaIssue(issues, 'error', 'tools-list-invalid-result', 'tools/list result must be an object with a tools array');
+    summary.errorCount = 1;
+    return { summary, issues };
+  }
+
+  summary.toolCount = result.tools.length;
+  const seenNames = new Map();
+
+  for (let index = 0; index < result.tools.length; index += 1) {
+    const tool = result.tools[index];
+    let toolValid = true;
+
+    if (!isObjectRecord(tool)) {
+      addToolSchemaIssue(issues, 'error', 'tools-list-invalid-result', `tools[${index}] must be an object`, { toolIndex: index });
+      continue;
+    }
+
+    const name = validateToolName(tool, index, issues);
+    toolValid = Boolean(name);
+    if (name) {
+      summary.toolNames.push(name);
+      if (seenNames.has(name)) {
+        const firstToolIndex = seenNames.get(name);
+        toolValid = false;
+        summary.duplicateNames.push(name);
+        addToolSchemaIssue(
+          issues,
+          'error',
+          'tool-name-duplicate',
+          `tools/list returned duplicate tool name ${JSON.stringify(name)}`,
+          { toolIndex: index, firstToolIndex, toolName: name }
+        );
+      } else {
+        seenNames.set(name, index);
+      }
+    }
+
+    if (typeof tool.description !== 'string' || !tool.description.trim()) {
+      addToolSchemaIssue(
+        issues,
+        'warning',
+        'tool-description-missing',
+        name
+          ? `tool ${JSON.stringify(name)} is missing a non-empty description`
+          : `tools[${index}] is missing a non-empty description`,
+        { toolIndex: index, toolName: name || '' }
+      );
+    }
+
+    if (!Object.hasOwn(tool, 'inputSchema')) {
+      addToolSchemaIssue(
+        issues,
+        'error',
+        'tool-input-schema-invalid',
+        name
+          ? `tool ${JSON.stringify(name)} is missing inputSchema`
+          : `tools[${index}] is missing inputSchema`,
+        { toolIndex: index, toolName: name || '', schemaPath: 'inputSchema' }
+      );
+      toolValid = false;
+    } else {
+      toolValid = validateInputSchema(tool.inputSchema, {
+        toolIndex: index,
+        toolName: name || '',
+        schemaPath: 'inputSchema'
+      }, issues) && toolValid;
+    }
+
+    if (toolValid) {
+      summary.validToolCount += 1;
+    }
+  }
+
+  summary.duplicateNames = [...new Set(summary.duplicateNames)].sort();
+  summary.toolNames = [...new Set(summary.toolNames)].sort();
+  summary.errorCount = issues.filter((issue) => issue.severity === 'error').length;
+  summary.warningCount = issues.filter((issue) => issue.severity === 'warning').length;
+  return { summary, issues };
+}
+
+function validateToolName(tool, index, issues) {
+  if (typeof tool.name !== 'string' || !tool.name.trim() || tool.name !== tool.name.trim()) {
+    addToolSchemaIssue(issues, 'error', 'tool-name-invalid', `tools[${index}] name must be a stable non-empty string`, {
+      toolIndex: index,
+      toolName: typeof tool.name === 'string' ? tool.name : ''
+    });
+    return '';
+  }
+
+  return tool.name;
+}
+
+function validateInputSchema(schema, context, issues) {
+  return validateSchemaValue(schema, context, issues);
+}
+
+function validateSchemaValue(schema, context, issues) {
+  if (typeof schema === 'boolean') {
+    return true;
+  }
+
+  return validateSchemaObject(schema, context, issues);
+}
+
+function validateSchemaObject(schema, context, issues) {
+  if (!isObjectRecord(schema)) {
+    addToolSchemaIssue(issues, 'error', 'tool-input-schema-invalid', `${context.schemaPath} must be a JSON Schema object or boolean schema`, context);
+    return false;
+  }
+
+  let valid = true;
+
+  if (Object.hasOwn(schema, 'type') && !isValidJsonSchemaType(schema.type)) {
+    valid = false;
+    addToolSchemaIssue(issues, 'error', 'tool-input-schema-invalid', `${context.schemaPath}.type must be a string or array of strings`, context);
+  }
+
+  if (Object.hasOwn(schema, 'properties')) {
+    if (!isObjectRecord(schema.properties)) {
+      valid = false;
+      addToolSchemaIssue(issues, 'error', 'tool-input-schema-invalid', `${context.schemaPath}.properties must be an object`, context);
+    } else {
+      for (const [propertyName, propertySchema] of Object.entries(schema.properties)) {
+        valid = validateSchemaValue(propertySchema, {
+          ...context,
+          schemaPath: `${context.schemaPath}.properties.${propertyName}`
+        }, issues) && valid;
+      }
+    }
+  }
+
+  if (Object.hasOwn(schema, 'required')) {
+    valid = validateRequired(schema, context, issues) && valid;
+  }
+
+  if (Object.hasOwn(schema, 'items')) {
+    valid = validateSchemaValueOrArray(schema.items, {
+      ...context,
+      schemaPath: `${context.schemaPath}.items`
+    }, issues) && valid;
+  }
+
+  if (Object.hasOwn(schema, 'additionalProperties') && typeof schema.additionalProperties !== 'boolean') {
+    valid = validateSchemaObject(schema.additionalProperties, {
+      ...context,
+      schemaPath: `${context.schemaPath}.additionalProperties`
+    }, issues) && valid;
+  }
+
+  for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+    if (Object.hasOwn(schema, keyword)) {
+      valid = validateSchemaArray(schema[keyword], {
+        ...context,
+        schemaPath: `${context.schemaPath}.${keyword}`
+      }, issues) && valid;
+    }
+  }
+
+  if (Object.hasOwn(schema, 'enum') && !Array.isArray(schema.enum)) {
+    valid = false;
+    addToolSchemaIssue(issues, 'error', 'tool-input-schema-invalid', `${context.schemaPath}.enum must be an array`, context);
+  }
+
+  return valid;
+}
+
+function validateSchemaValueOrArray(value, context, issues) {
+  if (Array.isArray(value)) {
+    return validateSchemaArray(value, context, issues);
+  }
+
+  return validateSchemaValue(value, context, issues);
+}
+
+function validateSchemaArray(value, context, issues) {
+  if (!Array.isArray(value) || !value.length) {
+    addToolSchemaIssue(issues, 'error', 'tool-input-schema-invalid', `${context.schemaPath} must be a non-empty array of schemas`, context);
+    return false;
+  }
+
+  let valid = true;
+  for (let index = 0; index < value.length; index += 1) {
+    valid = validateSchemaValue(value[index], {
+      ...context,
+      schemaPath: `${context.schemaPath}[${index}]`
+    }, issues) && valid;
+  }
+  return valid;
+}
+
+function validateRequired(schema, context, issues) {
+  if (!Array.isArray(schema.required) || schema.required.some((entry) => typeof entry !== 'string' || !entry)) {
+    addToolSchemaIssue(issues, 'error', 'tool-input-schema-invalid', `${context.schemaPath}.required must be an array of non-empty strings`, context);
+    return false;
+  }
+
+  let valid = true;
+  const seen = new Set();
+  for (const propertyName of schema.required) {
+    if (seen.has(propertyName)) {
+      valid = false;
+      addToolSchemaIssue(issues, 'error', 'tool-input-schema-invalid', `${context.schemaPath}.required must not contain duplicate entries`, {
+        ...context,
+        propertyName
+      });
+    }
+    seen.add(propertyName);
+
+    if (!isObjectRecord(schema.properties) || !Object.hasOwn(schema.properties, propertyName)) {
+      valid = false;
+      addToolSchemaIssue(
+        issues,
+        'error',
+        'tool-input-schema-required-missing',
+        `${context.schemaPath}.required references missing property ${JSON.stringify(propertyName)}`,
+        { ...context, propertyName }
+      );
+    }
+  }
+
+  return valid;
+}
+
+function isValidJsonSchemaType(value) {
+  if (typeof value === 'string') {
+    return JSON_SCHEMA_TYPES.has(value);
+  }
+  return Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === 'string' && JSON_SCHEMA_TYPES.has(entry));
+}
+
+function addToolSchemaIssue(issues, severity, code, message, details = {}) {
+  issues.push({
+    severity,
+    code,
+    message,
+    details
+  });
+}
+
+function isObjectRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
 export function classifyIssueCode(code) {
   return ISSUE_CLASS_BY_CODE.get(code) ?? ISSUE_CLASSES.MCP_PROTOCOL;
 }
 
 export function createFingerprint(commandWithArgs, options = {}) {
   const cwd = path.resolve(options.cwd ?? process.cwd());
-  const operation = options.operation || null;
+  const operations = normalizeGuardOperations(options.operations ?? (options.operation ? [options.operation] : []));
 
   return {
     guard: {
@@ -841,14 +1668,25 @@ export function createFingerprint(commandWithArgs, options = {}) {
       exists: fs.existsSync(cwd)
     },
     protocol: options.protocol ?? DEFAULT_PROTOCOL,
+    config: options.config ?? defaultConfigMetadata(),
+    profile: options.profile ?? DEFAULT_PROFILE,
     timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT,
     repeat: options.repeat ?? 1,
-    operation: operation
+    capabilityProbes: options.probeCapabilities ?? true,
+    operation: operations.length === 1
       ? {
-          method: operation.method,
-          hasParams: operation.params !== undefined
+          method: operations[0].method,
+          hasParams: operations[0].params !== undefined,
+          source: operations[0].source,
+          safeToolCallName: operations[0].safeToolCallName
         }
       : null,
+    operations: operations.map((operation) => ({
+      method: operation.method,
+      hasParams: operation.params !== undefined,
+      source: operation.source,
+      safeToolCallName: operation.safeToolCallName
+    })),
     system: {
       platform: process.platform,
       arch: process.arch,
@@ -1171,6 +2009,17 @@ function isNpxCommand(base) {
 
 function finalizeResult(result) {
   result.schemaVersion = JSON_SCHEMA_VERSION;
+  result.config ??= defaultConfigMetadata();
+  result.profile ??= DEFAULT_PROFILE;
+  result.capabilityProbes ??= true;
+  result.operations ??= result.operation ? [{
+    index: 0,
+    source: result.operation.source ?? 'request',
+    method: result.operation.method,
+    safeToolCallName: result.operation.safeToolCallName ?? '',
+    responded: Boolean(result.operation.responded),
+    error: result.operation.error ?? null
+  }] : [];
   result.staticScan ??= defaultStaticScan();
   result.staticFindings ??= [];
   result.issues = normalizeIssues(result.issues ?? []);
@@ -1216,6 +2065,12 @@ function buildChecks(result) {
     operation: repeated
       ? aggregateRunCheck(result, 'operation')
       : buildOperationCheck(result, issues),
+    capabilities: repeated
+      ? aggregateCapabilityChecks(result)
+      : buildCapabilityChecks(result, issues),
+    toolSchema: repeated
+      ? aggregateRunCheck(result, 'toolSchema')
+      : buildToolSchemaCheck(result, issues),
     process: buildIssueCheck(issues, (issue) => PROCESS_ISSUE_CODES.has(issue.code)),
     pythonBuffering: buildIssueCheck(issues, (issue) => issue.code === 'python-buffered-stdio'),
     staticScan: buildStaticScanCheck(result, issues),
@@ -1241,7 +2096,13 @@ function buildInitializeCheck(result, issues) {
 }
 
 function buildOperationCheck(result, issues) {
-  if (!result.operation) {
+  const operations = result.operations?.length
+    ? result.operations
+    : result.operation
+      ? [result.operation]
+      : [];
+
+  if (!operations.length) {
     return makeCheck('skipped', []);
   }
 
@@ -1251,14 +2112,108 @@ function buildOperationCheck(result, issues) {
 
   const matched = issues.filter((issue) => (
     OPERATION_ISSUE_CODES.has(issue.code)
-    || (!result.operation.responded && STDOUT_ISSUE_CODES.has(issue.code))
-    || (!result.operation.responded && JSON_RPC_ISSUE_CODES.has(issue.code))
+    || (operations.some((operation) => !operation.responded) && STDOUT_ISSUE_CODES.has(issue.code))
+    || (operations.some((operation) => !operation.responded) && JSON_RPC_ISSUE_CODES.has(issue.code))
   ));
   if (matched.length) {
     return makeCheck(statusFromIssues(matched), matched);
   }
 
-  return makeCheck(result.operation.responded ? 'pass' : 'fail', []);
+  return makeCheck(operations.every((operation) => operation.responded) ? 'pass' : 'fail', []);
+}
+
+function buildToolSchemaCheck(result, issues) {
+  if (!result.toolSchema?.checked) {
+    return makeCheck('skipped', []);
+  }
+
+  const matched = issues.filter((issue) => TOOL_SCHEMA_ISSUE_CODES.has(issue.code));
+  if (matched.length) {
+    return makeCheck(statusFromIssues(matched), matched);
+  }
+
+  return makeCheck('pass', []);
+}
+
+function buildCapabilityChecks(result, issues) {
+  const checks = {};
+  for (const definition of CAPABILITY_DEFINITIONS) {
+    const state = result.capabilityChecks?.[definition.name] ?? defaultCapabilityChecks()[definition.name];
+    const matched = issues.filter((issue) => (
+      CAPABILITY_ISSUE_CODES.has(issue.code)
+      && issue.capability === definition.name
+    ));
+    if (!result.initialized || !state.advertised || result.capabilityProbes === false) {
+      checks[definition.name] = makeCapabilityCheck('skipped', matched, state);
+    } else if (matched.length) {
+      checks[definition.name] = makeCapabilityCheck(statusFromIssues(matched), matched, state);
+    } else {
+      checks[definition.name] = makeCapabilityCheck(state.responded ? 'pass' : 'fail', matched, state);
+    }
+  }
+
+  const active = Object.values(checks).filter((check) => check.status !== 'skipped');
+  const status = active.length
+    ? active.some((check) => check.status === 'fail')
+      ? 'fail'
+      : active.some((check) => check.status === 'warning')
+        ? 'warning'
+        : 'pass'
+    : 'skipped';
+  return {
+    status,
+    issueCodes: [...new Set(active.flatMap((check) => check.issueCodes))].sort(),
+    ...checks
+  };
+}
+
+function aggregateCapabilityChecks(result) {
+  const checks = {};
+  for (const definition of CAPABILITY_DEFINITIONS) {
+    const runChecks = result.runs
+      .map((run) => run.checks?.capabilities?.[definition.name])
+      .filter(Boolean);
+    const activeRunChecks = runChecks.filter((check) => check.status !== 'skipped');
+    const state = aggregateCapabilityState(definition, runChecks);
+    if (!activeRunChecks.length) {
+      checks[definition.name] = makeAggregatedCapabilityCheck('skipped', [], state);
+    } else {
+      const status = activeRunChecks.some((check) => check.status === 'fail')
+        ? 'fail'
+        : activeRunChecks.some((check) => check.status === 'warning')
+          ? 'warning'
+          : 'pass';
+      checks[definition.name] = makeAggregatedCapabilityCheck(status, activeRunChecks, state);
+    }
+  }
+
+  const active = Object.values(checks).filter((check) => check.status !== 'skipped');
+  const status = active.length
+    ? active.some((check) => check.status === 'fail')
+      ? 'fail'
+      : active.some((check) => check.status === 'warning')
+        ? 'warning'
+        : 'pass'
+    : 'skipped';
+  return {
+    status,
+    issueCodes: [...new Set(active.flatMap((check) => check.issueCodes))].sort(),
+    ...checks
+  };
+}
+
+function aggregateCapabilityState(definition, runChecks) {
+  const itemCounts = [...new Set(
+    runChecks
+      .map((check) => check.itemCount)
+      .filter((itemCount) => Number.isInteger(itemCount))
+  )];
+  return {
+    advertised: runChecks.some((check) => check.advertised),
+    method: definition.method,
+    responded: runChecks.some((check) => check.responded),
+    itemCount: itemCounts.length === 1 ? itemCounts[0] : null
+  };
 }
 
 function buildStaticScanCheck(result, issues) {
@@ -1284,8 +2239,16 @@ function buildRepeatCheck(result) {
   }
 
   const failedRuns = result.runs.filter((run) => !run.ok).map((run) => run.run);
+  const repeatIssues = (result.issues ?? []).filter((issue) => (
+    issue.run || REPEAT_DRIFT_ISSUE_CODES.has(issue.code)
+  ));
+  const status = failedRuns.length
+    ? 'fail'
+    : repeatIssues.some((issue) => issue.severity === 'warning')
+      ? 'warning'
+      : 'pass';
   return {
-    ...makeCheck(failedRuns.length ? 'fail' : 'pass', result.issues ?? []),
+    ...makeCheck(status, repeatIssues),
     runs: result.runs.length,
     passedRuns: result.runs.length - failedRuns.length,
     failedRuns
@@ -1327,6 +2290,42 @@ function makeCheck(status, issues) {
   };
 }
 
+function makeCapabilityCheck(status, issues, state) {
+  return {
+    ...makeCheck(status, issues),
+    advertised: Boolean(state.advertised),
+    method: state.method,
+    responded: Boolean(state.responded),
+    itemCount: Number.isInteger(state.itemCount) ? state.itemCount : null
+  };
+}
+
+function makeAggregatedCapabilityCheck(status, checks, state) {
+  return {
+    status,
+    issueCodes: [...new Set(checks.flatMap((check) => check.issueCodes ?? []))].sort(),
+    advertised: Boolean(state.advertised),
+    method: state.method,
+    responded: Boolean(state.responded),
+    itemCount: Number.isInteger(state.itemCount) ? state.itemCount : null
+  };
+}
+
+function defaultConfigMetadata() {
+  return {
+    enabled: false,
+    path: '',
+    resolvedPath: '',
+    checks: {
+      command: false,
+      cwd: false,
+      envNames: [],
+      requests: [],
+      safeToolCalls: []
+    }
+  };
+}
+
 function defaultStaticScan() {
   return {
     enabled: false,
@@ -1335,6 +2334,253 @@ function defaultStaticScan() {
   };
 }
 
+function defaultToolSchemaValidation() {
+  return {
+    checked: false,
+    toolCount: 0,
+    toolNames: [],
+    validToolCount: 0,
+    warningCount: 0,
+    errorCount: 0,
+    duplicateNames: []
+  };
+}
+
+function aggregateRunToolSchemaValidation(runs) {
+  const checkedRuns = runs.filter((run) => run.toolSchema?.checked);
+  if (!checkedRuns.length) {
+    return defaultToolSchemaValidation();
+  }
+
+  return {
+    checked: true,
+    runs: checkedRuns.length,
+    toolCount: checkedRuns.reduce((sum, run) => sum + run.toolSchema.toolCount, 0),
+    validToolCount: checkedRuns.reduce((sum, run) => sum + run.toolSchema.validToolCount, 0),
+    warningCount: checkedRuns.reduce((sum, run) => sum + run.toolSchema.warningCount, 0),
+    errorCount: checkedRuns.reduce((sum, run) => sum + run.toolSchema.errorCount, 0),
+    toolNames: [...new Set(checkedRuns.flatMap((run) => run.toolSchema.toolNames ?? []))].sort(),
+    duplicateNames: [...new Set(checkedRuns.flatMap((run) => run.toolSchema.duplicateNames))].sort()
+  };
+}
+
+function defaultRepeatDrift() {
+  return {
+    checked: false,
+    status: 'skipped',
+    issueCodes: [],
+    baselineRun: null,
+    comparedRuns: [],
+    negotiatedProtocol: driftSection(),
+    capabilities: driftSection(),
+    tools: driftSection(),
+    lists: {
+      resources: driftSection(),
+      prompts: driftSection()
+    }
+  };
+}
+
+function driftSection() {
+  return {
+    status: 'skipped',
+    issueCodes: [],
+    baseline: null,
+    values: [],
+    changedRuns: []
+  };
+}
+
+function buildRepeatDrift(runs) {
+  const drift = defaultRepeatDrift();
+  if (!Array.isArray(runs) || runs.length < 2) {
+    return drift;
+  }
+
+  drift.checked = true;
+  const comparableRuns = runs.filter((run) => run.initialized);
+  drift.comparedRuns = comparableRuns.map((run) => run.run);
+  if (comparableRuns.length < 2) {
+    return drift;
+  }
+
+  drift.baselineRun = comparableRuns[0].run;
+  drift.negotiatedProtocol = compareScalarDrift(
+    comparableRuns,
+    (run) => run.negotiatedProtocol || '',
+    'repeat-protocol-drift'
+  );
+  drift.capabilities = compareSetDrift(
+    comparableRuns,
+    (run) => run.capabilityKeys ?? advertisedCapabilityKeys(run.capabilityChecks),
+    'repeat-capability-drift'
+  );
+  drift.tools = compareToolDrift(comparableRuns);
+  drift.lists.resources = compareListShapeDrift(comparableRuns, 'resources');
+  drift.lists.prompts = compareListShapeDrift(comparableRuns, 'prompts');
+
+  const sections = [
+    drift.negotiatedProtocol,
+    drift.capabilities,
+    drift.tools,
+    drift.lists.resources,
+    drift.lists.prompts
+  ];
+  const active = sections.filter((section) => section.status !== 'skipped');
+  drift.status = active.length
+    ? active.some((section) => section.status === 'warning')
+      ? 'warning'
+      : 'pass'
+    : 'skipped';
+  drift.issueCodes = [...new Set(active.flatMap((section) => section.issueCodes))].sort();
+  return drift;
+}
+
+function compareScalarDrift(runs, valueForRun, issueCode) {
+  const section = driftSection();
+  section.values = runs.map((run) => ({
+    run: run.run,
+    value: valueForRun(run)
+  }));
+  section.baseline = section.values[0].value;
+  section.changedRuns = section.values
+    .slice(1)
+    .filter((entry) => entry.value !== section.baseline)
+    .map((entry) => ({
+      run: entry.run,
+      expected: section.baseline,
+      actual: entry.value
+    }));
+  section.status = section.changedRuns.length ? 'warning' : 'pass';
+  section.issueCodes = section.changedRuns.length ? [issueCode] : [];
+  return section;
+}
+
+function compareSetDrift(runs, valuesForRun, issueCode) {
+  const section = driftSection();
+  section.values = runs.map((run) => ({
+    run: run.run,
+    values: sortedUnique(valuesForRun(run))
+  }));
+  section.baseline = section.values[0].values;
+  section.changedRuns = section.values
+    .slice(1)
+    .map((entry) => ({
+      run: entry.run,
+      added: arrayDifference(entry.values, section.baseline),
+      removed: arrayDifference(section.baseline, entry.values)
+    }))
+    .filter((entry) => entry.added.length || entry.removed.length);
+  section.status = section.changedRuns.length ? 'warning' : 'pass';
+  section.issueCodes = section.changedRuns.length ? [issueCode] : [];
+  return section;
+}
+
+function compareToolDrift(runs) {
+  const checkedRuns = runs.filter((run) => run.toolSchema?.checked);
+  if (checkedRuns.length < 2) {
+    return driftSection();
+  }
+
+  const section = compareSetDrift(
+    checkedRuns,
+    (run) => run.toolSchema.toolNames ?? [],
+    'repeat-tool-drift'
+  );
+  section.values = checkedRuns.map((run) => ({
+    run: run.run,
+    count: run.toolSchema.toolCount,
+    values: sortedUnique(run.toolSchema.toolNames ?? [])
+  }));
+  section.baselineCount = section.values[0].count;
+  const countDrift = section.values
+    .slice(1)
+    .filter((entry) => entry.count !== section.baselineCount)
+    .map((entry) => ({
+      run: entry.run,
+      expected: section.baselineCount,
+      actual: entry.count
+    }));
+  if (countDrift.length) {
+    section.countChangedRuns = countDrift;
+    section.status = 'warning';
+    section.issueCodes = ['repeat-tool-drift'];
+  }
+  return section;
+}
+
+function compareListShapeDrift(runs, capability) {
+  const checkedRuns = runs.filter((run) => Number.isInteger(run.capabilityChecks?.[capability]?.itemCount));
+  if (checkedRuns.length < 2) {
+    return driftSection();
+  }
+
+  const section = compareScalarDrift(
+    checkedRuns,
+    (run) => run.capabilityChecks[capability].itemCount,
+    'repeat-list-shape-drift'
+  );
+  section.capability = capability;
+  return section;
+}
+
+function repeatDriftIssues(drift) {
+  if (!drift?.checked || drift.status !== 'warning') {
+    return [];
+  }
+
+  const issues = [];
+  if (drift.negotiatedProtocol.status === 'warning') {
+    issues.push(repeatDriftIssue('repeat-protocol-drift', 'negotiated protocol changed across repeat runs', {
+      drift: drift.negotiatedProtocol
+    }));
+  }
+  if (drift.capabilities.status === 'warning') {
+    issues.push(repeatDriftIssue('repeat-capability-drift', 'advertised capability keys changed across repeat runs', {
+      drift: drift.capabilities
+    }));
+  }
+  if (drift.tools.status === 'warning') {
+    issues.push(repeatDriftIssue('repeat-tool-drift', 'tools/list tool names or counts changed across repeat runs', {
+      drift: drift.tools
+    }));
+  }
+  for (const capability of ['resources', 'prompts']) {
+    if (drift.lists[capability].status === 'warning') {
+      issues.push(repeatDriftIssue('repeat-list-shape-drift', `${capability}/list item count changed across repeat runs`, {
+        capability,
+        drift: drift.lists[capability]
+      }));
+    }
+  }
+  return issues;
+}
+
+function repeatDriftIssue(code, message, details) {
+  return {
+    severity: 'warning',
+    code,
+    message,
+    ...details
+  };
+}
+
+function advertisedCapabilityKeys(capabilityChecks = {}) {
+  return Object.entries(capabilityChecks)
+    .filter(([, check]) => check?.advertised)
+    .map(([name]) => name)
+    .sort();
+}
+
+function sortedUnique(values) {
+  return [...new Set((values ?? []).filter((value) => typeof value === 'string'))].sort();
+}
+
+function arrayDifference(left, right) {
+  const rightSet = new Set(right);
+  return left.filter((value) => !rightSet.has(value));
+}
+
 export function scanSource(root) {
   const findings = [];
   const absoluteRoot = path.resolve(root);
@@ -1344,12 +2590,14 @@ export function scanSource(root) {
     const text = fs.readFileSync(file, 'utf8');
     const lines = text.split(/\r?\n/);
     for (let index = 0; index < lines.length; index += 1) {
-      const message = detectStdoutWrite(file, lines[index]);
-      if (message) {
+      const finding = detectStdoutRisk(file, lines[index]);
+      if (finding) {
         findings.push({
           file: path.relative(process.cwd(), file).split(path.sep).join('/'),
           line: index + 1,
-          message
+          language: finding.language,
+          reason: finding.reason,
+          message: finding.message
         });
       }
     }
@@ -1358,34 +2606,254 @@ export function scanSource(root) {
   return findings;
 }
 
-function detectStdoutWrite(file, line) {
-  const ext = path.extname(file);
+function detectStdoutRisk(file, line) {
+  const ext = path.extname(file).toLowerCase();
   const stripped = line.trim();
   if (!stripped || stripped.startsWith('//') || stripped.startsWith('#')) return '';
+  const code = normalizeSourceLine(line, ext);
+
+  if (isJavaScriptSource(ext)) {
+    if (/\bconsole\.(log|info)\s*\(/.test(code)) {
+      return staticFinding(
+        'javascript',
+        'javascript-console-stdout',
+        'console.log/info writes to stdout; use console.error for MCP stdio diagnostics'
+      );
+    }
+
+    if (/\bprocess\.stdout\.write\s*\(/.test(code)) {
+      return staticFinding(
+        'javascript',
+        'javascript-process-stdout-write',
+        'direct process.stdout.write can pollute MCP stdout unless it only writes JSON-RPC frames; route diagnostics to stderr'
+      );
+    }
+
+    if (/\bprocess\.stdout\.(clearLine|cursorTo|moveCursor)\s*\(/.test(code)) {
+      return staticFinding(
+        'javascript',
+        'javascript-stdout-terminal-control',
+        'process.stdout terminal control writes to stdout; keep MCP stdout reserved for JSON-RPC frames'
+      );
+    }
+
+    if (/\bdotenv\.config\s*\(\s*\{[^}]*\bdebug\s*:\s*true\b/.test(code)) {
+      return staticFinding(
+        'javascript',
+        'javascript-dotenv-debug-output',
+        'dotenv debug output can print during startup; keep MCP diagnostics on stderr'
+      );
+    }
 
-  if (['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext) && /\bconsole\.(log|info)\s*\(/.test(line)) {
-    return 'console.log/info writes to stdout; use console.error for MCP stdio diagnostics';
+    if (/\b(stream|file)\s*:\s*process\.stdout\b/.test(code)) {
+      return staticFinding(
+        'javascript',
+        'javascript-progress-stdout',
+        'progress or spinner output is configured for stdout; MCP stdout must stay JSON-RPC only'
+      );
+    }
   }
 
-  if (ext === '.py' && /(^|[^\w])print\s*\(/.test(line) && !/file\s*=\s*sys\.stderr/.test(line)) {
-    return 'print() writes to stdout; pass file=sys.stderr for MCP stdio diagnostics';
+  if (ext === '.py') {
+    if (/(^|[^\w.])print\s*\(/.test(code) && !/file\s*=\s*sys\.stderr/.test(code)) {
+      return staticFinding(
+        'python',
+        'python-print-stdout',
+        'print() writes to stdout; pass file=sys.stderr for MCP stdio diagnostics'
+      );
+    }
+
+    if (/\bsys\.stdout\.write\s*\(/.test(code)) {
+      return staticFinding(
+        'python',
+        'python-sys-stdout-write',
+        'direct sys.stdout.write can pollute MCP stdout unless it only writes JSON-RPC frames; route diagnostics to stderr'
+      );
+    }
+
+    if (/\blogging\.StreamHandler\s*\(\s*sys\.stdout\s*\)/.test(code)
+      || /\blogging\.basicConfig\s*\([^)]*\bstream\s*=\s*sys\.stdout\b/.test(code)) {
+      return staticFinding(
+        'python',
+        'python-logging-stdout-handler',
+        'Python logging is configured to write to stdout; route MCP diagnostics to stderr'
+      );
+    }
+
+    if (/\btqdm\s*\([^)]*\bfile\s*=\s*sys\.stdout\b/.test(code)) {
+      return staticFinding(
+        'python',
+        'python-progress-stdout',
+        'progress output is configured for stdout; MCP stdout must stay JSON-RPC only'
+      );
+    }
   }
 
-  if (ext === '.go' && /\bfmt\.(Print|Printf|Println)\s*\(/.test(line)) {
-    return 'fmt.Print* writes to stdout; use stderr for MCP stdio diagnostics';
+  if (ext === '.go' && /\bfmt\.(Print|Printf|Println)\s*\(/.test(code)) {
+    return staticFinding(
+      'go',
+      'go-fmt-stdout',
+      'fmt.Print* writes to stdout; use stderr for MCP stdio diagnostics'
+    );
   }
 
-  if (ext === '.rs' && /\bprintln!\s*\(/.test(line)) {
-    return 'println! writes to stdout; use eprintln! for MCP stdio diagnostics';
+  if (ext === '.rs' && /\bprintln!\s*\(/.test(code)) {
+    return staticFinding(
+      'rust',
+      'rust-println-stdout',
+      'println! writes to stdout; use eprintln! for MCP stdio diagnostics'
+    );
   }
 
-  if (['.java', '.kt'].includes(ext) && /System\.out\.print/.test(line)) {
-    return 'System.out writes to stdout; use stderr for MCP stdio diagnostics';
+  if (['.java', '.kt'].includes(ext) && /System\.out\.print/.test(code)) {
+    return staticFinding(
+      'jvm',
+      'jvm-system-out',
+      'System.out writes to stdout; use stderr for MCP stdio diagnostics'
+    );
   }
 
   return '';
 }
 
+function staticFinding(language, reason, message) {
+  return { language, reason, message };
+}
+
+function isJavaScriptSource(ext) {
+  return ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext);
+}
+
+function normalizeSourceLine(line, ext) {
+  return stripInlineComment(maskStringLiterals(line), ext);
+}
+
+function stripInlineComment(line, ext) {
+  if (ext === '.py') {
+    return line.split('#')[0];
+  }
+
+  if (isJavaScriptSource(ext) || ['.go', '.rs', '.java', '.kt'].includes(ext)) {
+    return stripJavaScriptLikeInlineComment(line);
+  }
+
+  return line;
+}
+
+function stripJavaScriptLikeInlineComment(line) {
+  let inRegex = false;
+  let escaped = false;
+  let inCharClass = false;
+
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    const next = line[index + 1];
+
+    if (inRegex) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '[') {
+        inCharClass = true;
+      } else if (char === ']') {
+        inCharClass = false;
+      } else if (char === '/' && !inCharClass) {
+        inRegex = false;
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      return line.slice(0, index);
+    }
+
+    if (char === '/' && next === '*') {
+      return line.slice(0, index);
+    }
+
+    if (char === '/' && canStartJavaScriptRegex(line, index)) {
+      inRegex = true;
+    }
+  }
+
+  return line;
+}
+
+function canStartJavaScriptRegex(line, index) {
+  const before = line.slice(0, index).trimEnd();
+  if (!before) return true;
+
+  const last = before[before.length - 1];
+  if ('=(:,[!&|?;{}>'.includes(last)) return true;
+
+  return /\b(await|case|delete|of|return|throw|typeof|void|yield)$/.test(before);
+}
+
+function maskStringLiterals(line) {
+  let quote = '';
+  let escaped = false;
+  let masked = '';
+  let templateExpressionDepth = 0;
+
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    const next = line[index + 1];
+
+    if (quote) {
+      if (quote === '`' && char === '$' && next === '{') {
+        quote = '';
+        templateExpressionDepth += 1;
+        masked += '  ';
+        index += 1;
+        continue;
+      }
+
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = '';
+      }
+      masked += ' ';
+      continue;
+    }
+
+    if (templateExpressionDepth > 0) {
+      if (char === '"' || char === "'" || char === '`') {
+        quote = char;
+        masked += ' ';
+        continue;
+      }
+
+      if (char === '{') {
+        templateExpressionDepth += 1;
+      } else if (char === '}') {
+        templateExpressionDepth -= 1;
+        if (templateExpressionDepth === 0) {
+          quote = '`';
+          masked += ' ';
+          continue;
+        }
+      }
+
+      masked += char;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+      masked += ' ';
+      continue;
+    }
+
+    masked += char;
+  }
+
+  return masked;
+}
+
 function listSourceFiles(root) {
   const ignored = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', '.next', '.cache']);
   const files = [];
@@ -1431,6 +2899,10 @@ function formatTextResult(result) {
     lines.push(`request: ${result.operation.method} ${state}`);
   }
 
+  if (result.toolSchema?.checked) {
+    lines.push(`tool schemas: ${result.toolSchema.validToolCount}/${result.toolSchema.toolCount} valid`);
+  }
+
   if (result.staticFindings.length) {
     lines.push(`static findings: ${result.staticFindings.length}`);
     for (const finding of result.staticFindings.slice(0, 10)) {
@@ -1453,11 +2925,19 @@ function formatRepeatedTextResult(result) {
     `runs: ${passedRuns}/${result.runs.length} passed`
   ];
 
+  if (result.drift?.checked && result.drift.status !== 'skipped') {
+    const issueCodes = result.drift.issueCodes.length ? ` (${result.drift.issueCodes.join(', ')})` : '';
+    lines.push(`drift: ${result.drift.status}${issueCodes}`);
+  }
+
   for (const run of result.runs) {
     const runStatus = run.ok ? 'PASS' : 'FAIL';
     const invalidFrames = run.issues.filter((issue) => issue.code.startsWith('stdout-')).length;
     const stderrLines = run.stderr ? run.stderr.trim().split(/\r?\n/).filter(Boolean).length : 0;
-    lines.push(`run ${run.run}: ${runStatus}, initialize ${run.initialized ? 'ok' : 'failed'}, frames ${run.frames.length} stdout / ${invalidFrames} invalid, stderr ${stderrLines} lines`);
+    const toolSchemas = run.toolSchema?.checked
+      ? `, tool schemas ${run.toolSchema.validToolCount}/${run.toolSchema.toolCount} valid`
+      : '';
+    lines.push(`run ${run.run}: ${runStatus}, initialize ${run.initialized ? 'ok' : 'failed'}, frames ${run.frames.length} stdout / ${invalidFrames} invalid, stderr ${stderrLines} lines${toolSchemas}`);
   }
 
   if (result.staticFindings.length) {
@@ -1505,6 +2985,8 @@ Usage:
   mcp-stdio-guard [options] -- <command> [args...]
 
 Options:
+  --config <path>        read JSON config for registry runs and safe tool calls
+  --profile <name>       guard profile: custom, smoke, registry, ci, strict
   --protocol <version>   MCP protocol version, default ${DEFAULT_PROTOCOL}
   --timeout <ms>         initialize and request timeout, default ${DEFAULT_TIMEOUT}
   --repeat <count>       run the guard multiple times, default 1