Руководство по интеграциям

Mockarty – это не просто автономный мок-сервер, а платформа из нескольких компонентов, работающих вместе. В этом руководстве описано, как подключить внешние компоненты (ноды resolver, runner agent, генераторы кода) и интегрировать Mockarty в рабочий процесс разработки (CI/CD, MCP для AI-инструментов, вебхуки, мониторинг).

Новичок в Mockarty? Начните с Быстрого старта, чтобы запустить один экземпляр. Возвращайтесь сюда, когда потребуется масштабирование или автоматизация.

Совет: Примеры кода доступны для cURL, CLI и SDK-клиентов (Go, Python, Java). Смотрите Руководство по SDK для установки и настройки. Смотрите Руководство по CLI для командной утилиты.

URL-адреса в примерах: Во всех примерах используется localhost:5770 как адрес Mockarty по умолчанию. Если ваш экземпляр работает на удалённом сервере, замените localhost:5770 на реальный адрес (например, https://mockarty.company.com или http://192.168.1.50:5770). Подробнее — в разделе Полезные функции и советы.

Содержание

• Обзор
• Токены интеграции
• Ноды Mock Resolver
• Runner Agent
• Server Generator и API-First подход
• MCP-сервер (Model Context Protocol)
• Интеграция с CI/CD
• Webhook-уведомления
• Телеметрия и мониторинг
• Архитектурные диаграммы
• Управление интеграциями в Kubernetes

Обзор

Mockarty поддерживает распределённую архитектуру, которая позволяет масштабировать обработку
моков, выполнение тестов и генерацию кода на нескольких нодах. Это руководство описывает,
как подключить внешние компоненты к административной ноде Mockarty и внедрить API-first подход
в разработке.

Существует три типа внешних компонентов, подключаемых к Mockarty:

Вся межсерверная коммуникация защищена токенами интеграции — специальными учётными данными,
отдельными от пользовательских API-токенов.

Токены интеграции

Что такое токены интеграции?

Токены интеграции — это учётные данные для межсерверной аутентификации между нодами Mockarty.
Они отличаются от пользовательских API-токенов:

Зачем два типа токенов?

Представьте пропуска в здании: бейджи сотрудников (mk_*) идентифицируют людей и пропускают их через главный вход (REST API, CI/CD). Ключи от серверной (mki_*) позволяют серверам общаться друг с другом за кулисами (gRPC-координатор). Разделение означает:

• Отзыв пользовательского токена не ломает инфраструктуру resolver/runner.
• Отзыв токена интеграции отключает конкретную ноду, не затрагивая пользователей.
• Аудит становится понятнее – сразу видно, пришло ли действие от человека или от машины.
• Права разграничены – токены интеграции дают только специфичные для ноды операции (регистрация, heartbeat, получение задач), а пользовательские токены дают доступ к API.

Токены интеграции хешируются перед сохранением – Mockarty никогда не хранит
токен в открытом виде. Токен отображается только один раз при создании. Скопируйте его
немедленно.

Создание токенов интеграции

Через интерфейс

1. Перейдите в Settings > Integrations
2. Нажмите Create Integration
3. Выберите тип токена:
   • mock_resolver — для нод Mock Resolver
   • test_runner — для Runner Agent
   • orchestrator — для оркестратора Server Generator
4. Введите описательное имя (например, resolver-eu-west-1, runner-ci-pipeline)
5. Нажмите Create
6. Скопируйте токен из диалога подтверждения

Через API

cURL

curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mk_your_admin_api_token" \
  -d '{
    "name": "resolver-prod-1",
    "type": "mock_resolver"
  }'

CLI

# Создание токена интеграции
mockarty-cli integration create --name resolver-prod-1 --type mock_resolver

Go

// Создание токена интеграции
integration, err := client.Integrations().Create(ctx, &mockarty.CreateIntegrationRequest{
    Name: "resolver-prod-1",
    Type: "mock_resolver",
})
// integration.Token -- токен (показывается только один раз)

Python

# Создание токена интеграции
integration = client.integrations.create(name="resolver-prod-1", type="mock_resolver")
# integration["token"] -- токен (показывается только один раз)

Java

// Создание токена интеграции
var integration = client.integrations().create("resolver-prod-1", "mock_resolver");
// integration.getToken() -- токен (показывается только один раз)

Ответ:

{
  "integration": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "resolver-prod-1",
    "type": "mock_resolver",
    "enabled": true,
    "createdAt": "2026-03-13T10:00:00Z"
  },
  "token": "mki_abc123def456..."
}

Важно: Поле token возвращается только в ответе на запрос создания. Сохраните его в
безопасном месте.

Типы токенов

mock_resolver — предоставляет ноде права на:

• Получение конфигураций моков от административной ноды
• Обработку входящих запросов моков
• Отправку статуса здоровья обратно координатору

test_runner — предоставляет ноде права на:

• Получение задач API-тестов и нагрузочных тестов
• Отправку результатов тестов обратно в административную ноду
• Доступ к определениям моков, необходимым для выполнения тестов

