@visualq/mcp

Servidor MCP para VisualQ — la interfaz de agente Quality OS. @visualq/mcp expone 44 herramientas (perfil qa): auditoría multi-pilar, VRT/FRT (frt_get_feature), plan de tracking + prueba JIRA, salud continua. Para Cursor, Claude Desktop o cualquier cliente MCP.

Configuración de producción (recomendada)

1. Inicia sesión en https://visualq.ai

2. Ve a Configuración → Claves API de agente (admin de la organización)

3. Crea una clave con ámbito mcp_full

4. Opcionalmente, establece un slug de proyecto predeterminado si trabajas principalmente en un cliente

5. Copia el fragmento de configuración MCP de Cursor

6. Pégalo en ~/.cursor/mcp.json (o en el .cursor/mcp.json del proyecto) y reinicia Cursor

O un comando:

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

O instala el plugin de Cursor (habilidades + reglas incluidas).

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

Atajo para un solo proyecto

Si tu clave de organización tiene un proyecto predeterminado (o lo configuras solo en el entorno MCP):

"VISUALQ_DEFAULT_PROJECT": "afp-com"

Entonces las herramientas pueden omitir project cuando la clave tiene defaultProject en el servidor o esta variable de entorno está configurada en la configuración MCP.

Organizaciones con múltiples proyectos

Pasa project en cada llamada de herramienta (slug o id), por ejemplo "project": "afp-com".

Related MCP server: Artillery MCP Server

Variables de entorno

Ámbitos de clave API

Las claves de agente de organización solo admiten mcp_read y mcp_full.

Flujos de trabajo típicos del agente

Puerta PR de calidad MCP: gate_pr_quality → corregir con explain_vrt_failure / frt_heal_step_def → run_vrt o run_full_audit

Incorporar un sitio: create_project → crawl_site → create_scenario → run_baseline → create_frt_scenario → run_frt_feature

QA completo: run_full_audit (opcional pillars[]) → wait_for_run → gate_pr_quality → get_site_health

Auditoría solo de pilar: run_full_audit con pillars: ["a11y"], ["tracking"], etc.

VRT previo a fusión: list_scenarios → run_vrt → get_run_failures → explain_vrt_failure

FRT en CI: Acción de GitHub type: frt o visualq frt --api-key …

Prueba de tracking en Jira: leer ticket → tracking_prove_jira_ticket con confirm: true (intención semántica → escenario genérico vinculado) → pegar jiraMarkdown en JIRA.

QA impulsado por Jira: leer ticket → create_scenario / create_frt_scenario con id de ticket en el nombre → ejecutar pruebas

Las herramientas de mutación requieren confirm: true en los argumentos.

Clave CI de proyecto heredada

Para GitHub Actions / Jenkins, usa una clave con ámbito de proyecto (vq_live_…) con ámbito ci — no la clave de agente de organización.

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

Crea en Proyecto → Configuración → Claves API.

Puerta de enlace REST alojada (avanzado)

VisualQ también expone invocación JSON (no el protocolo de cable MCP stdio):

• GET https://visualq.ai/api/mcp — catálogo de herramientas (público)

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

El paquete npm @visualq/mcp es la ruta de integración IDE compatible.

Desarrollo local

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

Sincroniza el manifiesto de herramientas desde el backend visualq (repositorio hermano):

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

Antes de publicar en 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

Repositorio

• Paquete: abecms/visualq-mcp

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