mcp-stdio-guard 0.2.0 → 0.4.0

package/src/index.js

@@ -1,20 +1,78 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+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.2.0';
+    return typeof packageJson.version === 'string' ? packageJson.version : '0.4.0';
   } catch {
-    return '0.2.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',
+  '--cpu-prof-dir',
+  '--diagnostic-dir',
+  '--experimental-loader',
+  '--heapsnapshot-near-heap-limit',
+  '--import',
+  '--inspect-port',
+  '--loader',
+  '--max-old-space-size',
+  '--openssl-config',
+  '--perf-basic-prof-only-functions',
+  '--prof-process',
+  '--redirect-warnings',
+  '--require',
+  '--test-reporter',
+  '--test-reporter-destination',
+  '--title',
+  '--trace-event-categories',
+  '--trace-event-file-pattern',
+  '-C',
+  '-r'
+]);
+const NODE_EVAL_OPTIONS = new Set(['--eval', '--print', '-e', '-p']);
+
+export const ISSUE_CLASSES = Object.freeze({
+  INSTALL_RUNTIME: 'installRuntime',
+  STDIO_TRANSPORT: 'stdioTransport',
+  MCP_PROTOCOL: 'mcpProtocol'
+});
+
+const ISSUE_CLASS_NAMES = [
+  ISSUE_CLASSES.INSTALL_RUNTIME,
+  ISSUE_CLASSES.STDIO_TRANSPORT,
+  ISSUE_CLASSES.MCP_PROTOCOL
+];
 
 const STDOUT_ISSUE_CODES = new Set([
   'stdout-empty-line',
@@ -25,12 +83,38 @@ const STDOUT_ISSUE_CODES = new Set([
   'stdout-without-newline'
 ]);
 const JSON_RPC_ISSUE_CODES = new Set([
+  'notification-response',
+  'response-id-mismatch',
   'response-id-type-mismatch',
   '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',
+  'initialize-invalid-protocol-version',
+  'initialize-invalid-result',
+  'initialize-invalid-server-info',
+  'initialize-missing-capabilities',
+  'initialize-missing-protocol-version',
+  'initialize-missing-server-info',
   'initialize-timeout',
   'server-exited',
   'spawn-failed'
@@ -40,11 +124,64 @@ 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',
   'spawn-failed'
 ]);
+const ISSUE_CLASS_BY_CODE = new Map([
+  ['initialize-timeout', ISSUE_CLASSES.INSTALL_RUNTIME],
+  ['operation-missing-response', ISSUE_CLASSES.INSTALL_RUNTIME],
+  ['operation-timeout', ISSUE_CLASSES.INSTALL_RUNTIME],
+  ['python-buffered-stdio', ISSUE_CLASSES.INSTALL_RUNTIME],
+  ['server-crashed', ISSUE_CLASSES.INSTALL_RUNTIME],
+  ['server-exited', ISSUE_CLASSES.INSTALL_RUNTIME],
+  ['spawn-failed', ISSUE_CLASSES.INSTALL_RUNTIME],
+
+  ['static-stdout-write', ISSUE_CLASSES.STDIO_TRANSPORT],
+  ['stdout-content-length-framing', ISSUE_CLASSES.STDIO_TRANSPORT],
+  ['stdout-empty-line', ISSUE_CLASSES.STDIO_TRANSPORT],
+  ['stdout-non-json', ISSUE_CLASSES.STDIO_TRANSPORT],
+  ['stdout-without-newline', ISSUE_CLASSES.STDIO_TRANSPORT],
+
+  ['initialize-error', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['initialize-invalid-capabilities', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['initialize-invalid-protocol-version', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['initialize-invalid-result', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['initialize-invalid-server-info', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['initialize-missing-capabilities', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['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],
+  ['stdout-invalid-json-rpc', ISSUE_CLASSES.MCP_PROTOCOL],
+  ['stdout-unexpected-request-id', ISSUE_CLASSES.MCP_PROTOCOL]
+]);
 
 export async function runCli(argv) {
   const options = parseArgs(argv);
@@ -64,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
   };
@@ -85,6 +227,9 @@ export async function runCli(argv) {
       path: options.scanPath,
       failOnFindings: options.failOnStatic
     };
+    if (result.fingerprint) {
+      result.fingerprint.staticScan = result.staticScan;
+    }
     result.staticFindings = scanSource(options.scanPath);
     if (options.failOnStatic) {
       for (const finding of result.staticFindings) {
@@ -113,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: '',
@@ -125,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;
     }
 
@@ -140,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');
   }
@@ -183,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;
@@ -193,8 +643,10 @@ export async function guardRepeatedStdioServer(commandWithArgs, options = {}) {
     throw new Error('repeat must be an integer >= 1');
   }
 
+  const singleRunOptions = { ...options, repeat: 1 };
+
   for (let index = 1; index <= repeat; index += 1) {
-    const run = await guardStdioServer(commandWithArgs, options);
+    const run = await guardStdioServer(commandWithArgs, singleRunOptions);
     run.run = index;
     runs.push(run);
     for (const issue of run.issues) {
@@ -202,19 +654,33 @@ export async function guardRepeatedStdioServer(commandWithArgs, options = {}) {
     }
   }
 
-  return finalizeResult({
+  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: [],
-    durationMs: Date.now() - startedAt
-  });
+    toolSchema: aggregateRunToolSchemaValidation(runs),
+    durationMs,
+    fingerprint: createFingerprint(commandWithArgs, options)
+  };
+  result.fingerprint.timings.totalMs = durationMs;
+  return finalizeResult(result);
 }
 
 export async function guardStdioServer(commandWithArgs, options = {}) {
@@ -223,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 = [];
@@ -231,41 +698,80 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
   let stdoutBuffer = '';
   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: [],
-    durationMs: 0
+    toolSchema: defaultToolSchemaValidation(),
+    durationMs: 0,
+    fingerprint: createFingerprint(commandWithArgs, {
+      protocol,
+      timeoutMs,
+      cwd: options.cwd,
+      config: options.config,
+      profile: options.profile,
+      probeCapabilities,
+      operations,
+      env: options.env
+    })
   };
 
   return new Promise((resolve) => {
-    function addIssue(severity, code, message) {
-      issues.push({ severity, code, message });
+    function addIssue(severity, code, message, details = {}) {
+      issues.push({ ...details, severity, code, message });
     }
 
-    function armTimeout(code, message) {
+    function armTimeout(code, message, timeoutPhase, details = {}) {
       clearTimeout(timer);
+      result.process.phase = timeoutPhase;
       timer = setTimeout(() => {
-        addIssue('error', code, message);
+        result.process.timedOut = true;
+        result.process.timeoutCode = code;
+        result.process.timeoutMs = timeoutMs;
+        result.process.outcome = 'timeout';
+        addIssue('error', code, message, {
+          ...timeoutIssueDetails(code, timeoutMs, timeoutPhase),
+          ...details
+        });
         finish();
       }, timeoutMs);
     }
@@ -281,8 +787,19 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       result.durationMs = Date.now() - startedAt;
       result.stderr = Buffer.concat(stderrChunks).toString('utf8');
       result.initialized = initialized;
+      result.fingerprint.timings.startupMs = initializeResponseAt ? initializeResponseAt - startedAt : null;
+      result.fingerprint.timings.totalMs = result.durationMs;
+      const willTerminate = child && result.process.started && !child.killed && child.exitCode === null;
+      if (willTerminate) {
+        result.process.killedByGuard = true;
+        result.process.killSignal = 'SIGTERM';
+        result.process.killReason = result.process.timedOut ? 'timeout' : 'guard-finished';
+        if (!result.process.outcome || result.process.outcome === 'running') {
+          result.process.outcome = 'guard-terminated';
+        }
+      }
       finalizeResult(result);
-      if (child && !child.killed && child.exitCode === null) {
+      if (willTerminate) {
         endedByGuard = true;
         child.kill('SIGTERM');
       }
@@ -290,9 +807,166 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
     }
 
     function send(message) {
+      if (!child?.stdin?.writable) return;
       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);
@@ -303,15 +977,34 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       env,
       stdio: ['pipe', 'pipe', 'pipe']
     });
+    result.process.pid = child.pid ?? null;
+
+    armTimeout('initialize-timeout', `no initialize response within ${timeoutMs}ms`, 'initialize');
 
-    armTimeout('initialize-timeout', `no initialize response within ${timeoutMs}ms`);
+    child.on('spawn', () => {
+      result.process.started = true;
+      result.process.pid = child.pid ?? null;
+      result.process.outcome = 'running';
+    });
 
     child.on('error', (error) => {
       clearTimeout(timer);
-      addIssue('error', 'spawn-failed', error.message);
+      result.process.phase = 'startup';
+      result.process.outcome = 'spawn-failed';
+      result.process.spawnError = {
+        code: error.code || '',
+        message: error.message
+      };
+      addIssue('error', 'spawn-failed', error.message, {
+        detailCode: 'spawn-failed-before-startup',
+        phase: 'startup',
+        spawnErrorCode: error.code || ''
+      });
       finish();
     });
 
+    child.stdin.on('error', () => {});
+
     child.stdout.on('data', (chunk) => {
       stdoutBuffer += chunk.toString('utf8');
       const lines = stdoutBuffer.split(/\r?\n/);
@@ -329,17 +1022,36 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
     child.on('exit', (code, signal) => {
       if (result.durationMs) return;
       clearTimeout(timer);
+      const exitPhase = initialized
+        ? currentRequest
+          ? 'operation'
+          : 'post-initialize'
+        : 'initialize';
+      result.process.phase = exitPhase;
+      result.process.outcome = 'exited';
+      result.process.exitCode = code;
+      result.process.signal = signal;
       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`);
+      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 && code && code !== 0) {
-        addIssue('error', 'server-crashed', `server exited after initialize (code ${code}, signal ${signal ?? 'null'})`);
+      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));
       }
       if (!initialized && !endedByGuard && !issues.some((issue) => issue.code === 'spawn-failed')) {
-        addIssue('error', 'server-exited', `server exited before initialize completed (code ${code ?? 'null'}, signal ${signal ?? 'null'})`);
+        addIssue('error', 'server-exited', `server exited before initialize completed (code ${code ?? 'null'}, signal ${signal ?? 'null'})`, exitIssueDetails('before-initialize', code, signal));
       }
       finish();
     });
@@ -386,15 +1098,23 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
 
       frames.push(message);
 
-      if (isResponseIdTypeMismatch(message, 1)) {
+      if (!initialized && isResponseIdTypeMismatch(message, 1)) {
         clearTimeout(timer);
         addIssue('error', 'response-id-type-mismatch', `initialize response id ${JSON.stringify(message.id)} does not exactly match request id 1`);
         finish();
         return;
       }
 
-      if (message.id === 1) {
+      if (!initialized && isResponseIdMismatch(message, 1)) {
+        clearTimeout(timer);
+        addIssue('error', 'response-id-mismatch', `initialize response id ${JSON.stringify(message.id)} does not match request id 1`);
+        finish();
+        return;
+      }
+
+      if (!initialized && message.id === 1) {
         clearTimeout(timer);
+        initializeResponseAt = Date.now();
         if (!isJsonRpcResponse(message)) {
           addIssue('error', 'stdout-unexpected-request-id', 'stdout frame with id 1 is not an initialize response');
           finish();
@@ -407,41 +1127,36 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
           return;
         }
 
+        const initializeIssues = validateInitializeResult(message.result);
+        for (const issue of initializeIssues) {
+          addIssue(issue.severity, issue.code, issue.message);
+        }
+        if (initializeIssues.some((issue) => issue.severity === 'error')) {
+          finish();
+          return;
+        }
+
         initialized = true;
+        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`);
-        } else {
-          finishSoon();
-        }
-      } else if (operation && isResponseIdTypeMismatch(message, 2)) {
+        enqueuePostInitializeRequests();
+        startNextRequest();
+      } else if (initialized && currentRequest && isResponseIdTypeMismatch(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-type-mismatch', `${currentRequest.method} response id ${JSON.stringify(message.id)} does not exactly match request id ${currentRequest.id}`);
         finish();
-      } else if (operation && message.id === 2) {
+      } else if (initialized && currentRequest && isResponseIdMismatch(message, currentRequest.id)) {
         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;
-        if (message.error) {
-          result.operation.error = message.error;
-          addIssue('warning', 'operation-error', `${operation.method} returned error: ${message.error.message || JSON.stringify(message.error)}`);
-        }
-        finishSoon();
+        addIssue('error', 'response-id-mismatch', `${currentRequest.method} response id ${JSON.stringify(message.id)} does not match request id ${currentRequest.id}`);
+        finish();
+      } else if (initialized && currentRequest && message.id === currentRequest.id) {
+        handleCurrentRequestResponse(message);
+      } else if (initialized && !currentRequest && isJsonRpcResponse(message)) {
+        clearTimeout(timer);
+        addIssue('error', 'notification-response', 'server sent a JSON-RPC response after notifications/initialized without an outstanding request');
+        finish();
       }
     }
   });
@@ -467,10 +1182,92 @@ export function detectPythonBufferingIssue(commandWithArgs, env = process.env) {
   return 'Python stdout is buffered when piped; use python -u or PYTHONUNBUFFERED=1 for MCP stdio servers';
 }
 
+function defaultProcessInfo(timeoutMs) {
+  return {
+    started: false,
+    pid: null,
+    outcome: 'starting',
+    phase: 'initialize',
+    exitCode: null,
+    signal: null,
+    timedOut: false,
+    timeoutCode: '',
+    timeoutMs,
+    killedByGuard: false,
+    killSignal: '',
+    killReason: '',
+    spawnError: null
+  };
+}
+
+function timeoutIssueDetails(code, timeoutMs, phase) {
+  return {
+    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),
+    phase: position === 'during-operation'
+      ? 'operation'
+      : position === 'before-initialize'
+        ? 'initialize'
+        : 'post-initialize',
+    exitCode: code,
+    signal
+  };
+}
+
+function exitDetailCode(position, code, signal) {
+  if (signal) return `signal-exit-${position}`;
+  if (code === 0) return `clean-exit-${position}`;
+  return `nonzero-exit-${position}`;
+}
+
+function isAbnormalExit(code, signal) {
+  return signal !== null || (code !== null && code !== 0);
+}
+
 function isResponseIdTypeMismatch(message, expectedId) {
   return hasResponsePayload(message) && Object.hasOwn(message, 'id') && message.id !== expectedId && String(message.id) === String(expectedId);
 }
 
+function isResponseIdMismatch(message, expectedId) {
+  return hasResponsePayload(message) && Object.hasOwn(message, 'id') && message.id !== expectedId && String(message.id) !== String(expectedId);
+}
+
 function isJsonRpcResponse(message) {
   return hasResponsePayload(message) && !Object.hasOwn(message, 'method');
 }
@@ -493,10 +1290,38 @@ export function validateJsonRpc(message) {
   const hasResult = Object.hasOwn(message, 'result');
   const hasError = Object.hasOwn(message, 'error');
 
+  if (hasId && !isJsonRpcId(message.id)) {
+    return 'JSON-RPC id must be a string, integer number, or null';
+  }
+
+  if (hasMethod && hasId && message.id === null) {
+    return 'JSON-RPC request id must not be null';
+  }
+
   if (hasMethod && (hasResult || hasError)) {
     return 'request/notification frame must not include result or error';
   }
 
+  if (!hasMethod && hasResult && hasError) {
+    return 'response frame must not include both result and error';
+  }
+
+  if (!hasMethod && !hasId && (hasResult || hasError)) {
+    return 'response frame must include id';
+  }
+
+  if (!hasMethod && hasError) {
+    if (!message.error || typeof message.error !== 'object' || Array.isArray(message.error)) {
+      return 'JSON-RPC error must be an object';
+    }
+    if (!Number.isInteger(message.error.code)) {
+      return 'JSON-RPC error code must be an integer';
+    }
+    if (typeof message.error.message !== 'string') {
+      return 'JSON-RPC error message must be a string';
+    }
+  }
+
   if (hasId && !hasMethod && !hasResult && !hasError) {
     return 'response frame must include result or error';
   }
@@ -508,21 +1333,731 @@ export function validateJsonRpc(message) {
   return '';
 }
 
-function finalizeResult(result) {
-  result.schemaVersion = JSON_SCHEMA_VERSION;
-  result.staticScan ??= defaultStaticScan();
-  result.staticFindings ??= [];
-  result.ok = !result.issues.some((issue) => issue.severity === 'error');
-  result.checks = buildChecks(result);
-  return result;
+function isJsonRpcId(id) {
+  return id === null || typeof id === 'string' || (typeof id === 'number' && Number.isInteger(id));
 }
 
-function buildChecks(result) {
-  const issues = result.issues ?? [];
-  const repeated = Array.isArray(result.runs);
+function validateInitializeResult(result) {
+  const issues = [];
 
-  return {
-    initialize: repeated
+  if (!result || typeof result !== 'object' || Array.isArray(result)) {
+    return [{
+      severity: 'error',
+      code: 'initialize-invalid-result',
+      message: 'initialize result must be an object with protocolVersion and capabilities'
+    }];
+  }
+
+  if (!Object.hasOwn(result, 'protocolVersion')) {
+    issues.push({
+      severity: 'error',
+      code: 'initialize-missing-protocol-version',
+      message: 'initialize result is missing protocolVersion'
+    });
+  } else if (typeof result.protocolVersion !== 'string' || !result.protocolVersion) {
+    issues.push({
+      severity: 'error',
+      code: 'initialize-invalid-protocol-version',
+      message: 'initialize result protocolVersion must be a non-empty string'
+    });
+  }
+
+  if (!Object.hasOwn(result, 'capabilities')) {
+    issues.push({
+      severity: 'error',
+      code: 'initialize-missing-capabilities',
+      message: 'initialize result is missing capabilities'
+    });
+  } else if (!result.capabilities || typeof result.capabilities !== 'object' || Array.isArray(result.capabilities)) {
+    issues.push({
+      severity: 'error',
+      code: 'initialize-invalid-capabilities',
+      message: 'initialize result capabilities must be an object'
+    });
+  }
+
+  if (!Object.hasOwn(result, 'serverInfo')) {
+    issues.push({
+      severity: 'warning',
+      code: 'initialize-missing-server-info',
+      message: 'initialize result is missing serverInfo'
+    });
+  } else if (!result.serverInfo || typeof result.serverInfo !== 'object' || Array.isArray(result.serverInfo)) {
+    issues.push({
+      severity: 'warning',
+      code: 'initialize-invalid-server-info',
+      message: 'initialize result serverInfo should be an object'
+    });
+  }
+
+  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 operations = normalizeGuardOperations(options.operations ?? (options.operation ? [options.operation] : []));
+
+  return {
+    guard: {
+      name: 'mcp-stdio-guard',
+      version: VERSION
+    },
+    command: {
+      executable: commandWithArgs[0] || '',
+      args: redactArgv(commandWithArgs.slice(1)),
+      argv: redactArgv(commandWithArgs)
+    },
+    cwd: {
+      requested: String(options.cwd ?? process.cwd()),
+      resolved: cwd,
+      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,
+    capabilityProbes: options.probeCapabilities ?? true,
+    operation: operations.length === 1
+      ? {
+          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,
+      osRelease: os.release()
+    },
+    runtimes: detectRuntimeVersions(commandWithArgs),
+    package: detectPackageMetadata(commandWithArgs, cwd),
+    env: redactEnvMetadata(options.env ?? {}),
+    staticScan: defaultStaticScan(),
+    timings: {
+      startupMs: null,
+      totalMs: null
+    }
+  };
+}
+
+function redactEnvMetadata(env) {
+  const names = Object.keys(env).sort();
+  return {
+    inherited: true,
+    names,
+    values: Object.fromEntries(names.map((name) => [name, REDACTED]))
+  };
+}
+
+function redactArgv(argv) {
+  const redacted = [];
+  let redactNext = false;
+
+  for (const arg of argv) {
+    if (redactNext) {
+      redacted.push(REDACTED);
+      redactNext = false;
+      continue;
+    }
+
+    const secretAssignment = redactSecretAssignment(arg);
+    if (secretAssignment) {
+      redacted.push(secretAssignment);
+      continue;
+    }
+
+    redacted.push(arg);
+    if (isSecretFlag(arg)) {
+      redactNext = true;
+    }
+  }
+
+  return redacted;
+}
+
+function redactSecretAssignment(arg) {
+  const match = /^([^=\s]+)=(.*)$/.exec(arg);
+  if (!match) return '';
+
+  const [, name] = match;
+  return isSecretName(name) ? `${name}=${REDACTED}` : '';
+}
+
+function isSecretFlag(arg) {
+  if (!arg.startsWith('-')) return false;
+  const name = arg.replace(/^-+/, '').split(/[=\s]/)[0];
+  return isSecretName(name);
+}
+
+function isSecretName(name) {
+  return /(^|[-_])(api[-_]?key|auth|bearer|cookie|credential|password|passwd|private[-_]?key|pwd|secret|session|token)([-_]|$)/i.test(name);
+}
+
+function detectRuntimeVersions(commandWithArgs) {
+  const command = commandWithArgs[0] || '';
+  const base = path.basename(command).toLowerCase();
+  const runtimes = {
+    node: {
+      version: process.version,
+      role: isNodeCommand(command) ? 'guard-and-target' : 'guard'
+    }
+  };
+
+  if (isPythonCommand(command)) {
+    runtimes.python = executableVersion(command, ['--version']);
+  }
+
+  if (isNpmCommand(base) || isNpxCommand(base)) {
+    runtimes.npm = executableVersion('npm', ['--version']);
+  }
+
+  if (base === 'uv' || base === 'uvx') {
+    runtimes.uv = executableVersion(base === 'uvx' ? 'uv' : command, ['--version']);
+  }
+
+  if (base === 'docker') {
+    runtimes.docker = executableVersion(command, ['--version']);
+  }
+
+  return runtimes;
+}
+
+function executableVersion(command, args) {
+  const cacheKey = JSON.stringify([command, args]);
+  if (VERSION_PROBE_CACHE.has(cacheKey)) {
+    return { ...VERSION_PROBE_CACHE.get(cacheKey) };
+  }
+
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    timeout: 1000,
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  const version = {
+    command,
+    version: output.split(/\r?\n/)[0] || '',
+    available: !result.error && result.status === 0 && result.signal === null,
+    status: result.status,
+    signal: result.signal
+  };
+  VERSION_PROBE_CACHE.set(cacheKey, version);
+  return { ...version };
+}
+
+function detectPackageMetadata(commandWithArgs, cwd) {
+  const command = commandWithArgs[0] || '';
+  const args = commandWithArgs.slice(1);
+  const base = path.basename(command).toLowerCase();
+
+  if (isNpxCommand(base)) {
+    return packageFromSpec('npm', firstPackageSpec(args));
+  }
+
+  if (isNpmCommand(base)) {
+    const subcommand = args[0] || '';
+    if (subcommand === 'exec' || subcommand === 'x') {
+      return packageFromSpec('npm', firstPackageSpec(args.slice(1)));
+    }
+  }
+
+  if (base === 'uvx') {
+    return packageFromSpec('uv', firstPackageSpec(args));
+  }
+
+  if (base === 'docker') {
+    const image = dockerImageSpec(args);
+    return image ? { manager: 'docker', name: image, versionSpec: '' } : null;
+  }
+
+  if (isNodeCommand(command)) {
+    const entrypoint = nodeEntrypointArg(args);
+    return entrypoint ? localPackageMetadata(path.resolve(cwd, entrypoint)) : null;
+  }
+
+  return null;
+}
+
+function firstPackageSpec(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--') continue;
+
+    if (arg.startsWith('--package=')) {
+      return arg.slice('--package='.length);
+    }
+
+    if (arg === '--package' || arg === '-p') {
+      return args[index + 1] || '';
+    }
+
+    if (arg.startsWith('-')) {
+      continue;
+    }
+
+    return arg;
+  }
+
+  return '';
+}
+
+function nodeEntrypointArg(args) {
+  let afterSeparator = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (!afterSeparator && arg === '--') {
+      afterSeparator = true;
+      continue;
+    }
+
+    if (!afterSeparator && arg.startsWith('-')) {
+      const optionName = arg.split('=')[0];
+      if (NODE_EVAL_OPTIONS.has(optionName)) {
+        return '';
+      }
+      if (NODE_OPTIONS_WITH_VALUES.has(optionName) && !arg.includes('=') && index + 1 < args.length) {
+        index += 1;
+      }
+      continue;
+    }
+
+    return arg;
+  }
+
+  return '';
+}
+
+function packageFromSpec(manager, spec) {
+  if (!spec) return null;
+  const parsed = parsePackageSpec(spec);
+  return {
+    manager,
+    name: parsed.name,
+    versionSpec: parsed.versionSpec
+  };
+}
+
+function parsePackageSpec(spec) {
+  if (spec.startsWith('@')) {
+    const versionAt = spec.indexOf('@', 1);
+    if (versionAt > -1) {
+      return {
+        name: spec.slice(0, versionAt),
+        versionSpec: spec.slice(versionAt + 1)
+      };
+    }
+    return { name: spec, versionSpec: '' };
+  }
+
+  const versionAt = spec.lastIndexOf('@');
+  if (versionAt > 0) {
+    return {
+      name: spec.slice(0, versionAt),
+      versionSpec: spec.slice(versionAt + 1)
+    };
+  }
+
+  return { name: spec, versionSpec: '' };
+}
+
+function dockerImageSpec(args) {
+  const runIndex = args.indexOf('run');
+  if (runIndex === -1) return '';
+  const optionsWithValues = new Set([
+    '-e',
+    '--env',
+    '-h',
+    '--hostname',
+    '-p',
+    '--publish',
+    '-u',
+    '--user',
+    '-v',
+    '--volume',
+    '-w',
+    '--workdir',
+    '--entrypoint',
+    '--name',
+    '--network',
+    '--platform'
+  ]);
+
+  for (let index = runIndex + 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--') continue;
+    if (arg.startsWith('-')) {
+      const optionName = arg.split('=')[0];
+      if (optionsWithValues.has(optionName) && !arg.includes('=') && index + 1 < args.length) {
+        index += 1;
+      }
+      continue;
+    }
+    return arg;
+  }
+
+  return '';
+}
+
+function localPackageMetadata(entry) {
+  const packageJson = findNearestPackageJson(fs.existsSync(entry) && fs.statSync(entry).isDirectory() ? entry : path.dirname(entry));
+  if (!packageJson) return null;
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(packageJson, 'utf8'));
+    return {
+      manager: 'local',
+      name: typeof parsed.name === 'string' ? parsed.name : '',
+      versionSpec: typeof parsed.version === 'string' ? parsed.version : ''
+    };
+  } catch {
+    return null;
+  }
+}
+
+function findNearestPackageJson(start) {
+  let dir = path.resolve(start);
+  while (dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, 'package.json');
+    if (fs.existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  return '';
+}
+
+function isNodeCommand(command) {
+  const base = path.basename(command).toLowerCase();
+  return base === 'node' || base === 'node.exe' || command === process.execPath;
+}
+
+function isPythonCommand(command) {
+  const base = path.basename(command).toLowerCase();
+  return /^python(?:\d+(?:\.\d+)*)?(?:\.exe)?$/.test(base);
+}
+
+function isNpmCommand(base) {
+  return base === 'npm' || base === 'npm.cmd' || base === 'npm-cli.js';
+}
+
+function isNpxCommand(base) {
+  return base === 'npx' || base === 'npx.cmd';
+}
+
+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 ?? []);
+  result.ok = !result.issues.some((issue) => issue.severity === 'error');
+  result.checks = buildChecks(result);
+  result.issueClasses = buildIssueClasses(result.issues);
+  finalizeFingerprint(result);
+  return result;
+}
+
+function finalizeFingerprint(result) {
+  if (!result.fingerprint) return;
+  result.fingerprint.timings ??= {};
+  result.fingerprint.timings.totalMs = result.durationMs ?? result.fingerprint.timings.totalMs ?? null;
+
+  if (Array.isArray(result.runs)) {
+    result.fingerprint.runs = result.runs.map((run) => ({
+      run: run.run,
+      ok: run.ok,
+      startupMs: run.fingerprint?.timings?.startupMs ?? null,
+      totalMs: run.durationMs ?? run.fingerprint?.timings?.totalMs ?? null
+    }));
+  }
+}
+
+function normalizeIssues(issues) {
+  return issues.map((issue) => ({
+    ...issue,
+    class: classifyIssueCode(issue.code)
+  }));
+}
+
+function buildChecks(result) {
+  const issues = result.issues ?? [];
+  const repeated = Array.isArray(result.runs);
+
+  return {
+    initialize: repeated
       ? aggregateRunCheck(result, 'initialize')
       : buildInitializeCheck(result, issues),
     stdout: buildIssueCheck(issues, (issue) => STDOUT_ISSUE_CODES.has(issue.code)),
@@ -530,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),
@@ -537,6 +2078,13 @@ function buildChecks(result) {
   };
 }
 
+function buildIssueClasses(issues) {
+  return Object.fromEntries(ISSUE_CLASS_NAMES.map((className) => [
+    className,
+    buildIssueCheck(issues, (issue) => issue.class === className)
+  ]));
+}
+
 function buildInitializeCheck(result, issues) {
   const matched = issues.filter((issue) => (
     INITIALIZE_ISSUE_CODES.has(issue.code)
@@ -548,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', []);
   }
 
@@ -558,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) {
@@ -591,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
@@ -634,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,
@@ -642,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);
@@ -651,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
         });
       }
     }
@@ -665,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 (['.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 (/\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 (/\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 = [];
@@ -738,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)) {
@@ -760,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) {
@@ -812,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