@lengelhard/imap-email-mcp 1.5.0 → 1.7.0

package/.env.example

@@ -11,6 +11,14 @@ IMAP_HOST=imap.example.com
 # IMAP_TLS=true
 # IMAP_AUTH_TIMEOUT=10000
 # IMAP_TLS_REJECT_UNAUTHORIZED=true
+# IMAP_IDLE_CLOSE_SECONDS=300
+
+# Optional - Local read-only search index (requires Node 22.13+)
+# INDEX_ENABLED=false
+# INDEX_DB_PATH=            (default: ~/Library/Application Support/imap-email-mcp/index-<account>.sqlite on macOS)
+# INDEX_FOLDERS=            (comma list; default: all folders except Trash and Junk)
+# INDEX_EXCLUDE_FOLDERS=    (comma list, added to the default exclusions)
+# INDEX_SYNC_INTERVAL_MINUTES=5
 
 # Optional - SMTP Settings (defaults to IMAP values if not set)
 # SMTP_HOST=smtp.example.com

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 1.7.0
+
+### Added
+- Optional local read-only full-text index (`INDEX_ENABLED=true`) with tools `search_index`, `index_status` and `sync_index`. Uses Node's built-in SQLite (FTS5, accent-insensitive). Indexes subject, sender, recipients, attachment names and body text. Never modifies the mailbox.
+- `search_emails`: `folders` (multi-folder search), `cc`, `text`, `since_date`, `before_date`, `unseen_only`, `flagged_only`.
+- `list_emails`: `flagged_only`, `before_date`, `offset`.
+- `get_email`: `include_html` (HTML with inline images removed).
+- Responses from `list_emails` and `search_emails` include `total_matches`, and each result carries its `folder`.
+
+### Changed
+- One persistent IMAP connection is shared by all tools (serialised, auto-reconnect, closed after `IMAP_IDLE_CLOSE_SECONDS` of inactivity) instead of a new login per call.
+- `list_emails` and `search_emails` sort on the server (SORT by arrival time, UID order as fallback) and fetch headers only for the messages returned. Previously every match was fetched, including its MIME structure.
+- Read tools open folders read-only (EXAMINE).
+- `get_email` returns the text body by default and no longer returns HTML unless asked. HTML-only emails get a text version converted from the HTML.
+- `get_email` reports a missing UID as an error with a hint that UIDs change on move.
+- The server reports its real version.
+
+### Fixed
+- `list_emails`: combining `unseen_only` and `since_date` dropped the unread filter.
+- Date filters use the local calendar date (previously parsed as UTC).
+- A message expunged between SEARCH and FETCH could hang a search.
+
+### Compatibility
+- Result shape of `list_emails` and `search_emails` changed from a bare array to `{ total_matches, returned, results }`.
+- The local index requires Node 22.13+. Everything else still runs on Node 18+.

package/README.md

@@ -70,7 +70,8 @@ Add to your config file:
 ## Features
 
 - **Read emails** - List and read emails from any folder
-- **Search** - Search by subject, sender, or body content
+- **Search** - Live IMAP search across one or several folders, with date and flag filters, newest first
+- **Local full-text index** - Optional read-only SQLite index for reliable content search, independent of the server's body search
 - **Compose** - Create and save email drafts
 - **Send** - Send emails directly via SMTP
 - **Manage drafts** - List, read, update, and delete drafts
@@ -96,6 +97,22 @@ Add to your config file:
 | `SMTP_HOST` | Same as IMAP_HOST | SMTP server hostname |
 | `SMTP_PORT` | `465` | SMTP port |
 | `SMTP_SECURE` | `true` | Use secure SMTP |
+| `IMAP_IDLE_CLOSE_SECONDS` | `300` | Close the shared IMAP connection after this much inactivity |
+| `INDEX_ENABLED` | `false` | Enable the local read-only search index |
+| `INDEX_DB_PATH` | see below | Location of the index database |
+| `INDEX_FOLDERS` | all but Trash/Junk | Comma-separated folders to index |
+| `INDEX_EXCLUDE_FOLDERS` | none | Comma-separated folders to skip, on top of Trash/Junk |
+| `INDEX_SYNC_INTERVAL_MINUTES` | `5` | Background sync interval |
+
+### Local search index
+
+Some IMAP servers return incomplete results for body searches without reporting an error. The local index avoids that by keeping a searchable copy of message text on your machine.
+
+- **Read-only.** The indexer opens folders with EXAMINE and fetches with BODY.PEEK. It never changes flags, never moves, deletes or appends mail.
+- **What is indexed.** Subject, sender, recipients, attachment file names, and the text body (plain text, or HTML converted to text). Attachment contents are not indexed.
+- **Sync.** Newest mail first, in the background, every few minutes. Moves and deletes are picked up on the next sync; moves made through this server trigger a sync of the affected folders within seconds.
+- **Storage.** A single SQLite file, created with owner-only permissions. Default location on macOS: `~/Library/Application Support/imap-email-mcp/index-<account>.sqlite`; elsewhere `~/.local/share/imap-email-mcp/`. It contains the text of your mail, so keep the disk encrypted. Deleting the file is safe; it is rebuilt on the next start.
+- **Requirements.** Node 22.13 or later (uses the built-in `node:sqlite`, no native modules).
 
 ### Provider Settings
 
@@ -112,15 +129,20 @@ Add to your config file:
 | Tool | Description |
 |------|-------------|
 | `list_folders` | List all email folders/mailboxes |
-| `list_emails` | List emails with optional filtering |
-| `get_email` | Get full email content by UID |
-| `search_emails` | Search by subject, sender, or body |
+| `list_emails` | List emails newest first, with unread, flagged and date filters and paging |
+| `get_email` | Get an email by UID. Text by default; HTML (without inline images) on request |
+| `search_emails` | Live IMAP search across one or more folders: subject, from, to, cc, body, text, dates, flags |
+| `search_index` | Full-text search of the local index (when `INDEX_ENABLED=true`) |
+| `index_status` | Per-folder index coverage, last sync and errors |
+| `sync_index` | Run an index sync now |
 | `list_drafts` | List all draft emails |
 | `get_draft` | Get a specific draft by UID |
 | `create_draft` | Create a new email draft |
 | `update_draft` | Update an existing draft |
 | `send_email` | Send an email directly |
 | `delete_email` | Delete an email by UID |
+| `download_attachment` | Download an attachment: ≤700KB returns inline base64, larger saves to disk (ATTACHMENT_DIR) |
+| `extract_text` | Extract plain text from a PDF, xlsx/xlsm/xls, docx, or text attachment in one call, parsed server-side |
 
 ## Usage Examples