mcp-stdio-guard 0.1.0 → 0.3.0

package/src/index.js

@@ -1,10 +1,128 @@
 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.3.0';
+  } catch {
+    return '0.3.0';
+  }
+}
 
 const DEFAULT_PROTOCOL = '2025-11-25';
 const DEFAULT_TIMEOUT = 5000;
-const VERSION = '0.1.0';
+const VERSION = loadVersion();
+const JSON_SCHEMA_VERSION = 1;
+const REDACTED = '<redacted>';
+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',
+  'stdout-content-length-framing',
+  'stdout-invalid-json-rpc',
+  'stdout-non-json',
+  'stdout-unexpected-request-id',
+  '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 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'
+]);
+const OPERATION_ISSUE_CODES = new Set([
+  'operation-error',
+  'operation-missing-response',
+  'operation-timeout'
+]);
+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],
+  ['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);
@@ -23,7 +141,7 @@ export async function runCli(argv) {
     throw new Error('Missing command. Use: mcp-stdio-guard -- <command> [args...]');
   }
 
-  const result = await guardStdioServer(options.command, {
+  const guardOptions = {
     protocol: options.protocol,
     timeoutMs: options.timeoutMs,
     cwd: options.cwd,
@@ -33,9 +151,21 @@ export async function runCli(argv) {
           params: options.requestParams
         }
       : null
-  });
+  };
+
+  const result = options.repeat > 1
+    ? await guardRepeatedStdioServer(options.command, { ...guardOptions, repeat: options.repeat })
+    : await guardStdioServer(options.command, guardOptions);
 
   if (options.scanPath) {
+    result.staticScan = {
+      enabled: true,
+      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) {
@@ -48,7 +178,7 @@ export async function runCli(argv) {
     }
   }
 
-  result.ok = !result.issues.some((issue) => issue.severity === 'error');
+  finalizeResult(result);
 
   if (options.json) {
     console.log(JSON.stringify(result, null, 2));
@@ -70,6 +200,7 @@ export function parseArgs(argv) {
     failOnStatic: false,
     requestMethod: '',
     requestParams: undefined,
+    repeat: 1,
     json: false,
     help: false,
     version: false,
@@ -104,6 +235,9 @@ export function parseArgs(argv) {
     } else if (arg === '--timeout') {
       options.timeoutMs = Number(readOptionValue(argv, index, arg));
       index += 1;
+    } else if (arg === '--repeat') {
+      options.repeat = Number(readOptionValue(argv, index, arg));
+      index += 1;
     } else if (arg === '--scan') {
       options.scanPath = path.resolve(readOptionValue(argv, index, arg));
       index += 1;
@@ -119,6 +253,10 @@ export function parseArgs(argv) {
     throw new Error('--timeout must be an integer >= 100');
   }
 
+  if (!Number.isInteger(options.repeat) || options.repeat < 1) {
+    throw new Error('--repeat must be an integer >= 1');
+  }
+
   if (options.requestParams !== undefined && !options.requestMethod) {
     throw new Error('--params can only be used with --request');
   }
@@ -126,6 +264,46 @@ export function parseArgs(argv) {
   return options;
 }
 
+export async function guardRepeatedStdioServer(commandWithArgs, options = {}) {
+  const startedAt = Date.now();
+  const repeat = options.repeat ?? 1;
+  const runs = [];
+  const issues = [];
+
+  if (!Number.isInteger(repeat) || repeat < 1) {
+    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, singleRunOptions);
+    run.run = index;
+    runs.push(run);
+    for (const issue of run.issues) {
+      issues.push({ run: index, ...issue });
+    }
+  }
+
+  const durationMs = Date.now() - startedAt;
+  const result = {
+    schemaVersion: JSON_SCHEMA_VERSION,
+    ok: !issues.some((issue) => issue.severity === 'error'),
+    command: commandWithArgs,
+    protocol: options.protocol ?? DEFAULT_PROTOCOL,
+    repeat,
+    runs,
+    issues,
+    checks: {},
+    staticScan: defaultStaticScan(),
+    staticFindings: [],
+    durationMs,
+    fingerprint: createFingerprint(commandWithArgs, options)
+  };
+  result.fingerprint.timings.totalMs = durationMs;
+  return finalizeResult(result);
+}
+
 export async function guardStdioServer(commandWithArgs, options = {}) {
   const startedAt = Date.now();
   const command = commandWithArgs[0];
@@ -133,16 +311,19 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT;
   const protocol = options.protocol ?? DEFAULT_PROTOCOL;
   const operation = options.operation || null;
+  const env = { ...process.env, ...(options.env ?? {}) };
   const issues = [];
   const frames = [];
   const stderrChunks = [];
   let stdoutBuffer = '';
   let initialized = false;
   let endedByGuard = false;
+  let initializeResponseAt = 0;
   let timer;
   let child;
 
   const result = {
+    schemaVersion: JSON_SCHEMA_VERSION,
     ok: false,
     command: commandWithArgs,
     protocol,
@@ -157,20 +338,35 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       : null,
     frames,
     issues,
+    checks: {},
     stderr: '',
+    process: defaultProcessInfo(timeoutMs),
+    staticScan: defaultStaticScan(),
     staticFindings: [],
-    durationMs: 0
+    durationMs: 0,
+    fingerprint: createFingerprint(commandWithArgs, {
+      protocol,
+      timeoutMs,
+      cwd: options.cwd,
+      operation,
+      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) {
       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));
         finish();
       }, timeoutMs);
     }
@@ -186,8 +382,19 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       result.durationMs = Date.now() - startedAt;
       result.stderr = Buffer.concat(stderrChunks).toString('utf8');
       result.initialized = initialized;
-      result.ok = !issues.some((issue) => issue.severity === 'error');
-      if (child && !child.killed && child.exitCode === null) {
+      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 (willTerminate) {
         endedByGuard = true;
         child.kill('SIGTERM');
       }
@@ -195,28 +402,54 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
     }
 
     function send(message) {
+      if (!child?.stdin?.writable) return;
       child.stdin.write(`${JSON.stringify(message)}\n`);
     }
 
+    const pythonBufferingIssue = detectPythonBufferingIssue(commandWithArgs, env);
+    if (pythonBufferingIssue) {
+      addIssue('warning', 'python-buffered-stdio', pythonBufferingIssue);
+    }
+
     child = spawn(command, args, {
       cwd: options.cwd ?? process.cwd(),
-      env: process.env,
+      env,
       stdio: ['pipe', 'pipe', 'pipe']
     });
+    result.process.pid = child.pid ?? null;
 
-    armTimeout('initialize-timeout', `no initialize response within ${timeoutMs}ms`);
+    armTimeout('initialize-timeout', `no initialize response within ${timeoutMs}ms`, 'initialize');
+
+    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/);
       stdoutBuffer = lines.pop() ?? '';
       for (const line of lines) {
+        if (result.durationMs) break;
         handleStdoutLine(line);
       }
     });
