accessibility.ts•14.6 kB
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { AccessibilityScanner } from "./accessiblity-utils/scanner.js";
import { AccessibilityReportFetcher } from "./accessiblity-utils/report-fetcher.js";
import { AccessibilityAuthConfig } from "./accessiblity-utils/auth-config.js";
import { trackMCP } from "../lib/instrumentation.js";
import { parseAccessibilityReportFromCSV } from "./accessiblity-utils/report-parser.js";
import { queryAccessibilityRAG } from "./accessiblity-utils/accessibility-rag.js";
import { getBrowserStackAuth } from "../lib/get-auth.js";
import { BrowserStackConfig } from "../lib/types.js";
import logger from "../logger.js";
interface AuthCredentials {
username: string;
password: string;
}
interface ScanProgressContext {
sendNotification: (notification: any) => Promise<void>;
_meta?: {
progressToken?: string | number;
};
}
interface FormAuthArgs {
name: string;
type: "form";
url: string;
username: string;
password: string;
usernameSelector: string;
passwordSelector: string;
submitSelector: string;
}
interface BasicAuthArgs {
name: string;
type: "basic";
url: string;
username: string;
password: string;
}
type AuthConfigArgs = FormAuthArgs | BasicAuthArgs;
function setupAuth(config: BrowserStackConfig): AuthCredentials {
const authString = getBrowserStackAuth(config);
const [username, password] = authString.split(":");
return { username, password };
}
function createErrorResponse(message: string, isError = true): CallToolResult {
return {
content: [
{
type: "text",
text: message,
isError,
},
],
isError,
};
}
function createSuccessResponse(messages: string[]): CallToolResult {
return {
content: messages.map((text) => ({
type: "text" as const,
text,
})),
};
}
function handleMCPError(
toolName: string,
server: McpServer,
config: BrowserStackConfig,
error: unknown,
): CallToolResult {
trackMCP(toolName, server.server.getClientVersion()!, error, config);
const errorMessage = error instanceof Error ? error.message : "Unknown error";
return createErrorResponse(
`Failed to ${toolName.replace(/([A-Z])/g, " $1").toLowerCase()}: ${errorMessage}. Please open an issue on GitHub if the problem persists`,
);
}
async function notifyScanProgress(
context: ScanProgressContext,
message: string,
progress = 0,
): Promise<void> {
await context.sendNotification({
method: "notifications/progress",
params: {
progressToken: context._meta?.progressToken?.toString() ?? "NOT_FOUND",
message,
progress,
total: 100,
},
});
}
async function initializeScanner(
config: BrowserStackConfig,
): Promise<AccessibilityScanner> {
const scanner = new AccessibilityScanner();
const auth = setupAuth(config);
scanner.setAuth(auth);
return scanner;
}
async function initializeReportFetcher(
config: BrowserStackConfig,
): Promise<AccessibilityReportFetcher> {
const reportFetcher = new AccessibilityReportFetcher();
const auth = setupAuth(config);
reportFetcher.setAuth(auth);
return reportFetcher;
}
async function executeAccessibilityRAG(
args: { query: string },
server: McpServer,
config: BrowserStackConfig,
): Promise<CallToolResult> {
try {
trackMCP(
"accessibilityExpert",
server.server.getClientVersion()!,
undefined,
config,
);
return await queryAccessibilityRAG(args.query, config);
} catch (error) {
return handleMCPError("accessibilityExpert", server, config, error);
}
}
async function executeFetchAccessibilityIssues(
args: { scanId: string; scanRunId: string; cursor?: number },
server: McpServer,
config: BrowserStackConfig,
): Promise<CallToolResult> {
try {
trackMCP(
"fetchAccessibilityIssues",
server.server.getClientVersion()!,
undefined,
config,
);
return await fetchAccessibilityIssues(
args.scanId,
args.scanRunId,
config,
args.cursor,
);
} catch (error) {
return handleMCPError("fetchAccessibilityIssues", server, config, error);
}
}
async function fetchAccessibilityIssues(
scanId: string,
scanRunId: string,
config: BrowserStackConfig,
cursor = 0,
): Promise<CallToolResult> {
const reportFetcher = await initializeReportFetcher(config);
const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
const { records, page_length, total_issues, next_page } =
await parseAccessibilityReportFromCSV(reportLink, { nextPage: cursor });
const currentlyShown =
cursor === 0
? page_length
: Math.floor(cursor / JSON.stringify(records[0] || {}).length) +
page_length;
const remainingIssues = total_issues - currentlyShown;
const messages = [
`Retrieved ${page_length} accessibility issues (Total: ${total_issues})`,
`Issues: ${JSON.stringify(records, null, 2)}`,
];
if (next_page !== null) {
messages.push(
`${remainingIssues} more issues available. Use fetchAccessibilityIssues with cursor: ${next_page} to get the next batch.`,
);
} else {
messages.push(`✅ All issues retrieved.`);
}
return createSuccessResponse(messages);
}
async function executeAccessibilityScan(
args: { name: string; pageURL: string; authConfigId?: number },
context: ScanProgressContext,
server: McpServer,
config: BrowserStackConfig,
): Promise<CallToolResult> {
try {
trackMCP(
"startAccessibilityScan",
server.server.getClientVersion()!,
undefined,
config,
);
return await runAccessibilityScan(
args.name,
args.pageURL,
context,
config,
args.authConfigId,
);
} catch (error) {
return handleMCPError("startAccessibilityScan", server, config, error);
}
}
function validateFormAuthArgs(args: AuthConfigArgs): args is FormAuthArgs {
return (
args.type === "form" &&
"usernameSelector" in args &&
"passwordSelector" in args &&
"submitSelector" in args &&
!!args.usernameSelector &&
!!args.passwordSelector &&
!!args.submitSelector
);
}
async function createAuthConfig(
args: AuthConfigArgs,
config: BrowserStackConfig,
): Promise<any> {
const authConfig = new AccessibilityAuthConfig();
const auth = setupAuth(config);
authConfig.setAuth(auth);
if (args.type === "form") {
if (!validateFormAuthArgs(args)) {
throw new Error(
"Form authentication requires usernameSelector, passwordSelector, and submitSelector",
);
}
return await authConfig.createFormAuthConfig(args.name, {
username: args.username,
usernameSelector: args.usernameSelector,
password: args.password,
passwordSelector: args.passwordSelector,
submitSelector: args.submitSelector,
url: args.url,
});
} else {
return await authConfig.createBasicAuthConfig(args.name, {
url: args.url,
username: args.username,
password: args.password,
});
}
}
async function executeCreateAuthConfig(
args: AuthConfigArgs,
server: McpServer,
config: BrowserStackConfig,
): Promise<CallToolResult> {
try {
trackMCP(
"createAccessibilityAuthConfig",
server.server.getClientVersion()!,
undefined,
config,
);
logger.info(`Creating auth config: ${JSON.stringify(args)}`);
const result = await createAuthConfig(args, config);
return createSuccessResponse([
`✅ Auth config "${args.name}" created successfully with ID: ${result.data?.id}`,
`Auth config details: ${JSON.stringify(result.data, null, 2)}`,
]);
} catch (error) {
if (
error instanceof Error &&
error.message.includes("Form authentication requires")
) {
return createErrorResponse(error.message);
}
return handleMCPError(
"createAccessibilityAuthConfig",
server,
config,
error,
);
}
}
async function executeGetAuthConfig(
args: { configId: number },
server: McpServer,
config: BrowserStackConfig,
): Promise<CallToolResult> {
try {
trackMCP(
"getAccessibilityAuthConfig",
server.server.getClientVersion()!,
undefined,
config,
);
const authConfig = new AccessibilityAuthConfig();
const auth = setupAuth(config);
authConfig.setAuth(auth);
const result = await authConfig.getAuthConfig(args.configId);
return createSuccessResponse([
`✅ Auth config retrieved successfully`,
`Auth config details: ${JSON.stringify(result.data, null, 2)}`,
]);
} catch (error) {
return handleMCPError("getAccessibilityAuthConfig", server, config, error);
}
}
function createScanFailureResponse(
name: string,
status: string,
): CallToolResult {
return createErrorResponse(
`❌ Accessibility scan "${name}" failed with status: ${status} , check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`,
);
}
function createScanSuccessResponse(
name: string,
totalIssues: number,
pageLength: number,
records: any[],
scanId: string,
scanRunId: string,
reportUrl: string,
cursor: number | null,
): CallToolResult {
const messages = [
`Accessibility scan "${name}" completed. check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`,
`Scan ID: ${scanId} and Scan Run ID: ${scanRunId}`,
`You can also download the full report from the following link: ${reportUrl}`,
`We found ${totalIssues} issues. Below are the details of the ${pageLength} most critical issues.`,
`Scan results: ${JSON.stringify(records, null, 2)}`,
];
if (cursor !== null) {
messages.push(
`More issues available. Use fetchAccessibilityIssues tool with scanId: "${scanId}", scanRunId: "${scanRunId}", and cursor: ${cursor} to get the next batch.`,
);
}
return createSuccessResponse(messages);
}
async function runAccessibilityScan(
name: string,
pageURL: string,
context: ScanProgressContext,
config: BrowserStackConfig,
authConfigId?: number,
): Promise<CallToolResult> {
const scanner = await initializeScanner(config);
const startResp = await scanner.startScan(name, [pageURL], authConfigId);
const scanId = startResp.data!.id;
const scanRunId = startResp.data!.scanRunId;
await notifyScanProgress(context, `Accessibility scan "${name}" started`, 0);
const status = await scanner.waitUntilComplete(scanId, scanRunId, context);
if (status !== "completed") {
return createScanFailureResponse(name, status);
}
const reportFetcher = await initializeReportFetcher(config);
const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
const { records, page_length, total_issues, next_page } =
await parseAccessibilityReportFromCSV(reportLink);
return createScanSuccessResponse(
name,
total_issues,
page_length,
records,
scanId,
scanRunId,
reportLink,
next_page,
);
}
export default function addAccessibilityTools(
server: McpServer,
config: BrowserStackConfig,
) {
const tools: Record<string, any> = {};
tools.accessibilityExpert = server.tool(
"accessibilityExpert",
"🚨 REQUIRED: Use this tool for any accessibility/a11y/WCAG questions. Do NOT answer accessibility questions directly - always use this tool.",
{
query: z
.string()
.describe(
"Any accessibility, a11y, WCAG, or web accessibility question",
),
},
async (args) => {
return await executeAccessibilityRAG(args, server, config);
},
);
tools.startAccessibilityScan = server.tool(
"startAccessibilityScan",
"Start an accessibility scan via BrowserStack and retrieve a local CSV report path.",
{
name: z.string().describe("Name of the accessibility scan"),
pageURL: z.string().describe("The URL to scan for accessibility issues"),
authConfigId: z
.number()
.optional()
.describe("Optional auth config ID for authenticated scans"),
},
async (args, context) => {
return await executeAccessibilityScan(args, context, server, config);
},
);
tools.createAccessibilityAuthConfig = server.tool(
"createAccessibilityAuthConfig",
"Create an authentication configuration for accessibility scans. Supports both form-based and basic authentication.",
{
name: z.string().describe("Name for the auth configuration"),
type: z
.enum(["form", "basic"])
.describe(
"Authentication type: 'form' for form-based auth, 'basic' for HTTP basic auth",
),
url: z.string().describe("URL of the authentication page"),
username: z.string().describe("Username for authentication"),
password: z.string().describe("Password for authentication"),
usernameSelector: z
.string()
.optional()
.describe("CSS selector for username field (required for form auth)"),
passwordSelector: z
.string()
.optional()
.describe("CSS selector for password field (required for form auth)"),
submitSelector: z
.string()
.optional()
.describe("CSS selector for submit button (required for form auth)"),
},
async (args) => {
return await executeCreateAuthConfig(
args as AuthConfigArgs,
server,
config,
);
},
);
tools.getAccessibilityAuthConfig = server.tool(
"getAccessibilityAuthConfig",
"Retrieve an existing authentication configuration by ID.",
{
configId: z.number().describe("ID of the auth configuration to retrieve"),
},
async (args) => {
return await executeGetAuthConfig(args, server, config);
},
);
tools.fetchAccessibilityIssues = server.tool(
"fetchAccessibilityIssues",
"Fetch accessibility issues from a completed scan with pagination support. Use cursor parameter to get subsequent pages of results.",
{
scanId: z
.string()
.describe("The scan ID from a completed accessibility scan"),
scanRunId: z
.string()
.describe("The scan run ID from a completed accessibility scan"),
cursor: z
.number()
.optional()
.describe("Character offset for pagination (default: 0)"),
},
async (args) => {
return await executeFetchAccessibilityIssues(args, server, config);
},
);
return tools;
}