autoflow-mcp 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autoflow (memrrizwan@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# ⚡ Autoflow MCP
+
+**Zero-Config AI Agent Automation for Google Flow via the Autoflow Chrome Extension.**
+
+Control [Google Flow](https://flow.google.com/) — image & video generation with **Veo 3.1**, **Nano Banana**, and **Imagen 4** — directly from your AI agent without browser flags, terminal profiles, or bot blocks.
+
+---
+
+## 🌟 Why Autoflow MCP?
+
+Traditional browser MCP servers require launching Chrome with `--remote-debugging-port=9222`, hunting down profile directories, closing personal browser windows, and dealing with Google bot detection.
+
+**Autoflow MCP eliminates all of that:**
+* **Zero Configuration**: No terminal flags or profile paths. It bridges directly to your everyday Chrome browser.
+* **100% Anti-Bot Immune**: Actions run inside your real, active Google session via the Autoflow extension.
+* **Cross-Platform**: Works identically on Windows, macOS, and Linux out of the box.
+* **Fast & Lightweight**: Zero headless browser overhead (< 15MB RAM).
+
+---
+
+## 🏗️ Architecture
+
+```
+┌───────────────────────────────┐
+│ AI Client (Claude / OpenCode) │
+└───────────────┬───────────────┘
+                │ Standard MCP Stdio
+                ▼
+┌───────────────────────────────┐
+│      Autoflow MCP Server      │
+│     (ws://127.0.0.1:19845)    │
+└───────────────┬───────────────┘
+                │ Local WebSocket RPC
+                ▼
+┌───────────────────────────────┐
+│   Autoflow Chrome Extension   │
+│  (Background Service Worker)  │
+└───────────────┬───────────────┘
+                │ Native DOM & CDP Automation
+                ▼
+┌───────────────────────────────┐
+│    Google Flow Web Studio     │
+│   (https://flow.google.com/)  │
+└───────────────────────────────┘
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Requirements
+* Google Chrome with the **Autoflow Extension** installed and enabled.
+* Node.js >= 18.
+
+### 2. Configure Your AI Agent
+
+Add **Autoflow MCP** to your AI client's configuration (Claude Desktop, OpenCode, Antigravity `mcp_config.json`, or Cursor):
+
+#### Using `npx` (Recommended for Users)
+```json
+{
+  "mcpServers": {
+    "autoflow": {
+      "command": "npx",
+      "args": ["-y", "autoflow-mcp"]
+    }
+  }
+}
+```
+
+#### Running from Local Repository
+```json
+{
+  "mcpServers": {
+    "autoflow": {
+      "command": "node",
+      "args": ["F:/google-flow-browser-mcp-main/src/index.js"]
+    }
+  }
+}
+```
+
+### 3. Start Generating!
+Just talk to your AI assistant:
+* *"Check if Autoflow and Google Flow are connected."*
+* *"Generate a cinematic drone shot of a neon cyberpunk city in 16:9 ratio using Veo 3.1."*
+* *"List the available characters in my current Flow project."*
+
+---
+
+## 🔧 Tools Included
+
+| Tool | Parameters | Description |
+| :--- | :--- | :--- |
+| `autoflow_status` | *(none)* | Checks extension and Google Flow tab connectivity. |
+| `autoflow_open_flow` | *(none)* | Opens `https://flow.google.com/` in an active tab. |
+| `autoflow_generate` | `prompt`, `mode`, `model`, `aspectRatio`, `outputCount`, `videoOption`, `characters` | Generates images or videos with Veo 3 or Nano Banana models. |
+| `autoflow_list_characters` | *(none)* | Scans all available `@` character tags in the open project. |
+| `autoflow_cancel` | `groupId` *(optional)* | Cancels any ongoing generation queue. |
+
+---
+
+## 🧪 Testing
+
+Run the automated bridge test suite:
+```bash
+npm test
+```

package/extension-bridge/mcp-bridge.js

@@ -0,0 +1,384 @@
+// Autoflow MCP WebSocket Bridge
+// Connects the extension's background service worker to the local Autoflow MCP server
+
+const MCP_WS_PORT = 19845;
+const MCP_WS_URL = `ws://127.0.0.1:${MCP_WS_PORT}`;
+const RECONNECT_DELAY_MS = 5000;
+
+let socket = null;
+let isConnected = false;
+let reconnectTimer = null;
+let activeJobs = new Map(); // requestId -> { resolve, reject, groupId }
+
+function log(...args) {
+  console.log('[Autoflow MCP Bridge]', ...args);
+}
+
+function warn(...args) {
+  console.warn('[Autoflow MCP Bridge]', ...args);
+}
+
+function error(...args) {
+  console.error('[Autoflow MCP Bridge]', ...args);
+}
+
+// Find existing Google Flow tab or return null
+async function getFlowTab() {
+  try {
+    const tabs = await chrome.tabs.query({
+      url: ['*://flow.google.com/*', '*://labs.google/*']
+    });
+    const tab = tabs.find(t => t.url && (t.url.includes('flow.google.com') || t.url.includes('labs.google'))) || null;
+    if (tab && tab.id) {
+      // Memory-Saver Shield: prevent Chrome from freezing/discarding this tab
+      try {
+        chrome.tabs.update(tab.id, { autoDiscardable: false });
+      } catch (e) {}
+    }
+    return tab;
+  } catch (err) {
+    warn('Error querying flow tabs:', err);
+    return null;
+  }
+}
+
+// Ensure Flow tab is open, protected from memory discarding, and ready
+async function ensureFlowTab(options = {}) {
+  const { makeActive = false } = options;
+  let tab = await getFlowTab();
+
+  if (tab && tab.id) {
+    // Check if the tab's window is minimized. If minimized, un-minimize to normal state without stealing focus
+    try {
+      const win = await chrome.windows.get(tab.windowId);
+      if (win.state === 'minimized') {
+        await chrome.windows.update(tab.windowId, { state: 'normal', focused: false });
+      }
+    } catch (e) {}
+
+    // Ensure tab cannot be discarded by Chrome Memory Saver
+    try {
+      await chrome.tabs.update(tab.id, { autoDiscardable: false, active: makeActive });
+    } catch (e) {}
+
+    return tab;
+  }
+
+  log('No active Flow tab found, opening https://flow.google.com/ in background...');
+  tab = await chrome.tabs.create({
+    url: 'https://flow.google.com/',
+    active: makeActive
+  });
+
+  // Protect from discard immediately
+  try {
+    chrome.tabs.update(tab.id, { autoDiscardable: false });
+  } catch (e) {}
+
+  // Wait up to 15 seconds for navigation
+  for (let i = 0; i < 30; i++) {
+    await new Promise(r => setTimeout(r, 500));
+    try {
+      const current = await chrome.tabs.get(tab.id);
+      if (current && current.status === 'complete') {
+        await new Promise(r => setTimeout(r, 1000));
+        return current;
+      }
+    } catch (e) {}
+  }
+  return tab;
+}
+
+// Verify content script readiness before dispatching commands
+async function waitForContentScript(tabId, maxWaitMs = 5000) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < maxWaitMs) {
+    try {
+      const response = await new Promise((resolve) => {
+        chrome.tabs.sendMessage(tabId, { type: 'CHECK_FLOW_PAGE' }, (res) => {
+          if (chrome.runtime.lastError) resolve(null);
+          else resolve(res);
+        });
+      });
+      if (response && response.isFlowPage) {
+        return true;
+      }
+    } catch (e) {}
+    await new Promise(r => setTimeout(r, 500));
+  }
+  return false;
+}
+
+// Send message to local MCP server
+function sendToMcp(payload) {
+  if (socket && socket.readyState === WebSocket.OPEN) {
+    socket.send(JSON.stringify(payload));
+  }
+}
+
+// Handle RPC calls from MCP Server
+async function handleRpcRequest(data) {
+  const { id, action, params = {} } = data;
+  if (!id || !action) return;
+
+  log(`Received RPC action: ${action} (id: ${id})`, params);
+
+  try {
+    switch (action) {
+      case 'STATUS': {
+        const flowTab = await getFlowTab();
+        sendToMcp({
+          id,
+          success: true,
+          connected: true,
+          flowTabActive: !!flowTab,
+          flowTabUrl: flowTab ? flowTab.url : null,
+          version: chrome.runtime.getManifest().version
+        });
+        break;
+      }
+
+      case 'OPEN_FLOW': {
+        const tab = await ensureFlowTab();
+        sendToMcp({
+          id,
+          success: true,
+          tabId: tab.id,
+          url: tab.url
+        });
+        break;
+      }
+
+      case 'SCAN_CHARACTERS': {
+        const tab = await ensureFlowTab();
+        chrome.tabs.sendMessage(tab.id, { type: 'SCAN_CHARACTERS' }, (response) => {
+          const err = chrome.runtime.lastError;
+          if (err) {
+            sendToMcp({ id, success: false, error: err.message, characters: [] });
+          } else {
+            sendToMcp({ id, success: true, characters: response?.characters || [] });
+          }
+        });
+        break;
+      }
+
+      case 'CANCEL': {
+        const tab = await getFlowTab();
+        if (!tab || !tab.id) {
+          sendToMcp({ id, success: false, error: 'No Flow tab found to cancel' });
+          return;
+        }
+        chrome.tabs.sendMessage(tab.id, {
+          type: 'CANCEL_PROMPT_GROUP',
+          groupId: params.groupId
+        }, (response) => {
+          sendToMcp({ id, success: true, response });
+        });
+        break;
+      }
+
+      case 'GENERATE': {
+        const tab = await ensureFlowTab({ makeActive: true });
+        if (!tab || !tab.id) {
+          sendToMcp({ id, success: false, error: 'Could not open or find Google Flow tab' });
+          return;
+        }
+
+        // Ensure content script is mounted and active
+        await waitForContentScript(tab.id, 6000);
+
+        const groupId = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+        const payload = {
+          prompt: params.prompt || '',
+          mode: params.mode || (params.prompt?.toLowerCase().includes('video') ? 'textToVideo' : 'textToImage'),
+          model: params.model || (params.mode?.includes('Video') ? 'Veo 3.1 - Fast' : 'Nano Banana 2'),
+          aspectRatio: params.aspectRatio || '16:9',
+          outputCount: params.outputCount || 1,
+          videoOption: params.videoOption || '4s',
+          characters: params.characters || [],
+          images: params.images || [],
+          autoDownloadResourceQuality: params.autoDownloadResourceQuality || '1080',
+          folderName: params.folderName || 'Autoflow_MCP',
+          promptIndex: 0,
+          groupId: groupId,
+          isConcat: false
+        };
+
+        activeJobs.set(groupId, { id, startTime: Date.now() });
+
+        // Dispatch AUTO_FILL_FLOW to content script
+        chrome.tabs.sendMessage(tab.id, {
+          type: 'AUTO_FILL_FLOW',
+          payloads: [payload],
+          groupId: groupId,
+          concurrentPrompts: 1,
+          promptDelaySecondsMin: 0,
+          promptDelaySecondsMax: 0
+        }, (res) => {
+          const lastErr = chrome.runtime.lastError;
+          if (lastErr) {
+            warn(`Failed to dispatch AUTO_FILL_FLOW for job ${groupId}:`, lastErr);
+            activeJobs.delete(groupId);
+            sendToMcp({ id, success: false, error: lastErr.message });
+          } else {
+            log(`AUTO_FILL_FLOW dispatched successfully for job ${groupId}`);
+          }
+        });
+        break;
+      }
+
+      default:
+        sendToMcp({
+          id,
+          success: false,
+          error: `Unknown action: ${action}`
+        });
+        break;
+    }
+  } catch (err) {
+    error(`Error handling RPC action ${action}:`, err);
+    sendToMcp({
+      id,
+      success: false,
+      error: err.message || String(err)
+    });
+  }
+}
+
+// Forward progress and completion events from content script to MCP
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (!message || !message.type) return;
+
+  if (message.type === 'VIDEO_GENERATION_PROGRESS') {
+    const { data } = message;
+    if (data && data.groupId && activeJobs.has(data.groupId)) {
+      const job = activeJobs.get(data.groupId);
+      sendToMcp({
+        type: 'PROGRESS',
+        id: job.id,
+        percentage: data.percentage,
+        status: data.status,
+        prompt: data.prompt
+      });
+    }
+  } else if (message.type === 'PROMPT_GROUP_STATUS') {
+    const { data } = message;
+    if (data && data.id && activeJobs.has(data.id)) {
+      const job = activeJobs.get(data.id);
+      if (data.status === 'completed' || data.status === 'error' || data.status === 'cancelled') {
+        activeJobs.delete(data.id);
+        sendToMcp({
+          id: job.id,
+          success: data.status === 'completed',
+          status: data.status,
+          results: data.results,
+          totalCount: data.totalCount,
+          processedCount: data.processedCount
+        });
+      } else {
+        // In-progress status update
+        sendToMcp({
+          type: 'STATUS_UPDATE',
+          id: job.id,
+          status: data.status,
+          processedCount: data.processedCount,
+          totalCount: data.totalCount
+        });
+      }
+    }
+  } else if (message.type === 'GET_MCP_STATUS') {
+    sendResponse({ connected: isConnected, url: MCP_WS_URL, port: MCP_WS_PORT });
+    return true;
+  }
+});
+
+// Initialize WebSocket connection to local MCP server
+export function initMcpBridge() {
+  if (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)) {
+    return;
+  }
+
+  try {
+    socket = new WebSocket(MCP_WS_URL);
+
+    socket.onopen = () => {
+      isConnected = true;
+      log(`Connected to Autoflow MCP Server at ${MCP_WS_URL}`);
+      try {
+        chrome.storage.local.set({ mcp_connected: true, mcp_port: MCP_WS_PORT, mcp_last_seen: Date.now() });
+      } catch (e) {}
+
+      if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+      }
+      sendToMcp({
+        type: 'EXTENSION_HELLO',
+        name: 'Autoflow Extension',
+        version: chrome.runtime.getManifest().version,
+        extensionId: chrome.runtime.id,
+        timestamp: Date.now()
+      });
+    };
+
+    socket.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        handleRpcRequest(data);
+      } catch (err) {
+        warn('Invalid message received from MCP server:', event.data);
+      }
+    };
+
+    socket.onclose = () => {
+      if (isConnected) {
+        log('Disconnected from Autoflow MCP Server. Will attempt reconnect...');
+      }
+      isConnected = false;
+      try {
+        chrome.storage.local.set({ mcp_connected: false });
+      } catch (e) {}
+      scheduleReconnect();
+    };
+
+    socket.onerror = () => {
+      // Quietly handle connection errors (server may not be running yet)
+      isConnected = false;
+      try {
+        chrome.storage.local.set({ mcp_connected: false });
+      } catch (e) {}
+    };
+  } catch (err) {
+    scheduleReconnect();
+  }
+}
+
+function scheduleReconnect() {
+  if (reconnectTimer) return;
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    initMcpBridge();
+  }, RECONNECT_DELAY_MS);
+}
+
+// Keep-alive alarm and tab triggers for Manifest V3 lifecycle
+try {
+  chrome.alarms.create('autoflow_mcp_keepalive', { periodInMinutes: 1 });
+  chrome.alarms.onAlarm.addListener((alarm) => {
+    if (alarm.name === 'autoflow_mcp_keepalive') {
+      initMcpBridge();
+    }
+  });
+
+  chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
+    if (changeInfo.status === 'complete' && tab.url && (tab.url.includes('flow.google.com') || tab.url.includes('labs.google'))) {
+      initMcpBridge();
+    }
+  });
+} catch (e) {
+  // Ignore in environments where alarms/tabs might be restricted
+}
+
+// Start bridge
+initMcpBridge();
+

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "autoflow-mcp",
+  "version": "2.0.0",
+  "description": "Zero-config Model Context Protocol (MCP) server for Google Flow via Autoflow Chrome Extension",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "autoflow-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "extension-bridge",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node test-bridge.mjs && node test-queue.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "google-flow",
+    "veo",
+    "veo-3",
+    "nano-banana",
+    "imagen",
+    "ai-agent",
+    "claude",
+    "opencode",
+    "chrome-extension"
+  ],
+  "author": "Rizwan <memrrizwan@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/bridge/ws-server.js

