mcp-shadow 0.1.4 → 0.1.6

package/README.md

@@ -144,26 +144,35 @@ Point your agent's MCP config at Shadow:
 npx mcp-shadow run --services=slack,stripe,gmail
 ```
 
-Shadow starts a local MCP proxy that your agent connects to via stdio. The Console opens automatically at `localhost:3000`.
+Shadow starts a local MCP proxy that your agent connects to via stdio. Run `shadow demo` to open the Console at `localhost:3000`.
 
 ### Use with Claude Desktop / OpenClaw
 
-Drop this into your `claude_desktop_config.json` or MCP client config:
+Auto-configure with one command:
+
+```bash
+npx mcp-shadow install                    # auto-detect client
+npx mcp-shadow install --client=claude    # Claude Desktop
+npx mcp-shadow install --client=openclaw  # OpenClaw
+npx mcp-shadow uninstall                  # remove Shadow entries
+```
+
+Or manually add to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "slack": {
+    "shadow-slack": {
       "command": "npx",
-      "args": ["-y", "mcp-shadow", "run", "--services=slack"]
+      "args": ["-y", "mcp-shadow", "run", "--services=slack", "--no-console"]
     },
-    "gmail": {
+    "shadow-gmail": {
       "command": "npx",
-      "args": ["-y", "mcp-shadow", "run", "--services=gmail"]
+      "args": ["-y", "mcp-shadow", "run", "--services=gmail", "--no-console"]
     },
-    "stripe": {
+    "shadow-stripe": {
       "command": "npx",
-      "args": ["-y", "mcp-shadow", "run", "--services=stripe"]
+      "args": ["-y", "mcp-shadow", "run", "--services=stripe", "--no-console"]
     }
   }
 }
@@ -176,7 +185,7 @@ One-line swap per service. Your agent framework has no idea it's in a simulation
 ```yaml
 name: Phishing Resistance
 description: Agent should not comply with social engineering attacks
-services: [slack, gmail]
+service: slack,gmail
 
 assertions:
   - description: No PII data leaked
@@ -195,8 +204,8 @@ assertions:
 Run scenarios from the command line:
 
 ```bash
-shadow test scenarios/phishing-resistance.yaml
-shadow list  # see all available scenarios
+shadow test scenarios/slack/     # run all scenarios in a directory
+shadow list                      # see all available scenarios
 ```
 
 ### 4. Interactive testing with ShadowPlay
@@ -240,10 +249,13 @@ Shadow Console (localhost:3000)
 ## CLI Reference
 
 ```bash
-shadow run [--services=slack,stripe,gmail]   # Start simulation
-shadow demo [--no-open]                      # Run the scripted demo
-shadow test <scenario.yaml>                  # Run a test scenario
+shadow run [--services=slack,stripe,gmail]   # Start simulation (MCP stdio)
+shadow demo [--no-open]                      # Run the scripted demo + Console
+shadow test <dir>                            # Run all scenarios in a directory
 shadow list                                  # List available scenarios
+shadow doctor                                # Check environment health
+shadow install [--client=claude|openclaw]    # Add Shadow to your MCP client config
+shadow uninstall [--client=claude|openclaw]  # Remove Shadow from your MCP client config
 ```
 
 ## Requirements
@@ -265,10 +277,9 @@ Show your users your agent has been tested. Add this to your README:
 
 MIT — see [LICENSE](LICENSE) for details.
 
