@visualq/mcp

MCP 서버 for VisualQ — Quality OS 에이전트 인터페이스. **@visualq/mcp**는 44개 도구(qa 프로필)를 노출합니다: 다중 기둥 감사, VRT/FRT (frt_get_feature), 트래킹 계획 + JIRA 증명, 롤링 상태. Cursor, Claude Desktop 또는 모든 MCP 클라이언트용.

프로덕션 설정 (권장)

1. **https://visualq.ai**에 로그인

2. 설정 → 에이전트 API 키(조직 관리자)로 이동

3. 범위가 **mcp_full**인 키 생성

4. 선택적으로 하나의 클라이언트에서 주로 작업하는 경우 기본 프로젝트 slug를 설정합니다.

5. Cursor MCP config 스니펫을 복사합니다.

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**만 지원합니다.

일반적인 에이전트 워크플로

Quality 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

전체 QA: run_full_audit (선택적 pillars[]) → wait_for_run → gate_pr_quality → get_site_health

기둥 전용 감사: run_full_audit with 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 트래킹 증명: 티켓 읽기 → confirm: true와 함께 tracking_prove_jira_ticket (의미적 의도 → 일반 연결 시나리오) → jiraMarkdown을 JIRA에 붙여넣기.

Jira 기반 QA: 티켓 읽기 → 이름에 티켓 ID가 있는 create_scenario / create_frt_scenario → 테스트 실행

변경 도구는 인수에 **confirm: true**가 필요합니다.

레거시 프로젝트 CI 키

GitHub Actions / Jenkins의 경우 조직 에이전트 키가 아닌 범위 ci의 프로젝트 범위 키 (vq_live_…)를 사용합니다.

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