@mgcrea/mcp-apple-maps 1.15.0 → 1.16.0

package/README.md

@@ -20,20 +20,35 @@ from Maps' Core Data store.
 | `apple_maps_list_favorites`         | the places saved as favourites                         |
 | `apple_maps_list_collections`       | the Guides                                             |
 | `apple_maps_list_collection_places` | what is filed in one Guide                             |
+| `apple_maps_list_unfiled_places`    | saved places filed in no Guide                         |
 | `apple_maps_list_recents`           | where you have looked recently                         |
 | `apple_maps_search_places`          | all three at once, by name, label or address           |
 | `apple_maps_get_place`              | one place, by ref                                      |
 | `apple_maps_diagnostics`            | what opened, which columns resolved, what it cannot do |
 
+## What it writes
+
+Only with `APPLE_MAPS_ALLOW_WRITES=1`. Both are unregistered rather than refused when it is off, so a
+client that has not opted in is never told they exist.
+
+| Tool                         | What                                                      |
+| ---------------------------- | --------------------------------------------------------- |
+| `apple_maps_add_favorite`    | save a place as a favourite, seeding it through `maps://` |
+| `apple_maps_remove_favorite` | drop a favourite row                                      |
+
 ## What it does not do
 
 It reads what is **saved on this Mac**. It does not search Apple's map of the world, geocode an
 address, give directions or compute a travel time. Those are network calls to Apple's services,
 not data on your disk.
 
-It is also **read-only**, and that is a decision rather than a gap. The store is mirrored to iCloud
-by `NSPersistentCloudKitContainer`, so writing means editing one replica of a synchronising object
-graph underneath an app that is also editing it. That needs measuring before it needs shipping.
+It writes only **favourites**, and only with `APPLE_MAPS_ALLOW_WRITES` set. Everything else here is
+read-only. The store is mirrored to iCloud by `NSPersistentCloudKitContainer`, so a write is an edit
+to one replica of a synchronising object graph underneath a running app — a malformed row reaches
+every device on the account. That is why a place record is never fabricated: adding a favourite opens
+`maps://` so that Maps itself mints the record, and only then is it copied. **The place is left in
+your Recents whether or not you keep the favourite**, and resolving it over the network can take tens
+of seconds.
 
 ## Full Disk Access is mandatory
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as MAPS_SURFACE, N as BUILD_INFO, a as loadConfig, r as createServer } from "./server-CpYiHM_a.js";
+import { C as MAPS_SURFACE, N as BUILD_INFO, a as loadConfig, r as createServer } from "./server-ip7LF8Un.js";
 import { runStdioServer } from "@mgcrea/mcp-apple-core";
 //#region src/cli.ts
 const LOG_PREFIX = "apple-maps-mcp";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AppleAutomationError, AppleAutomationError as AppleMapsError, BuildInfo, CORE_DATA_EPOCH_OFFSET, FileFacts, IndexUnavailableError, Logger, ReadOnlyMode, SchemaDriftError, StoreFacts, SurfaceContext } from "@mgcrea/mcp-apple-core";
