mcp-stdio-guard 0.2.0 → 0.4.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.4.0"><img alt="Socket" src="https://badge.socket.dev/npm/package/mcp-stdio-guard/0.4.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>
@@ -22,7 +23,7 @@
 
 MCP stdio servers use stdout as their protocol channel. Debug text, banners, progress logs, `console.log`, Python `print`, or any other stray stdout output can corrupt the stream and make clients fail in confusing ways.
 
-`mcp-stdio-guard` starts your server, performs a real MCP initialize handshake, optionally sends a real post-initialize MCP request such as `tools/list`, validates every stdout frame, and scans source for risky stdout calls.
+`mcp-stdio-guard` starts your server, performs a real MCP initialize handshake, probes advertised `tools`, `resources`, and `prompts` list capabilities, optionally sends a real post-initialize MCP request such as `tools/list`, validates every stdout frame, checks returned tool metadata, and scans source for risky stdout calls.
 
 ## Why This Exists
 
@@ -59,13 +60,25 @@ Run your MCP server behind the guard:
 mcp-stdio-guard -- node ./server.js
 ```
 
+Use a deterministic profile for common workflows:
+
+```bash
+mcp-stdio-guard --profile registry --json -- node ./server.js
+```
+
+Use a config file for registry runs that need environment names, request lists, or explicitly safe tool calls:
+
+```bash
+mcp-stdio-guard --config mcp-stdio-guard.config.json
+```
+
 Exercise a real MCP operation after initialization:
 
 ```bash
 mcp-stdio-guard --request tools/list -- node ./server.js
 ```
 
-Scan source for obvious stdout writes too:
+Scan source for obvious stdout writes too. Findings are warnings unless `--fail-on-static` is set:
 
 ```bash
 mcp-stdio-guard --scan src --fail-on-static --request tools/list -- node ./server.js
@@ -98,6 +111,8 @@ mcp-stdio-guard --repeat 2 --request tools/list -- node ./server.js
 | Invalid JSON-RPC frames | Yes | No |
 | Server crash after `notifications/initialized` | Yes | No |
 | Missing `initialize` or operation response | Yes | No |
+| Duplicate tool names or invalid `inputSchema.required` | Yes with `--request tools/list` | No |
+| Cold/warm protocol, capability, or tool-list drift | Warning with `--repeat` | No |
 | stderr diagnostics | Allowed | Allowed |
 
 ## Live MCP Coverage
@@ -121,17 +136,74 @@ mcp-stdio-guard [options] -- <command> [args...]
 
 | Option | Description |
 | --- | --- |
+| `--config <path>` | read a JSON config file for registry runs and explicitly safe tool calls |
+| `--profile <name>` | apply a deterministic guard profile: `custom`, `smoke`, `registry`, `ci`, or `strict` |
 | `--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 |
+| `--scan <path>` | scan source for risky stdout writes and visible startup-output risks |
 | `--fail-on-static` | make static scan findings fail the command |
 | `--json` | print machine-readable output |
 | `--cwd <path>` | run the server command from a specific directory |
 | `--help` | show help |
 
+## Profiles
+
+Profiles are deterministic presets for common workflows. Existing CLI behavior remains the default `custom` profile, so current commands keep working unless `--profile` is provided.
+
+| Profile | Behavior |
+| --- | --- |
+| `custom` | preserve explicit CLI flags and legacy defaults |
+| `smoke` | initialize only unless `--request` is provided; skip advertised `tools/list`, `resources/list`, and `prompts/list` probes |
+| `registry` | run advertised list probes and repeat twice by default for cold/warm consistency |
+| `ci` | emit JSON output and make static scan findings fail when `--scan` is used |
+| `strict` | combine CI-style output/static failures with registry-style repeat depth; future adversarial probes will attach here |
+
+Explicit flags can still narrow or deepen a profile. For example, `--profile registry --repeat 1` keeps registry capability probing but disables the repeat preset.
+
+## Config Files
+
+Config files let registries run repeatable checks without hiding what was executed. The file is JSON, and CLI flags still override matching config defaults. Parsing happens before the server process starts, so invalid config does not launch the target command.
+
+Supported fields:
+
+| Field | Meaning |
+| --- | --- |
+| `command` | command as either `["node", "./server.js"]` or `"node"` with `args` |
+| `args` | arguments used only when `command` is a string |
+| `cwd` | working directory, resolved relative to the config file |
+| `env` | environment variables to pass; values are redacted in JSON output |
+| `profile`, `protocol`, `timeoutMs`, `repeat`, `json` | same meaning as CLI options |
+| `scan` or `scanPath` | source scan path, resolved relative to the config file |
+| `failOnStatic` | make static scan findings fail |
+| `request` | one explicit post-initialize request: `{ "method": "tools/list" }` |
+| `requests` | list of explicit post-initialize requests |
+| `safeToolCalls` | opt-in `tools/call` recipes; no tool is called unless listed here or explicitly requested |
+
+Example:
+
+```json
+{
+  "profile": "registry",
+  "command": ["node", "./server.js"],
+  "cwd": ".",
+  "json": true,
+  "env": {
+    "API_TOKEN": "set-in-runner"
+  },
+  "requests": [
+    { "method": "tools/list" }
+  ],
+  "safeToolCalls": [
+    { "name": "echo", "arguments": { "text": "hello" } }
+  ]
+}
+```
+
+The guard does not discover and call arbitrary tools from `tools/list`. Tool execution only happens through an explicit `safeToolCalls` entry or an explicit `tools/call` request you provide.
+
 ## 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:
@@ -140,18 +212,91 @@ mcp-stdio-guard [options] -- <command> [args...]
 | --- | --- |
 | `schemaVersion` | JSON contract version, currently `1` |
 | `ok` | `true` when no error-severity issue was found |
+| `config` | config file metadata and checks used, or `{ "enabled": false, ... }` |
+| `profile` | selected guard profile, for example `custom`, `smoke`, `registry`, `ci`, or `strict` |
 | `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 |
