@browserstack/mcp-server 1.2.15-beta.1 → 1.2.15-beta.2

package/dist/tools/percy-mcp/core/get-build-items.d.ts

@@ -0,0 +1,13 @@
+/**
+ * percy_get_build_items — List snapshots in a Percy build filtered by category.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface GetBuildItemsArgs {
+    build_id: string;
+    category?: string;
+    sort_by?: string;
+    limit?: number;
+}
+export declare function percyGetBuildItems(args: GetBuildItemsArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/core/get-build-items.js

@@ -0,0 +1,65 @@
+/**
+ * percy_get_build_items — List snapshots in a Percy build filtered by category.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+function na(value) {
+    if (value == null || value === "")
+        return "N/A";
+    return String(value);
+}
+function pct(value) {
+    if (value == null)
+        return "N/A";
+    return `${(value * 100).toFixed(1)}%`;
+}
+export async function percyGetBuildItems(args, config) {
+    const client = new PercyClient(config, { scope: "project" });
+    const limit = Math.min(args.limit ?? 20, 100);
+    const params = {
+        "filter[build-id]": args.build_id,
+        "page[limit]": String(limit),
+    };
+    if (args.category) {
+        params["filter[category]"] = args.category;
+    }
+    if (args.sort_by) {
+        params["sort"] = args.sort_by;
+    }
+    const response = await client.get("/build-items", params);
+    const items = Array.isArray(response.data) ? response.data : [];
+    if (items.length === 0) {
+        const category = args.category ? ` in category "${args.category}"` : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `_No snapshots found${category} for build ${args.build_id}._`,
+                },
+            ],
+        };
+    }
+    const lines = [];
+    const category = args.category ? ` (${args.category})` : "";
+    lines.push(`## Build Snapshots${category} — ${items.length} items`);
+    lines.push("");
+    lines.push("| # | Snapshot Name | ID | Diff | AI Diff | Status |");
+    lines.push("|---|---------------|----|----- |---------|--------|");
+    items.forEach((item, i) => {
+        const name = na(item.name ?? item.snapshotName);
+        const id = na(item.id ?? item.snapshotId);
+        const diff = pct(item.diffRatio);
+        const aiDiff = pct(item.aiDiffRatio);
+        const status = na(item.reviewState ?? item.state);
+        lines.push(`| ${i + 1} | ${name} | ${id} | ${diff} | ${aiDiff} | ${status} |`);
+    });
+    if (response.meta) {
+        const total = response.meta.totalEntries ?? response.meta.total;
+        if (total != null && total > items.length) {
+            lines.push("");
+            lines.push(`_Showing ${items.length} of ${total} snapshots._`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}

package/dist/tools/percy-mcp/core/get-build.d.ts

@@ -0,0 +1,10 @@
+/**
+ * percy_get_build — Get detailed Percy build information.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface GetBuildArgs {
+    build_id: string;
+}
+export declare function percyGetBuild(args: GetBuildArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/core/get-build.js

@@ -0,0 +1,16 @@
+/**
+ * percy_get_build — Get detailed Percy build information.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { formatBuild } from "../../../lib/percy-api/formatter.js";
+export async function percyGetBuild(args, config) {
+    const client = new PercyClient(config, { scope: "project" });
+    const response = await client.get(`/builds/${args.build_id}`, { "include-metadata": "true" }, [
+        "build-summary",
+        "browsers",
+    ]);
+    const build = response.data;
+    return {
+        content: [{ type: "text", text: formatBuild(build) }],
+    };
+}

package/dist/tools/percy-mcp/core/get-comparison.d.ts

@@ -0,0 +1,11 @@
+/**
+ * percy_get_comparison — Get detailed Percy comparison data.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface GetComparisonArgs {
+    comparison_id: string;
+    include_images?: boolean;
+}
+export declare function percyGetComparison(args: GetComparisonArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/core/get-comparison.js

@@ -0,0 +1,59 @@
+/**
+ * percy_get_comparison — Get detailed Percy comparison data.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { formatComparison } from "../../../lib/percy-api/formatter.js";
+export async function percyGetComparison(args, config) {
+    const client = new PercyClient(config, { scope: "project" });
+    const includes = [
+        "head-screenshot.image",
+        "base-screenshot.image",
+        "diff-image",
+        "ai-diff-image",
+        "browser.browser-family",
+        "comparison-tag",
+    ];
+    const response = await client.get(`/comparisons/${args.comparison_id}`, undefined, includes);
+    const comparison = response.data;
+    if (!comparison) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `_Comparison ${args.comparison_id} not found._`,
+                },
+            ],
+        };
+    }
+    const contentParts = [];
+    // Always include the formatted text
+    contentParts.push({
+        type: "text",
+        text: formatComparison(comparison, { includeRegions: true }),
+    });
+    // If include_images is requested, fetch and include image URLs as text
+    if (args.include_images) {
+        const imageLines = [];
+        imageLines.push("");
+        imageLines.push("### Screenshot URLs");
+        const baseUrl = comparison.baseScreenshot?.image?.url ?? comparison.baseScreenshot?.url;
+        const headUrl = comparison.headScreenshot?.image?.url ?? comparison.headScreenshot?.url;
+        const diffUrl = comparison.diffImage?.url;
+        const aiDiffUrl = comparison.aiDiffImage?.url;
+        if (baseUrl)
+            imageLines.push(`- **Base:** ${baseUrl}`);
+        if (headUrl)
+            imageLines.push(`- **Head:** ${headUrl}`);
+        if (diffUrl)
+            imageLines.push(`- **Diff:** ${diffUrl}`);
+        if (aiDiffUrl)
+            imageLines.push(`- **AI Diff:** ${aiDiffUrl}`);
+        if (imageLines.length > 2) {
+            contentParts.push({
+                type: "text",
+                text: imageLines.join("\n"),
+            });
+        }
+    }
+    return { content: contentParts };
+}

package/dist/tools/percy-mcp/core/get-snapshot.d.ts

@@ -0,0 +1,10 @@
+/**
+ * percy_get_snapshot — Get a Percy snapshot with all comparisons and screenshots.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface GetSnapshotArgs {
+    snapshot_id: string;
+}
+export declare function percyGetSnapshot(args: GetSnapshotArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/core/get-snapshot.js

@@ -0,0 +1,40 @@
+/**
+ * percy_get_snapshot — Get a Percy snapshot with all comparisons and screenshots.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { formatSnapshot, formatComparison, } from "../../../lib/percy-api/formatter.js";
+export async function percyGetSnapshot(args, config) {
+    const client = new PercyClient(config, { scope: "project" });
+    const includes = [
+        "comparisons.head-screenshot.image",
+        "comparisons.base-screenshot.lossy-image",
+        "comparisons.diff-image",
+        "comparisons.browser.browser-family",
+        "comparisons.comparison-tag",
+    ];
+    const response = await client.get(`/snapshots/${args.snapshot_id}`, undefined, includes);
+    const snapshot = response.data;
+    if (!snapshot) {
+        return {
+            content: [
+                { type: "text", text: `_Snapshot ${args.snapshot_id} not found._` },
+            ],
+        };
+    }
+    const comparisons = snapshot.comparisons ?? [];
+    const lines = [];
+    lines.push(formatSnapshot(snapshot, comparisons));
+    if (comparisons.length > 0) {
+        lines.push("");
+        lines.push("---");
+        lines.push("");
+        lines.push("### Comparison Details");
+        for (const comparison of comparisons) {
+            lines.push("");
+            lines.push(formatComparison(comparison, { includeRegions: true }));
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}

package/dist/tools/percy-mcp/core/list-builds.d.ts

@@ -0,0 +1,14 @@
+/**
+ * percy_list_builds — List Percy builds for a project with filtering.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface ListBuildsArgs {
+    project_id?: string;
+    branch?: string;
+    state?: string;
+    sha?: string;
+    limit?: number;
+}
+export declare function percyListBuilds(args: ListBuildsArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/core/list-builds.js

@@ -0,0 +1,45 @@
+/**
+ * percy_list_builds — List Percy builds for a project with filtering.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { formatBuildStatus } from "../../../lib/percy-api/formatter.js";
+export async function percyListBuilds(args, config) {
+    const client = new PercyClient(config, { scope: "project" });
+    const limit = Math.min(args.limit ?? 10, 30);
+    const params = {
+        "page[limit]": String(limit),
+    };
+    if (args.branch) {
+        params["filter[branch]"] = args.branch;
+    }
+    if (args.state) {
+        params["filter[state]"] = args.state;
+    }
+    if (args.sha) {
+        params["filter[sha]"] = args.sha;
+    }
+    const path = args.project_id
+        ? `/projects/${args.project_id}/builds`
+        : "/builds";
+    const response = await client.get(path, params);
+    const builds = Array.isArray(response.data) ? response.data : [];
+    if (builds.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "_No builds found matching the specified filters._",
+                },
+            ],
+        };
+    }
+    const lines = [];
+    lines.push(`## Percy Builds (${builds.length})`);
+    lines.push("");
+    for (const build of builds) {
+        lines.push(`- ${formatBuildStatus(build)} (ID: ${build.id})`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}

package/dist/tools/percy-mcp/core/list-projects.d.ts

@@ -0,0 +1,12 @@
+/**
+ * percy_list_projects — List Percy projects in an organization.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface ListProjectsArgs {
+    org_id?: string;
+    search?: string;
+    limit?: number;
+}
+export declare function percyListProjects(args: ListProjectsArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/core/list-projects.js

@@ -0,0 +1,51 @@
+/**
+ * percy_list_projects — List Percy projects in an organization.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyListProjects(args, config) {
+    const client = new PercyClient(config, { scope: "auto" });
+    const limit = Math.min(args.limit ?? 10, 50);
+    const params = {
+        "page[limit]": String(limit),
+    };
+    if (args.search) {
+        params["filter[name]"] = args.search;
+    }
+    const path = args.org_id
+        ? `/organizations/${args.org_id}/projects`
+        : "/projects";
+    const response = await client.get(path, params);
+    const projects = Array.isArray(response.data) ? response.data : [];
+    if (projects.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "_No projects found._",
+                },
+            ],
+        };
+    }
+    const lines = [];
+    lines.push(`## Percy Projects (${projects.length})`);
+    lines.push("");
+    lines.push("| # | Name | ID | Type | Default Branch |");
+    lines.push("|---|------|----|------|----------------|");
+    projects.forEach((project, i) => {
+        const name = project.name ?? "Unnamed";
+        const id = project.id ?? "?";
+        const type = project.type ?? "web";
+        const branch = project.defaultBaseBranch ?? "main";
+        lines.push(`| ${i + 1} | ${name} | ${id} | ${type} | ${branch} |`);
+    });
+    if (response.meta) {
+        const total = response.meta.totalPages ?? response.meta.total;
+        if (total != null) {
+            lines.push("");
+            lines.push(`_Showing ${projects.length} of ${total} projects._`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}

package/dist/tools/percy-mcp/creation/create-app-snapshot.d.ts

@@ -0,0 +1,12 @@
+/**
+ * percy_create_app_snapshot — Create a snapshot for App Percy or BYOS builds.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface CreateAppSnapshotArgs {
+    build_id: string;
+    name: string;
+    test_case?: string;
+}
+export declare function percyCreateAppSnapshot(args: CreateAppSnapshotArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/creation/create-app-snapshot.js

@@ -0,0 +1,29 @@
+/**
+ * percy_create_app_snapshot — Create a snapshot for App Percy or BYOS builds.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyCreateAppSnapshot(args, config) {
+    const client = new PercyClient(config, { scope: "auto" });
+    const attributes = {
+        name: args.name,
+    };
+    if (args.test_case) {
+        attributes["test-case"] = args.test_case;
+    }
+    const body = {
+        data: {
+            type: "snapshots",
+            attributes,
+        },
+    };
+    const response = await client.post(`/builds/${args.build_id}/snapshots`, body);
+    const id = response.data?.id ?? "unknown";
+    return {
+        content: [
+            {
+                type: "text",
+                text: `App snapshot '${args.name}' created (ID: ${id}). Create comparisons with percy_create_comparison.`,
+            },
+        ],
+    };
+}

package/dist/tools/percy-mcp/creation/create-build.d.ts

@@ -0,0 +1,19 @@
+/**
+ * percy_create_build — Create a new Percy build for visual testing.
+ *
+ * Supports two modes:
+ * 1. With project_id: POST /projects/{project_id}/builds
+ * 2. Without project_id: POST /builds (uses PERCY_TOKEN project scope)
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface CreateBuildArgs {
+    project_id?: string;
+    branch: string;
+    commit_sha: string;
+    commit_message?: string;
+    pull_request_number?: string;
+    type?: string;
+}
+export declare function percyCreateBuild(args: CreateBuildArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/creation/create-build.js

@@ -0,0 +1,68 @@
+/**
+ * percy_create_build — Create a new Percy build for visual testing.
+ *
+ * Supports two modes:
+ * 1. With project_id: POST /projects/{project_id}/builds
+ * 2. Without project_id: POST /builds (uses PERCY_TOKEN project scope)
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyCreateBuild(args, config) {
+    const { project_id, branch, commit_sha, commit_message, pull_request_number, type, } = args;
+    const body = {
+        data: {
+            type: "builds",
+            attributes: {
+                branch,
+                "commit-sha": commit_sha,
+                ...(commit_message ? { "commit-message": commit_message } : {}),
+                ...(pull_request_number
+                    ? { "pull-request-number": pull_request_number }
+                    : {}),
+                ...(type ? { type } : {}),
+            },
+            relationships: {
+                resources: {
+                    data: [],
+                },
+            },
+        },
+    };
+    try {
+        const client = new PercyClient(config);
+        // Use project-scoped endpoint if project_id given, otherwise token-scoped
+        const endpoint = project_id ? `/projects/${project_id}/builds` : "/builds";
+        const result = await client.post(endpoint, body);
+        // Handle both raw JSON:API response and deserialized response
+        const buildData = result?.data || result;
+        const buildId = buildData?.id ?? (typeof buildData === "object" ? "created" : "unknown");
+        const buildNumber = buildData?.buildNumber || buildData?.["build-number"] || "";
+        const webUrl = buildData?.webUrl || buildData?.["web-url"] || "";
+        let output = `## Percy Build Created\n\n`;
+        output += `| Field | Value |\n`;
+        output += `|-------|-------|\n`;
+        output += `| **Build ID** | ${buildId} |\n`;
+        if (buildNumber)
+            output += `| **Build Number** | ${buildNumber} |\n`;
+        output += `| **Branch** | ${branch} |\n`;
+        output += `| **Commit** | ${commit_sha} |\n`;
+        if (webUrl)
+            output += `| **URL** | ${webUrl} |\n`;
+        output += `\n### Next Steps\n\n`;
+        output += `1. Create snapshots: \`percy_create_snapshot\` with build_id \`${buildId}\`\n`;
+        output += `2. Upload resources: \`percy_upload_resource\` for each missing resource\n`;
+        output += `3. Finalize: \`percy_finalize_build\` with build_id \`${buildId}\`\n`;
+        return { content: [{ type: "text", text: output }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to create build: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/percy-mcp/creation/create-comparison.d.ts

@@ -0,0 +1,18 @@
+/**
+ * percy_create_comparison — Create a comparison with device/browser tag and tile metadata.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface CreateComparisonArgs {
+    snapshot_id: string;
+    tag_name: string;
+    tag_width: number;
+    tag_height: number;
+    tag_os_name?: string;
+    tag_os_version?: string;
+    tag_browser_name?: string;
+    tag_orientation?: string;
+    tiles: string;
+}
+export declare function percyCreateComparison(args: CreateComparisonArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/creation/create-comparison.js

@@ -0,0 +1,90 @@
+/**
+ * percy_create_comparison — Create a comparison with device/browser tag and tile metadata.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyCreateComparison(args, config) {
+    const client = new PercyClient(config, { scope: "auto" });
+    // Parse tiles JSON string
+    let tilesArray;
+    try {
+        tilesArray = JSON.parse(args.tiles);
+        if (!Array.isArray(tilesArray)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: 'tiles' must be a JSON array of tile objects.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: 'tiles' is not valid JSON. Expected a JSON array of tile objects.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Build tag attributes
+    const tagAttributes = {
+        name: args.tag_name,
+        width: args.tag_width,
+        height: args.tag_height,
+    };
+    if (args.tag_os_name)
+        tagAttributes["os-name"] = args.tag_os_name;
+    if (args.tag_os_version)
+        tagAttributes["os-version"] = args.tag_os_version;
+    if (args.tag_browser_name)
+        tagAttributes["browser-name"] = args.tag_browser_name;
+    if (args.tag_orientation)
+        tagAttributes["orientation"] = args.tag_orientation;
+    // Build tiles data
+    const tilesData = tilesArray.map((tile) => {
+        const tileAttributes = {
+            sha: tile.sha,
+        };
+        if (tile["status-bar-height"] != null) {
+            tileAttributes["status-bar-height"] = tile["status-bar-height"];
+        }
+        if (tile["nav-bar-height"] != null) {
+            tileAttributes["nav-bar-height"] = tile["nav-bar-height"];
+        }
+        return {
+            type: "tiles",
+            attributes: tileAttributes,
+        };
+    });
+    const body = {
+        data: {
+            type: "comparisons",
+            relationships: {
+                tag: {
+                    data: {
+                        type: "tag",
+                        attributes: tagAttributes,
+                    },
+                },
+                tiles: {
+                    data: tilesData,
+                },
+            },
+        },
+    };
+    const response = await client.post(`/snapshots/${args.snapshot_id}/comparisons`, body);
+    const id = response.data?.id ?? "unknown";
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Comparison created (ID: ${id}). Upload tiles with percy_upload_tile.`,
+            },
+        ],
+    };
+}

package/dist/tools/percy-mcp/creation/create-snapshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * percy_create_snapshot — Create a snapshot in a Percy build with DOM resources.
+ *
+ * POST /builds/{build_id}/snapshots with JSON:API body.
+ * Returns snapshot ID and list of missing resources for upload.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface CreateSnapshotArgs {
+    build_id: string;
+    name: string;
+    widths?: string;
+    enable_javascript?: boolean;
+    resources?: string;
+}
+export declare function percyCreateSnapshot(args: CreateSnapshotArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};