AVA MCP Server

Instructions

Implementation Reference

• mcp-server-example.py:40-92 (handler)

  The handler function implementing the 'write_email_draft' tool logic. It uses the Gmail API to create an email draft based on provided recipient, subject, and body. Registered via @mcp.tool() decorator.
  @mcp.tool() def write_email_draft(recipient_email: str, subject: str, body: str) -> dict: """Create a draft email using the Gmail API. Args: recipient_email (str): The email address of the recipient. subject (str): The subject line of the email. body (str): The main content/body of the email. Returns: dict or None: A dictionary containing the draft information including 'id' and 'message' if successful, None if an error occurs. Raises: HttpError: If there is an error communicating with the Gmail API. Note: This function requires: - Gmail API credentials to be properly configured - USER_EMAIL environment variable to be set with the sender's email address - Appropriate Gmail API permissions for creating drafts """ try: # create gmail api client service = get_gmail_service() message = EmailMessage() message.set_content(body) message["To"] = recipient_email message["From"] = os.getenv("USER_EMAIL") message["Subject"] = subject # encoded message encoded_message = base64.urlsafe_b64encode(message.as_bytes()).decode() create_message = {"message": {"raw": encoded_message}} # pylint: disable=E1101 draft = ( service.users() .drafts() .create(userId="me", body=create_message) .execute() ) print(f'Draft id: {draft["id"]}\nDraft message: {draft["message"]}') except HttpError as error: print(f"An error occurred: {error}") draft = None return draft
• tools/gmail.py:18-49 (helper)

  Supporting helper function that initializes and returns the Gmail API service client, which is called within the write_email_draft handler.
  def get_gmail_service(): """Gets valid user credentials from storage and creates Gmail API service. Returns: Service object for Gmail API calls """ creds = None token_path = os.path.expanduser(os.getenv('GOOGLE_TOKEN_PATH')) credentials_path = os.path.expanduser(os.getenv('GOOGLE_CREDENTIALS_PATH')) # The token file stores the user's access and refresh tokens if os.path.exists(token_path): creds = Credentials.from_authorized_user_file(token_path, SCOPES) # If there are no (valid) credentials available, let the user log in. if not creds or not creds.valid: if creds and creds.expired and creds.refresh_token: creds.refresh(Request()) else: if not os.path.exists(credentials_path): raise FileNotFoundError(f"Credentials file not found at {credentials_path}") flow = InstalledAppFlow.from_client_secrets_file( credentials_path, SCOPES) creds = flow.run_local_server(port=0) # Save the credentials for the next run os.makedirs(os.path.dirname(token_path), exist_ok=True) with open(token_path, 'w') as token: token.write(creds.to_json()) return build('gmail', 'v1', credentials=creds)
• mcp-server-example.py:40-40 (registration)

  The @mcp.tool() decorator registers the write_email_draft function as an MCP tool.
  @mcp.tool()