@kbzowski/mcp-inbox 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +396 -0
- package/dist/cache/db.d.ts +34 -0
- package/dist/cache/idle.d.ts +32 -0
- package/dist/cache/queries.d.ts +66 -0
- package/dist/cache/schema.d.ts +456 -0
- package/dist/cache/sync.d.ts +38 -0
- package/dist/config/env.d.ts +103 -0
- package/dist/errors/mapper.d.ts +10 -0
- package/dist/errors/types.d.ts +25 -0
- package/dist/formatters/markdown.d.ts +13 -0
- package/dist/imap/client.d.ts +37 -0
- package/dist/imap/folders.d.ts +19 -0
- package/dist/imap/mime-builder.d.ts +32 -0
- package/dist/imap/search.d.ts +28 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2572 -0
- package/dist/index.js.map +7 -0
- package/dist/migrations/0000_mean_the_santerians.sql +49 -0
- package/dist/migrations/0001_wooden_doomsday.sql +2 -0
- package/dist/migrations/meta/0000_snapshot.json +337 -0
- package/dist/migrations/meta/0001_snapshot.json +224 -0
- package/dist/migrations/meta/_journal.json +20 -0
- package/dist/server.d.ts +8 -0
- package/dist/smtp/client.d.ts +28 -0
- package/dist/tools/attachments/get-attachment.d.ts +43 -0
- package/dist/tools/define-tool.d.ts +61 -0
- package/dist/tools/drafts/create-draft.d.ts +11 -0
- package/dist/tools/drafts/get-draft.d.ts +10 -0
- package/dist/tools/drafts/list-drafts.d.ts +11 -0
- package/dist/tools/drafts/update-draft.d.ts +12 -0
- package/dist/tools/emails/delete-email.d.ts +6 -0
- package/dist/tools/emails/get-email.d.ts +10 -0
- package/dist/tools/emails/list-emails.d.ts +14 -0
- package/dist/tools/emails/mark-read.d.ts +9 -0
- package/dist/tools/emails/move-to-folder.d.ts +6 -0
- package/dist/tools/emails/search-emails.d.ts +17 -0
- package/dist/tools/emails/shared.d.ts +74 -0
- package/dist/tools/folders/list-folders.d.ts +7 -0
- package/dist/tools/registry.d.ts +21 -0
- package/dist/tools/send/forward.d.ts +11 -0
- package/dist/tools/send/reply.d.ts +12 -0
- package/dist/tools/send/send-draft.d.ts +5 -0
- package/dist/tools/send/send-email.d.ts +10 -0
- package/dist/tools/send/shared.d.ts +40 -0
- package/dist/utils/logger.d.ts +40 -0
- package/package.json +90 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Krzysztof Bzowski
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
# mcp-inbox
|
|
2
|
+
|
|
3
|
+
> MCP server that gives any MCP-capable agent read/write access to your IMAP inbox, with a local SQLite cache for fast responses and IMAP IDLE for real-time updates.
|
|
4
|
+
|
|
5
|
+
Works with any IMAP/SMTP provider: Gmail, Outlook, Fastmail, iCloud, Proton Mail (via Bridge), Dovecot, hosted Exchange, self-hosted mail servers. Tools for listing and searching mail, composing and sending, managing drafts, inspecting attachment metadata. Cache stays in sync with the server via CONDSTORE + IDLE so most reads serve from local SQLite without a network round-trip.
|
|
6
|
+
|
|
7
|
+
**On attachments:** `imap_get_email` surfaces attachment metadata (filename, content type, size) by default - enough for the agent to describe what's attached without any download. When the agent genuinely needs to read content inside an attachment (search a PDF, extract a table from a CSV), `imap_get_attachment` fetches the bytes inline as base64 for one response. Nothing is cached on disk; re-requesting the same attachment refetches from the server.
|
|
8
|
+
|
|
9
|
+
**Status:** 0.1.0, early. See `CLAUDE.md` for architecture notes.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Requirements
|
|
14
|
+
|
|
15
|
+
- **Node.js 24 LTS** or newer (`node --version` should print `v24.x` or higher).
|
|
16
|
+
- An IMAP/SMTP account. Gmail and Outlook users need an **app password**, not the account password - see [Provider notes](#provider-notes).
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Configure
|
|
21
|
+
|
|
22
|
+
mcp-inbox reads credentials from environment variables. At minimum you need three:
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
IMAP_USER=you@example.com
|
|
26
|
+
IMAP_PASSWORD=your-app-password
|
|
27
|
+
IMAP_HOST=imap.example.com
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The full list of variables (ports, TLS flags, cache tuning, IDLE folders) lives in [.env.example](.env.example).
|
|
31
|
+
|
|
32
|
+
How those env vars reach the server process depends on which MCP client you use. Every client below lets you set env per-server.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Connect it to your client
|
|
37
|
+
|
|
38
|
+
Pick your client and follow the snippet. Each example sets `IMAP_USER`, `IMAP_PASSWORD`, and `IMAP_HOST`; add any optional variables from `.env.example` the same way.
|
|
39
|
+
|
|
40
|
+
### Claude Code (CLI)
|
|
41
|
+
|
|
42
|
+
Works on macOS, Linux, and Windows.
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
claude mcp add mcp-inbox \
|
|
46
|
+
--env IMAP_USER=you@example.com \
|
|
47
|
+
--env IMAP_PASSWORD=your-app-password \
|
|
48
|
+
--env IMAP_HOST=imap.gmail.com \
|
|
49
|
+
-- npx -y @kbzowski/mcp-inbox
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Add `-s user` (user scope) to make the server available in every project instead of just the current directory. List and verify with `claude mcp list`. Remove with `claude mcp remove mcp-inbox`.
|
|
53
|
+
|
|
54
|
+
**Windows note:** works directly; Claude Code wraps `npx` correctly on Windows since mid-2025. If you hit `spawn npx ENOENT`, upgrade Claude Code first.
|
|
55
|
+
|
|
56
|
+
### Claude Desktop
|
|
57
|
+
|
|
58
|
+
Config file location:
|
|
59
|
+
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
60
|
+
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
61
|
+
- **Linux** (unofficial): `~/.config/Claude/claude_desktop_config.json`
|
|
62
|
+
|
|
63
|
+
Edit (create the file if it doesn't exist) and merge this into the top-level object:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"mcpServers": {
|
|
68
|
+
"mcp-inbox": {
|
|
69
|
+
"command": "npx",
|
|
70
|
+
"args": ["-y", "@kbzowski/mcp-inbox"],
|
|
71
|
+
"env": {
|
|
72
|
+
"IMAP_USER": "you@example.com",
|
|
73
|
+
"IMAP_PASSWORD": "your-app-password",
|
|
74
|
+
"IMAP_HOST": "imap.gmail.com"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Restart Claude Desktop after saving. The server appears in the "Search and tools" menu once the handshake completes.
|
|
82
|
+
|
|
83
|
+
**Windows quirk:** if Claude Desktop fails to spawn `npx` (older Electron versions do this), replace the `command`/`args` pair with:
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
"command": "cmd",
|
|
87
|
+
"args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"],
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Codex CLI (OpenAI)
|
|
91
|
+
|
|
92
|
+
Config lives at `~/.codex/config.toml`:
|
|
93
|
+
|
|
94
|
+
```toml
|
|
95
|
+
[mcp_servers.mcp-inbox]
|
|
96
|
+
command = "npx"
|
|
97
|
+
args = ["-y", "@kbzowski/mcp-inbox"]
|
|
98
|
+
|
|
99
|
+
[mcp_servers.mcp-inbox.env]
|
|
100
|
+
IMAP_USER = "you@example.com"
|
|
101
|
+
IMAP_PASSWORD = "your-app-password"
|
|
102
|
+
IMAP_HOST = "imap.gmail.com"
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Verify with `codex mcp list`. If you're on Windows and Codex can't find `npx`, wrap it: `command = "cmd"`, `args = ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
|
|
106
|
+
|
|
107
|
+
### Cursor
|
|
108
|
+
|
|
109
|
+
**Option A - Settings UI:** Settings → MCP → Add new MCP server. Fill in:
|
|
110
|
+
- Name: `mcp-inbox`
|
|
111
|
+
- Type: `command`
|
|
112
|
+
- Command: `npx -y @kbzowski/mcp-inbox`
|
|
113
|
+
- Env: add `IMAP_USER`, `IMAP_PASSWORD`, `IMAP_HOST` one per line
|
|
114
|
+
|
|
115
|
+
**Option B - edit `~/.cursor/mcp.json`:**
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"mcpServers": {
|
|
120
|
+
"mcp-inbox": {
|
|
121
|
+
"command": "npx",
|
|
122
|
+
"args": ["-y", "@kbzowski/mcp-inbox"],
|
|
123
|
+
"env": {
|
|
124
|
+
"IMAP_USER": "you@example.com",
|
|
125
|
+
"IMAP_PASSWORD": "your-app-password",
|
|
126
|
+
"IMAP_HOST": "imap.gmail.com"
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
A workspace-scoped variant goes at `.cursor/mcp.json` in the project root.
|
|
134
|
+
|
|
135
|
+
### VS Code (native MCP)
|
|
136
|
+
|
|
137
|
+
VS Code added first-party MCP support in 2025. Enable it at the workspace level by creating `.vscode/mcp.json`:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"servers": {
|
|
142
|
+
"mcp-inbox": {
|
|
143
|
+
"type": "stdio",
|
|
144
|
+
"command": "npx",
|
|
145
|
+
"args": ["-y", "@kbzowski/mcp-inbox"],
|
|
146
|
+
"env": {
|
|
147
|
+
"IMAP_USER": "you@example.com",
|
|
148
|
+
"IMAP_PASSWORD": "your-app-password",
|
|
149
|
+
"IMAP_HOST": "imap.gmail.com"
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
User-level config: the `mcp` section under your settings JSON (`Cmd/Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)").
|
|
157
|
+
|
|
158
|
+
### Cline (VS Code extension)
|
|
159
|
+
|
|
160
|
+
Cline reads its MCP config from `cline_mcp_settings.json`. Open it from the Cline sidebar → MCP Servers → Configure MCP Servers. Add:
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{
|
|
164
|
+
"mcpServers": {
|
|
165
|
+
"mcp-inbox": {
|
|
166
|
+
"command": "npx",
|
|
167
|
+
"args": ["-y", "@kbzowski/mcp-inbox"],
|
|
168
|
+
"env": {
|
|
169
|
+
"IMAP_USER": "you@example.com",
|
|
170
|
+
"IMAP_PASSWORD": "your-app-password",
|
|
171
|
+
"IMAP_HOST": "imap.gmail.com"
|
|
172
|
+
},
|
|
173
|
+
"disabled": false,
|
|
174
|
+
"autoApprove": []
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Continue.dev
|
|
181
|
+
|
|
182
|
+
Edit `~/.continue/config.yaml`:
|
|
183
|
+
|
|
184
|
+
```yaml
|
|
185
|
+
mcpServers:
|
|
186
|
+
- name: mcp-inbox
|
|
187
|
+
command: npx
|
|
188
|
+
args:
|
|
189
|
+
- "-y"
|
|
190
|
+
- "@kbzowski/mcp-inbox"
|
|
191
|
+
env:
|
|
192
|
+
IMAP_USER: you@example.com
|
|
193
|
+
IMAP_PASSWORD: your-app-password
|
|
194
|
+
IMAP_HOST: imap.gmail.com
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### Zed
|
|
198
|
+
|
|
199
|
+
Zed's editor settings (`Cmd/Ctrl+,`) - add a `context_servers` entry:
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"context_servers": {
|
|
204
|
+
"mcp-inbox": {
|
|
205
|
+
"command": "npx",
|
|
206
|
+
"args": ["-y", "@kbzowski/mcp-inbox"],
|
|
207
|
+
"env": {
|
|
208
|
+
"IMAP_USER": "you@example.com",
|
|
209
|
+
"IMAP_PASSWORD": "your-app-password",
|
|
210
|
+
"IMAP_HOST": "imap.gmail.com"
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Goose (Block)
|
|
218
|
+
|
|
219
|
+
Edit `~/.config/goose/config.yaml`:
|
|
220
|
+
|
|
221
|
+
```yaml
|
|
222
|
+
extensions:
|
|
223
|
+
mcp-inbox:
|
|
224
|
+
type: stdio
|
|
225
|
+
cmd: npx
|
|
226
|
+
args: ["-y", "@kbzowski/mcp-inbox"]
|
|
227
|
+
envs:
|
|
228
|
+
IMAP_USER: you@example.com
|
|
229
|
+
IMAP_PASSWORD: your-app-password
|
|
230
|
+
IMAP_HOST: imap.gmail.com
|
|
231
|
+
enabled: true
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Any other MCP client
|
|
235
|
+
|
|
236
|
+
The pattern every MCP client shares:
|
|
237
|
+
|
|
238
|
+
| Field | Value |
|
|
239
|
+
|---|---|
|
|
240
|
+
| Transport | stdio |
|
|
241
|
+
| Command | `npx` |
|
|
242
|
+
| Args | `["-y", "@kbzowski/mcp-inbox"]` |
|
|
243
|
+
| Env | `IMAP_USER`, `IMAP_PASSWORD`, `IMAP_HOST` (minimum) |
|
|
244
|
+
|
|
245
|
+
If the client expects a bundled executable instead of `npx`, install globally (`npm i -g @kbzowski/mcp-inbox`) and point it at `mcp-inbox` directly.
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Provider notes
|
|
250
|
+
|
|
251
|
+
### Gmail / Google Workspace
|
|
252
|
+
|
|
253
|
+
Use an **[app password](https://myaccount.google.com/apppasswords)**, not your account password. Requires 2-Step Verification turned on first.
|
|
254
|
+
|
|
255
|
+
```
|
|
256
|
+
IMAP_HOST=imap.gmail.com
|
|
257
|
+
IMAP_PORT=993
|
|
258
|
+
SMTP_HOST=smtp.gmail.com
|
|
259
|
+
SMTP_PORT=465
|
|
260
|
+
SMTP_SECURE=true
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Outlook / Microsoft 365
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
IMAP_HOST=outlook.office365.com
|
|
267
|
+
IMAP_PORT=993
|
|
268
|
+
SMTP_HOST=smtp.office365.com
|
|
269
|
+
SMTP_PORT=587
|
|
270
|
+
SMTP_SECURE=false
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
Outlook rejects the default `SMTP_PORT=465` setting - both `SMTP_PORT=587` and `SMTP_SECURE=false` are required. Personal accounts need an [app password](https://account.microsoft.com/security) if 2FA is on.
|
|
274
|
+
|
|
275
|
+
### Fastmail
|
|
276
|
+
|
|
277
|
+
Use an [app password](https://app.fastmail.com/settings/security/devicekeys/add) (account-level passwords are rejected).
|
|
278
|
+
|
|
279
|
+
```
|
|
280
|
+
IMAP_HOST=imap.fastmail.com
|
|
281
|
+
SMTP_HOST=smtp.fastmail.com
|
|
282
|
+
SMTP_PORT=465
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### iCloud
|
|
286
|
+
|
|
287
|
+
Requires an [app-specific password](https://account.apple.com) from your Apple ID security settings.
|
|
288
|
+
|
|
289
|
+
```
|
|
290
|
+
IMAP_HOST=imap.mail.me.com
|
|
291
|
+
SMTP_HOST=smtp.mail.me.com
|
|
292
|
+
SMTP_PORT=587
|
|
293
|
+
SMTP_SECURE=false
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Proton Mail
|
|
297
|
+
|
|
298
|
+
Proton Mail requires [Proton Mail Bridge](https://proton.me/mail/bridge) running locally; point mcp-inbox at the Bridge's advertised host/port (usually `127.0.0.1:1143` for IMAP).
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Troubleshooting
|
|
303
|
+
|
|
304
|
+
### "IMAP authentication failed"
|
|
305
|
+
|
|
306
|
+
You're almost certainly using your account password instead of an app password. See the provider-specific links above.
|
|
307
|
+
|
|
308
|
+
### The client can't find `npx` / `spawn ENOENT`
|
|
309
|
+
|
|
310
|
+
On Windows, some older clients don't resolve `.cmd` shims. Wrap the command:
|
|
311
|
+
|
|
312
|
+
```json
|
|
313
|
+
"command": "cmd",
|
|
314
|
+
"args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Or install globally and use the binary directly:
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
npm install -g @kbzowski/mcp-inbox
|
|
321
|
+
# then set command: "mcp-inbox" (no args)
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
### Passwords with shell-special characters
|
|
325
|
+
|
|
326
|
+
If your password contains `$`, `` ` ``, `!`, or a backslash, put it in an env file / config JSON rather than passing it on a shell command line. The config files above handle this correctly; `claude mcp add --env IMAP_PASSWORD=...` works if you **single-quote** the value in your shell.
|
|
327
|
+
|
|
328
|
+
### First-run takes a while
|
|
329
|
+
|
|
330
|
+
The first `npx -y @kbzowski/mcp-inbox` invocation downloads the package. Subsequent runs are cached. If it looks hung on first boot, check your network.
|
|
331
|
+
|
|
332
|
+
### Verify the connection manually
|
|
333
|
+
|
|
334
|
+
From any shell, set the env vars and run:
|
|
335
|
+
|
|
336
|
+
```bash
|
|
337
|
+
IMAP_USER=you@example.com IMAP_PASSWORD=... IMAP_HOST=imap.gmail.com npx -y @kbzowski/mcp-inbox
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
On success you'll see JSON log lines on stderr: `booting mcp-inbox` and `mcp-inbox ready`. The server then idles on stdin (waiting for MCP JSON-RPC). Hit `Ctrl+C` to stop.
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## Tool catalog
|
|
345
|
+
|
|
346
|
+
All tools are prefixed `imap_` so they don't collide with other email MCPs. Every read tool accepts `response_format: "markdown" | "json"` (default markdown) and `max_staleness_seconds` (default 60 - serves from cache when fresh, syncs otherwise).
|
|
347
|
+
|
|
348
|
+
### Discovery
|
|
349
|
+
|
|
350
|
+
- **`imap_list_folders`** - list every mailbox with its path, delimiter, and RFC 6154 special-use attribute (`\Drafts`, `\Sent`, `\Trash`, `\Junk`).
|
|
351
|
+
- **`imap_list_emails`** `(folder?, limit?, offset?, unseen_only?, since_date?, before_date?)` - paginated envelope list, newest first. Defaults to `INBOX`, 20 per page.
|
|
352
|
+
- **`imap_search_emails`** `(folder?, subject?, from?, to?, body?, unseen?, since_date?, before_date?)` - IMAP SEARCH on the server, returns matching envelopes from the cache. At least one criterion required.
|
|
353
|
+
|
|
354
|
+
### Reading
|
|
355
|
+
|
|
356
|
+
- **`imap_get_email`** `(folder, uid)` - full message: headers, plain text, HTML, and attachment metadata (filename, content type, size).
|
|
357
|
+
- **`imap_list_drafts`** `(folder?, limit?, offset?)` - same as list_emails but auto-resolves the Drafts folder via SPECIAL-USE.
|
|
358
|
+
- **`imap_get_draft`** `(uid, folder?)` - full draft content by UID.
|
|
359
|
+
- **`imap_get_attachment`** `(folder, uid, filename? | part_id?, max_inline_mb?)` - download an attachment as base64 bytes, inline in the response. Memory-only, no disk cache. Default cap is 5 MB; raise via `max_inline_mb` (up to 50).
|
|
360
|
+
|
|
361
|
+
### Flagging / filing
|
|
362
|
+
|
|
363
|
+
- **`imap_mark_read`** `(folder, uid)` - add `\Seen`. Idempotent.
|
|
364
|
+
- **`imap_mark_unread`** `(folder, uid)` - remove `\Seen`. Idempotent.
|
|
365
|
+
- **`imap_move_to_folder`** `(folder, uid, destination)` - IMAP MOVE with COPY+EXPUNGE fallback.
|
|
366
|
+
- **`imap_delete_email`** `(folder, uid, hard_delete?)` - defaults to move-to-Trash. `hard_delete: true` permanently expunges.
|
|
367
|
+
|
|
368
|
+
### Composing
|
|
369
|
+
|
|
370
|
+
- **`imap_create_draft`** `(to, subject, body?, html?, cc?, bcc?, from?)` - appends a new draft to the Drafts folder with the `\Draft` flag. nodemailer handles the RFC 2822 construction, so non-ASCII subjects, long bodies, and multipart text+HTML all just work.
|
|
371
|
+
- **`imap_update_draft`** `(uid, to, subject, body?, html?, cc?, bcc?, from?)` - replaces an existing draft. Append-then-delete: the new draft is written first, only then is the old UID removed. A failure in the middle never loses the draft.
|
|
372
|
+
|
|
373
|
+
### Sending
|
|
374
|
+
|
|
375
|
+
- **`imap_send_email`** `(to, subject, body?, html?, cc?, bcc?, from?)` - SMTP send + best-effort append to the Sent folder so the message shows up in the user's mail client.
|
|
376
|
+
- **`imap_send_draft`** `(uid, folder?)` - fetches raw source of the draft, sends it exactly as written (preserves attachments and formatting), then deletes the draft.
|
|
377
|
+
- **`imap_reply`** `(folder, uid, body?, html?, reply_all?, cc?, bcc?, from?)` - preserves threading via `In-Reply-To` / `References`. Subject gets a `Re: ` prefix.
|
|
378
|
+
- **`imap_forward`** `(folder, uid, to, body?, cc?, bcc?, from?)` - quotes the original inline, `Fwd: ` subject prefix.
|
|
379
|
+
|
|
380
|
+
### Tool annotations
|
|
381
|
+
|
|
382
|
+
Every tool carries MCP annotations so clients can gate destructive actions:
|
|
383
|
+
|
|
384
|
+
| Tool | readOnly | destructive | idempotent |
|
|
385
|
+
|---|:-:|:-:|:-:|
|
|
386
|
+
| list_folders / list_emails / get_email / search_emails / list_drafts / get_draft / get_attachment | ✓ | | ✓ |
|
|
387
|
+
| mark_read / mark_unread | | | ✓ |
|
|
388
|
+
| move_to_folder / delete_email | | ✓ | |
|
|
389
|
+
| create_draft / update_draft | | | |
|
|
390
|
+
| send_email / send_draft / reply / forward | | ✓ | |
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## License
|
|
395
|
+
|
|
396
|
+
MIT. Copyright (c) 2026 Krzysztof Bzowski. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { drizzle } from 'drizzle-orm/better-sqlite3';
|
|
2
|
+
import * as schema from './schema';
|
|
3
|
+
/**
|
|
4
|
+
* Default migrations folder resolved relative to this module.
|
|
5
|
+
*
|
|
6
|
+
* - Dev (tsx / vitest): `src/cache/migrations/`
|
|
7
|
+
* - Built binary (dist/index.js): `dist/migrations/` (build script
|
|
8
|
+
* copies the migrations there so the shipped tarball is self-contained)
|
|
9
|
+
*/
|
|
10
|
+
export declare const DEFAULT_MIGRATIONS_FOLDER: string;
|
|
11
|
+
export type CacheDb = ReturnType<typeof drizzle<typeof schema>>;
|
|
12
|
+
export interface CacheHandle {
|
|
13
|
+
db: CacheDb;
|
|
14
|
+
/** Release the underlying SQLite connection. Safe to call more than once. */
|
|
15
|
+
close: () => void;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Open (or create) the cache database, run pending migrations, and return
|
|
19
|
+
* a Drizzle-wrapped handle.
|
|
20
|
+
*
|
|
21
|
+
* Why better-sqlite3 and not node:sqlite: Drizzle 0.45.x does not yet
|
|
22
|
+
* ship a node:sqlite driver (tracking issue: drizzle-team/drizzle-orm#2648).
|
|
23
|
+
* better-sqlite3 is Drizzle's first-class SQLite driver, synchronous
|
|
24
|
+
* (matches our call-graph assumptions), and ships prebuilt binaries for
|
|
25
|
+
* Windows/macOS/Linux on Node 24 so end users don't need a build toolchain.
|
|
26
|
+
*
|
|
27
|
+
* @param path Absolute file path, or `:memory:` for an in-process database
|
|
28
|
+
* (used by unit tests).
|
|
29
|
+
* @param migrationsFolder Directory containing drizzle-kit output
|
|
30
|
+
* (e.g. src/cache/migrations). When omitted, migrations are
|
|
31
|
+
* skipped - typical only for :memory: unit tests that don't
|
|
32
|
+
* need a migration history.
|
|
33
|
+
*/
|
|
34
|
+
export declare function openCache(path: string, migrationsFolder?: string): CacheHandle;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { AppConfig } from '../config/env';
|
|
2
|
+
import type { CacheDb } from './db';
|
|
3
|
+
/**
|
|
4
|
+
* One held-open IMAP connection per watched folder. IMAP's SELECT is
|
|
5
|
+
* single-mailbox, so watching N folders needs N connections.
|
|
6
|
+
*
|
|
7
|
+
* Server-side events drive cache updates:
|
|
8
|
+
* - `exists` triggers an incremental sync (CONDSTORE makes this cheap).
|
|
9
|
+
* - `flags` updates the cached row directly if we got a UID, otherwise
|
|
10
|
+
* re-syncs the folder.
|
|
11
|
+
* - `expunge` deletes the cached row if we got a UID, otherwise re-syncs.
|
|
12
|
+
*
|
|
13
|
+
* ImapFlow handles the auto-re-IDLE loop internally; callers only need
|
|
14
|
+
* to `mailboxOpen(path)` and subscribe to events.
|
|
15
|
+
*/
|
|
16
|
+
export interface IdleSubscription {
|
|
17
|
+
folder: string;
|
|
18
|
+
stop: () => Promise<void>;
|
|
19
|
+
}
|
|
20
|
+
export interface IdleManagerOptions {
|
|
21
|
+
imap: AppConfig['imap'];
|
|
22
|
+
db: CacheDb;
|
|
23
|
+
folders: readonly string[];
|
|
24
|
+
}
|
|
25
|
+
export declare class IdleManager {
|
|
26
|
+
#private;
|
|
27
|
+
constructor(opts: IdleManagerOptions);
|
|
28
|
+
/** Open a watching connection per configured folder. Idempotent. */
|
|
29
|
+
start(): Promise<void>;
|
|
30
|
+
/** Release every watching connection. Idempotent. */
|
|
31
|
+
stop(): Promise<void>;
|
|
32
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import type { CacheDb } from './db';
|
|
2
|
+
import { type Folder, type FolderInsert, type Email, type EmailInsert } from './schema';
|
|
3
|
+
/**
|
|
4
|
+
* Insert or update a folder row (matched on the primary-key `name`).
|
|
5
|
+
* Used after every SELECT to record the current UIDVALIDITY / UIDNEXT /
|
|
6
|
+
* HIGHESTMODSEQ + refresh `lastSyncedAt`.
|
|
7
|
+
*/
|
|
8
|
+
export declare function upsertFolder(db: CacheDb, row: FolderInsert): void;
|
|
9
|
+
export declare function getFolder(db: CacheDb, name: string): Folder | undefined;
|
|
10
|
+
export declare function listFolders(db: CacheDb): Folder[];
|
|
11
|
+
/**
|
|
12
|
+
* Insert or update an email envelope. Matched on (folder, uid) - IMAP UIDs
|
|
13
|
+
* are folder-scoped, never global.
|
|
14
|
+
*/
|
|
15
|
+
export declare function upsertEmail(db: CacheDb, row: EmailInsert): void;
|
|
16
|
+
export declare function getEmail(db: CacheDb, folder: string, uid: number): Email | undefined;
|
|
17
|
+
export interface ListEmailsOptions {
|
|
18
|
+
/** Max rows to return. */
|
|
19
|
+
limit?: number;
|
|
20
|
+
/** Rows to skip (for pagination). */
|
|
21
|
+
offset?: number;
|
|
22
|
+
/** If true, only messages without the \\Seen flag. */
|
|
23
|
+
unseenOnly?: boolean;
|
|
24
|
+
/** Only messages received at/after this epoch-ms timestamp. */
|
|
25
|
+
sinceMs?: number;
|
|
26
|
+
/** Only messages received strictly before this epoch-ms timestamp. */
|
|
27
|
+
beforeMs?: number;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* List cached emails in a folder, newest first by IMAP INTERNALDATE.
|
|
31
|
+
* Messages with a null date sort last - preserves determinism when a
|
|
32
|
+
* provider returns envelope-only rows without dates.
|
|
33
|
+
*/
|
|
34
|
+
export declare function listEmailsByFolder(db: CacheDb, folder: string, opts?: ListEmailsOptions): Email[];
|
|
35
|
+
export declare function countEmailsInFolder(db: CacheDb, folder: string): number;
|
|
36
|
+
/**
|
|
37
|
+
* Replace the flag set on a cached email. Used for write-through
|
|
38
|
+
* invalidation after mark-read/mark-unread, and when IDLE delivers
|
|
39
|
+
* a FLAGS update.
|
|
40
|
+
*/
|
|
41
|
+
export declare function setEmailFlags(db: CacheDb, folder: string, uid: number, flags: string[]): void;
|
|
42
|
+
/**
|
|
43
|
+
* Wipe every cached message in a folder. Invoked when UIDVALIDITY changes
|
|
44
|
+
* on the server - all our UIDs have been invalidated at once.
|
|
45
|
+
*/
|
|
46
|
+
export declare function deleteEmailsByFolder(db: CacheDb, folder: string): void;
|
|
47
|
+
/**
|
|
48
|
+
* Remove a single cached email. Invoked on EXPUNGE from IDLE, and after
|
|
49
|
+
* destructive tools (delete_email, move_to_folder) succeed on the server.
|
|
50
|
+
*/
|
|
51
|
+
export declare function deleteEmail(db: CacheDb, folder: string, uid: number): void;
|
|
52
|
+
/**
|
|
53
|
+
* Remove a batch of UIDs from the cache in one statement. Used by the
|
|
54
|
+
* EXPUNGE-detection path of the UID-diff sync fallback.
|
|
55
|
+
*/
|
|
56
|
+
export declare function deleteEmailsByUids(db: CacheDb, folder: string, uids: number[]): void;
|
|
57
|
+
export interface CachedBody {
|
|
58
|
+
bodyText: string | null;
|
|
59
|
+
bodyHtml: string | null;
|
|
60
|
+
bodyCachedAt: number | null;
|
|
61
|
+
}
|
|
62
|
+
export declare function getEmailBody(db: CacheDb, folder: string, uid: number): CachedBody | undefined;
|
|
63
|
+
export declare function setEmailBody(db: CacheDb, folder: string, uid: number, body: {
|
|
64
|
+
text: string | null;
|
|
65
|
+
html: string | null;
|
|
66
|
+
}, nowMs: number): void;
|