mcp-stdio-guard 0.1.0 → 0.2.0

package/README.md

@@ -77,6 +77,12 @@ JSON output for CI:
 mcp-stdio-guard --json --request tools/list -- node ./server.js
 ```
 
+Repeat the same guard to catch cold/warm startup behavior:
+
+```bash
+mcp-stdio-guard --repeat 2 --request tools/list -- node ./server.js
+```
+
 ## What It Catches
 
 <p align="center">
@@ -86,6 +92,7 @@ mcp-stdio-guard --json --request tools/list -- node ./server.js
 | Problem | Runtime check | Static scan |
 | --- | --- | --- |
 | `console.log("starting")` before server startup | Yes | Yes |
+| Dependency/import-time stdout pollution | Yes with `--repeat` | No |
 | Python `print("debug")` in a stdio server | Yes | Yes |
 | Late stdout logs after `initialize` | Yes | Partial |
 | Invalid JSON-RPC frames | Yes | No |
@@ -116,6 +123,7 @@ mcp-stdio-guard [options] -- <command> [args...]
 | --- | --- |
 | `--protocol <version>` | MCP protocol version to send, default `2025-11-25` |
 | `--timeout <ms>` | initialize and request timeout, default `5000` |
+| `--repeat <count>` | run the same guard multiple times to catch cold/warm startup behavior |
 | `--request <method>` | send one MCP request after initialization, for example `tools/list` |
 | `--params <json>` | JSON params for `--request` |
 | `--scan <path>` | scan source for risky stdout writes |
@@ -124,6 +132,48 @@ mcp-stdio-guard [options] -- <command> [args...]
 | `--cwd <path>` | run the server command from a specific directory |
 | `--help` | show help |
 
+## JSON Contract
+
+`--json` is intended for CI, registries, and badge ingestion. The current contract is `schemaVersion: 1`; new fields may be added, but these fields are stable for consumers:
+
+| Field | Meaning |
+| --- | --- |
+| `schemaVersion` | JSON contract version, currently `1` |
+| `ok` | `true` when no error-severity issue was found |
+| `command` | command and arguments that were validated |
+| `protocol` | MCP protocol version sent by the guard |
+| `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 |
+| `checks` | badge-friendly per-class statuses |
+| `issues` | machine-readable diagnostics with `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.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "checks": {
+    "initialize": { "status": "pass", "issueCodes": [] },
+    "stdout": { "status": "pass", "issueCodes": [] },
+    "jsonRpc": { "status": "pass", "issueCodes": [] },
+    "operation": { "status": "pass", "issueCodes": [] },
+    "process": { "status": "pass", "issueCodes": [] },
+    "pythonBuffering": { "status": "pass", "issueCodes": [] },
+    "staticScan": { "status": "skipped", "issueCodes": [] },
+    "repeat": { "status": "skipped", "issueCodes": [] }
+  }
+}
+```
+
+The guard is registry-agnostic. It does not care whether an install command came from Smithery, Glama, GitHub, or a private catalog; it validates the command, working directory, optional source path, and observed stdio behavior.
+
 ## CI
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-stdio-guard",
-  "version": "0.1.0",
+  "version": "0.2.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

@@ -2,9 +2,49 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } 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';
+  } catch {
+    return '0.2.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 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([
+  'response-id-type-mismatch',
+  'stdout-invalid-json-rpc',
+  'stdout-unexpected-request-id'
+]);
+const INITIALIZE_ISSUE_CODES = new Set([
+  'initialize-error',
+  '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'
+]);
 
 export async function runCli(argv) {
   const options = parseArgs(argv);
@@ -23,7 +63,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 +73,18 @@ 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
+    };
     result.staticFindings = scanSource(options.scanPath);
     if (options.failOnStatic) {
       for (const finding of result.staticFindings) {
@@ -48,7 +97,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 +119,7 @@ export function parseArgs(argv) {
     failOnStatic: false,
     requestMethod: '',
     requestParams: undefined,
+    repeat: 1,
     json: false,
     help: false,
     version: false,
@@ -104,6 +154,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 +172,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 +183,40 @@ 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');
+  }
+
+  for (let index = 1; index <= repeat; index += 1) {
+    const run = await guardStdioServer(commandWithArgs, options);
+    run.run = index;
+    runs.push(run);
+    for (const issue of run.issues) {
+      issues.push({ run: index, ...issue });
+    }
+  }
+
+  return finalizeResult({
+    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: Date.now() - startedAt
+  });
+}
+
 export async function guardStdioServer(commandWithArgs, options = {}) {
   const startedAt = Date.now();
   const command = commandWithArgs[0];
@@ -133,6 +224,7 @@ 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 = [];
@@ -143,6 +235,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
   let child;
 
   const result = {
+    schemaVersion: JSON_SCHEMA_VERSION,
     ok: false,
     command: commandWithArgs,
     protocol,
@@ -157,7 +250,9 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       : null,
     frames,
     issues,
+    checks: {},
     stderr: '',
+    staticScan: defaultStaticScan(),
     staticFindings: [],
     durationMs: 0
   };
@@ -186,7 +281,7 @@ 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');
+      finalizeResult(result);
       if (child && !child.killed && child.exitCode === null) {
         endedByGuard = true;
         child.kill('SIGTERM');
@@ -198,9 +293,14 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       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']
     });
 
@@ -217,6 +317,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
       const lines = stdoutBuffer.split(/\r?\n/);
       stdoutBuffer = lines.pop() ?? '';
       for (const line of lines) {
+        if (result.durationMs) break;
         handleStdoutLine(line);
       }
     });
@@ -226,6 +327,7 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
     });
 
     child.on('exit', (code, signal) => {
+      if (result.durationMs) return;
       clearTimeout(timer);
       if (stdoutBuffer.trim()) {
         addIssue('error', 'stdout-without-newline', `stdout ended with an incomplete JSON-RPC frame: ${quote(stdoutBuffer)}`);
@@ -262,6 +364,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,8 +386,21 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
 
       frames.push(message);
 
+      if (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) {
         clearTimeout(timer);
+        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();
@@ -303,8 +424,18 @@ export async function guardStdioServer(commandWithArgs, options = {}) {
         } else {
           finishSoon();
         }
+      } else if (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) {
         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;
@@ -316,6 +447,38 @@ 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 isResponseIdTypeMismatch(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 +493,10 @@ export function validateJsonRpc(message) {
   const hasResult = Object.hasOwn(message, 'result');
   const hasError = Object.hasOwn(message, 'error');
 
+  if (hasMethod && (hasResult || hasError)) {
+    return 'request/notification frame must not include result or error';
+  }
+
   if (hasId && !hasMethod && !hasResult && !hasError) {
     return 'response frame must include result or error';
   }
@@ -341,6 +508,140 @@ 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 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 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 +715,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 +752,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 +806,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