accessflow-mcp-server 1.0.0

package/src/services/accessflow.ts

@@ -0,0 +1,9 @@
+export class AccessflowService {
+  private authCookie: string;
+
+  constructor(authCookie: string) {
+    this.authCookie = authCookie;
+  }
+
+  async fetchIssue(displayName: string, domain: string) {}
+}

package/src/tools/getIssueRemediation.ts

@@ -0,0 +1,218 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { ToolDefinition, ToolHandler, ToolContext } from "./types.js";
+
+export const getIssueRemediationDefinition: ToolDefinition = {
+  name: "getIssueRemediation",
+  description:
+    "Get detailed remediation guidance for an accessibility issue by issue display name",
+  inputSchema: {
+    type: "object",
+    properties: {
+      issueDisplayName: {
+        type: "string",
+        description:
+          "The accessibility issue display name (e.g., Decorative-Content-6d277a13ba)",
+      },
+    },
+    required: ["issueDisplayName"],
+  },
+};
+
+export const getIssueRemediationHandler: ToolHandler = async (
+  args,
+  context
+) => {
+  const { issueDisplayName } = args;
+  const { environment, headers } = context;
+
+  if (!issueDisplayName) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      "Issue display name is required"
+    );
+  }
+
+  let issue: any;
+
+  try {
+    const response = await fetch(
+      `${environment}/api/v6/mcp/${issueDisplayName}`,
+      {
+        method: "GET",
+        headers: headers,
+      }
+    );
+
+    if (!response.ok) {
+      if (response.status === 404) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `**Issue Not Found**\n\nNo accessibility issue found with display name: ${issueDisplayName}\n\nPlease verify the issue display name and try again.`,
+            },
+          ],
+        };
+      }
+
+      throw new McpError(
+        ErrorCode.InternalError,
+        `API request failed: ${response.status} ${response.statusText}`
+      );
+    }
+
+    issue = await response.json();
+  } catch (error) {
+    if (error instanceof McpError) {
+      throw error;
+    }
+
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Failed to fetch issue data: ${
+        error instanceof Error ? error.message : "Unknown error"
+      }`
+    );
+  }
+
+  if (!issue) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `**Issue Not Found**\n\nNo accessibility issue found with display name: ${issueDisplayName}\n\nPlease verify the issue display name and try again.`,
+        },
+      ],
+    };
+  }
+
+  // Find the related rule
+  // Handle MongoDB ObjectId - convert to string for comparison
+  let relatedRuleId = issue.relatedRuleId;
+
+  if (relatedRuleId && typeof relatedRuleId === "object") {
+    if (relatedRuleId.$oid) {
+      relatedRuleId = relatedRuleId.$oid;
+    } else if (
+      relatedRuleId.toString &&
+      typeof relatedRuleId.toString === "function"
+    ) {
+      relatedRuleId = relatedRuleId.toString();
+    }
+  }
+
+  const rule = relatedRuleId
+    ? context.rules.find((r) => r._id?.$oid === relatedRuleId)
+    : null;
+
+  // Format the remediation response
+  const response = formatRemediationResponse(issue, rule);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: response,
+      },
+    ],
+  };
+};
+
+function formatRemediationResponse(issue: any, rule: any = null): string {
+  // 1. Short summary of the problem
+  const summary =
+    rule?.shortDescription ||
+    `Accessibility issue detected: ${issue.displayName}`;
+
+  // 2. WCAG reference & severity
+  const wcagLevel = issue.WCAGLevel || "Unknown";
+  const severity = issue.severity?.toUpperCase() || "Unknown";
+  const criteria = issue.criteria || "Unknown";
+  const wcagLink = rule?.issueWCAGLink || "";
+
+  // 3. Code-level fix suggestions
+  let codeFix = "\n## Code-Level Fix\n\n";
+
+  if (rule) {
+    codeFix += rule.shortDescription
+      ? `**Solution:** ${rule.shortDescription}\n\n`
+      : "";
+
+    // Show the current problematic code
+    if (issue.HTML) {
+      codeFix += "**Current code:**\n```html\n" + issue.HTML + "\n```\n\n";
+    }
+
+    // Extract code examples from the HTML resolution if available
+    if (rule.issueResolution) {
+      const htmlResolution = rule.issueResolution;
+      const codeBlocks =
+        htmlResolution.match(/<pre[^>]*><code[^>]*>(.*?)<\/code><\/pre>/gs) ||
+        [];
+
+      if (codeBlocks.length > 0) {
+        // Extract and clean up code examples
+        codeBlocks.forEach((block: string, index: number) => {
+          const cleanCode = block
+            .replace(/<pre[^>]*><code[^>]*>/, "")
+            .replace(/<\/code><\/pre>/, "")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&amp;/g, "&")
+            .trim();
+
+          codeFix += `**Suggested fix ${
+            index + 1
+          }:**\n\`\`\`html\n${cleanCode}\n\`\`\`\n\n`;
+        });
+      }
+    }
+
+    // Add suggested fix details if available
+    if (rule.suggestedFix && rule.suggestedFix.length > 0) {
+      codeFix += "**Quick Fix Suggestions:**\n";
+      rule.suggestedFix.forEach((fix: any, index: number) => {
+        codeFix += `${index + 1}. **${fix.suggestedFixType}**: `;
+        if (fix.suggestedFixKey) {
+          codeFix += `Add attribute \`${fix.suggestedFixKey}="${fix.suggestedFixValue}"\`\n`;
+        } else {
+          codeFix += `${fix.suggestedFixValue}\n`;
+        }
+      });
+      codeFix += "\n";
+    }
+  } else {
+    codeFix += "No specific rule found for this issue.\n\n";
+  }
+
+  // 4. Links back to remediation panel
+  const remediationLinks = `
+## 📚 Additional Resources
+
+- **WCAG Reference:** ${
+    wcagLink
+      ? `[${wcagLevel} - ${criteria}](${wcagLink})`
+      : `${wcagLevel} - ${criteria}`
+  }
+- **Tutorial:** ${
+    rule?.issueTutorialLink || "Contact your AccessFlow administrator"
+  }
+- **Issue Location:** ${issue.webpath} (Selector: \`${issue.selector}\`)
+- **AccessFlow Panel:** View full remediation details in your AccessFlow dashboard
+
+---
+**Issue ID:** ${issue.displayName} | **Detected:** ${new Date(
+    issue.date?.$date || issue.modified?.$date || Date.now()
+  ).toLocaleDateString()} | **Confidence:** ${issue.confidence}%`;
+
+  return `# 🚨 ${summary}
+
+## 📊 WCAG Reference & Severity
+- **Severity:** ${severity}
+- **WCAG Level:** ${wcagLevel}
+- **Criteria:** ${criteria}
+- **Occurrences:** ${issue.occurrences} time(s) on this page
+${codeFix}
+${remediationLinks}`;
+}

