Floto MCP Server

Model Context Protocol (MCP) server for Floto's visual testing and design QA tools. This server allows AI agents (like Claude or Gemini) to compare design images with implementation screenshots and provide detailed feedback.

Features

• Visual Comparison: Compare design mockups with actual implementation screenshots.
• Smart Analysis: AI-powered detection of visual discrepancies.
• Multi-Client Support: Seamless integration with Claude Desktop, Claude Code, and Gemini CLI.

Installation

Prerequisites

• Node.js (v18 or higher)
• A Floto API Key (Get one at test-app.floto.ai)

Setup

You can install and configure the MCP server using our CLI tool.

For Gemini CLI

npx @floto/mcp-server add --api-key YOUR_API_KEY --gemini

For Claude Desktop

npx @floto/mcp-server add --api-key YOUR_API_KEY --claude-desktop

For Claude Code

npx @floto/mcp-server add --api-key YOUR_API_KEY --claude-code

CLI Commands

The CLI tool supports the following commands:

| Command | Description | |---------|-------------| | add | Installs the MCP server for a specific client. | | status | Checks if the server is installed for a specific client. | | remove | Removes the server configuration for a specific client. | | help | Shows usage instructions. |

Options

| Flag | Description | |------|-------------| | --api-key <key> | Your Floto API Key (required for add). | | --claude-desktop | Target Claude Desktop application. | | --claude-code | Target Claude Code CLI tool. | | --gemini | Target Gemini CLI environment. |

Available Tools

compare_design

Compares a design mockup with an implementation screenshot using AI-powered visual analysis.

🚀 Automatic Workflow Integration: AI agents (like Claude Code) will automatically use this tool when implementing ANY UI features. This is REQUIRED behavior:

1. ✅ Auto-Added to Todo List: Visual testing is automatically included as the final step in UI implementation tasks
2. ✅ Proactive Prompting: After implementing components, the agent will ask for a screenshot
3. ✅ Automatic Execution: The tool runs without needing explicit user requests
4. ✅ Iterative Feedback: The agent reports differences and fixes them automatically

This is treated like running npm test or npm run build - it happens automatically as part of the workflow!

Image Input Formats: Each image can be provided in THREE ways (use exactly ONE per image):

Design Image:

• designImagePath (string): Absolute path to the design mockup file
• designImageUrl (string): URL to download the design image from
• designImageBase64 (string): Base64-encoded image data. Supports both data URL format and raw base64.

Implementation Image:

• implementationImagePath (string): Absolute path to the implementation screenshot
• implementationImageUrl (string): URL to download the screenshot from
• implementationImageBase64 (string): NEW! Base64-encoded image data

Comparison Settings:

• comparisonMode (string, optional): smart (default) or exact
  • smart: AI-powered semantic comparison (best for design review)
  • exact: Strict pixel-perfect comparison (best for regression testing)
• processingMode (string, optional): quality (default) or quick
  • quality: Thorough, high-resolution analysis
  • quick: Faster results, less detailed

Typical Workflow (Fully Automated):

1. User: "Implement this dashboard from Figma" + [Figma URL]
2. Agent: Fetches design from Figma (gets base64 image automatically)
3. Agent: Creates todo list with "Verify visual match" as final step
4. Agent: Implements components and styling
5. Agent: Marks implementation complete, moves to visual testing
6. Agent: "Let me verify this matches the design. Please provide a screenshot."
7. User: [provides screenshot path or uploads image]
8. Agent: Automatically calls compare_design with both images
9. Agent: Reports differences (if any) and offers to fix them
10. Agent: Iterates until visual match is achieved

Why This Matters:

• 🎯 Zero Missed Designs: Visual testing happens automatically, every time
• ⚡ Faster Iterations: Catch visual bugs immediately during development
• 🔄 Consistent Quality: Every UI implementation is verified against the design
• 📊 Detailed Feedback: Get AI-powered analysis of what's different and why

See VISUAL_TESTING_WORKFLOW.md for complete workflow documentation and best practices.

License

MIT