@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.
@@ -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 };