@everydaydevopsio/pilot 0.5.2 → 0.6.0

package/src/mcp/tools/browser.ts

@@ -57,6 +57,10 @@ const navigateShape = {
 };
 
 const clickShape = {
+  ref: z
+    .string()
+    .optional()
+    .describe('Element ref from browser_snapshot (e.g. "e3")'),
   selector: z.string().optional().describe('CSS selector to click'),
   x: z.number().optional().describe('Viewport X coordinate'),
   y: z.number().optional().describe('Viewport Y coordinate'),
@@ -80,6 +84,10 @@ const clickShape = {
 
 const typeShape = {
   text: z.string().describe('Text to type'),
+  ref: z
+    .string()
+    .optional()
+    .describe('Element ref from browser_snapshot (e.g. "e3")'),
   selector: z.string().optional().describe('CSS selector to focus first'),
   clearFirst: z
     .boolean()
@@ -128,7 +136,7 @@ const startShape = {
     .boolean()
     .optional()
     .describe(
-      'Run Chrome headless. When omitted, falls back to PILOT_HEADLESS (default: true).'
+      'Run Chrome headless. When omitted, falls back to PILOT_HEADLESS (accepts true/1 or false/0; default: false).'
     ),
   chromePath: z
     .string()
@@ -190,6 +198,24 @@ const switchTabShape = {
   targetId: z.string().describe('Target ID of the tab to switch to')
 };
 
+const tabsShape = {
+  action: z
+    .enum(['list', 'new', 'select', 'close'])
+    .describe(
+      'Action: list tabs, open new tab, select/switch tab, or close tab'
+    ),
+  targetId: z
+    .string()
+    .optional()
+    .describe('Target ID (required for select and close actions)'),
+  url: z
+    .string()
+    .optional()
+    .describe(
+      'URL to open in the new tab (new action only, opens blank tab if omitted)'
+    )
+};
+
 const viewportResizeShape = {
   width: z.number().int().positive().describe('New viewport width in pixels'),
   height: z.number().int().positive().describe('New viewport height in pixels'),
@@ -361,10 +387,11 @@ export function registerBrowserTools(
 
   server.tool(
     'browser_click',
-    'Click an element by CSS selector or coordinates. Either selector or x/y coordinates required.',
+    'Click an element by ref (from browser_snapshot), CSS selector, or coordinates.',
     clickShape,
     async (params) => {
       if (
+        params.ref === undefined &&
         params.selector === undefined &&
         (params.x === undefined || params.y === undefined)
       ) {
@@ -372,7 +399,7 @@ export function registerBrowserTools(
           content: [
             {
               type: 'text' as const,
-              text: 'Error: Either selector or x/y coordinates are required'
+              text: 'Error: Either ref, selector, or x/y coordinates are required'
             }
           ],
           isError: true
@@ -380,7 +407,7 @@ export function registerBrowserTools(
       }
 
       const { client } = requireClient(context);
-      const result = await executeClick(client, params);
+      const result = await executeClick(client, params, context.elementRefMap);
 
       return {
         content: [
@@ -395,17 +422,18 @@ export function registerBrowserTools(
 
   server.tool(
     'browser_type',
-    'Type text into the focused element or a specified selector',
+    'Type text into the focused element, a ref (from browser_snapshot), or a CSS selector. Generates keystroke events (use browser_fill to replace a field value entirely).',
     typeShape,
     async (params) => {
       const { client } = requireClient(context);
-      await executeType(client, params);
+      await executeType(client, params, context.elementRefMap);
 
+      const target = params.ref ?? params.selector;
       return {
         content: [
           {
             type: 'text' as const,
-            text: `Typed "${params.text}"${params.selector ? ` into ${params.selector}` : ''}`
+            text: `Typed "${params.text}"${target ? ` into ${target}` : ''}`
           }
         ]
       };
@@ -602,4 +630,82 @@ export function registerBrowserTools(
       };
     }
   );
+
+  server.tool(
+    'browser_tabs',
+    'Manage browser tabs. Actions: "list" shows all tabs, "new" opens a tab (optional url), "select" switches to a tab (requires targetId), "close" closes a tab (requires targetId).',
+    tabsShape,
+    async ({ action, targetId, url }) => {
+      const { manager } = requireClient(context);
+
+      switch (action) {
+        case 'list': {
+          const tabs = await executeListTabs(manager);
+          return {
+            content: [
+              { type: 'text' as const, text: JSON.stringify(tabs, null, 2) }
+            ]
+          };
+        }
+
+        case 'new': {
+          const result = await executeNewTab(manager, url);
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `New tab opened (targetId: ${result.targetId}, url: ${result.url})`
+              }
+            ]
+          };
+        }
+
+        case 'select': {
+          if (!targetId) {
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: 'Error: targetId is required for select action'
+                }
+              ],
+              isError: true
+            };
+          }
+          await executeSwitchTab(manager, targetId);
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `Switched to tab ${targetId}.`
+              }
+            ]
+          };
+        }
+
+        case 'close': {
+          if (!targetId) {
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: 'Error: targetId is required for close action'
+                }
+              ],
+              isError: true
+            };
+          }
+          await executeCloseTab(manager, targetId);
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `Tab ${targetId} closed.`
+              }
+            ]
+          };
+        }
+      }
+    }
+  );
 }