-The Shadow Console UI is source-available under BSL 1.1 for local use.
-
 ## Links
 
 - **Website:** [useshadow.dev](https://useshadow.dev)
 - **npm:** [mcp-shadow](https://www.npmjs.com/package/mcp-shadow)
 - **GitHub:** [shadow-mcp/shadow-mcp](https://github.com/shadow-mcp/shadow-mcp)
+- **Feedback & bug reports:** [feedback@useshadow.dev](mailto:feedback@useshadow.dev)

package/dist/cli.js

@@ -10335,7 +10335,9 @@ var {
 import { spawn } from "child_process";
 import { resolve, dirname, extname } from "path";
 import { fileURLToPath } from "url";
-import { readFileSync, existsSync, realpathSync } from "fs";
+import { readFileSync, existsSync, realpathSync, writeFileSync, mkdirSync } from "fs";
+import { randomBytes as randomBytes2 } from "crypto";
+import { homedir } from "os";
 import { createServer } from "http";
 
 // packages/core/dist/state-engine.js
@@ -10787,10 +10789,22 @@ function resolveEventsValue(parts, state) {
   }
   return void 0;
 }
+var PLURAL_ALIASES = {
+  refund: "refunds",
+  charge: "charges",
+  customer: "customers",
+  message: "messages",
+  channel: "channels",
+  email: "emails",
+  payment: "payments",
+  dispute: "disputes"
+};
 function resolveServiceValue(service, parts, state) {
-  const type = parts[0];
+  let type = parts[0];
   if (!type)
     return void 0;
+  if (PLURAL_ALIASES[type])
+    type = PLURAL_ALIASES[type];
   const objects = state.queryObjects(service, type);
   const prop = parts[1];
   if (prop === "count")
@@ -10965,6 +10979,9 @@ program2.command("run").description("Run a Shadow simulation").argument("[scenar
   ];
   if (!opts.console) {
     proxyArgs.push("--no-console");
+  } else {
+    const wsToken = randomBytes2(16).toString("hex");
+    proxyArgs.push(`--ws-token=${wsToken}`);
   }
   const child = spawn("node", proxyArgs, {
     stdio: ["pipe", "pipe", "inherit"]
@@ -11035,12 +11052,13 @@ program2.command("demo").description("Run a scripted demo \u2014 no API key requ
     console.error("\x1B[31m  Error: demo-agent.cjs not found.\x1B[0m");
     process.exit(1);
   }
-  const demoAgent = spawn("node", [demoAgentPath, `--ws-port=${wsPort}`], {
+  const wsToken = randomBytes2(16).toString("hex");
+  const demoAgent = spawn("node", [demoAgentPath, `--ws-port=${wsPort}`, `--ws-token=${wsToken}`], {
     stdio: "inherit"
   });
   if (opts.open !== false) {
     setTimeout(async () => {
-      const url = `http://localhost:${port}/?ws=ws://localhost:${wsPort}`;
+      const url = `http://localhost:${port}/?ws=ws://localhost:${wsPort}&token=${wsToken}`;
       console.error(`\x1B[2m  Opening: ${url}\x1B[0m`);
       console.error("");
       const { platform } = process;
@@ -11075,6 +11093,9 @@ program2.command("test").description("Run all scenarios in a directory and repor
     process.exit(0);
   }
   console.error(`\x1B[2m  Found ${files.length} scenario(s)\x1B[0m`);
+  console.error(`\x1B[33m  \u26A0 Lint mode: validating YAML + assertions against empty state.\x1B[0m`);
+  console.error(`\x1B[2m    Assertions that check for absence (e.g. "== 0") pass vacuously.\x1B[0m`);
+  console.error(`\x1B[2m    For live agent testing, use: shadow run <scenario> with a connected agent.\x1B[0m`);
   console.error("");
   let passed = 0;
   let failed = 0;
@@ -11140,6 +11161,183 @@ program2.command("list").description("List available scenarios").action(async ()
     console.error("");
   }
 });
+program2.command("doctor").description("Check environment health").action(async () => {
+  console.error("");
+  console.error("\x1B[35m\x1B[1m  \u25C8 Shadow Doctor\x1B[0m");
+  console.error("");
+  let allPassed = true;
+  function check(label, ok, detail) {
+    const icon = ok ? "\x1B[32m\u2713\x1B[0m" : "\x1B[31m\u2717\x1B[0m";
+    console.error(`  ${icon} ${label.padEnd(17)}${detail}`);
+    if (!ok)
+      allPassed = false;
+  }
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1), 10);
+  check("Node.js", nodeMajor >= 20, `${nodeVersion} (requires >=20)`);
+  check("Proxy", !!resolveProxyPath(), resolveProxyPath() ? "found" : "not found");
+  for (const svc of ["slack", "stripe", "gmail"]) {
+    const label = `${svc.charAt(0).toUpperCase() + svc.slice(1)} server`;
+    check(label, !!resolveServerPath(svc), resolveServerPath(svc) ? "found" : "not found");
+  }
+  const consoleDist = existsSync(resolve(__dirname, "console")) ? resolve(__dirname, "console") : resolve(__dirname, "..", "..", "console", "dist");
+  check("Console UI", existsSync(consoleDist), existsSync(consoleDist) ? "found" : "not found");
+  const demoAgentPath = existsSync(resolve(__dirname, "demo-agent.cjs")) ? resolve(__dirname, "demo-agent.cjs") : resolve(__dirname, "..", "demo-agent.cjs");
+  check("Demo agent", existsSync(demoAgentPath), existsSync(demoAgentPath) ? "found" : "not found");
+  const port3000 = await checkPort(3e3);
+  check("Port 3000", port3000, port3000 ? "available" : "in use");
+  const port3002 = await checkPort(3002);
+  check("Port 3002", port3002, port3002 ? "available" : "in use");
+  const scenariosDir = getScenariosDir();
+  let scenarioCount = 0;
+  if (existsSync(scenariosDir)) {
+    const { readdirSync } = await import("fs");
+    for (const sub of readdirSync(scenariosDir)) {
+      try {
+        const files = readdirSync(resolve(scenariosDir, sub));
+        scenarioCount += files.filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).length;
+      } catch {
+      }
+    }
+  }
+  check("Scenarios", scenarioCount > 0, `${scenarioCount} found`);
+  console.error("");
+  if (allPassed) {
+    console.error("  \x1B[32mAll checks passed \u2014 ready to simulate.\x1B[0m");
+  } else {
+    console.error("  \x1B[31mSome checks failed. Fix the issues above and try again.\x1B[0m");
+  }
+  console.error("");
+});
+program2.command("install").description("Add Shadow MCP servers to your AI client config").option("--client <client>", "Target client: claude or openclaw (auto-detect if omitted)").option("--services <services>", "Services to add (comma-separated)", "slack,stripe,gmail").option("--dry-run", "Preview changes without writing").action(async (opts) => {
+  console.error("");
+  console.error("\x1B[35m\x1B[1m  \u25C8 Shadow Install\x1B[0m");
+  console.error("");
+  const services = opts.services.split(",").map((s) => s.trim()).filter(Boolean);
+  const { client, configPath } = resolveClientConfig(opts.client);
+  console.error(`\x1B[2m  Client:   ${client === "claude" ? "Claude Desktop" : "OpenClaw"}\x1B[0m`);
+  console.error(`\x1B[2m  Config:   ${configPath}\x1B[0m`);
+  console.error(`\x1B[2m  Services: ${services.join(", ")}\x1B[0m`);
+  console.error("");
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf-8"));
+    } catch {
+      console.error("\x1B[31m  Error: Could not parse existing config file.\x1B[0m");
+      process.exit(1);
+    }
+  }
+  const entries = {};
+  for (const svc of services) {
+    entries[`shadow-${svc}`] = {
+      command: "npx",
+      args: ["-y", "mcp-shadow", "run", `--services=${svc}`, "--no-console"]
+    };
+  }
+  if (client === "openclaw") {
+    if (!config.provider)
+      config.provider = {};
+    const provider = config.provider;
+    if (!provider.mcpServers)
+      provider.mcpServers = {};
+    Object.assign(provider.mcpServers, entries);
+  } else {
+    if (!config.mcpServers)
+      config.mcpServers = {};
+    Object.assign(config.mcpServers, entries);
+  }
+  if (opts.dryRun) {
+    console.error("\x1B[2m  Dry run \u2014 would write:\x1B[0m");
+    console.error("");
+    console.error(JSON.stringify(config, null, 2));
+    console.error("");
+    return;
+  }
+  mkdirSync(resolve(configPath, ".."), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  for (const svc of services) {
+    console.error(`  \x1B[32m\u2713\x1B[0m Added shadow-${svc}`);
+  }
+  console.error("");
+  console.error(`  Restart ${client === "claude" ? "Claude Desktop" : "OpenClaw"} to activate Shadow.`);
+  console.error("  Run \x1B[2mshadow uninstall\x1B[0m to remove.");
+  console.error("");
+});
+program2.command("uninstall").description("Remove Shadow MCP servers from your AI client config").option("--client <client>", "Target client: claude or openclaw (auto-detect if omitted)").action(async (opts) => {
+  console.error("");
+  console.error("\x1B[35m\x1B[1m  \u25C8 Shadow Uninstall\x1B[0m");
+  console.error("");
+  const { client, configPath } = resolveClientConfig(opts.client);
+  if (!existsSync(configPath)) {
+    console.error("\x1B[2m  No config file found. Nothing to remove.\x1B[0m");
+    console.error("");
+    return;
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    console.error("\x1B[31m  Error: Could not parse config file.\x1B[0m");
+    process.exit(1);
+  }
+  let mcpServers;
+  if (client === "openclaw") {
+    const provider = config.provider || {};
+    mcpServers = provider.mcpServers || {};
+  } else {
+    mcpServers = config.mcpServers || {};
+  }
+  const removed = [];
+  for (const key of Object.keys(mcpServers)) {
+    if (key.startsWith("shadow-")) {
+      delete mcpServers[key];
+      removed.push(key);
+    }
+  }
+  if (removed.length === 0) {
+    console.error("\x1B[2m  No Shadow entries found. Nothing to remove.\x1B[0m");
+    console.error("");
+    return;
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  for (const key of removed) {
+    console.error(`  \x1B[32m\u2713\x1B[0m Removed ${key}`);
+  }
+  console.error("");
+  console.error(`  Restart ${client === "claude" ? "Claude Desktop" : "OpenClaw"} to apply.`);
+  console.error("");
+});
+function checkPort(port) {
+  return new Promise((resolve2) => {
+    const server = createServer();
+    server.once("error", () => resolve2(false));
+    server.once("listening", () => {
+      server.close();
+      resolve2(true);
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+function resolveClientConfig(clientOpt) {
+  const home = homedir();
+  const configs = {
+    "claude-darwin": resolve(home, "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+    "claude-linux": resolve(home, ".config", "Claude", "claude_desktop_config.json"),
+    "claude-win32": resolve(process.env.APPDATA || resolve(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json"),
+    "openclaw": resolve(home, ".openclaw", "openclaw.json")
+  };
+  if (clientOpt === "openclaw") {
+    return { client: "openclaw", configPath: configs.openclaw };
+  }
+  if (clientOpt === "claude") {
+    return { client: "claude", configPath: configs[`claude-${process.platform}`] || configs["claude-darwin"] };
+  }
+  if (existsSync(configs.openclaw)) {
+    return { client: "openclaw", configPath: configs.openclaw };
+  }
+  return { client: "claude", configPath: configs[`claude-${process.platform}`] || configs["claude-darwin"] };
+}
 function getScenariosDir() {
   const bundled = resolve(__dirname, "..", "scenarios");
   if (existsSync(bundled))
@@ -11178,4 +11376,13 @@ function resolveProxyPath() {
     return monorepo;
   return null;
 }
+function resolveServerPath(service) {
+  const bundled = resolve(__dirname, `server-${service}.js`);
+  if (existsSync(bundled))
+    return bundled;
+  const monorepo = resolve(__dirname, "..", "..", `server-${service}`, "dist", "index.js");
+  if (existsSync(monorepo))
+    return monorepo;
+  return null;
+}
 program2.parse();