search_emails

Instructions

Implementation Reference

• src/tools.ts:6-9 (schema)

  Zod schema defining the input for search_emails: 'query' (string) and 'maxResults' (number, optional, default 10).

  search_emails: z.object({
      query: z.string().describe("Gmail search query (e.g., 'is:unread', 'from:newsletter@example.com')"),
      maxResults: z.number().optional().default(10).describe("Maximum number of results (default: 10)")
  }),

• src/tools.ts:50-55 (registration)

  getToolDefinitions() maps all schemas including search_emails into MCP tool definitions with name, description, and inputSchema.

  export const getToolDefinitions = () => 
      Object.entries(schemas).map(([name, schema]) => ({
          name,
          description: toolDescriptions[name],
          inputSchema: zodToJsonSchema(schema)
      }));

• src/tools.ts:65-71 (handler)

  The case 'search_emails' in handleToolCall: validates args, calls gmailService.searchEmails(query, maxResults), and returns formatted text results with email ID, subject, from, date, snippet, and Gmail URL.

  case "search_emails": {
      const v = validated as z.infer<typeof schemas.search_emails>;
      const results = await gmailService.searchEmails(v.query, v.maxResults);
      return { content: [{ type: "text", text: results.length ? 
          results.map(e => `ID: ${e.id}\nSubject: ${e.subject}\nFrom: ${e.from}\nDate: ${e.date}\nSnippet: ${e.snippet}\nGmail URL: ${gmailService.getEmailUrl(e.id)}\n`).join('---\n') : 
          "No emails found." }] };
  }

• src/gmail-service.ts:31-54 (helper)

  GmailService.searchEmails(): Calls Gmail API users.messages.list with query/maxResults, then fetches metadata for each message (Subject, From, To, Date headers) and returns EmailInfo[].

  async searchEmails(query: string, maxResults = 10): Promise<EmailInfo[]> {
      const { data } = await this.gmail.users.messages.list({ userId: 'me', q: query, maxResults });
      if (!data.messages?.length) return [];
      
      return Promise.all(data.messages.map(async (msg) => {
          const { data: detail } = await this.gmail.users.messages.get({
              userId: 'me',
              id: msg.id!,
              format: 'metadata',
              metadataHeaders: ['Subject', 'From', 'To', 'Date']
          });
          const h = detail.payload?.headers || [];
          const findHeader = (name: string) => h.find(x => x.name === name)?.value || '';
          return {
              id: msg.id!,
              threadId: detail.threadId,
              subject: findHeader('Subject'),
              from: findHeader('From'),
              to: findHeader('To'),
              date: findHeader('Date'),
              snippet: detail.snippet || ''
          };
      }));
  }