mcpspec 1.0.3 → 1.1.0

package/README.md

@@ -24,10 +24,11 @@
 ```bash
 mcpspec test ./collection.yaml        # Run tests
 mcpspec inspect "npx my-server"       # Interactive REPL
-mcpspec audit "npx my-server"         # Security scan
+mcpspec audit "npx my-server"         # Security scan (8 rules)
 mcpspec bench "npx my-server"         # Performance benchmark
 mcpspec score "npx my-server"         # Quality rating (0-100)
 mcpspec docs "npx my-server"          # Auto-generate documentation
+mcpspec record start "npx my-server"  # Record & replay sessions
 mcpspec ui                            # Launch web dashboard
 ```
 
@@ -50,9 +51,10 @@ mcpspec test
 |---|---|---|
 | **Test Collections** | YAML-based test suites with 10 assertion types, environments, variables, tags, retries, and parallel execution |
 | **Interactive Inspector** | Connect to any MCP server and explore tools, resources, and schemas in a live REPL |
-| **Security Audit** | Scan for path traversal, injection, auth bypass, resource exhaustion, and info disclosure. Safety filter auto-skips destructive tools; `--dry-run` previews targets |
+| **Security Audit** | 8 rules: path traversal, injection, auth bypass, resource exhaustion, info disclosure, **tool poisoning** (LLM prompt injection), and **excessive agency** (overly broad tools). Safety filter auto-skips destructive tools; `--dry-run` previews targets |
+| **Recording & Replay** | Record inspector sessions, save them, and replay against the same or different server versions. Diff output highlights regressions — matched, changed, added, removed steps |
 | **Benchmarks** | Measure min/max/mean/median/P95/P99 latency and throughput across hundreds of iterations |
-| **MCP Score** | 0-100 quality rating across documentation, schema quality, error handling, responsiveness, and security |
+| **MCP Score** | 0-100 quality rating across documentation, schema quality (opinionated linting: property types, descriptions, constraints, naming conventions), error handling, responsiveness, and security |
 | **Doc Generator** | Auto-generate Markdown or HTML documentation from server introspection |
 | **Web Dashboard** | Full React UI with server management, test runner, audit viewer, and dark mode |
 | **CI/CD Ready** | JUnit/JSON/TAP reporters, deterministic exit codes, `--ci` mode, GitHub Actions compatible |
@@ -69,6 +71,10 @@ mcpspec test
 | `mcpspec docs <server>` | Generate docs — `--format markdown\|html`, `--output <dir>` |
 | `mcpspec compare` | Compare test runs or `--baseline <name>` |
 | `mcpspec baseline save <name>` | Save/list baselines for regression detection |
+| `mcpspec record start <server>` | Record an inspector session — `.call`, `.save`, `.steps` |
+| `mcpspec record replay <name> <server>` | Replay a recording and diff against original |
+| `mcpspec record list` | List saved recordings |
+| `mcpspec record delete <name>` | Delete a saved recording |
 | `mcpspec init [dir]` | Scaffold project — `--template minimal\|standard\|full` |
 | `mcpspec ui` | Launch web dashboard on `localhost:6274` |
 
@@ -93,8 +99,8 @@ Pre-built test suites for popular MCP servers in [`examples/collections/servers/
 | Package | Description |
 |---------|-------------|
 | `@mcpspec/shared` | Types, Zod schemas, constants |
-| `@mcpspec/core` | MCP client, test runner, assertions, security scanner, profiler, doc generator, scorer |
-| `@mcpspec/cli` | 10 CLI commands built with Commander.js |
+| `@mcpspec/core` | MCP client, test runner, assertions, security scanner (8 rules), profiler, doc generator, scorer, recording/replay |
+| `@mcpspec/cli` | 11 CLI commands built with Commander.js |
 | `@mcpspec/server` | Hono HTTP server with REST API + WebSocket |
 | `@mcpspec/ui` | React SPA — TanStack Router, TanStack Query, Tailwind, shadcn/ui |
 
@@ -104,7 +110,7 @@ Pre-built test suites for popular MCP servers in [`examples/collections/servers/
 git clone https://github.com/light-handle/mcpspec.git
 cd mcpspec
 pnpm install && pnpm build
-pnpm test   # 260 tests across core + server
+pnpm test   # 294 tests across core + server
 ```
 
 ## License

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 import { readFileSync as readFileSync3 } from "fs";
 import { dirname, join as join2 } from "path";
 import { fileURLToPath } from "url";
@@ -1116,10 +1116,287 @@ ${COLORS5.bold}  MCP Score${COLORS5.reset}`);
   }
 });
 