package/src/tools/getMostUrgentIssues.ts

@@ -0,0 +1,144 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { ToolDefinition, ToolHandler, ToolContext } from "./types.js";
+
+export const getMostUrgentIssuesDefinition: ToolDefinition = {
+  name: "getMostUrgentIssues",
+  description:
+    "Get the most urgent accessibility issues as structured JSON data, ordered by severity (extreme > high > medium > low), then by site occurrences, then by page occurrences. Use the formatUrgentIssues prompt to format the JSON response into user-friendly markdown.",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    required: [],
+  },
+};
+
+export const getMostUrgentIssuesHandler: ToolHandler = async (
+  args,
+  context
+) => {
+  const { environment, headers } = context;
+
+  // Validate limit parameter
+  const issueLimit = 3;
+
+  try {
+    const response = await fetch(
+      `${environment}/api/v6/mcp/urgent-issues?limit=${issueLimit}`,
+      {
+        method: "GET",
+        headers: headers,
+      }
+    );
+
+    if (!response.ok) {
+      throw new McpError(
+        ErrorCode.InternalError,
+        `API request failed: ${response.status} ${response.statusText}`
+      );
+    }
+
+    const apiResponse = await response.json();
+
+    // Extract the issues array from the response
+    let issues: any[];
+    if (Array.isArray(apiResponse)) {
+      issues = apiResponse;
+    } else if (apiResponse && Array.isArray(apiResponse.issues)) {
+      issues = apiResponse.issues;
+    } else {
+      throw new McpError(
+        ErrorCode.InternalError,
+        `Invalid API response format. Expected array or object with 'issues' array. Received: ${JSON.stringify(
+          apiResponse,
+          null,
+          2
+        )}`
+      );
+    }
+
+    // The API returns issues already sorted by severity, site occurrences, and page occurrences
+    const sortedIssues = issues.slice(0, issueLimit);
+
+    if (sortedIssues.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                totalIssues: 0,
+                showing: 0,
+                issues: [],
+                hasMore: false,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    // Format the issues data for structured response
+    const formattedIssues = sortedIssues.map((issue: any, index: number) => ({
+      rank: index + 1,
+      displayName: issue.displayName,
+      severity: issue.severity?.toUpperCase() || "UNKNOWN",
+      severityEmoji: getSeverityEmoji(issue.severity),
+      wcagLevel: issue.WCAGLevel || "Unknown",
+      criteria: issue.criteria || "Unknown",
+      siteOccurrences: issue.siteOccurrences || 0,
+      pageOccurrences: issue.occurrences || 0,
+    }));
+
+    const responseData = {
+      totalIssues: issues.length,
+      showing: sortedIssues.length,
+      limit: issueLimit,
+      issues: formattedIssues,
+      hasMore: issues.length > issueLimit,
+      nextSteps: {
+        suggestion:
+          "Use getIssueRemediation with issueDisplayName for detailed fix guidance",
+        instructions:
+          "List to the user these issues with all the data for every one of them: severity, wcag, etc. For every issue, show the displayName to the user. After listing all the issues, suggest the user to get full issue remediation data. Do not fix the issues unless explicitly asked to fix",
+      },
+    };
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(responseData, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    if (error instanceof McpError) {
+      throw error;
+    }
+
+    // Enhanced error with more context
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown error";
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Failed to fetch urgent issues: ${errorMessage}. This may be due to an unexpected API response format or network issue.`
+    );
+  }
+};
+
+function getSeverityEmoji(severity: string): string {
+  switch (severity?.toLowerCase()) {
+    case "extreme":
+      return "🔴";
+    case "high":
+      return "🟠";
+    case "medium":
+      return "🟡";
+    case "low":
+      return "🟢";
+    default:
+      return "⚪";
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,33 @@
+import { ToolDefinition, ToolHandler } from "./types.js";
+import {
+  getIssueRemediationDefinition,
+  getIssueRemediationHandler,
+} from "./getIssueRemediation.js";
+import {
+  getMostUrgentIssuesDefinition,
+  getMostUrgentIssuesHandler,
+} from "./getMostUrgentIssues.js";
+
+export interface Tool {
+  definition: ToolDefinition;
+  handler: ToolHandler;
+}
+
+export const tools: Record<string, Tool> = {
+  getIssueRemediation: {
+    definition: getIssueRemediationDefinition,
+    handler: getIssueRemediationHandler,
+  },
+  getMostUrgentIssues: {
+    definition: getMostUrgentIssuesDefinition,
+    handler: getMostUrgentIssuesHandler,
+  },
+};
+
+export const getToolDefinitions = (): ToolDefinition[] => {
+  return Object.values(tools).map((tool) => tool.definition);
+};
+
+export const getToolHandler = (name: string): ToolHandler | undefined => {
+  return tools[name]?.handler;
+};

package/src/tools/types.ts

@@ -0,0 +1,20 @@
+export interface ToolContext {
+  rules: any[];
+  environment: string;
+  apiKey: string;
+  headers: Record<string, string>;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, any>;
+    required: string[];
+  };
+}
+
+export interface ToolHandler {
+  (args: any, context: ToolContext): Promise<any>;
+}

package/src/utils/domain.ts

@@ -0,0 +1,13 @@
+export function sanitizeDomain(domain: string): string {
+  if (!domain) {
+    return domain;
+  }
+
+  // Remove protocol (http:// or https://)
+  let sanitized = domain.replace(/^https?:\/\//, "");
+
+  // Remove trailing slash
+  sanitized = sanitized.replace(/\/$/, "");
+
+  return sanitized;
+}

package/test.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+
+/**
+ * Simple test script to verify the MCP server can start and respond
+ */
+async function testMCPServer() {
+  console.log("Testing AccessFlow MCP Server...\n");
+
+  // Test 1: Check if the server can be built
+  console.log("1. Building the server...");
+  try {
+    await execAsync("npm run build");
+    console.log("✅ Build successful\n");
+  } catch (error) {
+    console.error("❌ Build failed:", error);
+    return;
+  }
+
+  // Test 2: Check if required environment variables are set
+  console.log("2. Checking environment variables...");
+  if (!process.env.MONGO_URI) {
+    console.log("⚠️  MONGO_URI not set. Please set it for full functionality.");
+    console.log(
+      '   Example: export MONGO_URI="mongodb://localhost:27017/accessflow"'
+    );
+  } else {
+    console.log("✅ MONGO_URI is set");
+  }
+  console.log("");
+
+  // Test 3: Check if the server starts (just syntax check)
+  console.log("3. Checking server syntax...");
+  try {
+    // Quick syntax check by importing the module
+    const fs = await import("fs/promises");
+    const path = await import("path");
+
+    const serverPath = "./build/index.js";
+    const stats = await fs.stat(serverPath);
+    if (stats.isFile()) {
+      console.log("✅ Server file exists and is readable");
+    }
+  } catch (error) {
+    console.error("❌ Server file check failed:", error);
+    return;
+  }
+
+  console.log("\n🎉 Basic tests passed!");
+  console.log("\nNext steps:");
+  console.log("1. Set MONGO_URI environment variable");
+  console.log("2. Add the server to your VS Code MCP configuration");
+  console.log(
+    '3. Test with: @copilot /use accessflow getIssueRemediation issueDisplayName="AF-12345"'
+  );
+}
+
+// Run the tests
+testMCPServer().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node18",
+    "moduleResolution": "Node16",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "build"]
+}