@mgcrea/mcp-apple-reminders 0.0.0-bootstrap
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 +63 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +28 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +638 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2 -0
- package/dist/server-pj2yDDQb.js +2027 -0
- package/dist/server-pj2yDDQb.js.map +1 -0
- package/package.json +68 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,638 @@
|
|
|
1
|
+
import { AppBusyError as RemindersBusyError, AppNotRunningError as RemindersNotRunningError, AppleAutomationError, AppleAutomationError as AppleRemindersError, BuildInfo, Logger, OsascriptRunner, ReadOnlyMode, StoreFacts, SurfaceContext } from "@mgcrea/mcp-apple-core";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
4
|
+
import { DatabaseSync } from "node:sqlite";
|
|
5
|
+
//#region src/build-info.d.ts
|
|
6
|
+
declare const BUILD_INFO: BuildInfo;
|
|
7
|
+
//#endregion
|
|
8
|
+
//#region src/client/dates.d.ts
|
|
9
|
+
/**
|
|
10
|
+
* Date parsing for the Reminders tools.
|
|
11
|
+
*
|
|
12
|
+
* ## Why this module exists at all
|
|
13
|
+
*
|
|
14
|
+
* The scripting dictionary carries two separate due-date properties:
|
|
15
|
+
*
|
|
16
|
+
* due date "will set both date and time"
|
|
17
|
+
* allday due date "will only set a date"
|
|
18
|
+
*
|
|
19
|
+
* So the *shape of the input* has to pick the property. A caller that writes
|
|
20
|
+
* "2026-08-20" means a day; one that writes "2026-08-20T09:00" means an instant.
|
|
21
|
+
* Collapsing those into one field is how a reminder ends up silently due at
|
|
22
|
+
* midnight, which Reminders then renders as an all-day item anyway — the bug is
|
|
23
|
+
* invisible until someone misses something.
|
|
24
|
+
*
|
|
25
|
+
* ## The rule
|
|
26
|
+
*
|
|
27
|
+
* | Input names a… | Examples | Result |
|
|
28
|
+
* | ------------------- | ------------------------------------- | -------- |
|
|
29
|
+
* | day | `2026-08-20`, `today`, `next monday` | all-day |
|
|
30
|
+
* | instant | `2026-08-20T09:00`, `+3h`, `+2d` | timed |
|
|
31
|
+
* | day *and* a time | `tomorrow 09:00` | timed |
|
|
32
|
+
*
|
|
33
|
+
* `+2d` is timed rather than all-day on purpose: it names a duration from now,
|
|
34
|
+
* and the natural reading of "in two days" keeps the current time of day.
|
|
35
|
+
*
|
|
36
|
+
* ## Time zone
|
|
37
|
+
*
|
|
38
|
+
* Everything without an explicit offset resolves in **system local time**.
|
|
39
|
+
* Reminders is a local-calendar app: a reminder due "09:00" is due at nine
|
|
40
|
+
* o'clock where the person is, not at nine UTC. An input that *does* carry an
|
|
41
|
+
* offset (`…T09:00Z`, `…T09:00+02:00`) is honoured as the absolute instant it
|
|
42
|
+
* names.
|
|
43
|
+
*
|
|
44
|
+
* ## DST
|
|
45
|
+
*
|
|
46
|
+
* Day and week offsets are **calendar** arithmetic (`setDate`), so `+2d` across
|
|
47
|
+
* a clock change lands at the same wall-clock time — which is what "in two
|
|
48
|
+
* days" means to a person. Hour and minute offsets are **absolute** durations,
|
|
49
|
+
* so `+3h` is always three hours of elapsed time. That split is deliberate and
|
|
50
|
+
* pinned by tests; getting it backwards makes reminders drift by an hour twice
|
|
51
|
+
* a year.
|
|
52
|
+
*
|
|
53
|
+
* ## Testability
|
|
54
|
+
*
|
|
55
|
+
* `now` is an injected parameter with a `new Date()` default, mirroring how
|
|
56
|
+
* `loadConfig(env)` takes its environment — so tests are hermetic rather than
|
|
57
|
+
* having to freeze a global clock.
|
|
58
|
+
*/
|
|
59
|
+
/** What a parsed date turned out to be, which selects the Reminders property. */
|
|
60
|
+
type DueKind = "allDay" | "timed";
|
|
61
|
+
type ParsedDate = {
|
|
62
|
+
kind: DueKind;
|
|
63
|
+
/** The absolute instant, for comparisons and for handing to JXA. */
|
|
64
|
+
at: Date;
|
|
65
|
+
/**
|
|
66
|
+
* ISO-8601 **with an explicit offset**, e.g. `2026-08-20T09:00:00+02:00`.
|
|
67
|
+
*
|
|
68
|
+
* Always carries the offset so the value is unambiguous once it leaves this
|
|
69
|
+
* process — a bare local string reinterpreted in another zone is exactly the
|
|
70
|
+
* silent failure this module exists to prevent.
|
|
71
|
+
*/
|
|
72
|
+
iso: string;
|
|
73
|
+
/** Echoed back in tool results so a caller can see how its input was read. */
|
|
74
|
+
raw: string;
|
|
75
|
+
};
|
|
76
|
+
/**
|
|
77
|
+
* Local wall-clock time rendered with its offset.
|
|
78
|
+
*
|
|
79
|
+
* Deliberately not `toISOString()`, which converts to UTC and would report a
|
|
80
|
+
* 09:00 reminder as `07:00Z` — correct as an instant, but unreadable in a tool
|
|
81
|
+
* result where the whole point is confirming what the caller asked for.
|
|
82
|
+
*/
|
|
83
|
+
declare const toLocalIso: (d: Date) => string;
|
|
84
|
+
/**
|
|
85
|
+
* Parse one date argument.
|
|
86
|
+
*
|
|
87
|
+
* @param field Named in the error, so a failure says *which* argument was bad.
|
|
88
|
+
* @param raw The caller's string.
|
|
89
|
+
* @param now Injected for hermetic tests.
|
|
90
|
+
*/
|
|
91
|
+
declare const parseDate: (field: string, raw: string, now?: Date) => ParsedDate;
|
|
92
|
+
/**
|
|
93
|
+
* Parse a bound for a range filter (`dueBefore` / `dueAfter`).
|
|
94
|
+
*
|
|
95
|
+
* A bare day means the whole day, so the edge it resolves to depends on which
|
|
96
|
+
* side of the range it is: `dueBefore: "2026-08-20"` includes everything up to
|
|
97
|
+
* that evening, and `dueAfter: "2026-08-20"` includes everything from that
|
|
98
|
+
* morning. Resolving both to midnight would make `dueBefore` quietly exclude
|
|
99
|
+
* the day the caller named.
|
|
100
|
+
*/
|
|
101
|
+
declare const parseBound: (field: string, raw: string, edge: "start" | "end", now?: Date) => Date;
|
|
102
|
+
//#endregion
|
|
103
|
+
//#region src/client/errors.d.ts
|
|
104
|
+
/** Named in every user-facing error and in the env vars they mention. */
|
|
105
|
+
declare const REMINDERS_SURFACE: SurfaceContext;
|
|
106
|
+
/** A ReminderRef no longer resolves — completed-and-cleared, deleted, or stale. */
|
|
107
|
+
declare class ReminderNotFoundError extends AppleAutomationError {
|
|
108
|
+
readonly name = "ReminderNotFoundError";
|
|
109
|
+
constructor(ref: string);
|
|
110
|
+
}
|
|
111
|
+
/** A list was named that Reminders does not have. */
|
|
112
|
+
declare class ListNotFoundError extends AppleAutomationError {
|
|
113
|
+
readonly name = "ListNotFoundError";
|
|
114
|
+
constructor(name: string, available?: readonly string[]);
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* A date argument could not be understood.
|
|
118
|
+
*
|
|
119
|
+
* Carries the accepted grammar rather than just rejecting, because the caller is
|
|
120
|
+
* usually a model that will retry once and needs to know what shape to retry in.
|
|
121
|
+
*/
|
|
122
|
+
declare class InvalidDateError extends AppleAutomationError {
|
|
123
|
+
readonly name = "InvalidDateError";
|
|
124
|
+
constructor(field: string, raw: string, reason: string);
|
|
125
|
+
}
|
|
126
|
+
//#endregion
|
|
127
|
+
//#region src/client/locate.d.ts
|
|
128
|
+
/**
|
|
129
|
+
* Find Reminders' store.
|
|
130
|
+
*
|
|
131
|
+
* ## Why this is harder than Notes'
|
|
132
|
+
*
|
|
133
|
+
* Notes has one constant path, so its locator can `statSync` a known file and
|
|
134
|
+
* learn "exists but unreadable" — the signature of a TCC denial — without any
|
|
135
|
+
* permission at all. Reminders keeps its database under a **generated
|
|
136
|
+
* directory name**:
|
|
137
|
+
*
|
|
138
|
+
* ~/Library/Group Containers/group.com.apple.reminders/Container_v1/Stores/Data-<UUID>.sqlite
|
|
139
|
+
*
|
|
140
|
+
* Resolving that means *listing* a protected directory, which is itself the
|
|
141
|
+
* privileged operation. So without Full Disk Access there is not even a path to
|
|
142
|
+
* stat, and this returns `storePath: null` with a reason rather than reporting a
|
|
143
|
+
* file that does not exist. Those are different failures and lead to different
|
|
144
|
+
* fixes.
|
|
145
|
+
*
|
|
146
|
+
* ## Why it globs rather than hardcoding `Container_v1/Stores`
|
|
147
|
+
*
|
|
148
|
+
* That subpath is the observed layout, not a documented one, and Apple has
|
|
149
|
+
* moved this data before — `~/Library/Reminders/Container_v1/Stores` on older
|
|
150
|
+
* releases, and `~/Library/Calendars` in the EventKit era. A bounded walk for
|
|
151
|
+
* `*.sqlite` survives a reshuffle; a hardcoded path turns one into a total
|
|
152
|
+
* outage. The known layout is still *preferred* when present, so the common
|
|
153
|
+
* case costs one readdir.
|
|
154
|
+
*/
|
|
155
|
+
/** `group.com.apple.reminders`, under `~/Library/Group Containers`. */
|
|
156
|
+
declare const GROUP_CONTAINER = "group.com.apple.reminders";
|
|
157
|
+
type StoreCandidate = StoreFacts & {
|
|
158
|
+
path: string;
|
|
159
|
+
};
|
|
160
|
+
type LocateResult = StoreFacts & {
|
|
161
|
+
containerPath: string;
|
|
162
|
+
/** Null when discovery could not run — see `reason`. */
|
|
163
|
+
storePath: string | null;
|
|
164
|
+
/** Every `.sqlite` found, largest first. More than one is normal. */
|
|
165
|
+
candidates: StoreCandidate[];
|
|
166
|
+
/** Whether the container could be listed at all. The FDA signal for this surface. */
|
|
167
|
+
containerListable: boolean;
|
|
168
|
+
reason: string | null;
|
|
169
|
+
};
|
|
170
|
+
declare const defaultContainerPath: (home?: string) => string;
|
|
171
|
+
declare const locateStore: (opts?: {
|
|
172
|
+
storePath?: string | undefined;
|
|
173
|
+
home?: string;
|
|
174
|
+
}) => LocateResult;
|
|
175
|
+
//#endregion
|
|
176
|
+
//#region src/client/priority.d.ts
|
|
177
|
+
/**
|
|
178
|
+
* Reminder priority, which is a range on the wire and a set of buttons in the UI.
|
|
179
|
+
*
|
|
180
|
+
* The scripting dictionary documents the encoding exactly:
|
|
181
|
+
*
|
|
182
|
+
* priority — 0: no priority, 1–4: high, 5: medium, 6–9: low
|
|
183
|
+
*
|
|
184
|
+
* Two things follow, and naive implementations get both wrong.
|
|
185
|
+
*
|
|
186
|
+
* **Reading is a bucket, not a lookup.** The range exists because Reminders
|
|
187
|
+
* shares this field with CalDAV, where any 1–9 is legal. A reminder synced from
|
|
188
|
+
* another client can arrive as priority 3, and a `switch` over {0,1,5,9} would
|
|
189
|
+
* report it as unknown — or, worse, fall through to "none" and show an urgent
|
|
190
|
+
* item as unflagged.
|
|
191
|
+
*
|
|
192
|
+
* **Writing is a choice of representative.** The UI offers four buttons, so
|
|
193
|
+
* each bucket needs one canonical value. These match what Reminders itself
|
|
194
|
+
* writes, which keeps a round trip through this server from silently rewriting
|
|
195
|
+
* a value the app would have left alone.
|
|
196
|
+
*
|
|
197
|
+
* Note the inversion: a *lower* number is a *higher* priority. Sorting by the
|
|
198
|
+
* raw field ascending puts "none" (0) first, ahead of high (1) — so ordering by
|
|
199
|
+
* urgency needs `rank`, not the raw value.
|
|
200
|
+
*/
|
|
201
|
+
/** What the tools accept and return. */
|
|
202
|
+
type PriorityName = "none" | "low" | "medium" | "high";
|
|
203
|
+
declare const PRIORITY_NAMES: readonly PriorityName[];
|
|
204
|
+
/** Name → wire value, for writes. */
|
|
205
|
+
declare const toPriorityValue: (name: PriorityName) => number;
|
|
206
|
+
/**
|
|
207
|
+
* Wire value → name, for reads. Buckets the whole legal range, so a value
|
|
208
|
+
* written by another CalDAV client is still classified rather than dropped.
|
|
209
|
+
*/
|
|
210
|
+
declare const toPriorityName: (value: number | null | undefined) => PriorityName;
|
|
211
|
+
/**
|
|
212
|
+
* Sort key, ascending = most urgent first, with "none" last.
|
|
213
|
+
*
|
|
214
|
+
* The raw field cannot be used for this: 0 means "no priority" but sorts ahead
|
|
215
|
+
* of 1, which means "high".
|
|
216
|
+
*/
|
|
217
|
+
declare const rank: (value: number | null | undefined) => number;
|
|
218
|
+
//#endregion
|
|
219
|
+
//#region src/client/ref.d.ts
|
|
220
|
+
/**
|
|
221
|
+
* ReminderRef — the one identifier any tool accepts or returns.
|
|
222
|
+
*
|
|
223
|
+
* Wire format: r1:<reminders-id>
|
|
224
|
+
*
|
|
225
|
+
* The `r1:` prefix follows the same reasoning as Notes' `n1:`: if the id scheme
|
|
226
|
+
* ever changes, a versioned prefix makes that an additive change instead of a
|
|
227
|
+
* silent reinterpretation of every ref already sitting in a conversation.
|
|
228
|
+
*
|
|
229
|
+
* Deliberately NOT shared with Notes' or Mail's codec. Mail's assumes an integer
|
|
230
|
+
* id; Notes' hardcodes `ICNote/p<N>` and returns a numeric `primaryKey`.
|
|
231
|
+
* Reminders' `id` is declared `type="text"` in the scripting dictionary and is
|
|
232
|
+
* opaque — so this codec validates the envelope and refuses to invent structure
|
|
233
|
+
* inside it.
|
|
234
|
+
*
|
|
235
|
+
* ## Why this is tolerant about the id's shape
|
|
236
|
+
*
|
|
237
|
+
* Apple Events ids are observed as `x-apple-reminder://<uuid>`, but that is a
|
|
238
|
+
* shape this server *observes*, not one Apple documents. Rejecting anything
|
|
239
|
+
* else would turn a harmless format change into total failure, and a reminder
|
|
240
|
+
* synced from a CalDAV account is exactly the case most likely to differ. So an
|
|
241
|
+
* id is carried through verbatim, and the UUID is extracted opportunistically —
|
|
242
|
+
* it is what joins a row in the store to a reminder in the app, and when it is
|
|
243
|
+
* absent the index lane simply cannot enrich that one result.
|
|
244
|
+
*/
|
|
245
|
+
declare const REF_VERSION = "r1";
|
|
246
|
+
type ReminderRef = {
|
|
247
|
+
/** The full id, exactly as Apple Events issued it. This is what resolves. */
|
|
248
|
+
id: string;
|
|
249
|
+
/**
|
|
250
|
+
* The bridge to the store, when the id carries one.
|
|
251
|
+
*
|
|
252
|
+
* Null is a legitimate value, not an error: it means this reminder can still
|
|
253
|
+
* be read and written over Apple Events, and only the index-only fields
|
|
254
|
+
* (tags, url, recurrence, alarms) are unavailable for it.
|
|
255
|
+
*/
|
|
256
|
+
uuid: string | null;
|
|
257
|
+
};
|
|
258
|
+
declare const encodeRef: (id: string) => string;
|
|
259
|
+
declare const decodeRef: (raw: string) => ReminderRef;
|
|
260
|
+
/**
|
|
261
|
+
* Build a ref from an index row, which only ever knows the bare UUID.
|
|
262
|
+
*
|
|
263
|
+
* The scheme is measured, not assumed: the probe read a real id from Apple
|
|
264
|
+
* Events and found `x-apple-reminder://<uuid>`, then located the same UUID in
|
|
265
|
+
* `ZREMCDREMINDER.ZCKIDENTIFIER`. That round trip is what makes reconstructing
|
|
266
|
+
* an id from the store defensible.
|
|
267
|
+
*/
|
|
268
|
+
declare const refFromUuid: (uuid: string) => string;
|
|
269
|
+
/** The store keeps bare identifiers; normalise for comparison against a ref. */
|
|
270
|
+
declare const uuidOf: (id: string) => string | null;
|
|
271
|
+
//#endregion
|
|
272
|
+
//#region src/config.d.ts
|
|
273
|
+
/**
|
|
274
|
+
* Configuration is environment-only — this server holds no secret at all, its
|
|
275
|
+
* access is the macOS permission the user granted.
|
|
276
|
+
*
|
|
277
|
+
* `allowWrites`, `debug`, `osascriptPath`, `osascriptTimeoutMs` and `maxResults`
|
|
278
|
+
* come from `BaseConfigSchema`.
|
|
279
|
+
*/
|
|
280
|
+
declare const ConfigSchema: z.ZodObject<{
|
|
281
|
+
allowWrites: z.ZodDefault<z.ZodBoolean>;
|
|
282
|
+
debug: z.ZodDefault<z.ZodBoolean>;
|
|
283
|
+
osascriptPath: z.ZodDefault<z.ZodString>;
|
|
284
|
+
osascriptTimeoutMs: z.ZodDefault<z.ZodNumber>;
|
|
285
|
+
maxResults: z.ZodDefault<z.ZodNumber>;
|
|
286
|
+
accounts: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
287
|
+
lists: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
288
|
+
storePath: z.ZodOptional<z.ZodString>;
|
|
289
|
+
indexMode: z.ZodDefault<z.ZodEnum<{
|
|
290
|
+
auto: "auto";
|
|
291
|
+
immutable: "immutable";
|
|
292
|
+
off: "off";
|
|
293
|
+
ro: "ro";
|
|
294
|
+
}>>;
|
|
295
|
+
defaultList: z.ZodOptional<z.ZodString>;
|
|
296
|
+
includeCompleted: z.ZodDefault<z.ZodBoolean>;
|
|
297
|
+
degradedMaxReminders: z.ZodDefault<z.ZodNumber>;
|
|
298
|
+
attachmentDir: z.ZodDefault<z.ZodString>;
|
|
299
|
+
searchCacheTtlMs: z.ZodDefault<z.ZodNumber>;
|
|
300
|
+
}, z.core.$strict>;
|
|
301
|
+
type Config = z.infer<typeof ConfigSchema>;
|
|
302
|
+
/**
|
|
303
|
+
* `env` is a parameter with a default so tests are hermetic — they pass their
|
|
304
|
+
* own object rather than mutating (and having to restore) process.env.
|
|
305
|
+
*/
|
|
306
|
+
declare const loadConfig: (env?: NodeJS.ProcessEnv) => Config;
|
|
307
|
+
//#endregion
|
|
308
|
+
//#region src/client/store.d.ts
|
|
309
|
+
type StoreCapabilities = {
|
|
310
|
+
fingerprint: string;
|
|
311
|
+
/** Present columns, so an Apple rename degrades one field instead of the lane. */
|
|
312
|
+
reminderColumns: Set<string>;
|
|
313
|
+
listColumns: Set<string>;
|
|
314
|
+
hasAttachments: boolean;
|
|
315
|
+
hasObjects: boolean;
|
|
316
|
+
epochOffset: number;
|
|
317
|
+
};
|
|
318
|
+
type IndexReminder = {
|
|
319
|
+
primaryKey: number;
|
|
320
|
+
/** The bridge to an Apple Events id. Null rows cannot be joined to the app. */
|
|
321
|
+
uuid: string | null;
|
|
322
|
+
title: string | null;
|
|
323
|
+
notes: string | null;
|
|
324
|
+
completed: boolean;
|
|
325
|
+
/** The one thing Apple Events genuinely cannot tell you. */
|
|
326
|
+
allDay: boolean;
|
|
327
|
+
due: string | null;
|
|
328
|
+
completionDate: string | null;
|
|
329
|
+
created: string | null;
|
|
330
|
+
modified: string | null;
|
|
331
|
+
priority: number | null;
|
|
332
|
+
flagged: boolean;
|
|
333
|
+
listPk: number | null;
|
|
334
|
+
listName: string | null;
|
|
335
|
+
parentPk: number | null;
|
|
336
|
+
parentUuid: string | null;
|
|
337
|
+
};
|
|
338
|
+
type IndexList = {
|
|
339
|
+
primaryKey: number;
|
|
340
|
+
uuid: string | null;
|
|
341
|
+
name: string | null;
|
|
342
|
+
isGroup: boolean;
|
|
343
|
+
parentListPk: number | null;
|
|
344
|
+
smartListType: string | null;
|
|
345
|
+
};
|
|
346
|
+
type IndexAttachment = {
|
|
347
|
+
primaryKey: number;
|
|
348
|
+
uuid: string | null;
|
|
349
|
+
reminderPk: number | null;
|
|
350
|
+
filename: string | null;
|
|
351
|
+
uti: string | null;
|
|
352
|
+
sha512: string | null;
|
|
353
|
+
};
|
|
354
|
+
/** Enrichment the scripting dictionary has no class for at all. */
|
|
355
|
+
type IndexEnrichment = {
|
|
356
|
+
alarmCount: number;
|
|
357
|
+
hasRecurrence: boolean;
|
|
358
|
+
location: {
|
|
359
|
+
latitude: number;
|
|
360
|
+
longitude: number;
|
|
361
|
+
proximity: number | null;
|
|
362
|
+
} | null;
|
|
363
|
+
};
|
|
364
|
+
type ReminderQuery = {
|
|
365
|
+
query?: string | undefined;
|
|
366
|
+
scope?: "title" | "full" | undefined;
|
|
367
|
+
listPk?: number | undefined;
|
|
368
|
+
includeCompleted?: boolean | undefined;
|
|
369
|
+
limit: number;
|
|
370
|
+
offset?: number | undefined;
|
|
371
|
+
};
|
|
372
|
+
declare class ReminderStore {
|
|
373
|
+
#private;
|
|
374
|
+
readonly db: DatabaseSync;
|
|
375
|
+
readonly mode: string;
|
|
376
|
+
readonly caps: StoreCapabilities;
|
|
377
|
+
constructor(db: DatabaseSync, mode: string, caps: StoreCapabilities);
|
|
378
|
+
search(q: ReminderQuery): IndexReminder[];
|
|
379
|
+
byUuid(uuid: string): IndexReminder | null;
|
|
380
|
+
/**
|
|
381
|
+
* Subtasks, which Apple Events cannot reach at all — `container()` throws on
|
|
382
|
+
* every reminder, so this column is the only way to know a reminder has a
|
|
383
|
+
* parent.
|
|
384
|
+
*/
|
|
385
|
+
subtasksOf(parentPk: number): IndexReminder[];
|
|
386
|
+
lists(): IndexList[];
|
|
387
|
+
attachmentsOf(reminderPk: number): IndexAttachment[];
|
|
388
|
+
/**
|
|
389
|
+
* Alarms, recurrence and location for one reminder.
|
|
390
|
+
*
|
|
391
|
+
* `ZREMCDOBJECT` is polymorphic — alarm rows and recurrence rows share it and
|
|
392
|
+
* are told apart by which columns are populated, not by a type column we can
|
|
393
|
+
* rely on. So this reports presence and counts rather than pretending to
|
|
394
|
+
* reconstruct an RFC 5545 rule from columns nobody has documented.
|
|
395
|
+
*/
|
|
396
|
+
enrichmentOf(reminderPk: number): IndexEnrichment;
|
|
397
|
+
}
|
|
398
|
+
/** Read the store's shape once, so every query can degrade per column. */
|
|
399
|
+
declare const introspect: (db: DatabaseSync) => StoreCapabilities;
|
|
400
|
+
declare const openStore: (path: string | null, mode: ReadOnlyMode, logger?: Logger) => ReminderStore | null;
|
|
401
|
+
//#endregion
|
|
402
|
+
//#region src/client/reminders.d.ts
|
|
403
|
+
type LaneStatus = {
|
|
404
|
+
applescript: "live" | "unavailable";
|
|
405
|
+
index: "live" | "unavailable" | "disabled";
|
|
406
|
+
indexMode: string | null;
|
|
407
|
+
storeFingerprint: string | null;
|
|
408
|
+
reason: string | null;
|
|
409
|
+
};
|
|
410
|
+
type ReminderAccount = {
|
|
411
|
+
id: string | null;
|
|
412
|
+
name: string | null;
|
|
413
|
+
isDefault: boolean;
|
|
414
|
+
listCount: number;
|
|
415
|
+
reminderCount: number;
|
|
416
|
+
};
|
|
417
|
+
type ReminderList = {
|
|
418
|
+
id: string | null;
|
|
419
|
+
name: string | null;
|
|
420
|
+
accountId: string | null;
|
|
421
|
+
accountName: string | null;
|
|
422
|
+
depth: number;
|
|
423
|
+
color: string | null;
|
|
424
|
+
emblem: string | null;
|
|
425
|
+
isDefault: boolean;
|
|
426
|
+
reminderCount: number | null;
|
|
427
|
+
incompleteCount: number | null;
|
|
428
|
+
};
|
|
429
|
+
type ReminderSummary = {
|
|
430
|
+
ref: string;
|
|
431
|
+
name: string | null;
|
|
432
|
+
completed: boolean;
|
|
433
|
+
/** The effective due instant, whichever of the two properties carries it. */
|
|
434
|
+
due: string | null;
|
|
435
|
+
/** True when the due date names a day rather than a time. */
|
|
436
|
+
dueAllDay: boolean;
|
|
437
|
+
/**
|
|
438
|
+
* Where `dueAllDay` came from.
|
|
439
|
+
*
|
|
440
|
+
* `index` is `ZALLDAY`, which is authoritative. `heuristic` means the index
|
|
441
|
+
* was unavailable and the flag was inferred from the due time being local
|
|
442
|
+
* midnight — because Apple Events populates BOTH date properties for every
|
|
443
|
+
* dated reminder and so cannot answer the question itself.
|
|
444
|
+
*/
|
|
445
|
+
dueAllDaySource: "index" | "heuristic";
|
|
446
|
+
remindMe: string | null;
|
|
447
|
+
priority: PriorityName;
|
|
448
|
+
flagged: boolean;
|
|
449
|
+
list: string | null;
|
|
450
|
+
account: string | null;
|
|
451
|
+
/** Set when this reminder's container is another reminder, i.e. it is a subtask. */
|
|
452
|
+
parentRef: string | null;
|
|
453
|
+
created: string | null;
|
|
454
|
+
modified: string | null;
|
|
455
|
+
source: "index" | "apple-events";
|
|
456
|
+
};
|
|
457
|
+
type ReminderDetail = ReminderSummary & {
|
|
458
|
+
body: string | null;
|
|
459
|
+
completionDate: string | null;
|
|
460
|
+
/** Kept separate from `due` so a caller can see which property actually holds it. */
|
|
461
|
+
dueDate: string | null;
|
|
462
|
+
alldayDueDate: string | null;
|
|
463
|
+
subtasks: ReminderSummary[];
|
|
464
|
+
/**
|
|
465
|
+
* Fields the scripting dictionary has no class for. Null — not empty — when
|
|
466
|
+
* the index lane is unavailable, so a caller can tell "none" from "unknown".
|
|
467
|
+
*/
|
|
468
|
+
attachments: {
|
|
469
|
+
id: string | null;
|
|
470
|
+
filename: string | null;
|
|
471
|
+
uti: string | null;
|
|
472
|
+
}[] | null;
|
|
473
|
+
alarms: IndexEnrichment | null;
|
|
474
|
+
};
|
|
475
|
+
/** Filters accepted by list and search. Every one is applied in JS over bulk arrays. */
|
|
476
|
+
type ReminderFilters = {
|
|
477
|
+
list?: string | undefined;
|
|
478
|
+
includeCompleted?: boolean | undefined;
|
|
479
|
+
dueBefore?: string | undefined;
|
|
480
|
+
dueAfter?: string | undefined;
|
|
481
|
+
flagged?: boolean | undefined;
|
|
482
|
+
priority?: PriorityName | undefined;
|
|
483
|
+
hasDueDate?: boolean | undefined;
|
|
484
|
+
limit: number;
|
|
485
|
+
};
|
|
486
|
+
/** The fields a create or update may set. Absent means "leave alone". */
|
|
487
|
+
type ReminderFields = {
|
|
488
|
+
name?: string | undefined;
|
|
489
|
+
body?: string | null | undefined;
|
|
490
|
+
due?: string | undefined;
|
|
491
|
+
remindMe?: string | undefined;
|
|
492
|
+
priority?: PriorityName | undefined;
|
|
493
|
+
flagged?: boolean | undefined;
|
|
494
|
+
completed?: boolean | undefined;
|
|
495
|
+
};
|
|
496
|
+
type AppleRemindersClientOptions = {
|
|
497
|
+
config: Config;
|
|
498
|
+
logger?: Logger | undefined;
|
|
499
|
+
/** Injected by tests so nothing spawns a process or touches a real Reminders. */
|
|
500
|
+
osascript?: OsascriptRunner | undefined;
|
|
501
|
+
/** Injected by tests so the TTL cache can be exercised without waiting. */
|
|
502
|
+
now?: (() => Date) | undefined;
|
|
503
|
+
};
|
|
504
|
+
/**
|
|
505
|
+
* The Reminders client.
|
|
506
|
+
*
|
|
507
|
+
* Two lanes, and which one answers depends on what was granted:
|
|
508
|
+
*
|
|
509
|
+
* - **Apple Events** — accounts, lists, every mutation, and the whole core
|
|
510
|
+
* model. Always the authority: after a write, the result is what Reminders
|
|
511
|
+
* re-read, never what was requested.
|
|
512
|
+
* - **Index** — the Core Data store, for the fields the scripting dictionary
|
|
513
|
+
* has no class for at all: tags, url, recurrence, alarms.
|
|
514
|
+
*
|
|
515
|
+
* That split is the opposite way round from Mail, where the file lane exists
|
|
516
|
+
* because Apple Events search took 74 seconds. Here the dictionary is complete
|
|
517
|
+
* enough to ship on, and the permission buys capability rather than speed —
|
|
518
|
+
* which is the rule recorded in docs/distribution.md.
|
|
519
|
+
*/
|
|
520
|
+
declare class AppleRemindersClient {
|
|
521
|
+
#private;
|
|
522
|
+
readonly config: Config;
|
|
523
|
+
readonly runner: OsascriptRunner;
|
|
524
|
+
constructor(opts: AppleRemindersClientOptions);
|
|
525
|
+
locate(): LocateResult;
|
|
526
|
+
/** Open the index once and remember the outcome, including the failure. */
|
|
527
|
+
index(): ReminderStore | null;
|
|
528
|
+
/**
|
|
529
|
+
* Probe both lanes.
|
|
530
|
+
*
|
|
531
|
+
* Apple Events is probed twice with a gap: the first event is what triggers
|
|
532
|
+
* the Automation prompt, and it can return failure while the user is still
|
|
533
|
+
* deciding — reporting "denied" then would be wrong.
|
|
534
|
+
*/
|
|
535
|
+
lanes(): Promise<LaneStatus>;
|
|
536
|
+
accounts(): Promise<ReminderAccount[]>;
|
|
537
|
+
lists(): Promise<ReminderList[]>;
|
|
538
|
+
/** Drop the cache after a write, so the next read reflects it. */
|
|
539
|
+
invalidate(): void;
|
|
540
|
+
listReminders(filters: ReminderFilters): Promise<ReminderSummary[]>;
|
|
541
|
+
/**
|
|
542
|
+
* Text search over name and, optionally, body.
|
|
543
|
+
*
|
|
544
|
+
* Filtering happens in JS over the bulk arrays rather than through a `whose`
|
|
545
|
+
* specifier. `whose` evaluates per item across the Apple Event bridge, which
|
|
546
|
+
* Notes measured at 6.9x slower for a substring match on a comparable library.
|
|
547
|
+
*/
|
|
548
|
+
searchReminders(query: string, opts: {
|
|
549
|
+
scope?: "title" | "full";
|
|
550
|
+
} & ReminderFilters): Promise<ReminderSummary[]>;
|
|
551
|
+
/**
|
|
552
|
+
* One reminder in full.
|
|
553
|
+
*
|
|
554
|
+
* Apple Events is the authority for the core model, and the index supplies
|
|
555
|
+
* what the dictionary has no class for: the authoritative all-day flag,
|
|
556
|
+
* subtasks (`container()` throws on every reminder, so there is no other
|
|
557
|
+
* way), attachments, alarms, recurrence and location.
|
|
558
|
+
*
|
|
559
|
+
* The two are joined on the UUID inside the Apple Events id — measured, by
|
|
560
|
+
* scanning every TEXT column in the store for a real id rather than guessing
|
|
561
|
+
* a column name.
|
|
562
|
+
*/
|
|
563
|
+
getReminder(ref: string): Promise<ReminderDetail>;
|
|
564
|
+
/** Resolve a list by name or id, erroring with what is available. */
|
|
565
|
+
resolveList(nameOrId: string): Promise<string>;
|
|
566
|
+
createReminder(fields: ReminderFields & {
|
|
567
|
+
name: string;
|
|
568
|
+
list?: string | undefined;
|
|
569
|
+
}): Promise<ReminderDetail>;
|
|
570
|
+
updateReminder(ref: string, fields: ReminderFields): Promise<ReminderDetail>;
|
|
571
|
+
completeReminders(refs: string[], completed?: boolean): Promise<{
|
|
572
|
+
ref: string;
|
|
573
|
+
found: boolean;
|
|
574
|
+
completed: boolean;
|
|
575
|
+
}[]>;
|
|
576
|
+
/**
|
|
577
|
+
* Move reminders to another list.
|
|
578
|
+
*
|
|
579
|
+
* Copy-then-delete, because `reminder.container` is read-only in the scripting
|
|
580
|
+
* dictionary. The new ref is returned alongside the old one so a caller can
|
|
581
|
+
* update anything it was holding — the old ref stops resolving.
|
|
582
|
+
*/
|
|
583
|
+
moveReminders(refs: string[], list: string): Promise<{
|
|
584
|
+
ref: string | null;
|
|
585
|
+
previousRef: string;
|
|
586
|
+
moved: boolean;
|
|
587
|
+
error?: string;
|
|
588
|
+
}[]>;
|
|
589
|
+
deleteReminders(refs: string[]): Promise<{
|
|
590
|
+
deleted: number;
|
|
591
|
+
missing: string[];
|
|
592
|
+
}>;
|
|
593
|
+
}
|
|
594
|
+
//#endregion
|
|
595
|
+
//#region src/server.d.ts
|
|
596
|
+
declare const SERVER_NAME: string;
|
|
597
|
+
declare const SERVER_VERSION: string;
|
|
598
|
+
type CreateServerOptions = {
|
|
599
|
+
config: Config;
|
|
600
|
+
logger?: Logger;
|
|
601
|
+
/** Injected by tests so nothing spawns a process or touches a real Reminders. */
|
|
602
|
+
osascript?: OsascriptRunner;
|
|
603
|
+
/** Injected by tests so the TTL cache can be exercised without waiting. */
|
|
604
|
+
now?: () => Date;
|
|
605
|
+
};
|
|
606
|
+
type CreatedServer = {
|
|
607
|
+
server: McpServer;
|
|
608
|
+
client: AppleRemindersClient;
|
|
609
|
+
};
|
|
610
|
+
/**
|
|
611
|
+
* Build the server. Side-effect free: it opens no connection, spawns no
|
|
612
|
+
* process and reads no file, so a test can construct it freely and every
|
|
613
|
+
* external dependency arrives through an option.
|
|
614
|
+
*/
|
|
615
|
+
declare const createServer: (opts: CreateServerOptions) => CreatedServer;
|
|
616
|
+
//#endregion
|
|
617
|
+
//#region src/tools/index.d.ts
|
|
618
|
+
type ToolContext = {
|
|
619
|
+
/**
|
|
620
|
+
* Register the mutating tools too. Off by default — with the flag off they are
|
|
621
|
+
* not merely refused, they are invisible and cannot be called at all.
|
|
622
|
+
*/
|
|
623
|
+
allowWrites: boolean;
|
|
624
|
+
};
|
|
625
|
+
/**
|
|
626
|
+
* Register the Apple Reminders tools.
|
|
627
|
+
*
|
|
628
|
+
* The registered set is a pure function of `allowWrites` and nothing else. In
|
|
629
|
+
* particular it does NOT vary with whether Full Disk Access is granted: that is
|
|
630
|
+
* a runtime condition which can change while the process lives, and MCP clients
|
|
631
|
+
* cache the tool list, so a tool that appears and disappears would leave clients
|
|
632
|
+
* calling names the server no longer has. Tools that need the index instead
|
|
633
|
+
* report their source, or explain what is missing.
|
|
634
|
+
*/
|
|
635
|
+
declare const registerTools: (server: McpServer, client: AppleRemindersClient, ctx: ToolContext) => void;
|
|
636
|
+
//#endregion
|
|
637
|
+
export { AppleRemindersClient, AppleRemindersError, BUILD_INFO, type BuildInfo, type Config, type CreateServerOptions, type DueKind, GROUP_CONTAINER, type IndexAttachment, type IndexEnrichment, type IndexList, type IndexReminder, InvalidDateError, type LaneStatus, ListNotFoundError, type LocateResult, PRIORITY_NAMES, type ParsedDate, type PriorityName, REF_VERSION, REMINDERS_SURFACE, type ReminderAccount, type ReminderDetail, type ReminderFields, type ReminderFilters, type ReminderList, ReminderNotFoundError, type ReminderQuery, type ReminderRef, ReminderStore, type ReminderSummary, RemindersBusyError, RemindersNotRunningError, SERVER_NAME, SERVER_VERSION, type StoreCandidate, type StoreCapabilities, type ToolContext, createServer, decodeRef, defaultContainerPath, encodeRef, introspect, loadConfig, locateStore, openStore, parseBound, parseDate, rank, refFromUuid, registerTools, toLocalIso, toPriorityName, toPriorityValue, uuidOf };
|
|
638
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/locate.ts","../src/client/priority.ts","../src/client/ref.ts","../src/config.ts","../src/client/store.ts","../src/client/reminders.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
import { A as RemindersBusyError, C as parseDate, D as ListNotFoundError, E as InvalidDateError, M as BUILD_INFO, O as REMINDERS_SURFACE, S as parseBound, T as AppleRemindersError, _ as toPriorityName, a as loadConfig, b as defaultContainerPath, c as introspect, d as decodeRef, f as encodeRef, g as rank, h as PRIORITY_NAMES, i as registerTools, j as RemindersNotRunningError, k as ReminderNotFoundError, l as openStore, m as uuidOf, n as SERVER_VERSION, o as AppleRemindersClient, p as refFromUuid, r as createServer, s as ReminderStore, t as SERVER_NAME, u as REF_VERSION, v as toPriorityValue, w as toLocalIso, x as locateStore, y as GROUP_CONTAINER } from "./server-pj2yDDQb.js";
|
|
2
|
+
export { AppleRemindersClient, AppleRemindersError, BUILD_INFO, GROUP_CONTAINER, InvalidDateError, ListNotFoundError, PRIORITY_NAMES, REF_VERSION, REMINDERS_SURFACE, ReminderNotFoundError, ReminderStore, RemindersBusyError, RemindersNotRunningError, SERVER_NAME, SERVER_VERSION, createServer, decodeRef, defaultContainerPath, encodeRef, introspect, loadConfig, locateStore, openStore, parseBound, parseDate, rank, refFromUuid, registerTools, toLocalIso, toPriorityName, toPriorityValue, uuidOf };
|