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

package/dist/lib/percy-api/percy-error-handler.js

@@ -0,0 +1,302 @@
+/**
+ * Shared Percy error handler — turns raw API errors into helpful guidance.
+ *
+ * Instead of showing "403 Forbidden" or "404 Not Found", returns:
+ * - What went wrong
+ * - What the correct input looks like
+ * - Suggested next steps
+ */
+export function handlePercyToolError(error, toolHelp, args) {
+    const message = error instanceof Error ? error.message : String(error);
+    let output = `## Error: ${toolHelp.name}\n\n`;
+    // Parse the error type
+    if (message.includes("401") || message.includes("Unauthorized")) {
+        output += `**Authentication failed.** Your BrowserStack credentials may be invalid or expired.\n\n`;
+        output += `Check with: \`Use percy_auth_status\`\n`;
+    }
+    else if (message.includes("403") || message.includes("Forbidden")) {
+        output += `**Access denied.** Your credentials don't have permission for this operation.\n\n`;
+        output += `This usually means:\n`;
+        output += `- The ID you provided doesn't belong to your organization\n`;
+        output += `- Your account doesn't have access to this feature\n`;
+    }
+    else if (message.includes("404") || message.includes("Not Found")) {
+        output += `**Not found.** The ID or slug you provided doesn't exist.\n\n`;
+        // Show what was passed
+        const passedArgs = Object.entries(args)
+            .filter(([, v]) => v != null && v !== "")
+            .map(([k, v]) => `- \`${k}\`: \`${String(v)}\``)
+            .join("\n");
+        if (passedArgs) {
+            output += `You provided:\n${passedArgs}\n\n`;
+        }
+        output += `Double-check the ID/slug is correct.\n`;
+    }
+    else if (message.includes("422") || message.includes("Unprocessable")) {
+        output += `**Invalid input.** The parameters you provided aren't valid.\n\n`;
+    }
+    else if (message.includes("429") || message.includes("Rate")) {
+        output += `**Rate limited.** Too many requests. Wait a moment and try again.\n`;
+        return { content: [{ type: "text", text: output }], isError: true };
+    }
+    else if (message.includes("500") || message.includes("Internal Server")) {
+        output += `**Percy API error.** The server returned an internal error. This is usually temporary.\n\n`;
+        output += `Try again in a moment. If it persists, the endpoint may not be available for your account.\n`;
+    }
+    else {
+        output += `**Error:** ${message}\n\n`;
+    }
+    // Show correct usage
+    output += `\n### Correct Usage\n\n`;
+    output += `**${toolHelp.description}**\n\n`;
+    output += `| Parameter | Required | Description | Example |\n|---|---|---|---|\n`;
+    toolHelp.params.forEach((p) => {
+        output += `| \`${p.name}\` | ${p.required ? "Yes" : "No"} | ${p.description} | \`${p.example}\` |\n`;
+    });
+    if (toolHelp.examples.length > 0) {
+        output += `\n### Examples\n\n`;
+        toolHelp.examples.forEach((ex) => {
+            output += `\`\`\`\n${ex}\n\`\`\`\n\n`;
+        });
+    }
+    // Suggest discovery tools
+    output += `### How to find the right IDs\n\n`;
+    output += `- **Project slug:** \`Use percy_get_projects\`\n`;
+    output += `- **Build ID:** \`Use percy_get_builds with project_slug "org/project"\`\n`;
+    output += `- **Snapshot ID:** \`Use percy_get_build with build_id "123" and detail "snapshots"\`\n`;
+    output += `- **Comparison ID:** \`Use percy_get_snapshot with snapshot_id "456"\`\n`;
+    return { content: [{ type: "text", text: output }], isError: true };
+}
+// ── Pre-defined tool help for each tool ─────────────────────────────────────
+export const TOOL_HELP = {
+    percy_get_build: {
+        name: "percy_get_build",
+        description: "Get build details with different views",
+        params: [
+            {
+                name: "build_id",
+                required: true,
+                description: "Percy build ID (numeric)",
+                example: "48436286",
+            },
+            {
+                name: "detail",
+                required: false,
+                description: "View type",
+                example: "overview",
+            },
+            {
+                name: "comparison_id",
+                required: false,
+                description: "For rca/network detail",
+                example: "4391856176",
+            },
+        ],
+        examples: [
+            'Use percy_get_build with build_id "48436286"',
+            'Use percy_get_build with build_id "48436286" and detail "ai_summary"',
+            'Use percy_get_build with build_id "48436286" and detail "changes"',
+        ],
+    },
+    percy_get_snapshot: {
+        name: "percy_get_snapshot",
+        description: "Get snapshot with all comparisons and AI analysis",
+        params: [
+            {
+                name: "snapshot_id",
+                required: true,
+                description: "Percy snapshot ID (numeric)",
+                example: "2576885624",
+            },
+        ],
+        examples: ['Use percy_get_snapshot with snapshot_id "2576885624"'],
+    },
+    percy_get_comparison: {
+        name: "percy_get_comparison",
+        description: "Get comparison with AI change descriptions and image URLs",
+        params: [
+            {
+                name: "comparison_id",
+                required: true,
+                description: "Percy comparison ID (numeric)",
+                example: "4391856176",
+            },
+        ],
+        examples: ['Use percy_get_comparison with comparison_id "4391856176"'],
+    },
+    percy_get_builds: {
+        name: "percy_get_builds",
+        description: "List builds for a project",
+        params: [
+            {
+                name: "project_slug",
+                required: false,
+                description: "Project slug from percy_get_projects",
+                example: "9560f98d/my-project-abc123",
+            },
+            {
+                name: "branch",
+                required: false,
+                description: "Filter by branch",
+                example: "main",
+            },
+            {
+                name: "state",
+                required: false,
+                description: "Filter by state",
+                example: "finished",
+            },
+        ],
+        examples: [
+            'Use percy_get_builds with project_slug "9560f98d/my-project-abc123"',
+            "Use percy_get_projects  (to find project slugs first)",
+        ],
+    },
+    percy_get_projects: {
+        name: "percy_get_projects",
+        description: "List all Percy projects",
+        params: [
+            {
+                name: "search",
+                required: false,
+                description: "Search by name",
+                example: "my-app",
+            },
+        ],
+        examples: [
+            "Use percy_get_projects",
+            'Use percy_get_projects with search "dashboard"',
+        ],
+    },
+    percy_create_build: {
+        name: "percy_create_build",
+        description: "Create a Percy build with snapshots",
+        params: [
+            {
+                name: "project_name",
+                required: true,
+                description: "Project name",
+                example: "my-app",
+            },
+            {
+                name: "urls",
+                required: false,
+                description: "URLs to snapshot",
+                example: "http://localhost:3000",
+            },
+            {
+                name: "screenshots_dir",
+                required: false,
+                description: "Screenshot directory",
+                example: "./screenshots",
+            },
+            {
+                name: "test_command",
+                required: false,
+                description: "Test command",
+                example: "npx cypress run",
+            },
+        ],
+        examples: [
+            'Use percy_create_build with project_name "my-app" and urls "http://localhost:3000"',
+        ],
+    },
+    percy_create_project: {
+        name: "percy_create_project",
+        description: "Create or get a Percy project",
+        params: [
+            {
+                name: "name",
+                required: true,
+                description: "Project name",
+                example: "my-app",
+            },
+            {
+                name: "type",
+                required: false,
+                description: "web or automate",
+                example: "web",
+            },
+        ],
+        examples: ['Use percy_create_project with name "my-app"'],
+    },
+    percy_clone_build: {
+        name: "percy_clone_build",
+        description: "Clone snapshots from one build to another project",
+        params: [
+            {
+                name: "source_build_id",
+                required: true,
+                description: "Build ID to clone from",
+                example: "48436286",
+            },
+            {
+                name: "target_project_name",
+                required: true,
+                description: "Target project name",
+                example: "my-project",
+            },
+        ],
+        examples: [
+            'Use percy_clone_build with source_build_id "48436286" and target_project_name "my-project"',
+        ],
+    },
+    percy_create_app_build: {
+        name: "percy_create_app_build",
+        description: "Create an App Percy BYOS build from device screenshots",
+        params: [
+            {
+                name: "project_name",
+                required: true,
+                description: "App Percy project name",
+                example: "my-mobile-app",
+            },
+            {
+                name: "resources_dir",
+                required: true,
+                description: "Path to resources directory with device folders",
+                example: "./resources",
+            },
+            {
+                name: "branch",
+                required: false,
+                description: "Git branch (auto-detected)",
+                example: "main",
+            },
+            {
+                name: "test_case",
+                required: false,
+                description: "Test case name for all snapshots",
+                example: "Login Flow",
+            },
+        ],
+        examples: [
+            'Use percy_create_app_build with project_name "my-mobile-app" and resources_dir "./resources"',
+        ],
+    },
+    percy_get_insights: {
+        name: "percy_get_insights",
+        description: "Get testing health metrics",
+        params: [
+            {
+                name: "org_slug",
+                required: true,
+                description: "Organization slug or ID",
+                example: "9560f98d",
+            },
+            {
+                name: "period",
+                required: false,
+                description: "Time period",
+                example: "last_30_days",
+            },
+            {
+                name: "product",
+                required: false,
+                description: "web or app",
+                example: "web",
+            },
+        ],
+        examples: ['Use percy_get_insights with org_slug "9560f98d"'],
+    },
+};

