npm package: @floto/mcp-server
Description: Floto MCP server for visual testing and other tools
Author: Floto
Latest version: 0.2.8

# 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](https://test-app.floto.ai))

### Setup

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

#### For Gemini CLI
```bash
npx @floto/mcp-server add --api-key YOUR_API_KEY --gemini
```

#### For Claude Desktop
```bash
npx @floto/mcp-server add --api-key YOUR_API_KEY --claude-desktop
```

#### For Claude Code
```bash
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](./VISUAL_TESTING_WORKFLOW.md) for complete workflow documentation and best practices.

## License

MIT