@mgcrea/mcp-apple-contacts 0.0.0-bootstrap

package/dist/server-BjWSCaMN.js

@@ -0,0 +1,1480 @@
+import { AppleAutomationError, AppleAutomationError as AppleContactsError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, IndexUnavailableError as IndexUnavailableError$1, SchemaDriftError, SchemaDriftError as SchemaDriftError$1, columnsOf, createOsascriptRunner, describeStore, escapeLike, fail, fingerprintSchema, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, readPackageIdentity, trimmed, withBusyRetry, wrap } from "@mgcrea/mcp-apple-core";
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+//#region src/build-info.ts
+const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
+	name: "@mgcrea/mcp-apple-contacts",
+	version: "0.0.0"
+});
+const BUILD_INFO = {
+	name: pkg.name,
+	version: pkg.version,
+	gitCommit: "df06e7f",
+	gitCommitDate: "2026-08-22T16:20:23+02:00"
+};
+//#endregion
+//#region src/client/errors.ts
+/**
+* Contacts' error surface. The taxonomy lives in `@mgcrea/mcp-apple-core`; what
+* belongs here is the identity those messages are written against.
+*/
+const CONTACTS_SURFACE = {
+	appName: "Contacts",
+	envPrefix: "APPLE_CONTACTS"
+};
+/**
+* Contacts' Apple Events target — and, like Calendar's `com.apple.iCal`, not the
+* display name. Contacts.app kept the id it shipped with as Address Book;
+* `com.apple.Contacts` does not exist.
+*
+* Used by the write lane only. Reads never send an Apple Event.
+*/
+const CONTACTS_BUNDLE_ID = "com.apple.AddressBook";
+/** A contact ref no longer resolves — deleted, or its account was removed. */
+var ContactNotFoundError = class extends AppleAutomationError {
+	name = "ContactNotFoundError";
+	constructor(ref) {
+		super(`No contact for ref "${ref}". It was probably deleted, or the account holding it was removed, since the search ran. Re-run the search to get a current ref.`, { ref });
+	}
+};
+/**
+* The store could not be read, with the reason spelled out.
+*
+* Its own error because Contacts fails differently from every other surface in
+* this repo: it sits behind its own TCC service rather than behind Full Disk
+* Access, and unlike Full Disk Access that permission PROMPTS. So the fix is
+* usually "answer the dialog", not "go to System Settings" — and telling
+* somebody to grant whole-disk access for an address book would be asking for
+* far more than this server needs.
+*/
+var ContactsUnavailableError = class extends AppleAutomationError {
+	name = "ContactsUnavailableError";
+	constructor(reason) {
+		super(reason, {});
+	}
+};
+/**
+* A write did not survive the save.
+*
+* Its own error because Contacts fails this way and the other surfaces do not:
+* changes sit in an unsaved buffer until `save()` runs, so a mutation can
+* succeed, read back correctly inside the same script, and still never reach the
+* store. Every write script saves and then re-reads; this is what it raises when
+* the re-read comes back empty.
+*/
+var ContactWriteNotPersistedError = class extends AppleAutomationError {
+	name = "ContactWriteNotPersistedError";
+	constructor(message) {
+		super(`${message} Contacts keeps edits in an unsaved buffer, so this usually means the save was refused — check whether Contacts has a modal sheet open, or an account that is read-only.`, {});
+	}
+};
+//#endregion
+//#region src/client/jxa/core.ts
+/**
+* JXA script fragments for Contacts.
+*
+* Every script here is a static constant. None may contain a template
+* interpolation — `assertStaticScript` rejects any script containing a dollar
+* sign followed by a brace, including template literals written INSIDE the JXA
+* source. Use string concatenation in JXA code.
+*
+* Every script follows the same contract:
+*   - it reads its parameters from `JSON.parse(argv[0])`
+*   - it returns `JSON.stringify({ok: true, data})` on success
+*   - it returns `JSON.stringify({ok: false, error: {code, message}})` on an
+*     application-level failure, still exiting 0
+* so a non-zero exit always means infrastructure rather than "no such contact".
+*
+* ## There is no read.ts here, and that is still the design
+*
+* Adding writes did not add a read lane. Reads come off the file lane, which is
+* the only place a suffix-keyed index over 970 phone numbers can be built at
+* all — see `../store.ts`. These scripts exist only to make Contacts CHANGE
+* something. `test/jxa.test.ts` asserts `read.ts` does not exist.
+*
+* ## What the dictionary actually offers
+*
+* MEASURED from `sdef /System/Applications/Contacts.app` on macOS 26.6. The
+* whole command list is four verbs:
+*
+*     make      create a person, or a phone/email element under one
+*     add       put a person in a group
+*     remove    take a person out of a group
+*     save      commit everything
+*
+* That is all of it. The Standard Suite here contains **only `make`** — the
+* string "delete" does not appear anywhere in the dictionary. So there is no
+* supported way to delete a contact over Apple Events, which is why this file
+* has no DELETE script and why `delete_contacts` is not a tool. Whether Cocoa
+* Scripting answers an undeclared `delete` event anyway is a separate question
+* and an unmeasured one; guessing at it would risk destroying a real person's
+* card on the strength of an assumption.
+*
+* ## `save` is explicit, global, and the whole reason this is not like Calendar
+*
+* Calendar and Reminders persist a property assignment immediately. Contacts
+* does not: changes sit in an unsaved buffer until `Application("Contacts").save()`
+* runs, and the dictionary says so — the application class carries an `unsaved`
+* property, and `save` is documented as "Save ALL Contacts changes".
+*
+* Two consequences, both load-bearing:
+*
+* 1. **A write that forgets `save()` silently does nothing.** The object updates,
+*    every read-back inside the same script agrees, and the store never changes.
+*    Every script below saves before it verifies.
+* 2. **`save()` is not scoped to our change.** It commits whatever else is
+*    pending, including an edit someone has half-typed in the Contacts window.
+*    That is a property of the dictionary, not a choice made here, and the tool
+*    descriptions say so.
+*/
+/**
+* Shared prelude.
+*
+* The bundle identifier is `com.apple.AddressBook`, which — like Calendar's
+* `com.apple.iCal` — does not match the display name. Contacts.app kept the id
+* it shipped with as Address Book. `Application("Contacts")` is the correct
+* scripting name; `com.apple.Contacts` does not exist.
+*/
+const PRELUDE = `
+ObjC.import("AppKit");
+
+function isContactsRunning() {
+  var apps = $.NSRunningApplication.runningApplicationsWithBundleIdentifier("com.apple.AddressBook");
+  return apps.count > 0;
+}
+
+function ok(data) { return JSON.stringify({ ok: true, data: data }); }
+function err(code, message) { return JSON.stringify({ ok: false, error: { code: code, message: String(message) } }); }
+
+/** Read one property defensively: Contacts throws on properties it cannot supply. */
+function prop(fn, fallback) {
+  try {
+    var v = fn();
+    return v === undefined ? fallback : v;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+/**
+ * Find one person, without assuming the two lanes spell an id the same way.
+ *
+ * The file lane holds \`ZABCDRECORD.ZUNIQUEID\`; Apple Events returns whatever
+ * \`person.id()\` returns. That those are the same string is EXACTLY the kind of
+ * thing this project has been wrong about before — Calendar's \`calendar.uid()\`
+ * throws for every calendar, and the id bridge that held for its events did not
+ * extend to them. It is unmeasured here, so it is not assumed.
+ *
+ * Two attempts, cheapest first:
+ *
+ *   1. \`byId()\` with the value as given. Contacts offers a real by-id lookup,
+ *      unlike Calendar, so when the forms do agree this costs one round trip.
+ *   2. A bulk \`people.id()\` fetch, matched on the UUID substring. This is the
+ *      guard, and it is affordable precisely here: docs/contacts.md measured the
+ *      whole id list at 63-73 ms over 421 people, against the 1.8 s that made the
+ *      same trick unusable for Calendar's events.
+ *
+ * So a mismatch in id FORM degrades to a fast scan instead of a wrong "not
+ * found" — which is the failure this would otherwise produce, and the one that
+ * looks like the contact was deleted.
+ */
+function uuidOf(value) {
+  var m = /[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/.exec(String(value || ""));
+  return m ? m[0].toUpperCase() : null;
+}
+
+function findPerson(C, personId) {
+  try {
+    var direct = C.people.byId(personId);
+    direct.id();
+    return direct;
+  } catch (e) {
+    // Fall through to the scan.
+  }
+
+  var wanted = uuidOf(personId);
+  if (!wanted) return null;
+
+  try {
+    var ids = C.people.id();
+    for (var i = 0; i < ids.length; i++) {
+      if (uuidOf(ids[i]) === wanted) {
+        var found = C.people.byId(ids[i]);
+        found.id();
+        return found;
+      }
+    }
+  } catch (e2) {
+    return null;
+  }
+  return null;
+}
+
+/** Everything a write returns, so a caller sees what Contacts stored. */
+function shapePerson(p) {
+  return {
+    id: prop(function () { return String(p.id()); }, null),
+    name: prop(function () { return p.name(); }, null),
+    firstName: prop(function () { return p.firstName(); }, null),
+    lastName: prop(function () { return p.lastName(); }, null),
+    nickname: prop(function () { return p.nickname(); }, null),
+    organization: prop(function () { return p.organization(); }, null),
+    jobTitle: prop(function () { return p.jobTitle(); }, null),
+    department: prop(function () { return p.department(); }, null),
+    note: prop(function () { return p.note(); }, null),
+    company: prop(function () { return p.company(); }, false),
+    phones: prop(function () {
+      var out = [];
+      var xs = p.phones();
+      for (var i = 0; i < xs.length; i++) {
+        out.push({
+          label: prop(function () { return xs[i].label(); }, null),
+          value: prop(function () { return xs[i].value(); }, null)
+        });
+      }
+      return out;
+    }, []),
+    emails: prop(function () {
+      var out = [];
+      var xs = p.emails();
+      for (var i = 0; i < xs.length; i++) {
+        out.push({
+          label: prop(function () { return xs[i].label(); }, null),
+          value: prop(function () { return xs[i].value(); }, null)
+        });
+      }
+      return out;
+    }, [])
+  };
+}
+
+/**
+ * Apply the scalar properties a caller supplied.
+ *
+ * Only keys actually present are touched: a missing key means "leave it alone",
+ * an explicit null means "clear it". Assigning undefined would blank a field the
+ * caller never mentioned.
+ */
+function applyFields(p, f) {
+  if (f.firstName !== undefined) p.firstName = f.firstName;
+  if (f.lastName !== undefined) p.lastName = f.lastName;
+  if (f.nickname !== undefined) p.nickname = f.nickname;
+  if (f.organization !== undefined) p.organization = f.organization;
+  if (f.jobTitle !== undefined) p.jobTitle = f.jobTitle;
+  if (f.department !== undefined) p.department = f.department;
+  if (f.note !== undefined) p.note = f.note;
+  if (f.company !== undefined) p.company = f.company;
+}
+
+/**
+ * Add phone and email elements.
+ *
+ * These are ELEMENTS, not properties: a phone number is its own object made at
+ * the end of the person's phones. There is no way to set them as a bulk array,
+ * so each one is a separate \`make\`.
+ */
+function addChildren(C, p, phones, emails) {
+  var i;
+  if (phones) {
+    for (i = 0; i < phones.length; i++) {
+      p.phones.push(C.Phone({ label: phones[i].label || "mobile", value: phones[i].value }));
+    }
+  }
+  if (emails) {
+    for (i = 0; i < emails.length; i++) {
+      p.emails.push(C.Email({ label: emails[i].label || "home", value: emails[i].value }));
+    }
+  }
+}
+`;
+//#endregion
+//#region src/client/jxa/write.ts
+/**
+* The write scripts. Two verbs, and the absence of a third is deliberate.
+*
+* `create` and `update` are both `make`-and-`save`. There is no `delete`,
+* because the Contacts dictionary has no delete command — see `core.ts` for the
+* measurement. That absence is enforced by `test/jxa.test.ts`, so removing a
+* contact cannot be added here without the decision being taken again.
+*
+* Every script SAVES and then RE-READS, in that order. Contacts keeps changes in
+* an unsaved buffer, so a script that skips the save mutates a live object,
+* reports success from its own in-memory read, and leaves the store untouched.
+* Verifying before saving would find exactly the same false success.
+*/
+const CREATE_CONTACT = `${PRELUDE}
+function run(argv) {
+  var p = JSON.parse(argv[0]);
+  var C = Application("Contacts");
+
+  if (!isContactsRunning() && !p.allowLaunch) {
+    return err("APP_NOT_RUNNING", "Contacts is not running.");
+  }
+
+  var person;
+  try {
+    person = C.Person({
+      firstName: p.fields.firstName || "",
+      lastName: p.fields.lastName || ""
+    });
+    C.people.push(person);
+  } catch (e) {
+    return err("CREATE_FAILED", e.message || e);
+  }
+
+  try {
+    applyFields(person, p.fields);
+    addChildren(C, person, p.phones, p.emails);
+  } catch (e) {
+    // The person exists but is incomplete. Save anyway so the caller is told
+    // about a real half-written card rather than a phantom one, and let the
+    // read-back below show exactly what landed.
+    try { C.save(); } catch (e2) {}
+    return err("CREATE_INCOMPLETE", e.message || e);
+  }
+
+  try {
+    C.save();
+  } catch (e) {
+    return err("SAVE_FAILED", e.message || e);
+  }
+
+  // Re-read AFTER the save, so what comes back is what Contacts stored rather
+  // than what this script asked for.
+  var fresh = findPerson(C, prop(function () { return String(person.id()); }, ""));
+  if (!fresh) {
+    return err("CREATE_NOT_PERSISTED", "Contacts saved without error but the contact could not be read back.");
+  }
+  return ok(shapePerson(fresh));
+}
+`;
+const UPDATE_CONTACT = `${PRELUDE}
+function run(argv) {
+  var p = JSON.parse(argv[0]);
+  var C = Application("Contacts");
+
+  if (!isContactsRunning() && !p.allowLaunch) {
+    return err("APP_NOT_RUNNING", "Contacts is not running.");
+  }
+
+  var person = findPerson(C, p.personId);
+  if (!person) {
+    return err("CONTACT_NOT_FOUND", "No contact with id " + p.personId + ".");
+  }
+
+  try {
+    applyFields(person, p.fields);
+    addChildren(C, person, p.phones, p.emails);
+  } catch (e) {
+    return err("UPDATE_FAILED", e.message || e);
+  }
+
+  try {
+    C.save();
+  } catch (e) {
+    return err("SAVE_FAILED", e.message || e);
+  }
+
+  var fresh = findPerson(C, p.personId);
+  if (!fresh) {
+    return err("UPDATE_NOT_PERSISTED", "Contacts saved without error but the contact could not be read back.");
+  }
+  return ok(shapePerson(fresh));
+}
+`;
+//#endregion
+//#region src/client/locate.ts
+/**
+* Find Contacts' stores — plural, which is the whole point of this file.
+*
+* Every other surface in this repo has one store. Contacts has one per account
+* plus a root database, and `docs/contacts.md` measured what that means:
+*
+*     AddressBook-v22.abcddb                       1 contact
+*     Sources/<uuid>/AddressBook-v22.abcddb      420 contacts
+*
+* The obvious path — the one at the top of the directory — is present, readable,
+* correctly shaped, and empty. A server that opens it gets a working database
+* with nobody in it, which fails no check and returns no answer. That is not a
+* hypothetical: `scripts/probe-contacts.mjs` did exactly this and reported a
+* confident 0% resolution rate before anyone noticed.
+*
+* So there is no "the" store here. Everything readable is opened and the rows
+* are unioned, and the number of sources is discovered rather than assumed —
+* one on the probed machine, more with Google or Exchange accounts.
+*/
+/** `~/Library/Application Support/AddressBook`. */
+const ADDRESSBOOK_DIR = join("Library", "Application Support", "AddressBook");
+/** The per-account subdirectory. Each child holds one database. */
+const SOURCES_DIRNAME = "Sources";
+/** Constant on every store, root and source alike. */
+const STORE_FILENAME = "AddressBook-v22.abcddb";
+const defaultDirPath = (home = homedir()) => join(home, ADDRESSBOOK_DIR);
+/**
+* The grant hint.
+*
+* Deliberately NOT the Full Disk Access sentence the other surfaces use.
+* Contacts is protected by its own TCC service, and unlike Full Disk Access that
+* one prompts — so the likely fix is a dialog that was dismissed, and the
+* remedy names the Contacts pane rather than asking for the whole disk.
+*/
+const GRANT_HINT = "Contacts is protected by its own privacy permission, not by Full Disk Access. macOS asks for it the first time something reads the address book; if that dialog was dismissed, re-enable the app under System Settings > Privacy & Security > Contacts and restart it.";
+const listDirs = (dir) => {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+	} catch {
+		return [];
+	}
+};
+const locateStores = (opts = {}) => {
+	const dirPath = defaultDirPath(opts.home);
+	if (opts.storePath) {
+		const candidate = {
+			...describeStore(opts.storePath),
+			path: opts.storePath,
+			label: "explicit"
+		};
+		return {
+			dirPath,
+			dirListable: true,
+			candidates: [candidate],
+			readable: candidate.readable ? [candidate] : [],
+			sourceCount: 0,
+			reason: candidate.readable ? null : candidate.exists ? `The store at ${opts.storePath} exists but cannot be read. ${GRANT_HINT}` : `No file at ${opts.storePath}. APPLE_CONTACTS_STORE points at nothing.`
+		};
+	}
+	const rootPath = join(dirPath, STORE_FILENAME);
+	const sourceNames = listDirs(join(dirPath, SOURCES_DIRNAME));
+	const candidates = [{
+		...describeStore(rootPath),
+		path: rootPath,
+		label: "root"
+	}, ...sourceNames.map((name) => {
+		const path = join(dirPath, SOURCES_DIRNAME, name, STORE_FILENAME);
+		return {
+			...describeStore(path),
+			path,
+			label: name
+		};
+	})].filter((c) => c.exists);
+	const readable = candidates.filter((c) => c.readable);
+	const dirListable = listDirs(dirPath).length > 0 || sourceNames.length > 0;
+	const reason = readable.length ? null : candidates.length ? `Found ${candidates.length} Contacts store(s) under ${dirPath} but none could be opened. ${GRANT_HINT}` : dirListable ? `No ${STORE_FILENAME} under ${dirPath}. Has Contacts ever been set up on this account?` : `${dirPath} could not be listed, so the per-account stores could not be found. ${GRANT_HINT}`;
+	return {
+		dirPath,
+		dirListable,
+		candidates,
+		readable,
+		sourceCount: sourceNames.length,
+		reason
+	};
+};
+//#endregion
+//#region src/client/phone.ts
+/**
+* Phone number matching, which on this surface is the whole product.
+*
+* Contacts stores what the user typed. `docs/contacts.md` measured a 400-row
+* sample of `ZFULLNUMBER`: 222 formatted (`06 12 34 56 78`), 159 already E.164,
+* 15 bare digits. Messages, meanwhile, stores a handle as E.164 and nothing
+* else. So the two never meet as strings, and the measurement says so with an
+* unusually blunt number: **exact string equality resolves 3.7% of message
+* traffic.** A resolver that joins on the stored value is not slightly wrong, it
+* is useless.
+*
+* What works is a SUFFIX. No prefix rule connects `06…` to `+336…` without
+* knowing the user's country, which nothing here has any business guessing, but
+* the two agree from the ninth digit back.
+*/
+/** Everything that is not a digit, removed. The base of every key below. */
+const digitsOf = (value) => value.replaceAll(/\D/g, "");
+/**
+* How many trailing digits make a key. Nine, measured rather than picked.
+*
+* | key      | recent traffic resolved | ambiguous |
+* | -------- | ----------------------- | --------- |
+* | exact    | 8.5%                    | 1         |
+* | 10       | 96.7%                   | 5         |
+* | **9**    | **97.6%**               | **6**     |
+* | 7        | 97.6%                   | 6         |
+*
+* Seven ties nine on every column measured, so nine wins on the tie-break that
+* matters: a shorter key can only ever collide more. Ten is where French
+* national numbers (`0612345678`, ten digits) stop lining up with the same
+* number in E.164 (`+33612345678`, eleven) — which is exactly why 10 does no
+* better than plain digits and 9 does.
+*/
+const SUFFIX_DIGITS = 9;
+/**
+* Below this, a number is a shortcode — a bank, a delivery service, a 2FA
+* sender. 115 of the 958 handles in the measured `chat.db` were these. They can
+* never resolve to a contact, and counting them as failures is how a resolver
+* ends up reporting a far worse rate than it earns.
+*/
+const SHORTCODE_MAX_DIGITS = 6;
+const isShortcode = (value) => {
+	const d = digitsOf(value);
+	return d.length > 0 && d.length <= SHORTCODE_MAX_DIGITS;
+};
+/**
+* The lookup key, or `null` when the value is too short to make one.
+*
+* Returning `null` rather than a short key is deliberate: a three-digit key
+* would match any number ending in those digits, which is the failure mode this
+* whole module exists to avoid.
+*/
+const suffixKey = (value, digits = 9) => {
+	const d = digitsOf(value);
+	return d.length >= digits ? d.slice(-digits) : null;
+};
+/** Email keys are simply case-folded. Measured: 37 of 60 resolve, none ambiguous. */
+const emailKey = (value) => value.trim().toLowerCase();
+/**
+* What kind of thing a Messages handle is.
+*
+* Order matters: `@` decides first, because an email address can contain digits
+* and a phone number can never contain an `@`.
+*/
+const handleKind = (handle) => {
+	if (handle.includes("@")) return "email";
+	return isShortcode(handle) ? "shortcode" : "phone";
+};
+//#endregion
+//#region src/client/resolve.ts
+/**
+* Distinct PEOPLE, not distinct rows.
+*
+* A contact with the same number stored twice (mobile and iPhone, which Contacts
+* does routinely) would otherwise read as ambiguous. Linked records across two
+* accounts are collapsed on `ZLINKID` for the same reason: Contacts shows one
+* unified card for them, and reporting two names for one person would contradict
+* what the user sees in the app.
+*/
+const distinctPeople = (ids, lookup) => {
+	const seen = /* @__PURE__ */ new Map();
+	for (const id of ids) {
+		const contact = lookup.contacts.get(id);
+		if (!contact) continue;
+		const key = contact.linkId === null ? `pk:${id}` : `link:${contact.linkId}`;
+		if (!seen.has(key)) seen.set(key, contact);
+	}
+	return [...seen.values()];
+};
+const resolveHandle = (handle, lookup) => {
+	const kind = handleKind(handle);
+	const base = {
+		handle,
+		kind,
+		name: null,
+		contact: null,
+		matches: 0
+	};
+	if (kind === "shortcode") return {
+		...base,
+		status: "shortcode"
+	};
+	const ids = kind === "email" ? lookup.byEmail.get(emailKey(handle)) : (() => {
+		const key = suffixKey(handle, lookup.suffixDigits);
+		return key === null ? void 0 : lookup.byPhone.get(key);
+	})();
+	if (!ids?.size) return {
+		...base,
+		status: "unknown"
+	};
+	const people = distinctPeople(ids, lookup);
+	if (people.length === 1) {
+		const contact = people[0];
+		return {
+			handle,
+			kind,
+			status: "resolved",
+			name: contact.displayName,
+			contact,
+			matches: 1
+		};
+	}
+	if (people.length === 0) return {
+		...base,
+		status: "unknown"
+	};
+	return {
+		...base,
+		status: "ambiguous",
+		matches: people.length
+	};
+};
+const resolveHandles = (handles, lookup) => handles.map((h) => resolveHandle(h, lookup));
+/** Counts by status, for a caller that wants to report coverage honestly. */
+const summarise = (results) => {
+	const out = {
+		resolved: 0,
+		unknown: 0,
+		ambiguous: 0,
+		shortcode: 0
+	};
+	for (const r of results) out[r.status] += 1;
+	return out;
+};
+//#endregion
+//#region src/client/store.ts
+/**
+* Contacts' file lane.
+*
+* Reads only, and there is no Apple Events lane at all — not even a fallback.
+* `docs/contacts.md` measured the dictionary as fast (63 ms for every id, 52 ms
+* for every phone number) and still ruled it out for reads, because the thing
+* this surface exists to do is join 970 stored numbers against a set of handles
+* by suffix, and no amount of round trips gets a keyed index out of `osascript`.
+* The consequence is worth stating: **a read-only surface needs no Automation
+* grant**, so this server never prompts for one.
+*
+* ## Two things measured here that are not obvious from the schema
+*
+* **The store is plural.** See `locate.ts`. Every method on `ContactsIndex` fans
+* out over shards and merges.
+*
+* **`ZABCDRECORD` is not a table of contacts.** It is a Core Data single-table
+* inheritance root, and groups, containers and an info row live in it alongside
+* people — 425 rows for 420 contacts on the probed machine. `Z_ENT` is the only
+* discriminator, and it is resolved through `Z_PRIMARYKEY` BY NAME rather than
+* hardcoded, because Core Data assigns those numbers per model version.
+*/
+/** Tables the lane cannot work without. */
+const REQUIRED = ["ZABCDRECORD"];
+/** The schema this was written against. Named in the drift error, not enforced. */
+const PROBED_FINGERPRINT = "4f2871e93f6b";
+const PROBED_MACOS = "26.6";
+/**
+* Entity names that mean "a person".
+*
+* `ABCDSubscribedContact` inherits from `ABCDContact` and is included: a contact
+* arriving from a subscribed source is still someone whose name should appear
+* beside their messages. Groups (`ABCDGroup`, `ABCDSmartGroup`) and the
+* bookkeeping entities (`ABCDInfo`, `CNCDContainer`) are not people.
+*/
+const CONTACT_ENTITIES = /^(ABCD)?(Subscribed)?Contact$/i;
+const num = (v) => typeof v === "number" ? v : null;
+const text = (v) => typeof v === "string" && v.length > 0 ? v : null;
+/**
+* A name to show, assembled from whatever the record actually carries.
+*
+* Falls through deliberately: plenty of real contacts are an organisation with
+* no person name (a garage, a doctor's office), and plenty are a first name
+* alone. Returning an empty string would put a blank where a sender should be,
+* so the last resort is explicit.
+*/
+const displayNameOf = (c) => {
+	return [c.firstName, c.lastName].filter(Boolean).join(" ").trim() || c.nickname || c.organization || "(no name)";
+};
+/**
+* Add one key to one bucket. A null key is skipped, never stored as `""` — a
+* number too short to make a key must not become a key that matches everything.
+*/
+const remember = (map, key, id) => {
+	if (!key) return;
+	const bucket = map.get(key);
+	if (bucket) bucket.add(id);
+	else map.set(key, /* @__PURE__ */ new Set([id]));
+};
+var ContactsIndex = class ContactsIndex {
+	shards;
+	constructor(shards) {
+		this.shards = shards;
+	}
+	/** Every shard's fingerprint. More than one distinct value is worth showing. */
+	get fingerprints() {
+		return [...new Set(this.shards.map((s) => s.caps.fingerprint))];
+	}
+	get totalContacts() {
+		return this.shards.reduce((n, s) => n + s.contacts, 0);
+	}
+	/**
+	* Project a column, or a typed NULL when this store does not have it.
+	*
+	* Same guard as the other surfaces: the schema is reverse-engineered and
+	* unversioned, so an Apple rename costs one field rather than the lane.
+	*/
+	static #col(present, table, name, alias) {
+		return present.has(name) ? `${table}."${name}" AS ${alias}` : `NULL AS ${alias}`;
+	}
+	static #entFilter(caps, alias) {
+		if (!caps.contactEntities.length) return "";
+		return `WHERE ${alias}."Z_ENT" IN (${caps.contactEntities.join(", ")})`;
+	}
+	#contactsFrom(shard, where, params, limit) {
+		const c = shard.caps.recordColumns;
+		const col = ContactsIndex.#col;
+		const ent = ContactsIndex.#entFilter(shard.caps, "r");
+		const extra = where ? `${ent ? "AND" : "WHERE"} ${where}` : "";
+		const sql = `
+      SELECT r."Z_PK" AS recordPk,
+             ${col(c, "r", "ZUNIQUEID", "uniqueId")},
+             ${col(c, "r", "ZFIRSTNAME", "firstName")},
+             ${col(c, "r", "ZLASTNAME", "lastName")},
+             ${col(c, "r", "ZNICKNAME", "nickname")},
+             ${col(c, "r", "ZORGANIZATION", "organization")},
+             ${col(c, "r", "ZJOBTITLE", "jobTitle")},
+             ${col(c, "r", "ZLINKID", "linkId")},
+             ${col(c, "r", "ZCONTAINERWHERECONTACTISME", "isMe")}
+        FROM "ZABCDRECORD" r
+        ${ent} ${extra}
+       ORDER BY r."ZLASTNAME" ASC, r."ZFIRSTNAME" ASC
+       LIMIT ${Math.max(1, Math.trunc(limit))}`;
+		return shard.db.prepare(sql).all(...params).map((r) => {
+			const parts = {
+				firstName: text(r.firstName),
+				lastName: text(r.lastName),
+				nickname: text(r.nickname),
+				organization: text(r.organization)
+			};
+			return {
+				recordPk: Number(r.recordPk),
+				uniqueId: text(r.uniqueId),
+				...parts,
+				jobTitle: text(r.jobTitle),
+				displayName: displayNameOf(parts),
+				source: shard.label,
+				linkId: num(r.linkId),
+				isMe: num(r.isMe) !== null
+			};
+		});
+	}
+	/** Every contact, across every shard. */
+	list(limit) {
+		return this.shards.flatMap((s) => this.#contactsFrom(s, "", [], limit)).slice(0, limit);
+	}
+	/**
+	* Name search.
+	*
+	* `LIKE ? ESCAPE '\'` with core's `escapeLike`, so a contact called "100%
+	* Design" can be searched for literally instead of matching everyone.
+	*/
+	search(query, limit) {
+		const needle = `%${escapeLike(query)}%`;
+		const out = [];
+		for (const shard of this.shards) {
+			const c = shard.caps.recordColumns;
+			const fields = [
+				"ZFIRSTNAME",
+				"ZLASTNAME",
+				"ZNICKNAME",
+				"ORGANIZATION",
+				"ZORGANIZATION"
+			].filter((f) => c.has(f)).map((f) => `r."${f}" LIKE ? ESCAPE '\\'`);
+			if (!fields.length) continue;
+			out.push(...this.#contactsFrom(shard, `(${fields.join(" OR ")})`, fields.map(() => needle), limit));
+		}
+		return out.slice(0, limit);
+	}
+	byPk(shardLabel, recordPk) {
+		const shard = this.shards.find((s) => s.label === shardLabel);
+		if (!shard) return null;
+		return this.#contactsFrom(shard, `r."Z_PK" = ?`, [recordPk], 1)[0] ?? null;
+	}
+	#childRows(shard, table, caps, valueColumns, recordPks) {
+		if (!caps.size) return [];
+		const valueCol = valueColumns.find((v) => caps.has(v));
+		if (!valueCol || !caps.has("ZOWNER")) return [];
+		const scope = recordPks?.length ? `AND x."ZOWNER" IN (${recordPks.map(() => "?").join(", ")})` : "";
+		const sql = `
+      SELECT x."ZOWNER" AS recordPk,
+             x."${valueCol}" AS value,
+             ${caps.has("ZLABEL") ? `x."ZLABEL"` : "NULL"} AS label
+        FROM "${table}" x
+       WHERE x."${valueCol}" IS NOT NULL AND x."${valueCol}" <> '' ${scope}`;
+		return shard.db.prepare(sql).all(...recordPks ?? []).flatMap((r) => {
+			const value = text(r.value);
+			const recordPk = num(r.recordPk);
+			if (!value || recordPk === null) return [];
+			return [{
+				recordPk,
+				value,
+				label: text(r.label)
+			}];
+		});
+	}
+	phonesFor(shardLabel, recordPks) {
+		const shard = this.shards.find((s) => s.label === shardLabel);
+		if (!shard) return [];
+		return this.#childRows(shard, "ZABCDPHONENUMBER", shard.caps.phoneColumns, ["ZFULLNUMBER"], recordPks);
+	}
+	emailsFor(shardLabel, recordPks) {
+		const shard = this.shards.find((s) => s.label === shardLabel);
+		if (!shard) return [];
+		return this.#childRows(shard, "ZABCDEMAILADDRESS", shard.caps.emailColumns, ["ZADDRESS", "ZADDRESSNORMALIZED"], recordPks);
+	}
+	/**
+	* The resolver index: every phone suffix and every email, keyed to a contact.
+	*
+	* Built in one pass over every shard because a handle does not know which
+	* account its owner lives in. A key mapping to more than one DISTINCT contact
+	* is kept as such — see `resolve.ts`, which reports ambiguity rather than
+	* picking. `docs/contacts.md` measured six such collisions at nine digits, and
+	* twenty-eight at four.
+	*/
+	buildLookup(suffixDigits = 9) {
+		const byPhone = /* @__PURE__ */ new Map();
+		const byEmail = /* @__PURE__ */ new Map();
+		const contacts = /* @__PURE__ */ new Map();
+		for (const shard of this.shards) {
+			const people = this.#contactsFrom(shard, "", [], Number.MAX_SAFE_INTEGER);
+			const byPk = new Map(people.map((p) => [p.recordPk, p]));
+			for (const p of people) contacts.set(`${shard.label}:${p.recordPk}`, p);
+			for (const row of this.#childRows(shard, "ZABCDPHONENUMBER", shard.caps.phoneColumns, ["ZFULLNUMBER"])) {
+				if (!byPk.has(row.recordPk)) continue;
+				remember(byPhone, suffixKey(row.value, suffixDigits), `${shard.label}:${row.recordPk}`);
+			}
+			for (const row of this.#childRows(shard, "ZABCDEMAILADDRESS", shard.caps.emailColumns, ["ZADDRESS", "ZADDRESSNORMALIZED"])) {
+				if (!byPk.has(row.recordPk)) continue;
+				remember(byEmail, emailKey(row.value), `${shard.label}:${row.recordPk}`);
+			}
+		}
+		return {
+			byPhone,
+			byEmail,
+			contacts,
+			suffixDigits
+		};
+	}
+	close() {
+		for (const s of this.shards) try {
+			s.db.close();
+		} catch {}
+	}
+};
+const introspect = (db) => {
+	const recordColumns = new Set(columnsOf(db, "ZABCDRECORD"));
+	for (const t of REQUIRED) if (recordColumns.size === 0) throw new SchemaDriftError(`This Contacts store has no ${t} table. It was probed on macOS ${PROBED_MACOS} with schema fingerprint ${PROBED_FINGERPRINT} (a PROBE fingerprint — compare it against another probe run, not against the one diagnostics reports); re-run \`pnpm probe:contacts\` to see what changed.`);
+	let contactEntities = [];
+	try {
+		contactEntities = db.prepare(`SELECT Z_ENT AS ent, Z_NAME AS name FROM Z_PRIMARYKEY`).all().filter((r) => CONTACT_ENTITIES.test(r.name)).map((r) => Number(r.ent));
+	} catch {
+		contactEntities = [];
+	}
+	const phoneColumns = new Set(columnsOf(db, "ZABCDPHONENUMBER"));
+	const emailColumns = new Set(columnsOf(db, "ZABCDEMAILADDRESS"));
+	return {
+		fingerprint: fingerprintSchema(db),
+		recordColumns,
+		phoneColumns,
+		emailColumns,
+		contactEntities,
+		hasPhones: phoneColumns.size > 0,
+		hasEmails: emailColumns.size > 0,
+		hasNotes: columnsOf(db, "ZABCDNOTE").length > 0,
+		epochOffset: CORE_DATA_EPOCH_OFFSET
+	};
+};
+/** Count the people in one opened shard, with the entity filter applied. */
+const countContacts = (db, caps) => {
+	const where = caps.contactEntities.length ? `WHERE "Z_ENT" IN (${caps.contactEntities.join(", ")})` : "";
+	try {
+		const row = db.prepare(`SELECT COUNT(*) AS c FROM "ZABCDRECORD" ${where}`).get();
+		return Number(row.c ?? 0);
+	} catch {
+		return 0;
+	}
+};
+const openShard = (path, label, mode, logger) => {
+	try {
+		const { db, mode: used, validated } = openReadOnly(path, mode, {
+			label: "Contacts store",
+			envVar: "APPLE_CONTACTS_INDEX_MODE",
+			validate: introspect,
+			fatal: (err) => err instanceof SchemaDriftError,
+			onFallback: () => logger?.debug?.("opened a Contacts store with immutable=1, which skips the write-ahead log — very recent edits may be missing until Contacts checkpoints.")
+		});
+		return {
+			db,
+			mode: used,
+			caps: validated,
+			path,
+			label,
+			contacts: countContacts(db, validated)
+		};
+	} catch (err) {
+		if (err instanceof SchemaDriftError) throw err;
+		logger?.debug?.(`skipped Contacts store ${label}: ${String(err)}`);
+		return null;
+	}
+};
+//#endregion
+//#region src/client/contacts.ts
+var AppleContactsClient = class {
+	#config;
+	#logger;
+	#home;
+	#runner;
+	#located = null;
+	#index = null;
+	#indexTried = false;
+	#lookup = null;
+	constructor(opts) {
+		this.#config = opts.config;
+		this.#logger = opts.logger;
+		this.#home = opts.home;
+		this.#runner = opts.osascript ?? createOsascriptRunner({
+			surface: CONTACTS_SURFACE,
+			osascriptPath: opts.config.osascriptPath,
+			timeoutMs: opts.config.osascriptTimeoutMs,
+			...opts.logger ? { logger: opts.logger } : {}
+		});
+	}
+	get config() {
+		return this.#config;
+	}
+	located() {
+		this.#located ??= locateStores({
+			storePath: this.#config.storePath,
+			...this.#home ? { home: this.#home } : {}
+		});
+		return this.#located;
+	}
+	/**
+	* Open every readable store, once.
+	*
+	* `indexMode: "off"` is honoured as a hard no — it is what the test suite uses
+	* so that a machine WITH the grant does not silently read the developer's own
+	* address book and pass or fail on data nobody wrote.
+	*/
+	index() {
+		if (this.#indexTried) return this.#index;
+		this.#indexTried = true;
+		if (this.#config.indexMode === "off") return null;
+		const located = this.located();
+		const mode = this.#config.indexMode === "auto" ? "ro" : this.#config.indexMode;
+		const shards = [];
+		for (const candidate of located.readable) {
+			const shard = openShard(candidate.path, candidate.label, mode, this.#logger);
+			if (shard) shards.push(shard);
+		}
+		this.#index = shards.length ? new ContactsIndex(shards) : null;
+		return this.#index;
+	}
+	/**
+	* The index, or an error naming what is wrong.
+	*
+	* Never `[]`. An empty list is the answer to "you have no contacts", and this
+	* surface has exactly one way to produce that answer wrongly — reading the
+	* root store and finding one person in it. Callers get a reason instead.
+	*/
+	#require() {
+		const index = this.index();
+		if (index) return index;
+		if (this.#config.indexMode === "off") throw new IndexUnavailableError("The Contacts index is disabled (APPLE_CONTACTS_INDEX_MODE=off). This server has no other lane, so nothing can be read until it is re-enabled.");
+		throw new ContactsUnavailableError(this.located().reason ?? "No readable Contacts store was found.");
+	}
+	list(limit) {
+		return this.#require().list(limit ?? this.#config.maxResults);
+	}
+	search(query, limit) {
+		return this.#require().search(query, limit ?? this.#config.maxResults);
+	}
+	/** One contact with its phone numbers and email addresses. */
+	get(source, recordPk) {
+		const index = this.#require();
+		const contact = index.byPk(source, recordPk);
+		if (!contact) return null;
+		return {
+			...contact,
+			phones: index.phonesFor(source, [recordPk]).map(({ value, label }) => ({
+				value,
+				label
+			})),
+			emails: index.emailsFor(source, [recordPk]).map(({ value, label }) => ({
+				value,
+				label
+			}))
+		};
+	}
+	/**
+	* Built on first use and kept.
+	*
+	* Walking every contact and every phone row is cheap once (970 rows on the
+	* probed store) and pointless per call. There is no TTL: this process does not
+	* write to Contacts, and a server that has been running while the user edited
+	* their address book is not the case worth optimising for. `diagnostics`
+	* reports when it was built.
+	*/
+	lookup() {
+		this.#lookup ??= this.#require().buildLookup(this.#config.phoneSuffixDigits);
+		return this.#lookup;
+	}
+	/** The function `packages/messages` is meant to call. */
+	resolve(handles) {
+		const results = resolveHandles(handles, this.lookup());
+		return {
+			results,
+			summary: summarise(results)
+		};
+	}
+	async #run(scriptText, params) {
+		try {
+			return await withBusyRetry(() => this.#runner.run(scriptText, params));
+		} catch (err) {
+			const code = err?.details?.code;
+			const message = err instanceof Error ? err.message : String(err);
+			if (code === "CONTACT_NOT_FOUND") throw new ContactNotFoundError(message);
+			if (code === "CREATE_NOT_PERSISTED" || code === "UPDATE_NOT_PERSISTED") throw new ContactWriteNotPersistedError(message);
+			throw err;
+		}
+	}
+	/**
+	* Invalidate the read lane after a write.
+	*
+	* The index and the resolver lookup are both built once and kept, so a contact
+	* created through Apple Events would otherwise stay invisible to `resolve` for
+	* the life of the process — the exact "wrote it, cannot find it" confusion the
+	* id bridge exists to prevent.
+	*/
+	#invalidate() {
+		this.#index?.close();
+		this.#index = null;
+		this.#lookup = null;
+		this.#indexTried = false;
+	}
+	#shapeWrite(data) {
+		const personId = typeof data.id === "string" ? data.id : null;
+		const shaped = (key) => Array.isArray(data[key]) ? data[key].map((r) => ({
+			label: typeof r.label === "string" ? r.label : null,
+			value: typeof r.value === "string" ? r.value : null
+		})) : [];
+		return {
+			ref: null,
+			personId,
+			name: typeof data.name === "string" ? data.name : null,
+			organization: typeof data.organization === "string" ? data.organization : null,
+			phones: shaped("phones"),
+			emails: shaped("emails"),
+			source: "apple-events"
+		};
+	}
+	async createContact(input) {
+		const data = await this.#run(CREATE_CONTACT, {
+			fields: input.fields,
+			phones: input.phones ?? [],
+			emails: input.emails ?? [],
+			allowLaunch: true
+		});
+		this.#invalidate();
+		return this.#shapeWrite(data);
+	}
+	async updateContact(input) {
+		const data = await this.#run(UPDATE_CONTACT, {
+			personId: input.personId,
+			fields: input.fields,
+			phones: input.phones ?? [],
+			emails: input.emails ?? [],
+			allowLaunch: true
+		});
+		this.#invalidate();
+		return this.#shapeWrite(data);
+	}
+	status() {
+		const index = this.index();
+		return {
+			located: this.located(),
+			shards: (index?.shards ?? []).map((s) => ({
+				label: s.label,
+				path: s.path,
+				mode: s.mode,
+				contacts: s.contacts,
+				fingerprint: s.caps.fingerprint
+			})),
+			totalContacts: index?.totalContacts ?? 0,
+			indexMode: this.#config.indexMode
+		};
+	}
+	close() {
+		this.#index?.close();
+		this.#index = null;
+		this.#lookup = null;
+		this.#indexTried = false;
+	}
+};
+//#endregion
+//#region src/client/ref.ts
+/**
+* `k1:<account>/<recordPk>` — an opaque handle for one contact.
+*
+* ## Why the account rides along
+*
+* Because the store is plural. A record's `Z_PK` is a rowid, and rowids are only
+* unique WITHIN one database — the root store and each account store number
+* their rows from 1 independently. A bare pk would therefore resolve to a
+* different person depending on which store happened to be read first, which is
+* the kind of bug that produces a plausible wrong answer rather than an error.
+*
+* ## Why not `ZUNIQUEID`
+*
+* It exists and is stable, but it is not what the child tables join on —
+* `ZABCDPHONENUMBER.ZOWNER` points at `Z_PK`. Carrying the pk means a `get`
+* needs no extra lookup, and the account prefix supplies the uniqueness the pk
+* lacks. `uniqueId` is still returned on results for callers that want a
+* durable identity across a re-index.
+*
+* ## Why `k1`
+*
+* `c1:` is Calendar's and `r1:` is Reminders'; `k1` is free and the version
+* prefix keeps a future scheme change additive rather than a silent
+* reinterpretation of refs already sitting in a conversation.
+*/
+const REF_VERSION = "k1";
+/**
+* An account label can contain almost anything — it is a directory name, and on
+* the probed machine a UUID — so the pk is anchored as the tail and the label is
+* whatever precedes the last `/`. Splitting on the FIRST separator would break
+* on any label containing one.
+*/
+const REF_PATTERN = /^k1:(.+)\/(\d+)$/;
+var InvalidContactRefError = class extends AppleAutomationError {
+	name = "InvalidContactRefError";
+	constructor(raw) {
+		super(`"${raw}" is not a contact ref. Refs come from apple_contacts_search_contacts or apple_contacts_list_contacts and look like "k1:<account>/<id>" — they are opaque and must not be constructed by hand.` + (raw.startsWith("c1:") || raw.startsWith("r1:") ? " That one belongs to another surface: \"c1:\" refs are Calendar events and \"r1:\" refs are Reminders." : ""), { ref: raw });
+	}
+};
+const encodeRef = (source, recordPk) => `k1:${source}/${recordPk}`;
+const decodeRef = (raw) => {
+	const m = REF_PATTERN.exec(raw.trim());
+	if (!m) throw new InvalidContactRefError(raw);
+	const recordPk = Number(m[2]);
+	if (!Number.isSafeInteger(recordPk) || recordPk <= 0) throw new InvalidContactRefError(raw);
+	return {
+		source: m[1],
+		recordPk
+	};
+};
+//#endregion
+//#region src/config.ts
+/**
+* Configuration is environment-only — this server holds no secret at all, its
+* access is the macOS permission the user granted.
+*
+* Note what is ABSENT, and why:
+*
+* - **No `allowWrites` behaviour.** It is inherited from `BaseConfigSchema` and
+*   deliberately ignored: this surface registers no mutating tool, so there is
+*   nothing for the flag to gate. Editing someone's address book from a tool
+*   call was never part of what Contacts was probed for.
+* - **No `osascript` settings in use.** Also inherited, also unused — there is
+*   no Apple Events lane here at all, which is what lets this server run without
+*   an Automation grant.
+* - **No account allowlist.** Contacts are unioned across accounts precisely so
+*   that a handle resolves wherever its owner lives; scoping that by account
+*   would reintroduce the bug this surface exists to avoid.
+*/
+const ConfigSchema = BaseConfigSchema.extend({
+	/**
+	* Explicit store path. Bypasses discovery — for tests and forensic copies.
+	*
+	* Naming one file also DISABLES the union, which is the point of having it:
+	* a test needs a single known database, not whatever the machine happens to
+	* hold.
+	*/
+	storePath: z.string().optional(),
+	indexMode: z.enum([
+		"auto",
+		"ro",
+		"immutable",
+		"off"
+	]).default("auto"),
+	/**
+	* Trailing digits that make a phone key.
+	*
+	* Exposed because the right value is a fact about the user's country, and nine
+	* was measured on one machine with mostly French and E.164 numbers. Lower is
+	* more forgiving and collides more; the ambiguity count in `diagnostics` is
+	* how to tell whether a change helped.
+	*/
+	phoneSuffixDigits: z.number().int().min(6).max(15).default(9)
+}).strict();
+const loadConfig = (env = process.env) => parseConfig(ConfigSchema, {
+	allowWrites: parseBool(env.APPLE_CONTACTS_ALLOW_WRITES),
+	debug: parseBool(env.APPLE_CONTACTS_DEBUG),
+	storePath: trimmed(env.APPLE_CONTACTS_STORE),
+	indexMode: trimmed(env.APPLE_CONTACTS_INDEX_MODE),
+	phoneSuffixDigits: parseIntOpt(env.APPLE_CONTACTS_PHONE_SUFFIX_DIGITS),
+	osascriptPath: trimmed(env.APPLE_CONTACTS_OSASCRIPT_PATH),
+	osascriptTimeoutMs: parseIntOpt(env.APPLE_CONTACTS_OSASCRIPT_TIMEOUT_MS),
+	maxResults: parseIntOpt(env.APPLE_CONTACTS_MAX_RESULTS)
+});
+//#endregion
+//#region src/tools/actions.ts
+/**
+* The mutating tools. Registered only when `allowWrites` is on, and never
+* merely refused — an MCP client caches the tool list, so a tool that exists and
+* says no is a tool the model will keep trying.
+*
+* Two verbs, because the dictionary has two. There is no `delete_contacts`:
+* `sdef /System/Applications/Contacts.app` contains no delete command of any
+* kind, and writes go through Apple Events on every surface here because the
+* store is opened `PRAGMA query_only`. See `client/jxa/core.ts`.
+*/
+const labelledValue = z.object({
+	label: z.string().optional().describe("Which kind, e.g. \"mobile\", \"home\", \"work\". Defaults to mobile for phones."),
+	value: z.string().min(1)
+});
+const fields = {
+	firstName: z.string().nullable().optional(),
+	lastName: z.string().nullable().optional(),
+	nickname: z.string().nullable().optional(),
+	organization: z.string().nullable().optional(),
+	jobTitle: z.string().nullable().optional(),
+	department: z.string().nullable().optional(),
+	note: z.string().nullable().optional(),
+	company: z.boolean().optional().describe("True for an organisation rather than a person — Contacts shows it differently.")
+};
+const registerActionTools = (server, client) => {
+	server.registerTool("apple_contacts_create_contact", {
+		description: "Create a new contact in the address book. This is a real card in the user's real Contacts, and on an iCloud account it syncs to their other devices within seconds. Give at least one of firstName, lastName or organization. Contacts keeps edits in an unsaved buffer and its save command commits EVERYTHING pending, so this also saves any edit someone has half-typed in the Contacts window. That is how the app's scripting works, not a choice this server makes. The result is re-read after saving, so what comes back is what Contacts stored rather than what was asked for.",
+		inputSchema: {
+			...fields,
+			phones: z.array(labelledValue).optional(),
+			emails: z.array(labelledValue).optional()
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ phones, emails, ...rest }) => wrap(async () => {
+		if (!rest.firstName && !rest.lastName && !rest.organization) return fail("A contact needs at least one of firstName, lastName or organization — Contacts will otherwise create a nameless card that is hard to find again.");
+		return ok(await client.createContact({
+			fields: rest,
+			...phones ? { phones } : {},
+			...emails ? { emails } : {}
+		}));
+	}));
+	server.registerTool("apple_contacts_update_contact", {
+		description: "Change an existing contact, or add a phone number or email address to one. Omitting a field leaves it alone; passing null clears it. Phones and emails are ADDED, never replaced — Contacts models them as separate objects, and there is no way to remove one through its scripting dictionary. Contacts keeps edits in an unsaved buffer and its save command commits EVERYTHING pending, so this also saves any edit someone has half-typed in the Contacts window. That is how the app's scripting works, not a choice this server makes. The result is re-read after saving, so what comes back is what Contacts stored rather than what was asked for.",
+		inputSchema: {
+			ref: z.string().min(1).describe("A contact ref from a search or resolve result (looks like \"k1:<account>/<id>\"). Do not construct one by hand."),
+			...fields,
+			phones: z.array(labelledValue).optional().describe("Added to whatever is already there."),
+			emails: z.array(labelledValue).optional().describe("Added to whatever is already there.")
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ ref, phones, emails, ...rest }) => wrap(async () => {
+		const decoded = decodeRef(ref);
+		const contact = client.get(decoded.source, decoded.recordPk);
+		if (!contact) return fail(`No contact for ref "${ref}". It was probably deleted, or the account holding it was removed, since the search ran. Re-run the search to get a current ref.`);
+		if (!contact.uniqueId) return fail(`The contact "${contact.displayName}" has no stable identifier in the address book database, so it cannot be addressed through Contacts' scripting interface. Edit it in Contacts.app instead.`);
+		return ok(await client.updateContact({
+			personId: contact.uniqueId,
+			fields: rest,
+			...phones ? { phones } : {},
+			...emails ? { emails } : {}
+		}));
+	}));
+};
+//#endregion
+//#region src/tools/contacts.ts
+/**
+* NOTE ON `async` BELOW: core's `wrap` is typed `() => Promise<T>` because most
+* surfaces reach Apple Events. Contacts reads synchronous SQLite and never
+* leaves the process, so the thunks are marked async here rather than widening a
+* shared signature for every surface to accommodate one.
+*/
+const registerContactTools = (server, client) => {
+	server.registerTool("apple_contacts_search_contacts", {
+		description: "Search the address book by name, nickname or organisation. Returns a ref for each match, plus which account it came from — the same person can legitimately appear twice if they are in two accounts. Use apple_contacts_get_contact for phone numbers and email addresses.",
+		inputSchema: {
+			query: z.string().min(1).describe("Text to look for in names and organisations."),
+			limit: limitArg
+		},
+		annotations: { readOnlyHint: true }
+	}, async ({ query, limit }) => wrap(async () => client.search(query, limit).map((c) => ({
+		ref: encodeRef(c.source, c.recordPk),
+		name: c.displayName,
+		organization: c.organization,
+		jobTitle: c.jobTitle,
+		account: c.source
+	}))));
+	server.registerTool("apple_contacts_list_contacts", {
+		description: "List contacts across every account. This is the whole address book, so prefer apple_contacts_search_contacts when you are looking for someone specific.",
+		inputSchema: { limit: limitArg },
+		annotations: { readOnlyHint: true }
+	}, async ({ limit }) => wrap(async () => client.list(limit).map((c) => ({
+		ref: encodeRef(c.source, c.recordPk),
+		name: c.displayName,
+		organization: c.organization,
+		account: c.source
+	}))));
+	server.registerTool("apple_contacts_get_contact", {
+		description: "One contact in full: name, organisation, job title, every phone number and every email address, each with its label.",
+		inputSchema: { ref: z.string().min(1).describe("An opaque contact ref from a list or search result (looks like \"k1:<account>/<id>\"). Do not construct one by hand.") },
+		annotations: { readOnlyHint: true }
+	}, async ({ ref }) => wrap(async () => {
+		const decoded = decodeRef(ref);
+		const contact = client.get(decoded.source, decoded.recordPk);
+		if (!contact) return fail(`No contact for ref "${ref}". It was probably deleted, or the account holding it was removed, since the search ran. Re-run the search to get a current ref.`);
+		return ok({
+			ref,
+			name: contact.displayName,
+			firstName: contact.firstName,
+			lastName: contact.lastName,
+			nickname: contact.nickname,
+			organization: contact.organization,
+			jobTitle: contact.jobTitle,
+			account: contact.source,
+			isMe: contact.isMe,
+			phones: contact.phones,
+			emails: contact.emails
+		});
+	}));
+};
+//#endregion
+//#region src/tools/diagnostics.ts
+/**
+* What this server can currently do, and why not more.
+*
+* The caveats are the point. Two of them are specific to this surface and both
+* produce a plausible wrong answer rather than an error, which is exactly the
+* kind of thing a caller cannot discover for itself.
+*/
+const registerDiagnosticsTools = (server, client) => {
+	server.registerTool("apple_contacts_diagnostics", {
+		description: "Report which Contacts stores were opened, how many contacts each holds, and what this server cannot do. Start here when a lookup returns nothing.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => {
+		const status = client.status();
+		const located = status.located;
+		return {
+			server: {
+				name: BUILD_INFO.name,
+				version: BUILD_INFO.version
+			},
+			lane: {
+				reads: "file lane (read-only SQLite)",
+				writes: "none — this server registers no mutating tool",
+				appleEvents: "not used at all, so no Automation grant is needed or requested"
+			},
+			stores: {
+				directory: located.dirPath,
+				directoryListable: located.dirListable,
+				found: located.candidates.length,
+				opened: status.shards.length,
+				sourcesSeen: located.sourceCount,
+				totalContacts: status.totalContacts,
+				shards: status.shards,
+				indexMode: status.indexMode,
+				reason: located.reason
+			},
+			resolution: {
+				phoneSuffixDigits: client.config.phoneSuffixDigits,
+				note: "Phone matching uses the last N digits because Contacts stores numbers as typed. Fewer digits resolves more handles and collides more; the ambiguous count in a resolve result is how to tell whether a change helped."
+			},
+			caveats: [
+				"Contacts is protected by its own privacy permission, NOT by Full Disk Access, and unlike Full Disk Access macOS prompts for it. A store that cannot be opened usually means that prompt was dismissed — re-enable this app under System Settings > Privacy & Security > Contacts.",
+				"The address book is spread across several databases: one per account, plus a root store that is normally almost empty. All readable ones are unioned. If `opened` is lower than `found`, some accounts are missing from every answer here.",
+				"A handle that resolves to more than one contact is reported as ambiguous with no name, never as a guess. Putting the wrong name on a message is worse than putting none, because it does not look wrong.",
+				"Contacts held in two accounts are folded together on their link id, matching what Contacts.app shows as one unified card. A contact with no link id is not folded.",
+				"This server is read-only by construction. It cannot create, edit or delete a contact, and enabling writes does not add a tool."
+			]
+		};
+	}));
+};
+//#endregion
+//#region src/tools/resolve.ts
+/**
+* The tool this surface was built for.
+*
+* Everything else here is an ordinary address book server. This one exists
+* because `chat.db` — and a caller ID, and an email header — carries an
+* identifier and no name, and turning one into the other is the only thing on
+* this machine that can.
+*/
+const registerResolveTools = (server, client) => {
+	server.registerTool("apple_contacts_resolve_handles", {
+		description: "Turn phone numbers or email addresses into contact names. Give it the raw identifiers from somewhere else — Messages handles, a caller ID, an email header — and it returns one result per handle.\n\nRead `status` on every result rather than assuming a name came back:\n- \"resolved\" — exactly one contact. `name` is set.\n- \"unknown\" — nobody in the address book has this number. COMMON AND NOT AN ERROR: measured on a real store, about one in six of even the busiest correspondents does not resolve. Show the raw handle.\n- \"ambiguous\" — more than one contact has it, so no name is returned. Do not guess; `matches` says how many.\n- \"shortcode\" — a bank, a courier, a 2FA sender. Can never be a contact.\n\nPhone matching is by trailing digits, because Contacts stores numbers as typed (\"06 12 34 56 78\") while most systems hand you E.164 (\"+33612345678\"). Exact string matching resolves almost nothing and is not used.",
+		inputSchema: { handles: z.array(z.string().min(1)).min(1).max(500).describe("Phone numbers or email addresses, in any format — \"+33612345678\", \"06 12 34 56 78\" and \"user@example.com\" all work.") },
+		annotations: { readOnlyHint: true }
+	}, async ({ handles }) => wrap(async () => {
+		const { results, summary } = client.resolve(handles);
+		return {
+			summary,
+			results: results.map((r) => ({
+				handle: r.handle,
+				kind: r.kind,
+				status: r.status,
+				name: r.name,
+				matches: r.matches,
+				...r.contact ? {
+					ref: encodeRef(r.contact.source, r.contact.recordPk),
+					organization: r.contact.organization,
+					account: r.contact.source
+				} : {}
+			}))
+		};
+	}));
+};
+//#endregion
+//#region src/tools/index.ts
+/**
+* Register the Apple Contacts tools.
+*
+* READS are file-lane and ask for no Automation grant. WRITES are Apple Events,
+* always — the store is opened `PRAGMA query_only` because Contacts owns it and
+* reconciles it against iCloud, so writing to it would corrupt sync state.
+*
+* That split has a cost worth stating plainly: this surface used to need no
+* Automation grant at all, which docs/distribution.md calls the strongest
+* argument for file-first. Turning writes on gives that up — the first write
+* prompts for permission to control Contacts. With `allowWrites` off, nothing
+* here ever sends an Apple Event and the old property still holds.
+*
+* There is no delete. Contacts' scripting dictionary has no delete command of
+* any kind; see `client/jxa/core.ts` for the measurement.
+*
+* The registered set does NOT vary with whether the store is readable. That is a
+* runtime condition which can change while the process lives, and MCP clients
+* cache the tool list, so a tool that appeared and disappeared would leave
+* clients calling names the server no longer has. Tools that need the store
+* report what is missing instead.
+*/
+const registerTools = (server, client, ctx) => {
+	registerDiagnosticsTools(server, client);
+	registerContactTools(server, client);
+	registerResolveTools(server, client);
+	if (!ctx.allowWrites) return;
+	registerActionTools(server, client);
+};
+//#endregion
+//#region src/server.ts
+const SERVER_NAME = BUILD_INFO.name;
+const SERVER_VERSION = BUILD_INFO.version;
+/**
+* Build the server. Side-effect free: it opens no database and reads no file,
+* so a test can construct it freely and every external dependency arrives
+* through an option.
+*/
+const createServer = (opts) => {
+	const { config } = opts;
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	const client = new AppleContactsClient({
+		config,
+		...opts.logger ? { logger: opts.logger } : {},
+		...opts.osascript ? { osascript: opts.osascript } : {},
+		...opts.home ? { home: opts.home } : {}
+	});
+	registerTools(server, client, { allowWrites: config.allowWrites });
+	return {
+		server,
+		client
+	};
+};
+//#endregion
+export { AppleContactsError as A, isShortcode as C, STORE_FILENAME as D, SOURCES_DIRNAME as E, IndexUnavailableError$1 as F, SchemaDriftError$1 as I, BUILD_INFO as L, CONTACTS_SURFACE as M, ContactNotFoundError as N, defaultDirPath as O, ContactsUnavailableError as P, handleKind as S, ADDRESSBOOK_DIR as T, resolveHandles as _, loadConfig as a, digitsOf as b, decodeRef as c, ContactsIndex as d, countContacts as f, resolveHandle as g, openShard as h, registerTools as i, CONTACTS_BUNDLE_ID as j, locateStores as k, encodeRef as l, introspect as m, SERVER_VERSION as n, InvalidContactRefError as o, displayNameOf as p, createServer as r, REF_VERSION as s, SERVER_NAME as t, AppleContactsClient as u, summarise as v, suffixKey as w, emailKey as x, SUFFIX_DIGITS as y };
+
+//# sourceMappingURL=server-BjWSCaMN.js.map