orchestrator — предоставляет ноде права на:

• Доступ к API оркестратора Server Generator
• Создание и управление сгенерированными серверами
• Синхронизацию определений моков для сгенерированных серверов

Отзыв токенов

Чтобы отозвать токен интеграции:

1. Перейдите в Settings > Integrations
2. Найдите интеграцию в списке
3. Нажмите Disable для временной приостановки или Delete для окончательного отзыва

Через API:

# Отзыв (мягкий — нода перестаёт получать задачи на следующем heartbeat)
curl -X POST http://localhost:5770/api/v1/integrations/INTEGRATION_ID/revoke \
  -H "Authorization: Bearer mk_your_admin_api_token"

# Удаление (окончательное)
curl -X DELETE http://localhost:5770/api/v1/integrations/INTEGRATION_ID \
  -H "Authorization: Bearer mk_your_admin_api_token"

При отзыве токена соответствующая нода теряет связь и перестаёт получать обновления
на следующем цикле heartbeat (обычно в течение 30 секунд).

Ноды Mock Resolver

Назначение

Аналогия: Представьте Admin Node как менеджера ресторана, а Mock Resolver как официантов. Менеджер занимается бронированием, изменением меню и персоналом (административные задачи). Официанты обслуживают заказы клиентов (запросы к мокам). Добавление официантов позволяет обслуживать больше клиентов, не перегружая менеджера.

Ноды Mock Resolver обрабатывают трафик резолвинга моков – фактическую отдачу ответов моков
вашим приложениям и тестам. Перенося резолвинг на выделенные ноды, вы оставляете
административную ноду для UI, конфигурации и координации.

Архитектура

Ваше приложение/тесты ──HTTP──▶ Mock Resolver :5780
                                      │
                                 gRPC :5773
                                      │
                                      ▼
                                Admin Node :5770

Resolver подключается к административной ноде через gRPC-координатор на порту 5773.
Он получает конфигурации моков и кеширует их локально для быстрого резолвинга. Обновления
передаются от административной ноды в реальном времени.

Когда использовать

• Высокий трафик моков: ноды resolver горизонтально масштабируются
• Разделение ответственности: административный UI и обслуживание моков на разных нодах
• Сетевая изоляция: размещение resolver ближе к тестовой инфраструктуре
• Высокая доступность: несколько resolver обеспечивают отказоустойчивость

Настройка

Шаг 1: Создание токена интеграции

Создайте токен типа mock_resolver (см. Токены интеграции).

Шаг 2: Скачивание бинарного файла

Скачайте бинарный файл mockarty-resolver для вашей платформы со страницы релизов Mockarty.

Шаг 3: Настройка переменных окружения

Базовое подключение:

Идентификация и область видимости:

Сеть:

Кэш и поведение Store:

Таймауты координатора:

Дашборд:

TLS к координатору (опционально):

Логирование:

Валидация при старте. Resolver откажется стартовать, если TLS-параметры несогласованы (например, COORDINATOR_TLS_INSECURE_SKIP_VERIFY=true без COORDINATOR_TLS=true, или клиентский mTLS-сертификат задан без парного ключа). Это сделано специально — молчаливое падение до plaintext или ослабленного TLS скрыло бы ошибки оператора.

Шаг 4: Запуск

export COORDINATOR_ADDR="admin.example.com:5773"
export API_TOKEN="mki_your_resolver_token"
export RESOLVER_NAME="resolver-1"
export HTTP_PORT="5780"

./mockarty-resolver

Resolver подключится к координатору, загрузит текущие конфигурации моков и начнёт
обслуживать ответы моков.

Маршрутизация трафика

После запуска resolver направьте трафик моков на него вместо административной ноды:

Пример — направление тестов на resolver:

# Раньше (напрямую к административной ноде)
curl http://admin:5770/api/users/123

# Теперь (к resolver)
curl http://resolver-1:5780/api/users/123

Несколько Resolver

Вы можете запустить несколько нод resolver и распределять нагрузку между ними:

# Resolver 1
COORDINATOR_ADDR="admin:5773" API_TOKEN="mki_token1" RESOLVER_NAME="resolver-1" HTTP_PORT=5780 ./mockarty-resolver

# Resolver 2
COORDINATOR_ADDR="admin:5773" API_TOKEN="mki_token2" RESOLVER_NAME="resolver-2" HTTP_PORT=5781 ./mockarty-resolver

Разместите HTTP-балансировщик нагрузки (nginx, HAProxy, облачный LB) перед ними для
равномерного распределения.

Health Check

Каждый resolver предоставляет endpoint проверки здоровья:

curl http://resolver-1:5780/health

Используйте его для health check балансировщика нагрузки и мониторинга.

Dashboard

Каждая нода resolver запускает лёгкий dashboard, показывающий статус подключения,
количество обработанных моков и метрики производительности:

http://resolver-1:6780/

Пример Docker

