mailmate 1.5.0 → 1.6.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.
- checksums.yaml +4 -4
- data/README.md +146 -92
- data/lib/mailmate/cli/search.rb +2 -2
- data/lib/mailmate/mcp.rb +26 -6
- data/lib/mailmate/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b395d407ecab6e32e9e9d94da136031b0edd5cfa0302809721940a0dcefa2ba7
|
|
4
|
+
data.tar.gz: 80d7dc99046e899093e57422153e1b413f7688b5e1d080aa9ae7898778b92136
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 55136934383ab2be45fec5c5787242594a33208b6d71bffedf0b0ee4a0e1176f5876b4b09611c9716afcf34e6d7132a687e6c907a27f586b9a89f5ef7c9e4da1
|
|
7
|
+
data.tar.gz: 481da51efb264b36587908af1ab321d5f63c2174a3f2502be5722bb45600243433c210e30ad869737e531a8d4bffa97ffd371835265346c27dfef177d74ff24f
|
data/README.md
CHANGED
|
@@ -4,6 +4,144 @@ Ruby toolkit for [MailMate](https://freron.com) on macOS — a smart-mailbox fil
|
|
|
4
4
|
|
|
5
5
|
**Requires macOS with MailMate installed.** The library code (filter parser, evaluator) works anywhere, but the integration with MailMate itself — AppleScript, on-disk index reads, the `emate` binary — is macOS-only by way of MailMate being macOS-only.
|
|
6
6
|
|
|
7
|
+
## Privacy Policy
|
|
8
|
+
|
|
9
|
+
This gem — including its MCP server — contains **no networking code at all**.
|
|
10
|
+
It never opens a network connection of any kind, for any purpose: no HTTP, no
|
|
11
|
+
sockets, no telemetry endpoints. You can verify this from the source — there
|
|
12
|
+
isn't a single `net/*`, `open-uri`, or socket require anywhere in `lib/` or
|
|
13
|
+
`exe/`. The only network activity in the project's entire lifecycle happens at
|
|
14
|
+
install time: `gem install` fetches from rubygems.org, and `install.sh` may
|
|
15
|
+
additionally fetch a relocatable Ruby from GitHub. After that, nothing.
|
|
16
|
+
|
|
17
|
+
- **Data collection:** none. No telemetry, analytics, usage data, or crash
|
|
18
|
+
reports — and no code capable of transmitting them.
|
|
19
|
+
- **Usage and storage:** the gem reads MailMate's existing on-disk mail store
|
|
20
|
+
(`~/Library/Application Support/MailMate`) and drives the MailMate app via
|
|
21
|
+
AppleScript. It creates no data stores of its own beyond files you
|
|
22
|
+
explicitly ask it to write. The only optional configuration file is
|
|
23
|
+
`~/.config/mailmate/config.yml`, which you author yourself.
|
|
24
|
+
- **Third-party sharing:** none by the gem itself — it has no means to share
|
|
25
|
+
anything. Two things *adjacent* to it can move data off your machine, and
|
|
26
|
+
both are under your control: (1) `mm-send` / the `send` tool hands the
|
|
27
|
+
message to the MailMate app, and **MailMate** performs the delivery to the
|
|
28
|
+
recipients you named — the gem transmits nothing; (2) when the MCP server
|
|
29
|
+
is used from an AI client (Claude Desktop, Claude Code, etc.), message
|
|
30
|
+
content returned by its tools enters that client's conversation and is
|
|
31
|
+
transmitted to that AI provider under *its* privacy policy — choose which
|
|
32
|
+
messages you surface accordingly.
|
|
33
|
+
- **Data retention:** none. The gem retains nothing between invocations;
|
|
34
|
+
your mail stays wherever MailMate keeps it.
|
|
35
|
+
- **Contact:** brian@murphydye.com, or open an issue at
|
|
36
|
+
<https://github.com/brianmd/mailmate/issues>.
|
|
37
|
+
|
|
38
|
+
## Install
|
|
39
|
+
|
|
40
|
+
Pick the path that matches how you'll use it:
|
|
41
|
+
|
|
42
|
+
- **Claude Code plugin** — MCP tools for Claude, zero manual setup (below)
|
|
43
|
+
- **One-line installer** — the MCP server for any MCP client, fully isolated under `~/.mailmate-mcp`
|
|
44
|
+
- **`gem install mailmate`** — the CLI tools (and MCP server) on your own Ruby
|
|
45
|
+
|
|
46
|
+
### Requirements
|
|
47
|
+
|
|
48
|
+
- **macOS** with **MailMate** installed (and running, for any command that drives the UI or sends mail).
|
|
49
|
+
- **Ruby ≥ 3.0** — for the plugin and one-line installer this is optional: if no suitable Ruby is found, they download a private relocatable Ruby into `~/.mailmate-mcp/ruby` and never touch your system.
|
|
50
|
+
- No third-party CLI tools — the gem only shells out to macOS-bundled `plutil`, `osascript`, and `open`, plus MailMate's bundled `emate`.
|
|
51
|
+
|
|
52
|
+
### Claude Code plugin
|
|
53
|
+
|
|
54
|
+
This repo doubles as a Claude Code plugin marketplace. Inside Claude Code:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
/plugin marketplace add brianmd/mailmate
|
|
58
|
+
/plugin install mailmate@brianmd
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The plugin's MCP server self-provisions on first launch — Ruby (if needed) and gem dependencies go into `~/.mailmate-mcp`; nothing touches your system Ruby, Homebrew, or shell profile. It runs the plugin's bundled source, so plugin updates take effect without waiting for a gem release. Uninstall: `/plugin uninstall mailmate`, then `rm -rf ~/.mailmate-mcp`.
|
|
62
|
+
|
|
63
|
+
### One-line installer (any MCP client)
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
curl -fsSL https://raw.githubusercontent.com/brianmd/mailmate/main/install.sh | bash
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Installs the released gem into an isolated `GEM_HOME` under `~/.mailmate-mcp` (provisioning a private Ruby only if none ≥ 3.0 is found), writes a launcher shim, and registers it with Claude Code when the `claude` CLI is present (pass `--no-register` to skip). For Claude Desktop, add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"mcpServers": {
|
|
74
|
+
"mailmate": { "command": "/Users/<you>/.mailmate-mcp/bin/mailmate-mcp" }
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`~/.mailmate-mcp` is the entire footprint. Uninstall: `bash install.sh --uninstall` (or just delete the directory), plus `claude mcp remove mailmate`.
|
|
80
|
+
|
|
81
|
+
### As a Ruby gem (CLI tools)
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
gem install mailmate
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Then optionally bootstrap your config (will happen automatically on first invocation of any command from an interactive shell if it hasn't been run before):
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
mmdiscover
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`mmdiscover` reads MailMate's `Sources.plist` and `Identities.plist`, shows you the accounts and addresses it found, and offers to write `~/.config/mailmate/config.yml` from them. It also writes `~/.config/mailmate/bundle_loader.rb` for MailMate bundles. Running it explicitly is only needed in non-TTY contexts (cron jobs, MCP servers) — there, the gem falls back to built-in defaults and warns once.
|
|
94
|
+
|
|
95
|
+
### Optional: `mmmessage --markdown`
|
|
96
|
+
|
|
97
|
+
**On the vast majority of Ruby setups (stock `arm64-darwin` or `x86_64-darwin` Ruby) this step is a no-op — nokogiri ships a precompiled binary, you can skip the rest of this section and move on.** Keep reading only if your `gem install` actually fails.
|
|
98
|
+
|
|
99
|
+
`mmmessage --markdown` renders HTML-only message bodies as readable markdown. It needs the `reverse_markdown` gem, which has `nokogiri` as a transitive dependency:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
gem install reverse_markdown
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
That single command pulls `nokogiri` in automatically — no separate `gem install nokogiri` step. This is kept out of the base install because nokogiri ships a native extension. On Ruby/platform combinations without a precompiled match nokogiri falls back to compiling from source — it vendors its own libxml2/libxslt, but it does need a C compiler, which on macOS means Xcode Command Line Tools (`xcode-select --install`). If `gem install reverse_markdown` fails, that's almost certainly the cause.
|
|
106
|
+
|
|
107
|
+
If you never use `--markdown`, you never pay any of this. If you do invoke `--markdown` without the gem installed, `mmmessage` warns with a clear install hint and falls back to the raw HTML body (it does not abort — so the in-process MCP server survives a missing optional dependency). The plugin launcher and one-line installer attempt this gem automatically and degrade the same way if it fails to build.
|
|
108
|
+
|
|
109
|
+
### From source (development)
|
|
110
|
+
|
|
111
|
+
If you're hacking on the gem itself, skip `gem install` and put the repo's `exe/` on your `PATH`. Clone wherever you keep source repos, then prepend its `exe/` to `PATH` from your shell's rc file (`~/.zshrc`, `~/.bashrc`, etc.):
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
git clone https://github.com/brianmd/mailmate.git
|
|
115
|
+
cd mailmate
|
|
116
|
+
|
|
117
|
+
# In your shell rc file, add (adjust the path to wherever you cloned):
|
|
118
|
+
# export PATH="/absolute/path/to/mailmate/exe:$PATH"
|
|
119
|
+
# Then reload the shell (open a new tab, or `source` the rc file).
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Then `mmdiscover` as above.
|
|
123
|
+
|
|
124
|
+
### MCP server (manual setup)
|
|
125
|
+
|
|
126
|
+
The gem ships an MCP server (`exe/mailmate-mcp`) that exposes the same surface to AI assistants as JSON-RPC tools: `search`, `message`, `modify`, `verify`, `send`, `draft`, `open`, `list_mailboxes`, `list_tags`, `resolve_id`. Every tool carries MCP annotations (`readOnlyHint`/`destructiveHint`) so clients can apply sensible permission behavior. If you installed via the plugin or one-line installer above, this is already wired up; after a plain `gem install mailmate`, register it yourself:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
claude mcp add --scope user mailmate "$(which mailmate-mcp)"
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Or add manually to `~/.claude.json` under `"mcpServers"`:
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
"mailmate": {
|
|
136
|
+
"type": "stdio",
|
|
137
|
+
"command": "/absolute/path/to/mailmate-mcp",
|
|
138
|
+
"args": [],
|
|
139
|
+
"env": {}
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
For Claude Desktop, use the same command path in `claude_desktop_config.json` as shown under the one-line installer. Restart Claude Desktop after any change to server code or config.
|
|
144
|
+
|
|
7
145
|
## Example usage
|
|
8
146
|
|
|
9
147
|
### `mmsearch` — find messages
|
|
@@ -12,11 +150,11 @@ Ruby toolkit for [MailMate](https://freron.com) on macOS — a smart-mailbox fil
|
|
|
12
150
|
# Default: today's mail, all mailboxes
|
|
13
151
|
mmsearch
|
|
14
152
|
|
|
15
|
-
# From "
|
|
16
|
-
mmsearch 'f
|
|
153
|
+
# From "Substack" in the last 7 days
|
|
154
|
+
mmsearch 'f substack d 7d'
|
|
17
155
|
|
|
18
|
-
# Subject contains "
|
|
19
|
-
mmsearch 's "
|
|
156
|
+
# Subject contains "invoice due", not the word "draft"
|
|
157
|
+
mmsearch 's "invoice due" !draft'
|
|
20
158
|
|
|
21
159
|
# Received in May 2026
|
|
22
160
|
mmsearch 'd 2026-05'
|
|
@@ -41,7 +179,7 @@ mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
|
|
|
41
179
|
| `T <tag>` | Tags / IMAP keywords (`K` is a synonym). |
|
|
42
180
|
| `!<value>` | Negate, e.g. `f !smith` = From does NOT contain smith. |
|
|
43
181
|
|
|
44
|
-
The `--mailbox` argument accepts an account, an `account/path`, a bare mailbox name matched across accounts, or a **smart-mailbox name** (e.g. `
|
|
182
|
+
The `--mailbox` argument accepts an account, an `account/path`, a bare mailbox name matched across accounts, or a **smart-mailbox name** (e.g. `Newsletters`, `Receipts`, `Priority`) whose filter is ANDed into the search.
|
|
45
183
|
|
|
46
184
|
**Output fields.** Default columns are `flags date time direction party subject`. Prefix a field list with `+` to add to the defaults; a bare list replaces them (`id` is always the first column).
|
|
47
185
|
|
|
@@ -276,6 +414,8 @@ A few rough edges to be aware of:
|
|
|
276
414
|
|
|
277
415
|
## Status
|
|
278
416
|
|
|
417
|
+
1.6.0 — Distribution release. The repo is now a Claude Code plugin marketplace (`/plugin marketplace add brianmd/mailmate`), and a one-line `install.sh` provisions the MCP server into an isolated `~/.mailmate-mcp` — including a private relocatable Ruby when no Ruby ≥ 3.0 is present — without touching system Ruby, Homebrew, or shell profiles. Every MCP tool now carries a `title` plus `readOnlyHint`/`destructiveHint` annotations (Claude clients use these for permission behavior; Anthropic's directory review requires them), and the README gains a formal Privacy Policy section. No changes to CLI or library behavior.
|
|
418
|
+
|
|
279
419
|
1.5.0 — Reliability and batch-verification for `mm-modify`, plus search/read speedups. `mm-modify` gains a no-window retry guard (a `mid:` open that spawns no viewer would otherwise act on the wrong message) and opt-in effect verification: `--check` confirms a flag/tag/read action landed on the target eml-id by re-reading `#flags` (the only way to catch a duplicate-Message-ID misland). Because MailMate flushes `#flags` to disk ~5 s after acting, a new **`mm-verify`** command plus `mm-modify --emit-check` decouple acting from confirming — collect JSON check-tickets across a batch and verify them all in one flush-wait instead of paying the latency per message. `mmsearch` is substantially faster (compiled date ranges, cheapest-spec-first ordering, bulk-unpack index reader, inverted body search) with bit-identical output; the persistent MCP server now invalidates index caches on disk change. `mmmessage` shows user tags and lazy-loads the `mail` gem (`--raw`/`--mailmate` skip it). MCP: `message` gains `markdown`, `modify` gains a `check` mode (`none｜inline｜defer`), and a new `verify` tool batch-confirms deferred tickets.
|
|
280
420
|
|
|
281
421
|
1.2.0 — `mm-modify` no longer brings MailMate to the foreground and is roughly 8× faster on single-action invocations. Internally: the open call uses `open -g -a MailMate <url>` to keep MailMate in the background, and the fixed `--settle` sleeps are replaced by active waits (polling for the spawned viewer window to appear). `mmopen` gains a `--background` / `-g` flag for ad-hoc use. `mm-modify --verify` now works in `--dry-run` mode as a post-hoc state probe. `--settle` is preserved for backward compat; it now caps the active-wait timeout rather than fixing sleep duration.
|
|
@@ -284,92 +424,6 @@ A few rough edges to be aware of:
|
|
|
284
424
|
|
|
285
425
|
1.0.0 — initial public release; API stable from this point. Breaking changes bump the major version going forward.
|
|
286
426
|
|
|
287
|
-
## Install
|
|
288
|
-
|
|
289
|
-
### Requirements
|
|
290
|
-
|
|
291
|
-
- **macOS** with **MailMate** installed (and running, for any command that drives the UI or sends mail).
|
|
292
|
-
- **Ruby ≥ 3.0**.
|
|
293
|
-
- No third-party CLI tools — the gem only shells out to macOS-bundled `plutil`, `osascript`, and `open`, plus MailMate's bundled `emate`.
|
|
294
|
-
|
|
295
|
-
```bash
|
|
296
|
-
gem install mailmate
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
Then optionally bootstrap your config (will happen automatically on first invocation of any command from an interactive shell if it hasn't been run before):
|
|
300
|
-
|
|
301
|
-
```bash
|
|
302
|
-
mmdiscover
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
`mmdiscover` reads MailMate's `Sources.plist` and `Identities.plist`, shows you the accounts and addresses it found, and offers to write `~/.config/mailmate/config.yml` from them. It also writes `~/.config/mailmate/bundle_loader.rb` for MailMate bundles. Running it explicitly is only needed in non-TTY contexts (cron jobs, MCP servers) — there, the gem falls back to built-in defaults and warns once.
|
|
306
|
-
|
|
307
|
-
### Optional: `mmmessage --markdown`
|
|
308
|
-
|
|
309
|
-
**On the vast majority of Ruby setups (stock `arm64-darwin` or `x86_64-darwin` Ruby) this step is a no-op — nokogiri ships a precompiled binary, you can skip the rest of this section and move on.** Keep reading only if your `gem install` actually fails.
|
|
310
|
-
|
|
311
|
-
`mmmessage --markdown` renders HTML-only message bodies as readable markdown. It needs the `reverse_markdown` gem, which has `nokogiri` as a transitive dependency:
|
|
312
|
-
|
|
313
|
-
```bash
|
|
314
|
-
gem install reverse_markdown
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
That single command pulls `nokogiri` in automatically — no separate `gem install nokogiri` step. This is kept out of the base install because nokogiri ships a native extension. On Ruby/platform combinations without a precompiled match nokogiri falls back to compiling from source — it vendors its own libxml2/libxslt, but it does need a C compiler, which on macOS means Xcode Command Line Tools (`xcode-select --install`). If `gem install reverse_markdown` fails, that's almost certainly the cause.
|
|
318
|
-
|
|
319
|
-
If you never use `--markdown`, you never pay any of this. If you do invoke `--markdown` without the gem installed, `mmmessage` warns with a clear install hint and falls back to the raw HTML body (it does not abort — so the in-process MCP server survives a missing optional dependency).
|
|
320
|
-
|
|
321
|
-
### From source (development)
|
|
322
|
-
|
|
323
|
-
If you're hacking on the gem itself, skip `gem install` and put the repo's `exe/` on your `PATH`. Clone wherever you keep source repos, then prepend its `exe/` to `PATH` from your shell's rc file (`~/.zshrc`, `~/.bashrc`, etc.):
|
|
324
|
-
|
|
325
|
-
```bash
|
|
326
|
-
git clone https://github.com/brianmd/mailmate.git
|
|
327
|
-
cd mailmate
|
|
328
|
-
|
|
329
|
-
# In your shell rc file, add (adjust the path to wherever you cloned):
|
|
330
|
-
# export PATH="/absolute/path/to/mailmate/exe:$PATH"
|
|
331
|
-
# Then reload the shell (open a new tab, or `source` the rc file).
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
Then `mmdiscover` as above.
|
|
335
|
-
|
|
336
|
-
### MCP server
|
|
337
|
-
|
|
338
|
-
The gem also ships an MCP server (`exe/mailmate-mcp`) that exposes the same surface to AI assistants as JSON-RPC tools: `search`, `message`, `modify`, `verify`, `send`, `draft`, `open`, `list_mailboxes`, `list_tags`, `resolve_id`. After `gem install mailmate`, `mailmate-mcp` is on your `PATH`.
|
|
339
|
-
|
|
340
|
-
#### Claude Code (global, all projects)
|
|
341
|
-
|
|
342
|
-
```bash
|
|
343
|
-
claude mcp add --scope user mailmate "$(which mailmate-mcp)"
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
Or add manually to `~/.claude.json` under `"mcpServers"`:
|
|
347
|
-
|
|
348
|
-
```json
|
|
349
|
-
"mailmate": {
|
|
350
|
-
"type": "stdio",
|
|
351
|
-
"command": "/absolute/path/to/mailmate-mcp",
|
|
352
|
-
"args": [],
|
|
353
|
-
"env": {}
|
|
354
|
-
}
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
#### Claude Desktop
|
|
358
|
-
|
|
359
|
-
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
360
|
-
|
|
361
|
-
```json
|
|
362
|
-
{
|
|
363
|
-
"mcpServers": {
|
|
364
|
-
"mailmate": {
|
|
365
|
-
"command": "/absolute/path/to/mailmate-mcp"
|
|
366
|
-
}
|
|
367
|
-
}
|
|
368
|
-
}
|
|
369
|
-
```
|
|
370
|
-
|
|
371
|
-
Restart Claude Desktop after any change to server code or config.
|
|
372
|
-
|
|
373
427
|
## Commands
|
|
374
428
|
|
|
375
429
|
| Command | What it does |
|
|
@@ -397,7 +451,7 @@ The CLI tools take an `eml-id` — the integer filename of MailMate's `.eml` sto
|
|
|
397
451
|
require "mailmate"
|
|
398
452
|
|
|
399
453
|
# Parse and evaluate a MailMate smart-mailbox filter
|
|
400
|
-
ast = Mailmate.compile_filter("from.name = '
|
|
454
|
+
ast = Mailmate.compile_filter("from.name = 'Substack' and #date-received > '1 days ago'")
|
|
401
455
|
# ... feed `ast` to Mailmate::Evaluator ...
|
|
402
456
|
|
|
403
457
|
# Read the binary `#flags` index
|
data/lib/mailmate/cli/search.rb
CHANGED
|
@@ -206,8 +206,8 @@ module Mailmate
|
|
|
206
206
|
o.separator " T <tag> tag / IMAP keyword contains (K is a synonym)"
|
|
207
207
|
o.separator ""
|
|
208
208
|
o.separator " Examples:"
|
|
209
|
-
o.separator " mmsearch 'f
|
|
210
|
-
o.separator " mmsearch 's \"
|
|
209
|
+
o.separator " mmsearch 'f substack d 7d' from Substack in last 7 days"
|
|
210
|
+
o.separator " mmsearch 's \"invoice due\" !draft' subject has invoice due, no 'draft'"
|
|
211
211
|
o.separator " mmsearch 'd 2026-05' received in May 2026"
|
|
212
212
|
o.separator ""
|
|
213
213
|
o.separator "FIELDS (for the fields argument / --fields)"
|
data/lib/mailmate/mcp.rb
CHANGED
|
@@ -74,25 +74,27 @@ module Mailmate
|
|
|
74
74
|
TOOLS = [
|
|
75
75
|
{
|
|
76
76
|
name: "search",
|
|
77
|
+
title: "Search mail",
|
|
78
|
+
annotations: { title: "Search mail", readOnlyHint: true },
|
|
77
79
|
description: <<~DESC.strip,
|
|
78
80
|
Search MailMate's .eml files using MailMate's quicksearch syntax.
|
|
79
81
|
Returns column-aligned CSV. Same engine as the `mmsearch` CLI.
|
|
80
82
|
|
|
81
83
|
Query = space-separated specs combined with AND (no or/parens yet).
|
|
82
|
-
Quote multi-word terms ("
|
|
84
|
+
Quote multi-word terms ("invoice due"). Modifiers:
|
|
83
85
|
(bare term) From/To/Cc/Subject OR body contains
|
|
84
86
|
f <t> From t <t> To/Cc c <t> Cc s <t> Subject
|
|
85
87
|
a <t> any address header b <t> body m <t> headers OR body
|
|
86
88
|
d <date> received: Y, Y-M, Y-M-D, or relative 1d/2w/3m/1y
|
|
87
89
|
T <tag> tag / IMAP keyword (K is a synonym)
|
|
88
90
|
!<value> negate, e.g. f !smith (From does NOT contain smith)
|
|
89
|
-
The `mailbox` arg also accepts a smart-mailbox name (e.g.
|
|
90
|
-
|
|
91
|
+
The `mailbox` arg also accepts a smart-mailbox name (e.g. Newsletters,
|
|
92
|
+
Receipts, Priority) whose filter is ANDed into the search.
|
|
91
93
|
|
|
92
94
|
Examples:
|
|
93
|
-
query="f
|
|
94
|
-
query="T
|
|
95
|
-
query="s '
|
|
95
|
+
query="f substack d 7d" from Substack in the last 7 days
|
|
96
|
+
query="T urgent" tagged "urgent"
|
|
97
|
+
query="s 'invoice due' !draft" subject has 'invoice due', not 'draft'
|
|
96
98
|
|
|
97
99
|
Fields default to: flags date time direction party subject.
|
|
98
100
|
Prefix with "+" to add to the defaults ("+tags +mailbox"); a bare
|
|
@@ -128,6 +130,8 @@ module Mailmate
|
|
|
128
130
|
},
|
|
129
131
|
{
|
|
130
132
|
name: "message",
|
|
133
|
+
title: "Read message",
|
|
134
|
+
annotations: { title: "Read message", readOnlyHint: true },
|
|
131
135
|
description: "Read one MailMate message. Accepts either local eml-id (digits) or RFC Message-ID (with or without angle brackets). Default output: headers block (incl. any user tags) + plain-text body. For HTML-only mail (most newsletters), pass markdown:true to get clean readable markdown instead of raw HTML — strongly preferred for reading and far more token-efficient; it's a no-op on plain-text messages.",
|
|
132
136
|
inputSchema: {
|
|
133
137
|
type: "object",
|
|
@@ -143,6 +147,8 @@ module Mailmate
|
|
|
143
147
|
},
|
|
144
148
|
{
|
|
145
149
|
name: "modify",
|
|
150
|
+
title: "Modify message state",
|
|
151
|
+
annotations: { title: "Modify message state", readOnlyHint: false, destructiveHint: true },
|
|
146
152
|
description: <<~DESC.strip,
|
|
147
153
|
Apply state-change actions to a message via MailMate.
|
|
148
154
|
NOTE: drives MailMate's UI via AppleScript — it briefly takes focus,
|
|
@@ -192,6 +198,8 @@ module Mailmate
|
|
|
192
198
|
},
|
|
193
199
|
{
|
|
194
200
|
name: "verify",
|
|
201
|
+
title: "Verify modify results",
|
|
202
|
+
annotations: { title: "Verify modify results", readOnlyHint: true },
|
|
195
203
|
description: <<~DESC.strip,
|
|
196
204
|
Batch-confirm `modify` check-tickets (from check:"defer") against the
|
|
197
205
|
#flags index in ONE flush-wait. Pass the tickets you collected from a
|
|
@@ -218,6 +226,8 @@ module Mailmate
|
|
|
218
226
|
},
|
|
219
227
|
{
|
|
220
228
|
name: "send",
|
|
229
|
+
title: "Send mail",
|
|
230
|
+
annotations: { title: "Send mail", readOnlyHint: false, destructiveHint: true },
|
|
221
231
|
description: "Send mail via MailMate's `emate` (markdown body). Recipients and subject via fields; body is the markdown source. For replies, set `in_reply_to` and `references` so recipients' clients thread the message — without them a `Re:` subject alone is not enough. MailMate generates the outgoing Message-ID automatically.",
|
|
222
232
|
inputSchema: {
|
|
223
233
|
type: "object",
|
|
@@ -239,6 +249,8 @@ module Mailmate
|
|
|
239
249
|
},
|
|
240
250
|
{
|
|
241
251
|
name: "draft",
|
|
252
|
+
title: "Compose draft",
|
|
253
|
+
annotations: { title: "Compose draft", readOnlyHint: false, destructiveHint: false },
|
|
242
254
|
description: "Compose a draft via MailMate's `emate` (markdown body) — IDENTICAL to `send` but it never sends: the draft opens in MailMate and waits. There is no `send_now` option; use this whenever the instruction is 'write/compose but don't send'. For replies, set `in_reply_to` and `references` so the draft threads correctly. MailMate generates the outgoing Message-ID automatically.",
|
|
243
255
|
inputSchema: {
|
|
244
256
|
type: "object",
|
|
@@ -259,6 +271,8 @@ module Mailmate
|
|
|
259
271
|
},
|
|
260
272
|
{
|
|
261
273
|
name: "open",
|
|
274
|
+
title: "Open in MailMate",
|
|
275
|
+
annotations: { title: "Open in MailMate", readOnlyHint: false, destructiveHint: false },
|
|
262
276
|
description: "Open one MailMate message in MailMate's UI (activates the window). Accepts any of the id forms `resolve_id` takes. Read-side semantically, but does shift focus to MailMate.",
|
|
263
277
|
inputSchema: {
|
|
264
278
|
type: "object",
|
|
@@ -272,6 +286,8 @@ module Mailmate
|
|
|
272
286
|
},
|
|
273
287
|
{
|
|
274
288
|
name: "list_mailboxes",
|
|
289
|
+
title: "List mailboxes",
|
|
290
|
+
annotations: { title: "List mailboxes", readOnlyHint: true },
|
|
275
291
|
description: "Enumerate accounts, IMAP mailboxes (with optional message counts), and smart mailboxes MailMate has defined. Account names are decoded for display (`%40` → `@`).",
|
|
276
292
|
inputSchema: {
|
|
277
293
|
type: "object",
|
|
@@ -284,6 +300,8 @@ module Mailmate
|
|
|
284
300
|
},
|
|
285
301
|
{
|
|
286
302
|
name: "list_tags",
|
|
303
|
+
title: "List tags",
|
|
304
|
+
annotations: { title: "List tags", readOnlyHint: true },
|
|
287
305
|
description: "List user tags. Default: tags actually applied to messages, with usage counts (from MailMate's #flags index; system flags excluded). `defined: true`: tags MailMate has registered in Preferences → Tags (from Tags.plist).",
|
|
288
306
|
inputSchema: {
|
|
289
307
|
type: "object",
|
|
@@ -295,6 +313,8 @@ module Mailmate
|
|
|
295
313
|
},
|
|
296
314
|
{
|
|
297
315
|
name: "resolve_id",
|
|
316
|
+
title: "Resolve message identifiers",
|
|
317
|
+
annotations: { title: "Resolve message identifiers", readOnlyHint: true },
|
|
298
318
|
description: <<~DESC.strip,
|
|
299
319
|
Look up a message and return all its identifiers:
|
|
300
320
|
- eml_id local body-part id (changes per machine)
|
data/lib/mailmate/version.rb
CHANGED