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.
• Copy Audit: AI-powered review of UI copy & microcopy on a screen, with automatic brand-guideline (custom agent) routing.
• 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.

run_copy_audit

Runs an AI-powered copy & microcopy audit on a single screen/frame image and returns structured copy issues (unclear labels, inconsistent terminology, tone, grammar, CTA clarity, etc.), each with a severity, location, and suggested fix, plus an overall score and a link to the full report.

If the API key's account or team has a custom copy agent configured (brand voice & content guidelines), that agent runs automatically — you do not pass any agent ID. The response's summary.agent field names which agent produced the review.

Image Input (provide exactly ONE):

• imagePath (string): Absolute path to a PNG/JPG of the screen
• imageUrl (string): URL to download the image from
• imageBase64 (string): Base64-encoded image data (data URL or raw base64)
• name (string, optional): Label for the screen (defaults to the filename)

Returns:

{
  "summary": {
    "status": "completed",
    "overallScore": 82,
    "issuesFound": 3,
    "agent": "Copy Review"          // or your custom agent's name
  },
  "sessionId": "…",
  "reportUrl": "https://app.floto.ai/design-audit/…",
  "executiveSummary": "…",
  "issues": [
    {
      "id": "1",
      "severity": "Major",          // Critical | Major | Minor | Suggestion
      "location": "Primary CTA",
      "description": "…",
      "suggestion": "…",
      "rule": "…"                    // present only for custom-agent audits
    }
  ]
}

Example (Claude Code):

claude mcp add floto -- npx -y @floto/mcp-server
# then, with FLOTO_API_KEY set:
# "Run a copy audit on ./screens/checkout.png"

Or configure manually in .mcp.json:

{
  "mcpServers": {
    "floto": {
      "command": "npx",
      "args": ["-y", "@floto/mcp-server"],
      "env": { "FLOTO_API_KEY": "floto_..." }
    }
  }
}

License

MIT