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.
- package/README.md +22 -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.
|
|
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
|
+
"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",
|