Flows MCP Server

An MCP (Model Context Protocol) server that enables AI assistants like Claude to debug, analyze, and fix browser automation flows. Works both with real-time extension connection and offline via file-based storage.

What It Does

Core Use Case: "Why is my checkout flow failing?" → Claude analyzes failures, suggests fixes, and updates selectors automatically.

User runs flow in extension → fails
    ↓
Ask Claude: "Debug my checkout flow"
    ↓
Claude reads flow + results + elements from ~/.flows/
    ↓
Claude: "The 'Add to Cart' selector broke. Found 3 alternatives."
    ↓
Claude writes fix to ~/.flows/flows.json
    ↓
User reloads extension → runs flow → passes

Key Features

Offline Flow Analysis

Analyze and fix flows without the extension running. Data is stored in ~/.flows/:

• Flow definitions - All recorded flows with commands and selectors
• Execution results - Pass/fail status, error messages, screenshots
• Element library - Selector alternatives discovered during self-healing

AI-Powered Debugging

• Error analysis - Human-readable explanations for common failures (timeout, not found, intercepted, stale)
• Selector auditing - Score selectors for stability, flag brittle patterns (nth-child, deep nesting)
• Alternative suggestions - Find better selectors from element library or AI-healed results

Real-Time Sync

When both extension and MCP server are running:

• Execution results auto-sync after each run
• Flow changes sync bidirectionally
• WebSocket connection on ws://localhost:9222/flows-mcp

Tools Reference

Status & Sync

| Tool | Description | |------|-------------| | flows_status | Connection status, storage stats | | flows_sync | Export extension data to ~/.flows/ |

Read Operations

| Tool | Description | |------|-------------| | flows_list | List all flows with last result status | | flows_get | Get flow details and commands | | flows_get_results | Get execution results for a flow | | flows_get_elements | Get element library entries for a flow |

Analysis

| Tool | Description | |------|-------------| | flows_analyze | Analyze why a flow is failing, suggest fixes | | flows_analyze_selectors | Audit selector stability, identify brittle patterns |

Write Operations

| Tool | Description | |------|-------------| | flows_update | Update flow (rename, modify commands, etc.) | | flows_fix_selector | Apply a specific selector fix to a command | | flows_create | Create new flow from natural language description | | flows_delete | Delete a flow | | flows_run | Execute flow in browser (requires extension) |

Test Generation (NEW in v1.1.0)

| Tool | Description | |------|-------------| | flows_generate_test_data | Generate test data JSON (valid, invalid, boundary, injection values) | | flows_infer_assertions | Analyze flow for success/failure indicators (error selectors, success patterns) | | flows_convert_to_data_driven | Convert flow to use {{variables}} + conditional assertions | | flows_create_suite | Create test suites organized by category (smoke, regression, negative) | | flows_generate_comprehensive_tests | One-call orchestrator: generates complete test coverage |

Data-Driven Testing: Instead of creating N separate test flows, generate ONE flow with {{variable}} interpolation + test data file with N rows.

Conditional Assertions: The conditionalAssert command checks {{expected_outcome}} at runtime - verifying error indicators for negative tests, success indicators for positive tests.

BugBoard Integration

| Tool | Description | |------|-------------| | bugboard_configure | Set up API credentials | | bugboard_list_suites | List test suites in a project | | bugboard_get_test_cases | Get test cases from a suite | | bugboard_submit_result | Submit test execution results | | integration_sync_to_bugboard | Export flows as test cases | | integration_run_and_report | Run flows and submit results |

Installation

1. Build the MCP Server

cd mcp-server
npm install
npm run build

2. Configure Claude

Claude Code (Recommended)

Create a .mcp.json file in your project root for project-specific MCP servers:

# In your project directory (e.g., ~/Code/my-project/)
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "flows": {
      "command": "node",
      "args": ["/path/to/Chrome-Recorder/mcp-server/dist/index.js"]
    }
  }
}
EOF

Or add to global config (~/.claude/mcp.json) to use across all projects:

{
  "mcpServers": {
    "flows": {
      "command": "node",
      "args": ["/path/to/Chrome-Recorder/mcp-server/dist/index.js"]
    }
  }
}

Important: After adding the config, restart Claude Code to load the MCP server.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "flows": {
      "command": "node",
      "args": ["/path/to/Chrome-Recorder/mcp-server/dist/index.js"]
    }
  }
}

3. (Optional) Enable Real-Time Sync

