npm install -g mcpspec

mcpspec --version

# Install
npm install -g mcpspec

# Run a community test suite (filesystem server)
mcpspec test examples/collections/servers/filesystem.yaml

# Or explore a server interactively
mcpspec inspect "npx -y @modelcontextprotocol/server-filesystem /tmp"

name: My First Tests
server: npx -y @modelcontextprotocol/server-filesystem /tmp

tests:
  - name: List allowed directories
    call: list_allowed_directories
    expect:
      - exists: $.content

  - name: Read a test file
    call: read_file
    with:
      path: /tmp/mcpspec-test.txt
    expect:
      - exists: $.content

  - name: Handle missing file
    call: read_file
    with:
      path: /tmp/nonexistent-file-12345.txt
    expectError: true

mcpspec test

name: Simple Filesystem Tests
server: npx -y @modelcontextprotocol/server-filesystem /tmp

tests:
  - name: List allowed directories
    call: list_allowed_directories
    expect:
      - exists: $.content

  - name: Read a test file
    call: read_file
    with:
      path: /tmp/mcpspec-test.txt
    expect:
      - exists: $.content

  - name: Handle missing file
    call: read_file
    with:
      path: /tmp/nonexistent-file-12345.txt
    expectError: true

schemaVersion: "1.0"
name: Environment-Aware Tests
description: Tests that use environment variables

server:
  transport: stdio
  command: npx
  args: ["-y", "@modelcontextprotocol/server-filesystem", "{{baseDir}}"]

environments:
  dev:
    variables:
      baseDir: /tmp
  staging:
    variables:
      baseDir: /var/tmp

defaultEnvironment: dev

tests:
  - id: test-list
    name: List directories
    tags: [smoke]
    call: list_allowed_directories
    assertions:
      - type: schema
      - type: latency
        maxMs: 10000

  - id: test-read
    name: Read test file
    tags: [integration]
    call: read_file
    with:
      path: "{{baseDir}}/mcpspec-test.txt"
    assertions:
      - type: exists
        path: $.content

server: npx -y @modelcontextprotocol/server-filesystem /tmp

server:
  transport: stdio
  command: npx
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  env:
    NODE_ENV: test
  timeouts:
    connect: 10000
    call: 30000

# Server-Sent Events
server:
  transport: sse
  url: http://localhost:3000/sse

# Streamable HTTP
server:
  transport: streamable-http
  url: http://localhost:3000/mcp

environments:
  dev:
    variables:
      baseDir: /tmp
      apiUrl: http://localhost:3000
  prod:
    variables:
      baseDir: /data
      apiUrl: https://api.example.com

defaultEnvironment: dev

mcpspec test --env prod

tests:
  - name: Quick smoke test
    tags: [smoke, api]
    call: health_check

# Run only smoke tests
mcpspec test --tag smoke

# The @ prefix is optional and stripped automatically
mcpspec test --tag @smoke

tests:
  - name: Flaky network call
    call: fetch_data
    timeout: 15000    # 15s timeout for this test
    retries: 2        # Retry up to 2 times on error

expect:
  - exists: $.content           # Path exists
  - equals: [$.id, 123]         # Exact match
  - contains: [$.tags, "active"] # Contains value
  - matches: [$.email, ".*@.*"] # Regex match

assertions:
  - type: exists
    path: $.content
  - type: equals
    path: $.id
    value: 123
  - type: latency
    maxMs: 1000

# Shorthand — not available, use full format
assertions:
  - type: schema

# Shorthand
expect:
  - equals: [$.id, 123]

# Full
assertions:
  - type: equals
    path: $.id
    value: 123

# Shorthand
expect:
  - contains: [$.tags, "active"]

# Full
assertions:
  - type: contains
    path: $.tags
    value: "active"

# Shorthand
expect:
  - exists: $.content

# Full
assertions:
  - type: exists
    path: $.content

# Shorthand
expect:
  - matches: [$.email, ".*@.*\\.com"]

# Full
assertions:
  - type: matches
    path: $.email
    pattern: ".*@.*\\.com"

assertions:
  - type: type
    path: $.count
    expected: number   # string, number, boolean, object, array

assertions:
  - type: length
    path: $.items
    operator: gt    # eq, gt, gte, lt, lte
    value: 0

assertions:
  - type: latency
    maxMs: 1000   # milliseconds

assertions:
  - type: expression
    expr: "response.items.length > 0 and response.total == response.items.length"

mcpspec test [collection]

# Run with tags and parallel
mcpspec test --tag smoke --parallel 4

# CI mode with JUnit output
mcpspec test --ci --reporter junit --output results.xml

# Compare against baseline
mcpspec test --baseline main

mcpspec inspect <server>

mcpspec inspect "npx -y @modelcontextprotocol/server-filesystem /tmp"
# > .tools
# > .call read_file {"path": "/tmp/test.txt"}
# > .schema read_file
# > .exit

mcpspec record start <server>           # Record a session
mcpspec record list                      # List saved recordings
mcpspec record replay <name> <server>   # Replay and diff
mcpspec record delete <name>             # Delete a recording

mcpspec mock <recording> [options]

# Start mock server (stdin/stdout)
mcpspec mock my-api

# Tape/cassette style matching
mcpspec mock my-api --mode sequential

# Simulate original response timing
mcpspec mock my-api --latency original

