lucid-apple-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Randell Hendley / Lucid Systems LLC
+
+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,97 @@
+# lucid-apple-mcp
+
+MCP server that gives Claude and local LLMs access to Apple's on-device frameworks — Vision OCR, NSDataDetector, and Apple Intelligence FoundationModels. Everything runs on your Mac. Nothing leaves.
+
+**Zero tokens consumed · Zero data leaves your Mac.**
+
+## Tools
+
+| Tool | Engine | Needs Apple Intelligence | Input | Returns |
+|---|---|---|---|---|
+| `ocr` | Vision | No | `path` | plain text |
+| `recognize_document` | Vision | No | `path` | `{transcript, tables}` |
+| `detect` | NSDataDetector | No | `text` | JSON array |
+| `extract` | FoundationModels | **Yes** | `text`, `want?` | JSON object |
+| `classify` | FoundationModels | **Yes** | `text`, `labels` | one label |
+| `summarize` | FoundationModels | **Yes** | `text` | summary string |
+| `generate` | FoundationModels | **Yes** | `prompt`, `instructions?` | reply string |
+
+Three capability tiers:
+
+- **`ocr` + `detect`** — run on **any Apple Silicon Mac**. No Apple Intelligence, no macOS 26 required.
+- **`recognize_document`** — requires **macOS 26** (Vision's `RecognizeDocumentsRequest`), but **not** Apple Intelligence.
+- **`extract`, `classify`, `summarize`, `generate`** — require **macOS 26 + Apple Intelligence** enabled in System Settings.
+
+## Requirements
+
+- Apple Silicon Mac
+- Node.js 18+
+- Xcode Command Line Tools (`xcode-select --install`) — to build the Swift helper
+- macOS 26+ — for `recognize_document` and the four FoundationModels tools
+- Apple Intelligence enabled — for `extract`, `classify`, `summarize`, `generate` only
+
+## Install
+
+```bash
+git clone https://github.com/Lucid-Systems-LLC/Lucid-Apple-MCP.git
+cd Lucid-Apple-MCP
+npm install        # compiles helper.swift → ./helper automatically (postinstall)
+```
+
+`npm install` builds the Swift `helper` for you. On a non-Mac, or a Mac without the Xcode tools, it skips the build with a note instead of failing — run `npm run build` once the toolchain is present.
+
+## Add to Claude Code (CLI)
+
+```bash
+claude mcp add lucid-apple "$(which node)" "$(pwd)/server.mjs"
+```
+
+`$(which node)` bakes in the absolute path to your Node binary — which matters (see the note below).
+
+## Add to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lucid-apple": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/lucid-apple-mcp/server.mjs"]
+    }
+  }
+}
+```
+
+Use an **absolute path to `node`** — Claude Desktop is launched from the GUI and does not inherit your shell `PATH`, so a bare `"node"` fails with `spawn node ENOENT` (common with nvm or Homebrew). Find yours with `which node` (e.g. `/Users/you/.nvm/versions/node/v20.20.0/bin/node`). Use the absolute path to `server.mjs` too.
+
+Restart Claude Desktop. The tools appear in the MCP panel.
+
+## Architecture
+
+Node.js MCP server (`server.mjs`, stdio transport) spawns a compiled Swift binary (`helper`) once per tool call — one JSON request on stdin, one JSON result on stdout. The Swift binary bridges:
+
+- **Vision** (`VNRecognizeTextRequest`, `RecognizeDocumentsRequest`) → OCR
+- **NSDataDetector** → deterministic entity detection
+- **FoundationModels** → Apple's on-device LLM
+
+Stateless per call. No persistent process. Safe in air-gap when used with a local LLM client.
+
+## Privacy
+
+Computation is fully on-device — files and text never leave the Mac. One honest caveat: when driving this from a cloud assistant (e.g. Claude Desktop), tool *results* are returned to that assistant and become part of the cloud conversation. For an end-to-end offline pipeline, drive the MCP from a local client like Voical.
+
+## Limitations
+
+- `recognize_document` requires macOS 26; `extract`, `classify`, `summarize`, and `generate` require macOS 26 with Apple Intelligence enabled. On older macOS these return a clean "requires macOS 26" error — `ocr` and `detect` keep working.
+- Apple's on-device model is fast and private — not a frontier model. Use it for short answers, drafts, and rewrites.
+- `ocr` and `recognize_document` require absolute file paths.
+- macOS only. No Windows or Linux support.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Built by [Lucid Systems LLC](https://lucidsystemsai.com) · Veteran owned · No VC · No cloud

package/USAGE.md

@@ -0,0 +1,145 @@
+# Lucid Apple MCP — Usage
+
+On-device Apple Intelligence, exposed as MCP tools. Everything runs locally on the Mac:
+OCR via the **Vision** framework, entity detection via **NSDataDetector**, and
+generation / extraction / classification / summarization via Apple's on-device
+**FoundationModels** LLM. No cloud AI service is called for the work itself.
+
+## Requirements
+- Apple-silicon Mac, **macOS 26+**.
+- The four FoundationModels tools (`extract`, `classify`, `summarize`, `generate`)
+  require **Apple Intelligence enabled** in System Settings.
+- `ocr` and `detect` work regardless — Vision and NSDataDetector are always available.
+
+## Tools at a glance
+
+| Tool | Required | Optional | Returns | Engine | Needs Apple Intelligence |
+|---|---|---|---|---|---|
+| `ocr` | `path` | — | text (string) | Vision | No |
+| `recognize_document` | `path` | — | JSON `{transcript, tables}` | Vision | No |
+| `detect` | `text` | — | JSON array | NSDataDetector | No |
+| `extract` | `text` | `want` | JSON object | FoundationModels | Yes |
+| `classify` | `text`, `labels` | — | one label (string) | FoundationModels | Yes |
+| `summarize` | `text` | — | summary (string) | FoundationModels | Yes |
+| `generate` | `prompt` | `instructions` | reply (string) | FoundationModels | Yes |
+
+---
+
+## `ocr` — text from an image or PDF page
+**One parameter: `path` (absolute).** Accepts `png`, `jpg`, `heic`, `tiff`, or a rendered
+PDF page. Returns the recognized text, lines joined by newlines. ~0.2 s, fully offline.
+
+```json
+{ "tool": "ocr", "arguments": { "path": "/Users/you/Desktop/receipt.jpg" } }
+```
+
+## `recognize_document` — structured OCR (tables / forms / multi-column)
+**One parameter: `path` (absolute).** Apple Vision's `RecognizeDocumentsRequest` — same
+inputs as `ocr`, but returns **structured JSON**:
+`{ "transcript": "…full reading-order text…", "tables": [ [ [cell, …], …rows ], …tables ] }`.
+Use this instead of `ocr` whenever **layout matters** — tables, forms, receipts, multi-column
+pages. `ocr` flattens a table into a stream of words; this reconstructs it as rows of cells.
+Offline; no Apple Intelligence required.
+
+```json
+{ "tool": "recognize_document", "arguments": { "path": "/Users/you/Downloads/invoice.png" } }
+```
+
+## `detect` — dates / links / phones / addresses (deterministic)
+**One parameter: `text`.** Runs `NSDataDetector` — no model, instant, deterministic.
+Returns a JSON array; **every item has `match` (the literal substring) + `type`**, plus
+one type-specific field:
+
+| type | extra field | notes |
+|---|---|---|
+| `phone` | `value` | normalized phone string |
+| `link` | `url` | absolute URL |
+| `date` | `iso` | ISO-8601 **UTC**, resolved using the machine's local timezone |
+| `address` | — | the full address is in `match` |
+
+```jsonc
+// detect("Call +1 (512) 555-0123 or see https://voicalai.com — meeting June 14, 2026 at 3:00 PM, 123 Main St, Austin TX 78701")
+[
+  { "match": "+1 (512) 555-0123",            "type": "phone",   "value": "+1 (512) 555-0123" },
+  { "match": "https://voicalai.com",         "type": "link",    "url":   "https://voicalai.com" },
+  { "match": "June 14, 2026 at 3:00 PM",     "type": "date",    "iso":   "2026-06-14T20:00:00Z" },
+  { "match": "123 Main St, Austin TX 78701", "type": "address" }
+]
+```
+
+## `extract` — structured JSON from text
+**`text` (required) + `want` (optional).** Uses FoundationModels to pull structured
+fields and returns a JSON object. Today's date is injected into the prompt, so relative
+dates ("next Tuesday") resolve to absolute ones. `want` defaults to key fields / named
+entities / dates / action items.
+
+```json
+{ "tool": "extract", "arguments": { "text": "...", "want": "name, title, company, phone, email" } }
+```
+
+## `classify` — one label from a set
+**`text` + `labels` (non-empty array).** Returns exactly one of the provided labels.
+
+```json
+{ "tool": "classify", "arguments": { "text": "...", "labels": ["invoice", "contract", "medical", "junk"] } }
+```
+
+## `summarize` — concise summary
+**`text`.** Returns a short summary string (FoundationModels).
+
+## `generate` — quick on-device answer / draft / rewrite
+**`prompt` (required) + `instructions` (optional system-style guidance for tone/role/format).**
+Apple's on-device model — concise; good for short answers, drafting, and rewriting; not
+for deep reasoning.
+
+```json
+{ "tool": "generate", "arguments": { "prompt": "Rewrite this more formally: ...", "instructions": "You are a concise editor." } }
+```
+
+---
+
+## Chaining — OCR, then mine the text
+The tools compose. `ocr` lifts text off an image; the rest operate on that text:
+
+```
+ocr(image)  →  raw text
+   ├─ extract(text, want="…")     → structured JSON
+   ├─ detect(text)                → dates / links / phones / addresses (deterministic)
+   ├─ classify(text, labels=[…])  → one label
+   ├─ summarize(text)             → short summary
+   └─ generate(prompt=…)          → free-form reply
+```
+
+**Recipe — scan a business card**
+1. `text = ocr("/…/card.jpg")`
+2. `fields = extract(text, want="name, title, company, phone, email, address")`
+3. `entities = detect(text)` → ground the phone / email / address deterministically.
+
+**Recipe — triage a scanned document**
+1. `text = ocr("/…/letter.png")`
+2. `category = classify(text, labels=["invoice", "contract", "medical", "junk"])`
+3. `summary = summarize(text)`
+
+> **Accuracy tip:** for hard facts (dates, phones, links, addresses), trust `detect`
+> (deterministic) over the model's reading of them; use `extract` for the semantics.
+
+---
+
+## Conversational use (any MCP client)
+Once connected, just ask:
+- *"OCR /Users/me/Desktop/scan.png and pull out any dates and action items."*
+- *"Classify this note as urgent, normal, or low priority."*
+
+The client calls the tools for you.
+
+## Offline / privacy
+The **computation is on-device** — the image/file never leaves the Mac, and no cloud OCR
+or AI API is called. One honest distinction when driving this from a **cloud assistant**
+(e.g. Claude Desktop): the tool *result* is returned to that assistant and becomes part
+of the cloud conversation. For an **end-to-end offline** pipeline (results never leaving
+the machine), drive the MCP from a local client — e.g. Voical's local model.
+
+## Architecture
+A Node MCP server (`server.mjs`, `@modelcontextprotocol/sdk`, stdio) spawns a compiled
+Swift helper (`helper`) once per call — one JSON request on stdin, one JSON line on
+stdout — bridging Vision, NSDataDetector, and FoundationModels. Fully offline.

package/helper.swift

@@ -0,0 +1,209 @@
+// lucid-apple — Swift helper. Reads ONE JSON request {verb, ...} on stdin, runs an
+// on-device Apple capability, writes ONE JSON line to stdout. Fully offline. Spawned
+// per-call by the Node MCP server.
+//   Vision:           ocr (any macOS) · recognize_document (macOS 26)
+//   NSDataDetector:   detect (any macOS)
+//   FoundationModels: generate · summarize · extract · classify (macOS 26 + Apple Intelligence)
+//
+// Portability: `ocr` and `detect` build and run on any Apple Silicon Mac. The macOS-26
+// APIs (FoundationModels + Vision's RecognizeDocumentsRequest) are guarded by
+// `#if canImport(FoundationModels)` (so the file compiles on an older SDK) and
+// `@available(macOS 26.0, *)` / `if #available` (so it runs on an older deployment target).
+import Foundation
+import Vision
+
+#if canImport(FoundationModels)
+import FoundationModels
+#endif
+
+enum HErr: Error, CustomStringConvertible {
+    case bad(String)
+    var description: String { switch self { case .bad(let m): return m } }
+}
+
+@main
+struct Helper {
+    static func main() async {
+        let input = FileHandle.standardInput.readDataToEndOfFile()
+        guard let req = (try? JSONSerialization.jsonObject(with: input)) as? [String: Any],
+              let verb = req["verb"] as? String else {
+            emit(["ok": false, "error": "invalid request — expected JSON {\"verb\": ...}"])
+            return
+        }
+        do {
+            switch verb {
+            // ── Always available (any Apple Silicon Mac) ───────────────────────────
+            case "ocr":
+                guard let path = req["path"] as? String else { throw HErr.bad("ocr needs 'path'") }
+                emit(["ok": true, "text": try ocr(path: path)])
+
+            case "detect":
+                guard let text = req["text"] as? String else { throw HErr.bad("detect needs 'text'") }
+                let data = try JSONSerialization.data(withJSONObject: detectData(in: text))
+                emit(["ok": true, "text": String(data: data, encoding: .utf8) ?? "[]"])
+
+            // ── macOS 26 + Apple Intelligence (FoundationModels) ───────────────────
+            case "generate":
+                guard let prompt = req["prompt"] as? String else { throw HErr.bad("generate needs 'prompt'") }
+                #if canImport(FoundationModels)
+                if #available(macOS 26.0, *) {
+                    emit(["ok": true, "text": try await generate(prompt, instructions: req["instructions"] as? String)])
+                } else { emit(unavailable26("generate", needsAI: true)) }
+                #else
+                emit(unavailable26("generate", needsAI: true))
+                #endif
+
+            case "summarize":
+                guard let text = req["text"] as? String else { throw HErr.bad("summarize needs 'text'") }
+                #if canImport(FoundationModels)
+                if #available(macOS 26.0, *) {
+                    let p = "Summarize the following in a few concise sentences. Output only the summary.\n\n\(text)"
+                    emit(["ok": true, "text": try await generate(p, instructions: nil)])
+                } else { emit(unavailable26("summarize", needsAI: true)) }
+                #else
+                emit(unavailable26("summarize", needsAI: true))
+                #endif
+
+            case "extract":
+                guard let text = req["text"] as? String else { throw HErr.bad("extract needs 'text'") }
+                #if canImport(FoundationModels)
+                if #available(macOS 26.0, *) {
+                    let want = req["want"] as? String ?? "the key fields, named entities, dates/times, and action items"
+                    let df = DateFormatter(); df.dateFormat = "EEEE, MMMM d, yyyy"
+                    let p = "Today is \(df.string(from: Date())). From the TEXT below, extract \(want). Resolve any relative dates (e.g. \"next Tuesday\") to absolute calendar dates. Respond with ONLY valid minified JSON — no prose, no markdown fences.\n\nTEXT:\n\(text)"
+                    let raw = try await generate(p, instructions: "You are a precise information-extraction engine. Output only valid JSON.")
+                    emit(["ok": true, "text": stripFences(raw)])
+                } else { emit(unavailable26("extract", needsAI: true)) }
+                #else
+                emit(unavailable26("extract", needsAI: true))
+                #endif
+
+            case "classify":
+                guard let text = req["text"] as? String, let labels = req["labels"] as? [String], !labels.isEmpty else {
+                    throw HErr.bad("classify needs 'text' and a non-empty 'labels' array")
+                }
+                #if canImport(FoundationModels)
+                if #available(macOS 26.0, *) {
+                    let p = "Classify the TEXT into EXACTLY ONE of these labels: \(labels.joined(separator: ", ")). Reply with only the chosen label, nothing else.\n\nTEXT:\n\(text)"
+                    emit(["ok": true, "text": try await generate(p, instructions: "You are a classifier. Reply with exactly one of the allowed labels.")])
+                } else { emit(unavailable26("classify", needsAI: true)) }
+                #else
+                emit(unavailable26("classify", needsAI: true))
+                #endif
+
+            // ── macOS 26 (Vision RecognizeDocumentsRequest), no Apple Intelligence ──
+            case "recognize_document", "recognize_doc":
+                guard let path = req["path"] as? String else { throw HErr.bad("recognize_document needs 'path'") }
+                #if canImport(FoundationModels)
+                if #available(macOS 26.0, *) {
+                    let docObj = try await recognizeDocument(path: path)
+                    let docData = try JSONSerialization.data(withJSONObject: docObj)
+                    emit(["ok": true, "text": String(data: docData, encoding: .utf8) ?? "{}"])
+                } else { emit(unavailable26("recognize_document", needsAI: false)) }
+                #else
+                emit(unavailable26("recognize_document", needsAI: false))
+                #endif
+
+            default:
+                emit(["ok": false, "error": "unknown verb '\(verb)'"])
+            }
+        } catch {
+            emit(["ok": false, "error": "\(error)"])
+        }
+    }
+
+    // Clean, user-facing error for the macOS-26-only verbs when run on an older OS / SDK.
+    static func unavailable26(_ verb: String, needsAI: Bool) -> [String: Any] {
+        let why = needsAI
+            ? "requires macOS 26 with Apple Intelligence enabled"
+            : "requires macOS 26 (Vision RecognizeDocumentsRequest)"
+        return ["ok": false, "error": "\(verb) \(why). ocr and detect work on any Apple Silicon Mac."]
+    }
+
+    static func ocr(path: String) throws -> String {
+        let request = VNRecognizeTextRequest()
+        request.recognitionLevel = .accurate
+        try VNImageRequestHandler(url: URL(fileURLWithPath: path), options: [:]).perform([request])
+        return (request.results ?? [])
+            .compactMap { $0.topCandidates(1).first?.string }
+            .joined(separator: "\n")
+    }
+
+    // NSDataDetector — offline, deterministic detection of dates / links / phones / addresses.
+    static func detectData(in text: String) -> [[String: Any]] {
+        let types: NSTextCheckingResult.CheckingType = [.date, .link, .phoneNumber, .address]
+        guard let detector = try? NSDataDetector(types: types.rawValue) else { return [] }
+        let ns = text as NSString
+        var out: [[String: Any]] = []
+        detector.enumerateMatches(in: text, range: NSRange(location: 0, length: ns.length)) { m, _, _ in
+            guard let m = m else { return }
+            var item: [String: Any] = ["match": ns.substring(with: m.range)]
+            switch m.resultType {
+            case .date:
+                item["type"] = "date"
+                if let d = m.date { item["iso"] = ISO8601DateFormatter().string(from: d) }
+            case .link:
+                item["type"] = "link"; if let u = m.url { item["url"] = u.absoluteString }
+            case .phoneNumber:
+                item["type"] = "phone"; if let p = m.phoneNumber { item["value"] = p }
+            case .address:
+                item["type"] = "address"   // full address string is in "match"
+            default:
+                item["type"] = "other"
+            }
+            out.append(item)
+        }
+        return out
+    }
+
+    // Some small-model outputs wrap JSON in ```json … ``` despite instructions; strip it.
+    static func stripFences(_ s: String) -> String {
+        var t = s.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard t.hasPrefix("```") else { return t }
+        if let nl = t.firstIndex(of: "\n") { t = String(t[t.index(after: nl)...]) }
+        if let r = t.range(of: "```", options: .backwards) { t = String(t[..<r.lowerBound]) }
+        return t.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    static func emit(_ obj: [String: Any]) {
+        guard let data = try? JSONSerialization.data(withJSONObject: obj) else { return }
+        FileHandle.standardOutput.write(data)
+        FileHandle.standardOutput.write(Data("\n".utf8))
+    }
+}
+
+#if canImport(FoundationModels)
+@available(macOS 26.0, *)
+extension Helper {
+    static func generate(_ prompt: String, instructions: String?) async throws -> String {
+        let model = SystemLanguageModel.default
+        guard case .available = model.availability else {
+            throw HErr.bad("Apple Intelligence model unavailable: \(model.availability)")
+        }
+        let session = LanguageModelSession()
+        let full = instructions.map { "\($0)\n\n\(prompt)" } ?? prompt
+        return try await session.respond(to: full).content
+    }
+
+    // Vision RecognizeDocumentsRequest — STRUCTURED extraction (full transcript + TABLES
+    // as rows/cells), preserving the layout that plain OCR (VNRecognizeTextRequest) flattens.
+    static func recognizeDocument(path: String) async throws -> [String: Any] {
+        let request = RecognizeDocumentsRequest()
+        let observations = try await request.perform(on: URL(fileURLWithPath: path))
+        guard let document = observations.first?.document else {
+            throw HErr.bad("no document recognized in \(path)")
+        }
+        var out: [String: Any] = ["transcript": document.text.transcript]
+        var tables: [[[String]]] = []
+        for table in document.tables {
+            var rows: [[String]] = []
+            for row in table.rows {
+                rows.append(row.map { $0.content.text.transcript })
+            }
+            tables.append(rows)
+        }
+        out["tables"] = tables
+        return out
+    }
+}
+#endif

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "lucid-apple-mcp",
+  "version": "0.3.0",
+  "mcpName": "io.github.Lucid-Systems-LLC/lucid-apple-mcp",
+  "description": "Offline MCP server exposing Apple's on-device frameworks to Claude and local LLMs — Vision OCR with table-preserving document recognition, NSDataDetector, and Apple Intelligence Foundation Models. Runs entirely on your Mac: no cloud, no API keys, zero tokens consumed, zero data leaves the machine. macOS only.",
+  "type": "module",
+  "bin": { "lucid-apple-mcp": "./server.mjs" },
+  "scripts": {
+    "build": "swiftc -parse-as-library helper.swift -o helper",
+    "postinstall": "node -e \"const{spawnSync}=require('node:child_process');if(process.platform!=='darwin'){console.warn('[lucid-apple-mcp] non-macOS host - skipping Swift helper build (this server is macOS only).');process.exit(0)}const r=spawnSync('swiftc',['-parse-as-library','helper.swift','-o','helper'],{stdio:'inherit'});if(r.status!==0)console.warn('[lucid-apple-mcp] could not build helper - install Xcode Command Line Tools (xcode-select --install), then run: npm run build');process.exit(0)\"",
+    "smoke": "node smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "apple",
+    "apple-intelligence",
+    "foundation-models",
+    "vision",
+    "ocr",
+    "document-ocr",
+    "tables",
+    "nsdatadetector",
+    "on-device",
+    "offline",
+    "local",
+    "privacy",
+    "macos",
+    "no-cloud",
+    "claude"
+  ],
+  "repository": { "type": "git", "url": "git+https://github.com/Lucid-Systems-LLC/Lucid-Apple-MCP.git" },
+  "homepage": "https://github.com/Lucid-Systems-LLC/Lucid-Apple-MCP",
+  "bugs": { "url": "https://github.com/Lucid-Systems-LLC/Lucid-Apple-MCP/issues" },
+  "author": "Lucid Systems LLC",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "files": ["server.mjs", "helper.swift", "README.md", "USAGE.md", "LICENSE"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// lucid-apple — MCP server exposing Apple's on-device Intelligence
+// (OFFLINE) as tools. Each call spawns the Swift `helper` binary with a JSON request
+// on stdin and returns its JSON result. Nothing leaves the machine — safe in air-gap.
+//   FoundationModels: generate · summarize · extract · classify
+//   Vision:           ocr · recognize_document
+//   NSDataDetector:   detect
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const HELPER = join(dirname(fileURLToPath(import.meta.url)), 'helper')
+
+const HELPER_TIMEOUT_MS = 60000
+
+// Scan the helper's stdout from the last line up for the first line that parses as JSON.
+// Apple's Vision (RecognizeDocumentsRequest) can print a `VTEST:` diagnostic to stdout
+// AFTER our JSON on the error path; a naive last-line parse would choke on it.
+function lastJsonLine(out) {
+  const lines = out.split('\n')
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const s = lines[i].trim()
+    if (!s) continue
+    try {
+      return JSON.parse(s)
+    } catch {
+      /* keep scanning */
+    }
+  }
+  return undefined
+}
+
+function callHelper(req) {
+  return new Promise((resolve) => {
+    const p = spawn(HELPER, [], { stdio: ['pipe', 'pipe', 'pipe'] })
+    let out = ''
+    let err = ''
+    let settled = false
+    const done = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+    // A stalled helper (e.g. the on-device model wedging) must not hang the call forever.
+    const timer = setTimeout(() => {
+      try {
+        p.kill('SIGKILL')
+      } catch {
+        /* already gone */
+      }
+      done({ ok: false, error: `helper timed out after ${HELPER_TIMEOUT_MS}ms` })
+    }, HELPER_TIMEOUT_MS)
+    p.stdout.on('data', (d) => (out += d))
+    p.stderr.on('data', (d) => (err += d))
+    p.on('error', (e) => done({ ok: false, error: `cannot spawn helper: ${e.message}` }))
+    // Without this, an EPIPE when the helper exits early throws an *uncaught* exception
+    // that takes down the whole server. Swallow it; `close` reports the real outcome.
+    p.stdin.on('error', () => {})
+    p.on('close', () => {
+      const parsed = lastJsonLine(out)
+      done(parsed !== undefined ? parsed : { ok: false, error: err.trim() || 'helper returned no JSON' })
+    })
+    p.stdin.write(JSON.stringify(req))
+    p.stdin.end()
+  })
+}
+
+const TOOLS = [
+  {
+    name: 'ocr',
+    description:
+      'Extract text from an image or rendered PDF page using on-device Apple Vision OCR. Fully offline, ~0.2s.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'Absolute path to an image (png/jpg/heic/tiff) or rendered PDF page.' } },
+      required: ['path']
+    }
+  },
+  {
+    name: 'generate',
+    description:
+      "Ask Apple's on-device Intelligence model (offline). Good for quick answers, drafting, rewriting. Concise; not for deep reasoning.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'The prompt / question.' },
+        instructions: { type: 'string', description: 'Optional system-style guidance (tone, role, format).' }
+      },
+      required: ['prompt']
+    }
+  },
+  {
+    name: 'summarize',
+    description: "Summarize text concisely using Apple's on-device Intelligence model (offline).",
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string', description: 'The text to summarize.' } },
+      required: ['text']
+    }
+  },
+  {
+    name: 'extract',
+    description:
+      "Extract STRUCTURED data from text with Apple's on-device model (offline) — returns JSON. Great for pulling an event, action items, or contact fields out of an email / note / message.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The source text.' },
+        want: {
+          type: 'string',
+          description: "What to extract, e.g. 'the meeting date, time, attendees, and location' or 'all action items'. Defaults to key fields/entities/dates/action-items."
+        }
+      },
+      required: ['text']
+    }
+  },
+  {
+    name: 'classify',
+    description: "Classify text into EXACTLY ONE of a provided set of labels, on-device (offline).",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The text to classify.' },
+        labels: { type: 'array', items: { type: 'string' }, description: 'The allowed labels (pick exactly one).' }
+      },
+      required: ['text', 'labels']
+    }
+  },
+  {
+    name: 'detect',
+    description:
+      'Detect dates, links, phone numbers, and addresses in text (NSDataDetector — fully offline + deterministic). Returns a JSON array of items. Pairs well with extract for grounding calendar/contact data.',
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string', description: 'The text to scan.' } },
+      required: ['text']
+    }
+  },
+  {
+    name: 'recognize_document',
+    description:
+      'STRUCTURED document OCR via Apple Vision (RecognizeDocumentsRequest, offline). Returns JSON {transcript, tables} and preserves TABLES as rows/cells + reading order — unlike `ocr`, which flattens layout. Use for tables, forms, receipts, and multi-column documents.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'Absolute path to an image (png/jpg/heic/tiff) or rendered PDF page.' } },
+      required: ['path']
+    }
+  }
+]
+
+const server = new Server(
+  { name: 'lucid-apple', version: '0.3.0' },
+  { capabilities: { tools: {} } }
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params
+  const res = await callHelper({ verb: name, ...args })
+  if (!res.ok) {
+    return { content: [{ type: 'text', text: `Error: ${res.error}` }], isError: true }
+  }
+  return { content: [{ type: 'text', text: res.text ?? '' }] }
+})
+
+await server.connect(new StdioServerTransport())