mcp-validator

v0.7.7

Published

9 days ago

MCP Validator - инструмент для валидации кода, тестов и архитектуры через AI

Downloads

933

0High
0Medium
0Low

cyberwalrus

mcp validator ai code-quality testing

MCP Validator

📋 Оглавление

Общая информация

Версия: 0.5.11

MCP Validator — инструмент для валидации кода, тестов, архитектуры и промптов через AI с использованием Model Context Protocol (MCP).

Архитектура: Проект построен на архитектуре layered_library с четким разделением слоев (server, tools, agents, services, model, lib). Детальная структура описана в architecture.xml.

✨ Возможности

✅ Валидация кода — проверка TypeScript, JavaScript, Go, Python, Rust и других языков
🧪 Валидация тестов — анализ качества и полноты тестового покрытия
🏗️ Валидация архитектуры — проверка архитектурных решений
🔒 Проверка безопасности — поиск уязвимостей в коде
⚡ Анализ производительности — рекомендации по оптимизации
📝 Валидация документации — проверка качества и полноты документации
🎯 Валидация промптов — проверка качества AI промптов
📋 Валидация задач — анализ требований и спецификаций
🤖 Тестирование промптов — параллельное тестирование на консистентность (3-10 итераций)

Поддерживаемые языки: TypeScript, JavaScript, Go, Python, Rust, Java, C#, PHP, Ruby, Swift, Kotlin

Требования

Node.js >= 16.0.0 (поддержка Node.js 16+ добавлена в версии 0.5.9)
API ключ OpenRouter (получить бесплатно)

Примечание: Для совместимости с Node.js 16+ используется undici вместо встроенного fetch. Переменные окружения загружаются через dotenv.

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

1. Получите API ключ OpenRouter:

Перейдите на OpenRouter
Создайте новый API ключ

2. Настройте Cursor IDE:

Добавьте конфигурацию в ~/.cursor/mcp.json

{
    "mcpServers": {
        ... // другие MCP серверы
        "mcp-validator": {
            "command": "npx",
            "args": ["-y", "mcp-validator"],
            "env": {
                "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE"
            }
        }
    }
}

Замените YOUR_OPENROUTER_API_KEY_HERE на ваш API ключ OpenRouter
Перезапустите Cursor IDE

3. Первая валидация:

Попросите AI ассистента в Cursor выполнить валидацию кода через mcp-validator
Если всё настроено правильно, будет автоматически вызван инструмент MCP, который проанализирует файл и вернёт подробный отчёт

🔑 Получение API ключа

Перейдите на OpenRouter
Зарегистрируйтесь или войдите в аккаунт
Перейдите в раздел Keys
Создайте новый API ключ
Скопируйте ключ для использования в конфигурации

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

Настройка MCP сервера

Добавьте в конфигурацию MCP (~/.cursor/mcp.json):

Расширенная конфигурация

Для полной настройки с дополнительными параметрами:

{
    "mcpServers": {
        "mcp-validator": {
            "command": "npx",
            "args": ["-y", "mcp-validator"],
            "env": {
                "API_KEY": "sk-or-v1-xxxxxxxxxxxxxx",
                "API_URL": "https://openrouter.ai/api/v1",
                "API_PROVIDERS": "Cerebras",
                "LOG_LEVEL": "DEBUG",
                "AI_MODEL": "openai/gpt-oss-20b:free",
                "AI_MAX_TOKENS": "50000",
                "AI_TEMPERATURE": "0.7",
                "TIMEOUT_API_REQUEST": "30000",
                "TIMEOUT_VALIDATION": "60000",
                "PROMPTS_PATH": "./custom-prompts"
            }
        }
    }
}

Проверка подключения

После настройки mcp.json:

Перезапустите Cursor IDE для загрузки новой конфигурации
Проверьте статус в панели MCP (обычно в нижней части IDE)
Используйте инструменты через команды Cursor или автодополнение

Устранение проблем подключения

Если MCP сервер не подключается:

# Проверьте, что пакет установлен
npx mcp-validator --version

# Проверьте конфигурацию
cat ~/.cursor/mcp.json | jq '.mcpServers["mcp-validator"]'

# Проверьте логи в Cursor
# Откройте Developer Tools (Cmd+Option+I) и посмотрите консоль

Cursor Rules

Готовые правила и воркфлоу для Cursor IDE доступны в отдельном репозитории:

👉 CyberWalrus/cursor-rules

Репозиторий включает:

Правила воркфлоу (code, prompt, ai-docs, critique)
Шаблоны архитектур (FSD, Layered Library и др.)
Стандарты кодирования и документации
Git workflow команды

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

🔑 Обязательные

| Переменная | Описание | Пример | | -------------------- | ----------------------- | ------------------------- | | OPENROUTER_API_KEY | API ключ для OpenRouter | sk-or-v1-xxxxxxxxxxxxxx |

⚙️ Основные настройки

