@mgcrea/mcp-apple-maps 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,60 @@
+# @mgcrea/mcp-apple-maps
+
+MCP server for the macOS **Maps** app: the places you have saved.
+
+```json
+{
+  "mcpServers": {
+    "apple-maps": { "command": "npx", "args": ["-y", "@mgcrea/mcp-apple-maps"] }
+  }
+}
+```
+
+## What it reads
+
+Favourites, collections (Guides) and recents, with names, addresses and **real coordinates**,
+from Maps' Core Data store.
+
+| Tool                                | What                                                   |
+| ----------------------------------- | ------------------------------------------------------ |
+| `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_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 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.
+
+## Full Disk Access is mandatory
+
+Not an optimisation. Maps ships no scripting dictionary, so there is no Apple Events lane to fall
+back to — without the grant this server returns an **error**, never an empty list. Grant it to the
+app running the server, not to Maps.
+
+If a listing comes back empty, that means you have saved nothing of that kind. Run
+`apple_maps_diagnostics` to tell the two apart.
+
+## Configuration
+
+| Variable                    | Default    | What                                                   |
+| --------------------------- | ---------- | ------------------------------------------------------ |
+| `APPLE_MAPS_STORE`          | discovered | explicit store path, for tests and forensic copies     |
+| `APPLE_MAPS_INDEX_MODE`     | `auto`     | `auto` / `ro` / `immutable` / `off`                    |
+| `APPLE_MAPS_MAX_RESULTS`    | 50         | default result ceiling                                 |
+| `APPLE_MAPS_EXPOSE_PROMPTS` | on         | register the prompt and `cupertino://maps/*` resources |
+| `APPLE_MAPS_DEBUG`          | off        | verbose logging on stderr                              |
+
+`APPLE_MAPS_ALLOW_WRITES` is accepted and ignored: there is no mutating tool for it to gate.
+
+See [docs/maps.md](../../docs/maps.md) for the phase-0 measurements, including the three separate
+occasions on which this store was declared not to exist.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { C as MAPS_SURFACE, N as BUILD_INFO, a as loadConfig, r as createServer } from "./server-DgIy0w0S.js";
+import { runStdioServer } from "@mgcrea/mcp-apple-core";
+//#region src/cli.ts
+const LOG_PREFIX = "apple-maps-mcp";
+runStdioServer({
+	build: BUILD_INFO,
+	surface: MAPS_SURFACE,
+	logPrefix: LOG_PREFIX,
+	start: async (logger) => {
+		const config = loadConfig();
+		const { server, client } = createServer({
+			config,
+			logger
+		});
+		const status = client.status();
+		const caps = status.capabilities;
+		const rows = (k) => caps?.entities?.[k]?.rows ?? 0;
+		return {
+			server,
+			banner: `read-only, store=${status.store.opened ? status.store.mode ?? "open" : "UNREADABLE"}, favorites=${rows("favorites")}, collections=${rows("collections")}, recents=${rows("history")}, 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 { MAPS_SURFACE } from \"./client/errors.js\";\nimport { loadConfig } from \"./config.js\";\nimport { createServer } from \"./server.js\";\n\nconst LOG_PREFIX = \"apple-maps-mcp\";\n\nrunStdioServer({\n  build: BUILD_INFO,\n  surface: MAPS_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    const caps = status.capabilities as { entities?: Record<string, { rows?: number }> } | null;\n    const rows = (k: string): number => caps?.entities?.[k]?.rows ?? 0;\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. The counts are named because\n      // \"store=open\" alone cannot distinguish a working server from one pointed\n      // at an empty replica — which is exactly what the device-local cache is.\n      banner:\n        `read-only, ` +\n        `store=${status.store.opened ? (status.store.mode ?? \"open\") : \"UNREADABLE\"}, ` +\n        `favorites=${rows(\"favorites\")}, ` +\n        `collections=${rows(\"collections\")}, ` +\n        `recents=${rows(\"history\")}, ` +\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,MAAM,OAAO,OAAO;EACpB,MAAM,QAAQ,MAAsB,MAAM,WAAW,EAAE,EAAE,QAAQ;EACjE,OAAO;GACL;GAKA,QACE,oBACS,OAAO,MAAM,SAAU,OAAO,MAAM,QAAQ,SAAU,aAAa,cAC/D,KAAK,WAAW,EAAE,gBAChB,KAAK,aAAa,EAAE,YACxB,KAAK,SAAS,EAAE,UAClB,OAAO;EACpB;CACF;AACF,CAAC,CAAC,CAAC,OAAO,QAAiB;CACzB,QAAQ,MAAM,IAAI,WAAW,WAAW,GAAG;CAC3C,QAAQ,KAAK,CAAC;AAChB,CAAC"}