@@ -226,18 +459,28 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
     });
 
     child.on('exit', (code, signal) => {
+      if (result.durationMs) return;
       clearTimeout(timer);
+      const exitPhase = initialized
+        ? result.operation && !result.operation.responded
+          ? '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`);
+        addIssue('error', 'operation-missing-response', `${result.operation.method} did not receive a response before server exit`, exitIssueDetails('during-operation', code, signal));
       }
-      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();
     });
@@ -262,6 +505,12 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
         return;
       }
 
+      if (/^Content-Length\s*:/i.test(line)) {
+        addIssue('error', 'stdout-content-length-framing', 'stdout looks like LSP-style Content-Length framing; MCP stdio expects newline-delimited JSON-RPC frames');
+        finish();
+        return;
+      }
+
       let message;
       try {
         message = JSON.parse(line);
@@ -278,15 +527,46 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
 
       frames.push(message);
 
-      if (message.id === 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 (!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();
+          return;
+        }
+
         if (message.error) {
           addIssue('error', 'initialize-error', `initialize returned error: ${message.error.message || JSON.stringify(message.error)}`);
           finish();
           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;
+        result.process.phase = operation ? 'operation' : 'post-initialize';
         result.negotiatedProtocol = message.result?.protocolVersion || '';
         send({ jsonrpc: '2.0', method: 'notifications/initialized' });
         if (operation) {
@@ -299,13 +579,32 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
             request.params = operation.params;
           }
           send(request);
-          armTimeout('operation-timeout', `no ${operation.method} response within ${timeoutMs}ms`);
+          armTimeout('operation-timeout', `no ${operation.method} response within ${timeoutMs}ms`, 'operation');
         } else {
           finishSoon();
         }
-      } else if (operation && message.id === 2) {
+      } else if (initialized && !operation && isJsonRpcResponse(message)) {
+        clearTimeout(timer);
+        addIssue('error', 'notification-response', 'server sent a JSON-RPC response after notifications/initialized without an outstanding request');
+        finish();
+      } else if (initialized && operation && isResponseIdTypeMismatch(message, 2)) {
+        clearTimeout(timer);
+        addIssue('error', 'response-id-type-mismatch', `${operation.method} response id ${JSON.stringify(message.id)} does not exactly match request id 2`);
+        finish();
+      } else if (initialized && operation && isResponseIdMismatch(message, 2)) {
         clearTimeout(timer);
+        addIssue('error', 'response-id-mismatch', `${operation.method} response id ${JSON.stringify(message.id)} does not match request id 2`);
+        finish();
+      } else if (initialized && operation && message.id === 2) {
+        clearTimeout(timer);
+        if (!isJsonRpcResponse(message)) {
+          addIssue('error', 'stdout-unexpected-request-id', `stdout frame with id 2 is not a ${operation.method} response`);
+          finish();
+          return;
+        }
+
         result.operation.responded = true;
+        result.process.phase = 'post-initialize';
         if (message.error) {
           result.operation.error = message.error;
           addIssue('warning', 'operation-error', `${operation.method} returned error: ${message.error.message || JSON.stringify(message.error)}`);
@@ -316,6 +615,91 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
   });
 }
 