docker run -d \
  --name mockarty-resolver \
  -e COORDINATOR_ADDR="admin-host:5773" \
  -e API_TOKEN="mki_your_resolver_token" \
  -e RESOLVER_NAME="resolver-docker" \
  -e HTTP_PORT="5780" \
  -p 5780:5780 \
  -p 6780:6780 \
  mockarty/resolver:latest

Runner Agent

Назначение

Runner Agent выполняет коллекции API-тестов и нагрузочные тесты удалённо. Перенося
выполнение тестов на выделенные ноды runner, тяжёлые нагрузочные тесты не влияют
на производительность административной ноды.

Архитектура

Admin Node :5770
     │
gRPC :5773  (координатор отправляет задачи)
     │
     ▼
Runner Agent :6770  (выполняет тесты, отправляет результаты)

Runner подключается к административной ноде через gRPC-координатор. Когда пользователь
запускает тест или нагрузочный тест, координатор отправляет задачу доступному runner.
Результаты передаются обратно в административную ноду в потоковом режиме.

Когда использовать

• Нагрузочное тестирование: нагрузочные тесты генерируют значительный трафик — выполняйте их на выделенных нодах
• Распределённое тестирование: запускайте тесты из разных сетевых локаций или регионов
• Параллельное выполнение: несколько runner могут выполнять задачи одновременно
• Изоляция ресурсов: отделение выполнения тестов от административных операций

Настройка

Шаг 1: Создание токена интеграции

Создайте токен типа test_runner (см. Токены интеграции).

Шаг 2: Скачивание бинарного файла

Скачайте бинарный файл mockarty-runner для вашей платформы со страницы релизов Mockarty.

Шаг 3: Настройка переменных окружения

Runner поддерживает три режима подключения — выберите один и задайте соответствующую переменную адреса:

Базовое подключение:

Идентификация и область видимости:

Возможности и ёмкость:

Таймауты:

Безопасность:

Дашборд:

TLS к координатору (опционально):

Логирование:

Валидация при старте. На runner применяются те же TLS-инварианты: несогласованные TLS-параметры приводят к отказу старта, а не к молчаливой деградации.

Шаг 4: Запуск

export COORDINATOR_ADDR="admin.example.com:5773"
export API_TOKEN="mki_your_runner_token"
export RUNNER_NAME="runner-1"
export SHARED="true"
export CAPABILITIES="api_test,performance"
export MAX_CONCURRENT_TASKS="10"

./mockarty-runner

Scope: Shared и Namespace Runner

Shared runner (SHARED=true):

• Получают задачи из всех namespace
• Идеально подходят для общей тестовой инфраструктуры
• Обычно развёртываются командой платформы/DevOps

Namespace runner (SHARED=false, NAMESPACE=team-backend):

• Получают задачи только из назначенного namespace
• Идеально подходят для командной инфраструктуры
• Могут быть размещены ближе к ресурсам команды

Пример конфигурации:

# Shared runner — обрабатывает все namespace
SHARED=true CAPABILITIES="api_test,performance" ./mockarty-runner

# Командный runner — только namespace "payments"
SHARED=false NAMESPACE="payments" CAPABILITIES="api_test" ./mockarty-runner

Capabilities

Capabilities определяют, какие типы задач runner может принимать:

Runner может иметь несколько capabilities:

CAPABILITIES="api_test,performance"

Если runner имеет только api_test, он никогда не получит задачи нагрузочного тестирования,
и наоборот.

Метки раннеров (Runner Labels)

Метки — это произвольные теги, которые вы привязываете к интеграции раннера, чтобы
Test Plan, Schedule, Load Test, Fuzz или Chaos конфигурация могли выбирать конкретное
подмножество раннеров — например prod, staging, linux, arm64, gpu.

Метки опциональны. Если запуск не требует меток, выбор раннера работает как раньше
(ёмкость, capability, приоритет namespace, минимальная загрузка). Если запуск указал
одну или несколько обязательных меток, рассматриваются только раннеры, набор меток
которых является надмножеством требуемого набора.

Назначить метки на интеграцию

В UI откройте Settings → Integrations, разверните карточку раннера и нажмите кнопку
Edit labels — откроется чип-редактор. Редактор автоматически подсказывает уже
использующиеся метки в видимых для пользователя пространствах.

Через API:

curl -X PATCH https://mockarty.example/api/v1/integrations/<id>/labels \
  -H "Authorization: Bearer mk_<your_token>" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["prod", "linux", "arm64"]}'

Метки нормализуются к нижнему регистру и могут содержать только a-z, 0-9, .,
-, _, не более 64 символов на метку.

Получить список меток в namespace

Эндпоинт ниже используется автокомплитом, но подходит и для скриптов:

curl https://mockarty.example/api/v1/runners/labels?namespace=team-backend \
  -H "Authorization: Bearer mk_<your_token>"

Возвращает дедуплицированный отсортированный набор меток, видимых в указанном
пространстве (собственные + admin-scoped/общие раннеры).

Требовать метки при запуске

Добавьте поле requiredRunnerLabels в тело запроса. Примеры:

Performance:

