mcpbrowser 0.3.35 → 0.3.36

package/src/plugins/gcal/helpers.js

@@ -0,0 +1,415 @@
+/**
+ * helpers.js — Shared tiered utilities for the Google Calendar plugin.
+ *
+ * Provides URL-based navigation (T1), keyboard shortcut verification (T2),
+ * ARIA/data-attr DOM utilities (T3), and CSS-selector data extraction (T4).
+ *
+ * All helpers are stateless — they inspect the page at invocation time
+ * per FR-017. No internal state is maintained between calls.
+ */
+
+import { MCPResponse } from '../../core/responses.js';
+import * as sel from './selectors.js';
+import logger from '../../core/logger.js';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Maximum wait time for dynamic content (FR-012). */
+export const DEFAULT_TIMEOUT = 10_000;
+
+/** Calendar view states detected by detectView(). */
+export const VIEW = Object.freeze({
+  DAY: 'day',
+  WEEK: 'week',
+  MONTH: 'month',
+  SCHEDULE: 'schedule',
+  CUSTOM: 'custom',
+  EVENT_DETAIL: 'event_detail',
+  EVENT_FORM: 'event_form',
+  SEARCH_RESULTS: 'search_results',
+  LOADING: 'loading',
+  NOT_CALENDAR: 'not_calendar',
+  NOT_READY: 'not_ready'
+});
+
+/** Map param view names to URL path segments. */
+const VIEW_TO_PATH = {
+  day: 'day',
+  week: 'week',
+  month: 'month',
+  schedule: 'agenda',
+  custom: 'customday'
+};
+
+// ============================================================================
+// T1: URL-BASED NAVIGATION (FR-019)
+// ============================================================================
+
+/**
+ * Extract the Google account index (/u/N/) from a URL.
+ * Returns '0' if not found. Shared with Gmail plugin pattern.
+ */
+export function getAccountIndex(url) {
+  const match = url.match(/\/u\/(\d+)\//);
+  return match ? match[1] : '0';
+}
+
+/**
+ * Navigate Google Calendar to a specific path while preserving account index.
+ * @param {import('puppeteer').Page} page
+ * @param {string} path — e.g. 'r/day/2026/4/6', 'r/week', 'r/search'
+ */
+export async function calendarNavigate(page, path) {
+  const currentUrl = page.url();
+  const accountIndex = getAccountIndex(currentUrl);
+  const targetUrl = `https://calendar.google.com/calendar/u/${accountIndex}/${path}`;
+  logger.debug(`calendarNavigate: ${targetUrl}`);
+  await page.goto(targetUrl, { waitUntil: 'networkidle2', timeout: DEFAULT_TIMEOUT });
+}
+
+/**
+ * Build url path for a date in a given view.
+ * @param {string} view — 'day', 'week', 'month'
+ * @param {string} [date] — ISO date string, e.g. '2026-04-10'
+ * @returns {string} path segment, e.g. 'r/day/2026/4/10'
+ */
+export function buildViewPath(view, date) {
+  const pathView = VIEW_TO_PATH[view] || view;
+  if (date) {
+    // Parse ISO date string directly to avoid timezone issues
+    const parts = date.split('-');
+    const y = parseInt(parts[0], 10);
+    const m = parseInt(parts[1], 10);
+    const day = parseInt(parts[2], 10);
+    return `r/${pathView}/${y}/${m}/${day}`;
+  }
+  return `r/${pathView}`;
+}
+
+// ============================================================================
+// VIEW DETECTION (FR-017, FR-024 — URL path primary, DOM fallback)
+// ============================================================================
+
+/**
+ * Detect the current Google Calendar view from URL and DOM.
+ * @param {import('puppeteer').Page} page
+ * @returns {Promise<string>} One of the VIEW enum values.
+ */
+export async function detectView(page) {
+  const url = page.url();
+
+  if (!url.includes('calendar.google.com')) {
+    logger.debug('detectView: not Calendar');
+    return VIEW.NOT_CALENDAR;
+  }
+
+  // Check for interstitials / CAPTCHAs
+  const hasInterstitial = await page.evaluate(() => {
+    const body = document.body?.textContent || '';
+    return body.includes('Confirm it') ||
+           !!document.querySelector('iframe[src*="accounts.google.com"]') ||
+           !!document.querySelector('#captcha');
+  });
+  if (hasInterstitial) {
+    logger.debug('detectView: not_ready (interstitial/CAPTCHA)');
+    return VIEW.NOT_READY;
+  }
+
+  // URL path-based detection (primary signal)
+  const pathMatch = url.match(/\/r\/([a-z]+)/i);
+  const pathSegment = pathMatch ? pathMatch[1].toLowerCase() : '';
+
+  if (pathSegment === 'eventedit') {
+    logger.debug('detectView: event_form');
+    return VIEW.EVENT_FORM;
+  }
+  if (pathSegment === 'search') {
+    logger.debug('detectView: search_results');
+    return VIEW.SEARCH_RESULTS;
+  }
+  if (pathSegment === 'day') {
+    logger.debug('detectView: day');
+    return VIEW.DAY;
+  }
+  if (pathSegment === 'week') {
+    logger.debug('detectView: week');
+    return VIEW.WEEK;
+  }
+  if (pathSegment === 'month') {
+    logger.debug('detectView: month');
+    return VIEW.MONTH;
+  }
+  if (pathSegment === 'agenda' || pathSegment === 'list') {
+    logger.debug('detectView: schedule');
+    return VIEW.SCHEDULE;
+  }
+  if (pathSegment === 'customday') {
+    logger.debug('detectView: custom');
+    return VIEW.CUSTOM;
+  }
+
+  // Check for event detail dialog overlay
+  const hasEventDialog = await page.evaluate(() =>
+    !!document.querySelector('div[role="dialog"]')
+  );
+  if (hasEventDialog) {
+    logger.debug('detectView: event_detail (dialog overlay)');
+    return VIEW.EVENT_DETAIL;
+  }
+
+  // Default calendar view (e.g. /r or /r/)
+  const hasMain = await page.evaluate(() =>
+    !!document.querySelector('div[role="main"]')
+  );
+  if (hasMain) {
+    logger.debug('detectView: week (default fallback)');
+    return VIEW.WEEK;
+  }
+
+  logger.debug('detectView: loading (no main container)');
+  return VIEW.LOADING;
+}
+
+// ============================================================================
+// T2: KEYBOARD SHORTCUT VERIFICATION (FR-018)
+// ============================================================================
+
+/**
+ * Check if Google Calendar keyboard shortcuts are enabled by sending '?'.
+ * @param {import('puppeteer').Page} page
+ * @returns {Promise<{enabled: boolean, error?: string}>}
+ */
+export async function checkKeyboardShortcuts(page) {
+  try {
+    // Ensure nothing is focused that would swallow the keystroke
+    await page.evaluate(() => {
+      if (document.activeElement && document.activeElement.tagName !== 'BODY') {
+        document.activeElement.blur();
+      }
+    });
+
+    await page.keyboard.down('Shift');
+    await page.keyboard.press('/');
+    await page.keyboard.up('Shift');
+
+    const dialog = await page.waitForSelector(
+      'div[role="dialog"]',
+      { timeout: 2000 }
+    ).catch(() => null);
+
+    if (dialog) {
+      await page.keyboard.press('Escape');
+      return { enabled: true };
+    }
+
+    return {
+      enabled: false,
+      error: 'Google Calendar keyboard shortcuts are not enabled. Enable them in Calendar Settings → Keyboard shortcuts → Enable keyboard shortcuts.'
+    };
+  } catch {
+    return {
+      enabled: false,
+      error: 'Could not verify Google Calendar keyboard shortcuts. Ensure Calendar is fully loaded.'
+    };
+  }
+}
+
+// ============================================================================
+// PRECONDITION CHECKING (FR-022)
+// ============================================================================
+
+/**
+ * Check a precondition before performing an action.
+ * @param {import('puppeteer').Page} page
+ * @param {string} requirement — 'on_calendar', 'event_visible', 'list_view'
+ * @returns {Promise<{met: boolean, error?: string, suggestion?: string}>}
+ */
+export async function checkPrecondition(page, requirement) {
+  const url = page.url();
+
+  switch (requirement) {
+    case 'on_calendar': {
+      if (!url.includes('calendar.google.com')) {
+        return {
+          met: false,
+          error: 'Google Calendar is not the active page.',
+          suggestion: "Use fetch_webpage({ url: 'https://calendar.google.com' }) to navigate to Google Calendar first."
+        };
+      }
+      return { met: true };
+    }
+
+    case 'event_visible': {
+      const view = await detectView(page);
+      if (view === VIEW.NOT_CALENDAR || view === VIEW.NOT_READY || view === VIEW.LOADING) {
+        return {
+          met: false,
+          error: 'Google Calendar is not ready.',
+          suggestion: "Use fetch_webpage({ url: 'https://calendar.google.com' }) to navigate to Google Calendar."
+        };
+      }
+      return { met: true };
+    }
+
+    case 'list_view': {
+      const view = await detectView(page);
+      const isListView = [VIEW.DAY, VIEW.WEEK, VIEW.MONTH, VIEW.SCHEDULE, VIEW.CUSTOM, VIEW.SEARCH_RESULTS].includes(view);
+      if (!isListView) {
+        return {
+          met: false,
+          error: 'Not in a calendar view with visible events.',
+          suggestion: "Use list_events to navigate to a calendar view."
+        };
+      }
+      return { met: true };
+    }
+
+    default:
+      return { met: false, error: `Unknown precondition: ${requirement}` };
+  }
+}
+
+// ============================================================================
+// CONTENT WAITING (FR-012 — 10s timeout with diagnostics)
+// ============================================================================
+
+/**
+ * Wait for a selector to appear on the page.
+ * @param {import('puppeteer').Page} page
+ * @param {string} selector
+ * @param {number} [timeout=DEFAULT_TIMEOUT]
+ */
+export async function waitForCalendar(page, selector, timeout = DEFAULT_TIMEOUT) {
+  try {
+    await page.waitForSelector(selector, { timeout });
+  } catch {
+    throw new Error(
+      `Google Calendar content did not load within ${timeout}ms. ` +
+      `Selector that failed: "${selector}". ` +
+      `The page may still be loading or Calendar's UI may have changed.`
+    );
+  }
+}
+
+// ============================================================================
+// EVENT SELECTION — Hybrid DOM+keyboard (FR-016)
+// ============================================================================
+
+/**
+ * Select (click) an event by index or event ID.
+ * @param {import('puppeteer').Page} page
+ * @param {{index?: number, id?: string}} options
+ * @returns {Promise<{selected: boolean, error?: string}>}
+ */
+export async function selectEvent(page, { index, id } = {}) {
+  // Try by event ID first (more stable)
+  if (id !== undefined && id !== null) {
+    const event = await page.$(`[data-eventid="${id}"]`);
+    if (event) {
+      await event.click();
+      logger.debug(`selectEvent: selected by ID "${id}"`);
+      return { selected: true };
+    }
+    logger.debug(`selectEvent: ID "${id}" not found, trying index fallback`);
+  }
+
+  // Fall back to index-based selection
+  if (index !== undefined && index !== null) {
+    const events = await page.$$(sel.EVENT_CHIP);
+    if (index >= 0 && index < events.length) {
+      await events[index].click();
+      logger.debug(`selectEvent: selected by index ${index}`);
+      return { selected: true };
+    }
+    return {
+      selected: false,
+      error: `Event index ${index} is out of range. The current view has ${events.length} events (indices 0-${events.length - 1}). Use list_events to refresh.`
+    };
+  }
+
+  return { selected: false, error: 'No index or id provided for event selection.' };
+}
+
+// ============================================================================
+// EVENT EXTRACTION — T3+T4 data extraction
+// ============================================================================
+
+/**
+ * Extract visible events from the current Calendar view.
+ * Returns EventSummary objects per data-model.md.
+ * @param {import('puppeteer').Page} page
+ * @param {number} [limit=25]
+ * @returns {Promise<Array>}
+ */
+export async function extractVisibleEvents(page, limit = 25) {
+  return page.evaluate((selectors, lim) => {
+    const chips = document.querySelectorAll(selectors.eventChip);
+    const results = [];
+    const count = Math.min(chips.length, lim);
+
+    for (let i = 0; i < count; i++) {
+      const chip = chips[i];
+
+      // T3: aria-label is the primary extraction method for event data
+      const ariaLabel = chip.getAttribute('aria-label') || '';
+
+      // T3: data-eventid for stable identification
+      const eventId = chip.getAttribute('data-eventid') || null;
+
+      // Parse aria-label — typically "Title, date, time – time, calendar"
+      // This is a best-effort parse; structure varies by locale
+      const title = ariaLabel.split(',')[0]?.trim() || '';
+
+      // T4: CSS fallback for time and calendar info
+      const timeSpans = chip.querySelectorAll(selectors.timeSpan);
+      const timeText = timeSpans.length > 0 ? timeSpans[0]?.textContent?.trim() || '' : '';
+
+      // Detect all-day by checking if event lacks specific time text
+      const allDay = !timeText || timeText === '';
+
+      results.push({
+        index: i,
+        eventId,
+        title,
+        startDate: '', // Populated from date context outside evaluate
+        startTime: allDay ? null : timeText.split('–')[0]?.trim() || null,
+        endDate: '',
+        endTime: allDay ? null : timeText.split('–')[1]?.trim() || null,
+        allDay,
+        location: null, // Only available in detail view
+        calendarName: '', // Extracted from color dot or aria-label suffix
+        calendarColor: null
+      });
+    }
+    return results;
+  }, {
+    eventChip: sel.EVENT_CHIP,
+    timeSpan: sel.EVENT_TIME_IN_CHIP
+  }, limit);
+}
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Google Calendar plugin response — extends MCPResponse with data spreading.
+ * Mirrors GmailActionResponse pattern.
+ */
+export class GCalActionResponse extends MCPResponse {
+  constructor(data, summary, nextSteps) {
+    super(nextSteps);
+    this.data = data;
+    this._summary = summary;
+  }
+
+  _getAdditionalFields() {
+    return { ...this.data };
+  }
+
+  getTextSummary() {
+    return this._summary;
+  }
+}

package/src/plugins/gcal/index.js

@@ -0,0 +1,148 @@
+/**
+ * Google Calendar plugin — Site-specific automation for Google Calendar (calendar.google.com).
+ * Implements the MCPBrowser plugin interface (interfaceVersion 1).
+ *
+ * Uses a tiered interaction strategy (FR-011):
+ *   T1: URL path navigation for views/dates
+ *   T2: Keyboard shortcuts for actions (create, delete, view switches)
+ *   T3: ARIA / data attributes for data extraction and form filling
+ *   T4: CSS class selectors (last resort, centralized in selectors.js)
+ */
+
+import { listEvents } from './actions/list-events.js';
+import { readEvent } from './actions/read-event.js';
+import { createEvent } from './actions/create-event.js';
+import { searchEvents } from './actions/search-events.js';
+import { editEvent } from './actions/edit-event.js';
+import { rsvpEvent } from './actions/rsvp-event.js';
+import { deleteEvent } from './actions/delete-event.js';
+import { checkAvailability } from './actions/check-availability.js';
+
+export const manifest = {
+  name: "gcal",
+  version: "1.0.0",
+  description: "Google Calendar plugin for MCPBrowser — event management, scheduling, and availability with hybrid UI resilience (URL navigation, keyboard shortcuts, ARIA selectors, CSS fallback)",
+  interfaceVersion: 1,
+  urlPatterns: ["calendar.google.com"],
+  domPatterns: ["div[role=\"main\"]", "[data-eventchip]"]
+};
+
+export function matchesPage(url, html) {
+  try {
+    if (url && url.includes('calendar.google.com')) {
+      return { matched: true, confidence: 1.0 };
+    }
+    if (html && (html.includes('data-eventchip') || html.includes('data-datekey'))) {
+      return { matched: true, confidence: 0.8 };
+    }
+    return { matched: false };
+  } catch {
+    return { matched: false };
+  }
+}
+
+export function getActions() {
+  return [
+    {
+      name: "list_events",
+      description: "List visible events from the current Google Calendar view",
+      params: [
+        { name: "date", type: "string", description: "ISO date to navigate to (e.g., '2026-04-10'). If omitted, uses current view.", required: false },
+        { name: "view", type: "string", description: "Calendar view: day, week, month, schedule. If omitted, uses current view.", required: false },
+        { name: "limit", type: "number", description: "Maximum number of events to return (default: 25)", required: false, default: 25 }
+      ],
+      execute: listEvents
+    },
+    {
+      name: "read_event",
+      description: "Open an event and read its full details (attendees, description, conferencing link)",
+      params: [
+        { name: "index", type: "number", description: "0-based position in current event list", required: false },
+        { name: "id", type: "string", description: "Google Calendar event ID", required: false }
+      ],
+      execute: readEvent
+    },
+    {
+      name: "create_event",
+      description: "Create a new calendar event with title, time, location, description, and attendees",
+      params: [
+        { name: "title", type: "string", description: "Event title", required: true },
+        { name: "date", type: "string", description: "Event date (ISO format, e.g., '2026-04-07'). Default: today", required: false },
+        { name: "startTime", type: "string", description: "Start time in HH:MM format. Ignored if allDay:true", required: false },
+        { name: "endTime", type: "string", description: "End time in HH:MM format. Ignored if allDay:true", required: false },
+        { name: "allDay", type: "boolean", description: "Create an all-day event", required: false, default: false },
+        { name: "location", type: "string", description: "Event location", required: false },
+        { name: "description", type: "string", description: "Event description/notes", required: false },
+        { name: "attendees", type: "array", description: "Array of attendee email addresses", required: false },
+        { name: "save", type: "boolean", description: "If true, save the event. Default: false (leave for review)", required: false, default: false }
+      ],
+      execute: createEvent
+    },
+    {
+      name: "search_events",
+      description: "Search Google Calendar for events matching a keyword query",
+      params: [
+        { name: "query", type: "string", description: "Search keywords", required: true },
+        { name: "limit", type: "number", description: "Maximum results to return (default: 25)", required: false, default: 25 }
+      ],
+      execute: searchEvents
+    },
+    {
+      name: "edit_event",
+      description: "Modify an existing event's fields (time, title, location, description, attendees)",
+      params: [
+        { name: "index", type: "number", description: "0-based position in current event list", required: false },
+        { name: "id", type: "string", description: "Google Calendar event ID", required: false },
+        { name: "title", type: "string", description: "New title", required: false },
+        { name: "date", type: "string", description: "New date (ISO format)", required: false },
+        { name: "startTime", type: "string", description: "New start time (HH:MM)", required: false },
+        { name: "endTime", type: "string", description: "New end time (HH:MM)", required: false },
+        { name: "location", type: "string", description: "New location", required: false },
+        { name: "description", type: "string", description: "New description", required: false },
+        { name: "attendees", type: "array", description: "New attendee list (replaces existing)", required: false },
+        { name: "allDay", type: "boolean", description: "Toggle all-day", required: false },
+        { name: "save", type: "boolean", description: "If true, save changes. Default: false", required: false, default: false }
+      ],
+      execute: editEvent
+    },
+    {
+      name: "rsvp_event",
+      description: "Respond to a calendar invitation (accept, decline, or tentative)",
+      params: [
+        { name: "index", type: "number", description: "0-based position in current event list", required: false },
+        { name: "id", type: "string", description: "Google Calendar event ID", required: false },
+        { name: "response", type: "string", description: "RSVP response: accept, decline, or tentative", required: true }
+      ],
+      execute: rsvpEvent
+    },
+    {
+      name: "delete_event",
+      description: "Remove an event from Google Calendar",
+      params: [
+        { name: "index", type: "number", description: "0-based position in current event list", required: false },
+        { name: "id", type: "string", description: "Google Calendar event ID", required: false }
+      ],
+      execute: deleteEvent
+    },
+    {
+      name: "check_availability",
+      description: "Check whether a time slot is free or busy on the calendar",
+      params: [
+        { name: "date", type: "string", description: "ISO date to check (required)", required: true },
+        { name: "startTime", type: "string", description: "Window start time in HH:MM format (required)", required: true },
+        { name: "endTime", type: "string", description: "Window end time in HH:MM format (required)", required: true }
+      ],
+      execute: checkAvailability
+    }
+  ];
+}
+
+export function getInfo() {
+  return {
+    recommendation: "Manage Google Calendar — list, read, create, search, edit, RSVP, delete events and check availability.",
+    description: "Google Calendar event management with hybrid UI resilience — list, read, create, search, edit, RSVP, delete events and check availability using URL navigation (T1), keyboard shortcuts (T2), ARIA selectors (T3), and CSS fallback (T4).",
+    targetPages: ["Google Calendar (calendar.google.com)"],
+    authFlow: "User must be signed into Google Calendar in the browser before using plugin actions. Keyboard shortcuts must be enabled in Calendar Settings.",
+    actions: getActions().map(({ name, description, params }) => ({ name, description, params }))
+  };
+}

package/src/plugins/gcal/selectors.js

@@ -0,0 +1,54 @@
+/**
+ * selectors.js — Tier 4 CSS class selectors for the Google Calendar plugin.
+ *
+ * TIER 4 ONLY — These are Closure Compiler-generated class names that may
+ * change when Google deploys Calendar updates. All other interaction tiers
+ * (T1: URL path navigation, T2: keyboard shortcuts, T3: ARIA / data attributes)
+ * are defined inline in helpers.js since they use stable identifiers.
+ *
+ * Per FR-021: All CSS class selectors are centralized here so a Calendar UI
+ * update can be resolved by updating values in ONE place.
+ *
+ * Per SC-008: No action file should import CSS class names directly.
+ * All CSS access goes through this module.
+ *
+ * Tier coverage (SC-007): ~75% of interactions use T1/T2 (URL + keyboard).
+ * These T4 selectors cover only data extraction from event chips and detail
+ * popups where no ARIA/data-attribute alternative exists.
+ *
+ * @version 2026-04-06 — Initial capture against Google Calendar web UI
+ */
+
+// CALENDAR VIEW — Event chips (used by extractVisibleEvents)
+// No ARIA alternative: event chip container uses generated classes
+export const EVENT_CHIP = '[data-eventchip]';
+// No ARIA alternative: title text within chip is plain span
+export const EVENT_TITLE_IN_CHIP = 'span';
+// No ARIA alternative: time text within chip lacks data attributes
+export const EVENT_TIME_IN_CHIP = 'span';
+
+// EVENT DETAIL POPUP — Fields in the detail popup (used by read_event)
+// No ARIA alternative: location line lacks role/data attributes
+export const EVENT_LOCATION_IN_DETAIL = '[data-location]';
+// No ARIA alternative: description area uses contenteditable without data-attr
+export const EVENT_DESCRIPTION_IN_DETAIL = '[data-description]';
+
+// ATTENDEES — Within event detail popup (used by read_event, rsvp_event)
+// No ARIA alternative: attendee rows lack role="listitem"
+export const ATTENDEE_ROW = '[data-guest-email]';
+// No ARIA alternative: RSVP icons use generated classes
+export const ATTENDEE_RSVP_STATUS = '[data-rsvp]';
+
+// RSVP BUTTONS — Within event detail popup (used by rsvp_event)
+// No ARIA alternative: RSVP buttons lack unique aria-label
+export const RSVP_YES_BUTTON = '[data-response="1"]';
+export const RSVP_NO_BUTTON = '[data-response="2"]';
+export const RSVP_MAYBE_BUTTON = '[data-response="3"]';
+
+// CALENDAR INDICATOR — Color dot on event chips
+// No ARIA alternative: color indicator is CSS-only
+export const CALENDAR_COLOR_DOT = '[data-calendar-color]';
+
+// FORM CONTROLS — Event creation/edit form (used by create_event, edit_event)
+// No ARIA alternative: save button lacks unique accessible name
+export const SAVE_BUTTON = '[data-savebtn]';

package/src/plugins/gmail/index.js

@@ -186,6 +186,7 @@ export function getActions() {
  */
 export function getInfo() {
   return {
+    recommendation: "Manage Gmail emails — list, read, search, compose, reply, forward, archive, delete, label, and mark as read/unread.",
     description: "Gmail email management with hybrid UI resilience — list, read, search, compose, reply, forward, archive, delete, label, and mark emails using URL navigation (T1), keyboard shortcuts (T2), ARIA selectors (T3), and CSS fallback (T4).",
     targetPages: ["Gmail inbox (mail.google.com)"],
     authFlow: "User must be signed into Gmail in the browser before using plugin actions. The plugin does not handle Google account authentication.",

package/src/plugins.json

@@ -1,3 +1,4 @@
 {
-  "enabled": ["gmail"]
+  "enabled": [],
+  "enabled_no": ["gmail", "gcal"]
 }