@visualq/mcp

面向 VisualQ 的 MCP 服务器——质量操作系统的代理接口。@visualq/mcp 提供 44 个工具（qa profile）：多支柱审计、VRT/FRT（frt_get_feature）、跟踪计划及 JIRA 证明、滚动健康状态。适用于 Cursor、Claude Desktop 或任何 MCP 客户端。

生产环境配置（推荐）

1. 登录 https://visualq.ai

2. 前往 设置 → 代理 API 密钥（组织管理员）

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"

那么当密钥在服务器上设置了 defaultProject 或 MCP 配置中设置了此环境变量时，工具可以省略 project。

多项目组织

在每个工具调用中传递 project（slug 或 ID），例如 "project": "afp-com"。

Related MCP server: Artillery MCP Server

环境变量

API 密钥作用域

组织代理密钥仅支持 mcp_read 和 mcp_full。

典型代理工作流

质量 MCP PR 门禁： 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

完整质量审计： 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

CI 中的 FRT： GitHub Action type: frt 或 visualq frt --api-key …

Jira 跟踪证明： 读取工单 → tracking_prove_jira_ticket 带上 confirm: true（语义意图 → 通用链接场景） → 将 jiraMarkdown 粘贴到 JIRA。

Jira 驱动的质量审计： 读取工单 → 在名称中包含工单 ID 的情况下，使用 create_scenario / create_frt_scenario 创建场景 → 运行测试

修改工具需要在参数中带上 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 密钥 中创建。

托管 REST 网关（高级）

VisualQ 也暴露 JSON 调用（非 stdio MCP 协议）：

• GET https://visualq.ai/api/mcp — 工具目录（公开）

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

@visualq/mcp npm 包是受支持的 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）