pixelgrade

pixelgrade

pixelgrade 让你无需亲自打开浏览器，就能检查页面上的广告像素是否正常工作。提供一个落地页，它就会为找到的 Meta、TikTok 和 OpenAI 像素评分：它们是否会等到获得 Cookie 同意后才触发、同一事件是否会触发两次、浏览器端与任何服务端副本之间的事件 ID 是否一致，以及广告附加的点击 ID 是否已被捕获，例如将 fbclid 转换为 _fbc。如果发现问题，你会获得问题描述、说明，以及针对你的平台的分步修复指南。

该软件包本身不会在本地执行任何检查。它只是连接到托管的像素检查服务的轻量桥接层：它会原样返回从该服务捕获的工具列表，并将每次工具调用转发到上游，未经修改地返回回复。所有四种工具均为只读。检查会读取你指定的页面；读取报告、列出问题和查看修复指南都不会更改或安装任何内容，也不会访问任何广告账户。

工具

• check_page — 检查页面上的像素并为每个像素评分。必填：url（要检查的页面，通常是广告指向的落地页，长度为 3 到 2048 个字符）。可选：recheck（重新开始检查，而非复用过去 24 小时内的结果；上次检查满一小时后才可使用）和 wait_seconds（0 到 45，默认值为 40；检查需要 20 到 60 秒，如果仍在运行，可以通过 get_report 轮询）。欧盟浏览器会访问该页面两次，以测试 Cookie 同意行为。
• get_report — 读取先前检查的结果。必填：report（报告 ID，例如 Ab3dE5fG7hJ9kL2m，或完整的报告链接，长度为 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 状态、无法读取响应，或 无法完成的请求——会作为 isError 结果返回，其文本以 pixelgrade error: 开头（此呈现方式是本次重建自行标记的还原内容）。

命令行界面

每个工具也都可作为子命令使用，并接受一个 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 服务；其他参数 则会正常传递给命令行界面。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全通过桩接的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 详见 LICENSE。