package/dist/lib/percy-api/percy-session.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Percy Session — In-memory state that persists across tool calls.
+ *
+ * Stores active project token, build context, and org info so
+ * subsequent tool calls get richer context automatically.
+ */
+export interface PercySessionState {
+    projectName?: string;
+    projectToken?: string;
+    projectSlug?: string;
+    projectId?: string;
+    projectType?: string;
+    buildId?: string;
+    buildNumber?: string;
+    buildUrl?: string;
+    buildBranch?: string;
+    orgSlug?: string;
+    orgId?: string;
+}
+export declare function setActiveProject(opts: {
+    name: string;
+    token: string;
+    slug?: string;
+    id?: string;
+    type?: string;
+}): void;
+export declare function setActiveBuild(opts: {
+    id: string;
+    number?: string;
+    url?: string;
+    branch?: string;
+}): void;
+export declare function setOrg(opts: {
+    slug?: string;
+    id?: string;
+}): void;
+export declare function getSession(): PercySessionState;
+export declare function getActiveToken(): string | undefined;
+export declare function getActiveBuildId(): string | undefined;
+export declare function formatActiveProject(): string;
+export declare function formatActiveBuild(): string;
+export declare function formatSessionSummary(): string;

package/dist/lib/percy-api/percy-session.js

@@ -0,0 +1,87 @@
+/**
+ * Percy Session — In-memory state that persists across tool calls.
+ *
+ * Stores active project token, build context, and org info so
+ * subsequent tool calls get richer context automatically.
+ */
+const session = {};
+// ── Setters ─────────────────────────────────────────────────────────────────
+export function setActiveProject(opts) {
+    session.projectName = opts.name;
+    session.projectToken = opts.token;
+    if (opts.slug)
+        session.projectSlug = opts.slug;
+    if (opts.id)
+        session.projectId = opts.id;
+    if (opts.type)
+        session.projectType = opts.type;
+}
+export function setActiveBuild(opts) {
+    session.buildId = opts.id;
+    if (opts.number)
+        session.buildNumber = opts.number;
+    if (opts.url)
+        session.buildUrl = opts.url;
+    if (opts.branch)
+        session.buildBranch = opts.branch;
+}
+export function setOrg(opts) {
+    if (opts.slug)
+        session.orgSlug = opts.slug;
+    if (opts.id)
+        session.orgId = opts.id;
+}
+// ── Getters ─────────────────────────────────────────────────────────────────
+export function getSession() {
+    return { ...session };
+}
+export function getActiveToken() {
+    return session.projectToken;
+}
+export function getActiveBuildId() {
+    return session.buildId;
+}
+// ── Formatters (append to tool output) ──────────────────────────────────────
+export function formatActiveProject() {
+    if (!session.projectName)
+        return "";
+    const masked = session.projectToken
+        ? `${session.projectToken.slice(0, 8)}...${session.projectToken.slice(-4)}`
+        : "—";
+    let out = `\n### Active Project\n\n`;
+    out += `| | |\n|---|---|\n`;
+    out += `| **Project** | ${session.projectName} |\n`;
+    out += `| **Token** | \`${masked}\` |\n`;
+    if (session.projectType)
+        out += `| **Type** | ${session.projectType} |\n`;
+    if (session.projectSlug)
+        out += `| **Slug** | ${session.projectSlug} |\n`;
+    return out;
+}
+export function formatActiveBuild() {
+    if (!session.buildId)
+        return "";
+    let out = `\n### Active Build\n\n`;
+    out += `| | |\n|---|---|\n`;
+    out += `| **Build ID** | ${session.buildId} |\n`;
+    if (session.buildNumber)
+        out += `| **Build #** | ${session.buildNumber} |\n`;
+    if (session.buildUrl)
+        out += `| **URL** | ${session.buildUrl} |\n`;
+    if (session.buildBranch)
+        out += `| **Branch** | ${session.buildBranch} |\n`;
+    return out;
+}
+export function formatSessionSummary() {
+    const parts = [];
+    if (session.projectName) {
+        const masked = session.projectToken
+            ? `****${session.projectToken.slice(-4)}`
+            : "";
+        parts.push(`**Project:** ${session.projectName} (${masked})`);
+    }
+    if (session.buildId) {
+        parts.push(`**Build:** #${session.buildNumber || session.buildId}${session.buildUrl ? ` — ${session.buildUrl}` : ""}`);
+    }
+    return parts.length > 0 ? parts.join(" | ") : "";
+}

