qualien-mcp

Композитный MCP-шлюз — он агрегирует несколько серверов Model Context Protocol за одним подключением, специально подобранных для рабочих процессов SDET / QE. Добавьте один сервер к вашему ИИ-ассистенту вместо пяти.

npx qualien-mcp

Из коробки он предоставляет стартовую QE-пару — Playwright MCP (автоматизация браузера, DOM, скриншоты) и Filesystem MCP (чтение/редактирование файлов проекта, объекты страниц, тестовые утилиты) — без настройки. Инструменты предоставляются вашему ассистенту с пространствами имён вида playwright__… и filesystem__….

Зачем нужен шлюз?

Ваш ассистент уже умеет подключаться ко многим MCP-серверам напрямую — поэтому шлюз оправдывает своё место, делая то, что не под силу куче серверов:

• Единая точка входа — для добавления в любой клиент (Claude Code, Claude Desktop, Cursor, …).

• Курирование — включение/отключение для каждого сервера и каждого инструмента. Меньше инструментов, но с лучшими именами = лучший выбор инструмента моделью (вываливание на неё 200 инструментов делает её хуже).

• Единая поверхность маршрутизации/логирования — каждый вызов логируется в stderr с указанием нижестоящего сервера, инструмента и задержки.

• Чистый жизненный цикл — запускает каждый нижестоящий сервер как дочерний процесс и завершает их все при выходе (без осиротевших процессов браузера).

• Ориентированность на QE — авторский SDET-инструментарий, а не универсальный прокси.

Использование с вашим ассистентом

Claude Code (.mcp.json или пользовательские настройки):

{
  "mcpServers": {
    "qualien": { "command": "npx", "args": ["-y", "qualien-mcp"] }
  }
}

Claude Desktop (claude_desktop_config.json) — та же структура внутри mcpServers.

Эта единственная запись даёт вашему ассистенту все инструменты всех агрегированных серверов.

Добавление дополнительных серверов

Поместите qualien-mcp.config.json в рабочую директорию (или передайте --config <path>). Записи накладываются поверх встроенных значений по умолчанию — переопределите ключ, чтобы изменить его, или установите enabled: false, чтобы отключить стандартную возможность. Никаких новых релизов не требуется.

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/abs/path/to/allow"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "tools": { "deny": ["browser_close"] }
    }
  }
}

Полную структуру (command, args, env, enabled, tools.allow / tools.deny) см. в qualien-mcp.config.example.json.

Встроенный каталог

qualien-mcp поставляется с курируемым каталогом известных серверов (проверенных в npm), поэтому вы включаете нужный по ключу, указав только свои секреты — не нужно запоминать пакеты или команды:

{
  "servers": {
    "chrome-devtools": { "enabled": true },
    "postgres":  { "enabled": true, "env": { "DATABASE_URI": "postgres://…" } },
    "slack":     { "enabled": true, "env": { "SLACK_MCP_XOXP_TOKEN": "xoxp-…" } }
  }
}

Выполните npx qualien-mcp catalog, чтобы вывести их все с указанием требований каждого. Текущий каталог:

use монтирует сервер из каталога под другим ключом (например, две базы данных): { "db-prod": { "use": "postgres", "enabled": true, "env": {…} } }. Всё, чего нет в каталоге, вы по-прежнему определяете полностью (command/args или type/url).

Удалённые и OAuth-серверы (например, GitHub)

Нижестоящие серверы могут быть удалёнными (Streamable HTTP), так же как и локальными. Удалённый сервер задаётся как { "type": "http", "url": "…" }, и если ему нужен OAuth, каждый пользователь входит в свою собственную учётную запись — токены хранятся для каждого пользователя в ~/.qualien-mcp/credentials.json (0600) и никогда не объединяются и не передаются.

Хостируемый MCP GitHub — эталонный случай. Он не поддерживает динамическую регистрацию клиентов, поэтому вы один раз регистрируете собственное приложение GitHub OAuth App и передаёте qualien-mcp его Client ID:

1. GitHub → Settings → Developer settings → OAuth Apps → New. Установите callback URL на http://127.0.0.1:41999/callback. Скопируйте Client ID.