+// src/commands/record.ts
+import { Command as Command11 } from "commander";
+import { createInterface as createInterface2 } from "readline";
+import { randomUUID } from "crypto";
+import { EXIT_CODES as EXIT_CODES10 } from "@mcpspec/shared";
+import {
+  MCPClient as MCPClient6,
+  RecordingStore,
+  RecordingReplayer,
+  RecordingDiffer,
+  formatError as formatError7
+} from "@mcpspec/core";
+var COLORS6 = {
+  reset: "\x1B[0m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  gray: "\x1B[90m",
+  bold: "\x1B[1m",
+  cyan: "\x1B[36m",
+  blue: "\x1B[34m"
+};
+var recordCommand = new Command11("record").description("Record, replay, and manage inspector session recordings");
+recordCommand.command("start").description("Start a recording session (interactive REPL)").argument("<server>", 'Server command (e.g., "npx @modelcontextprotocol/server-filesystem /tmp")').action(async (serverCommand) => {
+  let client = null;
+  const store = new RecordingStore();
+  const steps = [];
+  let toolList = [];
+  try {
+    client = new MCPClient6({ serverConfig: serverCommand });
+    console.log(`${COLORS6.cyan}Connecting to: ${COLORS6.reset}${serverCommand}`);
+    await client.connect();
+    const info = client.getServerInfo();
+    const serverName = info?.name ?? "unknown";
+    console.log(`${COLORS6.green}Connected to ${serverName}${COLORS6.reset}`);
+    const tools = await client.listTools();
+    toolList = tools.map((t) => ({ name: t.name, description: t.description }));
+    console.log(`${COLORS6.gray}${tools.length} tools available${COLORS6.reset}`);
+    console.log(`
+${COLORS6.bold}Recording mode.${COLORS6.reset} Type ${COLORS6.bold}.help${COLORS6.reset} for commands.
+`);
+    const rl = createInterface2({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: `${COLORS6.red}rec>${COLORS6.reset} `
+    });
+    rl.prompt();
+    rl.on("line", async (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        rl.prompt();
+        return;
+      }
+      try {
+        if (trimmed === ".exit" || trimmed === ".quit") {
+          if (steps.length > 0) {
+            console.log(`${COLORS6.yellow}Warning: ${steps.length} unsaved step(s). Use .save <name> first, or .exit to discard.${COLORS6.reset}`);
+            if (trimmed === ".exit") {
+              await client?.disconnect();
+              rl.close();
+              process.exit(EXIT_CODES10.SUCCESS);
+            }
+          } else {
+            await client?.disconnect();
+            rl.close();
+            process.exit(EXIT_CODES10.SUCCESS);
+          }
+          return;
+        }
+        if (trimmed === ".help") {
+          console.log(`
+  ${COLORS6.bold}Recording commands:${COLORS6.reset}
+    .tools                  List available tools
+    .call <tool> <json>     Call a tool and record the result
+    .steps                  List recorded steps
+    .save <name>            Save recording with given name
+    .exit                   Disconnect and exit
+`);
+          rl.prompt();
+          return;
+        }
+        if (trimmed === ".tools") {
+          if (toolList.length === 0) {
+            console.log(`${COLORS6.gray}No tools available${COLORS6.reset}`);
+          } else {
+            console.log(`
+${COLORS6.bold}Tools (${toolList.length}):${COLORS6.reset}`);
+            for (const tool of toolList) {
+              console.log(`  ${COLORS6.green}${tool.name}${COLORS6.reset}`);
+              if (tool.description) console.log(`    ${COLORS6.gray}${tool.description}${COLORS6.reset}`);
+            }
+            console.log("");
+          }
+          rl.prompt();
+          return;
+        }
+        if (trimmed === ".steps") {
+          if (steps.length === 0) {
+            console.log(`${COLORS6.gray}No steps recorded yet${COLORS6.reset}`);
+          } else {
+            console.log(`
+${COLORS6.bold}Recorded steps (${steps.length}):${COLORS6.reset}`);
+            for (let i = 0; i < steps.length; i++) {
+              const s = steps[i];
+              const status = s.isError ? `${COLORS6.red}ERROR${COLORS6.reset}` : `${COLORS6.green}OK${COLORS6.reset}`;
+              console.log(`  ${i + 1}. ${s.tool} ${COLORS6.gray}${JSON.stringify(s.input)}${COLORS6.reset} [${status}] ${COLORS6.gray}${s.durationMs}ms${COLORS6.reset}`);
+            }
+            console.log("");
+          }
+          rl.prompt();
+          return;
+        }
+        if (trimmed.startsWith(".save ")) {
+          const name = trimmed.slice(6).trim();
+          if (!name) {
+            console.log(`${COLORS6.red}Usage: .save <name>${COLORS6.reset}`);
+            rl.prompt();
+            return;
+          }
+          if (steps.length === 0) {
+            console.log(`${COLORS6.yellow}No steps to save. Use .call first.${COLORS6.reset}`);
+            rl.prompt();
+            return;
+          }
+          const recording = {
+            id: randomUUID(),
+            name,
+            serverName: info?.name,
+            tools: toolList,
+            steps: [...steps],
+            createdAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          const path = store.save(name, recording);
+          console.log(`${COLORS6.green}Saved recording "${name}" (${steps.length} steps) to ${path}${COLORS6.reset}`);
+          rl.prompt();
+          return;
+        }
+        if (trimmed.startsWith(".call ")) {
+          const rest = trimmed.slice(6).trim();
+          const spaceIdx = rest.indexOf(" ");
+          let toolName;
+          let args = {};
+          if (spaceIdx === -1) {
+            toolName = rest;
+          } else {
+            toolName = rest.slice(0, spaceIdx);
+            const jsonStr = rest.slice(spaceIdx + 1).trim();
+            try {
+              args = JSON.parse(jsonStr);
+            } catch {
+              console.log(`${COLORS6.red}Invalid JSON: ${jsonStr}${COLORS6.reset}`);
+              rl.prompt();
+              return;
+            }
+          }
+          console.log(`${COLORS6.gray}Calling ${toolName}...${COLORS6.reset}`);
+          const start = performance.now();
+          let output = [];
+          let isError = false;
+          try {
+            const result = await client.callTool(toolName, args);
+            output = result.content;
+            isError = result.isError === true;
+          } catch (err) {
+            output = [{ type: "text", text: err instanceof Error ? err.message : String(err) }];
+            isError = true;
+          }
+          const durationMs = Math.round(performance.now() - start);
+          steps.push({ tool: toolName, input: args, output, isError, durationMs });
+          const statusLabel = isError ? `${COLORS6.red}ERROR${COLORS6.reset}` : `${COLORS6.green}OK${COLORS6.reset}`;
+          console.log(`[${statusLabel}] ${COLORS6.gray}${durationMs}ms${COLORS6.reset} (step ${steps.length})`);
+          console.log(JSON.stringify(output, null, 2));
+          rl.prompt();
+          return;
+        }
+        console.log(`${COLORS6.yellow}Unknown command. Type .help for available commands.${COLORS6.reset}`);
+      } catch (err) {
+        const formatted = formatError7(err);
+        console.log(`${COLORS6.red}${formatted.title}: ${formatted.description}${COLORS6.reset}`);
+      }
+      rl.prompt();
+    });
+    rl.on("close", async () => {
+      await client?.disconnect();
+      process.exit(EXIT_CODES10.SUCCESS);
+    });
+  } catch (err) {
+    const formatted = formatError7(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    await client?.disconnect();
+    process.exit(formatted.exitCode);
+  }
+});
+recordCommand.command("list").description("List saved recordings").action(() => {
+  const store = new RecordingStore();
+  const recordings = store.list();
+  if (recordings.length === 0) {
+    console.log(`${COLORS6.gray}No recordings found.${COLORS6.reset}`);
+    return;
+  }
+  console.log(`
+${COLORS6.bold}Saved recordings (${recordings.length}):${COLORS6.reset}`);
+  for (const name of recordings) {
+    const recording = store.load(name);
+    if (recording) {
+      console.log(`  ${COLORS6.green}${name}${COLORS6.reset} ${COLORS6.gray}(${recording.steps.length} steps, ${recording.createdAt})${COLORS6.reset}`);
+    } else {
+      console.log(`  ${COLORS6.green}${name}${COLORS6.reset}`);
+    }
+  }
+  console.log("");
+});
+recordCommand.command("replay").description("Replay a recording against a server and show diff").argument("<name>", "Recording name").argument("<server>", "Server command").action(async (name, serverCommand) => {
+  const store = new RecordingStore();
+  const recording = store.load(name);
+  if (!recording) {
+    console.error(`${COLORS6.red}Recording "${name}" not found.${COLORS6.reset}`);
+    process.exit(EXIT_CODES10.ERROR);
+  }
+  let client = null;
+  try {
+    client = new MCPClient6({ serverConfig: serverCommand });
+    console.log(`${COLORS6.cyan}Connecting to: ${COLORS6.reset}${serverCommand}`);
+    await client.connect();
+    console.log(`${COLORS6.green}Connected. Replaying ${recording.steps.length} steps...${COLORS6.reset}
+`);
+    const replayer = new RecordingReplayer();
+    const result = await replayer.replay(recording, client, {
+      onStepStart: (i, step) => {
+        process.stdout.write(`  ${i + 1}/${recording.steps.length} ${step.tool}... `);
+      },
+      onStepComplete: (_i, replayed) => {
+        const status = replayed.isError ? `${COLORS6.red}ERROR${COLORS6.reset}` : `${COLORS6.green}OK${COLORS6.reset}`;
+        console.log(`[${status}] ${COLORS6.gray}${replayed.durationMs}ms${COLORS6.reset}`);
+      }
+    });
+    const differ = new RecordingDiffer();
+    const diff = differ.diff(recording, result.replayedSteps, result.replayedAt);
+    console.log(`
+${COLORS6.bold}Diff Summary:${COLORS6.reset}`);
+    console.log(`  ${COLORS6.green}Matched:${COLORS6.reset} ${diff.summary.matched}`);
+    console.log(`  ${COLORS6.yellow}Changed:${COLORS6.reset} ${diff.summary.changed}`);
+    console.log(`  ${COLORS6.blue}Added:${COLORS6.reset}   ${diff.summary.added}`);
+    console.log(`  ${COLORS6.red}Removed:${COLORS6.reset} ${diff.summary.removed}`);
+    if (diff.summary.changed > 0) {
+      console.log(`
+${COLORS6.bold}Changed steps:${COLORS6.reset}`);
+      for (const step of diff.steps) {
+        if (step.type === "changed") {
+          console.log(`  Step ${step.index + 1} (${step.tool}): ${COLORS6.yellow}${step.outputDiff}${COLORS6.reset}`);
+        }
+      }
+    }
+    await client.disconnect();
+    const exitCode = diff.summary.changed > 0 || diff.summary.removed > 0 ? EXIT_CODES10.TEST_FAILURE : EXIT_CODES10.SUCCESS;
+    process.exit(exitCode);
+  } catch (err) {
+    const formatted = formatError7(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    await client?.disconnect();
+    process.exit(formatted.exitCode);
+  }
+});
+recordCommand.command("delete").description("Delete a saved recording").argument("<name>", "Recording name").action((name) => {
+  const store = new RecordingStore();
+  if (store.delete(name)) {
+    console.log(`${COLORS6.green}Deleted recording "${name}".${COLORS6.reset}`);
+  } else {
+    console.error(`${COLORS6.red}Recording "${name}" not found.${COLORS6.reset}`);
+    process.exit(EXIT_CODES10.ERROR);
+  }
+});
+
 // src/index.ts
 var __cliDir = dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(readFileSync3(join2(__cliDir, "..", "package.json"), "utf-8"));
-var program = new Command11();
+var program = new Command12();
 program.name("mcpspec").description("The definitive MCP server testing platform").version(pkg.version);
 program.addCommand(testCommand);
 program.addCommand(inspectCommand);
@@ -1131,4 +1408,5 @@ program.addCommand(auditCommand);
 program.addCommand(benchCommand);
 program.addCommand(docsCommand);
 program.addCommand(scoreCommand);
+program.addCommand(recordCommand);
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpspec",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "The definitive MCP server testing platform",
   "keywords": [
     "mcp",
@@ -29,9 +29,9 @@
     "@inquirer/prompts": "^7.0.0",
     "commander": "^12.1.0",
     "open": "^10.1.0",
-    "@mcpspec/core": "1.0.3",
-    "@mcpspec/shared": "1.0.3",
-    "@mcpspec/server": "1.0.3"
+    "@mcpspec/core": "1.1.0",
+    "@mcpspec/shared": "1.1.0",
+    "@mcpspec/server": "1.1.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",