@mgcrea/mcp-apple-contacts 0.0.0-bootstrap

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olivier Louvignes <olivier@mgcrea.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @mgcrea/mcp-apple-contacts
+
+Model Context Protocol server for the macOS **Apple Contacts** address book.
+
+> **Unofficial.** Not affiliated with Apple. It reads the address book already on your Mac.
+
+## Why it exists: resolving handles
+
+`apple_contacts_resolve_handles` turns phone numbers and email addresses into names, in batches of up
+to 500. Everything else here is in service of that.
+
+This is the surface where the file-lane rule is about **capability, not speed**. Contacts' scripting
+dictionary answers in ~65 ms — comfortably fast, and still useless for this: resolving a phone number
+means a suffix-keyed index over every stored number, and no quantity of Apple Events round trips
+produces one. So reads go through read-only SQLite, and there is no Apple Events read lane.
+
+The lookup builds in **3 ms** over 947 phone keys and 295 email keys, then is kept for the life of
+the process.
+
+## Permissions — this one is different
+
+| Permission                | Needed for  | Notes                                          |
+| ------------------------- | ----------- | ---------------------------------------------- |
+| **Contacts** (its own)    | reads       | **prompts** — answer the dialog, and that's it |
+| **Automation → Contacts** | writes only | reads are unaffected                           |
+
+Contacts fails differently from every other surface in this family: 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 nothing here
+asks you to hand over whole-disk access for an address book.
+
+## Tools
+
+Read: `diagnostics`, `resolve_handles`, `search_contacts`, `list_contacts`, `get_contact`.
+
+Write, registered **only** when `APPLE_CONTACTS_ALLOW_WRITES=1` — with the flag off they are
+invisible to the model, not merely refused: `create_contact`, `update_contact`.
+
+`resolveHandles()` is also exported from the package root, for callers already inside Node that
+would rather not go through MCP to reach it.
+
+## Configuration
+
+| Variable                              | Default |                                            |
+| ------------------------------------- | ------- | ------------------------------------------ |
+| `APPLE_CONTACTS_ALLOW_WRITES`         | off     | Register the mutating tools.               |
+| `APPLE_CONTACTS_PHONE_SUFFIX_DIGITS`  | `9`     | Suffix key length; 6–15.                   |
+| `APPLE_CONTACTS_INDEX_MODE`           | `auto`  | `auto` \| `ro` \| `immutable` \| `off`.    |
+| `APPLE_CONTACTS_STORE`                | auto    | Explicit store path.                       |
+| `APPLE_CONTACTS_OSASCRIPT_TIMEOUT_MS` | `30000` | Sized for the first-run permission prompt. |
+
+## Notes that will bite you
+
+- **The store is plural.** `locate.ts` returns a list and every query fans out — on a real machine,
+  `stores=2/2, contacts=421`, matching Apple Events exactly. A server reading only the first store
+  silently loses an account.
+- **Nine-digit suffix keys, and the length travels inside the lookup object** so the index and the
+  query cannot diverge. A self-join over a real address book at 7, 9 and 10 digits settles it: 7 and
+  9 collide identically (10 of 947 keys, 1.1%), and 10 drops a key while losing the
+  national-to-E.164 join.
+- **Ambiguity is a status, never a guess** — `resolved` / `unknown` / `ambiguous` / `shortcode`.
+  `unknown` is documented in the tool description as expected, not as an error.
+- **`Z_ENT` filters to `ABCDContact`.** Without it, a list tool returns your groups as people.
+- **A write can succeed and still not persist.** Contacts holds changes in an unsaved buffer, so a
+  mutation can read back correctly inside the same script and never reach the store. Every write
+  script saves and then re-reads.
+
+## Licence
+
+[MIT](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { L as BUILD_INFO, M as CONTACTS_SURFACE, a as loadConfig, r as createServer } from "./server-BjWSCaMN.js";
+import { runStdioServer } from "@mgcrea/mcp-apple-core";
+//#region src/cli.ts
+const LOG_PREFIX = "apple-contacts-mcp";
+runStdioServer({
+	build: BUILD_INFO,
+	surface: CONTACTS_SURFACE,
+	logPrefix: LOG_PREFIX,
+	start: async (logger) => {
+		const config = loadConfig();
+		const { server, client } = createServer({
+			config,
+			logger
+		});
+		const status = client.status();
+		return {
+			server,
+			banner: `read-only, stores=${status.shards.length}/${status.located.candidates.length}, contacts=${status.totalContacts}, suffix=${config.phoneSuffixDigits}, index=${config.indexMode}`
+		};
+	}
+}).catch((err) => {
+	console.error(`[${LOG_PREFIX}] fatal:`, err);
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { runStdioServer } from \"@mgcrea/mcp-apple-core\";\n\nimport { BUILD_INFO } from \"./build-info.js\";\nimport { CONTACTS_SURFACE } from \"./client/errors.js\";\nimport { loadConfig } from \"./config.js\";\nimport { createServer } from \"./server.js\";\n\nconst LOG_PREFIX = \"apple-contacts-mcp\";\n\nrunStdioServer({\n  build: BUILD_INFO,\n  surface: CONTACTS_SURFACE,\n  logPrefix: LOG_PREFIX,\n  start: async (logger) => {\n    const config = loadConfig();\n    const { server, client } = createServer({ config, logger });\n    const status = client.status();\n    return {\n      server,\n      // No writes= line: this surface has no mutating tool, and printing a flag\n      // that gates nothing would imply one exists.\n      banner:\n        `read-only, ` +\n        `stores=${status.shards.length}/${status.located.candidates.length}, ` +\n        `contacts=${status.totalContacts}, ` +\n        `suffix=${config.phoneSuffixDigits}, ` +\n        `index=${config.indexMode}`,\n    };\n  },\n}).catch((err: unknown) => {\n  console.error(`[${LOG_PREFIX}] fatal:`, err);\n  process.exit(1);\n});\n"],"mappings":";;;;AAQA,MAAM,aAAa;AAEnB,eAAe;CACb,OAAO;CACP,SAAS;CACT,WAAW;CACX,OAAO,OAAO,WAAW;EACvB,MAAM,SAAS,WAAW;EAC1B,MAAM,EAAE,QAAQ,WAAW,aAAa;GAAE;GAAQ;EAAO,CAAC;EAC1D,MAAM,SAAS,OAAO,OAAO;EAC7B,OAAO;GACL;GAGA,QACE,qBACU,OAAO,OAAO,OAAO,GAAG,OAAO,QAAQ,WAAW,OAAO,aACvD,OAAO,cAAc,WACvB,OAAO,kBAAkB,UAC1B,OAAO;EACpB;CACF;AACF,CAAC,CAAC,CAAC,OAAO,QAAiB;CACzB,QAAQ,MAAM,IAAI,WAAW,WAAW,GAAG;CAC3C,QAAQ,KAAK,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+import { AppleAutomationError, AppleAutomationError as AppleContactsError, BuildInfo, IndexUnavailableError, Logger, OsascriptRunner, ReadOnlyMode, SchemaDriftError, StoreFacts, SurfaceContext } from "@mgcrea/mcp-apple-core";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DatabaseSync } from "node:sqlite";
+//#region src/build-info.d.ts
+declare const BUILD_INFO: BuildInfo;
+//#endregion
+//#region src/config.d.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.
+ */
+declare const ConfigSchema: z.ZodObject<{
+  allowWrites: z.ZodDefault<z.ZodBoolean>;
+  debug: z.ZodDefault<z.ZodBoolean>;
+  osascriptPath: z.ZodDefault<z.ZodString>;
+  osascriptTimeoutMs: z.ZodDefault<z.ZodNumber>;
+  maxResults: z.ZodDefault<z.ZodNumber>;
+  storePath: z.ZodOptional<z.ZodString>;
+  indexMode: z.ZodDefault<z.ZodEnum<{
+    auto: "auto";
+    immutable: "immutable";
+    off: "off";
+    ro: "ro";
+  }>>;
+  phoneSuffixDigits: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type Config = z.infer<typeof ConfigSchema>;
+declare const loadConfig: (env?: NodeJS.ProcessEnv) => Config;
+//#endregion
+//#region src/client/locate.d.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`. */
+declare const ADDRESSBOOK_DIR: string;
+/** The per-account subdirectory. Each child holds one database. */
+declare const SOURCES_DIRNAME = "Sources";
+/** Constant on every store, root and source alike. */
+declare const STORE_FILENAME = "AddressBook-v22.abcddb";
+type StoreCandidate = StoreFacts & {
+  path: string;
+  /** `root` for the top-level database, else the source directory name. */
+  label: string;
+};
+type LocateResult = {
+  dirPath: string;
+  dirListable: boolean;
+  /** Every store-shaped file found, root first. */
+  candidates: StoreCandidate[];
+  /** The subset that can actually be opened. May be empty. */
+  readable: StoreCandidate[];
+  /** How many `Sources/*` directories were seen, readable or not. */
+  sourceCount: number;
+  reason: string | null;
+};
+declare const defaultDirPath: (home?: string) => string;
+declare const locateStores: (opts?: {
+  storePath?: string | undefined;
+  home?: string;
+}) => LocateResult;
+//#endregion
+//#region src/client/phone.d.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. */
+declare const digitsOf: (value: string) => string;
+/**
+ * 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.
+ */
+declare const SUFFIX_DIGITS = 9;
+declare const isShortcode: (value: string) => boolean;
+/**
+ * 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.
+ */
+declare const suffixKey: (value: string, digits?: number) => string | null;
+/** Email keys are simply case-folded. Measured: 37 of 60 resolve, none ambiguous. */
+declare const emailKey: (value: string) => string;
+type HandleKind = "phone" | "email" | "shortcode";
+/**
+ * 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 `@`.
+ */
+declare const handleKind: (handle: string) => HandleKind;
+//#endregion
+//#region src/client/store.d.ts
+type StoreCapabilities = {
+  fingerprint: string;
+  recordColumns: Set<string>;
+  phoneColumns: Set<string>;
+  emailColumns: Set<string>;
+  /** `Z_ENT` values that mean a person. Empty means the filter could not be built. */
+  contactEntities: number[];
+  hasPhones: boolean;
+  hasEmails: boolean;
+  hasNotes: boolean;
+  epochOffset: number;
+};
+type IndexContact = {
+  recordPk: number;
+  /** Stable across runs; the ref is built from it. */
+  uniqueId: string | null;
+  firstName: string | null;
+  lastName: string | null;
+  nickname: string | null;
+  organization: string | null;
+  jobTitle: string | null;
+  /** Assembled below — never a raw column, because no single column holds it. */
+  displayName: string;
+  /** Which store this came from, so a duplicate across accounts is explicable. */
+  source: string;
+  linkId: number | null;
+  isMe: boolean;
+};
+type ContactPhone = {
+  recordPk: number;
+  value: string;
+  label: string | null;
+};
+type ContactEmail = {
+  recordPk: number;
+  value: string;
+  label: string | 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.
+ */
+declare const displayNameOf: (c: {
+  firstName: string | null;
+  lastName: string | null;
+  nickname: string | null;
+  organization: string | null;
+}) => string;
+/** One opened database, with what was learned about it. */
+type Shard = {
+  db: DatabaseSync;
+  mode: string;
+  caps: StoreCapabilities;
+  path: string;
+  label: string;
+  contacts: number;
+};
+declare class ContactsIndex {
+  #private;
+  readonly shards: readonly Shard[];
+  constructor(shards: readonly Shard[]);
+  /** Every shard's fingerprint. More than one distinct value is worth showing. */
+  get fingerprints(): string[];
+  get totalContacts(): number;
+  /** Every contact, across every shard. */
+  list(limit: number): IndexContact[];
+  /**
+   * 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: string, limit: number): IndexContact[];
+  byPk(shardLabel: string, recordPk: number): IndexContact | null;
+  phonesFor(shardLabel: string, recordPks: readonly number[]): ContactPhone[];
+  emailsFor(shardLabel: string, recordPks: readonly number[]): ContactEmail[];
+  /**
+   * 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?: number): HandleLookup;
+  close(): void;
+}
+type HandleLookup = {
+  /** Phone suffix → the contacts carrying it. Key length is `suffixDigits`. */
+  byPhone: Map<string, Set<string>>;
+  /** Case-folded address → the contacts carrying it. */
+  byEmail: Map<string, Set<string>>;
+  /** `"<shard>:<pk>"` → the contact. */
+  contacts: Map<string, IndexContact>;
+  /** How the phone keys were built. Queries MUST use the same length. */
+  suffixDigits: number;
+};
+declare const introspect: (db: DatabaseSync) => StoreCapabilities;
+/** Count the people in one opened shard, with the entity filter applied. */
+declare const countContacts: (db: DatabaseSync, caps: StoreCapabilities) => number;
+declare const openShard: (path: string, label: string, mode: ReadOnlyMode, logger?: Logger) => Shard | null;
+//#endregion
+//#region src/client/resolve.d.ts
+/**
+ * Turn Messages handles into names.
+ *
+ * This is the function `packages/messages` exists to call, and the reason
+ * Contacts was probed at all: `chat.db` records a correspondent as
+ * `+15551234567` and nothing else, so a Messages server without this answers
+ * "+15551234567 said …", which is complete and useless.
+ *
+ * ## What the measurement says it must do
+ *
+ * `docs/contacts.md` measured resolution against a real 958-handle store two
+ * ways, and the gap between them is the whole design:
+ *
+ * | denominator                | resolved |
+ * | -------------------------- | -------- |
+ * | every handle ever seen     | 27.6%    |
+ * | messages in the last year  | 97.6%    |
+ * | the 25 busiest correspondents | 84%   |
+ *
+ * The first number is a fact about the address book — 321 handles sent exactly
+ * one message, ever — not about this resolver. The last one is the one that
+ * shapes the API: **about one in six of the busiest correspondents does not
+ * resolve.** So `unknown` is a normal, expected, first-class outcome. It is not
+ * an error, it must not throw, and a caller that treats it as a failure will be
+ * wrong several times on any real inbox.
+ */
+type ResolutionStatus =
+/** Exactly one contact carries this handle. */
+"resolved" |
+/** Nobody does. Normal — see above. */
+"unknown" |
+/**
+ * More than one distinct contact does.
+ *
+ * Reported rather than resolved by picking a winner. Six handles collided at
+ * nine digits on the probed store, and the failure mode of guessing is putting
+ * one person's name on another person's messages — which is worse than no name
+ * at all, because it is not visibly wrong.
+ */
+"ambiguous" |
+/** A shortcode: a bank, a courier, a 2FA sender. Can never be a contact. */
+"shortcode";
+type ResolvedHandle = {
+  handle: string;
+  kind: HandleKind;
+  status: ResolutionStatus;
+  /** The name to show. Null unless `status` is `resolved`. */
+  name: string | null;
+  contact: IndexContact | null;
+  /** How many distinct contacts matched. 0, 1, or more. */
+  matches: number;
+};
+declare const resolveHandle: (handle: string, lookup: HandleLookup) => ResolvedHandle;
+declare const resolveHandles: (handles: readonly string[], lookup: HandleLookup) => ResolvedHandle[];
+/** Counts by status, for a caller that wants to report coverage honestly. */
+declare const summarise: (results: readonly ResolvedHandle[]) => Record<ResolutionStatus, number>;
+//#endregion
+//#region src/client/contacts.d.ts
+/**
+ * Contacts' one lane, orchestrated.
+ *
+ * There is no lane *choice* here, which is what makes this the smallest client
+ * in the repo: no Apple Events fallback, no write path, no cache TTL. What it
+ * does own is the two things the store is awkward about — opening several
+ * databases instead of one, and building the resolver index lazily, because
+ * building it walks every contact and every phone row and most callers only
+ * want to list a few names.
+ */
+type CreateClientOptions = {
+  config: Config;
+  logger?: Logger;
+  /** Injected by tests so nothing spawns a process or touches real Contacts. */
+  osascript?: OsascriptRunner;
+  /** Injected by tests. */
+  home?: string;
+};
+/** The scalar fields a write may set. Absent means "leave alone". */
+type ContactFields = {
+  firstName?: string | null;
+  lastName?: string | null;
+  nickname?: string | null;
+  organization?: string | null;
+  jobTitle?: string | null;
+  department?: string | null;
+  note?: string | null;
+  company?: boolean;
+};
+type LabelledValue = {
+  label?: string;
+  value: string;
+};
+/** What a write reports: what Contacts stored, re-read after the save. */
+type WriteResult = {
+  ref: string | null;
+  personId: string | null;
+  name: string | null;
+  organization: string | null;
+  phones: {
+    label: string | null;
+    value: string | null;
+  }[];
+  emails: {
+    label: string | null;
+    value: string | null;
+  }[];
+  source: "apple-events";
+};
+type LaneStatus = {
+  located: LocateResult;
+  /** One row per store that opened. */
+  shards: {
+    label: string;
+    path: string;
+    mode: string;
+    contacts: number;
+    fingerprint: string;
+  }[];
+  totalContacts: number;
+  indexMode: string;
+};
+type ContactDetail = IndexContact & {
+  phones: {
+    value: string;
+    label: string | null;
+  }[];
+  emails: {
+    value: string;
+    label: string | null;
+  }[];
+};
+declare class AppleContactsClient {
+  #private;
+  constructor(opts: CreateClientOptions);
+  get config(): Config;
+  located(): LocateResult;
+  /**
+   * 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(): ContactsIndex | null;
+  list(limit?: number): IndexContact[];
+  search(query: string, limit?: number): IndexContact[];
+  /** One contact with its phone numbers and email addresses. */
+  get(source: string, recordPk: number): ContactDetail | null;
+  /**
+   * 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(): HandleLookup;
+  /** The function `packages/messages` is meant to call. */
+  resolve(handles: readonly string[]): {
+    results: ResolvedHandle[];
+    summary: Record<string, number>;
+  };
+  createContact(input: {
+    fields: ContactFields;
+    phones?: readonly LabelledValue[];
+    emails?: readonly LabelledValue[];
+  }): Promise<WriteResult>;
+  updateContact(input: {
+    personId: string;
+    fields: ContactFields;
+    phones?: readonly LabelledValue[];
+    emails?: readonly LabelledValue[];
+  }): Promise<WriteResult>;
+  status(): LaneStatus;
+  close(): void;
+}
+//#endregion
+//#region src/client/errors.d.ts
+declare const CONTACTS_SURFACE: SurfaceContext;
+/**
+ * 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.
+ */
+declare const CONTACTS_BUNDLE_ID = "com.apple.AddressBook";
+/** A contact ref no longer resolves — deleted, or its account was removed. */
+declare class ContactNotFoundError extends AppleAutomationError {
+  readonly name = "ContactNotFoundError";
+  constructor(ref: string);
+}
+/**
+ * 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.
+ */
+declare class ContactsUnavailableError extends AppleAutomationError {
+  readonly name = "ContactsUnavailableError";
+  constructor(reason: string);
+}
+//#endregion
+//#region src/client/ref.d.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.
+ */
+declare const REF_VERSION = "k1";
+type ContactRef = {
+  source: string;
+  recordPk: number;
+};
+declare class InvalidContactRefError extends AppleAutomationError {
+  readonly name = "InvalidContactRefError";
+  constructor(raw: string);
+}
+declare const encodeRef: (source: string, recordPk: number) => string;
+declare const decodeRef: (raw: string) => ContactRef;
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_NAME: string;
+declare const SERVER_VERSION: string;
+type CreateServerOptions = {
+  config: Config;
+  logger?: Logger;
+  /** Injected by tests so nothing spawns a process or touches real Contacts. */
+  osascript?: OsascriptRunner;
+  /** Injected by tests so discovery never reaches the developer's real home. */
+  home?: string;
+};
+type CreatedServer = {
+  server: McpServer;
+  client: AppleContactsClient;
+};
+/**
+ * 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.
+ */
+declare const createServer: (opts: CreateServerOptions) => CreatedServer;
+//#endregion
+//#region src/tools/index.d.ts
+type ToolContext = {
+  /**
+   * Register the mutating tools too. Off by default — with the flag off they are
+   * not merely refused, they are invisible and cannot be called at all, because
+   * MCP clients cache the tool list and a tool that exists and says no is one
+   * the model will keep trying.
+   */
+  allowWrites: boolean;
+};
+/**
+ * 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.
+ */
+declare const registerTools: (server: McpServer, client: AppleContactsClient, ctx: ToolContext) => void;
+//#endregion
+export { ADDRESSBOOK_DIR, AppleContactsClient, AppleContactsError, BUILD_INFO, type BuildInfo, CONTACTS_BUNDLE_ID, CONTACTS_SURFACE, type Config, type ContactDetail, ContactNotFoundError, type ContactRef, ContactsIndex, ContactsUnavailableError, type CreateClientOptions, type CreateServerOptions, type HandleKind, type HandleLookup, type IndexContact, IndexUnavailableError, InvalidContactRefError, type LaneStatus, type LocateResult, REF_VERSION, type ResolutionStatus, type ResolvedHandle, SERVER_NAME, SERVER_VERSION, SOURCES_DIRNAME, STORE_FILENAME, SUFFIX_DIGITS, SchemaDriftError, type Shard, type StoreCandidate, type StoreCapabilities, type ToolContext, countContacts, createServer, decodeRef, defaultDirPath, digitsOf, displayNameOf, emailKey, encodeRef, handleKind, introspect, isShortcode, loadConfig, locateStores, openShard, registerTools, resolveHandle, resolveHandles, suffixKey, summarise };
+//# sourceMappingURL=index.d.ts.map