@everydaydevopsio/pilot 0.5.0

package/src/mcp/tools/errors.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ConsoleBuffer, ConsoleLevel } from '../console-buffer.js';
+
+// Raw shapes for MCP SDK (expects ZodRawShape, not ZodObject)
+
+const getConsoleLogsShape = {
+  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 getErrorsShape = {
+  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')
+};
+
+export function registerErrorTools(
+  server: McpServer,
+  buffer: ConsoleBuffer
+): void {
+  server.tool(
+    'browser_get_console_logs',
+    'Get console log messages from the browser. Use this to see console output during testing.',
+    getConsoleLogsShape,
+    async ({ level, levels, sinceMs, limit }) => {
+      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
+      });
+
+      const total = buffer.size();
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify(
+              {
+                messages,
+                count: messages.length,
+                total,
+                hasMore: total > messages.length
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_get_errors',
+    'Get console errors (and optionally warnings) from the browser. Use this to check for JavaScript errors while testing an application.',
+    getErrorsShape,
+    async ({ sinceMs, limit, includeWarnings }) => {
+      const levels: ConsoleLevel[] = includeWarnings
+        ? ['error', 'warn']
+        : ['error'];
+
+      const errors = buffer.getAll({
+        level: levels,
+        sinceMs,
+        limit
+      });
+
+      const total = buffer.size();
+
+      if (errors.length === 0) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'No errors found.'
+            }
+          ]
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify(
+              {
+                errors,
+                count: errors.length,
+                hasMore: total > errors.length
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_clear_errors',
+    'Clear the console message buffer. Use this before testing to get a clean slate.',
+    {},
+    async () => {
+      const cleared = buffer.clear();
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Cleared ${cleared} console messages.`
+          }
+        ]
+      };
+    }
+  );
+}

package/src/mcp/tools/names.ts

@@ -0,0 +1,25 @@
+/**
+ * Canonical list of MCP tool names registered by this server.
+ * Shared between the smoke test and e2e test suite so both stay in sync.
+ */
+export const EXPECTED_TOOLS = [
+  'browser_start',
+  'browser_stop',
+  'browser_screenshot',
+  'browser_navigate',
+  'browser_click',
+  'browser_type',
+  'browser_evaluate',
+  'browser_wait',
+  'browser_page_info',
+  'browser_list_tabs',
+  'browser_new_tab',
+  'browser_close_tab',
+  'browser_switch_tab',
+  'browser_viewport_resize',
+  'browser_get_console_logs',
+  'browser_get_errors',
+  'browser_clear_errors'
+] as const;
+
+export type ToolName = (typeof EXPECTED_TOOLS)[number];

package/src/util/config.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+
+const ConfigSchema = z.object({
+  cdpPort: z.number().int().min(1).max(65535).default(9222),
+  cdpHost: z.string().default('127.0.0.1'),
+  cdpRetryMs: z.number().int().min(100).default(2000),
+  cdpMaxRetryMs: z.number().int().min(1000).default(30000),
+  logLevel: z
+    .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
+    .default('info'),
+  chromePath: z.string().optional(),
+  headless: z.boolean().default(true),
+  profileName: z.string().default('profile1'),
+  viewport: z.string().default('desktop'),
+  responsive: z.boolean().optional()
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+export interface CliArgs {
+  cdpPort?: number;
+  cdpHost?: string;
+  logLevel?: string;
+  chromePath?: string;
+  headless?: boolean;
+  profileName?: string;
+  viewport?: string;
+  responsive?: boolean;
+}
+
+export function loadConfig(cliArgs: CliArgs = {}): Config {
+  const env = {
+    cdpPort: process.env.PILOT_CDP_PORT
+      ? parseInt(process.env.PILOT_CDP_PORT, 10)
+      : undefined,
+    cdpHost: process.env.PILOT_CDP_HOST,
+    cdpRetryMs: process.env.PILOT_CDP_RETRY_MS
+      ? parseInt(process.env.PILOT_CDP_RETRY_MS, 10)
+      : undefined,
+    cdpMaxRetryMs: process.env.PILOT_CDP_MAX_RETRY_MS
+      ? parseInt(process.env.PILOT_CDP_MAX_RETRY_MS, 10)
+      : undefined,
+    logLevel: process.env.PILOT_LOG_LEVEL,
+    chromePath: process.env.PILOT_CHROME_PATH,
+    headless:
+      process.env.PILOT_HEADLESS !== undefined
+        ? process.env.PILOT_HEADLESS !== 'false'
+        : undefined,
+    profileName: process.env.PILOT_PROFILE_NAME,
+    viewport: process.env.PILOT_VIEWPORT,
+    responsive:
+      process.env.PILOT_RESPONSIVE !== undefined
+        ? process.env.PILOT_RESPONSIVE !== 'false'
+        : undefined
+  };
+
+  const merged = {
+    cdpPort: cliArgs.cdpPort ?? env.cdpPort,
+    cdpHost: cliArgs.cdpHost ?? env.cdpHost,
+    cdpRetryMs: env.cdpRetryMs,
+    cdpMaxRetryMs: env.cdpMaxRetryMs,
+    logLevel: cliArgs.logLevel ?? env.logLevel,
+    chromePath: cliArgs.chromePath ?? env.chromePath,
+    headless: cliArgs.headless ?? env.headless,
+    profileName: cliArgs.profileName ?? env.profileName,
+    viewport: cliArgs.viewport ?? env.viewport,
+    responsive: cliArgs.responsive ?? env.responsive
+  };
+
+  return ConfigSchema.parse(merged);
+}

package/src/util/logger.ts

@@ -0,0 +1,18 @@
+import pino from 'pino';
+
+let _logger: pino.Logger | null = null;
+
+export function createLogger(level = 'info'): pino.Logger {
+  // Always write to stderr: this is an MCP server that communicates over stdio,
+  // so stdout must carry only MCP protocol messages. pino-pretty is a
+  // devDependency and is not available in production/global installs.
+  _logger = pino({ level }, process.stderr);
+  return _logger;
+}
+
+export function getLogger(): pino.Logger {
+  if (!_logger) {
+    _logger = createLogger();
+  }
+  return _logger;
+}

package/src/viewport.ts

@@ -0,0 +1,204 @@
+import type { Client } from 'chrome-remote-interface';
+
+interface EmulationDomain {
+  setDeviceMetricsOverride(params: {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    mobile: boolean;
+  }): Promise<void>;
+  setTouchEmulationEnabled(params: {
+    enabled: boolean;
+    maxTouchPoints?: number;
+  }): Promise<void>;
+  setUserAgentOverride(params: { userAgent: string }): Promise<void>;
+}
+
+interface BrowserDomain {
+  getWindowForTarget(params?: {
+    targetId?: string;
+  }): Promise<{ windowId: number }>;
+  setWindowBounds(params: {
+    windowId: number;
+    bounds: { width?: number; height?: number };
+  }): Promise<void>;
+}
+
+export interface ViewportConfig {
+  width: number;
+  height: number;
+  deviceScaleFactor: number;
+  mobile: boolean;
+  userAgent?: string;
+  responsive?: boolean;
+}
+
+const MOBILE_USER_AGENT =
+  'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Mobile Safari/537.36';
+
+export const VIEWPORT_PRESETS = {
+  desktop: {
+    width: 1920,
+    height: 1080,
+    deviceScaleFactor: 1,
+    mobile: false,
+    responsive: true
+  },
+  'desktop-small': {
+    width: 1366,
+    height: 768,
+    deviceScaleFactor: 1,
+    mobile: false,
+    responsive: true
+  },
+  tablet: {
+    width: 768,
+    height: 1024,
+    deviceScaleFactor: 2,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  },
+  'tablet-landscape': {
+    width: 1024,
+    height: 768,
+    deviceScaleFactor: 2,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  },
+  mobile: {
+    width: 390,
+    height: 844,
+    deviceScaleFactor: 3,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  },
+  'mobile-landscape': {
+    width: 844,
+    height: 390,
+    deviceScaleFactor: 3,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  },
+  'mobile-small': {
+    width: 360,
+    height: 800,
+    deviceScaleFactor: 3,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  },
+  'desktop-scaled': {
+    width: 1536,
+    height: 864,
+    deviceScaleFactor: 1.25,
+    mobile: false
+  },
+  'desktop-qhd': {
+    width: 2560,
+    height: 1440,
+    deviceScaleFactor: 1,
+    mobile: false,
+    responsive: true
+  },
+  'mobile-pro': {
+    width: 393,
+    height: 852,
+    deviceScaleFactor: 3,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  },
+  'mobile-large': {
+    width: 430,
+    height: 932,
+    deviceScaleFactor: 3,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  },
+  'mobile-android': {
+    width: 412,
+    height: 915,
+    deviceScaleFactor: 2.625,
+    mobile: true,
+    userAgent: MOBILE_USER_AGENT
+  }
+} satisfies Record<string, ViewportConfig>;
+
+export type ViewportPresetName = keyof typeof VIEWPORT_PRESETS;
+
+export interface ResolveViewportOptions {
+  preset?: string;
+  width?: number;
+  height?: number;
+  deviceScaleFactor?: number;
+  responsive?: boolean;
+}
+
+export function resolveViewport(
+  opts: ResolveViewportOptions = {}
+): ViewportConfig {
+  const presetName = opts.preset ?? 'desktop';
+  const presets = VIEWPORT_PRESETS as Record<string, ViewportConfig>;
+  const base = presets[presetName];
+  if (!base) {
+    const valid = Object.keys(VIEWPORT_PRESETS).join(', ');
+    throw new Error(
+      `Unknown viewport preset "${presetName}". Valid presets: ${valid}`
+    );
+  }
+
+  return {
+    ...base,
+    ...(opts.width !== undefined && { width: opts.width }),
+    ...(opts.height !== undefined && { height: opts.height }),
+    ...(opts.deviceScaleFactor !== undefined && {
+      deviceScaleFactor: opts.deviceScaleFactor
+    }),
+    ...(opts.responsive !== undefined && { responsive: opts.responsive })
+  };
+}
+
+export async function applyViewport(
+  client: Client,
+  config: ViewportConfig
+): Promise<void> {
+  const emulation = client.Emulation as unknown as EmulationDomain;
+  const browser = client.Browser as unknown as BrowserDomain;
+
+  // Resize the actual browser window so it matches the viewport dimensions.
+  // This is needed because --window-size is unreliable (Chrome may restore
+  // a previous size from the profile) and setDeviceMetricsOverride only
+  // overrides the rendering viewport, not the window itself.
+  try {
+    const { windowId } = await browser.getWindowForTarget();
+    await browser.setWindowBounds({
+      windowId,
+      bounds: { width: config.width, height: config.height }
+    });
+  } catch {
+    // Best-effort: headless Chrome or older versions may not support this.
+  }
+
+  // In responsive mode, skip setDeviceMetricsOverride so the page uses the
+  // real window dimensions and reflows naturally when the window is resized
+  // — just like a normal browser. This is the default for desktop presets.
+  if (!config.responsive) {
+    await emulation.setDeviceMetricsOverride({
+      width: config.width,
+      height: config.height,
+      deviceScaleFactor: config.deviceScaleFactor,
+      mobile: config.mobile
+    });
+  }
+
+  if (config.mobile) {
+    await emulation.setTouchEmulationEnabled({
+      enabled: true,
+      maxTouchPoints: 5
+    });
+  }
+
+  if (config.userAgent) {
+    await emulation.setUserAgentOverride({
+      userAgent: config.userAgent
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "test", "e2e"]
+}