+import { AppleAutomationError, AppleAutomationError as AppleMapsError, BuildInfo, CORE_DATA_EPOCH_OFFSET, FileFacts, IndexUnavailableError, InterferenceWatch, Logger, ReadOnlyMode, SchemaDriftError, StoreFacts, SurfaceContext } from "@mgcrea/mcp-apple-core";
 import { DatabaseSync } from "node:sqlite";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -135,6 +135,110 @@ declare const ConfigSchema: z.ZodObject<{
 type Config = z.infer<typeof ConfigSchema>;
 declare const loadConfig: (env?: NodeJS.ProcessEnv) => Config;
 //#endregion
+//#region src/client/ax.d.ts
+type Guide = {
+  name: string;
+  places: number | null;
+};
+/** Injected so tests never shell out, matching `write.ts`'s `OpenUrl` seam. */
+type OpenUrl$1 = (url: string) => void;
+/**
+ * How long to wait for a card, a sheet or a picker.
+ *
+ * Overridable so a test can pin a "this never appeared" path without waiting for
+ * it. Ten seconds because a place has to resolve over the network before its
+ * card exists; sheets and pickers are local and get less.
+ */
+type Waits = {
+  card: number;
+  sheet: number;
+};
+declare class MapsAxLane {
+  #private;
+  private constructor();
+  /** Null when this server is not hosted by Cupertino — see `core/src/ax.ts`. */
+  static open(env?: NodeJS.ProcessEnv, openUrl?: OpenUrl$1, waits?: Partial<Waits>): MapsAxLane | null;
+  close(): void;
+  /** Start watching for someone using the Mac during a sequence. */
+  watch(): InterferenceWatch;
+  /**
+   * Open a place and wait for its card.
+   *
+   * The combined `q=` and `ll=` form, because a coordinate positions the map and
+   * a NAME selects a place — `write.ts` records the same thing for the same
+   * reason.
+   */
+  openCard(place: {
+    name: string;
+    latitude: number;
+    longitude: number;
+  }): Promise<boolean>;
+  /**
+   * Is this place saved?
+   *
+   * Read off `AddButton`'s NAME, which is the state bit. `docs/desktop.md`
+   * corrected itself on this: `FavoriteButton` reports identical attributes
+   * either way, and the sibling carries `"Add"` versus `"Added"`.
+   *
+   * Localised, and that is a real limit rather than an oversight — there is no
+   * unlocalised state anywhere on this card.
+   */
+  isSaved(): Promise<boolean | null>;
+  /**
+   * Save the open place into the Places library.
+   *
+   * Two presses, not one: `AddButton` raises a **"Name This Location"** sheet
+   * and nothing is written until its `Save` is pressed. The sheet REPLACES the
+   * window list — a full walk during it returns the sheet and nothing else — so
+   * the card's elements are unreachable until it closes, and `Save` carries no
+   * `AXIdentifier`, which is why it is addressed by name.
+   */
+  savePlace(): Promise<boolean>;
+  /**
+   * Remove the open place from the Places library.
+   *
+   * The menu item is `delete_from_places`, and it is only present when the place
+   * IS saved — the same slot carries `add_to_places` when it is not. So its
+   * absence is a state reading rather than a failure, and this reports which.
+   */
+  removePlace(): Promise<"removed" | "not-saved" | "no-menu">;
+  /**
+   * Every guide Maps knows about, read off its own picker.
+   *
+   * This is the authoritative list, and it is not the same as the store's:
+   * `docs/desktop.md` found the picker showing a "Favorites" guide that
+   * `apple_maps_list_collections` does not return. Read here as a side effect of
+   * being on the way to a write, rather than as a tool of its own — reaching it
+   * needs a place card, which needs a `maps://` open, which leaves a Recents
+   * entry. That is too much side effect for something calling itself a read.
+   *
+   * Leaves the picker OPEN, because the caller is normally about to press a row.
+   */
+  openGuidePicker(): Promise<Guide[] | null>;
+  /** Press one guide row, then Done. Returns false if no row matched. */
+  chooseGuide(name: string): Promise<boolean>;
+  /**
+   * Re-open the card and read the state bit, which is the only way to verify.
+   *
+   * **A write closes the card.** Saving through the naming sheet dismisses the
+   * whole place card and returns Maps to its main view, so reading `AddButton`
+   * straight after a press finds nothing and reports "the card does not say it
+   * is saved" — which is a sentence about the write having failed, when what
+   * actually happened is that the thing being read went away.
+   *
+   * So verification re-opens the place first. That costs another `maps://`,
+   * which is free in the sense that matters: the Recents entry this leaves was
+   * already left by opening the card in the first place.
+   */
+  verifySaved(place: {
+    name: string;
+    latitude: number;
+    longitude: number;
+  }): Promise<boolean | null>;
+  /** Abandon the picker without filing anything. */
+  cancelGuidePicker(): Promise<void>;
+}
+//#endregion
 //#region src/client/store.d.ts
 type FieldMap = {
   /**
@@ -497,11 +601,20 @@ type CreateClientOptions = {
   logger?: Logger;
   /** Injected by tests so discovery never reaches the developer's real home. */
   home?: string;
+  /**
+   * The interface lane, for tests.
+   *
+   * A seam of the same shape as `home`: null pins the store-only surface on a
+   * machine that IS hosted, and a stub drives the interface lane on one that is
+   * not. Undefined means "ask the environment", which is what the server does.
+   */
+  ax?: MapsAxLane | null | undefined;
 };
 declare class AppleMapsClient {
   #private;
   constructor(opts: CreateClientOptions);
   get config(): Config;
+  get axLane(): MapsAxLane | null;
   located(): LocateResult;
   /**
    * A writer bound to the located store, or an error explaining why not.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/locate.ts","../src/config.ts","../src/client/store.ts","../src/client/ref.ts","../src/client/write.ts","../src/client/maps.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/locate.ts","../src/config.ts","../src/client/ax.ts","../src/client/store.ts","../src/client/ref.ts","../src/client/write.ts","../src/client/maps.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}

package/dist/index.js

@@ -1,2 +1,2 @@
-import { A as fromStoreTime, C as MAPS_SURFACE, D as UndatableStoreError, E as SchemaDriftError, M as resolveEpoch, N as BUILD_INFO, O as APPLE_SECONDS, S as MAPS_BUNDLE_ID, T as PlaceNotFoundError, _ as defaultDirectory, a as loadConfig, b as AppleMapsError, c as introspect, d as InvalidMapsRefError, f as PLACE_REF_VERSION, g as encodePlaceRef, h as encodeCollectionRef, i as registerTools, j as renderInstant, k as CORE_DATA_EPOCH_OFFSET, l as openStore, m as decodePlaceRef, n as SERVER_VERSION, o as AppleMapsClient, p as decodeCollectionRef, r as createServer, s as MapsStore, t as SERVER_NAME, u as COLLECTION_REF_VERSION, v as defaultStorePath, w as MapsStoreUnavailableError, x as IndexUnavailableError, y as locateStore } from "./server-CpYiHM_a.js";
+import { A as fromStoreTime, C as MAPS_SURFACE, D as UndatableStoreError, E as SchemaDriftError, M as resolveEpoch, N as BUILD_INFO, O as APPLE_SECONDS, S as MAPS_BUNDLE_ID, T as PlaceNotFoundError, _ as defaultDirectory, a as loadConfig, b as AppleMapsError, c as introspect, d as InvalidMapsRefError, f as PLACE_REF_VERSION, g as encodePlaceRef, h as encodeCollectionRef, i as registerTools, j as renderInstant, k as CORE_DATA_EPOCH_OFFSET, l as openStore, m as decodePlaceRef, n as SERVER_VERSION, o as AppleMapsClient, p as decodeCollectionRef, r as createServer, s as MapsStore, t as SERVER_NAME, u as COLLECTION_REF_VERSION, v as defaultStorePath, w as MapsStoreUnavailableError, x as IndexUnavailableError, y as locateStore } from "./server-ip7LF8Un.js";
 export { APPLE_SECONDS, AppleMapsClient, AppleMapsError, BUILD_INFO, COLLECTION_REF_VERSION, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, InvalidMapsRefError, MAPS_BUNDLE_ID, MAPS_SURFACE, MapsStore, MapsStoreUnavailableError, PLACE_REF_VERSION, PlaceNotFoundError, SERVER_NAME, SERVER_VERSION, SchemaDriftError, UndatableStoreError, createServer, decodeCollectionRef, decodePlaceRef, defaultDirectory, defaultStorePath, encodeCollectionRef, encodePlaceRef, fromStoreTime, introspect, loadConfig, locateStore, openStore, registerTools, renderInstant, resolveEpoch };