mailmate 1.3.0 → 1.4.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 +34 -0
- data/lib/mailmate/mcp.rb +63 -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: b2e41c1bf66c9a41c75d683f9e7edcfa2d6ac5982f6a54c2d3cc4b2cbb5c36a8
|
|
4
|
+
data.tar.gz: 378d1b75d3485de7cf5285e8b12f4fa0ebd7b144b9ebe4a5d4322f6a5d592726
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 710617dc65666c1eec32f4a6d1e7c4ac15c3aab6ce295548d59edaefacd86863ed2b716246bceb250dd9f7f67c4e3a54701366a3c4c65a6b69321b6df3024587
|
|
7
|
+
data.tar.gz: a54ee5f4a6cf7ff02c35f6239ab63e805404db1610fa470358ac382bf4870b1fb8176a0990e5a01a24195275e6c603fe44b2d124b9c6829765f222872f874a10
|
data/README.md
CHANGED
|
@@ -25,6 +25,40 @@ mmsearch 'd 2026-05'
|
|
|
25
25
|
mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
+
**Quicksearch syntax.** The search-string is a list of specs combined with **AND** (`or`/parens not yet supported). Wrap multi-word terms in `"double quotes"`.
|
|
29
|
+
|
|
30
|
+
| Modifier | Scope |
|
|
31
|
+
|---|---|
|
|
32
|
+
| _bare term_ | From/To/Cc/Subject **or body** contains (the UI quicksearch default). `--headers-only` skips the body scan. |
|
|
33
|
+
| `f <term>` | From contains. |
|
|
34
|
+
| `t <term>` | To/Cc (recipients) contains. |
|
|
35
|
+
| `c <term>` | Cc contains. |
|
|
36
|
+
| `s <term>` | Subject contains. |
|
|
37
|
+
| `a <term>` | Any address header contains. |
|
|
38
|
+
| `b <term>` | Body (plain text) contains. |
|
|
39
|
+
| `m <term>` | Common headers OR body. |
|
|
40
|
+
| `d <date>` | Received date: `Y`, `Y-M`, `Y-M-D`, or relative `1d`/`2w`/`3m`/`1y`. |
|
|
41
|
+
| `T <tag>` | Tags / IMAP keywords (`K` is a synonym). |
|
|
42
|
+
| `!<value>` | Negate, e.g. `f !smith` = From does NOT contain smith. |
|
|
43
|
+
|
|
44
|
+
The `--mailbox` argument accepts an account, an `account/path`, a bare mailbox name matched across accounts, or a **smart-mailbox name** (e.g. `Medium`, `Whisper`, `Personal Inbox`) whose filter is ANDed into the search.
|
|
45
|
+
|
|
46
|
+
**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
|
+
|
|
48
|
+
| Field | What it shows |
|
|
49
|
+
|---|---|
|
|
50
|
+
| `id` | The `.eml` body-part ID (always emitted first). |
|
|
51
|
+
| `path` | Absolute file path. |
|
|
52
|
+
| `mailbox` | `<account>/<mailbox>` relative to the IMAP root. |
|
|
53
|
+
| `from`, `to`, `cc`, `bcc`, `reply-to` | Address headers (joined with `; `). |
|
|
54
|
+
| `subject` | Decoded subject. |
|
|
55
|
+
| `date` / `time` | `YYYY-MM-DD` / `HH:MM` (sender's timezone). |
|
|
56
|
+
| `message-id` | The `Message-ID` header. |
|
|
57
|
+
| `direction` | `→` outbound, `←` inbound (rendered as `dir`). |
|
|
58
|
+
| `party` | The other party — recipient(s) if outbound, sender if inbound. |
|
|
59
|
+
| `flags` | Two chars: position 1 archive-state (`A` archived / `P` primary), position 2 read-state (`R` read / `U` unread) — e.g. `AR`, `PU`. |
|
|
60
|
+
| `read` / `archive` | Standalone versions of the two `flags` positions. |
|
|
61
|
+
|
|
28
62
|
### `mmmessage` — read one message
|
|
29
63
|
|
|
30
64
|
```bash
|
data/lib/mailmate/mcp.rb
CHANGED
|
@@ -30,6 +30,46 @@ module Mailmate
|
|
|
30
30
|
PROTOCOL_VERSION = "2024-11-05"
|
|
31
31
|
SERVER_NAME = "mailmate"
|
|
32
32
|
|
|
33
|
+
# Server-level guidance returned from `initialize`. This is the gem's
|
|
34
|
+
# operational doctrine — the things a caller must know to drive MailMate
|
|
35
|
+
# correctly that don't fit in a single tool's description. It travels with
|
|
36
|
+
# the gem so the MCP is self-sufficient (no companion skill required).
|
|
37
|
+
INSTRUCTIONS = <<~INSTRUCTIONS.strip
|
|
38
|
+
Read and act on MailMate's local mail store on macOS. `search`, `message`,
|
|
39
|
+
`resolve_id`, and `list_*` are read-only; `send`, `draft`, `modify`, and
|
|
40
|
+
`open` require MailMate to be running (they drive the app).
|
|
41
|
+
|
|
42
|
+
Composing (send / draft)
|
|
43
|
+
- Bodies are Markdown; MailMate renders them to HTML on the way out. For
|
|
44
|
+
that to reach recipients, MailMate → Preferences → Composer must have
|
|
45
|
+
"Preview: Display" = Always and "Replying/Forwarding HTML" = Always
|
|
46
|
+
embed — otherwise recipients get plain text. These are global, one-time
|
|
47
|
+
settings.
|
|
48
|
+
- Set `from` explicitly. When the To: address matches one of the user's
|
|
49
|
+
own accounts, MailMate may otherwise send from that account.
|
|
50
|
+
- Prefer `draft` over `send` whenever the user said "don't send" / "just
|
|
51
|
+
draft it" — `draft` physically cannot send, so it's the safe choice.
|
|
52
|
+
`send` also opens a draft and waits unless you pass `send_now: true`.
|
|
53
|
+
- Threading: set BOTH `in_reply_to` and `references`. A "Re:" subject
|
|
54
|
+
alone does not thread in modern clients. MailMate generates the
|
|
55
|
+
outgoing Message-ID itself.
|
|
56
|
+
|
|
57
|
+
Modifying (modify)
|
|
58
|
+
- Drives MailMate's UI via AppleScript: it briefly takes focus, calls are
|
|
59
|
+
serial per app, and each call costs a few seconds (flag/tag writes are
|
|
60
|
+
async). Batch multiple actions into ONE call rather than many.
|
|
61
|
+
- Opening a message marks it \\Seen; read state is auto-preserved unless
|
|
62
|
+
your action chain itself includes read/unread.
|
|
63
|
+
- A Message-ID can live in several mailboxes (Sent + Received copies,
|
|
64
|
+
Gmail label copies). When it does, the action may land on a different
|
|
65
|
+
copy than the id you targeted.
|
|
66
|
+
|
|
67
|
+
Identifiers
|
|
68
|
+
- Tools accept a local eml-id (an integer; per-machine, NOT portable) or
|
|
69
|
+
an RFC Message-ID (portable across machines). Use `resolve_id` to
|
|
70
|
+
convert between them and to mint a cross-machine message:// URL.
|
|
71
|
+
INSTRUCTIONS
|
|
72
|
+
|
|
33
73
|
TOOLS = [
|
|
34
74
|
{
|
|
35
75
|
name: "search",
|
|
@@ -37,15 +77,31 @@ module Mailmate
|
|
|
37
77
|
Search MailMate's .eml files using MailMate's quicksearch syntax.
|
|
38
78
|
Returns column-aligned CSV. Same engine as the `mmsearch` CLI.
|
|
39
79
|
|
|
40
|
-
|
|
80
|
+
Query = space-separated specs combined with AND (no or/parens yet).
|
|
81
|
+
Quote multi-word terms ("rent due"). Modifiers:
|
|
82
|
+
(bare term) From/To/Cc/Subject OR body contains
|
|
83
|
+
f <t> From t <t> To/Cc c <t> Cc s <t> Subject
|
|
84
|
+
a <t> any address header b <t> body m <t> headers OR body
|
|
85
|
+
d <date> received: Y, Y-M, Y-M-D, or relative 1d/2w/3m/1y
|
|
86
|
+
T <tag> tag / IMAP keyword (K is a synonym)
|
|
87
|
+
!<value> negate, e.g. f !smith (From does NOT contain smith)
|
|
88
|
+
The `mailbox` arg also accepts a smart-mailbox name (e.g. Medium,
|
|
89
|
+
Whisper, Personal Inbox) whose filter is ANDed into the search.
|
|
90
|
+
|
|
91
|
+
Examples:
|
|
41
92
|
query="f medium d 7d" from Medium in the last 7 days
|
|
42
|
-
query="T robot" tagged "robot"
|
|
93
|
+
query="T robot" tagged "robot"
|
|
43
94
|
query="s 'rent due' !draft" subject has 'rent due', not 'draft'
|
|
44
|
-
query="d 2026-05" received in May 2026
|
|
45
95
|
|
|
46
|
-
Fields default to: flags date time direction party subject
|
|
47
|
-
Prefix
|
|
48
|
-
|
|
96
|
+
Fields default to: flags date time direction party subject.
|
|
97
|
+
Prefix with "+" to add to the defaults ("+tags +mailbox"); a bare
|
|
98
|
+
list replaces them (id is always the first column). Meanings:
|
|
99
|
+
flags 2 chars — archive-state (A archived / P primary) then
|
|
100
|
+
read-state (R read / U unread), e.g. AR, PU
|
|
101
|
+
direction → outbound / ← inbound party the other party
|
|
102
|
+
read R/U archive A/P (standalone flag columns)
|
|
103
|
+
Other fields (from/to/cc/bcc/reply-to/subject/date/time/message-id/
|
|
104
|
+
path/mailbox) are the obvious header or location values.
|
|
49
105
|
DESC
|
|
50
106
|
inputSchema: {
|
|
51
107
|
type: "object",
|
|
@@ -247,6 +303,7 @@ module Mailmate
|
|
|
247
303
|
protocolVersion: PROTOCOL_VERSION,
|
|
248
304
|
capabilities: { tools: {} },
|
|
249
305
|
serverInfo: { name: SERVER_NAME, version: Mailmate::VERSION },
|
|
306
|
+
instructions: INSTRUCTIONS,
|
|
250
307
|
}))
|
|
251
308
|
when "notifications/initialized", "notifications/cancelled"
|
|
252
309
|
# notifications — no response
|
data/lib/mailmate/version.rb
CHANGED