mcp-uimax

Instructions

Implementation Reference

• src/server.ts:33-137 (handler)

  The `review_ui` tool is defined in `src/server.ts` using the MCP `server.tool` method. Its handler calls `runFullReview` to collect data and then returns a structured response containing screenshot, audit reports, and an expert prompt.

    server.tool(
      "review_ui",
      `THE PRIMARY TOOL — Fully automated UI review pipeline. Captures a screenshot, runs accessibility/performance/code audits, then returns ALL data along with an expert frontend review methodology so you can generate a comprehensive review and implement fixes.
  
  Use this when the user asks to "review my UI", "audit my frontend", or "find UI issues". After receiving the results, you MUST:
  1. Study the screenshot carefully for visual/UX issues
  2. Analyze the audit data following the expert methodology provided
  3. Generate a comprehensive review with SPECIFIC fixes (exact CSS values, code changes)
  4. Implement the fixes directly in the codebase
  
  This tool is FREE — it runs entirely within Claude Code using the user's existing plan. No API keys needed.`,
      {
        url: z.string().url().describe("URL of the running application (e.g., http://localhost:3000)"),
        codeDirectory: z.string().describe("Absolute path to the frontend source directory (e.g., /Users/me/project/src)"),
        width: z.number().optional().default(1440).describe("Viewport width in pixels"),
        height: z.number().optional().default(900).describe("Viewport height in pixels"),
      },
      async ({ url, codeDirectory, width, height }) => {
        try {
          // Collect all audit data
          const auditData = await runFullReview(url, codeDirectory, {
            width: width ?? 1440,
            height: height ?? 900,
          });
  
          const auditReport = formatFullReviewReport(auditData);
  
          // Return screenshot + data + expert prompt to Claude Code
          // Claude Code (on the user's Pro plan) generates the expert review itself
          return {
            content: [
              {
                type: "text" as const,
                text: [
                  `# UIMax Data Collection Complete`,
                  ``,
                  `**URL:** ${url}`,
                  `**Code Directory:** ${codeDirectory}`,
                  `**Timestamp:** ${auditData.timestamp}`,
                  `**Accessibility violations:** ${auditData.accessibility.violations.length}`,
                  `**Accessibility passes:** ${auditData.accessibility.passes}`,
                  `**Load time:** ${auditData.performance.loadTime.toFixed(0)}ms`,
                  `**DOM nodes:** ${auditData.performance.domNodes}`,
                  `**Code files analyzed:** ${auditData.codeAnalysis.totalFiles}`,
                  `**Code findings:** ${auditData.codeAnalysis.findings.length}`,
                  `**Framework detected:** ${auditData.codeAnalysis.framework}`,
                  ...(auditData.lighthouse
                    ? [
                        `**Lighthouse Performance:** ${auditData.lighthouse.scores.performance ?? "N/A"}`,
                        `**Lighthouse Accessibility:** ${auditData.lighthouse.scores.accessibility ?? "N/A"}`,
                        `**Lighthouse Best Practices:** ${auditData.lighthouse.scores.bestPractices ?? "N/A"}`,
                        `**Lighthouse SEO:** ${auditData.lighthouse.scores.seo ?? "N/A"}`,
                      ]
                    : [`**Lighthouse:** skipped (timed out or unavailable)`]),
                  ``,
                  `---`,
                  ``,
                  `## Screenshot of the live UI — study this carefully:`,
                ].join("\n"),
              },
              {
                type: "image" as const,
                data: auditData.screenshot.base64,
                mimeType: auditData.screenshot.mimeType,
              },
              {
                type: "text" as const,
                text: [
                  ``,
                  `---`,
                  ``,
                  auditReport,
                  ``,
                  `---`,
                  ``,
                  `# Expert Review Instructions`,
                  ``,
                  `You now have everything you need. Follow the methodology below to generate a comprehensive expert UI review, then implement every fix.`,
                  ``,
                  UI_REVIEW_PROMPT,
                  ``,
                  `---`,
                  ``,
                  `# Implementation Instructions`,
                  ``,
                  `After generating your review, IMMEDIATELY implement the fixes:`,
                  `1. Start with CRITICAL severity findings`,
                  `2. Then HIGH, MEDIUM, LOW in order`,
                  `3. For each finding, locate the exact file and apply the specific code change`,
                  `4. After implementing all fixes, provide a summary of what was changed`,
                  ``,
                  `DO NOT just list the findings — actually edit the code files and fix them.`,
                ].join("\n"),
              },
            ],
          };
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          return {
            content: [{ type: "text" as const, text: `UI review failed: ${message}` }],
            isError: true,
          };
        }
      }
    );