@@ -0,0 +1,159 @@
+import { WebSocketServer, WebSocket } from 'ws';
+
+const DEFAULT_PORT = 19845;
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_TIMEOUT_MS = 600000; // 10 minutes default for video generation
+
+let wss = null;
+let activeSocket = null;
+let extensionInfo = null;
+const pendingRequests = new Map();
+
+export function startBridgeServer(port = process.env.AUTOFLOW_PORT || DEFAULT_PORT) {
+  if (wss) {
+    return { wss, port };
+  }
+
+  const numericPort = Number(port);
+
+  wss = new WebSocketServer({
+    port: numericPort,
+    host: DEFAULT_HOST
+  });
+
+  wss.on('listening', () => {
+    // Note: Use stderr for logging so stdout remains clean for MCP stdio protocol
+    console.error(`[Autoflow Bridge] WebSocket server listening on ws://${DEFAULT_HOST}:${numericPort}`);
+  });
+
+  wss.on('connection', (ws) => {
+    console.error('[Autoflow Bridge] Chrome Extension connected');
+    activeSocket = ws;
+
+    ws.on('message', (raw) => {
+      try {
+        const message = JSON.parse(raw.toString());
+        handleExtensionMessage(message);
+      } catch (err) {
+        console.error('[Autoflow Bridge] Failed to parse message from extension:', err);
+      }
+    });
+
+    ws.on('close', () => {
+      console.error('[Autoflow Bridge] Chrome Extension disconnected');
+      if (activeSocket === ws) {
+        activeSocket = null;
+        extensionInfo = null;
+      }
+    });
+
+    ws.on('error', (err) => {
+      console.error('[Autoflow Bridge] Socket error:', err.message);
+    });
+  });
+
+  wss.on('error', (err) => {
+    console.error('[Autoflow Bridge] Server error:', err.message);
+  });
+
+  return { wss, port: numericPort };
+}
+
+function handleExtensionMessage(message) {
+  if (!message) return;
+
+  // Extension Handshake
+  if (message.type === 'EXTENSION_HELLO') {
+    extensionInfo = {
+      name: message.name,
+      version: message.version,
+      extensionId: message.extensionId,
+      connectedAt: new Date().toISOString()
+    };
+    console.error(`[Autoflow Bridge] Extension identified: ${message.name} v${message.version}`);
+    return;
+  }
+
+  // Progress streaming
+  if (message.type === 'PROGRESS' || message.type === 'STATUS_UPDATE') {
+    const pending = pendingRequests.get(message.id);
+    if (pending && typeof pending.onProgress === 'function') {
+      pending.onProgress(message);
+    }
+    return;
+  }
+
+  // Response to an RPC call
+  if (message.id && pendingRequests.has(message.id)) {
+    const { resolve, reject, timeoutTimer } = pendingRequests.get(message.id);
+    clearTimeout(timeoutTimer);
+    pendingRequests.delete(message.id);
+
+    if (message.success) {
+      resolve(message);
+    } else {
+      reject(new Error(message.error || 'Unknown error occurred in extension'));
+    }
+  }
+}
+
+export function isExtensionConnected() {
+  return activeSocket !== null && activeSocket.readyState === WebSocket.OPEN;
+}
+
+export function getExtensionInfo() {
+  return {
+    connected: isExtensionConnected(),
+    info: extensionInfo
+  };
+}
+
+export function sendRpc(action, params = {}, options = {}) {
+  return new Promise((resolve, reject) => {
+    if (!isExtensionConnected()) {
+      return reject(new Error(
+        'Autoflow Chrome Extension is not connected. Please ensure Google Chrome is open with the Autoflow extension active.'
+      ));
+    }
+
+    const id = `mcp_req_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+    const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+
+    const timeoutTimer = setTimeout(() => {
+      if (pendingRequests.has(id)) {
+        pendingRequests.delete(id);
+        reject(new Error(`Autoflow request '${action}' timed out after ${timeoutMs / 1000}s`));
+      }
+    }, timeoutMs);
+
+    pendingRequests.set(id, {
+      resolve,
+      reject,
+      timeoutTimer,
+      onProgress: options.onProgress
+    });
+
+    const payload = JSON.stringify({
+      id,
+      action,
+      params
+    });
+
+    activeSocket.send(payload, (err) => {
+      if (err) {
+        clearTimeout(timeoutTimer);
+        pendingRequests.delete(id);
+        reject(new Error(`Failed to send command to extension: ${err.message}`));
+      }
+    });
+  });
+}
+
+export function closeBridgeServer() {
+  if (wss) {
+    wss.close();
+    wss = null;
+    activeSocket = null;
+    extensionInfo = null;
+  }
+}

package/src/index.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  startBridgeServer,
+  isExtensionConnected,
+  getExtensionInfo,
+  sendRpc
+} from './bridge/ws-server.js';
+import { jobQueue } from './queue/mcp-queue.js';
+
+// Start the local WebSocket Bridge for the Autoflow Chrome Extension
+const port = process.env.AUTOFLOW_PORT || 19845;
+startBridgeServer(port);
+
+// Initialize MCP Server
+const server = new Server(
+  {
+    name: 'autoflow-mcp',
+    version: '2.0.0'
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+
+const TOOL_DEFINITIONS = [
+  {
+    name: 'autoflow_status',
+    description: 'Check the connection status of the Autoflow Chrome Extension and Google Flow tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'autoflow_open_flow',
+    description: 'Instruct the Autoflow extension to open Google Flow (https://flow.google.com/) in an active browser tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'autoflow_get_queue',
+    description: 'Inspect the current status of the Autoflow sequential job queue (active job, pending jobs, and recent history).',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'autoflow_generate',
+    description: 'Generate an AI video or image on Google Flow using Veo 3 or Nano Banana models via the Autoflow extension (queued sequentially).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: {
+          type: 'string',
+          description: 'The creative prompt for the image or video generation.'
+        },
+        mode: {
+          type: 'string',
+          description: 'Generation mode: textToVideo, imageToVideo, textToImage, imageToImage.',
+          enum: ['textToVideo', 'imageToVideo', 'textToImage', 'imageToImage']
+        },
+        model: {
+          type: 'string',
+          description: 'AI model to use (e.g. "Veo 3.1 - Fast", "Veo 3.1 - Quality", "Nano Banana 2", "Imagen 4").'
+        },
+        aspectRatio: {
+          type: 'string',
+          description: 'Aspect ratio: "16:9", "9:16", "1:1", "4:3", "3:4".',
+          enum: ['16:9', '9:16', '1:1', '4:3', '3:4']
+        },
+        outputCount: {
+          type: 'number',
+          description: 'Number of outputs to generate (1, 2, or 4). Default is 1.',
+          enum: [1, 2, 4]
+        },
+        videoOption: {
+          type: 'string',
+          description: 'Duration for video: "4s", "6s", "8s", "10s".',
+          enum: ['4s', '6s', '8s', '10s']
+        },
+        characters: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of character names to automatically mention with @ in the prompt.'
+        },
+        autoDownloadResourceQuality: {
+          type: 'string',
+          description: 'Download quality: "1080", "2k", "4k", or "no-download".',
+          enum: ['1080', '2k', '4k', 'no-download']
+        },
+        folderName: {
+          type: 'string',
+          description: 'Folder name where downloaded files should be saved.'
+        }
+      },
+      required: ['prompt']
+    }
+  },
+  {
+    name: 'autoflow_list_characters',
+    description: 'Scan and list all available character tags in the currently open Google Flow project.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'autoflow_cancel',
+    description: 'Cancel any running or queued generation job in Google Flow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        jobId: {
+          type: 'string',
+          description: 'Optional job ID to cancel. If omitted, cancels the currently active job.'
+        }
+      }
+    }
+  }
+];
+
+// Register list of tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOL_DEFINITIONS };
+});
+
+// Handle tool execution requests
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    switch (name) {
+      case 'autoflow_status': {
+        if (!isExtensionConnected()) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    status: 'disconnected',
+                    extensionConnected: false,
+                    message: 'Autoflow Chrome Extension is not connected. Please ensure Google Chrome is open with the Autoflow extension active.'
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+
+        const extStatus = await sendRpc('STATUS', {}, { timeoutMs: 10000 });
+        const info = getExtensionInfo();
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  status: 'connected',
+                  extensionConnected: true,
+                  extension: info.info,
+                  flow: extStatus,
+                  queue: jobQueue.getQueueState()
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+
+      case 'autoflow_open_flow': {
+        const result = await sendRpc('OPEN_FLOW', {}, { timeoutMs: 15000 });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      }
+
+      case 'autoflow_get_queue': {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(jobQueue.getQueueState(), null, 2)
+            }
+          ]
+        };
+      }
+
+      case 'autoflow_generate': {
+        const prompt = args.prompt;
+        const isVideo = args.mode?.includes('Video') ||
+          (!args.mode && (prompt.toLowerCase().includes('video') || prompt.toLowerCase().includes('shot') || prompt.toLowerCase().includes('cinematic')));
+
+        const defaultMode = isVideo ? 'textToVideo' : 'textToImage';
+        const defaultModel = isVideo ? 'Veo 3.1 - Fast' : 'Nano Banana 2';
+
+        const params = {
+          prompt,
+          mode: args.mode || defaultMode,
+          model: args.model || defaultModel,
+          aspectRatio: args.aspectRatio || '16:9',
+          outputCount: args.outputCount || 1,
+          videoOption: args.videoOption || '4s',
+          characters: args.characters || [],
+          autoDownloadResourceQuality: args.autoDownloadResourceQuality || '1080',
+          folderName: args.folderName || 'Autoflow_MCP'
+        };
+
+        // Route through the sequential FIFO queue to prevent collisions
+        const result = await jobQueue.enqueue(params);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      }
+
+      case 'autoflow_list_characters': {
+        const result = await sendRpc('SCAN_CHARACTERS', {}, { timeoutMs: 20000 });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      }
+
+      case 'autoflow_cancel': {
+        const result = await jobQueue.cancel(args.jobId || args.groupId);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      }
+
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Tool '${name}' not found.`);
+    }
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              error: err.message || String(err),
+              suggestion: !isExtensionConnected()
+                ? 'Open Google Chrome and verify the Autoflow extension is active.'
+                : 'Ensure a tab with https://flow.google.com/ is open.'
+            },
+            null,
+            2
+          )
+        }
+      ],
+      isError: true
+    };
+  }
+});
+
+// Run MCP Stdio transport
+async function run() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[Autoflow MCP] Server started and listening via stdio.');
+}
+
+run().catch((err) => {
+  console.error('[Autoflow MCP] Fatal error starting server:', err);
+  process.exit(1);
+});

