@visualq/mcp

VisualQ 向け MCP サーバー — 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. 主に 1 つのクライアントで作業する場合は、必要に応じて デフォルトプロジェクト スラッグを設定

5. Cursor MCP 設定 スニペットをコピー

6. ~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）に貼り付け、Cursor を再起動

または 1 つのコマンドで:

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（スラッグまたは 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 で 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 駆動 QA: チケットを読む → create_scenario / create_frt_scenario でチケット ID を名前に含める → テストを実行

変更ツールには引数に 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）