package/dist/lib/percy-api/polling.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Exponential backoff polling utility for Percy API.
+ *
+ * Used when waiting for async operations to complete (e.g., build processing,
+ * AI analysis finishing). Returns null on timeout rather than throwing.
+ */
+export interface PollOptions {
+    /** Initial delay between polls in milliseconds. Default: 500 */
+    initialDelayMs?: number;
+    /** Maximum delay between polls in milliseconds. Default: 5000 */
+    maxDelayMs?: number;
+    /** Total timeout in milliseconds. Default: 120000 (2 minutes) */
+    maxTimeoutMs?: number;
+    /** Optional callback invoked before each poll attempt. */
+    onPoll?: (attempt: number) => void;
+}
+/**
+ * Polls `fn` with exponential backoff until it returns `{ done: true }`.
+ *
+ * Backoff schedule: initialDelay → 2x → 4x → ... capped at maxDelay.
+ * Returns the result when done, or null if the timeout is exceeded.
+ */
+export declare function pollUntil<T>(fn: () => Promise<{
+    done: boolean;
+    result?: T;
+}>, options?: PollOptions): Promise<T | null>;

package/dist/lib/percy-api/polling.js

@@ -0,0 +1,42 @@
+/**
+ * Exponential backoff polling utility for Percy API.
+ *
+ * Used when waiting for async operations to complete (e.g., build processing,
+ * AI analysis finishing). Returns null on timeout rather than throwing.
+ */
+/**
+ * Polls `fn` with exponential backoff until it returns `{ done: true }`.
+ *
+ * Backoff schedule: initialDelay → 2x → 4x → ... capped at maxDelay.
+ * Returns the result when done, or null if the timeout is exceeded.
+ */
+export async function pollUntil(fn, options) {
+    const initialDelayMs = options?.initialDelayMs ?? 500;
+    const maxDelayMs = options?.maxDelayMs ?? 5_000;
+    const maxTimeoutMs = options?.maxTimeoutMs ?? 120_000;
+    const onPoll = options?.onPoll;
+    const startTime = Date.now();
+    let delay = initialDelayMs;
+    let attempt = 0;
+    while (Date.now() - startTime < maxTimeoutMs) {
+        attempt++;
+        if (onPoll) {
+            onPoll(attempt);
+        }
+        const response = await fn();
+        if (response.done) {
+            return response.result ?? null;
+        }
+        // Check if waiting another cycle would exceed the timeout
+        if (Date.now() - startTime + delay >= maxTimeoutMs) {
+            break;
+        }
+        await sleep(delay);
+        delay = Math.min(delay * 2, maxDelayMs);
+    }
+    // Timeout exceeded
+    return null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/lib/percy-api/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Percy API Zod schemas and inferred TypeScript types.
+ *
+ * All schemas use `.passthrough()` to allow extra fields from the API
+ * without throwing validation errors. This ensures forward compatibility
+ * as the Percy API evolves.
+ */
+import { z } from "zod";
+export declare const PercyBuildSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodOptional<z.ZodLiteral<"builds">>;
+    state: z.ZodString;
+    branch: z.ZodNullable<z.ZodString>;
+    buildNumber: z.ZodNullable<z.ZodNumber>;
+    reviewState: z.ZodNullable<z.ZodString>;
+    reviewStateReason: z.ZodNullable<z.ZodString>;
+    totalSnapshots: z.ZodNullable<z.ZodNumber>;
+    totalComparisons: z.ZodNullable<z.ZodNumber>;
+    totalComparisonsDiff: z.ZodNullable<z.ZodNumber>;
+    failedSnapshotsCount: z.ZodNullable<z.ZodNumber>;
+    failureReason: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodNullable<z.ZodString>;
+    finishedAt: z.ZodNullable<z.ZodString>;
+    aiDetails: z.ZodNullable<z.ZodAny>;
+    errorBuckets: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+}, z.core.$loose>;
+export type PercyBuild = z.infer<typeof PercyBuildSchema>;
+export declare const PercyComparisonSchema: z.ZodObject<{
+    id: z.ZodString;
+    state: z.ZodNullable<z.ZodString>;
+    width: z.ZodNullable<z.ZodNumber>;
+    diffRatio: z.ZodNullable<z.ZodNumber>;
+    aiDiffRatio: z.ZodNullable<z.ZodNumber>;
+    aiProcessingState: z.ZodNullable<z.ZodString>;
+    aiDetails: z.ZodNullable<z.ZodAny>;
+    appliedRegions: z.ZodNullable<z.ZodArray<z.ZodAny>>;
+}, z.core.$loose>;
+export type PercyComparison = z.infer<typeof PercyComparisonSchema>;
+export declare const PercySnapshotSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    reviewState: z.ZodNullable<z.ZodString>;
+    reviewStateReason: z.ZodNullable<z.ZodString>;
+}, z.core.$loose>;
+export type PercySnapshot = z.infer<typeof PercySnapshotSchema>;
+export declare const PercyProjectSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    slug: z.ZodNullable<z.ZodString>;
+}, z.core.$loose>;
+export type PercyProject = z.infer<typeof PercyProjectSchema>;
+export declare const PercyBuildSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    summary: z.ZodNullable<z.ZodString>;
+}, z.core.$loose>;
+export type PercyBuildSummary = z.infer<typeof PercyBuildSummarySchema>;