package/src/queue/mcp-queue.js

@@ -0,0 +1,162 @@
+import { sendRpc, isExtensionConnected } from '../bridge/ws-server.js';
+
+export class McpJobQueue {
+  constructor() {
+    this.queue = [];
+    this.activeJob = null;
+    this.history = [];
+    this.isProcessing = false;
+  }
+
+  // Enqueue a new generation job with strict sequential FIFO processing
+  enqueue(params) {
+    const id = `job_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+    const job = {
+      id,
+      prompt: params.prompt,
+      params,
+      status: 'queued',
+      progress: 0,
+      progressStatus: 'queued',
+      createdAt: new Date().toISOString(),
+      startedAt: null,
+      completedAt: null,
+      result: null,
+      error: null
+    };
+
+    const promise = new Promise((resolve, reject) => {
+      job.resolve = resolve;
+      job.reject = reject;
+    });
+
+    this.queue.push(job);
+    console.error(`[Autoflow Queue] Enqueued job ${id} ("${params.prompt.substring(0, 40)}..."). Queue depth: ${this.queue.length}`);
+    this.processNext();
+
+    return promise;
+  }
+
+  async processNext() {
+    if (this.isProcessing || this.queue.length === 0) {
+      return;
+    }
+
+    this.isProcessing = true;
+    this.activeJob = this.queue.shift();
+    this.activeJob.status = 'running';
+    this.activeJob.startedAt = new Date().toISOString();
+
+    console.error(`[Autoflow Queue] Processing job ${this.activeJob.id}: "${this.activeJob.prompt.substring(0, 40)}..."`);
+
+    try {
+      const result = await sendRpc('GENERATE', this.activeJob.params, {
+        timeoutMs: 600000, // 10 minute timeout
+        onProgress: (prog) => {
+          if (this.activeJob) {
+            this.activeJob.progress = prog.percentage || this.activeJob.progress;
+            this.activeJob.progressStatus = prog.status || 'generating';
+          }
+        }
+      });
+
+      this.activeJob.status = 'completed';
+      this.activeJob.completedAt = new Date().toISOString();
+      this.activeJob.progress = 100;
+      this.activeJob.result = result;
+
+      this.addToHistory(this.activeJob);
+      this.activeJob.resolve(result);
+    } catch (err) {
+      console.error(`[Autoflow Queue] Job ${this.activeJob.id} failed:`, err.message);
+      this.activeJob.status = 'failed';
+      this.activeJob.completedAt = new Date().toISOString();
+      this.activeJob.error = err.message;
+
+      this.addToHistory(this.activeJob);
+      this.activeJob.reject(err);
+    } finally {
+      this.activeJob = null;
+      this.isProcessing = false;
+      this.processNext();
+    }
+  }
+
+  // Cancel an active or pending job
+  async cancel(jobId) {
+    // If no jobId specified, cancel active job or first pending
+    if (!jobId && this.activeJob) {
+      jobId = this.activeJob.id;
+    }
+
+    if (this.activeJob && this.activeJob.id === jobId) {
+      console.error(`[Autoflow Queue] Cancelling active job ${jobId}`);
+      try {
+        await sendRpc('CANCEL', { groupId: this.activeJob.id });
+      } catch (e) {}
+
+      this.activeJob.status = 'cancelled';
+      this.activeJob.completedAt = new Date().toISOString();
+      this.activeJob.error = 'Cancelled by user';
+      this.addToHistory(this.activeJob);
+      this.activeJob.reject(new Error('Job was cancelled'));
+
+      this.activeJob = null;
+      this.isProcessing = false;
+      this.processNext();
+      return { success: true, message: `Active job ${jobId} cancelled` };
+    }
+
+    const index = this.queue.findIndex(j => j.id === jobId);
+    if (index !== -1) {
+      const [removed] = this.queue.splice(index, 1);
+      removed.status = 'cancelled';
+      removed.completedAt = new Date().toISOString();
+      removed.error = 'Cancelled before execution';
+      this.addToHistory(removed);
+      removed.reject(new Error('Job was cancelled from queue'));
+      return { success: true, message: `Queued job ${jobId} cancelled` };
+    }
+
+    return { success: false, message: `Job ${jobId || 'current'} not found` };
+  }
+
+  addToHistory(job) {
+    this.history.unshift({
+      id: job.id,
+      prompt: job.prompt,
+      status: job.status,
+      createdAt: job.createdAt,
+      startedAt: job.startedAt,
+      completedAt: job.completedAt,
+      progress: job.progress,
+      error: job.error
+    });
+
+    if (this.history.length > 20) {
+      this.history.pop();
+    }
+  }
+
+  getQueueState() {
+    return {
+      activeJob: this.activeJob ? {
+        id: this.activeJob.id,
+        prompt: this.activeJob.prompt,
+        status: this.activeJob.status,
+        progress: this.activeJob.progress,
+        progressStatus: this.activeJob.progressStatus,
+        startedAt: this.activeJob.startedAt
+      } : null,
+      queueLength: this.queue.length,
+      pendingJobs: this.queue.map(j => ({
+        id: j.id,
+        prompt: j.prompt,
+        createdAt: j.createdAt
+      })),
+      recentHistory: this.history.slice(0, 5)
+    };
+  }
+}
+
+export const jobQueue = new McpJobQueue();