mcp-stdio-guard 0.1.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>
@@ -77,6 +78,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 +93,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 +124,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 +133,151 @@ 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 |
+| `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 |
+| `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": [] },
+    "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.3.0",
   "description": "A runtime zero-dependency CLI that catches stdout pollution and handshake failures in MCP stdio servers.",
   "type": "module",
   "bin": {