+| `operations` | all explicit post-initialize requests, including config requests and safe tool calls |
+| `toolSchema` | summary of `tools/list` metadata validation when that operation was requested or probed from an advertised tools capability |
+| `capabilityProbes` | whether advertised capability list probes were enabled for this run |
+| `capabilityKeys` | sorted capability keys returned by `initialize` for a single run; repeat mode exposes this inside each `runs` entry |
+| `capabilityChecks` | advertised capability probes observed during a single run; repeat mode exposes this inside each `runs` entry |
+| `drift` | repeat-run comparison summary for negotiated protocol, advertised capabilities, tool names/counts, and resource/prompt list counts |
+| `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 |
+| `staticFindings` | source scan findings with language, file, line, reason, 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.
+Check statuses are `pass`, `fail`, `warning`, or `skipped`. The `checks` object separates the signal into `initialize`, `stdout`, `jsonRpc`, `operation`, `capabilities`, `toolSchema`, `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` | `capability-list-error`, `capability-list-missing-response`, `capability-list-timeout`, `capability-list-unsupported`, `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`, `repeat-capability-drift`, `repeat-list-shape-drift`, `repeat-protocol-drift`, `repeat-tool-drift`, `response-id-mismatch`, `response-id-type-mismatch`, `stdout-invalid-json-rpc`, `stdout-unexpected-request-id`, `tool-description-missing`, `tool-input-schema-invalid`, `tool-input-schema-required-missing`, `tool-name-duplicate`, `tool-name-invalid`, `tools-list-invalid-result` |
+
+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.
+
+Tool schema checks run when `tools/list` receives a successful result, either from `--request tools/list` or from the advertised tools capability probe. Duplicate or invalid tool names, missing `inputSchema`, invalid schema shapes, and `required` entries that are absent from `properties` are MCP protocol failures. Missing tool descriptions are warning-level so registries can show quality guidance without marking the server broken.
+
+Capability honesty checks are additive. If `initialize` advertises `capabilities.tools`, `capabilities.resources`, or `capabilities.prompts`, the guard probes the matching `tools/list`, `resources/list`, or `prompts/list` method after `notifications/initialized`. Unadvertised capabilities are `skipped`, not failed. `capability-list-unsupported` means an advertised list method returned method-not-found; `capability-list-error`, `capability-list-timeout`, and `capability-list-missing-response` mean the advertised list method existed in the contract but failed at runtime.
+
+Repeat drift checks compare successful initialized runs against the first initialized run. Negotiated protocol changes, advertised capability key changes, added or removed tool names, tool count changes, and resource/prompt list count changes are warning-level `repeat-*` issues. Tool order is normalized before comparison, so order-only changes do not warn.
+
+The repeat `drift` object has stable `status`, `issueCodes`, `baselineRun`, and `comparedRuns` fields. Its nested `negotiatedProtocol`, `capabilities`, `tools`, `lists.resources`, and `lists.prompts` sections include `changedRuns` so registries can show exactly what changed between cold and warm starts.
+
+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 | Show `checks.capabilities` as advertised MCP surface honesty |
+| 4 | Show `checks.toolSchema` as tool metadata quality, separate from startup and stdio transport health |
+| 5 | Show `drift` warnings as stability advisories, not hard failures, unless another check failed |
+| 6 | Compare `fingerprint.system`, `fingerprint.runtimes`, and `fingerprint.timings` before marking a package broken |
+| 7 | Show `fingerprint.env.names` only when debugging; never ask users to paste secret values |
 
 Example:
 
@@ -159,11 +304,100 @@ Example:
 {
   "schemaVersion": 1,
   "ok": true,
+  "config": {
+    "enabled": false,
+    "path": "",
+    "resolvedPath": "",
+    "checks": { "command": false, "cwd": false, "envNames": [], "requests": [], "safeToolCalls": [] }
+  },
+  "profile": "custom",
+  "fingerprint": {
+    "guard": { "name": "mcp-stdio-guard", "version": "0.4.0" },
+    "command": {
+      "executable": "node",
+      "args": ["./server.js"],
+      "argv": ["node", "./server.js"]
+    },
+    "cwd": {
+      "requested": "/repo/server",
+      "resolved": "/repo/server",
+      "exists": true
+    },
+    "protocol": "2025-11-25",
+    "config": {
+      "enabled": false,
+      "path": "",
+      "resolvedPath": "",
+      "checks": { "command": false, "cwd": false, "envNames": [], "requests": [], "safeToolCalls": [] }
+    },
+    "profile": "custom",
+    "timeoutMs": 5000,
+    "repeat": 1,
+    "capabilityProbes": true,
+    "operation": { "method": "tools/list", "hasParams": false, "source": "cli-request", "safeToolCallName": "" },
+    "operations": [{ "method": "tools/list", "hasParams": false, "source": "cli-request", "safeToolCallName": "" }],
+    "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
+  },
+  "capabilityProbes": true,
+  "capabilityKeys": ["tools"],
+  "capabilityChecks": {
+    "tools": { "advertised": true, "method": "tools/list", "responded": true, "itemCount": 2, "error": null },
+    "resources": { "advertised": false, "method": "resources/list", "responded": false, "itemCount": null, "error": null },
+    "prompts": { "advertised": false, "method": "prompts/list", "responded": false, "itemCount": null, "error": null }
+  },
+  "issueClasses": {
+    "installRuntime": { "status": "pass", "issueCodes": [] },
+    "stdioTransport": { "status": "pass", "issueCodes": [] },
+    "mcpProtocol": { "status": "pass", "issueCodes": [] }
+  },
+  "toolSchema": {
+    "checked": true,
+    "toolCount": 2,
+    "toolNames": ["read_file", "search"],
+    "validToolCount": 2,
+    "warningCount": 0,
+    "errorCount": 0,
+    "duplicateNames": []
+  },
   "checks": {
     "initialize": { "status": "pass", "issueCodes": [] },
     "stdout": { "status": "pass", "issueCodes": [] },
     "jsonRpc": { "status": "pass", "issueCodes": [] },
     "operation": { "status": "pass", "issueCodes": [] },
+    "capabilities": {
+      "status": "pass",
+      "issueCodes": [],
+      "tools": { "status": "pass", "issueCodes": [], "advertised": true, "method": "tools/list", "responded": true, "itemCount": 2 },
+      "resources": { "status": "skipped", "issueCodes": [], "advertised": false, "method": "resources/list", "responded": false, "itemCount": null },
+      "prompts": { "status": "skipped", "issueCodes": [], "advertised": false, "method": "prompts/list", "responded": false, "itemCount": null }
+    },
+    "toolSchema": { "status": "pass", "issueCodes": [] },
     "process": { "status": "pass", "issueCodes": [] },
     "pythonBuffering": { "status": "pass", "issueCodes": [] },
     "staticScan": { "status": "skipped", "issueCodes": [] },
@@ -178,7 +412,7 @@ The guard is registry-agnostic. It does not care whether an install command came
 
 ```yaml
 - run: npm ci
-- run: npx mcp-stdio-guard --scan src --fail-on-static --request tools/list -- node ./server.js
+- run: npx mcp-stdio-guard --profile ci --scan src --request tools/list -- node ./server.js
 ```
 
 ## Output
@@ -192,6 +426,7 @@ frames: 2 stdout / 0 invalid
 stderr: 0 lines
 protocol: 2025-11-25
 request: tools/list responded
+tool schemas: 2/2 valid
 ```
 
 Polluted stdout:
@@ -210,7 +445,7 @@ request: tools/list responded
 
 - Runtime dependencies: zero.
 - Default behavior: validate the real process boundary.
-- Optional static scan: intentionally simple and conservative.
+- Optional static scan: intentionally simple and conservative; catches common JavaScript and Python stdout writes, stdout logging handlers, and visible startup-output risks.
 - CI posture: fail on protocol corruption, crashes, and missing responses.
 - Promotion promise: no fake stars, no spam, just a tool that catches a real MCP failure mode.
 

package/package.json

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