list_recent_senders
Identifies top email senders over a specified period, ordered by message count. Answers 'who has been emailing me lately?'
Instructions
Top senders over the last N days, ordered by message count. Useful for "who has been emailing me lately?" style questions.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_recent_senders"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | ||
| folder | No | INBOX | |
| since_days | No | ||
| top | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/productivity_mcp/server.py:316-329 (handler)The actual handler function for the 'list_recent_senders' tool. It retrieves up to 1000 messages from a folder (default INBOX) within the last N days (default 30), counts messages per sender, and returns the top senders (default 20) sorted by message count descending.
def list_recent_senders( account: str | None = None, folder: str = "INBOX", since_days: int = 30, top: int = 20, ) -> list[dict[str, Any]]: """Top senders over the last N days, ordered by message count. Useful for "who has been emailing me lately?" style questions.""" msgs = _email(account).list_messages(folder=folder, limit=1000, since_days=since_days) counts: dict[str, int] = {} for m in msgs: counts[m.sender] = counts.get(m.sender, 0) + 1 ranked = sorted(counts.items(), key=lambda kv: -kv[1])[:top] return [{"sender": s, "count": c} for s, c in ranked] - src/productivity_mcp/server.py:314-315 (registration)Tool registration via @mcp.tool() decorator on the list_recent_senders function. This is how the tool is registered with the FastMCP server.
@mcp.tool() @_logged - Input schema defined via function signature (account, folder, since_days, top) and return type annotation (list[dict[str, Any]]).
def list_recent_senders( account: str | None = None, folder: str = "INBOX", since_days: int = 30, top: int = 20, ) -> list[dict[str, Any]]: - src/productivity_mcp/server.py:66-73 (helper)The _email() helper function resolves the account name to an EmailProvider instance, used by list_recent_senders to call list_messages().
def _email(account: str | None) -> EmailProvider: if not _email_providers: raise RuntimeError("No email accounts configured. See example.config.toml.") if account is None: return next(iter(_email_providers.values())) if account not in _email_providers: raise KeyError(f"Unknown email account: {account}. Available: {list(_email_providers)}") return _email_providers[account] - The abstract list_messages method on EmailProvider that list_recent_senders calls internally.
def list_messages( self, folder: str = "INBOX", limit: int = 25, query: str | None = None, unread_only: bool = False, recipients: list[str] | None = None, since_days: int | None = None, senders: list[str] | None = None, ) -> list[EmailMessage]: ...