@lengelhard/imap-email-mcp 1.6.0 → 1.7.1

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,40 @@
+# Changelog
+
+## 1.7.1
+
+### Fixed
+- Several server processes sharing one index (Claude Desktop can start more than one) no longer sync at the same time. A lock file next to the database lets one process sync while the others keep answering searches. Stale locks (process gone, or no heartbeat for 3 minutes) are taken over automatically.
+- SQLite waits up to 10 seconds for a busy database instead of failing with "database is locked".
+- A scheduled sync is skipped when another process completed a full sync in the last half interval.
+- Index refreshes requested after a move or delete are retried when another process holds the sync lock.
+- The server exits when the client disconnects or on SIGTERM/SIGINT/SIGHUP, instead of lingering while IMAP sockets are open. The sync lock is released on exit.
+
+### Changed
+- `index_status` reports `this_pid`, `sync_running_in_pid` (when another process syncs), `last_full_sync`, and a `last_run` shared by all processes.
+- `sync_index` and `search_index` say so when another process is already syncing.
+
+## 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,23 @@ 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.
+- **Several processes.** Some clients start more than one copy of the server. They share the index file: one process syncs at a time (a lock file next to the database), and all of them answer searches. A lock left by a process that died is taken over after at most 3 minutes.
+- **Requirements.** Node 22.13 or later (uses the built-in `node:sqlite`, no native modules).
 
 ### Provider Settings
 
@@ -112,9 +130,12 @@ 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 |