+export function detectPythonBufferingIssue(commandWithArgs, env = process.env) {
+  const command = commandWithArgs[0] || '';
+  const args = commandWithArgs.slice(1);
+  const basename = path.basename(command).toLowerCase();
+
+  if (!/^python(?:\d+(?:\.\d+)*)?(?:\.exe)?$/.test(basename)) {
+    return '';
+  }
+
+  if (Object.hasOwn(env, 'PYTHONUNBUFFERED') && String(env.PYTHONUNBUFFERED) !== '') {
+    return '';
+  }
+
+  if (args.some((arg) => arg === '-u' || /^-[^-]*u/.test(arg))) {
+    return '';
+  }
+
+  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' : 'startup-timeout',
+    phase,
+    timeoutMs
+  };
+}
+
+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');
+}
+
+function hasResponsePayload(message) {
+  return Object.hasOwn(message, 'result') || Object.hasOwn(message, 'error');
+}
+
 export function validateJsonRpc(message) {
   if (!message || typeof message !== 'object' || Array.isArray(message)) {
     return 'JSON-RPC frame must be an object';
@@ -330,6 +714,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';
   }
@@ -341,6 +757,584 @@ export function validateJsonRpc(message) {
   return '';
 }
 
+function isJsonRpcId(id) {
+  return id === null || typeof id === 'string' || (typeof id === 'number' && Number.isInteger(id));
+}
+
+function validateInitializeResult(result) {
+  const issues = [];
+
+  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;
+}
+
+export function classifyIssueCode(code) {
+  return ISSUE_CLASS_BY_CODE.get(code) ?? ISSUE_CLASSES.MCP_PROTOCOL;
+}
+
+export function createFingerprint(commandWithArgs, options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const operation = options.operation || null;
+
+  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,
+    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT,
+    repeat: options.repeat ?? 1,
+    operation: operation
+      ? {
+          method: operation.method,
+          hasParams: operation.params !== undefined
+        }
+      : null,
+    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.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)),
+    jsonRpc: buildIssueCheck(issues, (issue) => JSON_RPC_ISSUE_CODES.has(issue.code)),
+    operation: repeated
+      ? aggregateRunCheck(result, 'operation')
+      : buildOperationCheck(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),
+    repeat: buildRepeatCheck(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)
+    || (!result.initialized && STDOUT_ISSUE_CODES.has(issue.code))
+    || (!result.initialized && JSON_RPC_ISSUE_CODES.has(issue.code))
+  ));
+  if (matched.length) return makeCheck(statusFromIssues(matched), matched);
+  return makeCheck(result.initialized ? 'pass' : 'fail', []);
+}
+
+function buildOperationCheck(result, issues) {
+  if (!result.operation) {
+    return makeCheck('skipped', []);
+  }
+
+  if (!result.initialized) {
+    return makeCheck('skipped', []);
+  }
+
+  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))
+  ));
+  if (matched.length) {
+    return makeCheck(statusFromIssues(matched), matched);
+  }
+
+  return makeCheck(result.operation.responded ? 'pass' : 'fail', []);
+}
+
+function buildStaticScanCheck(result, issues) {
+  if (!result.staticScan?.enabled) {
+    return makeCheck('skipped', []);
+  }
+
+  const matched = issues.filter((issue) => issue.code === 'static-stdout-write');
+  if (matched.length) {
+    return makeCheck(statusFromIssues(matched), matched);
+  }
+
+  if (result.staticFindings?.length) {
+    return makeCheck('warning', [{ code: 'static-stdout-write' }]);
+  }
+
+  return makeCheck('pass', []);
+}
+
+function buildRepeatCheck(result) {
+  if (!Array.isArray(result.runs)) {
+    return makeCheck('skipped', []);
+  }
+
+  const failedRuns = result.runs.filter((run) => !run.ok).map((run) => run.run);
+  return {
+    ...makeCheck(failedRuns.length ? 'fail' : 'pass', result.issues ?? []),
+    runs: result.runs.length,
+    passedRuns: result.runs.length - failedRuns.length,
+    failedRuns
+  };
+}
+
+function aggregateRunCheck(result, checkName) {
+  const checks = result.runs
+    .map((run) => run.checks?.[checkName])
+    .filter(Boolean)
+    .filter((check) => check.status !== 'skipped');
+
+  if (!checks.length) {
+    return makeCheck('skipped', []);
+  }
+
+  const status = checks.some((check) => check.status === 'fail')
+    ? 'fail'
+    : checks.some((check) => check.status === 'warning')
+      ? 'warning'
+      : 'pass';
+  const issueCodes = [...new Set(checks.flatMap((check) => check.issueCodes))].sort();
+  return { status, issueCodes };
+}
+
+function buildIssueCheck(issues, predicate) {
+  const matched = issues.filter(predicate);
+  return makeCheck(matched.length ? statusFromIssues(matched) : 'pass', matched);
+}
+
+function statusFromIssues(issues) {
+  return issues.some((issue) => issue.severity === 'error') ? 'fail' : 'warning';
+}
+
+function makeCheck(status, issues) {
+  return {
+    status,
+    issueCodes: [...new Set(issues.map((issue) => issue.code))].sort()
+  };
+}
+
+function defaultStaticScan() {
+  return {
+    enabled: false,
+    path: '',
+    failOnFindings: false
+  };
+}
+
 export function scanSource(root) {
   const findings = [];
   const absoluteRoot = path.resolve(root);
@@ -414,6 +1408,10 @@ function listSourceFiles(root) {
 }
 
 function formatTextResult(result) {
+  if (Array.isArray(result.runs)) {
+    return formatRepeatedTextResult(result);
+  }
+
   const status = result.ok ? 'PASS' : 'FAIL';
   const invalidFrames = result.issues.filter((issue) => issue.code.startsWith('stdout-')).length;
   const stderrLines = result.stderr ? result.stderr.trim().split(/\r?\n/).filter(Boolean).length : 0;
@@ -447,6 +1445,36 @@ function formatTextResult(result) {
   return lines.join('\n');
 }
 
+function formatRepeatedTextResult(result) {
+  const status = result.ok ? 'PASS' : 'FAIL';
+  const passedRuns = result.runs.filter((run) => run.ok).length;
+  const lines = [
+    `${status} MCP stdio guard`,
+    `runs: ${passedRuns}/${result.runs.length} passed`
+  ];
+
+  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`);
+  }
+
+  if (result.staticFindings.length) {
+    lines.push(`static findings: ${result.staticFindings.length}`);
+    for (const finding of result.staticFindings.slice(0, 10)) {
+      lines.push(`[warning] ${finding.file}:${finding.line} ${finding.message}`);
+    }
+  }
+
+  for (const issue of result.issues) {
+    const prefix = issue.run ? `run ${issue.run} ` : '';
+    lines.push(`[${issue.severity}] ${prefix}${issue.code}: ${issue.message}`);
+  }
+
+  return lines.join('\n');
+}
+
 function readOptionValue(argv, index, option) {
   const value = argv[index + 1];
   if (!value || value.startsWith('--')) {
@@ -471,12 +1499,15 @@ function quote(value) {
 function helpText() {
   return `mcp-stdio-guard validates MCP stdio servers.
 
+MCP stdio output is expected as newline-delimited JSON-RPC on stdout.
+
 Usage:
   mcp-stdio-guard [options] -- <command> [args...]
 
 Options:
   --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
   --scan <path>          scan source for risky stdout writes
   --fail-on-static       fail when --scan finds risky stdout writes
   --request <method>     send one MCP request after initialize, e.g. tools/list