package/dist/lib/percy-api/types.js

@@ -0,0 +1,76 @@
+/**
+ * Percy API Zod schemas and inferred TypeScript types.
+ *
+ * All schemas use `.passthrough()` to allow extra fields from the API
+ * without throwing validation errors. This ensures forward compatibility
+ * as the Percy API evolves.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Build
+// ---------------------------------------------------------------------------
+export const PercyBuildSchema = z
+    .object({
+    id: z.string(),
+    type: z.literal("builds").optional(),
+    state: z.string(),
+    branch: z.string().nullable(),
+    buildNumber: z.number().nullable(),
+    reviewState: z.string().nullable(),
+    reviewStateReason: z.string().nullable(),
+    totalSnapshots: z.number().nullable(),
+    totalComparisons: z.number().nullable(),
+    totalComparisonsDiff: z.number().nullable(),
+    failedSnapshotsCount: z.number().nullable(),
+    failureReason: z.string().nullable(),
+    createdAt: z.string().nullable(),
+    finishedAt: z.string().nullable(),
+    aiDetails: z.any().nullable(),
+    errorBuckets: z.array(z.any()).nullable(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+export const PercyComparisonSchema = z
+    .object({
+    id: z.string(),
+    state: z.string().nullable(),
+    width: z.number().nullable(),
+    diffRatio: z.number().nullable(),
+    aiDiffRatio: z.number().nullable(),
+    aiProcessingState: z.string().nullable(),
+    aiDetails: z.any().nullable(),
+    appliedRegions: z.array(z.any()).nullable(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Snapshot
+// ---------------------------------------------------------------------------
+export const PercySnapshotSchema = z
+    .object({
+    id: z.string(),
+    name: z.string().nullable(),
+    reviewState: z.string().nullable(),
+    reviewStateReason: z.string().nullable(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Project
+// ---------------------------------------------------------------------------
+export const PercyProjectSchema = z
+    .object({
+    id: z.string(),
+    name: z.string().nullable(),
+    slug: z.string().nullable(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Build Summary
+// ---------------------------------------------------------------------------
+export const PercyBuildSummarySchema = z
+    .object({
+    id: z.string(),
+    summary: z.string().nullable(),
+})
+    .passthrough();

package/dist/server-factory.js

@@ -16,6 +16,8 @@ import addAppLiveTools from "./tools/applive.js";
 import addBuildInsightsTools from "./tools/build-insights.js";
 import { setupOnInitialized } from "./oninitialized.js";
 import addRCATools from "./tools/rca-agent.js";
+// import addPercyMcpTools from "./tools/percy-mcp/index.js"; // v1 disabled
+import addPercyMcpToolsV2 from "./tools/percy-mcp/v2/index.js";
 /**
  * Wrapper class for BrowserStack MCP Server
  * Stores a map of registered tools by name
@@ -51,6 +53,8 @@ export class BrowserStackMcpServer {
             addSelfHealTools,
             addBuildInsightsTools,
             addRCATools,
+            // addPercyMcpTools, // v1 — disabled, replaced by v2
+            addPercyMcpToolsV2,
         ];
         toolAdders.forEach((adder) => {
             // Each adder now returns a Record<string, Tool>

package/dist/tools/percy-mcp/advanced/branchline-operations.d.ts

@@ -0,0 +1,16 @@
+/**
+ * percy_branchline_operations — Sync, merge, or unmerge Percy branch baselines.
+ *
+ * Sync copies approved baselines to target branches.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface BranchlineOperationsArgs {
+    action: string;
+    project_id?: string;
+    build_id?: string;
+    target_branch_filter?: string;
+    snapshot_ids?: string;
+}
+export declare function percyBranchlineOperations(args: BranchlineOperationsArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};