curl -X POST https://mockarty.example/api/v1/perf/run \
  -H "Authorization: Bearer mk_<your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "<perf-config-id>",
    "requiredRunnerLabels": ["prod", "arm64"]
  }'

Fuzz:

curl -X POST https://mockarty.example/api/v1/fuzzing/run \
  -H "Authorization: Bearer mk_<your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "<fuzz-config-id>",
    "requiredRunnerLabels": ["staging"]
  }'

Test Plan (метки сохраняются на плане и применяются ко всем элементам):

curl -X POST https://mockarty.example/api/v1/test-plans \
  -H "Authorization: Bearer mk_<your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "team-backend",
    "name": "Nightly regression",
    "items": [...],
    "requiredRunnerLabels": ["prod"]
  }'

Поведение, если нет подходящего раннера

Если requiredRunnerLabels непустое и ни один доступный раннер не удовлетворяет
требованию, задача завершается с понятным сообщением (а не падает в локальное
выполнение):

no available runner with required labels [prod arm64]
(capacity, capability, or labels do not match)

Льготный период (5 минут с момента создания задачи) даёт возможность подходящему
раннеру подключиться до того, как задача будет помечена как failed.

Несколько Runner

Вы можете запустить несколько runner agent. Координатор автоматически распределяет задачи
на основе доступности и capabilities:

# Runner 1 — только API-тесты
RUNNER_NAME="runner-api-1" CAPABILITIES="api_test" UI_PORT=6770 ./mockarty-runner

# Runner 2 — только нагрузочные тесты
RUNNER_NAME="runner-perf-1" CAPABILITIES="performance" UI_PORT=6771 ./mockarty-runner

# Runner 3 — оба типа
RUNNER_NAME="runner-all-1" CAPABILITIES="api_test,performance" UI_PORT=6772 ./mockarty-runner

Примечание: При запуске нескольких runner на одном хосте назначьте разные значения
UI_PORT, чтобы избежать конфликтов портов.

Dashboard

Каждый runner предоставляет dashboard, показывающий статус задач, историю выполнения
и использование ресурсов:

http://runner-1:6770/

Пример Docker

docker run -d \
  --name mockarty-runner \
  -e COORDINATOR_ADDR="admin-host:5773" \
  -e API_TOKEN="mki_your_runner_token" \
  -e RUNNER_NAME="runner-docker" \
  -e SHARED="true" \
  -e CAPABILITIES="api_test,performance" \
  -e MAX_CONCURRENT_TASKS="10" \
  -p 6770:6770 \
  mockarty/runner:latest

Server Generator и API-First подход

Что такое Server Generator?

mockarty-server-generator — это автономный бинарный файл, который генерирует полностью
функциональные серверы протоколов из API-спецификаций. Сгенерированные серверы отдают
ответы моков из вашего экземпляра Mockarty, обеспечивая рабочий процесс разработки
API-first.

Рабочий процесс API-First

Подход API-first позволяет определить контракт API до написания кода реализации:

1. Определите спецификацию API (OpenAPI, .proto, GraphQL schema и др.)
2. Сгенерируйте автономный сервер из спецификации с помощью mockarty-server-generator
3. Ответы моков автоматически создаются в Mockarty на основе спецификации
4. Разрабатывайте клиентское приложение, работая с сгенерированным сервером
5. Замените сгенерированный сервер реальной реализацией, когда она будет готова

Этот подход позволяет frontend- и backend-командам работать параллельно — frontend-команда
разрабатывает приложение, работая с сгенерированным сервером моков, пока backend-команда
реализует настоящий сервис.

Требования к лицензии

Генерация серверов требует функцию mock в лицензии Mockarty.
Проверьте статус лицензии в Settings > License.

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

Три режима работы

1. Режим CLI

Генерация серверного кода из спецификаций в командной строке:

# Генерация OpenAPI-сервера
./mockarty-server-generator openapi \
  -input ./api/openapi.yaml \
  -output ./generated-server \
  -create-mocks \
  -mockarty-url http://localhost:5770 \
  -api-token mk_your_token

# Генерация gRPC-сервера
./mockarty-server-generator grpc \
  -input ./proto/service.proto \
  -output ./generated-grpc-server \
  -create-mocks \
  -mockarty-url http://localhost:5770 \
  -api-token mk_your_token

Примечание: Название протокола (например, openapi, grpc, mcp, graphql, soap, kafka, rabbitmq, sse, socket) — это позиционная подкоманда, а не флаг.

Флаг -create-mocks автоматически создаёт определения моков в Mockarty на основе спецификации.

2. Режим Orchestrator

Запуск Server Generator как REST API сервиса для программного управления сгенерированными серверами:

./mockarty-server-generator orchestrator \
  -port 8888 \
  -api-token mk_your_token \
  -mockarty-url http://localhost:5770

Orchestrator предоставляет endpoint для создания, просмотра и управления сгенерированными
серверами. Для аутентификации требуется API-токен.

3. Экспериментальный UI

Веб-интерфейс для интерактивной генерации серверов:

./mockarty-server-generator experimental-ui \
  -port 8888 \
  -api-token mk_your_token \
  -mockarty-url http://localhost:5770