1. Start the MCP server (listens on ws://localhost:9222/flows-mcp)
2. Open Flows extension → Settings → Enable "MCP Bridge"
3. Extension connects and syncs automatically

File Storage Structure

~/.flows/
├── flows.json          # All flow definitions
├── elements.json       # Element library (selectors + alternatives)
└── results/
    └── {flowId}.json   # Most recent execution result per flow

Flow Definition

{
  "id": "flow-abc123",
  "name": "Login Flow",
  "commands": [
    {
      "id": "cmd-1",
      "type": "click",
      "description": "Click login button",
      "target": {
        "css": "#login-btn",
        "testId": "login-button",
        "alternatives": [
          {"type": "css", "value": "[data-action='login']", "confidence": 0.85}
        ]
      }
    }
  ],
  "metadata": {
    "createdAt": "2024-01-15T10:30:00Z",
    "tags": ["auth", "smoke"]
  }
}

Execution Result

{
  "flowId": "flow-abc123",
  "status": "failed",
  "duration": 5230,
  "timestamp": "2024-01-15T14:22:00Z",
  "summary": {
    "totalCommands": 8,
    "passedCommands": 5,
    "failedCommands": 1,
    "passRate": 62.5
  },
  "failedCommand": {
    "commandId": "cmd-6",
    "commandIndex": 5,
    "type": "click",
    "selector": "#add-to-cart",
    "error": "Element not found after 10s timeout"
  },
  "screenshot": "base64..."
}

Example Interactions

Debug a Failing Flow

User: "Why is my login flow failing?"

Claude uses: flows_list
→ [{id: "login-123", name: "Login Flow", lastStatus: "failed"}]

Claude uses: flows_analyze {flowId: "login-123"}
→ {
    status: "failing",
    failure: {
      commandId: "cmd-3",
      error: "Element not found",
      analysis: "The selector could not find any matching elements..."
    },
    alternatives: [{
      commandId: "cmd-3",
      currentSelector: "#login-btn",
      alternatives: [
        {selector: "[data-testid='login']", confidence: 0.9, source: "element-library"}
      ]
    }],
    fixes: [{
      type: "selector",
      description: "Replace broken selector with alternative from element-library",
      suggestedValue: "[data-testid='login']",
      confidence: 0.9
    }]
  }

Claude: "Your login flow is failing at step 3 (Click login button).
The #login-btn selector can't find the element. I found a better
alternative in your element library: [data-testid='login'] with 90%
confidence. Want me to apply this fix?"

Audit Selector Quality

User: "Check the selectors in my checkout flow"

Claude uses: flows_analyze_selectors {flowId: "checkout-456"}
→ {
    overallScore: 65,
    analysis: [
      {
        command: "Click Add to Cart",
        selector: "div:nth-child(3) > button",
        issues: ["Uses positional selector (brittle)"],
        suggestions: ["Use data-testid or unique class"]
      },
      {
        command: "Enter Card Number",
        selector: "[data-testid='card-input']",
        goodPractices: ["Uses data-testid (stable)"]
      }
    ]
  }

Claude: "Your checkout flow scores 65/100 for selector stability.
The 'Add to Cart' step uses a brittle nth-child selector that will
break if the page layout changes. Consider adding data-testid='add-cart'
to that button."

Architecture

┌──────────────────────┐         ┌──────────────────────┐
│   Flows Extension    │         │     MCP Server       │
│                      │         │                      │
│  Exports on:         │         │  Components:         │
│  - Flow run complete │ ──────► │  - ExtensionBridge   │
│  - Flow save         │  files  │  - FileStorage       │
│  - Manual trigger    │         │  - FlowAnalyzer      │
│                      │         │  - ToolRegistry      │
│  Imports on:         │ ◄────── │  - FlowsTools        │
│  - Extension load    │  files  │                      │
│  - Manual trigger    │         │                      │
└──────────────────────┘         └──────────────────────┘
        │                                  │
        │    WebSocket (real-time sync)    │
        └──────────────────────────────────┘
              ws://localhost:9222/flows-mcp

Component Responsibilities

| Component | Purpose | |-----------|---------| | ExtensionBridge | WebSocket server, real-time sync, message routing | | FileStorage | Read/write ~/.flows/ with security (path traversal prevention) | | FlowAnalyzer | Failure analysis, selector auditing, alternative suggestions | | ToolRegistry | Open/Closed compliant tool dispatch | | FlowsTools | MCP tool implementations |

Development

# Install dependencies
npm install

# Build for production
npm run build

# Watch mode (development)
npm run dev

# Run tests
npm test

# Test coverage
npm test:coverage

# Start server directly
npm start

Test Coverage

72 unit tests covering:

• ToolRegistry - Registration, execution, helpers
• FileStorage - CRUD, JSON error handling, security
• FlowAnalyzer - Analysis, selector auditing, error explanations

Security

Authentication

The MCP server uses token-based authentication:

1. Auto-generated token - On first run, a secure token is created at ~/.flows/.auth-token
2. Extension configuration - Copy the token to Flows extension settings
3. Connection validation - Extension must provide valid token to connect

# View your auth token
cat ~/.flows/.auth-token

Security Features

| Feature | Description | |---------|-------------| | Token authentication | 64-char hex token, timing-safe comparison | | Localhost-only binding | Server binds to 127.0.0.1, rejecting remote connections | | Origin validation | Only accepts connections from chrome-extension:// origins | | Rate limiting | 100 requests/minute per client, prevents abuse | | Path traversal prevention | Flow IDs sanitized before file operations | | Input validation | All extension messages validated before processing | | File permissions | Auth token file created with 0600 (owner read/write only) |

Token Regeneration

If you suspect the token is compromised:

# Delete the token file - a new one will be generated on next server start
rm ~/.flows/.auth-token

License

MIT