# Generate standalone .js file (only requires @modelcontextprotocol/sdk)
mcpspec mock my-api --generate ./mocks/server.js
node ./mocks/server.js

mcpspec audit <server> [options]

# Passive scan (safe for production)
mcpspec audit "npx my-server"

# Active scan with CI gate
mcpspec audit "npx my-server" --mode active --acknowledge-risk --fail-on medium

# Preview what would be scanned
mcpspec audit "npx my-server" --dry-run

mcpspec score <server> [options]

mcpspec score "npx my-server"
mcpspec score "npx my-server" --badge ./badge.svg --min-score 80

mcpspec bench <server> [options]

mcpspec bench "npx my-server" --iterations 200 --tool echo --args '{"message":"test"}'

mcpspec docs <server> [options]

mcpspec docs "npx my-server" --format html --output ./docs

# Save current results as a baseline
mcpspec baseline save main

# List saved baselines
mcpspec baseline list

# Compare two runs
mcpspec compare <run1> <run2>

# Compare against a baseline
mcpspec compare --baseline main

mcpspec init [directory] --template <minimal|standard|full>

mcpspec ci-init [options]

# Interactive wizard
mcpspec ci-init

# Non-interactive
mcpspec ci-init --platform github --checks test,audit,score --fail-on medium --min-score 80

mcpspec ui [options]

# 1. Start a recording session
mcpspec record start "npx my-server"

# 2. Interact with the server (REPL)
# > .call get_user {"id": "1"}
# > .call list_items {}
# > .call create_item {"name": "test"}

# 3. Save the recording
# > .save my-api

# 4. List recordings
mcpspec record list

# 5. Replay against a new version — diffs results step-by-step
mcpspec record replay my-api "npx my-server-v2"

mcpspec mock my-api

mcpspec mock my-api --mode sequential

mcpspec mock my-api --latency original   # Simulate real timing
mcpspec mock my-api --latency 100        # Fixed 100ms delay

mcpspec mock my-api --generate ./mocks/server.js
node ./mocks/server.js

mcpspec mock my-api --on-missing error   # Return error (default)
mcpspec mock my-api --on-missing empty   # Return empty content

mcpspec score "npx my-server" --badge ./mcp-score.svg

name: MCP Server Tests
on: [push, pull_request]

jobs:
  mcpspec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g mcpspec

      - name: Run tests
        run: mcpspec test --ci --reporter junit --output results.xml

      - name: Security audit
        run: mcpspec audit "npx my-server" --mode passive --fail-on high

      - name: Quality gate
        run: mcpspec score "npx my-server" --min-score 80

      - uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: results.xml

mcpspec:
  image: node:22
  stage: test
  script:
    - npm install -g mcpspec
    - mcpspec test --ci --reporter junit --output results.xml
    - mcpspec audit "npx my-server" --mode passive --fail-on high
  artifacts:
    when: always
    paths:
      - results.xml
    reports:
      junit: results.xml
    expire_in: 1 week

#!/bin/bash
# .git/hooks/pre-commit
if git diff --cached --name-only | grep -q "collections/.*\.yaml$"; then
  mcpspec test $(git diff --cached --name-only | grep "collections/.*\.yaml$")
fi

# Shorthand
server: npx my-server /tmp

# Explicit
server:
  transport: stdio
  command: npx
  args: ["my-server", "/tmp"]
  env:
    NODE_ENV: test

server:
  transport: sse
  url: http://localhost:3000/sse

server:
  transport: streamable-http
  url: http://localhost:3000/mcp

# Top-level fields
schemaVersion: "1.0"            # Optional, currently "1.0"
name: string                    # Required — collection name
description: string             # Optional
server: string | ServerConfig   # Required — see Server Configuration
environments:                   # Optional — named variable sets
  <name>:
    variables:
      <key>: <value>
defaultEnvironment: string      # Optional
tests:                          # Required — at least 1 test
  - id: string                  # Optional — unique identifier
    name: string                # Required — display name
    tags: string[]              # Optional — for --tag filtering
    timeout: number             # Optional — ms, default 30000
    retries: number             # Optional — retry on error
    type: tool                  # Optional — default "tool"
    call: string                # Tool name to invoke
    tool: string                # Alias for call
    with: object                # Tool input arguments
    input: object               # Alias for with
    expect: Shorthand[]         # Shorthand assertions
    assertions: Assertion[]     # Full assertions
    expectError: boolean        # Expect error response
    extract:                    # Optional — extract variables
      - name: string
        path: string            # JSONPath

# ServerConfig object
server:
  name: string                  # Optional
  transport: stdio|sse|streamable-http  # Default: stdio
  command: string               # For stdio
  args: string[]                # For stdio
  url: string                   # For SSE/HTTP
  env: Record<string, string>  # Environment variables
  timeouts:
    connect: number             # Connection timeout (ms)
    call: number                # Call timeout (ms)

# Assertion object
assertions:
  - type: schema|equals|contains|exists|matches|type|length|latency|mimeType|expression
    path: string                # JSONPath (for value assertions)
    value: any                  # Expected value
    expected: any               # Expected type or mime type
    pattern: string             # Regex pattern
    maxMs: number               # Max latency
    operator: eq|gt|gte|lt|lte  # For length
    expr: string                # Safe expression