@everydaydevopsio/pilot 0.5.2 → 0.6.1

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];

package/src/mcp/tools/network.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import {
+  executeNetwork,
+  formatNetworkList,
+  formatNetworkDetail
+} from '../../commands/network.js';
+
+const networkShape = {
+  action: z
+    .enum(['list', 'get', 'clear'])
+    .describe('Action: list requests, get request detail, or clear buffer'),
+  requestId: z
+    .string()
+    .optional()
+    .describe('Request ID (required for "get" action)'),
+  url: z.string().optional().describe('Filter by URL substring (list only)'),
+  method: z
+    .string()
+    .optional()
+    .describe('Filter by HTTP method, e.g. GET, POST (list only)'),
+  statusMin: z
+    .number()
+    .int()
+    .optional()
+    .describe('Filter by minimum status code (list only)'),
+  statusMax: z
+    .number()
+    .int()
+    .optional()
+    .describe('Filter by maximum status code (list only)'),
+  resourceType: z
+    .string()
+    .optional()
+    .describe(
+      'Filter by resource type: Document, Stylesheet, Script, Image, XHR, Fetch, etc. (list only)'
+    ),
+  failed: z
+    .boolean()
+    .optional()
+    .describe('Filter to only failed requests (list only)'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Maximum number of results (list only)')
+};
+
+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, networkBuffer: context.networkBuffer };
+}
+
+export function registerNetworkTools(
+  server: McpServer,
+  context: BrowserContext
+): void {
+  server.tool(
+    'browser_network',
+    'Inspect captured network requests. Actions: "list" shows request summaries with filters (url, method, status, resourceType, failed); "get" returns full detail for a request ID including headers and response body; "clear" resets the buffer.',
+    networkShape,
+    async (params) => {
+      const { client, networkBuffer } = requireContext(context);
+      const result = await executeNetwork(client, networkBuffer, params);
+
+      let text: string;
+      if (result.action === 'list') {
+        text = formatNetworkList(result);
+      } else if (result.action === 'get') {
+        text = formatNetworkDetail(result);
+      } else {
+        text = `Cleared ${result.cleared} network records.`;
+      }
+
+      return {
+        content: [{ type: 'text' as const, text }]
+      };
+    }
+  );
+}

package/src/mcp/tools/performance.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import { executePerformance } from '../../commands/performance.js';
+
+const performanceShape = {
+  action: z
+    .enum(['start', 'stop', 'analyze'])
+    .describe(
+      'Action: "start" begins tracing, "stop" ends collection, "analyze" returns a summary of navigation timing, long tasks, slow requests, and large resources'
+    )
+};
+
+function requireContext(context: BrowserContext) {
+  const manager = context.manager;
+  if (!manager || !manager.isConnected()) {
+    throw new Error('Browser not started. Call browser_start first.');
+  }
+  return { client: manager.getClient()! };
+}
+
+export function registerPerformanceTools(
+  server: McpServer,
+  context: BrowserContext
+): void {
+  server.tool(
+    'browser_performance',
+    'Inspect page performance. Actions: "start" begins tracing (call before navigating), "stop" ends collection, "analyze" returns an agent-friendly summary with navigation timing, long tasks, slow requests, large resources, and JS execution time.',
+    performanceShape,
+    async ({ action }) => {
+      const { client } = requireContext(context);
+      const result = await executePerformance(client, context.traceState, {
+        action
+      });
+      return {
+        content: [{ type: 'text' as const, text: result.text }]
+      };
+    }
+  );
+}

package/src/mcp/tools/runtime.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type {
+  ConsoleBuffer,
+  ConsoleLevel,
+  ConsoleMessage
+} from '../console-buffer.js';
+
+const consoleShape = {
+  action: z
+    .enum(['list', 'clear'])
+    .default('list')
+    .describe('Action: list messages or clear the buffer'),
+  level: z
+    .enum(['log', 'warn', 'error', 'info', 'debug'])
+    .optional()
+    .describe('Filter by single log level'),
+  levels: z
+    .array(z.enum(['log', 'warn', 'error', 'info', 'debug']))
+    .optional()
+    .describe('Filter by multiple log levels'),
+  sinceMs: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Only messages from the last N milliseconds'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .default(100)
+    .describe('Maximum messages to return')
+};
+
+const errorsShape = {
+  action: z
+    .enum(['list', 'clear'])
+    .default('list')
+    .describe('Action: list errors or clear the buffer'),
+  sinceMs: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Only errors from the last N milliseconds'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .default(50)
+    .describe('Maximum errors to return'),
+  includeWarnings: z
+    .boolean()
+    .default(false)
+    .describe('Include warnings in addition to errors')
+};
+
+// CDP line/column numbers are 0-based; convert to 1-based for display
+function line1(n: number): number {
+  return n + 1;
+}
+
+function formatMessage(msg: ConsoleMessage): string {
+  const parts = [`[${msg.level.toUpperCase()}] ${msg.text}`];
+  if (msg.url) {
+    const col =
+      msg.columnNumber !== undefined ? `:${line1(msg.columnNumber)}` : '';
+    parts.push(`  at ${msg.url}:${line1(msg.lineNumber)}${col}`);
+  }
+  if (msg.stackFrames && msg.stackFrames.length > 0) {
+    for (const frame of msg.stackFrames) {
+      const fn = frame.functionName || '<anonymous>';
+      parts.push(
+        `    at ${fn} (${frame.url}:${line1(frame.lineNumber)}:${line1(frame.columnNumber)})`
+      );
+    }
+  }
+  return parts.join('\n');
+}
+
+export function registerRuntimeTools(
+  server: McpServer,
+  buffer: ConsoleBuffer
+): void {
+  server.tool(
+    'browser_console',
+    'Get or clear console messages. Actions: "list" returns messages with optional level/sinceMs/limit filters; "clear" resets the buffer. Messages include source location and stack traces for exceptions.',
+    consoleShape,
+    async ({ action, level, levels, sinceMs, limit }) => {
+      if (action === 'clear') {
+        const cleared = buffer.clear();
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Cleared ${cleared} console messages.`
+            }
+          ]
+        };
+      }
+
+      let filterLevels: ConsoleLevel | ConsoleLevel[] | undefined;
+      if (levels && levels.length > 0) {
+        filterLevels = levels as ConsoleLevel[];
+      } else if (level) {
+        filterLevels = level as ConsoleLevel;
+      }
+
+      const messages = buffer.getAll({ level: filterLevels, sinceMs, limit });
+
+      if (messages.length === 0) {
+        return {
+          content: [{ type: 'text' as const, text: 'No console messages.' }]
+        };
+      }
+
+      const formatted = messages.map(formatMessage).join('\n\n');
+      const header = `Console messages (${messages.length}):\n`;
+
+      return {
+        content: [{ type: 'text' as const, text: header + formatted }]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_errors',
+    'Get or clear runtime errors and exceptions. Actions: "list" returns errors with stack traces; "clear" resets the buffer. Captures both console.error calls and uncaught exceptions.',
+    errorsShape,
+    async ({ action, sinceMs, limit, includeWarnings }) => {
+      if (action === 'clear') {
+        const cleared = buffer.clear();
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Cleared ${cleared} console messages.`
+            }
+          ]
+        };
+      }
+
+      const levels: ConsoleLevel[] = includeWarnings
+        ? ['error', 'warn']
+        : ['error'];
+
+      const errors = buffer.getAll({ level: levels, sinceMs, limit });
+
+      if (errors.length === 0) {
+        return {
+          content: [{ type: 'text' as const, text: 'No errors found.' }]
+        };
+      }
+
+      const formatted = errors.map(formatMessage).join('\n\n');
+      const header = `Errors (${errors.length}):\n`;
+
+      return {
+        content: [{ type: 'text' as const, text: header + formatted }]
+      };
+    }
+  );
+}

