🇬🇧 English version

MCP Server Tester

Высококлассный инструмент для тестирования MCP серверов с поддержкой протокола SSE-HTTP-STDIO, авторизацией по Bearer токену и написанием тестовых сценариев через конфигурационные файлы без необходимости программирования.

🚀 Доступен на всех платформах

👨‍💻 Автор

Создано @ii_pomogator - Канал ИИ-помогатор в Telegram

✨ Ключевые возможности

• 🔌 Полная поддержка SSE-HTTP-STDIO протокола для MCP серверов
• 🔐 Bearer токен авторизация для безопасного тестирования
• 📝 Декларативные тесты - пишите сценарии в YAML без программирования
• 🎯 Множественные assertion типы - проверяйте любые аспекты ответов
• 📊 Детальные отчеты о прохождении тестов
• 🐳 Docker поддержка для изолированного тестирования
• 🔄 CI/CD интеграция через GitHub Actions

📦 Установка

NPM (Node.js)

npm install -g mcp-server-tester-sse-http-stdio

PyPI (Python)

pip install mcp-server-tester-sse-stdio

Docker

docker pull stgmt/mcp-server-tester

🚀 Быстрый старт

Использование через NPM

npx mcp-server-tester-sse-http-stdio test --test test.yaml --server-config config.json

Использование через Python

mcp-server-tester test --test test.yaml --server-config config.json

Использование через Docker

docker run -v $(pwd):/workspace stgmt/mcp-server-tester test --test /workspace/test.yaml

📝 Пример тестового сценария

name: "MCP Server Basic Test"
description: "Проверка базовой функциональности MCP сервера"
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!"

📋 Конфигурация сервера

{
  "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 команды

Запуск тестов

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

Options:
  --server-name <name>  Имя сервера из конфигурации
  --verbose            Подробный вывод
  --json-output        Вывод результатов в JSON формате
  --timeout <ms>       Таймаут для тестов (по умолчанию: 30000)

Валидация конфигурации

mcp-server-tester validate --test <test-file>

Список доступных инструментов сервера

mcp-server-tester tools --server-config <config-file> --server-name <name>

🐳 Docker поддержка

Простой запуск

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

Поддерживаемые платформы

| Платформа | Архитектура | Статус | |-----------|-------------|--------| | Linux | amd64 | ✅ | | Linux | arm64 | ✅ | | macOS | amd64 | ✅ | | macOS | arm64 | ✅ | | Windows | amd64 | ✅ |

🔄 CI/CD интеграция

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

Проверка структуры ответа

expect:
  status: "success"
  result:
    type: "object"
    properties:
      message:
        type: "string"
        pattern: "^Hello.*"
      count:
        type: "number"
        minimum: 0

Проверка массивов

expect:
  tools:
    type: "array"
    minItems: 1
    items:
      type: "object"
      required: ["name", "description"]

Условные проверки

expect:
  oneOf:
    - status: "success"
      result: { processed: true }
    - status: "pending"
      result: { queued: true }

🔧 Расширенные возможности

Переменные окружения

tests:
  - name: "Test with env variables"
    env:
      API_KEY: "${TEST_API_KEY}"
      BASE_URL: "${TEST_BASE_URL:-http://localhost:3000}"

Последовательные тесты с зависимостями

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_groups:
  - name: "Performance tests"
    tests:
      - name: "Test 1"
      - name: "Test 2"
      - name: "Test 3"

📚 Документация

• Полное руководство
• API Reference
• Примеры тестов
• FAQ

🤝 Вклад в проект

Мы приветствуем вклад в развитие проекта! См. CONTRIBUTING.md для деталей.

📄 Лицензия

MIT License - см. LICENSE файл.

🔗 Ссылки

• GitHub: stgmt/mcp-server-tester-sse-http-stdio
• NPM: mcp-server-tester-sse-http-stdio
• PyPI: mcp-server-tester
• Docker Hub: stgmt/mcp-server-tester

💬 Поддержка

• Создать Issue
• Discussions
• Email: [email protected]

Разработано с ❤️ @ii_pomogator