# mcp-for-spotlight

Ein kleiner MCP-Server (Model Context Protocol), der die macOS-Spotlight-Suche
als Tools bereitstellt. Er kapselt `mdfind` (Volltext- und Metadaten-Suche über
den Spotlight-Index) und `mdls` (Metadaten einer Datei). Systemweite
Dateisuche, nicht auf eine App beschränkt.

## Was ist ein MCP-Server?

MCP (Model Context Protocol) ist ein offener Standard, über den KI-Anwendungen
(der Host, etwa Claude Desktop oder Claude Code) mit externen Werkzeugen und
Daten sprechen. Ein Server stellt Fähigkeiten (Tools) bereit und weiß selbst
nichts von KI. Kommunikation über JSON-RPC 2.0, hier per stdio.

## Warum Spotlight statt `locate` oder AppleScript

- **Spotlight (`mdfind`)** indexiert Datei-Inhalt **und** Metadaten (Betreff,
  Autor, Typ, Datum) und wird live aktualisiert. Der richtige Index für
  Inhaltssuche.
- **`locate`** kennt nur Datei-Pfade/-Namen, keinen Inhalt, und ist oft
  veraltet oder inaktiv.
- **AppleScript-`whose`** (etwa in Mail) ist ein linearer Scan ohne Index.

## Tools

| Tool | Zweck |
|------|-------|
| `spotlight_search` | Dateien per `mdfind` finden: Freitext, Dateiname oder rohe Spotlight-Abfrage |
| `spotlight_metadata` | Spotlight-Metadaten einer Datei per `mdls` lesen |

`spotlight_search` erwartet genau eine Suchart:

- `text` — Freitext (Volltext + Metadaten), z. B. `"Quartalsbericht"`
- `name` — Teilstring im Dateinamen
- `query` — rohe Spotlight-Abfrage, z. B.
  `kMDItemContentType == "com.adobe.pdf" && kMDItemFSName == "*Rechnung*"c`

Optional `onlyIn` (auf ein Verzeichnis begrenzen) und `limit` (Vorgabe 50).

## Installation

```bash
npm install
```

Kein Build-Schritt: reines ESM-JavaScript, läuft direkt mit Node (>= 18).

## Full Disk Access

Geschützte Orte (z. B. `~/Library/Mail`, `~/Library/Messages`) liefern nur
Treffer, wenn der ausführende Prozess **Full Disk Access** hat
(Systemeinstellungen → Datenschutz & Sicherheit → Festplattenvollzugriff, dort
das Terminal bzw. den Node-Host freigeben). Ohne FDA sind normale
Nutzerdateien trotzdem durchsuchbar.

## Lokal testen

```bash
npm run inspect
```

## Registrieren

Claude Code:

```bash
claude mcp add spotlight -- node /absolute/path/to/mcp-for-spotlight/src/index.js
```

Claude Desktop, in `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "spotlight": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-for-spotlight/src/index.js"]
    }
  }
}
```

## Beispiele

```text
spotlight_search  name="Rechnung" onlyIn="/Users/me/Documents"
spotlight_search  query='kMDItemContentType == "com.adobe.pdf"' onlyIn="/Users/me/Downloads"
spotlight_metadata path="/Users/me/Downloads/x.pdf" attributes=["kMDItemContentCreationDate"]
```

## Lizenz

MIT