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

package/dist/tools/percy-mcp/advanced/branchline-operations.js

@@ -0,0 +1,81 @@
+/**
+ * percy_branchline_operations — Sync, merge, or unmerge Percy branch baselines.
+ *
+ * Sync copies approved baselines to target branches.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyBranchlineOperations(args, config) {
+    const { action, project_id, build_id, target_branch_filter, snapshot_ids } = args;
+    const client = new PercyClient(config);
+    const VALID_ACTIONS = ["sync", "merge", "unmerge"];
+    if (!VALID_ACTIONS.includes(action)) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Invalid action "${action}". Valid actions: ${VALID_ACTIONS.join(", ")}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Build the request body based on action
+    const attrs = {};
+    const relationships = {};
+    if (project_id) {
+        relationships.project = {
+            data: { type: "projects", id: project_id },
+        };
+    }
+    if (build_id) {
+        relationships.build = {
+            data: { type: "builds", id: build_id },
+        };
+    }
+    if (target_branch_filter) {
+        attrs["target-branch-filter"] = target_branch_filter;
+    }
+    if (snapshot_ids) {
+        relationships.snapshots = {
+            data: snapshot_ids
+                .split(",")
+                .map((id) => id.trim())
+                .filter(Boolean)
+                .map((id) => ({ type: "snapshots", id })),
+        };
+    }
+    const body = {
+        data: {
+            type: "branchline",
+            attributes: attrs,
+            ...(Object.keys(relationships).length > 0 ? { relationships } : {}),
+        },
+    };
+    try {
+        await client.post(`/branchline/${action}`, body);
+        const lines = [];
+        lines.push(`## Branchline ${action.charAt(0).toUpperCase() + action.slice(1)} Complete`);
+        lines.push("");
+        if (build_id)
+            lines.push(`**Build:** ${build_id}`);
+        if (project_id)
+            lines.push(`**Project:** ${project_id}`);
+        if (target_branch_filter)
+            lines.push(`**Target Branch Filter:** ${target_branch_filter}`);
+        if (snapshot_ids)
+            lines.push(`**Snapshot IDs:** ${snapshot_ids}`);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to ${action} branchline: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/percy-mcp/advanced/manage-variants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * percy_manage_variants — List, create, or update A/B testing variants
+ * for Percy snapshot comparisons.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface ManageVariantsArgs {
+    comparison_id?: string;
+    snapshot_id?: string;
+    action?: string;
+    variant_id?: string;
+    name?: string;
+    state?: string;
+}
+export declare function percyManageVariants(args: ManageVariantsArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/advanced/manage-variants.js

@@ -0,0 +1,155 @@
+/**
+ * percy_manage_variants — List, create, or update A/B testing variants
+ * for Percy snapshot comparisons.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyManageVariants(args, config) {
+    const { comparison_id, snapshot_id, action = "list", variant_id, name, state, } = args;
+    const client = new PercyClient(config);
+    // ---- List ----
+    if (action === "list") {
+        if (!comparison_id) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "comparison_id is required for the 'list' action.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const response = await client.get("/variants", { comparison_id });
+        const variants = Array.isArray(response?.data) ? response.data : [];
+        if (variants.length === 0) {
+            return {
+                content: [
+                    { type: "text", text: "_No variants found for this comparison._" },
+                ],
+            };
+        }
+        const lines = [];
+        lines.push(`## Variants (Comparison: ${comparison_id})`);
+        lines.push("");
+        lines.push("| ID | Name | State |");
+        lines.push("|----|------|-------|");
+        for (const variant of variants) {
+            const attrs = variant.attributes ?? variant;
+            const vName = attrs.name ?? "Unnamed";
+            const vState = attrs.state ?? "—";
+            lines.push(`| ${variant.id ?? "?"} | ${vName} | ${vState} |`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    // ---- Create ----
+    if (action === "create") {
+        if (!snapshot_id) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "snapshot_id is required for the 'create' action.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (!name) {
+            return {
+                content: [
+                    { type: "text", text: "name is required for the 'create' action." },
+                ],
+                isError: true,
+            };
+        }
+        const body = {
+            data: {
+                type: "variants",
+                attributes: {
+                    name,
+                },
+                relationships: {
+                    snapshot: {
+                        data: { type: "snapshots", id: snapshot_id },
+                    },
+                },
+            },
+        };
+        try {
+            const result = (await client.post("/variants", body));
+            const id = result?.data?.id ?? "?";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Variant created (ID: ${id}, name: "${name}").`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    { type: "text", text: `Failed to create variant: ${message}` },
+                ],
+                isError: true,
+            };
+        }
+    }
+    // ---- Update ----
+    if (action === "update") {
+        if (!variant_id) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "variant_id is required for the 'update' action.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const attrs = {};
+        if (name)
+            attrs.name = name;
+        if (state)
+            attrs.state = state;
+        const body = {
+            data: {
+                type: "variants",
+                id: variant_id,
+                attributes: attrs,
+            },
+        };
+        try {
+            await client.patch(`/variants/${variant_id}`, body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Variant ${variant_id} updated.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    { type: "text", text: `Failed to update variant: ${message}` },
+                ],
+                isError: true,
+            };
+        }
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Invalid action "${action}". Valid actions: list, create, update`,
+            },
+        ],
+        isError: true,
+    };
+}

package/dist/tools/percy-mcp/advanced/manage-visual-monitoring.d.ts

@@ -0,0 +1,16 @@
+/**
+ * percy_manage_visual_monitoring — Create, update, or list Visual Monitoring projects
+ * with URL lists, cron schedules, and auth configuration.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface ManageVisualMonitoringArgs {
+    org_id?: string;
+    project_id?: string;
+    action?: string;
+    urls?: string;
+    cron?: string;
+    schedule?: boolean;
+}
+export declare function percyManageVisualMonitoring(args: ManageVisualMonitoringArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/advanced/manage-visual-monitoring.js

@@ -0,0 +1,171 @@
+/**
+ * percy_manage_visual_monitoring — Create, update, or list Visual Monitoring projects
+ * with URL lists, cron schedules, and auth configuration.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyManageVisualMonitoring(args, config) {
+    const { org_id, project_id, action = "list", urls, cron, schedule } = args;
+    const client = new PercyClient(config);
+    // ---- List ----
+    if (action === "list") {
+        if (!org_id) {
+            return {
+                content: [
+                    { type: "text", text: "org_id is required for the 'list' action." },
+                ],
+                isError: true,
+            };
+        }
+        const response = await client.get(`/organizations/${org_id}/visual_monitoring_projects`);
+        const projects = Array.isArray(response?.data) ? response.data : [];
+        if (projects.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "_No Visual Monitoring projects found._",
+                    },
+                ],
+            };
+        }
+        const lines = [];
+        lines.push(`## Visual Monitoring Projects (Org: ${org_id})`);
+        lines.push("");
+        lines.push("| ID | Name | URLs | Schedule | Status |");
+        lines.push("|----|------|------|----------|--------|");
+        for (const project of projects) {
+            const attrs = project.attributes ?? project;
+            const name = attrs.name ?? "Unnamed";
+            const urlCount = Array.isArray(attrs.urls)
+                ? attrs.urls.length
+                : (attrs["url-count"] ?? "?");
+            const cronSchedule = attrs.cron ?? attrs["cron-schedule"] ?? "—";
+            const status = attrs.enabled ?? attrs.status ?? "—";
+            lines.push(`| ${project.id ?? "?"} | ${name} | ${urlCount} URLs | ${cronSchedule} | ${status} |`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    // ---- Create ----
+    if (action === "create") {
+        if (!org_id) {
+            return {
+                content: [
+                    { type: "text", text: "org_id is required for the 'create' action." },
+                ],
+                isError: true,
+            };
+        }
+        const urlArray = urls
+            ? urls
+                .split(",")
+                .map((u) => u.trim())
+                .filter(Boolean)
+            : [];
+        const attrs = {};
+        if (urlArray.length > 0)
+            attrs.urls = urlArray;
+        if (cron)
+            attrs.cron = cron;
+        if (schedule !== undefined)
+            attrs.enabled = schedule;
+        const body = {
+            data: {
+                type: "visual-monitoring-projects",
+                attributes: attrs,
+                relationships: {
+                    organization: {
+                        data: { type: "organizations", id: org_id },
+                    },
+                },
+            },
+        };
+        try {
+            const result = (await client.post(`/organizations/${org_id}/visual_monitoring_projects`, body));
+            const id = result?.data?.id ?? "?";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `## Visual Monitoring Project Created\n\n**ID:** ${id}\n**URLs:** ${urlArray.length}\n**Cron:** ${cron ?? "not set"}\n**Enabled:** ${schedule ?? "default"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to create Visual Monitoring project: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    // ---- Update ----
+    if (action === "update") {
+        if (!project_id) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "project_id is required for the 'update' action.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const attrs = {};
+        if (urls) {
+            attrs.urls = urls
+                .split(",")
+                .map((u) => u.trim())
+                .filter(Boolean);
+        }
+        if (cron)
+            attrs.cron = cron;
+        if (schedule !== undefined)
+            attrs.enabled = schedule;
+        const body = {
+            data: {
+                type: "visual-monitoring-projects",
+                id: project_id,
+                attributes: attrs,
+            },
+        };
+        try {
+            await client.patch(`/visual_monitoring_projects/${project_id}`, body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Visual Monitoring project ${project_id} updated.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to update Visual Monitoring project: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Invalid action "${action}". Valid actions: list, create, update`,
+            },
+        ],
+        isError: true,
+    };
+}

package/dist/tools/percy-mcp/auth/auth-status.d.ts

@@ -0,0 +1,3 @@
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyAuthStatus(_args: Record<string, never>, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/percy-mcp/auth/auth-status.js

@@ -0,0 +1,131 @@
+import { getPercyApiBaseUrl, maskToken } from "../../../lib/percy-api/auth.js";
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { getBrowserStackAuth } from "../../../lib/get-auth.js";
+export async function percyAuthStatus(_args, config) {
+    const baseUrl = getPercyApiBaseUrl();
+    let output = `## Percy Auth Status\n\n`;
+    output += `**API URL:** ${baseUrl}\n\n`;
+    const percyToken = process.env.PERCY_TOKEN;
+    const orgToken = process.env.PERCY_ORG_TOKEN;
+    const hasBstackCreds = !!(config["browserstack-username"] && config["browserstack-access-key"]);
+    // Token table
+    output += `### Token Configuration\n\n`;
+    output += `| Token | Status | Value |\n`;
+    output += `|-------|--------|-------|\n`;
+    output += `| PERCY_TOKEN | ${percyToken ? "Set" : "Not set"} | ${percyToken ? maskToken(percyToken) : "—"} |\n`;
+    output += `| PERCY_ORG_TOKEN | ${orgToken ? "Set" : "Not set"} | ${orgToken ? maskToken(orgToken) : "—"} |\n`;
+    output += `| BrowserStack Credentials | ${hasBstackCreds ? "Set" : "Not set"} | ${hasBstackCreds ? config["browserstack-username"] : "—"} |\n`;
+    output += "\n";
+    // Detect token type from prefix
+    if (percyToken) {
+        const hasPrefix = percyToken.includes("_");
+        const prefix = hasPrefix ? percyToken.split("_")[0] : null;
+        const tokenTypes = {
+            web: "Web project (full access — can read and write)",
+            auto: "Automate project (full access)",
+            app: "App project (full access)",
+            ss: "Generic/BYOS project",
+            vmw: "Visual Monitoring project",
+        };
+        if (prefix && tokenTypes[prefix]) {
+            output += `**Token type:** ${prefix} — ${tokenTypes[prefix]}\n\n`;
+        }
+        else if (!hasPrefix) {
+            output += `**Token type:** CI/write-only — can create builds but may not read them\n`;
+            output += `  Tip: Use \`percy_create_project\` to get a full-access \`web_*\` token\n\n`;
+        }
+        else {
+            output += `**Token type:** ${prefix} — custom\n\n`;
+        }
+    }
+    // Validation
+    output += `### Validation\n\n`;
+    // 1. Try Percy API with token
+    if (percyToken) {
+        try {
+            const client = new PercyClient(config, { scope: "project" });
+            const builds = await client.get("/builds", {
+                "page[limit]": "1",
+            });
+            const buildList = Array.isArray(builds) ? builds : [];
+            if (buildList.length > 0) {
+                const proj = buildList[0]?.project?.name ||
+                    buildList[0]?.project?.slug ||
+                    "unknown";
+                output += `**Percy API (read):** ✓ Valid — project "${proj}"\n`;
+                output += `**Latest build:** #${buildList[0]?.buildNumber || buildList[0]?.id} (${buildList[0]?.state || "unknown"})\n`;
+            }
+            else {
+                output += `**Percy API (read):** ✓ Valid — no builds yet\n`;
+            }
+        }
+        catch {
+            // Read failed — token might be write-only (CI token)
+            output += `**Percy API (read):** ✗ No read access (this is normal for CI/write-only tokens)\n`;
+        }
+    }
+    // 2. Try BrowserStack API (project creation / token fetch)
+    if (hasBstackCreds) {
+        try {
+            const authString = getBrowserStackAuth(config);
+            const auth = Buffer.from(authString).toString("base64");
+            const response = await fetch("https://api.browserstack.com/api/app_percy/get_project_token?name=__mcp_auth_check__", {
+                headers: {
+                    Authorization: `Basic ${auth}`,
+                    "Content-Type": "application/json",
+                },
+            });
+            if (response.ok) {
+                output += `**BrowserStack API:** ✓ Valid — can create projects and get tokens\n`;
+            }
+            else {
+                output += `**BrowserStack API:** ✗ Failed (${response.status})\n`;
+            }
+        }
+        catch (e) {
+            output += `**BrowserStack API:** ✗ Error — ${e.message}\n`;
+        }
+    }
+    // 3. Org token check
+    if (orgToken) {
+        try {
+            const client = new PercyClient(config, { scope: "org" });
+            await client.get("/projects", { "page[limit]": "1" });
+            output += `**Org scope:** ✓ Valid\n`;
+        }
+        catch (e) {
+            output += `**Org scope:** ✗ Failed — ${e.message}\n`;
+        }
+    }
+    output += "\n";
+    // Capabilities summary
+    output += `### What You Can Do\n\n`;
+    if (hasBstackCreds) {
+        output += `✓ **Create projects** — \`percy_create_project\`\n`;
+        output += `✓ **Create builds with snapshots** — \`percy_create_percy_build\`\n`;
+    }
+    if (percyToken) {
+        const hasPrefix = percyToken.includes("_");
+        const prefix = hasPrefix ? percyToken.split("_")[0] : null;
+        if (prefix === "web" || prefix === "auto" || prefix === "app") {
+            output += `✓ **Read builds, snapshots, comparisons** — all read tools\n`;
+            output += `✓ **Approve/reject builds** — \`percy_approve_build\`\n`;
+            output += `✓ **AI analysis, RCA, summaries** — all intelligence tools\n`;
+            output += `✓ **PR visual report** — \`percy_pr_visual_report\`\n`;
+        }
+        else {
+            output += `⚠ **Limited read access** — this token can create builds but may not read them\n`;
+            output += `  Tip: Run \`percy_create_project\` to get a full-access \`web_*\` token\n`;
+        }
+    }
+    else if (hasBstackCreds) {
+        output += `⚠ **No PERCY_TOKEN set** — read operations will use BrowserStack fallback\n`;
+        output += `  Tip: Run \`percy_create_project\` to get a project token\n`;
+    }
+    if (!percyToken && !orgToken && !hasBstackCreds) {
+        output += `### Setup Required\n\n`;
+        output += `No credentials configured. Run:\n`;
+        output += `\`\`\`bash\ncd mcp-server && ./percy-config/setup.sh\n\`\`\`\n`;
+    }
+    return { content: [{ type: "text", text: output }] };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Percy build approval/rejection tool handler.
+ *
+ * Sends a review action (approve, request_changes, unapprove, reject)
+ * to the Percy Reviews API using JSON:API format.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyApproveBuild(args: {
+    build_id: string;
+    action: string;
+    snapshot_ids?: string;
+    reason?: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;

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

@@ -0,0 +1,97 @@
+/**
+ * Percy build approval/rejection tool handler.
+ *
+ * Sends a review action (approve, request_changes, unapprove, reject)
+ * to the Percy Reviews API using JSON:API format.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const VALID_ACTIONS = [
+    "approve",
+    "request_changes",
+    "unapprove",
+    "reject",
+];
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+export async function percyApproveBuild(args, config) {
+    const { build_id, action, snapshot_ids, reason } = args;
+    // Validate action
+    if (!VALID_ACTIONS.includes(action)) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Invalid action "${action}". Valid actions: ${VALID_ACTIONS.join(", ")}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // request_changes requires snapshot_ids (snapshot-level action)
+    if (action === "request_changes" && !snapshot_ids) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "request_changes requires snapshot_ids. This action works at snapshot level only.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Build JSON:API request body
+    const body = {
+        data: {
+            type: "reviews",
+            attributes: {
+                action,
+                ...(reason ? { reason } : {}),
+            },
+            relationships: {
+                build: {
+                    data: { type: "builds", id: build_id },
+                },
+                ...(snapshot_ids
+                    ? {
+                        snapshots: {
+                            data: snapshot_ids
+                                .split(",")
+                                .map((id) => id.trim())
+                                .filter(Boolean)
+                                .map((id) => ({ type: "snapshots", id })),
+                        },
+                    }
+                    : {}),
+            },
+        },
+    };
+    try {
+        const client = new PercyClient(config);
+        const result = (await client.post("/reviews", body));
+        const reviewState = result?.reviewState ?? result?.["review-state"] ?? action;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Build #${build_id} ${action} successful. Review state: ${reviewState}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to ${action} build #${build_id}: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}