patch_label

Instructions

Implementation Reference

• src/index.ts:492-511 (registration)

  Registration of the 'patch_label' MCP tool, including input schema (using Zod) and the handler function that destructures params, calls the shared handleTool helper, which invokes Gmail API's users.labels.patch to partially update the label, and formats the response.

  server.tool("patch_label",
    "Patch an existing label (partial update)",
    {
      id: z.string().describe("The ID of the label to patch"),
      name: z.string().optional().describe("The display name of the label"),
      messageListVisibility: z.enum(['show', 'hide']).optional().describe("The visibility of messages with this label in the message list"),
      labelListVisibility: z.enum(['labelShow', 'labelShowIfUnread', 'labelHide']).optional().describe("The visibility of the label in the label list"),
      color: z.object({
        textColor: z.string().describe("The text color of the label as hex string"),
        backgroundColor: z.string().describe("The background color of the label as hex string")
      }).optional().describe("The color settings for the label")
    },
    async (params) => {
      const { id, ...labelData } = params
      return handleTool(config, async (gmail: gmail_v1.Gmail) => {
        const { data } = await gmail.users.labels.patch({ userId: 'me', id, requestBody: labelData })
        return formatResponse(data)
      })
    }
  )

• src/index.ts:504-510 (handler)

  The handler function for 'patch_label' tool: extracts id and labelData from params, uses handleTool to authenticate and call Gmail API patch on labels with the provided data.

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

• src/index.ts:495-502 (schema)

  Zod schema for 'patch_label' tool inputs: required id, optional name, visibilities, and color object.

  id: z.string().describe("The ID of the label to patch"),
  name: z.string().optional().describe("The display name of the label"),
  messageListVisibility: z.enum(['show', 'hide']).optional().describe("The visibility of messages with this label in the message list"),
  labelListVisibility: z.enum(['labelShow', 'labelShowIfUnread', 'labelHide']).optional().describe("The visibility of the label in the label list"),
  color: z.object({
    textColor: z.string().describe("The text color of the label as hex string"),
    backgroundColor: z.string().describe("The background color of the label as hex string")
  }).optional().describe("The color settings for the label")

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

  Shared 'handleTool' helper function used by 'patch_label' and all other tools: handles OAuth2 client creation/validation, Gmail client setup, executes the provided API callback, and manages auth errors with formatted responses.

  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}` });
    }
  }