Sign inSign up

stgmt/mcp-server-tester-sse-http-stdio

By stgmt

β€’Updated 10 months ago
Archived

πŸ§ͺ MCP Server Testing Framework - Multi-platform Docker image for testing Model Context Protocol s

Image
Integration & delivery
Machine learning & AI
Developer tools
0

3.3K

stgmt/mcp-server-tester-sse-http-stdio repository overview

πŸ‡·πŸ‡Ί Русская вСрсия⁠

⁠MCP Server Tester - High-performance testing framework for MCP servers with SSE-HTTP-STDIO protocol support, Bearer token authorization, and declarative test scenarios

A high-performance tool for testing MCP servers with SSE-HTTP-STDIO protocol support, Bearer token authorization, and test scenario writing through configuration files without programming.

β πŸš€ Available on All Platforms

npm version PyPI version Docker Hub GitHub Actions

β πŸ‘¨β€πŸ’» Author

Created by @ii_pomogator⁠ - AI Assistant Channel on Telegram

⁠✨ Key Features

  • πŸ”Œ Full SSE-HTTP-STDIO protocol support for MCP servers
  • πŸ” Bearer token authorization for secure testing
  • πŸ“ Declarative tests - write scenarios in YAML without programming
  • 🎯 Multiple assertion types - verify any aspects of responses
  • πŸ“Š Detailed reports on test execution
  • 🐳 Docker support for isolated testing
  • πŸ”„ CI/CD integration via GitHub Actions

β πŸ“¦ Installation

⁠NPM (Node.js)
npm install -g mcp-server-tester-sse-http-stdio
⁠PyPI (Python)
pip install mcp-server-tester
⁠Docker
docker pull stgmt/mcp-server-tester

β πŸš€ Quick Start

⁠Using NPM
npx mcp-server-tester-sse-http-stdio test --test test.yaml --server-config config.json
⁠Using Python
mcp-server-tester test --test test.yaml --server-config config.json
⁠Using Docker
docker run -v $(pwd):/workspace stgmt/mcp-server-tester test --test /workspace/test.yaml

β πŸ“ Example Test Scenario

name: "MCP Server Basic Test"
description: "Testing basic MCP server functionality"
timeout: 30000

tests:
  - name: "Initialize connection"
    type: "initialize"
    params:
      protocolVersion: "1.0.0"
      capabilities:
        tools: true
    expect:
      status: "success"
      capabilities:
        tools: true

  - name: "List available tools"
    type: "tools/list"
    expect:
      status: "success"
      tools:
        - name: "echo"
          description: "Echo tool"

  - name: "Call echo tool"
    type: "tools/call"
    params:
      name: "echo"
      arguments:
        message: "Hello, MCP!"
    expect:
      status: "success"
      result:
        message: "Hello, MCP!"

β πŸ“‹ Server Configuration

{
  "mcpServers": {
    "test-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "BEARER_TOKEN": "your-secret-token"
      },
      "transport": {
        "type": "sse",
        "config": {
          "url": "http://localhost:3000/sse",
          "headers": {
            "Authorization": "Bearer your-secret-token"
          }
        }
      }
    }
  }
}

β πŸ› οΈ CLI Commands

⁠Run Tests
mcp-server-tester test --test <test-file> --server-config <config-file> [options]

Options:
  --server-name <name>  Server name from configuration
  --verbose            Verbose output
  --json-output        Output results in JSON format
  --timeout <ms>       Test timeout (default: 30000)
⁠Validate Configuration
mcp-server-tester validate --test <test-file>
⁠List Available Server Tools
mcp-server-tester tools --server-config <config-file> --server-name <name>

⁠🐳 Docker Support

⁠Simple Run
docker run -v $(pwd):/workspace stgmt/mcp-server-tester \
  test --test /workspace/test.yaml --server-config /workspace/config.json
⁠Docker Compose
version: '3.8'
services:
  mcp-tester:
    image: stgmt/mcp-server-tester
    volumes:
      - ./tests:/workspace/tests
      - ./config:/workspace/config
    command: test --test /workspace/tests/test.yaml --server-config /workspace/config/server.json
⁠Supported Platforms
PlatformArchitectureStatus
Linuxamd64βœ…
Linuxarm64βœ…
macOSamd64βœ…
macOSarm64βœ…
Windowsamd64βœ…

β πŸ”„ CI/CD Integration

⁠GitHub Actions
name: MCP Server Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run MCP Server Tests
        run: |
          docker run -v ${{ github.workspace }}:/workspace \
            stgmt/mcp-server-tester test \
            --test /workspace/tests/test.yaml \
            --server-config /workspace/config.json
⁠GitLab CI
mcp-tests:
  image: stgmt/mcp-server-tester
  script:
    - mcp-server-tester test --test tests/test.yaml --server-config config.json

β πŸ“Š Assertion Examples

⁠Response Structure Validation
expect:
  status: "success"
  result:
    type: "object"
    properties:
      message:
        type: "string"
        pattern: "^Hello.*"
      count:
        type: "number"
        minimum: 0
⁠Array Validation
expect:
  tools:
    type: "array"
    minItems: 1
    items:
      type: "object"
      required: ["name", "description"]
⁠Conditional Validation
expect:
  oneOf:
    - status: "success"
      result: { processed: true }
    - status: "pending"
      result: { queued: true }

β πŸ”§ Advanced Features

⁠Environment Variables
tests:
  - name: "Test with env variables"
    env:
      API_KEY: "${TEST_API_KEY}"
      BASE_URL: "${TEST_BASE_URL:-http://localhost:3000}"
⁠Sequential Tests with Dependencies
tests:
  - name: "Create resource"
    id: "create"
    type: "tools/call"
    params:
      name: "create_resource"
    capture:
      resource_id: "$.result.id"
  
  - name: "Get created resource"
    depends_on: ["create"]
    type: "tools/call"
    params:
      name: "get_resource"
      arguments:
        id: "${resource_id}"
⁠Parallel Execution
parallel_groups:
  - name: "Performance tests"
    tests:
      - name: "Test 1"
      - name: "Test 2"
      - name: "Test 3"

β πŸ“š Documentation

⁠🀝 Contributing

We welcome contributions to the project! See CONTRIBUTING.md⁠ for details.

β πŸ“„ License

MIT License - see LICENSE⁠ file.

β πŸ”— Links

β πŸ’¬ Support

Developed with ❀️ by @ii_pomogator⁠

Tag summary

Content type

Image

Digest

sha256:bbe3cd926…

Size

193.8 MB

Last updated

10 months ago

docker pull stgmt/mcp-server-tester-sse-http-stdio