mcp-stdio-guard 0.2.0 → 0.3.0

package/README.md

@@ -11,6 +11,7 @@
 <p align="center">
   <a href="https://github.com/1Utkarsh1/mcp-stdio-guard/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/1Utkarsh1/mcp-stdio-guard/actions/workflows/ci.yml/badge.svg" /></a>
   <a href="https://www.npmjs.com/package/mcp-stdio-guard"><img alt="npm" src="https://img.shields.io/npm/v/mcp-stdio-guard?color=0b6bcb" /></a>
+  <a href="https://badge.socket.dev/npm/package/mcp-stdio-guard/0.3.0"><img alt="Socket" src="https://badge.socket.dev/npm/package/mcp-stdio-guard/0.3.0" /></a>
   <img alt="runtime dependencies" src="https://img.shields.io/badge/runtime%20deps-0-1f8f4c" />
   <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-2f855a" />
   <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-111827" /></a>
@@ -145,20 +146,123 @@ mcp-stdio-guard [options] -- <command> [args...]
 | `negotiatedProtocol` | protocol version returned by the server, when available |
 | `initialized` | whether the server completed the initialize handshake |
 | `operation` | post-initialize request result, or `null` when `--request` was not used |
+| `process` | startup, timeout, exit code, signal, and guard-termination metadata for a single run; repeat mode exposes this inside each `runs` entry |
 | `checks` | badge-friendly per-class statuses |
-| `issues` | machine-readable diagnostics with `severity`, `code`, and `message`; repeat mode also adds `run` |
+| `issueClasses` | registry-friendly summary grouped by `installRuntime`, `stdioTransport`, and `mcpProtocol` |
+| `fingerprint` | redacted reproducibility metadata for debugging registry and CI runs |
+| `issues` | machine-readable diagnostics with `class`, `severity`, `code`, and `message`; repeat mode also adds `run` |
 | `staticScan` | whether source scanning was enabled and whether findings fail the command |
 | `staticFindings` | source scan findings with file, line, and message |
 | `runs` | per-run results when `--repeat` is used |
 
 Check statuses are `pass`, `fail`, `warning`, or `skipped`. The `checks` object separates the signal into `initialize`, `stdout`, `jsonRpc`, `operation`, `process`, `pythonBuffering`, `staticScan`, and `repeat`, each with stable `status` and `issueCodes` fields. When `--repeat` is used, `checks.repeat` also includes `runs`, `passedRuns`, and `failedRuns`; each entry in `runs` is a normal schema-versioned result for that individual guard run.
 
