mcpbrowser 0.3.34 → 0.3.35

package/src/plugins/gmail/actions/read-email.js

@@ -0,0 +1,149 @@
+/**
+ * read-email.js — Open and read a specific email thread.
+ *
+ * Tier usage:
+ *   T1: gmailNavigate to thread by ID hash
+ *   T2: keyboard shortcut 'o' to open selected row
+ *   T3: span[email] for sender extraction
+ *   T4: MESSAGE_CONTAINER, MSG_BODY, MSG_DATE, THREAD_SUBJECT, ATTACHMENT_* selectors
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import {
+  checkPrecondition,
+  gmailNavigate,
+  checkKeyboardShortcuts,
+  selectEmailRow,
+  waitForGmail,
+  GmailActionResponse
+} from '../helpers.js';
+import {
+  THREAD_SUBJECT,
+  MESSAGE_CONTAINER,
+  MSG_BODY,
+  MSG_DATE,
+  ATTACHMENT_AREA,
+  ATTACHMENT_NAME,
+  ATTACHMENT_SIZE
+} from '../selectors.js';
+
+/**
+ * Open and read a specific email by ID or list index.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} [opts.params.id] - Gmail thread/message ID
+ * @param {number} [opts.params.index] - Positional index in current list view
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function readEmail({ page, params }) {
+  if (params.id == null && params.index == null) {
+    return new ErrorResponse(
+      'Either id or index is required to read an email.',
+      [
+        'Use list_emails to see available emails and their indices',
+        'Use search_emails to find a specific email by keyword'
+      ]
+    );
+  }
+
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  if (params.id) {
+    // T1: Navigate directly to thread by ID
+    await gmailNavigate(page, '#inbox/' + params.id);
+  } else {
+    // T2: Select row by index, then open with keyboard shortcut
+    const kb = await checkKeyboardShortcuts(page);
+    if (!kb.enabled) {
+      return new ErrorResponse(
+        kb.error || 'Keyboard shortcuts are not enabled in Gmail.',
+        ['Enable keyboard shortcuts in Gmail Settings → General → Keyboard shortcuts → ON, then reload Gmail.']
+      );
+    }
+
+    const sel = await selectEmailRow(page, { index: params.index });
+    if (!sel.selected) {
+      return new ErrorResponse(
+        sel.error || `Could not select email at index ${params.index}.`,
+        ['Use list_emails to check available email indices']
+      );
+    }
+
+    // T2: Press 'o' to open the selected email
+    await page.keyboard.press('o');
+  }
+
+  // Wait for thread content to load
+  await waitForGmail(page, THREAD_SUBJECT);
+
+  // T3+T4: Extract thread data from DOM
+  const thread = await page.evaluate((selectors) => {
+    const subjectEl = document.querySelector(selectors.threadSubject);
+    const subject = subjectEl?.textContent?.trim() || '';
+
+    const containers = document.querySelectorAll(selectors.messageContainer);
+    const messages = [];
+
+    for (const container of containers) {
+      // T3: span[email] for sender info
+      const senderEl = container.querySelector('span[email]');
+      const sender = senderEl?.getAttribute('name') || senderEl?.textContent?.trim() || '';
+      const senderEmail = senderEl?.getAttribute('email') || '';
+
+      // T4: CSS selectors for body, date, attachments
+      const bodyEl = container.querySelector(selectors.msgBody);
+      const body = bodyEl?.textContent?.trim() || '';
+
+      const dateEl = container.querySelector(selectors.msgDate);
+      const date = dateEl?.getAttribute('title') || dateEl?.textContent?.trim() || '';
+
+      const attachments = [];
+      const attachArea = container.querySelector(selectors.attachmentArea);
+      if (attachArea) {
+        const nameEls = attachArea.querySelectorAll(selectors.attachmentName);
+        const sizeEls = attachArea.querySelectorAll(selectors.attachmentSize);
+        for (let i = 0; i < nameEls.length; i++) {
+          attachments.push({
+            name: nameEls[i]?.textContent?.trim() || '',
+            size: sizeEls[i]?.textContent?.trim() || ''
+          });
+        }
+      }
+
+      messages.push({ sender, senderEmail, date, body, attachments });
+    }
+
+    // Attempt to extract thread ID from URL hash
+    const hash = window.location.hash || '';
+    const idMatch = hash.match(/\/([A-Za-z0-9]+)$/);
+    const id = idMatch ? idMatch[1] : undefined;
+
+    return { id, subject, messageCount: messages.length, messages };
+  }, {
+    threadSubject: THREAD_SUBJECT,
+    messageContainer: MESSAGE_CONTAINER,
+    msgBody: MSG_BODY,
+    msgDate: MSG_DATE,
+    attachmentArea: ATTACHMENT_AREA,
+    attachmentName: ATTACHMENT_NAME,
+    attachmentSize: ATTACHMENT_SIZE
+  });
+
+  return new GmailActionResponse(
+    { thread },
+    `Email: "${thread.subject}" — ${thread.messageCount} message(s).`,
+    [
+      'Use reply_email to respond',
+      'Use forward_email to forward',
+      'Use archive_email to archive',
+      'Use list_emails to return to inbox'
+    ]
+  );
+}

package/src/plugins/gmail/actions/reply-email.js

@@ -0,0 +1,87 @@
+/**
+ * reply-email.js — Reply (or reply-all) to the currently open email thread.
+ *
+ * Tier usage:
+ *   T2: 'r' for reply, 'a' for reply-all, Ctrl+Enter to send
+ *   T3: div[aria-label="Message Body"] for reply editor
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  checkKeyboardShortcuts,
+  waitForGmail,
+  GmailActionResponse
+} from '../helpers.js';
+
+/**
+ * Reply to the currently open thread.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} [opts.params.body] - Reply body text
+ * @param {boolean} [opts.params.replyAll] - If true, reply-all
+ * @param {boolean} [opts.params.send] - If true, send immediately
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function replyEmail({ page, params }) {
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  // Precondition: must have a thread open
+  const threadPre = await checkPrecondition(page, 'thread_open');
+  if (!threadPre.met) {
+    return new ErrorResponse(threadPre.error, [
+      threadPre.suggestion || "Use read_email to open an email thread first."
+    ]);
+  }
+
+  // Verify keyboard shortcuts are enabled
+  const kb = await checkKeyboardShortcuts(page);
+  if (!kb.enabled) {
+    return new ErrorResponse(kb.error, [
+      'Enable keyboard shortcuts in Gmail Settings → General → Keyboard shortcuts → ON, then reload Gmail.'
+    ]);
+  }
+
+  // T2: Press 'a' for reply-all or 'r' for reply
+  const key = params.replyAll ? 'a' : 'r';
+  await page.keyboard.press(key);
+  logger.debug(`replyEmail: pressed '${key}' for ${params.replyAll ? 'reply-all' : 'reply'}`);
+
+  // Wait for reply editor
+  await waitForGmail(page, 'div[aria-label="Message Body"]');
+
+  // Fill reply body
+  if (params.body) {
+    await page.type('div[aria-label="Message Body"]', params.body);
+  }
+
+  // Send if requested
+  if (params.send) {
+    await page.keyboard.down('Control');
+    await page.keyboard.press('Enter');
+    await page.keyboard.up('Control');
+    logger.debug('replyEmail: sent via Ctrl+Enter');
+  }
+
+  const status = params.send ? 'sent' : 'draft';
+  const action = params.replyAll ? 'Reply-all' : 'Reply';
+  const summary = params.send
+    ? `${action} sent.`
+    : `${action} draft created. Review and send manually in Gmail.`;
+
+  return new GmailActionResponse(
+    { status, replyAll: !!params.replyAll },
+    summary,
+    params.send
+      ? ['Use list_emails to return to inbox']
+      : ['Review and send the reply draft manually in Gmail']
+  );
+}

package/src/plugins/gmail/actions/search-emails.js

@@ -0,0 +1,95 @@
+/**
+ * search-emails.js — Search emails using Gmail's search functionality.
+ *
+ * Tier usage:
+ *   T1: gmailNavigate to #search/<query>
+ *   T4: EMAIL_ROW + NO_RESULTS selectors for result detection
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import {
+  checkPrecondition,
+  gmailNavigate,
+  waitForGmail,
+  extractEmailRows,
+  GmailActionResponse
+} from '../helpers.js';
+import { EMAIL_ROW, NO_RESULTS } from '../selectors.js';
+
+/**
+ * Search emails by query string.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.query - Gmail search query
+ * @param {number} [opts.params.limit=25] - Maximum results to return
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function searchEmails({ page, params }) {
+  // Validate query
+  if (!params.query || !params.query.trim()) {
+    return new ErrorResponse(
+      'Search query is required.',
+      [
+        'Provide a query string, e.g. search_emails({ query: "from:boss subject:urgent" })',
+        'Use list_emails to browse without a search query'
+      ]
+    );
+  }
+
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  const query = params.query.trim();
+  const limit = params.limit || 25;
+
+  // T1: Navigate to search results
+  await gmailNavigate(page, '#search/' + encodeURIComponent(query));
+
+  // Wait for either email rows or no-results indicator
+  let hasResults = true;
+  try {
+    await waitForGmail(page, EMAIL_ROW);
+  } catch {
+    // Check if no-results indicator is present instead
+    const noResults = await page.$(NO_RESULTS);
+    if (noResults) {
+      hasResults = false;
+    } else {
+      // Neither rows nor no-results — re-throw the timeout
+      throw new Error(
+        `Gmail search did not return results within the timeout. ` +
+        `Query: "${query}". The page may still be loading.`
+      );
+    }
+  }
+
+  if (!hasResults) {
+    return new GmailActionResponse(
+      { emails: [], query, resultCount: 0 },
+      `No results found for "${query}".`,
+      [
+        'Try a different or broader search query',
+        'Use list_emails to browse the inbox instead'
+      ]
+    );
+  }
+
+  // T3+T4: Extract search results
+  const emails = await extractEmailRows(page, limit);
+
+  return new GmailActionResponse(
+    { emails, query, resultCount: emails.length },
+    `Found ${emails.length} result(s) for "${query}".`,
+    [
+      'Use read_email to open a specific result',
+      'Refine your search with Gmail search operators (from:, to:, subject:, has:attachment)',
+      'Use list_emails to return to the inbox'
+    ]
+  );
+}