Доступ к UI по адресу http://localhost:8888/ui.

Результат генерации

Генератор создаёт автономный Go-проект с vendored зависимостями:

generated-server/
  main.go
  go.mod
  go.sum
  vendor/
    ...

Сборка и запуск сгенерированного сервера:

cd generated-server
go build -mod=vendor -o server .
./server

Сгенерированный сервер полностью самодостаточен — загрузка внешних зависимостей при сборке
не требуется.

Переменные окружения сгенерированного сервера

Smart Merge

При повторном запуске генератора с -create-mocks для существующего набора моков
генератор выполняет умное слияние:

• Новые endpoint добавляются как новые моки
• Существующие моки обновляются (маршруты, методы) без потери вручную добавленных условий,
  ссылок на store или пользовательских модификаций ответов
• Удалённые endpoint не удаляются автоматически (требуется ручная очистка)

Это позволяет итеративно дорабатывать спецификацию API без потери ручных настроек моков.

Пример Docker (Orchestrator)

docker run -d \
  --name mockarty-server-generator \
  -e API_TOKEN="mk_your_token" \
  -e MOCKARTY_URL="http://admin-host:5770" \
  -p 8888:8888 \
  mockarty/server-generator:latest \
  orchestrator -port 8888

Подробное описание всех типов серверов, форматов ввода и параметров конфигурации
см. в Руководстве по Server Generator.

MCP-сервер (Model Context Protocol)

Что такое MCP-сервер?

Mockarty предоставляет встроенный MCP-сервер (Model Context Protocol), который позволяет AI-агентам, таким как Claude Desktop, Cursor, Windsurf и другим MCP-совместимым инструментам, взаимодействовать с вашим экземпляром Mockarty напрямую. AI-агент может создавать моки, запрашивать хранилища, запускать тесты и управлять ресурсами на естественном языке.

Endpoint MCP

MCP-сервер доступен по адресу:

http://localhost:5772/mcp

Порт настраивается через переменную окружения MCP_PORT (по умолчанию: 5772).

Аутентификация

Endpoint MCP требует API-токен для аутентификации. Используйте пользовательский API-токен (формат mk_*), созданный в Settings > API Tokens.

Аутентификация передаётся через HTTP-заголовки:

X-API-Key: mk_your_token_here

или:

Authorization: Bearer mk_your_token_here

Пространство имён по умолчанию

У пользователя может быть доступ к нескольким пространствам имён. По
умолчанию каждый MCP-вызов должен передавать аргумент namespace, что
неудобно. Чтобы задать default per-client, используйте опциональный
заголовок:

X-Mockarty-Namespace: your-namespace

Порядок выбора пространства имён (от наибольшего приоритета):

1. Аргумент namespace в вызове инструмента (когда LLM передаёт его
   явно).
2. Заголовок X-Mockarty-Namespace (этот раздел — задаётся один раз в
   конфиге клиента, применяется ко всем вызовам).
3. Привязанное к API-токену пространство имён, если токен выпущен
   namespace-scoped (CI/CD режим).
4. Первое не-sandbox членство пользователя как финальный fallback.

Пространство имён из заголовка проходит ту же проверку членства, что и
namespace из аргументов — запрос к namespace, к которому у пользователя
нет доступа, отклоняется с permission denied: user does not have access to namespace …. Только привязанный к токену namespace (пункт 3) даёт
жёсткий override, чтобы CI/CD-токены не могли вырваться из своей зоны.

Подключение Claude Desktop

Добавьте следующее в файл конфигурации Claude Desktop (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "mockarty": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:5772/mcp",
        "--header",
        "X-API-Key: mk_your_token_here"
      ]
    }
  }
}

Замените mk_your_token_here на ваш реальный API-токен и измените URL, если ваш экземпляр Mockarty находится на другом хосте или порту.

Подключение Cursor

Cursor имеет встроенную поддержку MCP. Добавьте Mockarty как MCP-сервер в настройках Cursor:

1. Откройте Cursor Settings → Features → MCP Servers
2. Нажмите + Add new MCP server
3. Выберите Type: sse (для Streamable HTTP)
4. Заполните:
   • Name: mockarty
   • Server URL: http://localhost:5772/mcp
5. Нажмите Save

Поскольку Cursor автоматически передаёт заголовки, вы также можете настроить его через файл .cursor/mcp.json на уровне проекта:

{
  "mcpServers": {
    "mockarty": {
      "url": "http://localhost:5772/mcp",
      "headers": {
        "X-API-Key": "mk_your_token_here"
      }
    }
  }
}

Совет: Разместите .cursor/mcp.json в корне проекта для конфигурации на уровне проекта или используйте ~/.cursor/mcp.json для глобальной конфигурации.

Подключение Claude Code (CLI)

Claude Code нативно поддерживает MCP-серверы. Добавьте Mockarty в конфигурацию проекта или глобальную конфигурацию:

На уровне проекта (.claude/settings.json в корне проекта):

