Percy Integration with new flow

Author: tech-sushant

src/tools/percy-change.ts

@@ -0,0 +1,79 @@
+import logger from "../logger.js";
+import { BrowserStackConfig } from "../lib/types.js";
+import { getBrowserStackAuth } from "../lib/get-auth.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { getPercyBuildCount } from "./review-agent-utils/build-counts.js";
+import { getPercySnapshotIds } from "./review-agent-utils/percy-snapshots.js";
+import { PercyIntegrationTypeEnum } from "./sdk-utils/common/types.js";
+import { fetchPercyToken } from "./sdk-utils/percy-web/fetchPercyToken.js";
+
+import {
+  getPercySnapshotDiffs,
+  PercySnapshotDiff,
+} from "./review-agent-utils/percy-diffs.js";
+
+export async function fetchPercyChanges(
+  args: { project_name: string },
+  config: BrowserStackConfig,
+): Promise<CallToolResult> {
+  const { project_name } = args;
+  const authorization = getBrowserStackAuth(config);
+
+  // Get Percy token for the project
+  const percyToken = await fetchPercyToken(project_name, authorization, {
+    type: PercyIntegrationTypeEnum.WEB,
+  });
+
+  // Get build info (noBuilds, isFirstBuild, lastBuildId)
+  const { noBuilds, isFirstBuild, lastBuildId } =
+    await getPercyBuildCount(percyToken);
+
+  if (noBuilds) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No Percy builds found. Please run your first Percy scan to start visual testing.",
+        },
+      ],
+    };
+  }
+
+  if (isFirstBuild || !lastBuildId) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "This is the first Percy build. No baseline exists to compare changes.",
+        },
+      ],
+    };
+  }
+
+  // Get snapshot IDs for the latest build
+  const snapshotIds = await getPercySnapshotIds(lastBuildId, percyToken);
+  logger.info(
+    `Fetched ${snapshotIds.length} snapshot IDs for build: ${lastBuildId} as ${snapshotIds.join(", ")}`,
+  );
+
+  // Fetch all diffs concurrently and flatten results
+  const allDiffs = await getPercySnapshotDiffs(snapshotIds, percyToken);
+
+  if (allDiffs.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "AI Summary is not yet available for this build/framework. There may still be visual changes—please review the build on the dashboard. Support for AI Summary will be added soon.",
+        },
+      ],
+    };
+  }
+
+  return {
+    content: allDiffs.map((diff: PercySnapshotDiff) => ({
+      type: "text",
+      text: `${diff.name} → ${diff.title}: ${diff.description ?? ""}`,
+    })),
+  };
+}

src/tools/percy-sdk.ts

@@ -1,24 +1,36 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { trackMCP } from "../index.js";
 import { BrowserStackConfig } from "../lib/types.js";
+import { fetchPercyChanges } from "./percy-change.js";
+import { addListTestFiles } from "./list-test-files.js";
+import { runPercyScan } from "./run-percy-scan.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SetUpPercyParamsShape } from "./sdk-utils/common/schema.js";
 import { updateTestsWithPercyCommands } from "./add-percy-snapshots.js";
-import { addListTestFiles } from "./list-test-files.js";
-import { trackMCP } from "../index.js";
+import { approveOrDeclinePercyBuild } from "./review-agent-utils/percy-approve-reject.js";
+
 import {
   setUpPercyHandler,
   setUpSimulatePercyChangeHandler,
 } from "./sdk-utils/handler.js";
+
 import {
   SETUP_PERCY_DESCRIPTION,
   SIMULATE_PERCY_CHANGE_DESCRIPTION,
   LIST_TEST_FILES_DESCRIPTION,
   PERCY_SNAPSHOT_COMMANDS_DESCRIPTION,
 } from "./sdk-utils/common/constants.js";
+
 import {
   ListTestFilesParamsShape,
   UpdateTestFileWithInstructionsParams,
 } from "./percy-snapshot-utils/constants.js";
 
+import {
+  RunPercyScanParamsShape,
+  FetchPercyChangesParamsShape,
+  ManagePercyBuildApprovalParamsShape,
+} from "./sdk-utils/common/schema.js";
+
 export function registerPercyTools(
   server: McpServer,
   config: BrowserStackConfig,
@@ -153,6 +165,33 @@ export function registerPercyTools(
     },
   );
 
+  tools.runPercyScan = server.tool(
+    "runPercyScan",
+    "Run a Percy visual test scan. Example prompts : Run this Percy build/scan.Never run percy scan/build without this tool",
+    RunPercyScanParamsShape,
+    async (args) => {
+      return runPercyScan(args, config);
+    },
+  );
+
+  tools.fetchPercyChanges = server.tool(
+    "fetchPercyChanges",
+    "Retrieves and summarizes all visual changes detected by Percy between the latest and previous builds, helping quickly review what has changed in your project.",
+    FetchPercyChangesParamsShape,
+    async (args) => {
+      return await fetchPercyChanges(args, config);
+    },
+  );
+
+  tools.managePercyBuildApproval = server.tool(
+    "managePercyBuildApproval",
+    "Approve or reject a Percy build",
+    ManagePercyBuildApprovalParamsShape,
+    async (args) => {
+      return await approveOrDeclinePercyBuild(args, config);
+    },
+  );
+
   return tools;
 }
 

src/tools/percy-snapshot-utils/utils.ts

