modify_thread

Instructions

Implementation Reference

• src/index.ts:789-803 (registration)

  Registration of the 'modify_thread' MCP tool, including description, Zod input schema, and inline handler function that invokes the Gmail API threads.modify endpoint.

  server.tool("modify_thread",
    "Modify the labels applied to a thread",
    {
      id: z.string().describe("The ID of the thread to modify"),
      addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the thread"),
      removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the thread")
    },
    async (params) => {
      const { id, ...threadData } = params
      return handleTool(config, async (gmail: gmail_v1.Gmail) => {
        const { data } = await gmail.users.threads.modify({ userId: 'me', id, requestBody: threadData })
        return formatResponse(data)
      })
    }
  )

• src/index.ts:796-802 (handler)

  The core handler function for 'modify_thread' tool execution. It destructures the thread ID and label modifications from params, wraps the Gmail threads.modify API call in the shared handleTool utility for auth and error handling, and formats the response.

  async (params) => {
    const { id, ...threadData } = params
    return handleTool(config, async (gmail: gmail_v1.Gmail) => {
      const { data } = await gmail.users.threads.modify({ userId: 'me', id, requestBody: threadData })
      return formatResponse(data)
    })
  }

• src/index.ts:791-795 (schema)

  Zod schema for input validation of the 'modify_thread' tool, specifying required thread ID and optional label IDs to add/remove.

  {
    id: z.string().describe("The ID of the thread to modify"),
    addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the thread"),
    removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the thread")
  },

• src/index.ts:50-80 (helper)

  Shared 'handleTool' helper used by 'modify_thread' and other tools for OAuth2 authentication, credential validation, Gmail client initialization, API execution, and specialized error handling for auth issues.

  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) {
      // Check for specific authentication errors
      if (
        error.message?.includes("invalid_grant") ||
        error.message?.includes("refresh_token") ||
        error.message?.includes("invalid_client") ||
        error.message?.includes("unauthorized_client") ||
        error.code === 401 ||
        error.code === 403
      ) {
        return formatResponse({
          error: `Authentication failed: ${error.message}. Please re-authenticate by running: npx @shinzolabs/gmail-mcp auth`,
        });
      }
  
      return formatResponse({ error: `Tool execution failed: ${error.message}` });
    }
  }