{
  "mcpServers": {
    "mockarty": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:5772/mcp",
        "--header",
        "X-API-Key: mk_your_token_here"
      ]
    }
  }
}

Глобальная (~/.claude/settings.json):

{
  "mcpServers": {
    "mockarty": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:5772/mcp",
        "--header",
        "X-API-Key: mk_your_token_here"
      ]
    }
  }
}

После добавления перезапустите Claude Code и проверьте командой /mcp, чтобы увидеть подключённые серверы.

Подключение Windsurf

В Windsurf перейдите в Settings → Cascade → MCP Servers и добавьте:

{
  "mcpServers": {
    "mockarty": {
      "serverUrl": "http://localhost:5772/mcp",
      "headers": {
        "X-API-Key": "mk_your_token_here"
      }
    }
  }
}

Подключение других MCP-клиентов

Любой MCP-совместимый клиент может подключиться, используя:

Доступные инструменты MCP

После подключения AI-агент получает доступ к инструментам для:

• Управление моками — Просмотр, создание, обновление и удаление моков по пространствам имён
• Операции с хранилищами — Чтение и запись значений Global Store, Chain Store
• Управление шаблонами — Просмотр, загрузка и применение шаблонов моков
• API-тестирование — Просмотр коллекций, запуск наборов тестов, просмотр результатов
• Фаззинг безопасности — Запуск/остановка сессий фаззинга, просмотр находок, сортировка уязвимостей
• Нагрузочное тестирование — Запуск нагрузочных тестов, генерация скриптов k6, сравнение результатов
• Запись трафика — Запуск/остановка сессий записи, просмотр перехваченных запросов
• Генерация кода — Генерация моков из спецификаций OpenAPI/Swagger
• HTTP-запросы — Выполнение произвольных HTTP-вызовов для тестирования endpoint или получения спецификаций
• Утилиты — Конвертация XML в JSON, кодирование Base64, валидация шаблонов

Создание API-токена для MCP

1. Перейдите в Settings > API Tokens в интерфейсе Mockarty.
2. Нажмите Create Token.
3. Введите имя (например, claude-desktop-mcp).
4. Скопируйте сгенерированный токен (начинается с mk_).
5. Используйте этот токен в конфигурации MCP-клиента.

Безопасность: API-токены наследуют права пользователя, который их создал. Для доступа через MCP убедитесь, что владелец токена имеет соответствующие роли в пространствах имён.

Частые ошибки

• Использование токена интеграции (mki_*) для MCP. MCP требует пользовательский API-токен (mk_*). Токены интеграции предназначены только для нод resolver/runner.
• Забыли перезапустить MCP-клиент после изменения файла конфигурации. Claude Desktop, Cursor и Windsurf требуют перезапуска для применения изменений.
• Неверный URL. Если MCP_PORT не задан, MCP-сервер работает на порту 5772 по умолчанию. MCP всегда работает на отдельном выделенном порту, отдельно от основного HTTP-сервера.
• Файрвол блокирует порт. Убедитесь, что порт 5772 (или ваш настроенный порт MCP) доступен с машины, на которой запущен AI-инструмент.

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

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

Для CI/CD пайплайнов используйте пользовательские API-токены (mk_*),
а не токены интеграции. Создайте API-токен в Settings > API Tokens или через
административный API.

Создание моков в CI

Автоматизируйте создание моков как часть CI-пайплайна:

# Создание мока для endpoint пользователей
curl -X POST http://mockarty:5770/api/v1/mocks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mk_your_ci_token" \
  -d '{
    "id": "ci-users-get",
    "http": {
      "route": "/api/users/list",
      "httpMethod": "GET"
    },
    "response": {
      "statusCode": 200,
      "payload": {
        "id": "$.fake.UUID",
        "name": "$.fake.FirstName",
        "email": "$.fake.Email"
      }
    }
  }'

Запуск коллекций тестов

Выполнение тестов запускается через систему Runner Agent (см. Runner Agent) или веб-интерфейс (страница API Tester). Прямого REST-эндпоинта для запуска коллекций тестов не существует — координатор автоматически отправляет задачи подключённым runner agent при инициации запуска тестов из UI.

Нагрузочные тесты через API

Запуск нагрузочных тестов:

curl -X POST http://mockarty:5770/api/v1/perf/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mk_your_ci_token" \
  -d '{
    "script": {
      "collectionId": "your-collection-uuid",
      "environmentId": "your-env-uuid"
    },
    "options": {
      "duration": "60s",
      "concurrency": 10
    }
  }'

Импорт OpenAPI-спецификаций

Автоматическая генерация моков из OpenAPI-спецификаций в CI-пайплайне:

curl -X POST http://mockarty:5770/api/v1/api-tester/import/openapi \
  -H "Authorization: Bearer mk_your_ci_token" \
  -F "file=@./api/openapi.yaml" \
  -F "namespace=ci-tests"

Пример GitHub Actions