2. В qualien-mcp.config.json:

   {
     "servers": {
       "github": {
         "type": "http",
         "url": "https://api.githubcopilot.com/mcp/",
         "oauth": true,
         "clientId": "<your client id>"
       }
     }
   }

3. Авторизуйтесь (браузер откроется один раз):

   npx qualien-mcp login github

После этого шлюз подключается к GitHub в неинтерактивном режиме (обновляя токены по мере необходимости) и предоставляет инструменты github__*. Если удалённый сервер ещё не авторизован, шлюз пропускает его с подсказкой (run: npx qualien-mcp login github) и продолжает обслуживать всё остальное — он никогда не блокирует запуск. Серверам, которые поддерживают динамическую регистрацию, clientId не требуется.

Безопасно по умолчанию

qualien-mcp применяет ограничения централизованно, перед передачей вызова — поэтому они действуют независимо от того, что разрешает нижестоящий сервер, и композитные инструменты тоже не могут их обойти:

• Базы данных доступны только для чтения — вызовы postgres/mysql, содержащие записывающий/DDL SQL (INSERT/UPDATE/DELETE/DROP/…), отклоняются. Разрешается явно через { "postgres": { "readOnly": false } }.

• Корни файловой системы — { "filesystem": { "roots": ["./src", "./tests"] } } отклоняет любой вызов, чей аргумент пути выходит за пределы этих директорий.

• Деструктивные инфраструктурные инструменты блокируются — инструменты docker/kubernetes, имя которых выглядит деструктивным (delete/remove/prune/kill/…), отклоняются, если не задано { "allowDestructive": true }.

• Плюс курирование tools.deny / tools.allow для каждого сервера.

Честная оценка: они мешают LLM случайно нанести вред. Проверка SQL основана на ключевых словах (эвристика), а не на парсере — это не песочница для защиты от вредоносных действий. Для настоящей изоляции нужны собственные разрешения нижестоящего сервера или контейнер.

Композитные QE-инструменты

Помимо сквозной передачи, qualien-mcp поставляет инструменты, которые он реализует сам (пространство имён qe__) и которые оркестрируют несколько нижестоящих серверов в одном вызове — в этом главная ценность шлюза для QE.

qe__verify_api_vs_db — сквозная проверка согласованности API↔БД в одном вызове. Передайте ему два подвызова (инструменты с пространствами имён, которые можно найти через tools/list); он выполнит оба и сравнит полезные нагрузки:

{
  "api": { "tool": "openapi__getUser", "arguments": { "id": 1 } },
  "db":  { "tool": "postgres__query", "arguments": { "sql": "select id, name from users where id = 1" } },
  "match": "subset"        // every field the DB returns must match the API (default)
}
// → { "match": false, "differences": [ { "path": "name", "api": "Ann", "db": "Bob" } ], … }

Композитные инструменты появляются только при подключении требуемых нижестоящих серверов (qe__verify_api_vs_db требует сервер database). В планах — больше (repro-from-Jira, page-object-from-URL, flaky triage).

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

В одном процессе qualien-mcp является одновременно MCP-сервером для вашего ассистента и MCP-клиентом для каждого нижестоящего сервера:

assistant ⇄ qualien-mcp ⇄ playwright-mcp
                         ⇄ filesystem-mcp
                         ⇄ …

• tools/list отправляет вызовы всем нижестоящим серверам, фильтрует по вашим правилам курирования и задаёт каждому пространство имён вида <server>__<tool>.

• tools/call маршрутизирует по этому префиксу к серверу-владельцу и пробрасывает ответ насквозь.

• Ресурсы и промпты агрегируются так же, когда их предоставляет нижестоящий сервер.

• Нижестоящий сервер, который не смог запуститься, логируется и пропускается — шлюз продолжает обслуживать остальные.

• Логи отправляются в stderr (stdout — это протокол); ваш хост показывает их в своих MCP-логах.

Дорожная карта

• v0.1 — Playwright + Filesystem, пространства имён, курирование, логирование, чистый жизненный цикл ✅

• Далее — расширение на основе конфигурации (GitHub через его размещённый OAuth MCP, БД, Sequential-Thinking, Memory, Chrome DevTools), композитные QE-инструменты (например, проверка согласованности API ↔ БД в одном вызове), определение границ безопасности.

Лицензия

MIT