maildoc

Легковесные инструменты для поиска электронной почты, получения вложений и извлечения PDF для ИИ-агентов и автоматизации.

Настройка

pip install -r requirements.txt

Укажите учетные данные в .env (см. .env.example):

GMAIL_USERNAME=user@example.com
GMAIL_APP_PASSWORD=your_app_password

Быстрый старт

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-сервер (Claude Desktop / Cursor / Antigravity)

Запуск в качестве сервера Model Context Protocol (MCP):

python server.py

Пример claude_desktop_config.json:

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

Справочник инструментов

Почта и поиск

• search_emails(sender, subject, body, seen, date_gte, date_lt, with_attachments, folder, limit): Поиск по почтовому ящику и возврат структурированных словарей.

• fetch_email_by_uid(uid, folder): Получение одного письма по UID.

• list_folders(): Список папок почтового ящика.

• mark_email_as_read(uid, folder): Отметить письмо как прочитанное.

• move_email(uid, destination_folder, source_folder): Переместить письмо между папками.

• delete_email(uid, folder): Удалить письмо.

• create_folder(folder_name): Создать папку почтового ящика.

• delete_folder(folder_name): Удалить папку почтового ящика.

• connect_to_email(), disconnect_from_email(): Вспомогательные функции жизненного цикла подключения.

Извлечение PDF

• read_pdf_attachment(uid, attachment_filename, password=None, folder="INBOX"): Скачать вложение и извлечь его текст за один шаг (идеально для MCP / ИИ-агентов).

• extract_pdf_text(pdf_bytes, password=None): Извлечь весь текст из PDF-байтов.

• extract_pdf_page_text(pdf_bytes, page_number, password=None): Извлечь текст с конкретной страницы (нумерация с 1).