apple-tools-mcp 3.2.3 → 3.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +22 -2
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,22 @@
1
1
  # apple-tools-mcp
2
2
 
3
- An MCP (Model Context Protocol) server for Apple Mail, Messages, Calendar, and Contacts on macOS. Search them in plain language, send mail and messages, and create, edit, or remove calendar events and contacts. It talks to any MCP client over stdio. Search embeddings and the write bridge stay on your Mac.
3
+ An MCP (Model Context Protocol) server for Apple Mail, Messages, Calendar, and Contacts on macOS. Search them in plain language, send mail and messages, and create, edit, or remove calendar events and contacts. It talks to any MCP client over stdio, or over HTTP with a bearer token. Plain-language search is retrieval-augmented: your mail, messages, and calendar events are embedded on your Mac and kept in a local LanceDB vector database (see [How search works](#how-search-works)). The embeddings and the write bridge stay on your Mac.
4
+
5
+ ## How search works
6
+
7
+ Search runs against a local vector index, not a cloud service.
8
+
9
+ - **Embedding model:** [`Xenova/all-MiniLM-L6-v2`](https://huggingface.co/Xenova/all-MiniLM-L6-v2), a 384-dimension sentence-embedding model (mean pooling, normalized), run on your Mac with [Transformers.js](https://github.com/huggingface/transformers.js). The model files are downloaded from Hugging Face the first time the model loads and cached after that. Your mail, messages, and events are never sent anywhere to be embedded.
10
+ - **Vector database:** [LanceDB](https://lancedb.com/), embedded in the process (no server), stored in `~/.apple-tools-mcp/vector-index/` with three tables: `emails`, `messages`, and `calendar`.
11
+ - **What is indexed:**
12
+ - **Mail:** every `.emlx` file under `~/Library/Mail`, including partly downloaded ones. The embedded text is From, To, Subject, and the start of the body (1,000 characters in all).
13
+ - **Messages:** iMessage and SMS from `~/Library/Messages/chat.db`, including text that macOS stores only in the rich-text `attributedBody` field. The embedded text is the sender and the message (500 characters).
14
+ - **Calendar:** events from Calendar's `Calendar.sqlitedb`. The embedded text is title, calendar, location, and notes (500 characters).
15
+ - **Contacts are not embedded.** The contact tools and name matching read the Contacts (AddressBook) database directly.
16
+ - **At query time:** the question is embedded with the same model. Up to three variants of it (the original, one with time words removed, and one with a common synonym swapped in) each run a nearest-neighbour search. The result lists are merged with Reciprocal Rank Fusion (k = 60), then re-ranked by 70% vector similarity and 30% keyword match. If nothing comes back, one broader query is tried. `smart_search` chooses which tables to search from the question.
17
+ - **Not from the index:** `mail_find`, `mail_links`, `calendar_date`, `calendar_free_time`, the contact tools, and every write tool read Mail, Calendar, Contacts, or Messages live, so they work while the index is rebuilding.
18
+
19
+ The indexer (below) refreshes the index incrementally, every 5 minutes by default. The search tools return matching items for your MCP client's model to read and answer from.
4
20
 
5
21
  ## Requirements
6
22
 
@@ -172,7 +188,7 @@ If you do not run the indexer, the MCP process indexes when it starts, then exit
172
188
 
173
189
  ### 5. Another computer (optional)
174
190
 
175
- The same tools are available over HTTP, with a bearer token on every request. stdio on this Mac does not use the token.
191
+ The same tools are available over HTTP, with a bearer token on every request. stdio on this Mac does not use the token. The token is a random secret created on first use and kept in your login Keychain (service `apple-tools-mcp-http`); `apple-tools-mcp http-token` prints it.
176
192
 
177
193
  ```bash
178
194
  apple-tools-http
@@ -469,6 +485,10 @@ git config core.hooksPath .githooks
469
485
  npm run scan:package
470
486
  ```
471
487
 
488
+ Before a pull request is merged, `python3 .security/local-gate.py <PR number>` runs
489
+ Gitleaks, the production `npm audit`, offline Semgrep, and the unit and security
490
+ tests on the exact PR head and records the result as the `local-gate` status.
491
+
472
492
  The hook scans staged changes and fails closed if Gitleaks is unavailable. CI scans
473
493
  all fetched Git history and the exact `npm pack --dry-run` file list. Release CI
474
494
  repeats the package scan before npm Trusted Publishing. Credential rules are
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apple-tools-mcp",
3
- "version": "3.2.3",
3
+ "version": "3.2.4",
4
4
  "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts. Speaks stdio (local) or bearer-token-authenticated Streamable HTTP (LAN / Tailscale).",
5
5
  "type": "module",
6
6
  "main": "index.js",