+`issueClasses` is additive to `checks`. It groups issue codes by the kind of problem a registry or client should display:
+
+| Issue class | Meaning | Display guidance |
+| --- | --- | --- |
+| `installRuntime` | the command could not start, timed out, exited, crashed, or hit a runtime advisory | show as "needs inspection" or "runtime/install issue"; do not present it as an MCP protocol violation |
+| `stdioTransport` | stdout was not a clean newline-delimited JSON-RPC channel, or source scan found risky stdout writes | show as stdio hygiene failure; ask maintainers to keep diagnostics on stderr |
+| `mcpProtocol` | the server emitted invalid JSON-RPC/MCP responses, mismatched request ids, or returned initialize/operation errors | show as MCP/JSON-RPC conformance issue |
+
+Current issue-code mapping:
+
+| Issue class | Issue codes |
+| --- | --- |
+| `installRuntime` | `initialize-timeout`, `operation-missing-response`, `operation-timeout`, `python-buffered-stdio`, `server-crashed`, `server-exited`, `spawn-failed` |
+| `stdioTransport` | `static-stdout-write`, `stdout-content-length-framing`, `stdout-empty-line`, `stdout-non-json`, `stdout-without-newline` |
+| `mcpProtocol` | `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`, `notification-response`, `operation-error`, `response-id-mismatch`, `response-id-type-mismatch`, `stdout-invalid-json-rpc`, `stdout-unexpected-request-id` |
+
+Initialize lifecycle checks are part of the MCP protocol class. Missing or invalid `protocolVersion` and `capabilities` fail the run before the guard sends `notifications/initialized` or any normal request. Missing or invalid `serverInfo` is warning-level so registries can surface incomplete metadata without confusing it with a broken transport.
+
+JSON-RPC invariant checks distinguish wrong response ids from id type round-trip problems and fail servers that respond to `notifications/initialized`. JSON-RPC error frames must be structured with numeric `code` and string `message` fields.
+
+Runtime issue codes remain backward-compatible. For finer registry display, runtime issues may also include a stable `detailCode`:
+
+| Existing issue code | Detail codes |
+| --- | --- |
+| `spawn-failed` | `spawn-failed-before-startup` |
+| `server-exited` | `clean-exit-before-initialize`, `nonzero-exit-before-initialize`, `signal-exit-before-initialize` |
+| `initialize-timeout` | `startup-timeout` |
+| `operation-timeout` | `request-timeout` |
+| `operation-missing-response` | `clean-exit-during-operation`, `nonzero-exit-during-operation`, `signal-exit-during-operation` |
+| `server-crashed` | `nonzero-exit-after-initialize`, `signal-exit-after-initialize` |
+
+`process` records the observed lifecycle even when the run passes. `outcome` is one of `starting`, `running`, `exited`, `timeout`, `spawn-failed`, or `guard-terminated`; `starting` is the transient initial value while the child is being created, not an expected terminal outcome. `phase` is `startup`, `initialize`, `operation`, or `post-initialize`. `exitCode` and `signal` are included when the process exits before the guard finishes; timeout runs include `timedOut`, `timeoutCode`, `timeoutMs`, and guard kill metadata. `spawnError` is either `null` or an object with `code` and `message`; the matching `spawn-failed` issue also exposes `spawnErrorCode`.
+
+Spawn failure shape:
+
+| Field | Shape |
+| --- | --- |
+| `process.spawnError` | `null` or `{ "code": "ENOENT", "message": "spawn missing-command ENOENT" }` |
+| `issues[].spawnErrorCode` | short platform error code such as `ENOENT`, or `""` when unavailable |
+
+`fingerprint` helps explain why a result reproduced in one runner but not another. It includes the guard version, redacted command argv, cwd details, protocol, timeout, repeat count, requested operation, platform/arch, relevant runtime versions, package metadata when detectable, static-scan context, and startup/total duration. Environment variable values are always emitted as `<redacted>` and only explicitly provided env names are listed.
+
+Registry display flow:
+
+| Step | Use |
+| --- | --- |
+| 1 | Show `issueClasses` first so install/runtime, stdio transport, and MCP protocol failures stay distinct |
+| 2 | Use `fingerprint.command`, `fingerprint.cwd`, and `fingerprint.package` to show what was actually run |
+| 3 | Compare `fingerprint.system`, `fingerprint.runtimes`, and `fingerprint.timings` before marking a package broken |
+| 4 | Show `fingerprint.env.names` only when debugging; never ask users to paste secret values |
+
 Example:
 
 ```json
 {
   "schemaVersion": 1,
   "ok": true,
+  "fingerprint": {
+    "guard": { "name": "mcp-stdio-guard", "version": "0.3.0" },
+    "command": {
+      "executable": "node",
+      "args": ["./server.js"],
+      "argv": ["node", "./server.js"]
+    },
+    "cwd": {
+      "requested": "/repo/server",
+      "resolved": "/repo/server",
+      "exists": true
+    },
+    "protocol": "2025-11-25",
+    "timeoutMs": 5000,
+    "repeat": 1,
+    "operation": { "method": "tools/list", "hasParams": false },
+    "system": { "platform": "darwin", "arch": "arm64", "osRelease": "25.0.0" },
+    "runtimes": {
+      "node": { "version": "v24.0.0", "role": "guard-and-target" }
+    },
+    "package": null,
+    "env": {
+      "inherited": true,
+      "names": ["API_TOKEN"],
+      "values": { "API_TOKEN": "<redacted>" }
+    },
+    "staticScan": { "enabled": false, "path": "", "failOnFindings": false },
+    "timings": { "startupMs": 42, "totalMs": 96 }
+  },
+  "process": {
+    "started": true,
+    "pid": 12345,
+    "outcome": "guard-terminated",
+    "phase": "post-initialize",
+    "exitCode": null,
+    "signal": null,
+    "timedOut": false,
+    "timeoutCode": "",
+    "timeoutMs": 5000,
+    "killedByGuard": true,
+    "killSignal": "SIGTERM",
+    "killReason": "guard-finished",
+    "spawnError": null
+  },
+  "issueClasses": {
+    "installRuntime": { "status": "pass", "issueCodes": [] },
+    "stdioTransport": { "status": "pass", "issueCodes": [] },
+    "mcpProtocol": { "status": "pass", "issueCodes": [] }
+  },
   "checks": {
     "initialize": { "status": "pass", "issueCodes": [] },
     "stdout": { "status": "pass", "issueCodes": [] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-stdio-guard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A runtime zero-dependency CLI that catches stdout pollution and handshake failures in MCP stdio servers.",
   "type": "module",
   "bin": {

package/src/index.js

@@ -1,13 +1,14 @@
 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.3.0';
   } catch {
-    return '0.2.0';
+    return '0.3.0';
   }
 }
 
@@ -15,6 +16,44 @@ const DEFAULT_PROTOCOL = '2025-11-25';
 const DEFAULT_TIMEOUT = 5000;
 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',
@@ -25,12 +64,21 @@ 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 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'
@@ -45,6 +93,36 @@ const PROCESS_ISSUE_CODES = new Set([
   '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);
@@ -85,6 +163,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) {
@@ -193,8 +274,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,7 +285,8 @@ export async function guardRepeatedStdioServer(commandWithArgs, options = {}) {
     }
   }
 
-  return finalizeResult({
+  const durationMs = Date.now() - startedAt;
+  const result = {
     schemaVersion: JSON_SCHEMA_VERSION,
     ok: !issues.some((issue) => issue.severity === 'error'),
     command: commandWithArgs,
@@ -213,8 +297,11 @@ export async function guardRepeatedStdioServer(commandWithArgs, options = {}) {
     checks: {},
     staticScan: defaultStaticScan(),
     staticFindings: [],
-    durationMs: Date.now() - startedAt
-  });
+    durationMs,
+    fingerprint: createFingerprint(commandWithArgs, options)
+  };
+  result.fingerprint.timings.totalMs = durationMs;
+  return finalizeResult(result);
 }
 
 export async function guardStdioServer(commandWithArgs, options = {}) {
@@ -231,6 +318,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
   let stdoutBuffer = '';
   let initialized = false;
   let endedByGuard = false;
+  let initializeResponseAt = 0;
   let timer;
   let child;
 
@@ -252,20 +340,33 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
     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);
     }
@@ -281,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.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,6 +402,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
     }
 
     function send(message) {
+      if (!child?.stdin?.writable) return;
       child.stdin.write(`${JSON.stringify(message)}\n`);
     }
 
@@ -303,15 +416,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`);
+    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/);
@@ -329,17 +461,26 @@ 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();
     });
@@ -386,15 +527,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,7 +556,17 @@ 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;
+        result.process.phase = operation ? 'operation' : 'post-initialize';
         result.negotiatedProtocol = message.result?.protocolVersion || '';
         send({ jsonrpc: '2.0', method: 'notifications/initialized' });
         if (operation) {
@@ -420,15 +579,23 @@ 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 && isResponseIdTypeMismatch(message, 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 (operation && message.id === 2) {
+      } 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`);
@@ -437,6 +604,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
         }
 
         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)}`);
@@ -467,10 +635,63 @@ 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' : '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');
 }
@@ -493,10 +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';
   }
@@ -508,15 +757,452 @@ 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);
@@ -537,6 +1223,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)