mcp-stress 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel El-Borai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# mcp-stress
+
+Stress testing tool for MCP (Model Context Protocol) servers.
+
+## Install
+
+```bash
+# npm
+npx mcp-stress <command>
+npm install -g mcp-stress
+
+# JSR / Deno
+deno install -g -A --name mcp-stress jsr:@dgellow/mcp-stress/cli
+```
+
+## Commands
+
+### run
+
+Execute a stress test against an MCP server.
+
+```bash
+# Stdio transport (spawns the server)
+mcp-stress run -d 30 -c 10 --tool echo -- node my-server.js
+
+# HTTP transport
+mcp-stress run -d 30 -c 10 --url http://localhost:3000/mcp
+
+# Find max throughput (auto-scales concurrency)
+mcp-stress run -p find-ceiling -d 120 -c 50 -- node my-server.js
+
+# CI mode: JSON output + assertions
+mcp-stress run --json --assert "p99 < 500ms" --assert "error_rate < 1%" -- node my-server.js
+
+# Live browser dashboard
+mcp-stress run --live -d 60 -c 10 -o results.ndjson -- node my-server.js
+
+# Send exactly N requests (useful for debugging)
+mcp-stress run -n 5 -v -- node my-server.js
+```
+
+**Options:**
+
+| Flag                | Description                                                                       |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `-p, --profile`     | Workload profile (default: `tool-flood`)                                          |
+| `-d, --duration`    | Test duration in seconds (default: 10)                                            |
+| `-n, --requests`    | Stop after N requests (overrides duration)                                        |
+| `-c, --concurrency` | Peak concurrent workers (default: 1)                                              |
+| `-t, --timeout`     | Request timeout in ms (default: 30000)                                            |
+| `--tool`            | Target a specific tool by name                                                    |
+| `--shape`           | Load shape: `constant`, `linear-ramp`, `exponential`, `step`, `spike`, `sawtooth` |
+| `-o, --output`      | NDJSON output file path                                                           |
+| `--live`            | Open real-time browser dashboard                                                  |
+| `--json`            | Output JSON summary to stdout                                                     |
+| `--assert`          | Threshold assertion, repeatable (e.g. `"p99 < 500ms"`)                            |
+| `--seed`            | PRNG seed for reproducibility                                                     |
+| `--sse`             | Use legacy HTTP+SSE transport (default: streamable-http)                          |
+| `-v, --verbose`     | Log every request/response                                                        |
+
+### chart
+
+Generate an interactive HTML report from a previous run.
+
+```bash
+mcp-stress chart results.ndjson --open
+```
+
+### compare
+
+Compare two test runs and detect regressions.
+
+```bash
+mcp-stress compare baseline.ndjson current.ndjson --open
+mcp-stress compare baseline.ndjson current.ndjson --json --assert "p99_delta < 10%"
+```
+
+### diagnose
+
+Probe server connectivity and protocol compliance.
+
+```bash
+mcp-stress diagnose -- node my-server.js
+mcp-stress diagnose --url http://localhost:3000/mcp
+```
+
+### discover
+
+Enumerate server capabilities (tools, resources, prompts).
+
+```bash
+mcp-stress discover -- node my-server.js
+```
+
+### profiles / shapes
+
+List available workload profiles and load shapes.
+
+```bash
+mcp-stress profiles
+mcp-stress shapes
+```
+
+## Transports
+
+- **stdio** (default): Spawns the server as a subprocess. Use
+  `-- command [args]`.
+- **Streamable HTTP**: Connect to a running server. Use `--url`.
+- **SSE** (legacy): Use `--url` with `--sse`.
+
+## Output
+
+All test data is written as NDJSON (newline-delimited JSON) with three event
+types:
+
+- `meta` — run parameters and configuration
+- `request` — individual request results (method, latency, ok/error)
+- `summary` — aggregate statistics
+
+## Development
+
+```bash
+./scripts/lint     # Format check + type check
+./scripts/test     # Run tests
+./scripts/build    # Compile binary + npm packages
+./scripts/start    # Run the CLI
+```

package/mcp-stress.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const PLATFORMS = {
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+  "darwin-x64": "darwin-x64",
+  "darwin-arm64": "darwin-arm64",
+  "win32-x64": "win32-x64",
+};
+
+const key = `${process.platform}-${process.arch}`;
+const pkgSuffix = PLATFORMS[key];
+
+if (!pkgSuffix) {
+  console.error(`Unsupported platform: ${key}`);
+  console.error("Use Deno instead: deno install -g -A --name mcp-stress jsr:@dgellow/mcp-stress/cli");
+  process.exit(1);
+}
+
+const binName = process.platform === "win32" ? "mcp-stress.exe" : "mcp-stress";
+let binPath;
+
+for (const loc of [
+  path.join(__dirname, "..", pkgSuffix, "bin", binName),
+  path.join(__dirname, "..", "..", pkgSuffix, "bin", binName),
+]) {
+  if (fs.existsSync(loc)) { binPath = loc; break; }
+}
+
+if (!binPath) {
+  try {
+    binPath = path.join(path.dirname(require.resolve(`@mcp-stress/${pkgSuffix}/package.json`)), "bin", binName);
+  } catch {
+    console.error(`Binary not found for ${key}. Try: npm install mcp-stress`);
+    process.exit(1);
+  }
+}
+
+const child = spawn(binPath, process.argv.slice(2), { stdio: "inherit" });
+child.on("error", (err) => { console.error(`Failed to start mcp-stress: ${err.message}`); process.exit(1); });
+for (const sig of Object.keys(os.constants.signals)) { try { process.on(sig, () => child.kill(sig)); } catch {} }
+child.on("exit", (code, signal) => { if (signal) process.kill(process.pid, signal); else process.exit(code ?? 0); });

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "mcp-stress",
+  "version": "0.1.2",
+  "description": "Stress testing tool for MCP servers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dgellow/mcp-stress.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dgellow/mcp-stress/issues"
+  },
+  "homepage": "https://github.com/dgellow/mcp-stress#readme",
+  "keywords": [
+    "mcp",
+    "stress-test",
+    "load-test",
+    "benchmark",
+    "model-context-protocol",
+    "cli"
+  ],
+  "bin": {
+    "mcp-stress": "./mcp-stress.js"
+  },
+  "files": [
+    "mcp-stress.js"
+  ],
+  "optionalDependencies": {
+    "@mcp-stress/linux-x64": "0.1.2",
+    "@mcp-stress/linux-arm64": "0.1.2",
+    "@mcp-stress/darwin-x64": "0.1.2",
+    "@mcp-stress/darwin-arm64": "0.1.2",
+    "@mcp-stress/win32-x64": "0.1.2"
+  }
+}