package/src/mcp/tools/snapshot.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import { executeSnapshot } from '../../commands/snapshot.js';
+import { executeFind } from '../../commands/find.js';
+
+const findShape = {
+  role: z
+    .string()
+    .optional()
+    .describe(
+      'Filter by ARIA role (e.g. button, link, textbox, checkbox, radio, heading)'
+    ),
+  name: z
+    .string()
+    .optional()
+    .describe('Filter by accessible name (substring, case-insensitive)'),
+  text: z
+    .string()
+    .optional()
+    .describe(
+      'Filter by text content — matches name, value, or description (substring, case-insensitive)'
+    )
+};
+
+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 };
+}
+
+export function registerSnapshotTools(
+  server: McpServer,
+  context: BrowserContext
+): void {
+  server.tool(
+    'browser_snapshot',
+    'Capture a structured accessibility snapshot of the current page. Returns interactive and meaningful elements with short refs (e1, e2, ...) that can be used with browser_click and other interaction tools instead of CSS selectors.',
+    {},
+    async () => {
+      const { client, refMap } = requireContext(context);
+      const result = await executeSnapshot(client, refMap);
+      return {
+        content: [{ type: 'text' as const, text: result.text }]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_find',
+    'Find elements in the current page matching a query. Takes a new snapshot and filters by role, name, or text. Returns matching elements with refs.',
+    findShape,
+    async ({ role, name, text }) => {
+      const { client, refMap } = requireContext(context);
+      const result = await executeFind(client, refMap, { role, name, text });
+      return {
+        content: [{ type: 'text' as const, text: result.text }]
+      };
+    }
+  );
+}

package/src/mcp/tools/styles.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import { executeStyles } from '../../commands/styles.js';
+
+const stylesShape = {
+  ref: z.string().describe('Element ref from browser_snapshot (e.g. "e3")'),
+  properties: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'CSS properties to return (e.g. ["display", "color"]). Omit for a default diagnostic set covering layout, visibility, and common properties.'
+    )
+};
+
+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 };
+}
+
+export function registerStylesTools(
+  server: McpServer,
+  context: BrowserContext
+): void {
+  server.tool(
+    'browser_styles',
+    'Inspect computed styles, matched CSS rules, and box model for an element by ref. Helps diagnose visibility issues (display:none, opacity:0), layout problems (margins, positioning, overflow), and identify which CSS rule is responsible for a property. Use browser_snapshot first to get refs.',
+    stylesShape,
+    async ({ ref, properties }) => {
+      const { client, refMap } = requireContext(context);
+      const result = await executeStyles(client, refMap, { ref, properties });
+      return {
+        content: [{ type: 'text' as const, text: result.text }]
+      };
+    }
+  );
+}

package/src/util/config.ts

@@ -9,7 +9,7 @@ const ConfigSchema = z.object({
     .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
     .default('info'),
   chromePath: z.string().optional(),
-  headless: z.boolean().default(true),
+  headless: z.boolean().default(false),
   profileName: z.string().default('profile1'),
   viewport: z.string().default('desktop'),
   responsive: z.boolean().optional()
@@ -44,7 +44,8 @@ export function loadConfig(cliArgs: CliArgs = {}): Config {
     chromePath: process.env.PILOT_CHROME_PATH,
     headless:
       process.env.PILOT_HEADLESS !== undefined
-        ? process.env.PILOT_HEADLESS !== 'false'
+        ? process.env.PILOT_HEADLESS === 'true' ||
+          process.env.PILOT_HEADLESS === '1'
         : undefined,
     profileName: process.env.PILOT_PROFILE_NAME,
     viewport: process.env.PILOT_VIEWPORT,