name: Интеграционные тесты с Mockarty

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      mockarty:
        image: mockarty/mockarty:latest
        ports:
          - 5770:5770
        env:
          DB_DSN: "postgres://..."

    steps:
      - uses: actions/checkout@v4

      - name: Ожидание Mockarty
        run: |
          for i in $(seq 1 30); do
            curl -s http://localhost:5770/health && break
            sleep 2
          done

      - name: Импорт OpenAPI-спецификации
        run: |
          curl -X POST http://localhost:5770/api/v1/api-tester/import/openapi \
            -H "Authorization: Bearer ${{ secrets.MOCKARTY_TOKEN }}" \
            -F "file=@./api/openapi.yaml"

      - name: Запуск тестов
        run: npm test
        env:
          API_BASE_URL: http://localhost:5770

Webhook-уведомления

Настройка

Подписки на событийные webhook хранятся в таблице webhook_subscriptions базы данных. Каждая подписка связывает пользователя с URL и набором типов событий. Webhook уровня namespace (срабатывающие при создании/обновлении/удалении моков) настраиваются отдельно в Settings > Webhooks в административном интерфейсе.

Каждая подписка на событийный webhook требует:

• URL: Endpoint для получения уведомлений
• Event Types: Какие события вызывают webhook (например, test.run.completed, fuzzing.finding.new)
• Secret (опционально): Используется для подписи payload с помощью HMAC-SHA256 для верификации

Типы событий

Формат Payload

Payload webhook в формате JSON:

{
  "id": "event-uuid",
  "type": "test.run.completed",
  "userId": "user-uuid",
  "namespace": "production",
  "payload": { ... },
  "createdAt": "2026-03-13T10:30:00Z"
}

Поле payload содержит данные, специфичные для события (результаты тестов, аномалии фаззинга и т.д.).

Если настроен secret для webhook, payload подписывается с помощью HMAC-SHA256, и подпись
включается в заголовок X-Mockarty-Signature. Также отправляется заголовок X-Mockarty-Timestamp.

Поведение доставки

Доставка webhook выполняется в режиме fire-and-forget с таймаутом 10 секунд на запрос. Одновременно может доставляться до 10 webhook. При достижении лимита параллельности дополнительные доставки пропускаются для текущего цикла событий.

Примечание: Автоматического повтора для неудачных доставок webhook в настоящее время нет. Если целевой URL недоступен или возвращает ошибку, доставка логируется, но не повторяется. Убедитесь, что ваш приёмник webhook высокодоступен.

Сценарии использования

• Уведомления в Slack: Отправка сообщения в канал Slack при провале тестов (test.run.completed)
• Ворота CI/CD: Блокировка деплоев при обнаружении уязвимостей фаззингом (fuzzing.finding.new)
• Мониторинг агентов: Отслеживание прогресса и ошибок задач агентов (agent.task.*)
• Журнал аудита: Пересылка всех событий в сервис логирования для compliance
• Обновление dashboard: Запуск обновления dashboard при системных оповещениях (system.alert)

Телеметрия и мониторинг

Интеграция с OpenTelemetry

Mockarty поддерживает OpenTelemetry для распределённой трассировки. Телеметрия настраивается через страницу Панель администратора > Телеметрия в веб-интерфейсе, а не через переменные окружения. Администратор может включать/выключать трассировку, настраивать endpoint экспортёра и частоту сэмплирования из UI.

Метрики Prometheus

Все компоненты Mockarty предоставляют метрики Prometheus по адресу /metrics:

# Административная нода
curl http://admin:5770/metrics

# Нода resolver
curl http://resolver:5780/metrics

Ключевые метрики:

• mockarty_http_requests_total — Количество HTTP-запросов по методу, endpoint, коду статуса
• mockarty_http_request_duration_seconds — Гистограмма длительности HTTP-запросов
• mockarty_mock_requests_total — Количество запросов моков по ID мока, namespace, протоколу
• mockarty_mocks_total — Общее количество моков по namespace, протоколу, состоянию жизненного цикла
• mockarty_db_query_duration_seconds — Длительность запросов к базе данных по операции и таблице
• mockarty_cache_hits_total / mockarty_cache_misses_total — Счётчики попаданий/промахов кеша
• mockarty_errors_total — Количество ошибок по типу и компоненту
• mockarty_users_total — Общее количество зарегистрированных пользователей
• mockarty_active_sessions — Активные пользовательские сессии
• mockarty_db_connections — Состояние пула подключений к базе данных
• mockarty_rate_limit_hits_total — Отклонения по лимиту запросов

Endpoint здоровья

Все компоненты предоставляют endpoint здоровья для мониторинга и настройки балансировщика
нагрузки:

Ответ health check:

{
  "status": "pass",
  "releaseId": "1.2.3",
  "uptime": "72h15m30s"
}

Интеграция с Grafana

Вы можете создавать пользовательские дашборды Grafana, используя метрики Prometheus, перечисленные выше. Добавьте Mockarty как источник данных Prometheus в Grafana и создайте панели для нужных метрик. Все метрики из раздела Метрики Prometheus доступны для построения дашбордов.

Архитектурные диаграммы

Базовая конфигурация (одна нода)

