Metadata-Version: 2.4
Name: mcs-driver-mailread
Version: 0.2.1
Summary: Mail-reading driver for the Model Context Standard -- lets an LLM read and organise e-mail.
Author-email: Danny Gerst <danny@dannygerst.de>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.modelcontextstandard.io
Project-URL: Source, https://github.com/modelcontextstandard/python-sdk
Keywords: mcs,modelcontextstandard,driver,mail,email,imap
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcs-driver-core>=0.2.2
Provides-Extra: imap
Requires-Dist: mcs-adapter-imap>=0.1; extra == "imap"
Provides-Extra: gmail
Requires-Dist: mcs-adapter-http>=0.3; extra == "gmail"
Provides-Extra: inspector
Requires-Dist: mcs-inspector>=0.1; extra == "inspector"
Dynamic: license-file

# mcs-driver-mailread

Mail-reading driver for the **Model Context Standard (MCS)**.

Provides tools for listing folders, reading messages, searching, moving, and
organising e-mail. The actual I/O is delegated to a pluggable adapter, making
the same driver work with IMAP, Gmail API, Microsoft Graph, or any future
backend.

## Installation

```bash
pip install mcs-driver-mailread

# With IMAP adapter
pip install mcs-driver-mailread[imap]
```

## Quick start

```python
from mcs.driver.mailread import MailreadToolDriver

# IMAP (default adapter)
td = MailreadToolDriver(
    adapter="imap",
    host="imap.example.com",
    user="alice@example.com",
    password="...",
)

tools = td.list_tools()       # 7 tools
result = td.execute_tool("list_folders", {})
```

## Tools

| Tool               | Description                            |
|--------------------|----------------------------------------|
| `list_folders`     | List all mailbox folders               |
| `list_messages`    | List message summaries in a folder     |
| `fetch_message`    | Fetch a full message by UID            |
| `search_messages`  | Search messages by criteria            |
| `move_message`     | Move a message to another folder       |
| `set_flags`        | Add or remove flags on a message       |
| `create_folder`    | Create a new mailbox folder            |

## Adapter protocol

The driver defines a `MailboxPort` typing protocol. Any object that implements
the seven methods above satisfies the contract -- no inheritance required.

## Links

- **Homepage:** <https://www.modelcontextstandard.io>
- **Source:** <https://github.com/modelcontextstandard/python-sdk>

## License

Apache-2.0