| Переменная | Описание | По умолчанию | Возможные значения | | -------------- | -------------------------------- | ------------- | ----------------------------------- | | NODE_ENV | Среда выполнения | development | development, production, test | | LOG_LEVEL | Уровень логирования | INFO | DEBUG, INFO, WARN, ERROR | | PROMPTS_PATH | Путь к пользовательским промптам | prompts | Любой путь к папке |

🤖 Настройки AI модели

| Переменная | Описание | По умолчанию | Диапазон | | ---------------- | ------------------------------- | ------------------------- | ------------------------------------------- | | AI_MODEL | Модель AI для валидации | openai/gpt-oss-20b:free | Любая модель OpenAI-совместимого провайдера | | AI_MAX_TOKENS | Максимальное количество токенов | 100000 | 1-1000000 | | AI_TEMPERATURE | Температура генерации | 0.5 | 0.0-2.0 |

🌐 Настройки API

| Переменная | Описание | По умолчанию | Пример значения | | --------------- | ------------------------------------------- | ------------------------------ | ----------------------------- | | API_KEY | API ключ для OpenAI-совместимого провайдера | sk-or-v1-xxx | Любой валидный ключ | | API_URL | URL OpenAI-совместимого API | https://openrouter.ai/api/v1 | Любой валидный URL | | API_PROVIDERS | Список провайдеров OpenRouter через запятую | - | Cerebras, Cerebras,OpenAI |

Поддерживаемые провайдеры:

OpenRouter (по умолчанию): https://openrouter.ai/api/v1
- API_PROVIDERS: позволяет явно указать провайдера(ов) OpenRouter (Cerebras, OpenAI, Qwen, Meta)
- Если не указано - OpenRouter выберет провайдера автоматически
OpenAI: https://api.openai.com/v1
Anthropic Claude: https://api.anthropic.com/v1
Другие OpenAI-совместимые API

⏱️ Настройки таймаутов

| Переменная | Описание | По умолчанию | Единицы | | --------------------- | ------------------------------ | ------------ | ------------ | | TIMEOUT_API_REQUEST | Таймаут для API запросов | 30000 | миллисекунды | | TIMEOUT_VALIDATION | Таймаут для процесса валидации | 30000 | миллисекунды |

🔧 Настройки MCP сервера

| Переменная | Описание | По умолчанию | | ------------------------ | -------------------- | -------------------------------- | | MCP_SERVER_NAME | Имя MCP сервера | mcp-validator | | MCP_SERVER_DESCRIPTION | Описание сервера | Production-ready MCP validator | | MCP_PROTOCOL_VERSION | Версия MCP протокола | 2024-11-05 | | MCP_SERVER_VERSION | Версия сервера | Из package.json |

🧪 Настройки для разработки

| Переменная | Описание | По умолчанию | Значения | | -------------- | --------------------------- | ------------ | --------------- | | MCP_E2E_TEST | Флаг E2E тестирования | false | true, false | | NODE_PATH | Путь для разрешения модулей | "" | Путь к папке |

🚀 Расширенные настройки

| Переменная | Описание | По умолчанию | Единицы | | ----------------------- | ------------------------------ | ------------ | ------------ | | MAX_PARALLEL_REQUESTS | Максимум параллельных запросов | 5 | количество | | HEARTBEAT_INTERVAL | Интервал heartbeat | 30000 | миллисекунды | | REQUEST_BUFFER_SIZE | Размер буфера запросов | 1048576 | байты (1MB) |

🔧 Скрытые/внутренние переменные

Эти переменные используются внутренне системой и обычно не требуют настройки:

| Переменная | Описание | По умолчанию | Назначение | | ----------------------------- | ----------------------------- | ----------------------------------------- | ---------------- | | OPENROUTER_MOCK_CLIENT_PATH | Путь к мок клиенту для тестов | end-to-end/mocks/openrouter-test-client | E2E тестирование |

Инструменты MCP

После успешного подключения MCP сервера в Cursor IDE будут доступны следующие инструменты:

💡 Как использовать: В Cursor IDE инструменты MCP доступны через:
Автодополнение — начните печатать название инструмента
Команды — используйте @ для вызова инструментов
Контекстное меню — правый клик на файле/коде

1️⃣ validate — Универсальная валидация

Валидация кода:

{
  "validationType": "code",
  "input": {
    "type": "content",
    "data": "export function test() { return 42; }"
  },
  "language": "typescript"
}

Валидация тестов:

{
  "validationType": "tests",
  "input": {
    "type": "file",
    "data": "/path/to/test.spec.ts"
  },
  "language": "typescript"
}

Кастомная валидация:

{
  "validationType": "custom",
  "input": {
    "type": "content",
    "data": "Your content here"
  },
  "customPrompt": "Check if this code follows our team conventions",
  "language": "typescript"
}

2️⃣ test-prompt — Тестирование промптов на консистентность

{
  "prompt": "Напиши функцию сортировки массива",
  "iterations": 5,
  "context": "Тест консистентности ответов",
  "timeout": 30000
}

Результат покажет:

Консистентность ответов (score 0-100)
Аномалии во времени выполнения
Повторяющиеся паттерны в ответах
Детальный отчет по каждой итерации