┌──────────────┐         ┌──────────────────┐
│ Ваше прило-  │──HTTP──▶│  Mockarty Admin   │
│ жение/тесты  │         │     :5770         │
└──────────────┘         │                   │
                         │  - Обслуживание   │
                         │    моков          │
                         │  - Админ UI       │
                         │  - API            │
                         │  - Запуск тестов  │
                         └──────────────────┘

Распределённая конфигурация (рекомендуется для продакшена)

                         ┌──────────────┐
                    ┌───▶│  Resolver 1  │
                    │    │    :5780     │
┌──────────────┐    │    └──────┬───────┘
│ Ваше прило-  │────┤           │ gRPC :5773
│ жение/тесты  │    │    ┌──────▼───────────────┐
└──────────────┘    │    │   Mockarty Admin     │
                    │    │      :5770           │
                    └───▶│                      │
                         │  - Админ UI          │
                  ┌──────│  - Координатор       │
                  │      │  - Конфигурация      │
                  │      └──────────────────────┘
                  │ gRPC :5773
                  │
           ┌──────▼───────┐
           │  Runner Agent │
           │    :6770      │
           │               │
           │  - API-тесты  │
           │  - Нагрузочные│
           │    тесты      │
           └───────────────┘

Полная архитектура с Server Generator

┌─────────────────────────────────────────────────────────────────────┐
│                     Среда разработки                                │
│                                                                     │
│  ┌────────────┐    ┌─────────────┐    ┌────────────────────────┐   │
│  │ Специфика- │───▶│  Server     │───▶│  Сгенерированный       │   │
│  │ ция API    │    │  Generator  │    │  сервер :8080          │   │
│  └────────────┘    └──────┬──────┘    │                        │   │
│                           │           │  Отдаёт ответы моков   │   │
│                    создаёт моки       │  из Mockarty           │   │
│                           │           └───────────┬────────────┘   │
│                           ▼                       │                 │
│                    ┌──────────────┐                │                 │
│  ┌──────────┐     │  Mockarty    │◀───────────────┘                 │
│  │ Frontend │────▶│  Admin       │     запрашивает данные моков     │
│  │   App    │     │  :5770       │                                   │
│  └──────────┘     └──────┬───────┘                                  │
│                          │                                          │
│                   ┌──────┴───────┐                                  │
│                   │              │                                   │
│            ┌──────▼──────┐ ┌────▼────────┐                         │
│            │  Resolver   │ │  Runner     │                          │
│            │  :5780      │ │  Agent      │                          │
│            └─────────────┘ └─────────────┘                         │
└─────────────────────────────────────────────────────────────────────┘

Справочник портов

Управление интеграциями в Kubernetes

В Kubernetes-средах CLI и Admin API Mockarty поддерживают динамическое управление интеграциями кластера – добавление, удаление и настройку нод resolver и runner-агентов без редактирования значений Helm или сырых манифестов.

Динамические команды управления интеграциями

# Добавить новую ноду resolver в кластер
mockarty-cli cluster add-resolver --namespace production --replicas 2

# Добавить нового runner-агента
mockarty-cli cluster add-runner --namespace staging --replicas 1

# Удалить интеграцию (resolver или runner) по имени
mockarty-cli cluster remove-integration --name resolver-production-3

# Показать все активные интеграции
mockarty-cli cluster status --integrations

Эти команды обновляют CR MockartyCluster, а оператор автоматически приводит изменения в соответствие с ресурсами Kubernetes.

Интеграции на уровне пространства имён и на уровне администратора

Интеграции на уровне пространства имён полезны в мультитенантных средах, где каждая команда управляет своими резолверами. Интеграции на уровне администратора предназначены для общей инфраструктуры.

Квоты ресурсов

Для предотвращения исчерпания ресурсов в общих кластерах настройте лимиты для каждого пространства имён:

Когда пространство имён превышает свою квоту, CLI и API возвращают ошибку, а оператор отклоняет обновление CR. Квоты применяются на уровне оператора, а не через Kubernetes ResourceQuotas.

Матрица RBAC для Kubernetes-операций

Роли RBAC управляются через авторизацию Admin Node на основе Casbin. Сам оператор использует выделенный ServiceAccount с минимально необходимыми разрешениями Kubernetes RBAC.

Подробнее о конфигурации CRD, автомасштабировании HPA и сетевых политиках см. руководство Архитектура масштабирования. Для первоначальной настройки кластера и установки через Helm см. Руководство по развёртыванию.

Смотрите также

• Установка и развёртывание — Примеры Docker Compose, переменные окружения и настройка TLS
• Руководство по генератору кода — Подробное руководство по CLI генератора серверов для всех поддерживаемых протоколов и брокеров
• Руководство администратора — Управление пользователями, пространствами имен, аутентификация и безопасность
• Справочник API — Полная документация REST API
• Быстрый старт — Начните работу за 20 минут
• Контрактное тестирование — Валидация моков по спецификациям API и обнаружение breaking changes
• Хаос-тестирование — Внедрение сбоев, задержек и ошибок для проверки устойчивости системы