@visualq/mcp

MCP-сервер для VisualQ — интерфейс агента Quality OS. @visualq/mcp предоставляет 44 инструмента (профиль qa): многокомпонентный аудит, VRT/FRT (frt_get_feature), трекинг-план + JIRA-доказательство, текущее состояние здоровья. Для Cursor, Claude Desktop или любого MCP-клиента.

Настройка для продакшена (рекомендуется)

1. Войдите в https://visualq.ai

2. Перейдите в Настройки → Agent API Keys (администратор организации)

3. Создайте ключ с областью mcp_full

4. При желании установите проект по умолчанию (slug), если вы в основном работаете с одним клиентом

5. Скопируйте фрагмент конфигурации Cursor MCP

6. Вставьте в ~/.cursor/mcp.json (или в .cursor/mcp.json проекта) и перезапустите Cursor

Или одной командой:

npx @visualq/setup-agent cursor --key vq_org_live_… --project my-site

Или установите плагин для Cursor (навыки + правила в комплекте).

{
  "mcpServers": {
    "visualq": {
      "command": "npx",
      "args": ["-y", "@visualq/mcp"],
      "env": {
        "VISUALQ_API_KEY": "vq_org_live_…",
        "VISUALQ_BASE_URL": "https://visualq.ai",
        "VISUALQ_TOOL_PROFILE": "qa"
      }
    }
  }
}

Быстрый доступ к одному проекту

Если у ключа организации есть проект по умолчанию (или вы установили его только в окружении MCP):

"VISUALQ_DEFAULT_PROJECT": "afp-com"

Тогда инструменты могут опускать параметр project, если у ключа есть defaultProject на сервере или эта переменная окружения установлена в конфигурации MCP.

Организации с несколькими проектами

Передавайте project при каждом вызове инструмента (slug или id), например "project": "afp-com".

Related MCP server: Artillery MCP Server

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

Области ключей API

Ключи агентов организации поддерживают только mcp_read и mcp_full.

Типичные рабочие процессы агента

Quality MCP PR gate: gate_pr_quality → исправление с помощью explain_vrt_failure / frt_heal_step_def → run_vrt или run_full_audit

Подключение сайта: create_project → crawl_site → create_scenario → run_baseline → create_frt_scenario → run_frt_feature

Полное QA: run_full_audit (опционально pillars[]) → wait_for_run → gate_pr_quality → get_site_health

Аудит только по столпам: run_full_audit с pillars: ["a11y"], ["tracking"] и т.д.

VRT перед слиянием: list_scenarios → run_vrt → get_run_failures → explain_vrt_failure

FRT в CI: GitHub Action type: frt или visualq frt --api-key …

Jira-доказательство трекинга: прочитать тикет → tracking_prove_jira_ticket с confirm: true (семантическое намерение → общий связанный сценарий) → вставить jiraMarkdown в JIRA.

QA на основе Jira: прочитать тикет → create_scenario / create_frt_scenario с id тикета в имени → запустить тесты

Инструменты, изменяющие данные, требуют confirm: true в аргументах.

Устаревший CI-ключ проекта

Для GitHub Actions / Jenkins используйте ключ с областью проекта (vq_live_…) с областью ci — не ключ агента организации.

{
  "mcpServers": {
    "visualq": {
      "command": "npx",
      "args": ["-y", "@visualq/mcp"],
      "env": {
        "VISUALQ_API_KEY": "vq_live_…",
        "VISUALQ_BASE_URL": "https://visualq.ai"
      }
    }
  }
}

Создайте в Проект → Настройки → API keys.

Хостированный REST-шлюз (продвинутый)

VisualQ также предоставляет JSON-вызов (не по протоколу stdio MCP):

• GET https://visualq.ai/api/mcp — каталог инструментов (публичный)

• POST https://visualq.ai/api/mcp/v1/invoke — X-API-Key + { "tool", "args" }

Пакет npm @visualq/mcp — это поддерживаемый путь интеграции с IDE.

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

npm install
npm run build
VISUALQ_API_KEY=vq_org_live_… VISUALQ_BASE_URL=http://localhost:3000 node dist/index.js

Синхронизация манифеста инструментов из бэкенда visualq (репозиторий-сосед):

cd ../visualq && npm run mcp:export-manifest
cd ../visualq-mcp && npm run sync-manifest

Перед публикацией в npm:

cd ../visualq && npm run mcp:export-manifest
cd ../visualq-mcp && npm test && npm run build && npm run sync-manifest
npm publish --access public
# Optional: publish agent skills if skills/ changed
cd packages/agent-skills && npm publish --access public

Репозиторий

• Пакет: abecms/visualq-mcp

• Бэкенд: abecms/visualq (/api/mcp/v1/invoke)