e2e-pilot 0.0.69

package/src/mcp.ts

@@ -0,0 +1,876 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { Page, Browser, BrowserContext, chromium } from 'playwright-core'
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import dedent from 'string-dedent'
+import {
+  getCdpUrl,
+  LOG_FILE_PATH,
+  VERSION,
+  sleep,
+  RELAY_PORT,
+  getServerVersion,
+  setDeviceScaleFactorForMacOS,
+  preserveSystemColorScheme,
+  formatAsCommentLines,
+  formatDateTimeForPath,
+} from './utils.js'
+import { killPortProcess } from 'kill-port-process'
+import { CDPSession } from './cdp-session.js'
+import { executeCode, savePageSnapshots } from './execute.js'
+import { startTracing, stopTracing, type ActiveTracing } from './trace-utils.js'
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const require = createRequire(import.meta.url)
+
+interface State {
+  isConnected: boolean
+  page: Page | null
+  browser: Browser | null
+  context: BrowserContext | null
+}
+
+const state: State = {
+  isConnected: false,
+  page: null,
+  browser: null,
+  context: null,
+}
+
+const userState: Record<string, any> = {}
+
+// Store logs per page targetId
+const browserLogs: Map<string, string[]> = new Map()
+const MAX_LOGS_PER_PAGE = 5000
+
+// Store last accessibility snapshot per page for diff feature
+const lastSnapshots: WeakMap<Page, string> = new WeakMap()
+
+// Cache CDP sessions per page
+const cdpSessionCache: WeakMap<Page, CDPSession> = new WeakMap()
+
+// Track active recording with tracing
+// The recording state is persisted to disk so it survives MCP restarts (e.g., Claude Code auto-compact)
+let activeRecording: { path: string; tracing: ActiveTracing } | null = null
+
+// Persisted recording state file path
+const RECORDING_STATE_FILE = '.e2e-pilot/recording-state.json'
+
+interface PersistedRecordingState {
+  path: string
+  tracing: ActiveTracing
+}
+
+function getRecordingStateFilePath(): string {
+  return path.join(process.cwd(), RECORDING_STATE_FILE)
+}
+
+function saveRecordingState(recording: { path: string; tracing: ActiveTracing }): void {
+  const stateFilePath = getRecordingStateFilePath()
+  const dir = path.dirname(stateFilePath)
+  fs.mkdirSync(dir, { recursive: true })
+  const state: PersistedRecordingState = {
+    path: recording.path,
+    tracing: recording.tracing,
+  }
+  fs.writeFileSync(stateFilePath, JSON.stringify(state, null, 2), 'utf-8')
+}
+
+function loadRecordingState(): PersistedRecordingState | null {
+  const stateFilePath = getRecordingStateFilePath()
+  try {
+    if (!fs.existsSync(stateFilePath)) {
+      return null
+    }
+    const content = fs.readFileSync(stateFilePath, 'utf-8')
+    const state = JSON.parse(content) as PersistedRecordingState
+    // Verify the recording file still exists
+    if (!fs.existsSync(state.path)) {
+      clearRecordingState()
+      return null
+    }
+    return state
+  } catch {
+    return null
+  }
+}
+
+function clearRecordingState(): void {
+  const stateFilePath = getRecordingStateFilePath()
+  try {
+    if (fs.existsSync(stateFilePath)) {
+      fs.unlinkSync(stateFilePath)
+    }
+  } catch {
+    // Ignore errors when clearing state
+  }
+}
+
+// Restore recording state from disk on MCP startup
+const persistedState = loadRecordingState()
+if (persistedState) {
+  activeRecording = {
+    path: persistedState.path,
+    tracing: persistedState.tracing,
+  }
+}
+
+const NO_TABS_ERROR = `No browser tabs are connected. Please install and enable the E2E Pilot extension on at least one tab: https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe`
+
+interface RemoteConfig {
+  host: string
+  port: number
+  token?: string
+}
+
+function getRemoteConfig(): RemoteConfig | null {
+  const host = process.env.E2E_PILOT_HOST
+  if (!host) {
+    return null
+  }
+  return {
+    host,
+    port: RELAY_PORT,
+    token: process.env.E2E_PILOT_TOKEN,
+  }
+}
+
+function clearUserState() {
+  Object.keys(userState).forEach((key) => delete userState[key])
+}
+
+function clearConnectionState() {
+  state.isConnected = false
+  state.browser = null
+  state.page = null
+  state.context = null
+}
+
+function getLogServerUrl(): string {
+  const remote = getRemoteConfig()
+  if (remote) {
+    return `http://${remote.host}:${remote.port}/mcp-log`
+  }
+  return `http://127.0.0.1:${RELAY_PORT}/mcp-log`
+}
+
+async function sendLogToRelayServer(level: string, ...args: any[]) {
+  try {
+    await fetch(getLogServerUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ level, args }),
+      signal: AbortSignal.timeout(1000),
+    })
+  } catch {
+    // Silently fail if relay server is not available
+  }
+}
+
+/**
+ * Log to both console.error (for early startup) and relay server log file.
+ * Fire-and-forget to avoid blocking.
+ */
+function mcpLog(...args: any[]) {
+  console.error(...args)
+  sendLogToRelayServer('log', ...args)
+}
+
+async function killRelayServer(port: number): Promise<void> {
+  try {
+    await killPortProcess(port)
+    await sleep(500)
+  } catch {}
+}
+
+/**
+ * Compare two semver versions. Returns:
+ * - negative if v1 < v2
+ * - 0 if v1 === v2
+ * - positive if v1 > v2
+ */
+function compareVersions(v1: string, v2: string): number {
+  const parts1 = v1.split('.').map(Number)
+  const parts2 = v2.split('.').map(Number)
+  const len = Math.max(parts1.length, parts2.length)
+
+  for (let i = 0; i < len; i++) {
+    const p1 = parts1[i] || 0
+    const p2 = parts2[i] || 0
+    if (p1 !== p2) {
+      return p1 - p2
+    }
+  }
+  return 0
+}
+
+async function ensureRelayServer(): Promise<void> {
+  const serverVersion = await getServerVersion(RELAY_PORT)
+
+  if (serverVersion === VERSION) {
+    return
+  }
+
+  // Don't restart if server version is higher than MCP version.
+  // This prevents older MCPs from killing a newer server.
+  if (serverVersion !== null && compareVersions(serverVersion, VERSION) > 0) {
+    return
+  }
+
+  if (serverVersion !== null) {
+    mcpLog(`CDP relay server version mismatch (server: ${serverVersion}, mcp: ${VERSION}), restarting...`)
+    await killRelayServer(RELAY_PORT)
+  } else {
+    mcpLog('CDP relay server not running, starting it...')
+  }
+
+  const dev = process.env.E2E_PILOT_NODE_ENV === 'development'
+  const scriptPath = dev
+    ? path.resolve(__dirname, '../src/start-relay-server.ts')
+    : require.resolve('../dist/start-relay-server.js')
+
+  const serverProcess = spawn(dev ? 'tsx' : process.execPath, [scriptPath], {
+    detached: true,
+    stdio: 'ignore',
+    env: {
+      ...process.env,
+    },
+  })
+
+  serverProcess.unref()
+
+  for (let i = 0; i < 10; i++) {
+    await sleep(500)
+    const newVersion = await getServerVersion(RELAY_PORT)
+    if (newVersion === VERSION) {
+      mcpLog('CDP relay server started successfully, waiting for extension to connect...')
+      await sleep(1000)
+      return
+    }
+  }
+
+  throw new Error(`Failed to start CDP relay server after 5 seconds. Check logs at: ${LOG_FILE_PATH}`)
+}
+
+async function ensureConnection(): Promise<{ browser: Browser; page: Page }> {
+  if (state.isConnected && state.browser && state.page) {
+    return { browser: state.browser, page: state.page }
+  }
+
+  const remote = getRemoteConfig()
+  if (!remote) {
+    await ensureRelayServer()
+  }
+
+  const cdpEndpoint = getCdpUrl(remote || { port: RELAY_PORT })
+  console.log(`Connecting to CDP endpoint: ${cdpEndpoint}`)
+  const browser = await chromium.connectOverCDP(cdpEndpoint)
+  console.log(`Connected to CDP endpoint`)
+
+  // Clear connection state when browser disconnects (e.g., extension reconnects, relay server restarts)
+  browser.on('disconnected', () => {
+    mcpLog('Browser disconnected, clearing connection state')
+    clearConnectionState()
+  })
+
+  const contexts = browser.contexts()
+  const context = contexts.length > 0 ? contexts[0] : await browser.newContext()
+  // set default action timeout
+  context.setDefaultTimeout(5000)
+
+  // Set up console listener for all future pages
+  context.on('page', (page) => {
+    setupPageConsoleListener(page)
+  })
+
+  const pages = context.pages()
+  if (pages.length === 0) {
+    throw new Error(NO_TABS_ERROR)
+  }
+  const page = pages[0]
+
+  // Set up console listener for all existing pages
+  context.pages().forEach((p) => setupPageConsoleListener(p))
+
+  // These functions only set context-level options, they do NOT send CDP commands to pages.
+  // Sending CDP commands (like Emulation.setEmulatedMedia or setDeviceMetricsOverride) to pages
+  // immediately after connectOverCDP causes pages to render white/blank with about:blank URLs,
+  // because pages may not be fully initialized yet. Playwright applies these settings lazily.
+  await preserveSystemColorScheme(context)
+  await setDeviceScaleFactorForMacOS(context)
+
+  state.browser = browser
+  state.page = page
+  state.context = context
+  state.isConnected = true
+
+  return { browser, page }
+}
+
+async function getPageTargetId(page: Page): Promise<string> {
+  if (!page) {
+    throw new Error('Page is null or undefined')
+  }
+
+  const guid = (page as any)._guid
+  if (guid) {
+    return guid
+  }
+
+  throw new Error('Could not get page identifier: _guid not available')
+}
+
+function setupPageConsoleListener(page: Page) {
+  // Get targetId synchronously using _guid
+  const targetId = (page as any)._guid as string | undefined
+
+  if (!targetId) {
+    // If no _guid, silently fail - this shouldn't happen in normal operation
+    return
+  }
+
+  // Initialize logs array for this page
+  if (!browserLogs.has(targetId)) {
+    browserLogs.set(targetId, [])
+  }
+
+  page.on('framenavigated', (frame) => {
+    if (frame === page.mainFrame()) {
+      browserLogs.set(targetId, [])
+    }
+  })
+
+  page.on('close', () => {
+    browserLogs.delete(targetId)
+  })
+
+  page.on('console', (msg) => {
+    try {
+      let logEntry = `[${msg.type()}] ${msg.text()}`
+
+      if (!browserLogs.has(targetId)) {
+        browserLogs.set(targetId, [])
+      }
+      const pageLogs = browserLogs.get(targetId)!
+
+      pageLogs.push(logEntry)
+      if (pageLogs.length > MAX_LOGS_PER_PAGE) {
+        pageLogs.shift()
+      }
+    } catch (e) {
+      mcpLog('[MCP] Failed to get console message text:', e)
+      return
+    }
+  })
+}
+
+async function getCurrentPage(timeout = 5000) {
+  if (state.page && !state.page.isClosed()) {
+    return state.page
+  }
+
+  // Current page is closed or doesn't exist - find another available page
+  if (state.browser) {
+    const contexts = state.browser.contexts()
+    if (contexts.length > 0) {
+      const pages = contexts[0].pages().filter((p) => !p.isClosed())
+
+      if (pages.length > 0) {
+        const page = pages[0]
+        await page.waitForLoadState('domcontentloaded', { timeout }).catch(() => {})
+        // Update state.page to the new default page
+        state.page = page
+        return page
+      }
+    }
+  }
+
+  throw new Error(NO_TABS_ERROR)
+}
+
+async function resetConnection(): Promise<{ browser: Browser; page: Page; context: BrowserContext }> {
+  if (state.browser) {
+    try {
+      await state.browser.close()
+    } catch (e) {
+      mcpLog('Error closing browser:', e)
+    }
+  }
+
+  clearConnectionState()
+  clearUserState()
+
+  // DO NOT clear browser logs on reset - logs should persist across reconnections
+  // browserLogs.clear()
+
+  const remote = getRemoteConfig()
+  if (!remote) {
+    await ensureRelayServer()
+  }
+
+  const cdpEndpoint = getCdpUrl(remote || { port: RELAY_PORT })
+  const browser = await chromium.connectOverCDP(cdpEndpoint)
+
+  // Clear connection state when browser disconnects (e.g., extension reconnects, relay server restarts)
+  browser.on('disconnected', () => {
+    mcpLog('Browser disconnected, clearing connection state')
+    clearConnectionState()
+  })
+
+  const contexts = browser.contexts()
+  const context = contexts.length > 0 ? contexts[0] : await browser.newContext()
+  context.setDefaultTimeout(5000)
+
+  // Set up console listener for all future pages
+  context.on('page', (page) => {
+    setupPageConsoleListener(page)
+  })
+
+  const pages = context.pages()
+  if (pages.length === 0) {
+    throw new Error(NO_TABS_ERROR)
+  }
+  const page = pages[0]
+
+  // Set up console listener for all existing pages
+  context.pages().forEach((p) => setupPageConsoleListener(p))
+
+  await preserveSystemColorScheme(context)
+  await setDeviceScaleFactorForMacOS(context)
+
+  state.browser = browser
+  state.page = page
+  state.context = context
+  state.isConnected = true
+
+  return { browser, page, context }
+}
+
+const server = new McpServer({
+  name: 'e2e-pilot',
+  title: 'The better playwright MCP: works as a browser extension. No context bloat. More capable.',
+  version: '1.0.0',
+})
+
+const promptContent =
+  fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'prompt.md'), 'utf-8') +
+  `\n\nfor debugging internal errors, check relay server logs at: ${LOG_FILE_PATH}`
+
+server.tool(
+  'execute',
+  promptContent,
+  {
+    intend: z.string().describe('The intent of the call, e.g. "Fill form and submit"'),
+    code: z
+      .string()
+      .optional()
+      .describe(
+        'js playwright code, has {page, state, context} in scope. Should be one line, using ; to execute multiple statements. you MUST call execute multiple times instead of writing complex scripts in a single tool call.',
+      ),
+    file: z
+      .string()
+      .optional()
+      .describe('Path to a file containing the code to execute. If provided, code parameter is ignored.'),
+    startLine: z
+      .number()
+      .optional()
+      .describe('Start line number (1-indexed) when loading from file. If omitted, starts from beginning.'),
+    endLine: z
+      .number()
+      .optional()
+      .describe('End line number (1-indexed, inclusive) when loading from file. If omitted, reads to end of file.'),
+    timeout: z.number().default(5000).describe('Timeout in milliseconds for code execution (default: 5000ms)'),
+  },
+  async ({ code, file, startLine, endLine, timeout, intend }) => {
+    // Load code from file if file parameter is provided
+    let finalCode: string
+    if (file) {
+      if (!fs.existsSync(file)) {
+        return {
+          content: [{ type: 'text', text: `File not found: ${file}` }],
+          isError: true,
+        }
+      }
+      const fileContent = fs.readFileSync(file, 'utf-8')
+      const lines = fileContent.split('\n')
+      const start = startLine ? startLine - 1 : 0 // Convert to 0-indexed
+      const end = endLine ? endLine : lines.length // endLine is inclusive, so no -1
+      finalCode = lines.slice(start, end).join('\n')
+    } else if (code) {
+      finalCode = code
+    } else {
+      return {
+        content: [{ type: 'text', text: 'Either "code" or "file" parameter must be provided' }],
+        isError: true,
+      }
+    }
+
+    const remote = getRemoteConfig()
+    if (!remote) {
+      await ensureRelayServer()
+    }
+    await ensureConnection()
+
+    const page = await getCurrentPage(timeout)
+    const context = state.context || page.context()
+
+    return executeCode({
+      code: finalCode,
+      timeout,
+      deps: {
+        page,
+        context,
+        userState,
+        browserLogs,
+        lastSnapshots,
+        cdpSessionCache,
+        getPageTargetId,
+        getCdpUrl: () => getCdpUrl(remote || { port: RELAY_PORT }),
+        resetConnection,
+        logger: mcpLog,
+        sendLogToRelayServer,
+        intend,
+        activeRecordingPath: activeRecording?.path,
+      },
+    })
+  },
+)
+
+server.tool(
+  'snapshot',
+  dedent`
+    Take a snapshot of the current page.
+    Returns the path to the snapshot file.
+  `,
+  {},
+  async () => {
+    const remote = getRemoteConfig()
+    if (!remote) {
+      await ensureRelayServer()
+    }
+    await ensureConnection()
+    const page = await getCurrentPage()
+
+    try {
+      const snapshotPaths = await savePageSnapshots({ page, lastSnapshots, timeout: 5000 })
+
+      if (!snapshotPaths) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to save snapshot: _snapshotForAI returned null. The page may not support accessibility snapshots or the page is not fully loaded. Try using 'execute' tool with 'await page.waitForLoadState("domcontentloaded")' first.`,
+            },
+          ],
+          isError: true,
+        }
+      }
+
+      const viewportSize = page.viewportSize()
+      let responseText = `Snapshots saved:\n- Full: ${snapshotPaths.fullPath}`
+      if (viewportSize) {
+        responseText += `\n- Viewport: ${viewportSize.width}x${viewportSize.height}`
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseText,
+          },
+        ],
+      }
+    } catch (error: any) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Failed to save snapshot: ${error.message}`,
+          },
+        ],
+        isError: true,
+      }
+    }
+  },
+)
+
+server.tool(
+  'start_recording',
+  dedent`
+    Start recording browser interactions to a .js file for e2e test code generation.
+    Also starts Playwright tracing to capture screenshots, DOM snapshots, and action logs.
+    Creates files at:
+    - .e2e-pilot/recordings/YYYY-MM-DD_HH-MM-SS.js (code recording)
+    - .e2e-pilot/traces/YYYY-MM-DD_HH-MM-SS.zip (trace file)
+    All subsequent execute calls will append their code to this file until stop_recording is called.
+    Use stop_recording to stop and get the recording and trace file paths.
+  `,
+  {
+    title: z.string().describe('A title describing the recording purpose, e.g. "Login flow" or "Create new loan"'),
+    pageDescription: z.string().describe('A multiline description of the page state.'),
+  },
+  async ({ title, pageDescription }) => {
+    const remote = getRemoteConfig()
+    if (!remote) {
+      await ensureRelayServer()
+    }
+    await ensureConnection()
+
+    const context = state.context
+    if (!context) {
+      return {
+        content: [{ type: 'text', text: 'No browser context available. Call execute first.' }],
+        isError: true,
+      }
+    }
+
+    if (activeRecording) {
+      return {
+        content: [{ type: 'text', text: `Recording already active at: ${activeRecording.path}` }],
+        isError: true,
+      }
+    }
+
+    const timeout = 5000
+    const page = await getCurrentPage(timeout)
+
+    const pageUrl = page.url()
+    const pageTitle = await page.title()
+
+    const now = new Date()
+    const dateTimeStr = formatDateTimeForPath(now)
+
+    const recordingDir = path.join(process.cwd(), '.e2e-pilot', 'recordings')
+    fs.mkdirSync(recordingDir, { recursive: true })
+
+    const recordingPath = path.join(recordingDir, `${dateTimeStr}.js`)
+    const snapshotPaths = await savePageSnapshots({ page, lastSnapshots, timeout })
+
+    // Start tracing
+    const tracesBaseDir = path.join(process.cwd(), '.e2e-pilot', 'traces')
+    const tracing = await startTracing({ context, baseDir: tracesBaseDir })
+
+    const metaComment = dedent`
+      // ${title}
+
+      // Initial state:
+      // Snapshot: ${snapshotPaths?.fullPath}
+      // URL: ${pageUrl}
+      // Title: ${pageTitle}
+      ${formatAsCommentLines(pageDescription)}
+
+
+    `
+    fs.writeFileSync(recordingPath, metaComment, 'utf-8')
+
+    activeRecording = { path: recordingPath, tracing }
+    saveRecordingState(activeRecording)
+
+    let responseText = `Recording started: ${recordingPath}\nTracing started: ${tracing.path}\n\nPage URL: ${pageUrl}\nPage Title: ${pageTitle}`
+    if (snapshotPaths) {
+      responseText += `\n\nSnapshots saved:\n- Full: ${snapshotPaths.fullPath}`
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: responseText,
+        },
+      ],
+    }
+  },
+)
+
+server.tool(
+  'read_recording',
+  dedent`
+    Read the currently active recording file.
+    Returns the content of the recording started by start_recording.
+  `,
+  {},
+  async () => {
+    if (!activeRecording) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'No active recording. Call start_recording first.',
+          },
+        ],
+        isError: true,
+      }
+    }
+
+    try {
+      const content = fs.readFileSync(activeRecording.path, 'utf-8')
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Recording file: ${activeRecording.path}\n\n${content || '(empty)'}`,
+          },
+        ],
+      }
+    } catch (error: any) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Failed to read recording: ${error.message}`,
+          },
+        ],
+        isError: true,
+      }
+    }
+  },
+)
+
+server.tool(
+  'stop_recording',
+  dedent`
+    Stop the active recording and tracing session.
+    Returns the paths to the recording file and trace file.
+    View traces with: npx playwright show-trace <trace-file>
+  `,
+  {},
+  async () => {
+    if (!activeRecording) {
+      return {
+        content: [{ type: 'text', text: 'No active recording. Call start_recording first.' }],
+        isError: true,
+      }
+    }
+
+    const context = state.context
+    if (!context) {
+      const recordingPath = activeRecording.path
+      activeRecording = null
+      clearRecordingState()
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Recording stopped: ${recordingPath}\n\nWarning: Could not stop tracing (no browser context).`,
+          },
+        ],
+      }
+    }
+
+    const recordingPath = activeRecording.path
+    let tracePath: string | null = null
+    let tracingWarning = ''
+
+    try {
+      tracePath = await stopTracing({ context, activeTracing: activeRecording.tracing })
+    } catch (error: any) {
+      // Tracing may fail if MCP was restarted (tracing session lost)
+      // Still allow stopping the recording gracefully
+      tracingWarning = `\n\nWarning: Could not save trace (${error.message}). This can happen if the MCP was restarted during recording.`
+    }
+
+    activeRecording = null
+    clearRecordingState()
+
+    if (tracePath) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Recording stopped: ${recordingPath}\nTrace saved: ${tracePath}\n\nView trace with: npx playwright show-trace ${tracePath}`,
+          },
+        ],
+      }
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Recording stopped: ${recordingPath}${tracingWarning}`,
+        },
+      ],
+    }
+  },
+)
+
+server.tool(
+  'reset',
+  dedent`
+    Recreates the CDP connection and resets the browser/page/context. Use this when the MCP stops responding, you get connection errors, if there are no pages in context, assertion failures, page closed, or other issues.
+
+    After calling this tool, the page and context variables are automatically updated in the execution environment.
+
+    This tools also removes any custom properties you may have added to the global scope AND clearing all keys from the \`state\` object. Only \`page\`, \`context\`, \`state\` (empty), \`console\`, and utility functions will remain.
+
+    if playwright always returns all pages as about:blank urls and evaluate does not work you should ask the user to restart Chrome. This is a known Chrome bug.
+  `,
+  {},
+  async () => {
+    try {
+      const { page, context } = await resetConnection()
+      const pagesCount = context.pages().length
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Connection reset successfully. ${pagesCount} page(s) available. Current page URL: ${page.url()}`,
+          },
+        ],
+      }
+    } catch (error: any) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Failed to reset connection: ${error.message}`,
+          },
+        ],
+        isError: true,
+      }
+    }
+  },
+)
+
+async function checkRemoteServer({ host, port }: { host: string; port: number }): Promise<void> {
+  const versionUrl = `http://${host}:${port}/version`
+  try {
+    const response = await fetch(versionUrl, { signal: AbortSignal.timeout(3000) })
+    if (!response.ok) {
+      throw new Error(`Server responded with status ${response.status}`)
+    }
+  } catch (error: any) {
+    const isConnectionError = error.cause?.code === 'ECONNREFUSED' || error.name === 'TimeoutError'
+    if (isConnectionError) {
+      throw new Error(
+        `Cannot connect to remote relay server at ${host}:${port}. ` +
+          `Make sure 'npx -y e2e-pilot serve' is running on the host machine.`,
+      )
+    }
+    throw new Error(`Failed to connect to remote relay server: ${error.message}`)
+  }
+}
+
+export async function startMcp(options: { host?: string; token?: string } = {}) {
+  if (options.host) {
+    process.env.E2E_PILOT_HOST = options.host
+  }
+  if (options.token) {
+    process.env.E2E_PILOT_TOKEN = options.token
+  }
+
+  const remote = getRemoteConfig()
+  if (!remote) {
+    await ensureRelayServer()
+  } else {
+    mcpLog(`Using remote CDP relay server: ${remote.host}:${remote.port}`)
+    await checkRemoteServer(remote)
+  }
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}