@@ -34,7 +34,7 @@ export async function updateFileAndStep(
   if (nextIndex === total) {
     content.push({
       type: "text",
-      text: `Step 4: Percy snapshot commands have been added to all files. You can now run the Percy build using the above command.`,
+      text: `Step 3: Percy snapshot commands have been added to all files. You can now run the tool runPercyScan to run the percy scan.`,
     });
   }
 

src/tools/review-agent-utils/build-counts.ts

@@ -0,0 +1,33 @@
+// Utility for fetching the count of Percy builds.
+export async function getPercyBuildCount(percyToken: string) {
+  const apiUrl = `https://percy.io/api/v1/builds`;
+
+  const response = await fetch(apiUrl, {
+    headers: {
+      Authorization: `Token token=${percyToken}`,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Percy builds: ${response.statusText}`);
+  }
+
+  const data = await response.json();
+  const builds = data.data ?? [];
+
+  let isFirstBuild = false;
+  let lastBuildId;
+
+  if (builds.length === 0) {
+    return { noBuilds: true, isFirstBuild: false, lastBuildId: undefined };
+  } else if (builds.length === 1) {
+    isFirstBuild = true;
+    lastBuildId = builds[0].id;
+  } else {
+    isFirstBuild = false;
+    lastBuildId = builds[0].id;
+  }
+
+  return { noBuilds: false, isFirstBuild, lastBuildId };
+}

src/tools/review-agent-utils/percy-approve-reject.ts

@@ -0,0 +1,53 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+export async function approveOrDeclinePercyBuild(
+  args: { buildId: string; action: "approve" | "unapprove" | "reject" },
+  config: BrowserStackConfig,
+): Promise<CallToolResult> {
+  const { buildId, action } = args;
+
+  // Get Basic Auth credentials
+  const [username, accessKey] = getBrowserStackAuth(config).split(":");
+  const authHeader = `Basic ${Buffer.from(`${username}:${accessKey}`).toString("base64")}`;
+
+  // Prepare request body
+  const body = {
+    data: {
+      type: "reviews",
+      attributes: { action },
+      relationships: {
+        build: { data: { type: "builds", id: buildId } },
+      },
+    },
+  };
+
+  // Send request to Percy API
+  const response = await fetch("https://percy.io/api/v1/reviews", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: authHeader,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `Percy build ${action} failed: ${response.status} ${errorText}`,
+    );
+  }
+
+  const result = await response.json();
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Percy build ${buildId} was ${result.data.attributes["review-state"]} by ${result.data.attributes["action-performed-by"].user_name}`,
+      },
+    ],
+  };
+}

src/tools/review-agent-utils/percy-builds.ts

@@ -0,0 +1,43 @@
+/**
+ * Utility for fetching Percy build information.
+ */
+
+export interface PercyBuildInfo {
+  noBuilds: boolean;
+  isFirstBuild: boolean;
+  lastBuildId?: string;
+}
+
+/**
+ * Fetches Percy build information for a given token.
+ * @param percyToken - The Percy API token.
+ * @returns PercyBuildInfo object.
+ */
+export async function getPercyBuildInfo(
+  percyToken: string,
+): Promise<PercyBuildInfo> {
+  const apiUrl = "https://percy.io/api/v1/builds";
+
+  const response = await fetch(apiUrl, {
+    headers: {
+      Authorization: `Token token=${percyToken}`,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Percy builds: ${response.statusText}`);
+  }
+
+  const data = await response.json();
+  const builds = data.data ?? [];
+
+  if (builds.length === 0) {
+    return { noBuilds: true, isFirstBuild: false, lastBuildId: undefined };
+  }
+
+  const isFirstBuild = builds.length === 1;
+  const lastBuildId = builds[0].id;
+
+  return { noBuilds: false, isFirstBuild, lastBuildId };
+}

src/tools/review-agent-utils/percy-diffs.ts

@@ -0,0 +1,76 @@
+/**
+ * Utility for fetching and aggregating Percy snapshot diffs.
+ */
+
+export interface PercySnapshotDiff {
+  id: string;
+  name: string | null;
+  title: string;
+  description: string | null;
+  coordinates: any;
+}
+
+/**
+ * Fetches diffs for a single Percy snapshot.
+ * @param snapshotId - The Percy snapshot ID.
+ * @param percyToken - The Percy API token.
+ * @returns Array of PercySnapshotDiff objects.
+ */
+export async function getPercySnapshotDiff(
+  snapshotId: string,
+  percyToken: string,
+): Promise<PercySnapshotDiff[]> {
+  const apiUrl = `https://percy.io/api/v1/snapshots/${snapshotId}`;
+
+  const response = await fetch(apiUrl, {
+    headers: {
+      Authorization: `Token token=${percyToken}`,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch Percy snapshot ${snapshotId}: ${response.statusText}`,
+    );
+  }
+
+  const data = await response.json();
+  const pageUrl = data.data.attributes?.name || null;
+
+  const changes: PercySnapshotDiff[] = [];
+  const comparisons =
+    data.included?.filter((item: any) => item.type === "comparisons") ?? [];
+
+  for (const comparison of comparisons) {
+    const appliedRegions = comparison.attributes?.["applied-regions"] ?? [];
+    for (const region of appliedRegions) {
+      if (region.ignored) continue;
+      changes.push({
+        id: String(region.id),
+        name: pageUrl,
+        title: region.change_title,
+        description: region.change_description ?? null,
+        coordinates: region.coordinates ?? null,
+      });
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Fetches and flattens all diffs for an array of Percy snapshot IDs.
+ * @param snapshotIds - Array of Percy snapshot IDs.
+ * @param percyToken - The Percy API token.
+ * @returns Flat array of PercySnapshotDiff objects.
+ */
+export async function getPercySnapshotDiffs(
+  snapshotIds: string[],
+  percyToken: string,
+): Promise<PercySnapshotDiff[]> {
+  const allDiffs = await Promise.all(
+    snapshotIds.map((id) => getPercySnapshotDiff(id, percyToken)),
+  );
+  return allDiffs.flat();
+}