mcpspec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCPSpec Contributors
+
+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/dist/index.js

@@ -0,0 +1,1109 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command as Command11 } from "commander";
+
+// src/commands/test.ts
+import { Command } from "commander";
+import { readFileSync, writeFileSync, watch } from "fs";
+import { resolve } from "path";
+import { EXIT_CODES } from "@mcpspec/shared";
+import {
+  loadYamlSafely,
+  TestRunner,
+  ConsoleReporter,
+  JsonReporter,
+  JunitReporter,
+  HtmlReporter,
+  TapReporter,
+  MCPSpecError,
+  formatError
+} from "@mcpspec/core";
+import { collectionSchema } from "@mcpspec/shared";
+function coerceCollection(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new MCPSpecError("COLLECTION_PARSE_ERROR", "Collection file is empty or invalid", {});
+  }
+  const obj = raw;
+  const coerced = { ...obj };
+  if (Array.isArray(obj["tests"])) {
+    coerced["tests"] = obj["tests"].map((test) => {
+      const t = { ...test };
+      if (t["expectError"] === "true") t["expectError"] = true;
+      if (t["expectError"] === "false") t["expectError"] = false;
+      if (typeof t["timeout"] === "string") t["timeout"] = parseInt(t["timeout"], 10);
+      if (typeof t["retries"] === "string") t["retries"] = parseInt(t["retries"], 10);
+      if (Array.isArray(t["assertions"])) {
+        t["assertions"] = t["assertions"].map((a) => {
+          const assertion = { ...a };
+          if (typeof assertion["maxMs"] === "string")
+            assertion["maxMs"] = parseInt(assertion["maxMs"], 10);
+          if (typeof assertion["value"] === "string" && assertion["type"] === "length")
+            assertion["value"] = parseInt(assertion["value"], 10);
+          return assertion;
+        });
+      }
+      if (Array.isArray(t["expect"])) {
+        t["expect"] = t["expect"].map((e) => {
+          return e;
+        });
+      }
+      return t;
+    });
+  }
+  return coerced;
+}
+var testCommand = new Command("test").description("Run tests from a collection file").argument("[collection]", "Path to collection YAML file", "mcpspec.yaml").option("--env <environment>", "Environment to use").option("--reporter <type>", "Reporter type: console, json, junit, html, tap", "console").option("--output <path>", "Output file path for results").option("--ci", "CI mode (no colors, structured output)", false).option("--tag <tags...>", "Filter tests by tag").option("--parallel <n>", "Number of parallel test executions").option("--baseline <name>", "Compare results against named baseline").option("--watch", "Re-run tests on file changes", false).action(async (collectionPath, options) => {
+  if (options.watch) {
+    await runWatch(collectionPath, options);
+  } else {
+    const exitCode = await runOnce(collectionPath, options);
+    process.exit(exitCode);
+  }
+});
+async function runOnce(collectionPath, options) {
+  try {
+    const fullPath = resolve(collectionPath);
+    let content;
+    try {
+      content = readFileSync(fullPath, "utf-8");
+    } catch {
+      const formatted = formatError(
+        new MCPSpecError("COLLECTION_PARSE_ERROR", `Cannot read file: ${fullPath}`, {
+          filePath: fullPath
+        })
+      );
+      console.error(`
+  ${formatted.title}: ${formatted.description}`);
+      formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+      return EXIT_CODES.CONFIG_ERROR;
+    }
+    const raw = loadYamlSafely(content);
+    const collection = coerceCollection(raw);
+    try {
+      collectionSchema.parse(collection);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const formatted = formatError(
+        new MCPSpecError("COLLECTION_VALIDATION_ERROR", message, {
+          details: message,
+          filePath: fullPath
+        })
+      );
+      console.error(`
+  ${formatted.title}: ${formatted.description}`);
+      formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+      return EXIT_CODES.CONFIG_ERROR;
+    }
+    const reporter = createReporter(options);
+    const runner = new TestRunner();
+    const parallelism = options.parallel ? parseInt(options.parallel, 10) : 1;
+    const result = await runner.run(collection, {
+      environment: options.env,
+      reporter,
+      parallelism,
+      tags: options.tag
+    });
+    if (options.output) {
+      const output = getReporterOutput(reporter, options.reporter);
+      if (output) {
+        writeFileSync(resolve(options.output), output, "utf-8");
+      }
+    }
+    if (options.baseline) {
+      const { BaselineStore: BaselineStore3, ResultDiffer: ResultDiffer2 } = await import("@mcpspec/core");
+      const store = new BaselineStore3();
+      const baseline = store.load(options.baseline);
+      if (baseline) {
+        const differ = new ResultDiffer2();
+        const diff = differ.diff(baseline, result, options.baseline);
+        console.log(`
+  Baseline comparison against "${options.baseline}":`);
+        if (diff.summary.regressions > 0) {
+          console.log(`    Regressions: ${diff.summary.regressions}`);
+          for (const r of diff.regressions) {
+            console.log(`      - ${r.testName}: ${r.before?.status} -> ${r.after?.status}`);
+          }
+        }
+        if (diff.summary.fixes > 0) {
+          console.log(`    Fixes: ${diff.summary.fixes}`);
+        }
+        if (diff.summary.newTests > 0) {
+          console.log(`    New tests: ${diff.summary.newTests}`);
+        }
+        if (diff.summary.removedTests > 0) {
+          console.log(`    Removed tests: ${diff.summary.removedTests}`);
+        }
+        if (diff.summary.regressions === 0 && diff.summary.fixes === 0) {
+          console.log("    No changes detected.");
+        }
+        console.log("");
+      } else {
+        console.log(`
+  Baseline "${options.baseline}" not found. Run \`mcpspec baseline save ${options.baseline}\` first.
+`);
+      }
+    }
+    await runner.cleanup();
+    if (result.summary.failed > 0 || result.summary.errors > 0) {
+      return EXIT_CODES.TEST_FAILURE;
+    }
+    return EXIT_CODES.SUCCESS;
+  } catch (err) {
+    const formatted = formatError(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    return formatted.exitCode;
+  }
+}
+function createReporter(options) {
+  switch (options.reporter) {
+    case "json":
+      return new JsonReporter(options.output);
+    case "junit":
+      return new JunitReporter(options.output);
+    case "html":
+      return new HtmlReporter(options.output);
+    case "tap":
+      return new TapReporter();
+    default:
+      return new ConsoleReporter({ ci: options.ci });
+  }
+}
+function getReporterOutput(reporter, type) {
+  if (type === "json") return reporter.getOutput();
+  if (type === "junit") return reporter.getOutput();
+  if (type === "html") return reporter.getOutput();
+  return void 0;
+}
+async function runWatch(collectionPath, options) {
+  const fullPath = resolve(collectionPath);
+  let running = false;
+  let debounceTimer = null;
+  const run = async () => {
+    if (running) return;
+    running = true;
+    console.log("\n--- Running tests ---\n");
+    await runOnce(collectionPath, options);
+    running = false;
+  };
+  await run();
+  console.log(`
+Watching ${fullPath} for changes... (Ctrl+C to stop)
+`);
+  watch(fullPath, () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      run();
+    }, 300);
+  });
+  await new Promise(() => {
+  });
+}
+
+// src/commands/inspect.ts
+import { Command as Command2 } from "commander";
+import { createInterface } from "readline";
+import { EXIT_CODES as EXIT_CODES2 } from "@mcpspec/shared";
+import { MCPClient, formatError as formatError2 } from "@mcpspec/core";
+var COLORS = {
+  reset: "\x1B[0m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  gray: "\x1B[90m",
+  bold: "\x1B[1m",
+  cyan: "\x1B[36m"
+};
+var inspectCommand = new Command2("inspect").description("Interactive inspection of an MCP server").argument("<server>", 'Server command (e.g., "npx @modelcontextprotocol/server-filesystem /tmp")').action(async (serverCommand) => {
+  let client = null;
+  try {
+    client = new MCPClient({ serverConfig: serverCommand });
+    console.log(`${COLORS.cyan}Connecting to: ${COLORS.reset}${serverCommand}`);
+    await client.connect();
+    const info = client.getServerInfo();
+    if (info) {
+      console.log(
+        `${COLORS.green}Connected to ${info.name ?? "unknown"} v${info.version ?? "?"}${COLORS.reset}`
+      );
+    } else {
+      console.log(`${COLORS.green}Connected${COLORS.reset}`);
+    }
+    console.log(`
+Type ${COLORS.bold}.help${COLORS.reset} for available commands
+`);
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: `${COLORS.cyan}mcpspec>${COLORS.reset} `
+    });
+    rl.prompt();
+    rl.on("line", async (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        rl.prompt();
+        return;
+      }
+      try {
+        if (trimmed === ".exit" || trimmed === ".quit") {
+          await client?.disconnect();
+          rl.close();
+          process.exit(EXIT_CODES2.SUCCESS);
+          return;
+        }
+        if (trimmed === ".help") {
+          console.log(`
+  ${COLORS.bold}Available commands:${COLORS.reset}
+    .tools             List all available tools
+    .resources         List all available resources
+    .call <tool> <json>  Call a tool with JSON arguments
+    .schema <tool>     Show input schema for a tool
+    .info              Show server info
+    .exit              Disconnect and exit
+`);
+          rl.prompt();
+          return;
+        }
+        if (trimmed === ".tools") {
+          const tools = await client.listTools();
+          if (tools.length === 0) {
+            console.log(`${COLORS.gray}No tools available${COLORS.reset}`);
+          } else {
+            console.log(`
+${COLORS.bold}Tools (${tools.length}):${COLORS.reset}`);
+            for (const tool of tools) {
+              console.log(`  ${COLORS.green}${tool.name}${COLORS.reset}`);
+              if (tool.description) {
+                console.log(`    ${COLORS.gray}${tool.description}${COLORS.reset}`);
+              }
+            }
+            console.log("");
+          }
+          rl.prompt();
+          return;
+        }
+        if (trimmed === ".resources") {
+          const resources = await client.listResources();
+          if (resources.length === 0) {
+            console.log(`${COLORS.gray}No resources available${COLORS.reset}`);
+          } else {
+            console.log(`
+${COLORS.bold}Resources (${resources.length}):${COLORS.reset}`);
+            for (const resource of resources) {
+              console.log(`  ${COLORS.green}${resource.uri}${COLORS.reset}`);
+              if (resource.name) {
+                console.log(`    ${COLORS.gray}${resource.name}${COLORS.reset}`);
+              }
+            }
+            console.log("");
+          }
+          rl.prompt();
+          return;
+        }
+        if (trimmed === ".info") {
+          const serverInfo = client.getServerInfo();
+          console.log(JSON.stringify(serverInfo, null, 2));
+          rl.prompt();
+          return;
+        }
+        if (trimmed.startsWith(".schema ")) {
+          const toolName = trimmed.slice(8).trim();
+          const tools = await client.listTools();
+          const tool = tools.find((t) => t.name === toolName);
+          if (!tool) {
+            console.log(`${COLORS.red}Tool "${toolName}" not found${COLORS.reset}`);
+            console.log(
+              `${COLORS.gray}Available: ${tools.map((t) => t.name).join(", ")}${COLORS.reset}`
+            );
+          } else {
+            console.log(JSON.stringify(tool.inputSchema, null, 2));
+          }
+          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(`${COLORS.red}Invalid JSON: ${jsonStr}${COLORS.reset}`);
+              rl.prompt();
+              return;
+            }
+          }
+          console.log(`${COLORS.gray}Calling ${toolName}...${COLORS.reset}`);
+          const result = await client.callTool(toolName, args);
+          console.log(JSON.stringify(result, null, 2));
+          rl.prompt();
+          return;
+        }
+        console.log(`${COLORS.yellow}Unknown command. Type .help for available commands.${COLORS.reset}`);
+      } catch (err) {
+        const formatted = formatError2(err);
+        console.log(`${COLORS.red}${formatted.title}: ${formatted.description}${COLORS.reset}`);
+      }
+      rl.prompt();
+    });
+    rl.on("close", async () => {
+      await client?.disconnect();
+      process.exit(EXIT_CODES2.SUCCESS);
+    });
+  } catch (err) {
+    const formatted = formatError2(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    await client?.disconnect();
+    process.exit(formatted.exitCode);
+  }
+});
+
+// src/commands/init.ts
+import { Command as Command3 } from "commander";
+import { mkdirSync, writeFileSync as writeFileSync2, existsSync } from "fs";
+import { resolve as resolve2, join } from "path";
+import { EXIT_CODES as EXIT_CODES3 } from "@mcpspec/shared";
+var TEMPLATES = {
+  minimal: `name: My MCP Tests
+server: npx my-mcp-server
+
+tests:
+  - name: Basic test
+    call: my_tool
+    with:
+      param: value
+    expect:
+      - exists: $.content
+`,
+  standard: `schemaVersion: "1.0"
+name: My MCP Tests
+description: Test collection for my MCP server
+
+server:
+  transport: stdio
+  command: npx
+  args:
+    - my-mcp-server
+
+tests:
+  - name: List tools are available
+    call: my_tool
+    with:
+      param: value
+    assertions:
+      - type: exists
+        path: $.content
+      - type: latency
+        maxMs: 5000
+
+  - name: Handle invalid input
+    call: my_tool
+    with:
+      invalid_param: true
+    expectError: true
+`,
+  full: `schemaVersion: "1.0"
+name: My MCP Tests
+description: Comprehensive test collection
+
+server:
+  name: my-server
+  transport: stdio
+  command: npx
+  args:
+    - my-mcp-server
+  env:
+    NODE_ENV: test
+
+environments:
+  dev:
+    variables:
+      API_URL: http://localhost:3000
+  staging:
+    variables:
+      API_URL: https://staging.example.com
+
+defaultEnvironment: dev
+
+tests:
+  - id: test-basic
+    name: Basic tool call
+    tags:
+      - smoke
+    call: my_tool
+    with:
+      param: value
+    assertions:
+      - type: schema
+      - type: exists
+        path: $.content
+      - type: latency
+        maxMs: 5000
+
+  - id: test-error
+    name: Handle error gracefully
+    tags:
+      - error-handling
+    call: my_tool
+    with:
+      invalid: true
+    expectError: true
+
+  - id: test-extract
+    name: Extract and reuse data
+    tags:
+      - integration
+    call: get_data
+    with:
+      id: "1"
+    assertions:
+      - type: exists
+        path: $.id
+    extract:
+      - name: itemId
+        path: $.id
+
+  - id: test-use-extracted
+    name: Use extracted variable
+    tags:
+      - integration
+    call: get_detail
+    with:
+      id: "{{itemId}}"
+    assertions:
+      - type: exists
+        path: $.detail
+`
+};
+function generateFromWizard(result) {
+  const serverBlock = result.transport === "stdio" ? `server: ${result.command}` : `server:
+  transport: ${result.transport}
+  url: ${result.url}`;
+  const template = TEMPLATES[result.template];
+  const lines = template.split("\n");
+  const output = [];
+  let skipServer = false;
+  for (const line of lines) {
+    if (line.startsWith("name:")) {
+      output.push(`name: ${result.name}`);
+    } else if (line.startsWith("server:") || line.startsWith("server ")) {
+      output.push(serverBlock);
+      if (line === "server:") {
+        skipServer = true;
+      }
+    } else if (skipServer) {
+      if (line.startsWith("  ") && !line.startsWith("  -") && !line.match(/^\w/)) {
+        if (line.match(/^[a-zA-Z]/)) {
+          skipServer = false;
+          output.push(line);
+        }
+        continue;
+      } else {
+        skipServer = false;
+        output.push(line);
+      }
+    } else {
+      output.push(line);
+    }
+  }
+  return output.join("\n");
+}
+var initCommand = new Command3("init").description("Initialize a new mcpspec project").argument("[directory]", "Target directory", ".").option("--template <type>", "Template type: minimal, standard, full").action(async (directory, options) => {
+  const dir = resolve2(directory);
+  try {
+    if (!options.template && process.stdin.isTTY) {
+      const { runOnboardingWizard } = await import("./onboarding-5G6D2OYR.js");
+      const result = await runOnboardingWizard();
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      const collectionPath2 = join(dir, "mcpspec.yaml");
+      if (existsSync(collectionPath2)) {
+        console.error(`File already exists: ${collectionPath2}`);
+        process.exit(EXIT_CODES3.CONFIG_ERROR);
+      }
+      const content = generateFromWizard(result);
+      writeFileSync2(collectionPath2, content, "utf-8");
+      console.log(`
+Created ${collectionPath2}`);
+      console.log(`
+Edit the file to configure your tests, then run: mcpspec test`);
+      return;
+    }
+    const template = options.template ?? "standard";
+    if (!TEMPLATES[template]) {
+      console.error(`Unknown template: ${template}. Available: minimal, standard, full`);
+      process.exit(EXIT_CODES3.CONFIG_ERROR);
+    }
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const collectionPath = join(dir, "mcpspec.yaml");
+    if (existsSync(collectionPath)) {
+      console.error(`File already exists: ${collectionPath}`);
+      process.exit(EXIT_CODES3.CONFIG_ERROR);
+    }
+    writeFileSync2(collectionPath, TEMPLATES[template], "utf-8");
+    console.log(`Created ${collectionPath}`);
+    console.log(`
+Edit the file to configure your MCP server and tests.`);
+    console.log(`Then run: mcpspec test`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Failed to initialize: ${message}`);
+    process.exit(EXIT_CODES3.ERROR);
+  }
+});
+
+// src/commands/compare.ts
+import { Command as Command4 } from "commander";
+import { EXIT_CODES as EXIT_CODES4 } from "@mcpspec/shared";
+import { BaselineStore, ResultDiffer } from "@mcpspec/core";
+var compareCommand = new Command4("compare").description("Compare test runs against a baseline").argument("[run1]", "First run (baseline name)").argument("[run2]", "Second run (baseline name)").option("--baseline <name>", "Compare latest run against named baseline").action((run1, run2, options) => {
+  const store = new BaselineStore();
+  const differ = new ResultDiffer();
+  if (run1 && run2) {
+    const baseline = store.load(run1);
+    const current = store.load(run2);
+    if (!baseline) {
+      console.error(`Baseline "${run1}" not found.`);
+      process.exit(EXIT_CODES4.CONFIG_ERROR);
+    }
+    if (!current) {
+      console.error(`Baseline "${run2}" not found.`);
+      process.exit(EXIT_CODES4.CONFIG_ERROR);
+    }
+    const diff = differ.diff(baseline, current, run1);
+    printDiff(diff);
+    process.exit(diff.summary.regressions > 0 ? EXIT_CODES4.TEST_FAILURE : EXIT_CODES4.SUCCESS);
+  }
+  if (options.baseline) {
+    const baselines = store.list();
+    if (baselines.length === 0) {
+      console.error("No baselines found. Run `mcpspec baseline save <name>` first.");
+      process.exit(EXIT_CODES4.CONFIG_ERROR);
+    }
+    const baseline = store.load(options.baseline);
+    if (!baseline) {
+      console.error(`Baseline "${options.baseline}" not found.`);
+      console.error(`Available baselines: ${baselines.join(", ")}`);
+      process.exit(EXIT_CODES4.CONFIG_ERROR);
+    }
+    const otherBaselines = baselines.filter((b) => b !== options.baseline);
+    if (otherBaselines.length === 0) {
+      console.error("Need at least two baselines to compare. Run tests and save another baseline.");
+      process.exit(EXIT_CODES4.CONFIG_ERROR);
+    }
+    const current = store.load(otherBaselines[otherBaselines.length - 1]);
+    if (!current) {
+      console.error("Could not load comparison baseline.");
+      process.exit(EXIT_CODES4.CONFIG_ERROR);
+    }
+    const diff = differ.diff(baseline, current, options.baseline);
+    printDiff(diff);
+    process.exit(diff.summary.regressions > 0 ? EXIT_CODES4.TEST_FAILURE : EXIT_CODES4.SUCCESS);
+  }
+  console.error("Usage: mcpspec compare <run1> <run2> or mcpspec compare --baseline <name>");
+  process.exit(EXIT_CODES4.CONFIG_ERROR);
+});
+function printDiff(diff) {
+  console.log(`
+Comparison against baseline "${diff.baselineName}":`);
+  console.log(`  Tests before: ${diff.summary.totalBefore}`);
+  console.log(`  Tests after:  ${diff.summary.totalAfter}`);
+  console.log("");
+  if (diff.regressions.length > 0) {
+    console.log("  Regressions:");
+    for (const r of diff.regressions) {
+      console.log(`    \u2717 ${r.testName}: ${r.before?.status} -> ${r.after?.status}`);
+    }
+  }
+  if (diff.fixes.length > 0) {
+    console.log("  Fixes:");
+    for (const r of diff.fixes) {
+      console.log(`    \u2713 ${r.testName}: ${r.before?.status} -> ${r.after?.status}`);
+    }
+  }
+  if (diff.newTests.length > 0) {
+    console.log("  New tests:");
+    for (const r of diff.newTests) {
+      console.log(`    + ${r.testName}: ${r.after?.status}`);
+    }
+  }
+  if (diff.removedTests.length > 0) {
+    console.log("  Removed tests:");
+    for (const r of diff.removedTests) {
+      console.log(`    - ${r.testName}`);
+    }
+  }
+  if (diff.regressions.length === 0 && diff.fixes.length === 0 && diff.newTests.length === 0 && diff.removedTests.length === 0) {
+    console.log("  No changes detected.");
+  }
+  console.log("");
+}
+
+// src/commands/baseline.ts
+import { Command as Command5 } from "commander";
+import { readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve3 } from "path";
+import { EXIT_CODES as EXIT_CODES5 } from "@mcpspec/shared";
+import { BaselineStore as BaselineStore2 } from "@mcpspec/core";
+var baselineCommand = new Command5("baseline").description("Manage test baselines").addCommand(
+  new Command5("save").description("Save a test run result as a named baseline").argument("<name>", "Baseline name").argument("[results-file]", "Path to JSON results file").action((name, resultsFile) => {
+    const store = new BaselineStore2();
+    if (!resultsFile) {
+      console.error("Usage: mcpspec baseline save <name> <results-file.json>");
+      console.error("  Run tests with --reporter json --output results.json first.");
+      process.exit(EXIT_CODES5.CONFIG_ERROR);
+    }
+    try {
+      const fullPath = resolve3(resultsFile);
+      const content = readFileSync2(fullPath, "utf-8");
+      const raw = JSON.parse(content);
+      const result = {
+        ...raw,
+        startedAt: new Date(raw.startedAt),
+        completedAt: new Date(raw.completedAt)
+      };
+      const savedPath = store.save(name, result);
+      console.log(`Baseline "${name}" saved to ${savedPath}`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`Failed to save baseline: ${message}`);
+      process.exit(EXIT_CODES5.ERROR);
+    }
+  })
+).addCommand(
+  new Command5("list").description("List saved baselines").action(() => {
+    const store = new BaselineStore2();
+    const baselines = store.list();
+    if (baselines.length === 0) {
+      console.log("No baselines saved.");
+      console.log("Run `mcpspec baseline save <name> <results.json>` to create one.");
+      return;
+    }
+    console.log("Saved baselines:");
+    for (const name of baselines) {
+      console.log(`  - ${name}`);
+    }
+  })
+);
+
+// src/commands/ui.ts
+import { Command as Command6 } from "commander";
+var uiCommand = new Command6("ui").description("Launch the MCPSpec web UI").option("-p, --port <port>", "Port to listen on", "6274").option("--host <host>", "Host to bind to", "127.0.0.1").option("--no-open", "Do not auto-open browser").action(async (opts) => {
+  const port = parseInt(opts.port, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error("Invalid port number");
+    process.exit(1);
+  }
+  const { startServer, UI_DIST_PATH } = await import("@mcpspec/server");
+  const uiDistPath = UI_DIST_PATH;
+  const server = await startServer({
+    port,
+    host: opts.host,
+    uiDistPath
+  });
+  const url = `http://${server.host}:${server.port}`;
+  if (opts.open) {
+    try {
+      const { default: open } = await import("open");
+      await open(url);
+    } catch {
+      console.log(`Open ${url} in your browser`);
+    }
+  }
+  process.on("SIGINT", () => {
+    console.log("\nShutting down...");
+    server.close();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    server.close();
+    process.exit(0);
+  });
+});
+
+// src/commands/audit.ts
+import { Command as Command7 } from "commander";
+import { EXIT_CODES as EXIT_CODES6 } from "@mcpspec/shared";
+import {
+  MCPClient as MCPClient2,
+  ScanConfig,
+  SecurityScanner,
+  formatError as formatError3
+} from "@mcpspec/core";
+var COLORS2 = {
+  reset: "\x1B[0m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  green: "\x1B[32m",
+  cyan: "\x1B[36m",
+  gray: "\x1B[90m",
+  bold: "\x1B[1m"
+};
+var SEVERITY_COLORS = {
+  critical: COLORS2.red + COLORS2.bold,
+  high: COLORS2.red,
+  medium: COLORS2.yellow,
+  low: COLORS2.cyan,
+  info: COLORS2.gray
+};
+var auditCommand = new Command7("audit").description("Run security audit on an MCP server").argument("<server>", "Server command or URL").option("--mode <mode>", "Scan mode: passive, active, aggressive", "passive").option("--acknowledge-risk", "Skip confirmation prompt for active/aggressive modes", false).option("--fail-on <severity>", "Fail with exit code 6 if findings at or above severity: info, low, medium, high, critical").option("--rules <rules...>", "Only run specific rules").action(async (serverCommand, options) => {
+  let client = null;
+  try {
+    const mode = options.mode;
+    const config = new ScanConfig({
+      mode,
+      acknowledgeRisk: options.acknowledgeRisk,
+      rules: options.rules
+    });
+    if (config.requiresConfirmation()) {
+      console.log(`
+${COLORS2.yellow}${COLORS2.bold}  WARNING: Security Scan${COLORS2.reset}`);
+      console.log(`${COLORS2.yellow}  Mode: ${mode}${COLORS2.reset}`);
+      console.log(`${COLORS2.yellow}  This sends potentially harmful payloads to the server.${COLORS2.reset}`);
+      console.log(`${COLORS2.yellow}  NEVER run against production systems!${COLORS2.reset}
+`);
+      const { confirm } = await import("@inquirer/prompts");
+      const confirmed = await confirm({
+        message: "Is this a TEST environment? Continue with scan?",
+        default: false
+      });
+      if (!confirmed) {
+        console.log("  Scan cancelled.");
+        process.exit(EXIT_CODES6.SUCCESS);
+      }
+    }
+    console.log(`
+${COLORS2.cyan}  Connecting to:${COLORS2.reset} ${serverCommand}`);
+    client = new MCPClient2({ serverConfig: serverCommand });
+    await client.connect();
+    const info = client.getServerInfo();
+    console.log(`${COLORS2.green}  Connected to ${info?.name ?? "unknown"} v${info?.version ?? "?"}${COLORS2.reset}`);
+    console.log(`${COLORS2.gray}  Scan mode: ${mode} | Rules: ${config.rules.join(", ")}${COLORS2.reset}
+`);
+    const scanner = new SecurityScanner();
+    const result = await scanner.scan(client, config, {
+      onRuleStart: (_ruleId, ruleName) => {
+        process.stdout.write(`  ${COLORS2.gray}Running ${ruleName}...${COLORS2.reset}`);
+      },
+      onRuleComplete: (_ruleId, findingCount) => {
+        if (findingCount > 0) {
+          console.log(` ${COLORS2.yellow}${findingCount} finding(s)${COLORS2.reset}`);
+        } else {
+          console.log(` ${COLORS2.green}clean${COLORS2.reset}`);
+        }
+      }
+    });
+    console.log(`
+${COLORS2.bold}  Security Scan Results${COLORS2.reset}`);
+    console.log(`  ${"\u2500".repeat(50)}`);
+    console.log(`  Server: ${result.serverName}`);
+    console.log(`  Mode: ${result.mode}`);
+    console.log(`  Findings: ${result.summary.totalFindings}`);
+    if (result.summary.totalFindings > 0) {
+      console.log(`
+  ${COLORS2.bold}By Severity:${COLORS2.reset}`);
+      for (const sev of ["critical", "high", "medium", "low", "info"]) {
+        const count = result.summary.bySeverity[sev];
+        if (count > 0) {
+          console.log(`    ${SEVERITY_COLORS[sev]}${sev.toUpperCase()}${COLORS2.reset}: ${count}`);
+        }
+      }
+      console.log(`
+  ${COLORS2.bold}Findings:${COLORS2.reset}
+`);
+      for (const finding of result.findings) {
+        const color = SEVERITY_COLORS[finding.severity];
+        console.log(`  ${color}[${finding.severity.toUpperCase()}]${COLORS2.reset} ${finding.title}`);
+        console.log(`    ${COLORS2.gray}${finding.description}${COLORS2.reset}`);
+        if (finding.evidence) {
+          console.log(`    ${COLORS2.gray}Evidence: ${finding.evidence.slice(0, 100)}${COLORS2.reset}`);
+        }
+        if (finding.remediation) {
+          console.log(`    ${COLORS2.cyan}Fix: ${finding.remediation}${COLORS2.reset}`);
+        }
+        console.log("");
+      }
+    } else {
+      console.log(`
+  ${COLORS2.green}No security findings detected.${COLORS2.reset}
+`);
+    }
+    await client.disconnect();
+    if (options.failOn) {
+      const failOnSeverity = options.failOn;
+      const failConfig = new ScanConfig({ severityThreshold: failOnSeverity });
+      const matchingFindings = result.findings.filter((f) => failConfig.meetsThreshold(f.severity));
+      if (matchingFindings.length > 0) {
+        process.exit(EXIT_CODES6.SECURITY_FINDINGS);
+      }
+    }
+    process.exit(EXIT_CODES6.SUCCESS);
+  } catch (err) {
+    const formatted = formatError3(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    await client?.disconnect();
+    process.exit(formatted.exitCode);
+  }
+});
+
+// src/commands/bench.ts
+import { Command as Command8 } from "commander";
+import { EXIT_CODES as EXIT_CODES7 } from "@mcpspec/shared";
+import {
+  MCPClient as MCPClient3,
+  BenchmarkRunner,
+  formatError as formatError4
+} from "@mcpspec/core";
+var COLORS3 = {
+  reset: "\x1B[0m",
+  green: "\x1B[32m",
+  cyan: "\x1B[36m",
+  gray: "\x1B[90m",
+  bold: "\x1B[1m",
+  yellow: "\x1B[33m"
+};
+var benchCommand = new Command8("bench").description("Run performance benchmark on an MCP server").argument("<server>", "Server command or URL").option("--iterations <n>", "Number of iterations", "100").option("--tool <name>", "Tool to benchmark (defaults to first available)").option("--args <json>", "JSON arguments for the tool call", "{}").option("--timeout <ms>", "Timeout per call in milliseconds", "30000").option("--warmup <n>", "Number of warmup iterations", "5").action(async (serverCommand, options) => {
+  let client = null;
+  try {
+    console.log(`
+${COLORS3.cyan}  Connecting to:${COLORS3.reset} ${serverCommand}`);
+    client = new MCPClient3({ serverConfig: serverCommand });
+    await client.connect();
+    const info = client.getServerInfo();
+    console.log(`${COLORS3.green}  Connected to ${info?.name ?? "unknown"} v${info?.version ?? "?"}${COLORS3.reset}
+`);
+    const tools = await client.listTools();
+    if (tools.length === 0) {
+      console.error("  No tools available on this server.");
+      await client.disconnect();
+      process.exit(EXIT_CODES7.ERROR);
+    }
+    let toolName = options.tool;
+    if (!toolName) {
+      toolName = tools[0].name;
+      console.log(`${COLORS3.gray}  No --tool specified, using: ${toolName}${COLORS3.reset}`);
+    } else {
+      const found = tools.find((t) => t.name === toolName);
+      if (!found) {
+        console.error(`  Tool "${toolName}" not found. Available: ${tools.map((t) => t.name).join(", ")}`);
+        await client.disconnect();
+        process.exit(EXIT_CODES7.ERROR);
+      }
+    }
+    let args = {};
+    if (options.args) {
+      try {
+        args = JSON.parse(options.args);
+      } catch {
+        console.error(`  Invalid JSON for --args: ${options.args}`);
+        await client.disconnect();
+        process.exit(EXIT_CODES7.CONFIG_ERROR);
+      }
+    }
+    const iterations = parseInt(options.iterations, 10);
+    const warmup = parseInt(options.warmup ?? "5", 10);
+    const timeout = parseInt(options.timeout ?? "30000", 10);
+    console.log(`${COLORS3.bold}  Benchmarking: ${toolName}${COLORS3.reset}`);
+    console.log(`  Iterations: ${iterations} | Warmup: ${warmup} | Timeout: ${timeout}ms
+`);
+    const runner = new BenchmarkRunner();
+    const result = await runner.run(client, toolName, args, {
+      iterations,
+      warmupIterations: warmup,
+      concurrency: 1,
+      timeout
+    }, {
+      onWarmupStart: (n) => {
+        console.log(`${COLORS3.gray}  Warming up (${n} iterations)...${COLORS3.reset}`);
+      },
+      onIterationComplete: (i, total) => {
+        if (i % Math.max(1, Math.floor(total / 10)) === 0 || i === total) {
+          process.stdout.write(`\r  Progress: ${i}/${total}`);
+        }
+      },
+      onComplete: () => {
+        console.log("");
+      }
+    });
+    console.log(`
+${COLORS3.bold}  Benchmark Results${COLORS3.reset}`);
+    console.log(`  ${"\u2500".repeat(40)}`);
+    console.log(`  Tool:       ${result.toolName}`);
+    console.log(`  Iterations: ${result.iterations}`);
+    console.log(`  Errors:     ${result.errors}`);
+    console.log("");
+    console.log(`  ${COLORS3.bold}Latency Statistics:${COLORS3.reset}`);
+    console.log(`    Min:    ${result.stats.min.toFixed(2)}ms`);
+    console.log(`    Max:    ${result.stats.max.toFixed(2)}ms`);
+    console.log(`    Mean:   ${result.stats.mean.toFixed(2)}ms`);
+    console.log(`    Median: ${result.stats.median.toFixed(2)}ms`);
+    console.log(`    P95:    ${result.stats.p95.toFixed(2)}ms`);
+    console.log(`    P99:    ${result.stats.p99.toFixed(2)}ms`);
+    console.log(`    StdDev: ${result.stats.stddev.toFixed(2)}ms`);
+    const durationSec = (result.completedAt.getTime() - result.startedAt.getTime()) / 1e3;
+    const rps = result.iterations / durationSec;
+    console.log(`
+  Throughput: ${COLORS3.green}${rps.toFixed(1)} calls/sec${COLORS3.reset}`);
+    console.log("");
+    await client.disconnect();
+    process.exit(EXIT_CODES7.SUCCESS);
+  } catch (err) {
+    const formatted = formatError4(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    await client?.disconnect();
+    process.exit(formatted.exitCode);
+  }
+});
+
+// src/commands/docs.ts
+import { Command as Command9 } from "commander";
+import { EXIT_CODES as EXIT_CODES8 } from "@mcpspec/shared";
+import { MCPClient as MCPClient4, DocGenerator, formatError as formatError5 } from "@mcpspec/core";
+var COLORS4 = {
+  reset: "\x1B[0m",
+  green: "\x1B[32m",
+  cyan: "\x1B[36m",
+  bold: "\x1B[1m"
+};
+var docsCommand = new Command9("docs").description("Generate documentation from an MCP server").argument("<server>", "Server command or URL").option("--format <format>", "Output format: markdown, html", "markdown").option("--output <dir>", "Output directory").action(async (serverCommand, options) => {
+  let client = null;
+  try {
+    console.log(`
+${COLORS4.cyan}  Connecting to:${COLORS4.reset} ${serverCommand}`);
+    client = new MCPClient4({ serverConfig: serverCommand });
+    await client.connect();
+    const info = client.getServerInfo();
+    console.log(`${COLORS4.green}  Connected to ${info?.name ?? "unknown"} v${info?.version ?? "?"}${COLORS4.reset}
+`);
+    const format = options.format === "html" ? "html" : "markdown";
+    const generator = new DocGenerator();
+    const content = await generator.generate(client, {
+      format,
+      outputDir: options.output
+    });
+    if (options.output) {
+      const filename = format === "html" ? "index.html" : "README.md";
+      console.log(`${COLORS4.green}  Documentation written to ${options.output}/${filename}${COLORS4.reset}
+`);
+    } else {
+      console.log(content);
+    }
+    await client.disconnect();
+    process.exit(EXIT_CODES8.SUCCESS);
+  } catch (err) {
+    const formatted = formatError5(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    await client?.disconnect();
+    process.exit(formatted.exitCode);
+  }
+});
+
+// src/commands/score.ts
+import { Command as Command10 } from "commander";
+import { writeFileSync as writeFileSync3 } from "fs";
+import { EXIT_CODES as EXIT_CODES9 } from "@mcpspec/shared";
+import { MCPClient as MCPClient5, MCPScoreCalculator, BadgeGenerator, formatError as formatError6 } from "@mcpspec/core";
+var COLORS5 = {
+  reset: "\x1B[0m",
+  green: "\x1B[32m",
+  cyan: "\x1B[36m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m",
+  bold: "\x1B[1m",
+  gray: "\x1B[90m"
+};
+function scoreColor(score) {
+  if (score >= 80) return COLORS5.green;
+  if (score >= 60) return COLORS5.yellow;
+  return COLORS5.red;
+}
+var scoreCommand = new Command10("score").description("Calculate MCP Score for a server").argument("<server>", "Server command or URL").option("--badge <path>", "Output badge SVG path").action(async (serverCommand, options) => {
+  let client = null;
+  try {
+    console.log(`
+${COLORS5.cyan}  Connecting to:${COLORS5.reset} ${serverCommand}`);
+    client = new MCPClient5({ serverConfig: serverCommand });
+    await client.connect();
+    const info = client.getServerInfo();
+    console.log(`${COLORS5.green}  Connected to ${info?.name ?? "unknown"} v${info?.version ?? "?"}${COLORS5.reset}
+`);
+    const calculator = new MCPScoreCalculator();
+    const score = await calculator.calculate(client, {
+      onCategoryStart: (category) => {
+        process.stdout.write(`${COLORS5.gray}  Evaluating ${category}...${COLORS5.reset}`);
+      },
+      onCategoryComplete: (_category, categoryScore) => {
+        const color = scoreColor(categoryScore);
+        console.log(` ${color}${categoryScore}/100${COLORS5.reset}`);
+      }
+    });
+    console.log(`
+${COLORS5.bold}  MCP Score${COLORS5.reset}`);
+    console.log(`  ${"\u2500".repeat(40)}`);
+    const categories = [
+      { name: "Documentation", score: score.categories.documentation },
+      { name: "Schema Quality", score: score.categories.schemaQuality },
+      { name: "Error Handling", score: score.categories.errorHandling },
+      { name: "Performance", score: score.categories.performance },
+      { name: "Security", score: score.categories.security }
+    ];
+    for (const cat of categories) {
+      const color = scoreColor(cat.score);
+      const bar = "\u2588".repeat(Math.round(cat.score / 5)) + "\u2591".repeat(20 - Math.round(cat.score / 5));
+      console.log(`  ${cat.name.padEnd(16)} ${bar} ${color}${cat.score}/100${COLORS5.reset}`);
+    }
+    const overallColor = scoreColor(score.overall);
+    console.log(`
+  ${COLORS5.bold}Overall: ${overallColor}${score.overall}/100${COLORS5.reset}
+`);
+    if (options.badge) {
+      const badgeGenerator = new BadgeGenerator();
+      const svg = badgeGenerator.generate(score);
+      writeFileSync3(options.badge, svg, "utf-8");
+      console.log(`${COLORS5.green}  Badge written to ${options.badge}${COLORS5.reset}
+`);
+    }
+    await client.disconnect();
+    process.exit(EXIT_CODES9.SUCCESS);
+  } catch (err) {
+    const formatted = formatError6(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    await client?.disconnect();
+    process.exit(formatted.exitCode);
+  }
+});
+
+// src/index.ts
+var program = new Command11();
+program.name("mcpspec").description("The definitive MCP server testing platform").version("1.0.0");
+program.addCommand(testCommand);
+program.addCommand(inspectCommand);
+program.addCommand(initCommand);
+program.addCommand(compareCommand);
+program.addCommand(baselineCommand);
+program.addCommand(uiCommand);
+program.addCommand(auditCommand);
+program.addCommand(benchCommand);
+program.addCommand(docsCommand);
+program.addCommand(scoreCommand);
+program.parse(process.argv);

package/dist/onboarding-5G6D2OYR.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+// src/wizard/onboarding.ts
+import { input, select } from "@inquirer/prompts";
+async function runOnboardingWizard() {
+  console.log("\n  Welcome to MCPSpec! Let's set up your test collection.\n");
+  const name = await input({
+    message: "Collection name:",
+    default: "My MCP Tests"
+  });
+  const transport = await select({
+    message: "How does your MCP server communicate?",
+    choices: [
+      { name: "stdio (command-line process)", value: "stdio" },
+      { name: "SSE (Server-Sent Events)", value: "sse" },
+      { name: "Streamable HTTP", value: "streamable-http" }
+    ]
+  });
+  let command;
+  let url;
+  if (transport === "stdio") {
+    command = await input({
+      message: "Server command (e.g., npx @modelcontextprotocol/server-filesystem /tmp):",
+      default: "npx my-mcp-server"
+    });
+  } else {
+    url = await input({
+      message: "Server URL:",
+      default: "http://localhost:3000/mcp"
+    });
+  }
+  const template = await select({
+    message: "Template complexity:",
+    choices: [
+      { name: "Minimal - simple tests to get started", value: "minimal" },
+      { name: "Standard - tests with assertions (Recommended)", value: "standard" },
+      { name: "Full - environments, tags, extraction", value: "full" }
+    ]
+  });
+  return { name, transport, command, url, template };
+}
+export {
+  runOnboardingWizard
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mcpspec",
+  "version": "1.0.0",
+  "description": "The definitive MCP server testing platform",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "testing",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "mcpspec": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/mcpspec.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^12.1.0",
+    "open": "^10.1.0",
+    "@mcpspec/core": "1.0.0",
+    "@mcpspec/shared": "1.0.0",
+    "@mcpspec/server": "1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist .turbo"
+  }
+}