# maildoc

Lightweight email search, attachment retrieval, and PDF extraction tools for AI agents and automation.

## Setup

```bash
pip install -r requirements.txt
```

Set credentials in `.env` (see `.env.example`):
```env
GMAIL_USERNAME=user@example.com
GMAIL_APP_PASSWORD=your_app_password
```

## Quickstart

```python
from maildoc import search_emails, download_attachment, extract_pdf_text

# Search emails with attachments
emails = search_emails(
    sender="billing@example.com",
    with_attachments=True,
    limit=5,
)

# Download and extract text from PDF attachments (with optional password for protected files)
for email in emails:
    for att in email["attachments"]:
        if att["filename"].endswith(".pdf"):
            pdf_bytes = download_attachment(email["uid"], att["filename"])
            if pdf_bytes:
                # Pass password if the PDF is password-protected (e.g., bank statements)
                text = extract_pdf_text(pdf_bytes, password="optional_password")
                print(text)
```

## MCP Server (Claude Desktop / Cursor / Antigravity)

Run as a Model Context Protocol (MCP) server:
```bash
python server.py
```

Example `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "maildoc": {
      "command": "python",
      "args": ["/absolute/path/to/maildoc/server.py"],
      "env": {
        "GMAIL_USERNAME": "user@example.com",
        "GMAIL_APP_PASSWORD": "your_app_password"
      }
    }
  }
}
```

## Tools Reference

### Email & Search
- `search_emails(sender, subject, body, seen, date_gte, date_lt, with_attachments, folder, limit)`: Search mailbox and return structured dicts.
- `fetch_email_by_uid(uid, folder)`: Fetch a single email by UID.
- `list_folders()`: List mailbox folders.
- `mark_email_as_read(uid, folder)`: Mark email as read.
- `move_email(uid, destination_folder, source_folder)`: Move email between folders.
- `delete_email(uid, folder)`: Delete email.
- `create_folder(folder_name)`: Create mailbox folder.
- `delete_folder(folder_name)`: Delete mailbox folder.
- `connect_to_email()`, `disconnect_from_email()`: Connection lifecycle helpers.

### PDF Extraction
- `read_pdf_attachment(uid, attachment_filename, password=None, folder="INBOX")`: Download attachment and extract its text directly in one step (ideal for MCP / AI agents).
- `extract_pdf_text(pdf_bytes, password=None)`: Extract all text from PDF bytes.
- `extract_pdf_page_text(pdf_bytes, page_number, password=None)`: Extract text from a specific page (1-indexed).