mcpspec 1.1.0 → 1.2.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/light-handle/mcpspec/main/mcpspec.png" alt="MCPSpec" width="200" />
+  <img src="mcpspec.png" alt="MCPSpec" width="200" />
 </p>
 
 <h1 align="center">MCPSpec</h1>
@@ -29,6 +29,8 @@ 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 mock my-recording             # Start mock server from recording
+mcpspec ci-init --platform github     # Generate CI pipeline config
 mcpspec ui                            # Launch web dashboard
 ```
 
@@ -43,21 +45,460 @@ mcpspec init --template standard
 
 # 3. Run tests
 mcpspec test
+
+# 4. Add CI gating (optional)
+mcpspec ci-init
 ```
 
 ## Features
 
-| | Feature | Description |
-|---|---|---|
-| **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** | 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 (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 |
+### Test Collections
+
+Write tests in YAML with 10 assertion types, environments, variable extraction, tags, retries, and parallel execution.
+
+```yaml
+name: Filesystem Tests
+server: npx @modelcontextprotocol/server-filesystem /tmp
+
+tests:
+  - name: Read a file
+    call: read_file
+    with:
+      path: /tmp/test.txt
+    expect:
+      - exists: $.content
+      - type: [$.content, string]
+
+  - name: Handle missing file
+    call: read_file
+    with:
+      path: /tmp/nonexistent.txt
+    expectError: true
+```
+
+**Advanced features:**
+
+```yaml
+schemaVersion: "1.0"
+name: Advanced Tests
+
+server:
+  command: npx
+  args: ["my-mcp-server"]
+  env:
+    NODE_ENV: test
+
+environments:
+  dev:
+    variables:
+      BASE_PATH: /tmp/dev
+  staging:
+    variables:
+      BASE_PATH: /tmp/staging
+
+defaultEnvironment: dev
+
+tests:
+  - id: create-data
+    name: Create data
+    tags: [smoke, write]
+    timeout: 5000
+    retries: 2
+    call: create_item
+    with:
+      name: "test-item"
+    assertions:
+      - type: schema
+      - type: exists
+        path: $.id
+      - type: latency
+        maxMs: 1000
+    extract:
+      - name: itemId
+        path: $.id
+
+  - id: verify-data
+    name: Verify created data
+    tags: [smoke, read]
+    call: get_item
+    with:
+      id: "{{itemId}}"
+    assertions:
+      - type: equals
+        path: $.name
+        value: "test-item"
+      - type: expression
+        expr: "response.id == itemId"
+```
+
+**Assertion types:**
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `schema` | Validate response structure | `type: schema` |
+| `equals` | Exact match (deep comparison) | `path: $.id, value: 123` |
+| `contains` | Array or string contains value | `path: $.tags, value: "active"` |
+| `exists` | Path exists and is not null | `path: $.name` |
+| `matches` | Regex pattern match | `path: $.email, pattern: ".*@.*"` |
+| `type` | Type check | `path: $.count, expected: number` |
+| `length` | Array/string length | `path: $.items, operator: gt, value: 0` |
+| `latency` | Response time threshold | `maxMs: 1000` |
+| `mimeType` | Content type validation | `expected: "image/png"` |
+| `expression` | Safe expression eval | `expr: "response.total > 0"` |
+
+Expressions use [expr-eval](https://github.com/silentmatt/expr-eval) — comparisons, logical operators, property access, math. No arbitrary code execution.
+
+**Shorthand format** for common assertions:
+
+```yaml
+expect:
+  - exists: $.field
+  - equals: [$.id, 123]
+  - contains: [$.tags, "active"]
+  - matches: [$.email, ".*@.*"]
+```
+
+**Run options:**
+
+```bash
+mcpspec test ./tests.yaml              # Specific file
+mcpspec test --env staging             # Switch environment
+mcpspec test --tag @smoke              # Filter by tag
+mcpspec test --parallel 4              # Parallel execution
+mcpspec test --reporter junit --output results.xml
+mcpspec test --baseline main           # Compare against baseline
+mcpspec test --watch                   # Re-run on file changes
+mcpspec test --ci                      # CI mode (no colors)
+```
+
+**Reporters:** console (default), json, junit, html, tap.
+
+---
+
+### Interactive Inspector
+
+Connect to any MCP server and explore its capabilities in a live REPL.
+
+```bash
+mcpspec inspect "npx @modelcontextprotocol/server-filesystem /tmp"
+```
+
+| Command | Description |
+|---------|-------------|
+| `.tools` | List all available tools with descriptions |
+| `.resources` | List all available resources (URIs) |
+| `.call <tool> <json>` | Call a tool with JSON input |
+| `.schema <tool>` | Display tool's JSON Schema input spec |
+| `.info` | Show server info (name, version, capabilities) |
+| `.help` | Show help |
+| `.exit` | Disconnect and exit |
+
+```
+mcpspec> .tools
+  read_file        Read complete contents of a file
+  write_file       Create or overwrite a file
+  list_directory   List directory contents
+
+mcpspec> .call read_file {"path": "/tmp/test.txt"}
+{
+  "content": "Hello, world!"
+}
+```
+
+---
+
+### Security Audit
+
+8 security rules covering traditional vulnerabilities and LLM-specific threats. A safety filter auto-skips destructive tools, and `--dry-run` previews targets before scanning.
+
+```bash
+mcpspec audit "npx my-server"                        # Passive (safe)
+mcpspec audit "npx my-server" --mode active           # Active probing
+mcpspec audit "npx my-server" --fail-on medium        # CI gate
+mcpspec audit "npx my-server" --exclude-tools delete  # Skip tools
+mcpspec audit "npx my-server" --dry-run               # Preview targets
+```
+
+**Security rules:**
+
+| Rule | Mode | What it detects |
+|------|------|-----------------|
+| Path Traversal | Passive | `../../etc/passwd` style directory escape attacks |
+| Input Validation | Passive | Missing constraints (enum, pattern, min/max) on tool inputs |
+| Info Disclosure | Passive | Leaked paths, stack traces, API keys in tool descriptions |
+| Tool Poisoning | Passive | LLM prompt injection in descriptions, hidden Unicode, cross-tool manipulation |
+| Excessive Agency | Passive | Destructive tools without confirmation params, arbitrary code execution |
+| Resource Exhaustion | Active | Unbounded loops, large allocations, recursion |
+| Auth Bypass | Active | Missing auth checks, hardcoded credentials |
+| Injection | Active | SQL and command injection in tool inputs |
+
+**Scan modes:**
+
+- **Passive** (default) — 5 rules, analyzes metadata only, no tool calls. Safe for production.
+- **Active** — All 8 rules, sends test payloads. Requires confirmation prompt.
+- **Aggressive** — All 8 rules with more exhaustive probing. Requires confirmation prompt.
+
+Active/aggressive modes auto-skip tools matching destructive patterns (`delete_*`, `drop_*`, `destroy_*`, etc.) and require explicit confirmation unless `--acknowledge-risk` is passed.
+
+Each finding includes severity (info/low/medium/high/critical), description, evidence, and remediation advice.
+
+---
+
+### Recording & Replay
+
+Record inspector sessions, save them, and replay against the same or different server versions. Diff output highlights regressions.
+
+```bash
+# Record a session
+mcpspec record start "npx my-server"
+mcpspec> .call get_user {"id": "1"}
+mcpspec> .call list_items {}
+mcpspec> .save my-session
+
+# Later: replay against new server version
+mcpspec record replay my-session "npx my-server-v2"
+```
+
+**Replay output:**
+
+```
+Replaying 3 steps against my-server-v2...
+
+  1/3 get_user............. [OK] 42ms
+  2/3 list_items........... [CHANGED] 38ms
+  3/3 create_item.......... [OK] 51ms
+
+Summary: 2 matched, 1 changed, 0 added, 0 removed
+```
+
+**Manage recordings:**
+
+```bash
+mcpspec record list                    # List saved recordings
+mcpspec record delete my-session       # Delete a recording
+```
+
+Recordings are stored in `~/.mcpspec/recordings/` and include tool names, inputs, outputs, timing, and error states for each step.
+
+---
+
+### Mock Server
+
+Turn any recording into a mock MCP server — a drop-in replacement for the real server. Useful for CI/CD without real dependencies, offline development, and deterministic tests.
+
+```bash
+# Start mock server from a recording (stdio transport)
+mcpspec mock my-api
+
+# Use as a server in test collections
+mcpspec test --server "mcpspec mock my-api" ./tests.yaml
+
+# Generate standalone .js file (only needs @modelcontextprotocol/sdk)
+mcpspec mock my-api --generate ./mock-server.js
+node mock-server.js
+```
+
+**Matching modes:**
+
+| Mode | Behavior |
+|------|----------|
+| `match` (default) | Exact input match first, then next queued response per tool |
+| `sequential` | Tape/cassette style — responses served in recorded order |
+
+**Options:**
+
+```bash
+mcpspec mock my-api --mode sequential       # Tape-style matching
+mcpspec mock my-api --latency original      # Simulate original response times
+mcpspec mock my-api --latency 100           # Fixed 100ms delay
+mcpspec mock my-api --on-missing empty      # Return empty instead of error for unrecorded tools
+```
+
+The generated standalone file embeds the recording data and matching logic — commit it to your repo for portable, dependency-light mock servers.
+
+---
+
+### Performance Benchmarks
+
+Measure latency and throughput with statistical analysis across hundreds of iterations.
+
+```bash
+mcpspec bench "npx my-server"                         # 100 iterations
+mcpspec bench "npx my-server" --iterations 500
+mcpspec bench "npx my-server" --tool read_file
+mcpspec bench "npx my-server" --args '{"path":"/tmp/f"}'
+mcpspec bench "npx my-server" --warmup 10
+```
+
+**Output:**
+
+```
+Benchmarking read_file (100 iterations, 5 warmup)...
+
+  Latency
+  ────────────────────────────
+  Min        12.34ms
+  Max        89.21ms
+  Mean       34.56ms
+  Median     31.22ms
+  P95        67.89ms
+  P99        82.45ms
+  Std Dev    15.23ms
+
+  Throughput: 28.94 calls/sec
+  Errors:     0
+```
+
+Warmup iterations (default: 5) are excluded from measurements. The profiler uses `performance.now()` for high-resolution timing.
+
+---
+
+### MCP Score
+
+A 0-100 quality rating across 5 weighted categories with opinionated schema linting.
+
+```bash
+mcpspec score "npx my-server"
+mcpspec score "npx my-server" --badge badge.svg       # Generate SVG badge
+mcpspec score "npx my-server" --min-score 80          # Fail if below threshold
+```
+
+**Scoring categories:**
+
+| Category (weight) | What it measures |
+|--------------------|-----------------|
+| Documentation (25%) | Percentage of tools and resources with descriptions |
+| Schema Quality (25%) | Property types, descriptions, required fields, constraints (enum/pattern/min/max), naming conventions |
+| Error Handling (20%) | Structured error responses (`isError: true`) vs. crashes on bad input |
+| Responsiveness (15%) | Median latency: <100ms = 100, <500ms = 80, <1s = 60, <5s = 40 |
+| Security (15%) | Findings from passive security scan: 0 = 100, <=2 = 70, <=5 = 40 |
+
+Schema quality uses 6 sub-criteria: structure (20%), property types (20%), descriptions (20%), required fields (15%), constraints (15%), naming conventions (10%).
+
+The `--badge` flag generates a shields.io-style SVG badge for your README.
+
+---
+
+### Doc Generator
+
+Auto-generate Markdown or HTML documentation from server introspection. Zero manual writing.
+
+```bash
+mcpspec docs "npx my-server"                   # Markdown to stdout
+mcpspec docs "npx my-server" --format html      # HTML output
+mcpspec docs "npx my-server" --output ./docs    # Write to directory
+```
+
+Generated docs include: server name/version/description, all tools with their input schemas, and all resources with URIs and descriptions.
+
+---
+
+### Web Dashboard
+
+A full React UI for managing servers, running tests, viewing audit results, and more. Dark mode included.
+
+```bash
+mcpspec ui                    # Opens localhost:6274
+mcpspec ui --port 8080        # Custom port
+mcpspec ui --no-open          # Don't auto-open browser
+```
+
+**Pages:**
+
+| Page | What it does |
+|------|-------------|
+| Dashboard | Overview of servers, collections, recent runs |
+| Servers | Connect and manage MCP server connections |
+| Collections | Create and edit YAML test collections |
+| Runs | View test run history and results |
+| Inspector | Interactive tool calling with schema forms and protocol logging |
+| Audit | Run security scans and view findings |
+| Benchmark | Performance profiling with charts |
+| Score | MCP Score visualization |
+| Docs | Generated server documentation |
+| Recordings | View, replay, and manage recorded sessions |
+
+Real-time WebSocket updates for running tests, live protocol logging in the inspector, and dark mode with localStorage persistence.
+
+---
+
+### CI/CD Integration
+
+`ci-init` generates ready-to-use pipeline configurations. Deterministic exit codes and JUnit/JSON/TAP reporters for seamless CI integration.
+
+```bash
+mcpspec ci-init                                 # Interactive wizard
+mcpspec ci-init --platform github               # GitHub Actions
+mcpspec ci-init --platform gitlab               # GitLab CI
+mcpspec ci-init --platform shell                # Shell script
+mcpspec ci-init --checks test,audit,score       # Choose checks
+mcpspec ci-init --fail-on medium                # Audit severity gate
+mcpspec ci-init --min-score 70                  # MCP Score threshold
+mcpspec ci-init --force                         # Overwrite/replace existing
+```
+
+Auto-detects platform from `.github/` or `.gitlab-ci.yml`. GitLab `--force` surgically replaces only the mcpspec job block, preserving other jobs.
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Test failure |
+| `2` | Runtime error |
+| `3` | Configuration error |
+| `4` | Connection error |
+| `5` | Timeout |
+| `6` | Security findings above threshold |
+| `7` | Validation error |
+| `130` | Interrupted (Ctrl+C) |
+
+---
+
+### Baselines & Comparison
+
+Save test runs as baselines and detect regressions between versions.
+
+```bash
+mcpspec baseline save main                      # Save current run
+mcpspec baseline list                           # List all baselines
+mcpspec test --baseline main                    # Compare against baseline
+mcpspec compare --baseline main                 # Explicit comparison
+mcpspec compare <run-id-1> <run-id-2>           # Compare two runs
+```
+
+Comparison output shows regressions (tests that now fail), fixes (tests that now pass), new tests, and removed tests.
+
+---
+
+### Transports
+
+MCPSpec supports 3 transport types for connecting to MCP servers:
+
+| Transport | Use case | Connection |
+|-----------|----------|------------|
+| **stdio** | Local processes | Spawns child process, communicates via stdin/stdout |
+| **SSE** | Server-Sent Events | Connects to HTTP SSE endpoint |
+| **HTTP** | Streamable HTTP | POST requests to HTTP endpoint |
+
+```yaml
+# stdio (default)
+server:
+  command: npx
+  args: ["my-mcp-server"]
+
+# SSE
+server:
+  transport: sse
+  url: http://localhost:3000/sse
+
+# HTTP
+server:
+  transport: http
+  url: http://localhost:3000/mcp
+```
+
+Connection state machine with automatic reconnection: exponential backoff (1s, 2s, 4s, 8s) up to 30s max, 3 retry attempts.
 
 ## Commands
 
@@ -66,8 +507,8 @@ mcpspec test
 | `mcpspec test [collection]` | Run test collections with `--env`, `--tag`, `--parallel`, `--reporter`, `--watch`, `--ci` |
 | `mcpspec inspect <server>` | Interactive REPL — `.tools`, `.call`, `.schema`, `.resources`, `.info` |
 | `mcpspec audit <server>` | Security scan — `--mode`, `--fail-on`, `--exclude-tools`, `--dry-run` |
-| `mcpspec bench <server>` | Performance benchmark — `--iterations`, `--tool`, `--args` |
-| `mcpspec score <server>` | Quality score (0-100) — `--badge badge.svg` |
+| `mcpspec bench <server>` | Performance benchmark — `--iterations`, `--tool`, `--args`, `--warmup` |
+| `mcpspec score <server>` | Quality score (0-100) — `--badge badge.svg`, `--min-score` |
 | `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 |
@@ -75,32 +516,40 @@ mcpspec test
 | `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 mock <recording>` | Mock server from recording — `--mode`, `--latency`, `--on-missing`, `--generate` |
 | `mcpspec init [dir]` | Scaffold project — `--template minimal\|standard\|full` |
+| `mcpspec ci-init` | Generate CI config — `--platform github\|gitlab\|shell`, `--checks`, `--fail-on`, `--force` |
 | `mcpspec ui` | Launch web dashboard on `localhost:6274` |
 
 ## Community Collections
 
-Pre-built test suites for popular MCP servers in [`examples/collections/servers/`](https://github.com/light-handle/mcpspec/tree/main/examples/collections/servers):
+Pre-built test suites for popular MCP servers in [`examples/collections/servers/`](examples/collections/servers/):
 
 | Collection | Server | Tests |
 |------------|--------|-------|
-| filesystem.yaml | @modelcontextprotocol/server-filesystem | 12 |
-| memory.yaml | @modelcontextprotocol/server-memory | 10 |
-| everything.yaml | @modelcontextprotocol/server-everything | 11 |
-| fetch.yaml | @modelcontextprotocol/server-fetch | 7 |
-| time.yaml | @modelcontextprotocol/server-time | 10 |
-| chrome-devtools.yaml | chrome-devtools-mcp | 11 |
-| github.yaml | @modelcontextprotocol/server-github | 9 |
+| [filesystem.yaml](examples/collections/servers/filesystem.yaml) | @modelcontextprotocol/server-filesystem | 12 |
+| [memory.yaml](examples/collections/servers/memory.yaml) | @modelcontextprotocol/server-memory | 10 |
+| [everything.yaml](examples/collections/servers/everything.yaml) | @modelcontextprotocol/server-everything | 11 |
+| [fetch.yaml](examples/collections/servers/fetch.yaml) | @modelcontextprotocol/server-fetch | 7 |
+| [time.yaml](examples/collections/servers/time.yaml) | @modelcontextprotocol/server-time | 10 |
+| [chrome-devtools.yaml](examples/collections/servers/chrome-devtools.yaml) | chrome-devtools-mcp | 11 |
+| [github.yaml](examples/collections/servers/github.yaml) | @modelcontextprotocol/server-github | 9 |
 
 **70 tests** covering tool discovery, read/write operations, error handling, security edge cases, and latency.
 
+```bash
+# Run community collections directly
+mcpspec test examples/collections/servers/filesystem.yaml
+mcpspec test examples/collections/servers/time.yaml --tag smoke
+```
+
 ## Architecture
 
 | Package | Description |
 |---------|-------------|
 | `@mcpspec/shared` | Types, Zod schemas, constants |
 | `@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/cli` | 13 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 |
 
@@ -110,7 +559,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   # 294 tests across core + server
+pnpm test   # 329 tests across core + server
 ```
 
 ## License

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command12 } from "commander";
-import { readFileSync as readFileSync3 } from "fs";
-import { dirname, join as join2 } from "path";
+import { Command as Command14 } from "commander";
+import { readFileSync as readFileSync4 } from "fs";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 
 // src/commands/test.ts
@@ -1393,10 +1393,451 @@ recordCommand.command("delete").description("Delete a saved recording").argument
   }
 });
 