package/src/mcp/tools/connect.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import type { BrowserManager } from '../../browser/browser-manager.js';
+import { executeConnect, formatConnectResult } from '../../commands/connect.js';
+
+const connectShape = {
+  host: z
+    .string()
+    .default('127.0.0.1')
+    .describe('Chrome debugging host (default: 127.0.0.1)'),
+  port: z
+    .number()
+    .int()
+    .min(1)
+    .max(65535)
+    .default(9222)
+    .describe('Chrome debugging port (default: 9222)')
+};
+
+export function registerConnectTools(
+  server: McpServer,
+  context: BrowserContext,
+  makeBrowserManager: () => BrowserManager
+): void {
+  server.tool(
+    'browser_connect',
+    'Connect to an existing Chrome instance with remote debugging enabled. Start Chrome with --remote-debugging-port=PORT, then use this tool to connect. Lists available tabs after connecting. Use browser_switch_tab to select a specific tab.',
+    connectShape,
+    async ({ host, port }) => {
+      if (context.manager?.isConnected()) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Already connected to a browser. Call browser_stop to disconnect first.'
+            }
+          ]
+        };
+      }
+
+      if (context.manager) {
+        await context.manager.destroy();
+        context.manager = null;
+      }
+
+      const manager = makeBrowserManager();
+      try {
+        const result = await executeConnect(manager, { host, port });
+        context.manager = manager;
+        return {
+          content: [
+            { type: 'text' as const, text: formatConnectResult(result) }
+          ]
+        };
+      } catch (err) {
+        await manager.destroy();
+        throw err;
+      }
+    }
+  );
+}

