pixelgrade

pixelgrade

pixelgrade を使うと、自分でブラウザーを開かずに、ページ上の広告ピクセルが実際に機能しているか確認できます。ランディングページを指定すると、ページ上で見つかった Meta、TikTok、OpenAI のピクセルを評価します。Cookie の同意を待つか、同じイベントが 2 回発生するか、イベント ID がブラウザー側とサーバー側の両方で一致するか、広告が付加するクリック ID（たとえば fbclid が _fbc になる）が取得されるかを確認します。問題がある場合は、検出結果、説明、使用しているプラットフォームで修正するための手順ガイドが表示されます。

このパッケージ自体はローカルで何も確認しません。ホスト型のピクセルチェックサービスへの薄いブリッジです。サービスからそのまま取得した情報に基づいてツール一覧を返し、すべてのツール呼び出しを上流に転送して、応答を変更せずに返します。4 つのツールはすべて読み取り専用です。チェックでは指定したページを読み取ります。レポートの読み取り、検出結果の一覧表示、修正ガイドの読み取りでは、何も変更もインストールもせず、広告アカウントにもアクセスしません。

ツール

• check_page — ページのピクセルを確認し、それぞれを評価します。必須：url（確認するページ。通常は広告のリンク先となるランディングページ。3～2048 文字）。任意：recheck（過去 24 時間以内の結果を再利用せず、新たに確認を開始します。前回の確認から 1 時間経過している場合に指定できます）および wait_seconds（0～45、デフォルトは 40。確認には 20～60 秒かかります。まだ実行中の場合は、get_report でポーリングできます）。EU のブラウザーがページに 2 回アクセスし、同意の動作を検証します。
• get_report — 前回の確認結果を読み取ります。必須：report（Ab3dE5fG7hJ9kL2m のようなレポート ID、またはレポートの完全なリンク。8～200 文字）。ステータス、検出された各ピクセルの評価、問題ごとの説明と修正ガイドへのリンク、チェックリストを返します。レポートは 90 日間保持されます。
• list_findings — 確認で報告される可能性のあるすべての問題を一覧表示します。引数は不要です。各項目には ID、重大度、タイトル、説明、および修正ガイドの有無が含まれます。確認を実行する前に問題の一覧を把握するのに役立ちます。
• get_fix_guide — 問題に対する修正手順ガイド（Markdown）を読み取ります。すべての引数は任意です：issue_id（レポートに記載された問題 ID。たとえば meta.fires_before_consent）、platform（たとえば framer、shopify、webflow、wordpress。省略した場合や不明な場合は、一般向けのガイドが返されます）、consent_tool（complianz、cookiebot、cookieyes、onetrust、usercentrics のいずれか。指定すると、Meta、TikTok、OpenAI のピクセルをその同意ツールに接続する方法がガイドに記載されます）。セットアップガイドも issue_id で取得できます。たとえば、Meta Conversions API、TikTok Events API、OpenAI Pixel またはその Conversions API のインストール方法です。

設定

• ISPIXELWORKING_MCP_URL（任意） — 上流エンドポイントを上書きします。デフォルトは https://ispixelworking.com/mcp です。（この上書き用フックは、この再構築で独自に追加したものとして明示されています。）
• ISPIXELWORKING_API_KEY（任意） — 設定すると、すべての上流リクエストに Authorization: Bearer <key> ヘッダーが付加されます。未設定の場合、キーのヘッダーは送信されません。（ヘッダー名は、Authorization というシークレットヘッダーを宣言する元のレジストリ記録によって固定されています。記録ではパッケージ環境変数の名前は固定されていないため、この環境変数からの Bearer 形式およびキーの転送は、再構築で独自に追加したものとして明示されています。元のインターフェイスはキーなしの状態で取得されました。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流にストリーミング可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name pixelgrade）を送信し、次に notifications/initialized 通知、続いて呼び出し元の引数を 変更せずに含めた tools/call リクエストを送信します。上流が Mcp-Session-Id ヘッダーを付けて initialize に応答すると、その値はセッション内の以降のすべてのリクエストに引き継がれ、 プロセスの存続期間中、同じセッションが再利用されます。応答は 通常の JSON、またはサーバー送信イベントとして届くことがあり、どちらも読み取ります。

上流からの成功結果は、上流が設定した isError フラグも含めて、 そのまま返されます。失敗（JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、または完了できないリクエスト）は、 テキストが pixelgrade error: で始まる isError 結果として返されます（この表現は、 この再構築で独自に付けたラベルです）。

CLI

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドとしても利用できます。

npx @reneturcios/pixelgrade check_page '{"url":"https://example.com/landing"}'
npx @reneturcios/pixelgrade get_report '{"report":"Ab3dE5fG7hJ9kL2m"}'
npx @reneturcios/pixelgrade get_fix_guide '{"issue_id":"meta.fires_before_consent","platform":"shopify"}'
npx @reneturcios/pixelgrade list_findings '{}'
npx @reneturcios/pixelgrade --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/pixelgrade mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "pixelgrade": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pixelgrade", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/pixelgrade
docker run --rm ghcr.io/cloudcorprecords/pixelgrade --version

コンテナのデフォルトコマンドは mcp です。そのため、最初の形式は stdio MCP サーバーとして動作し、それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートは、スタブ化された JSON-RPC 上流のみを使って実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。