list_threads

Instructions

Implementation Reference

• src/index.ts:720-754 (handler)

  Full implementation of the 'list_threads' tool, including registration, input schema, and handler function. The handler calls the Gmail API to list threads, optionally decodes and processes message payloads (filtering headers, decoding base64 bodies), and formats the response.

  server.tool("list_threads",
    "List threads in the user's mailbox",
    {
      maxResults: z.number().optional().describe("Maximum number of threads to return"),
      pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
      q: z.string().optional().describe("Only return threads matching the specified query"),
      labelIds: z.array(z.string()).optional().describe("Only return threads with labels that match all of the specified label IDs"),
      includeSpamTrash: z.boolean().optional().describe("Include threads from SPAM and TRASH in the results"),
      includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large"),
    },
    async (params) => {
      return handleTool(config, async (gmail: gmail_v1.Gmail) => {
        const { data } = await gmail.users.threads.list({ userId: 'me', ...params })
  
        if (data.threads) {
          data.threads = data.threads.map(thread => {
            if (thread.messages) {
              thread.messages = thread.messages.map(message => {
                if (message.payload) {
                  message.payload = processMessagePart(
                    message.payload,
                    params.includeBodyHtml
                  )
                }
                return message
              })
            }
            return thread
          })
        }
  
        return formatResponse(data)
      })
    }
  )

• src/index.ts:722-729 (schema)

  Input schema (Zod) for the list_threads tool parameters.

  {
    maxResults: z.number().optional().describe("Maximum number of threads to return"),
    pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
    q: z.string().optional().describe("Only return threads matching the specified query"),
    labelIds: z.array(z.string()).optional().describe("Only return threads with labels that match all of the specified label IDs"),
    includeSpamTrash: z.boolean().optional().describe("Include threads from SPAM and TRASH in the results"),
    includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large"),
  },

• src/index.ts:79-93 (helper)

  Helper function used by list_threads to recursively process message parts: decode base64 bodies (unless HTML and not requested), filter headers to specific list, used to clean up responses.

  const processMessagePart = (messagePart: MessagePart, includeBodyHtml = false): MessagePart => {
    if ((messagePart.mimeType !== 'text/html' || includeBodyHtml) && messagePart.body) {
      messagePart.body = decodedBody(messagePart.body)
    }
  
    if (messagePart.parts) {
      messagePart.parts = messagePart.parts.map(part => processMessagePart(part, includeBodyHtml))
    }
  
    if (messagePart.headers) {
      messagePart.headers = messagePart.headers.filter(header => RESPONSE_HEADERS_LIST.includes(header.name || ''))
    }
  
    return messagePart
  }

• src/index.ts:49-65 (helper)

  Shared helper invoked by list_threads handler: handles OAuth2 client creation/validation, Gmail client setup, executes the API call, catches errors.

  const handleTool = async (queryConfig: Record<string, any> | undefined, apiCall: (gmail: gmail_v1.Gmail) => Promise<any>) => {
    try {
      const oauth2Client = queryConfig ? createOAuth2Client(queryConfig) : defaultOAuth2Client
      if (!oauth2Client) throw new Error('OAuth2 client could not be created, please check your credentials')
  
      const credentialsAreValid = await validateCredentials(oauth2Client)
      if (!credentialsAreValid) throw new Error('OAuth2 credentials are invalid, please re-authenticate')
  
      const gmailClient = queryConfig ? google.gmail({ version: 'v1', auth: oauth2Client }) : defaultGmailClient
      if (!gmailClient) throw new Error('Gmail client could not be created, please check your credentials')
  
      const result = await apiCall(gmailClient)
      return result
    } catch (error: any) {
      return `Tool execution failed: ${error.message}`
    }
  }