count-daily-emails

Instructions

Implementation Reference

• src/email_client/server.py:215-232 (registration)

  Registration of the 'count-daily-emails' tool, including its name, description, and JSON schema for input validation (start_date and end_date required).

  types.Tool(
      name="count-daily-emails",
      description="Count emails received for each day in a date range",
      inputSchema={
          "type": "object",
          "properties": {
              "start_date": {
                  "type": "string",
                  "description": "Start date in YYYY-MM-DD format",
              },
              "end_date": {
                  "type": "string",
                  "description": "End date in YYYY-MM-DD format",
              },
          },
          "required": ["start_date", "end_date"],
      },
  ),

• src/email_client/server.py:422-447 (handler)

  Main handler for the 'count-daily-emails' tool. Parses start and end dates, loops through each day, performs IMAP search for emails received 'ON' that date using the count_emails_async helper, handles timeouts, and formats results as a markdown table of daily counts.

  elif name == "count-daily-emails":
      start_date = datetime.strptime(arguments["start_date"], "%Y-%m-%d")
      end_date = datetime.strptime(arguments["end_date"], "%Y-%m-%d")
      
      result_text = "Daily email counts:\n\n"
      result_text += "Date | Count\n"
      result_text += "-" * 30 + "\n"
      
      current_date = start_date
      while current_date <= end_date:
          date_str = current_date.strftime("%d-%b-%Y")
          search_criteria = f'(ON "{date_str}")'
          
          try:
              async with asyncio.timeout(SEARCH_TIMEOUT):
                  count = await count_emails_async(mail, search_criteria)
                  result_text += f"{current_date.strftime('%Y-%m-%d')} | {count}\n"
          except asyncio.TimeoutError:
              result_text += f"{current_date.strftime('%Y-%m-%d')} | Timeout\n"
          
          current_date += timedelta(days=1)
      
      return [types.TextContent(
          type="text",
          text=result_text
      )]

• src/email_client/server.py:107-115 (helper)

  Helper function used by the count-daily-emails handler to asynchronously count the number of emails matching an IMAP search criteria (e.g., emails received on a specific date). Runs IMAP search in executor to avoid blocking.

  async def count_emails_async(mail: imaplib.IMAP4_SSL, search_criteria: str) -> int:
      """Asynchronously count emails matching the search criteria."""
      loop = asyncio.get_event_loop()
      try:
          _, messages = await loop.run_in_executor(None, lambda: mail.search(None, search_criteria))
          return len(messages[0].split()) if messages[0] else 0
      except Exception as e:
          raise Exception(f"Error counting emails: {str(e)}")