Install

From npm:

npx mcp-stdio-guard -- node ./server.js

From this repo:

git clone https://github.com/1Utkarsh1/mcp-stdio-guard.git
cd mcp-stdio-guard
npm ci
npm test

Quickstart

Run your MCP server behind the guard:

mcp-stdio-guard -- node ./server.js

Use a deterministic profile for common workflows:

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:

mcp-stdio-guard --config mcp-stdio-guard.config.json

Exercise a real MCP operation after initialization:

mcp-stdio-guard --request tools/list -- node ./server.js

Scan source for obvious stdout writes too. Findings are warnings unless --fail-on-static is set:

mcp-stdio-guard --scan src --fail-on-static --request tools/list -- node ./server.js

JSON output for CI:

mcp-stdio-guard --json --request tools/list -- node ./server.js

Repeat the same guard to catch cold/warm startup behavior:

mcp-stdio-guard --repeat 2 --request tools/list -- node ./server.js

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:

Example:

{
  "profile": "registry",
  "command": ["node", "./server.js"],
  "cwd": ".",
  "json": true,
  "env": {
    "API_TOKEN": "set-in-runner"
  },
  "requests": [
    { "method": "tools/list" }
  ],
  "adversarialProbes": ["invalid-method", "notification"],
  "safeToolCalls": [
    { "name": "echo", "arguments": { "text": "hello" } }
  ],
  "adversarialToolCalls": [
    { "name": "echo", "arguments": { "unexpected": true } }
  ]
}

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.

Adversarial probes are off by default because they intentionally send unusual inputs. Built-in probes check that unknown methods return structured errors, invalid params return structured errors, notifications do not receive responses, and malformed JSON does not crash the process. adversarialToolCalls is separate because it calls a named tool with intentionally invalid arguments; only use it for tools you control and consider safe/idempotent.