IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:774-839 (handler)

  The main logic for retrieving a cached overview of emails from IMAP folders.

  def get_cached_overview(
      self, mailbox: Optional[str] = None, limit: int = 20
  ) -> dict:
      """Get cached email overview for INBOX, next, waiting, someday (from in-memory cache)."""
      import time
  
      # If watcher is running, use its cache
      if self.watcher and self.watcher.running:
          # Wait briefly for cache to populate if empty
          for _ in range(10):
              cache = self.watcher.get_cache(mailbox)
              if cache:
                  return cache
              time.sleep(0.5)
          return self.watcher.get_cache(mailbox)
  
      # Fallback to manual fetch if watcher not running
      folders = self.config.get("folders", {})
      mailboxes = {
          "inbox": folders.get("inbox", "INBOX"),
          "next": folders.get("next", "next"),
          "waiting": folders.get("waiting", "waiting"),
          "someday": folders.get("someday", "someday"),
      }
  
      if mailbox:
          if mailbox not in mailboxes:
              return {}
          mailboxes = {mailbox: mailboxes[mailbox]}
  
      result = {}
      for key, folder in mailboxes.items():
          cache_key = f"overview_{folder}"
          if cache_key in self.cache:
              ttl = self.config.get("cache", {}).get("ttl_seconds", 300)
              cache_time = self.cache_timestamps.get(cache_key, datetime.min)
              if (datetime.now() - cache_time).total_seconds() < ttl:
                  result[key] = self.cache[cache_key]
                  continue
  
          try:
              emails = self.fetch_emails(folder, limit=limit)
              status = self.get_mailbox_status(folder)
              overview = {
                  "emails": [
                      {
                          "uid": e.uid,
                          "sender": e.from_address.email if e.from_address else "",
                          "sender_name": e.from_address.name if e.from_address else None,
                          "subject": e.subject,
                          "date": e.date.isoformat() if e.date else None,
                          "unread": "\\Seen" not in e.flags,
                      }
                      for e in emails
                  ],
                  "total": status.exists,
                  "unread": status.unseen,
                  "last_updated": datetime.now().isoformat(),
              }
              self.cache[cache_key] = overview
              self.cache_timestamps[cache_key] = datetime.now()
              result[key] = overview
          except Exception as e:
              result[key] = {"error": str(e)}
  
      return result

• src/imap_mcp/server.py:649-653 (registration)

  Tool registration logic for "get_cached_overview" within the MCP server handler.

  elif name == "get_cached_overview":
      return imap_client.get_cached_overview(
          mailbox=args.get("mailbox"),
          limit=args.get("limit", 20),
      )