+// src/commands/ci-init.ts
+import { Command as Command12 } from "commander";
+import { existsSync as existsSync2, writeFileSync as writeFileSync4, readFileSync as readFileSync3, mkdirSync as mkdirSync2, chmodSync } from "fs";
+import { resolve as resolve4 } from "path";
+import { EXIT_CODES as EXIT_CODES11 } from "@mcpspec/shared";
+function detectPlatform() {
+  if (existsSync2(".github")) return "github";
+  if (existsSync2(".gitlab-ci.yml")) return "gitlab";
+  return null;
+}
+function detectCollection() {
+  if (existsSync2("mcpspec.yaml")) return "./mcpspec.yaml";
+  if (existsSync2("mcpspec.yml")) return "./mcpspec.yml";
+  return null;
+}
+function renderGitHubActions(config) {
+  const lines = [];
+  lines.push("name: MCP Server Tests");
+  lines.push("on: [push, pull_request]");
+  lines.push("");
+  lines.push("jobs:");
+  lines.push("  mcpspec:");
+  lines.push("    runs-on: ubuntu-latest");
+  lines.push("    steps:");
+  lines.push("      - uses: actions/checkout@v4");
+  lines.push("      - uses: actions/setup-node@v4");
+  lines.push("        with:");
+  lines.push("          node-version: '22'");
+  lines.push("");
+  lines.push("      # Or add mcpspec as a devDependency for version pinning");
+  lines.push("      - run: npm install -g mcpspec");
+  const artifacts = [];
+  if (config.checks.includes("test")) {
+    lines.push("");
+    lines.push("      - name: Run tests");
+    lines.push(`        run: mcpspec test ${config.collection} --ci --reporter junit --output results.xml`);
+    artifacts.push("results.xml");
+  }
+  if (config.checks.includes("audit") && config.server) {
+    lines.push("");
+    lines.push("      - name: Security audit");
+    lines.push(`        run: mcpspec audit "${config.server}" --mode passive --fail-on ${config.failOn}`);
+  }
+  if (config.checks.includes("score") && config.server) {
+    lines.push("");
+    lines.push("      - name: MCP Score");
+    if (config.minScore !== null) {
+      lines.push(`        run: mcpspec score "${config.server}" --badge badge.svg --min-score ${config.minScore}`);
+    } else {
+      lines.push(`        run: mcpspec score "${config.server}" --badge badge.svg`);
+    }
+    artifacts.push("badge.svg");
+  }
+  if (config.checks.includes("bench") && config.server) {
+    lines.push("");
+    lines.push("      - name: Performance benchmark");
+    lines.push(`        run: mcpspec bench "${config.server}"`);
+  }
+  if (artifacts.length > 0) {
+    lines.push("");
+    lines.push("      - name: Upload results");
+    lines.push("        if: always()");
+    lines.push("        uses: actions/upload-artifact@v4");
+    lines.push("        with:");
+    lines.push("          name: mcpspec-results");
+    lines.push("          path: |");
+    for (const a of artifacts) {
+      lines.push(`            ${a}`);
+    }
+  }
+  if (config.checks.includes("test")) {
+    lines.push("");
+    lines.push("      - name: Test Report");
+    lines.push("        if: always()");
+    lines.push("        uses: mikepenz/action-junit-report@v4");
+    lines.push("        with:");
+    lines.push("          report_paths: results.xml");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderGitLabCI(config) {
+  const lines = [];
+  lines.push("mcpspec:");
+  lines.push("  image: node:22");
+  lines.push("  stage: test");
+  lines.push("  script:");
+  lines.push("    # Or add mcpspec as a devDependency for version pinning");
+  lines.push("    - npm install -g mcpspec");
+  if (config.checks.includes("test")) {
+    lines.push(`    - mcpspec test ${config.collection} --ci --reporter junit --output results.xml`);
+  }
+  if (config.checks.includes("audit") && config.server) {
+    lines.push(`    - mcpspec audit "${config.server}" --mode passive --fail-on ${config.failOn}`);
+  }
+  if (config.checks.includes("score") && config.server) {
+    if (config.minScore !== null) {
+      lines.push(`    - mcpspec score "${config.server}" --min-score ${config.minScore}`);
+    } else {
+      lines.push(`    - mcpspec score "${config.server}"`);
+    }
+  }
+  if (config.checks.includes("bench") && config.server) {
+    lines.push(`    - mcpspec bench "${config.server}"`);
+  }
+  if (config.checks.includes("test")) {
+    lines.push("  artifacts:");
+    lines.push("    when: always");
+    lines.push("    paths:");
+    lines.push("      - results.xml");
+    lines.push("    reports:");
+    lines.push("      junit: results.xml");
+    lines.push("    expire_in: 1 week");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderShellScript(config) {
+  const lines = [];
+  lines.push("#!/usr/bin/env bash");
+  lines.push("set -euo pipefail");
+  lines.push("");
+  lines.push("# Or add mcpspec as a devDependency for version pinning");
+  lines.push("command -v mcpspec >/dev/null 2>&1 || npm install -g mcpspec");
+  lines.push("");
+  lines.push('echo "Running MCPSpec CI checks..."');
+  lines.push("");
+  if (config.checks.includes("test")) {
+    lines.push(`mcpspec test ${config.collection} --ci --reporter junit --output results.xml`);
+    lines.push('echo "Tests passed."');
+    lines.push("");
+  }
+  if (config.checks.includes("audit") && config.server) {
+    lines.push(`mcpspec audit "${config.server}" --mode passive --fail-on ${config.failOn}`);
+    lines.push('echo "Security audit passed."');
+    lines.push("");
+  }
+  if (config.checks.includes("score") && config.server) {
+    if (config.minScore !== null) {
+      lines.push(`mcpspec score "${config.server}" --min-score ${config.minScore}`);
+    } else {
+      lines.push(`mcpspec score "${config.server}"`);
+    }
+    lines.push('echo "MCP Score check passed."');
+    lines.push("");
+  }
+  if (config.checks.includes("bench") && config.server) {
+    lines.push(`mcpspec bench "${config.server}"`);
+    lines.push('echo "Benchmark complete."');
+    lines.push("");
+  }
+  lines.push('echo "All checks passed!"');
+  lines.push("");
+  return lines.join("\n");
+}
+function getOutputPath(platform) {
+  switch (platform) {
+    case "github":
+      return ".github/workflows/mcpspec.yml";
+    case "gitlab":
+      return ".gitlab-ci.yml";
+    case "shell":
+      return "mcpspec-ci.sh";
+  }
+}
+function replaceGitLabJob(existing, newJob) {
+  const lines = existing.split("\n");
+  let blockStart = -1;
+  let blockEnd = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (blockStart === -1) {
+      if (/^mcpspec:/.test(line)) {
+        blockStart = i;
+      }
+    } else {
+      if (line.length > 0 && !line.startsWith(" ") && !line.startsWith("#")) {
+        blockEnd = i;
+        break;
+      }
+    }
+  }
+  if (blockStart === -1) return null;
+  while (blockEnd > blockStart && lines[blockEnd - 1].trim() === "") {
+    blockEnd--;
+  }
+  const before = lines.slice(0, blockStart);
+  const after = lines.slice(blockEnd);
+  while (before.length > 0 && before[before.length - 1].trim() === "") {
+    before.pop();
+  }
+  const parts = [];
+  if (before.length > 0) {
+    parts.push(before.join("\n"));
+    parts.push("");
+  }
+  parts.push(newJob.trimEnd());
+  if (after.length > 0) {
+    const afterStr = after.join("\n").trimStart();
+    if (afterStr.length > 0) {
+      parts.push("");
+      parts.push(afterStr);
+    }
+  }
+  return parts.join("\n") + "\n";
+}
+function parseChecks(checksStr) {
+  const valid = ["test", "audit", "score", "bench"];
+  const parsed = checksStr.split(",").map((c) => c.trim()).filter(Boolean);
+  for (const c of parsed) {
+    if (!valid.includes(c)) {
+      console.error(`Unknown check: ${c}. Valid checks: ${valid.join(", ")}`);
+      process.exit(EXIT_CODES11.CONFIG_ERROR);
+    }
+  }
+  return parsed;
+}
+var ciInitCommand = new Command12("ci-init").description("Generate CI pipeline configuration for MCP server testing").option("--platform <type>", "CI platform: github, gitlab, or shell").option("--collection <path>", "Path to collection file").option("--server <command>", "Server command for audit/score/bench steps").option("--checks <list>", "Comma-separated checks: test,audit,score,bench", "test,audit").option("--fail-on <severity>", "Audit severity gate: low, medium, high, critical", "high").option("--min-score <n>", "Minimum MCP Score threshold (0-100)").option("--force", "Overwrite existing files").action(async (options) => {
+  try {
+    let platform = options.platform;
+    let collection = options.collection ?? detectCollection() ?? "./mcpspec.yaml";
+    let server = options.server ?? "";
+    let checks = parseChecks(options.checks ?? "test,audit");
+    let failOn = options.failOn ?? "high";
+    let minScore = options.minScore ? Number(options.minScore) : null;
+    if (!platform && process.stdin.isTTY) {
+      const { select, input, checkbox, confirm } = await import("@inquirer/prompts");
+      console.log("\n  Generate CI pipeline configuration for MCPSpec.\n");
+      const detected = detectPlatform();
+      platform = await select({
+        message: "CI platform:",
+        choices: [
+          { name: "GitHub Actions", value: "github" },
+          { name: "GitLab CI", value: "gitlab" },
+          { name: "Shell script", value: "shell" }
+        ],
+        default: detected ?? void 0
+      });
+      const detectedCollection = detectCollection();
+      collection = await input({
+        message: "Collection file path:",
+        default: detectedCollection ?? "./mcpspec.yaml"
+      });
+      server = await input({
+        message: "Server command (for audit/score/bench, leave empty to skip):",
+        default: ""
+      });
+      checks = await checkbox({
+        message: "Which checks to run?",
+        choices: [
+          { name: "Test collections", value: "test", checked: true },
+          { name: "Security audit", value: "audit", checked: true },
+          { name: "MCP Score", value: "score", checked: false },
+          { name: "Performance benchmark", value: "bench", checked: false }
+        ]
+      });
+      if (checks.length === 0) {
+        console.error("No checks selected. At least one check is required.");
+        process.exit(EXIT_CODES11.CONFIG_ERROR);
+      }
+      if (checks.includes("audit")) {
+        failOn = await select({
+          message: "Fail on audit severity:",
+          choices: [
+            { name: "critical", value: "critical" },
+            { name: "high (recommended)", value: "high" },
+            { name: "medium", value: "medium" },
+            { name: "low", value: "low" }
+          ],
+          default: "high"
+        });
+      }
+      if (checks.includes("score")) {
+        const wantMinScore = await confirm({
+          message: "Set a minimum MCP Score threshold?",
+          default: false
+        });
+        if (wantMinScore) {
+          const scoreStr = await input({
+            message: "Minimum score (0-100):",
+            default: "70"
+          });
+          minScore = Number(scoreStr);
+          if (isNaN(minScore) || minScore < 0 || minScore > 100) {
+            console.error("Score must be a number between 0 and 100.");
+            process.exit(EXIT_CODES11.CONFIG_ERROR);
+          }
+        }
+      }
+    } else if (!platform) {
+      platform = detectPlatform() ?? "shell";
+    }
+    if (minScore !== null && (isNaN(minScore) || minScore < 0 || minScore > 100)) {
+      console.error("--min-score must be a number between 0 and 100.");
+      process.exit(EXIT_CODES11.CONFIG_ERROR);
+    }
+    const config = { platform, collection, server, checks, failOn, minScore };
+    const outputPath = getOutputPath(platform);
+    const resolvedPath = resolve4(outputPath);
+    const force = options.force === true;
+    const fileExists = existsSync2(resolvedPath);
+    if (platform === "gitlab" && fileExists) {
+      const existing = readFileSync3(resolvedPath, "utf-8");
+      const hasMcpspec = existing.includes("mcpspec");
+      const newJob = renderGitLabCI(config);
+      if (hasMcpspec && !force) {
+        console.error(`MCPSpec job already exists in ${outputPath}. Use --force to overwrite, or edit manually.`);
+        process.exit(EXIT_CODES11.CONFIG_ERROR);
+      }
+      if (hasMcpspec && force) {
+        const replaced = replaceGitLabJob(existing, newJob);
+        if (replaced) {
+          writeFileSync4(resolvedPath, replaced, "utf-8");
+          console.log(`
+Replaced MCPSpec job in ${outputPath}`);
+        } else {
+          writeFileSync4(resolvedPath, existing.trimEnd() + "\n\n" + newJob, "utf-8");
+          console.log(`
+Appended MCPSpec job to ${outputPath}`);
+        }
+      } else {
+        writeFileSync4(resolvedPath, existing.trimEnd() + "\n\n" + newJob, "utf-8");
+        console.log(`
+Appended MCPSpec job to ${outputPath}`);
+      }
+    } else {
+      if (fileExists && !force) {
+        console.error(`File already exists: ${outputPath}. Use --force to overwrite.`);
+        process.exit(EXIT_CODES11.CONFIG_ERROR);
+      }
+      let content;
+      switch (platform) {
+        case "github":
+          content = renderGitHubActions(config);
+          break;
+        case "gitlab":
+          content = renderGitLabCI(config);
+          break;
+        case "shell":
+          content = renderShellScript(config);
+          break;
+      }
+      const parentDir = resolve4(outputPath, "..");
+      if (!existsSync2(parentDir)) {
+        mkdirSync2(parentDir, { recursive: true });
+      }
+      writeFileSync4(resolvedPath, content, "utf-8");
+      if (platform === "shell") {
+        chmodSync(resolvedPath, 493);
+      }
+      console.log(`
+Created ${outputPath}`);
+    }
+    console.log(`
+  Platform:   ${platform}`);
+    console.log(`  Checks:     ${checks.join(", ")}`);
+    if (checks.includes("audit")) console.log(`  Fail on:    ${failOn}`);
+    if (minScore !== null) console.log(`  Min score:  ${minScore}`);
+    if (server) console.log(`  Server:     ${server}`);
+    console.log(`  Collection: ${collection}`);
+    console.log("");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Failed to generate CI config: ${message}`);
+    process.exit(EXIT_CODES11.ERROR);
+  }
+});
+
+// src/commands/mock.ts
+import { Command as Command13 } from "commander";
+import { writeFileSync as writeFileSync5, chmodSync as chmodSync2 } from "fs";
+import { EXIT_CODES as EXIT_CODES12 } from "@mcpspec/shared";
+import {
+  RecordingStore as RecordingStore2,
+  MockMCPServer,
+  MockGenerator,
+  formatError as formatError8
+} from "@mcpspec/core";
+var COLORS7 = {
+  reset: "\x1B[0m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m"
+};
+var mockCommand = new Command13("mock").description("Start a mock MCP server from a saved recording").argument("<recording>", "Recording name (from mcpspec record)").option("--mode <mode>", "Matching strategy: match or sequential", "match").option("--latency <ms>", 'Response delay: 0, milliseconds, or "original"', "0").option("--on-missing <behavior>", "Unrecorded tool behavior: error or empty", "error").option("--generate <path>", "Generate standalone .js file instead of starting server").action(async (recordingName, options) => {
+  try {
+    const mode = options.mode;
+    if (mode !== "match" && mode !== "sequential") {
+      console.error(`${COLORS7.red}Error: --mode must be "match" or "sequential"${COLORS7.reset}`);
+      process.exit(EXIT_CODES12.VALIDATION_ERROR);
+    }
+    const onMissing = options.onMissing;
+    if (onMissing !== "error" && onMissing !== "empty") {
+      console.error(`${COLORS7.red}Error: --on-missing must be "error" or "empty"${COLORS7.reset}`);
+      process.exit(EXIT_CODES12.VALIDATION_ERROR);
+    }
+    const latency = options.latency === "original" ? "original" : parseInt(options.latency, 10);
+    if (typeof latency === "number" && isNaN(latency)) {
+      console.error(`${COLORS7.red}Error: --latency must be a number or "original"${COLORS7.reset}`);
+      process.exit(EXIT_CODES12.VALIDATION_ERROR);
+    }
+    const store = new RecordingStore2();
+    const recording = store.load(recordingName);
+    if (!recording) {
+      console.error(`${COLORS7.red}Error: Recording "${recordingName}" not found${COLORS7.reset}`);
+      console.error(`${COLORS7.dim}  Available recordings: ${store.list().join(", ") || "(none)"}${COLORS7.reset}`);
+      process.exit(EXIT_CODES12.CONFIG_ERROR);
+    }
+    if (options.generate) {
+      const generator = new MockGenerator();
+      const code = generator.generate({ recording, mode, latency, onMissing });
+      writeFileSync5(options.generate, code, "utf-8");
+      try {
+        chmodSync2(options.generate, 493);
+      } catch {
+      }
+      console.error(`${COLORS7.green}Generated mock server: ${options.generate}${COLORS7.reset}`);
+      console.error(`${COLORS7.dim}  Run: node ${options.generate}${COLORS7.reset}`);
+      console.error(`${COLORS7.dim}  Requires: @modelcontextprotocol/sdk${COLORS7.reset}`);
+      process.exit(EXIT_CODES12.SUCCESS);
+    }
+    console.error(`${COLORS7.cyan}MCPSpec Mock Server${COLORS7.reset}`);
+    console.error(`${COLORS7.dim}  Recording: ${recording.name}${COLORS7.reset}`);
+    console.error(`${COLORS7.dim}  Tools: ${recording.tools.map((t) => t.name).join(", ")}${COLORS7.reset}`);
+    console.error(`${COLORS7.dim}  Steps: ${recording.steps.length}${COLORS7.reset}`);
+    console.error(`${COLORS7.dim}  Mode: ${mode} | Latency: ${latency}ms | On missing: ${onMissing}${COLORS7.reset}`);
+    console.error("");
+    const server = new MockMCPServer({ recording, mode, latency, onMissing });
+    await server.start();
+  } catch (err) {
+    const formatted = formatError8(err);
+    console.error(`
+  ${formatted.title}: ${formatted.description}`);
+    formatted.suggestions.forEach((s) => console.error(`    - ${s}`));
+    process.exit(formatted.exitCode);
+  }
+});
+
 // src/index.ts
 var __cliDir = dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync3(join2(__cliDir, "..", "package.json"), "utf-8"));
-var program = new Command12();
+var pkg = JSON.parse(readFileSync4(join3(__cliDir, "..", "package.json"), "utf-8"));
+var program = new Command14();
 program.name("mcpspec").description("The definitive MCP server testing platform").version(pkg.version);
 program.addCommand(testCommand);
 program.addCommand(inspectCommand);
@@ -1409,4 +1850,6 @@ program.addCommand(benchCommand);
 program.addCommand(docsCommand);
 program.addCommand(scoreCommand);
 program.addCommand(recordCommand);
+program.addCommand(ciInitCommand);
+program.addCommand(mockCommand);
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpspec",
-  "version": "1.1.0",
+  "version": "1.2.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.1.0",
-    "@mcpspec/shared": "1.1.0",
-    "@mcpspec/server": "1.1.0"
+    "@mcpspec/server": "1.2.0",
+    "@mcpspec/core": "1.2.0",
+    "@mcpspec/shared": "1.2.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",