3️⃣ verify-info — Проверка информации

{
  "input": {
    "type": "content",
    "data": "TypeScript был создан Microsoft в 2012 году"
  },
  "context": "Проверка исторических фактов"
}

Проверяет достоверность информации через 3 параллельные AI проверки с комбинированным отчётом.

4️⃣ validate-interactive — Интерактивная валидация

{
  "filePath": "/path/to/file.ts",
  "language": "typescript"
}

Запускает интерактивный режим с выбором типа валидации через elicitation (диалоговое окно в IDE).

Промпты MCP

MCP Validator предоставляет 5 готовых промптов для быстрого запуска валидации:

| Промпт | Описание | Аргументы | | --- | --- | --- | | validate-code | Валидация кода | filePath, focus (quality/security/performance/all) | | validate-tests | Валидация тестов | filePath | | validate-architecture | Валидация архитектуры | filePath | | test-consistency | Тест консистентности промпта | prompt, iterations (3-10) | | verify-facts | Проверка фактов | text |

Использование в Cursor:

/validate-code filePath=/src/utils.ts focus=quality

Ресурсы MCP

MCP Validator предоставляет 4 ресурса для получения информации:

| URI | Описание | MIME-тип | | --- | --- | --- | | validator://config | Текущая конфигурация валидатора | application/json | | validator://prompts/{type} | Промпт для указанного типа валидации | text/markdown | | validator://languages | Список поддерживаемых языков | application/json | | validator://help | Справка по инструментам | text/markdown |

Пример чтения ресурса:

// Получить конфигурацию
const config = await client.readResource("validator://config");

// Получить промпт валидации кода
const prompt = await client.readResource("validator://prompts/code");

HTTP режим

MCP Validator поддерживает Streamable HTTP транспорт для интеграции с веб-приложениями.

Настройка HTTP режима:

{
    "mcpServers": {
        "mcp-validator": {
            "command": "npx",
            "args": ["-y", "mcp-validator"],
            "env": {
                "OPENROUTER_API_KEY": "sk-or-v1-xxx",
                "MCP_TRANSPORT": "http",
                "MCP_HTTP_PORT": "8080",
                "MCP_HTTP_HOST": "0.0.0.0"
            }
        }
    }
}

Эндпоинты:

| Метод | Путь | Описание | | --- | --- | --- | | POST | /mcp | JSON-RPC запросы к MCP серверу | | GET | /mcp | SSE стрим для событий | | DELETE | /mcp | Закрытие сессии | | GET | /health | Проверка состояния сервера |

Пример запроса:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Интерактивная валидация

Инструмент validate-interactive использует MCP elicitation для интерактивного выбора типа валидации.

Как это работает:

Вызовите инструмент с путём к файлу
IDE покажет диалоговое окно с выбором типа валидации
Выберите нужный тип (code, tests, architecture, prompts, documentation)
Валидация запустится автоматически

Преимущества:

Не нужно запоминать типы валидации
Быстрый выбор через UI
Поддержка отмены операции

Пример использования:

{
  "filePath": "/src/components/Button.tsx",
  "context": "Проверка компонента перед коммитом"
}

Если тип валидации указан явно (validationType), диалоговое окно не появится.

CLI режим

# Показать справку
mcp-validator --help

# Показать версию
mcp-validator --version

Локальный запуск

Установка

npm install mcp-validator
# или
yarn add mcp-validator

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

Создайте файл .env в корне проекта:

# Обязательные настройки
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxx

# Основные настройки
NODE_ENV=production
LOG_LEVEL=INFO
PROMPTS_PATH=./custom-prompts

# Настройки AI
DEFAULT_AI_MODEL=openai/gpt-4o-mini
AI_MAX_TOKENS=50000
AI_TEMPERATURE=0.7

# Таймауты
VALIDATION_TIMEOUT=60000
PARALLEL_TEST_TIMEOUT=180000

# MCP сервер
MCP_SERVER_NAME=my-validator
MCP_SERVER_DESCRIPTION="Custom MCP validator for my project"

Запуск MCP сервера

# Запуск через npx (рекомендуется)
npx mcp-validator

# Или установка глобально
npm install -g mcp-validator
mcp-validator

# Локальная разработка
yarn start

Технологический стек

TypeScript 5.9.3 — строгая типизация всей кодовой базы
Node.js 16+ — поддержка через undici (HTTP клиент) и dotenv (переменные окружения)
@modelcontextprotocol/sdk 1.20.0 — официальный MCP SDK для интеграции с Cursor
OpenAI SDK 6.3.0 — упрощенная агентная архитектура
undici 5.28.4 — HTTP клиент для совместимости с Node.js 16+ (заменяет встроенный fetch)
dotenv 17.2.3 — загрузка переменных окружения из .env файла
zod 4.1.12 — runtime валидация схем с TypeScript типами

Дополнительные ресурсы

Model Context Protocol
OpenRouter Documentation
Cursor IDE
Cursor Rules — готовые правила и воркфлоу для Cursor IDE
CHANGELOG — история изменений