@visualq/mcp

MCP-Server für VisualQ — die Quality OS-Agent-Schnittstelle. @visualq/mcp stellt 44 Tools (QA-Profil) bereit: Multi-Pillar-Audit, VRT/FRT (frt_get_feature), Tracking-Plan + JIRA-Nachweis, laufende Health-Überprüfung. Für Cursor, Claude Desktop oder jeden MCP-Client.

Produktionseinrichtung (empfohlen)

1. Melden Sie sich bei https://visualq.ai an

2. Gehen Sie zu Einstellungen → Agent API Keys (Org-Administrator)

3. Erstellen Sie einen Schlüssel mit dem Bereich mcp_full

4. Legen Sie optional einen Standard-Projekt-Slug fest, wenn Sie hauptsächlich an einem Client arbeiten

5. Kopieren Sie den Cursor MCP-Konfigurationsausschnitt

6. Fügen Sie ihn in ~/.cursor/mcp.json (oder das projektbezogene .cursor/mcp.json) ein und starten Sie Cursor neu

Oder ein Befehl:

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

Oder installieren Sie das Cursor-Plugin (Fähigkeiten + Regeln gebündelt).

{
  "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"
      }
    }
  }
}

Abkürzung für einzelne Projekte

Wenn Ihr Organisationsschlüssel ein Standardprojekt hat (oder Sie es nur in der MCP-Umgebungsvariable festlegen):

"VISUALQ_DEFAULT_PROJECT": "afp-com"

Dann können Tools project weglassen, wenn der Schlüssel defaultProject auf dem Server hat oder diese Umgebungsvariable in der MCP-Konfiguration gesetzt ist.

Organisationen mit mehreren Projekten

Übergeben Sie project bei jedem Tool-Aufruf (Slug oder ID), z. B. "project": "afp-com".

Related MCP server: Artillery MCP Server

Umgebungsvariablen

API-Schlüssel-Bereiche

Org-Agent-Schlüssel unterstützen nur mcp_read und mcp_full.

Typische Agent-Workflows

Quality MCP PR-Gate: gate_pr_quality → Behebung mit explain_vrt_failure / frt_heal_step_def → run_vrt oder run_full_audit

Eine Website onboarden: create_project → crawl_site → create_scenario → run_baseline → create_frt_scenario → run_frt_feature

Vollständige QA: run_full_audit (optional pillars[]) → wait_for_run → gate_pr_quality → get_site_health

Nur-Pillar-Audit: run_full_audit mit pillars: ["a11y"], ["tracking"], usw.

VRT vor dem Merge: list_scenarios → run_vrt → get_run_failures → explain_vrt_failure

FRT in CI: GitHub Action type: frt oder visualq frt --api-key …

Jira-Nachweis von Tracking: Ticket lesen → tracking_prove_jira_ticket mit confirm: true (semantische Absicht → generisches verknüpftes Szenario) → jiraMarkdown in JIRA einfügen.

Jira-gesteuerte QA: Ticket lesen → create_scenario / create_frt_scenario mit Ticket-ID im Namen → Tests ausführen

Mutierende Tools erfordern confirm: true in den Argumenten.

Legacy-Projekt-CI-Schlüssel

Für GitHub Actions / Jenkins verwenden Sie einen projektbezogenen Schlüssel (vq_live_…) mit dem Bereich ci — nicht den Org-Agent-Schlüssel.

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

Erstellen Sie in Projekt → Einstellungen → API keys.

Gehostetes REST-Gateway (fortgeschritten)

VisualQ bietet auch JSON-Aufrufe (kein stdio MCP-Drahtprotokoll):

• GET https://visualq.ai/api/mcp — Tool-Katalog (öffentlich)

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

Das npm-Paket @visualq/mcp ist der unterstützte IDE-Integrationspfad.

Lokale Entwicklung

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

Tool-Manifest vom visualq-Backend (Geschwister-Repository) synchronisieren:

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

Vor der Veröffentlichung auf 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

Repository

• Paket: abecms/visualq-mcp

• Backend: abecms/visualq (/api/mcp/v1/invoke)