@kbzowski/mcp-inbox 0.5.1 → 0.6.1
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/README.md +88 -0
- package/dist/app.js +1559 -426
- package/dist/cache/backfill.d.ts +35 -0
- package/dist/cache/db.d.ts +7 -2
- package/dist/cache/indexer.d.ts +34 -0
- package/dist/cache/queries.d.ts +18 -0
- package/dist/cache/schema.d.ts +117 -0
- package/dist/cache/vectors.d.ts +77 -0
- package/dist/config/env.d.ts +38 -0
- package/dist/embeddings/chunk.d.ts +3 -0
- package/dist/embeddings/client.d.ts +11 -0
- package/dist/errors/types.d.ts +3 -1
- package/dist/formatters/markdown.d.ts +23 -0
- package/dist/http.d.ts +14 -0
- package/dist/imap/body-text.d.ts +47 -0
- package/dist/migrations/20260804153609_illegal_scream/migration.sql +8 -0
- package/dist/migrations/20260804153609_illegal_scream/snapshot.json +383 -0
- package/dist/tools/define-tool.d.ts +4 -0
- package/dist/tools/emails/index-folder.d.ts +10 -0
- package/dist/tools/emails/semantic-search.d.ts +13 -0
- package/dist/tools/emails/shared.d.ts +14 -0
- package/dist/utils/logger.d.ts +8 -5
- package/package.json +20 -20
package/README.md
CHANGED
|
@@ -46,6 +46,59 @@ claude mcp add inbox --scope project \
|
|
|
46
46
|
|
|
47
47
|
The same `mcpServers` object works in `claude_desktop_config.json`, `~/.cursor/mcp.json` and `cline_mcp_settings.json`. VS Code reads `.vscode/mcp.json` and calls the key `servers`, not `mcpServers`. Codex CLI, Zed, Continue and Goose use their own formats: [docs/clients.md](docs/clients.md).
|
|
48
48
|
|
|
49
|
+
### Docker
|
|
50
|
+
|
|
51
|
+
No Node on the host? Build the image and let the agent run it. The server talks over stdio, so the container needs `-i` (and no `-t`).
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
docker build -t mcp-inbox .
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"mcpServers": {
|
|
60
|
+
"inbox": {
|
|
61
|
+
"command": "docker",
|
|
62
|
+
"args": [
|
|
63
|
+
"run", "-i", "--rm",
|
|
64
|
+
"-v", "mcp-inbox-cache:/data",
|
|
65
|
+
"-e", "IMAP_USER", "-e", "IMAP_PASSWORD", "-e", "IMAP_HOST",
|
|
66
|
+
"mcp-inbox"
|
|
67
|
+
],
|
|
68
|
+
"env": {
|
|
69
|
+
"IMAP_USER": "you@example.com",
|
|
70
|
+
"IMAP_PASSWORD": "your-app-password",
|
|
71
|
+
"IMAP_HOST": "imap.example.com"
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The `mcp-inbox-cache` volume keeps the SQLite cache between runs; without it every start re-syncs from scratch. Pass any other variable from [Environment](#environment) the same way (`-e NAME`).
|
|
79
|
+
|
|
80
|
+
### Shared server (streamable HTTP)
|
|
81
|
+
|
|
82
|
+
To connect several clients to one server, run it over HTTP instead of stdio. Set `MCP_HTTP_PORT` and `MCP_AUTH_TOKEN` (16+ characters; required, because this exposes your mailbox). Put both in `.env` and run `docker compose up -d`; `compose.yaml` publishes `127.0.0.1:3333`. Without Docker: `MCP_HTTP_PORT=3333 MCP_AUTH_TOKEN=... npx -y @kbzowski/mcp-inbox`.
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"mcpServers": {
|
|
87
|
+
"inbox": {
|
|
88
|
+
"type": "http",
|
|
89
|
+
"url": "http://localhost:3333/mcp",
|
|
90
|
+
"headers": { "Authorization": "Bearer your-token" }
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Claude Code: `claude mcp add --transport http inbox http://localhost:3333/mcp --header "Authorization: Bearer your-token"`. The server is stateless and shares one IMAP connection and cache across clients. There is no TLS; keep it on localhost or put a reverse proxy in front.
|
|
97
|
+
|
|
98
|
+
The image is Debian-based on purpose: `sqlite-vec` (semantic search) has no Alpine build. If your embeddings server runs on the host, use `host.docker.internal` instead of `localhost` in `IMAP_EMBEDDINGS_BASE_URL`.
|
|
99
|
+
|
|
100
|
+
To run embeddings locally alongside the server, add the Ollama overlay: `docker compose -f compose.yaml -f compose.embeddings.yaml up -d`. It pulls `snowflake-arctic-embed2` (~1.2 GB) on first start and keeps Ollama off the host network, so mail text never leaves the machine. Its settings override any `IMAP_EMBEDDINGS_*` in `.env`, and the model change rebuilds the index.
|
|
101
|
+
|
|
49
102
|
### Credentials
|
|
50
103
|
|
|
51
104
|
Gmail, Outlook, Fastmail and iCloud all need an **app password**, not the account password.
|
|
@@ -69,6 +122,8 @@ All prefixed `imap_`. Read tools take `response_format: "markdown" | "json"` (de
|
|
|
69
122
|
| `imap_list_folders` | |
|
|
70
123
|
| `imap_list_emails` | `folder?, limit?, offset?, unseen_only?, since_date?, before_date?` |
|
|
71
124
|
| `imap_search_emails` | `folder?, subject?, from?, to?, body?, unseen?, flagged?, answered?, since_date?, before_date?, or?, not?` |
|
|
125
|
+
| `imap_semantic_search` | `query, folder?, limit?, since_date?, before_date?` |
|
|
126
|
+
| `imap_index_folder` | `folders?, max_messages?` |
|
|
72
127
|
| `imap_get_email` | `folder, uid` |
|
|
73
128
|
| `imap_get_attachment` | `folder, uid, filename? \| part_id?, max_inline_mb?` |
|
|
74
129
|
| `imap_list_drafts` | `folder?, limit?, offset?` |
|
|
@@ -98,6 +153,31 @@ Worth knowing:
|
|
|
98
153
|
|
|
99
154
|
`destructiveHint` is set on move, delete, and everything that sends.
|
|
100
155
|
|
|
156
|
+
## Semantic search (optional)
|
|
157
|
+
|
|
158
|
+
`imap_search_emails` matches literal text on the server. `imap_semantic_search` matches meaning: "the invoice from the hosting provider" finds a message titled "Payment receipt #4417". It works across languages and paraphrases, and it only ranks what has been indexed.
|
|
159
|
+
|
|
160
|
+
Indexing covers the subject, the sender, and the message text, so a message is findable by what it says even when its subject is useless ("Re: 4417"). Quoted reply history is stripped before embedding, and a message is ranked by its single most relevant passage.
|
|
161
|
+
|
|
162
|
+
Off unless you set `IMAP_EMBEDDINGS_BASE_URL`. Any OpenAI-compatible `/v1/embeddings` endpoint works, including a local one:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
IMAP_EMBEDDINGS_BASE_URL=https://your-endpoint/v1
|
|
166
|
+
IMAP_EMBEDDINGS_API_KEY=sk-...
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Indexing is opt-in per folder.** Run `imap_index_folder` on the folders you care about before searching them - it takes a list, and they share the call's `max_messages` budget. That call sends each message's subject, sender, and body text to the configured endpoint. **Attachments are never downloaded or sent** - only the message's text part is fetched, which on a real mailbox is roughly 80x less data than the full messages. It is safe to re-run: already-indexed messages are skipped, so a large folder can be indexed over several calls. Afterwards a background pass keeps every indexed folder current, so new mail becomes searchable on its own. It runs every `IMAP_EMBEDDINGS_SWEEP_MINUTES` (15 by default, `0` disables it) and embeds at most `IMAP_EMBEDDINGS_SWEEP_BATCH` messages per pass. Searching never writes, so its latency stays predictable; `pending_index` tells you when the index is still catching up.
|
|
170
|
+
|
|
171
|
+
`imap_semantic_search` takes an optional `folder`. Omit it and every indexed folder is searched in one pass, with each result reporting the folder it came from.
|
|
172
|
+
|
|
173
|
+
If your IMAP server refuses to serve individual body parts, indexing falls back to subjects and senders alone and says so: `bodies_indexed` comes back as zero.
|
|
174
|
+
|
|
175
|
+
Vectors live in the same SQLite cache as everything else and survive restarts. They also outlive the message bodies that `IMAP_CACHE_BODY_RETAIN_DAYS` prunes, so old mail stays findable.
|
|
176
|
+
|
|
177
|
+
Changing `IMAP_EMBEDDINGS_MODEL` or `IMAP_EMBEDDINGS_DIMS` drops the index - the vector table's dimensionality is fixed when it is created. Upgrading mcp-inbox can do the same when the index format changes. Either way the fix is the same: re-run `imap_index_folder`.
|
|
178
|
+
|
|
179
|
+
**Platform support.** Vector search needs the `sqlite-vec` extension, which ships prebuilt binaries for linux-x64/arm64, macOS x64/arm64, and windows-x64. On **windows-arm64 and Alpine/musl** there is no binary: the two semantic tools return a clear error pointing at `imap_search_emails`, and every other tool works normally.
|
|
180
|
+
|
|
101
181
|
## Environment
|
|
102
182
|
|
|
103
183
|
| Variable | Default |
|
|
@@ -113,6 +193,14 @@ Worth knowing:
|
|
|
113
193
|
| `IMAP_CACHE_DIR` | platform cache dir |
|
|
114
194
|
| `IMAP_CACHE_DEFAULT_STALENESS_SEC` | `60` |
|
|
115
195
|
| `IMAP_CACHE_BODY_RETAIN_DAYS` | `180` (`0` keeps forever) |
|
|
196
|
+
| `IMAP_EMBEDDINGS_BASE_URL` | unset (semantic search off) |
|
|
197
|
+
| `IMAP_EMBEDDINGS_API_KEY` | unset (no auth header sent) |
|
|
198
|
+
| `IMAP_EMBEDDINGS_MODEL` | `arctic-embed-l-v2` |
|
|
199
|
+
| `IMAP_EMBEDDINGS_DIMS` | `1024` |
|
|
200
|
+
| `IMAP_EMBEDDINGS_BATCH_SIZE` | `64` |
|
|
201
|
+
| `IMAP_EMBEDDINGS_TIMEOUT_MS` | `30000` |
|
|
202
|
+
| `IMAP_EMBEDDINGS_SWEEP_MINUTES` | `15` (`0` disables background indexing) |
|
|
203
|
+
| `IMAP_EMBEDDINGS_SWEEP_BATCH` | `200` |
|
|
116
204
|
| `IMAP_IDLE_ENABLED` | `true` |
|
|
117
205
|
| `IMAP_IDLE_FOLDERS` | `INBOX` (empty disables) |
|
|
118
206
|
| `DEBUG` | unset; try `mcp-inbox:*` |
|