package/src/mcp/tools/files.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import { executeDialog, formatDialogResult } from '../../commands/dialog.js';
+import { executeUpload } from '../../commands/upload.js';
+import {
+  executeDownloads,
+  formatDownloadsResult
+} from '../../commands/downloads.js';
+
+const dialogShape = {
+  action: z
+    .enum(['list', 'accept', 'dismiss'])
+    .describe(
+      'Action: list pending dialogs, accept (OK/Yes), or dismiss (Cancel/No)'
+    ),
+  promptText: z
+    .string()
+    .optional()
+    .describe('Text to enter for prompt dialogs (accept action only)')
+};
+
+const uploadShape = {
+  ref: z
+    .string()
+    .describe('Element ref of a file input (from browser_snapshot)'),
+  files: z
+    .array(z.string())
+    .describe(
+      'File paths to upload. Must exist, be regular files, and be under PILOT_UPLOAD_ROOTS (default: cwd).'
+    )
+};
+
+const downloadsShape = {
+  action: z
+    .enum(['list', 'wait', 'clear'])
+    .describe(
+      'Action: list tracked downloads, wait for one to complete, or clear'
+    ),
+  guid: z
+    .string()
+    .optional()
+    .describe('Download GUID (required for wait action)'),
+  timeoutMs: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Timeout for wait action in milliseconds (default: 30000)')
+};
+
+function requireContext(context: BrowserContext) {
+  const manager = context.manager;
+  if (!manager || !manager.isConnected()) {
+    throw new Error('Browser not started. Call browser_start first.');
+  }
+  const client = manager.getClient()!;
+  return { client };
+}
+
+export function registerFilesTools(
+  server: McpServer,
+  context: BrowserContext
+): void {
+  server.tool(
+    'browser_dialog',
+    'Handle browser dialogs (alert, confirm, prompt). Use "list" to see pending dialogs, "accept" to click OK/Yes, or "dismiss" to click Cancel/No. For prompt dialogs, provide promptText with accept.',
+    dialogShape,
+    async ({ action, promptText }) => {
+      const { client } = requireContext(context);
+      const result = await executeDialog(client, context.dialogQueue, {
+        action,
+        promptText
+      });
+      return {
+        content: [{ type: 'text' as const, text: formatDialogResult(result) }]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_upload',
+    'Upload files to a file input element by ref. Files must exist, be regular files, and be under allowed roots (PILOT_UPLOAD_ROOTS env, default: cwd). Use browser_snapshot to find file input refs.',
+    uploadShape,
+    async ({ ref, files }) => {
+      const { client } = requireContext(context);
+      const result = await executeUpload(client, context.elementRefMap, {
+        ref,
+        files
+      });
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Uploaded ${result.files.length} file(s) to ${result.ref}`
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_downloads',
+    'Track file downloads. Actions: "list" shows tracked downloads with status/progress; "wait" blocks until a download (by GUID) completes; "clear" resets the tracker.',
+    downloadsShape,
+    async ({ action, guid, timeoutMs }) => {
+      requireContext(context);
+      const result = await executeDownloads(context.downloadTracker, {
+        action,
+        guid,
+        timeoutMs
+      });
+      return {
+        content: [
+          { type: 'text' as const, text: formatDownloadsResult(result) }
+        ]
+      };
+    }
+  );
+}

package/src/mcp/tools/interaction.ts

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import { executeFill } from '../../commands/fill.js';
+import { executeHover } from '../../commands/hover.js';
+import { executePressKey } from '../../commands/press_key.js';
+import { executeSelect } from '../../commands/select.js';
+import { executeCheck } from '../../commands/check.js';
+import { executeScroll } from '../../commands/scroll.js';
+
+function requireContext(context: BrowserContext) {
+  const manager = context.manager;
+  if (!manager || !manager.isConnected()) {
+    throw new Error('Browser not started. Call browser_start first.');
+  }
+  const client = manager.getClient()!;
+  return { client, refMap: context.elementRefMap };
+}
+
+const fillShape = {
+  ref: z.string().describe('Element ref from browser_snapshot (e.g. "e3")'),
+  value: z.string().describe('Value to set in the field')
+};
+
+const hoverShape = {
+  ref: z
+    .string()
+    .optional()
+    .describe('Element ref from browser_snapshot (e.g. "e3")'),
+  x: z.number().optional().describe('Viewport X coordinate'),
+  y: z.number().optional().describe('Viewport Y coordinate')
+};
+
+const pressKeyShape = {
+  key: z
+    .string()
+    .describe(
+      'Key to press. Named keys: Enter, Tab, Escape, Backspace, Delete, Space, ArrowUp/Down/Left/Right, Home, End, PageUp/Down, F1-F12. Modifier combos: Control+a, Meta+c, Shift+Enter.'
+    )
+};
+
+const selectShape = {
+  ref: z.string().describe('Element ref of a <select> element'),
+  value: z.string().optional().describe('Option value attribute to select'),
+  label: z.string().optional().describe('Option visible text to select'),
+  index: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Option index to select (0-based)')
+};
+
+const checkShape = {
+  ref: z.string().describe('Element ref of a checkbox or radio button'),
+  checked: z.boolean().optional().describe('Desired state. Omit to toggle.')
+};
+
+const scrollShape = {
+  ref: z.string().optional().describe('Element ref to scroll into view'),
+  direction: z
+    .enum(['up', 'down', 'left', 'right'])
+    .optional()
+    .describe('Scroll direction'),
+  amount: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Scroll amount in pixels (default: 300)'),
+  x: z.number().optional().describe('Absolute scroll X position'),
+  y: z.number().optional().describe('Absolute scroll Y position')
+};
+
+export function registerInteractionTools(
+  server: McpServer,
+  context: BrowserContext
+): void {
+  server.tool(
+    'browser_fill',
+    'Fill a form field by element ref. Replaces the entire field value and fires input/change events compatible with React, Vue, and Svelte. Use browser_snapshot first to get refs.',
+    fillShape,
+    async ({ ref, value }) => {
+      const { client, refMap } = requireContext(context);
+      const result = await executeFill(client, refMap, { ref, value });
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Filled ${result.ref} with "${result.value}"`
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_hover',
+    'Hover over an element by ref or coordinates. Dispatches a mouseMoved event.',
+    hoverShape,
+    async (params) => {
+      if (
+        params.ref === undefined &&
+        (params.x === undefined || params.y === undefined)
+      ) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Error: Either ref or x/y coordinates are required'
+            }
+          ],
+          isError: true
+        };
+      }
+      const { client, refMap } = requireContext(context);
+      const result = await executeHover(client, refMap, params);
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Hovered at (${result.x}, ${result.y})`
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_press_key',
+    'Press a key or key combination. Supports named keys (Enter, Tab, Escape, etc.) and modifier combos (Control+a, Meta+c, Shift+Enter).',
+    pressKeyShape,
+    async ({ key }) => {
+      const { client } = requireContext(context);
+      const result = await executePressKey(client, { key });
+      const modStr =
+        result.modifiers.length > 0
+          ? ` with modifiers: ${result.modifiers.join('+')}`
+          : '';
+      return {
+        content: [
+          { type: 'text' as const, text: `Pressed ${result.key}${modStr}` }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_select',
+    'Select an option in a <select> element by value, label, or index. Use browser_snapshot to get the ref.',
+    selectShape,
+    async (params) => {
+      if (
+        params.value === undefined &&
+        params.label === undefined &&
+        params.index === undefined
+      ) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Error: One of value, label, or index is required'
+            }
+          ],
+          isError: true
+        };
+      }
+      const { client, refMap } = requireContext(context);
+      const result = await executeSelect(client, refMap, params);
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Selected "${result.selectedLabel}" (value="${result.selectedValue}") in ${result.ref}`
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_check',
+    'Toggle a checkbox or radio button by ref. Optionally set to a specific checked state.',
+    checkShape,
+    async ({ ref, checked }) => {
+      const { client, refMap } = requireContext(context);
+      const result = await executeCheck(client, refMap, { ref, checked });
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `${result.ref} is now ${result.checked ? 'checked' : 'unchecked'}`
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_scroll',
+    'Scroll the page or an element. Use ref to scroll an element into view, direction/amount for relative scrolling, or x/y for absolute scroll position.',
+    scrollShape,
+    async (params) => {
+      if (
+        params.ref === undefined &&
+        params.direction === undefined &&
+        params.x === undefined &&
+        params.y === undefined
+      ) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Error: At least one of ref, direction, or x/y is required'
+            }
+          ],
+          isError: true
+        };
+      }
+      const { client, refMap } = requireContext(context);
+      const result = await executeScroll(client, refMap, params);
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Scrolled to (${result.scrollX}, ${result.scrollY})`
+          }
+        ]
+      };
+    }
+  );
+}

package/src/mcp/tools/names.ts

@@ -19,7 +19,25 @@ export const EXPECTED_TOOLS = [
   'browser_viewport_resize',
   'browser_get_console_logs',
   'browser_get_errors',
-  'browser_clear_errors'
+  'browser_clear_errors',
+  'browser_snapshot',
+  'browser_find',
+  'browser_fill',
+  'browser_hover',
+  'browser_press_key',
+  'browser_select',
+  'browser_check',
+  'browser_scroll',
+  'browser_network',
+  'browser_console',
+  'browser_errors',
+  'browser_styles',
+  'browser_dialog',
+  'browser_upload',
+  'browser_downloads',
+  'browser_performance',
+  'browser_connect',
+  'browser_tabs'
 ] as const;
 
 export type ToolName = (typeof EXPECTED_TOOLS)[number];