apple-notes-mcp 2.11.0 → 2.13.0

package/docs/markdown-templates.md

@@ -246,3 +246,86 @@ export:
 
 Each warning carries `noteId` and, when known, `attachmentId`. At most 200
 are listed; `warningsOmitted` counts the rest.
+
+## Editing in a browser
+
+`apple-notes-mcp templates edit` starts a small local web editor for
+templates. It is a command-line tool, not an MCP tool, and it runs only while
+you leave it running.
+
+```bash
+npx apple-notes-mcp templates edit               # start from standard-markdown
+npx apple-notes-mcp templates edit obsidian      # open a built-in or saved template
+npx apple-notes-mcp templates edit --note "x-coredata://…/ICNote/p123"
+```
+
+It prints one address, such as
+`http://127.0.0.1:52817/?token=3f9c…`. Open it in a browser. The page shows
+the template JSON on the left and the rendered Markdown on the right. Each
+edit is checked by the same validator as `validate-markdown-template`, and
+problems are listed with their JSON paths. The preview uses the same renderer
+as `export-notes-markdown`, against three built-in sample notes (headings and
+lists, inline formatting and links, attachments and tags). Attachments render
+as placeholders; the preview never copies files.
+
+Real notes are not read unless you pass `--note` with one note id. That note
+is read once, read-only, from the Notes database when the editor starts, so
+it needs the same Full Disk Access as `export-notes-markdown`. It appears as
+an extra preview choice.
+
+**Save** writes the template to the library through the same path as
+`save-markdown-template`: it validates first, is create-only, and replaces an
+existing template only when you tick "Replace an existing template". The
+editor never writes to Notes.
+
+| Option | Meaning |
+| --- | --- |
+| `name` | Template to open first (default `standard-markdown`) |
+| `--port N` | Port to listen on (default: any free port) |
+| `--idle-minutes N` | Stop after N minutes with no requests (default 30; `0` turns it off) |
+| `--note ID` | Also preview one real note, read-only |
+| `--tailnet` | Listen on this Mac's Tailscale address instead of `127.0.0.1` (see below) |
+
+Press Ctrl-C to stop the editor. It also stops by itself after the idle
+period.
+
+### What the editor exposes
+
+- It listens on `127.0.0.1` only, unless you pass `--tailnet`.
+- Every request must carry the random token from the printed address, either
+  as `?token=` or as an `Authorization: Bearer` header. A new token is made
+  each run, and the editor never logs it. Anyone who has the address can
+  read and save templates until the editor stops, so treat it like a
+  password.
+- Requests whose `Host` header is not the editor's own address are refused,
+  which blocks DNS rebinding. Requests from another origin are refused, and
+  saves must come from the editor's own page with a JSON body, so another web
+  page cannot drive it.
+- The page loads nothing from the network. Its script and style carry a
+  per-page nonce under a strict Content-Security-Policy, and responses send
+  `Referrer-Policy: no-referrer` so the token does not leak in a referrer.
+
+### On your tailnet
+
+`--tailnet` binds the editor to this Mac's [Tailscale](https://tailscale.com)
+IPv4 address (the `100.64.0.0/10` address on its `utun` interface) so you
+can edit from an iPad or another computer on your tailnet. It is off unless
+you pass the flag, and it refuses to start when this Mac has no Tailscale
+address.
+
+The editor finds the address by reading the network interfaces. It does not
+run the `tailscale` command, and it never changes Tailscale settings, Serve
+or Funnel, ACLs, or the macOS firewall. Whether other devices can reach the
+port is decided by your tailnet's access rules. The traffic is carried inside
+Tailscale's encrypted tunnel, but the editor itself speaks plain HTTP.
+
+With `--tailnet`, every device on your tailnet that is allowed to reach this
+Mac can connect to the port, and any of them that has the printed address can
+read and save templates. Share the address only with yourself, and stop the
+editor when you are done.
+
+**`--note` with `--tailnet` exposes the full note.** `--note <id>` previews one
+real note, and the preview shows that note's whole body. With `--tailnet`,
+anyone on your tailnet who has the printed address can read the entire note,
+not only the templates. Do not combine the two unless you want that. The
+editor prints this warning at startup, and `templates edit --help` repeats it.

package/native/permissions-window/apple-notes-permissions-window.swift

@@ -0,0 +1,215 @@
+// apple-notes-permissions-window
+//
+// An optional setup window for apple-notes-mcp. It shows the permissions
+// checklist that `apple-notes-mcp setup --permissions` prints, with an
+// "Open Settings" button per missing grant and a "Re-check" button. It probes
+// nothing itself: the TypeScript side runs every check and sends the results,
+// so the window and the terminal report always agree. It never reads the Notes
+// database, never sends Notes an Apple event, and never changes a setting.
+//
+// Protocol: JSON lines on stdin and stdout.
+//   in:  {"type": "hello"}                  answer the handshake and exit, no UI
+//   in:  {"type": "report", "report": {...}} show or refresh the checklist
+//   out: {"type": "hello", "protocolVersion": 1, "sourceSha256": "..."}
+//   out: {"type": "open", "id": "<item id>"}  the user asked to open that item's pane
+//   out: {"type": "recheck"}                  the user asked for a fresh check
+// The window closes when stdin ends; closing the window ends the process.
+//
+// Build (done by `apple-notes-mcp setup --permissions-window`, which also
+// generates the one-line source-digest file that defines helperSourceSHA256
+// and the Info.plist linked into __TEXT,__info_plist):
+//   xcrun swiftc -O -parse-as-library -framework AppKit -framework SwiftUI \
+//     -Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker Info.plist \
+//     apple-notes-permissions-window.swift source-digest.swift -o apple-notes-permissions-window
+
+import AppKit
+import Foundation
+import SwiftUI
+
+let protocolVersion = 1
+
+func send(_ object: [String: Any]) {
+    guard let data = try? JSONSerialization.data(withJSONObject: object, options: [.sortedKeys]) else { return }
+    FileHandle.standardOutput.write(data)
+    FileHandle.standardOutput.write(Data([0x0A]))
+}
+
+struct Item: Identifiable {
+    let id: String
+    let title: String
+    let status: String
+    let required: Bool
+    let detail: String
+    let settingsPane: String?
+    let hasSettings: Bool
+    let fix: String?
+    /// The command deliberately did not probe this item (Automation is opt-in).
+    let notProbed: Bool
+
+    init?(_ object: [String: Any]) {
+        guard let id = object["id"] as? String, let title = object["title"] as? String,
+              let status = object["status"] as? String else { return nil }
+        self.id = id
+        self.title = title
+        self.status = status
+        required = object["required"] as? Bool ?? false
+        detail = object["detail"] as? String ?? ""
+        settingsPane = object["settingsPane"] as? String
+        hasSettings = (object["settingsUrl"] as? String)?.hasPrefix("x-apple.systempreferences:") ?? false
+        fix = object["fix"] as? String
+        notProbed = object["notProbed"] as? Bool ?? false
+    }
+
+    var pending: Bool { !notProbed && (status == "missing" || status == "unknown") }
+}
+
+final class Model: ObservableObject {
+    @Published var items: [Item] = []
+    @Published var ready = false
+    @Published var launchingApp: String?
+    @Published var checking = false
+
+    func apply(_ report: [String: Any]) {
+        items = (report["items"] as? [[String: Any]] ?? []).compactMap(Item.init)
+        ready = report["ready"] as? Bool ?? false
+        launchingApp = report["launchingApp"] as? String
+        checking = false
+    }
+
+    func recheck() {
+        checking = true
+        send(["type": "recheck"])
+    }
+
+    func open(_ item: Item) {
+        send(["type": "open", "id": item.id])
+    }
+}
+
+struct StatusIcon: View {
+    let status: String
+    var body: some View {
+        switch status {
+        case "granted", "not_needed":
+            Image(systemName: "checkmark.circle.fill").foregroundStyle(.green)
+        case "missing":
+            Image(systemName: "xmark.circle.fill").foregroundStyle(.red)
+        case "not_checked":
+            Image(systemName: "minus.circle.fill").foregroundStyle(.secondary)
+        default:
+            Image(systemName: "questionmark.circle.fill").foregroundStyle(.orange)
+        }
+    }
+}
+
+struct ChecklistView: View {
+    @ObservedObject var model: Model
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 14) {
+            Text("Apple Notes MCP permissions").font(.title2).bold()
+            Text(model.launchingApp.map { "Grants shown are for \($0), the app that launched this check." }
+                ?? "Grants shown are for the process that launched this check.")
+                .font(.callout).foregroundStyle(.secondary)
+            ForEach(model.items) { item in
+                HStack(alignment: .top, spacing: 10) {
+                    StatusIcon(status: item.notProbed ? "not_checked" : item.status).font(.title3)
+                    VStack(alignment: .leading, spacing: 4) {
+                        Text(item.required ? item.title : "\(item.title) (optional)").font(.headline)
+                        if item.notProbed {
+                            Text("Not checked").font(.caption).bold().foregroundStyle(.secondary)
+                        }
+                        Text(item.detail).font(.callout).fixedSize(horizontal: false, vertical: true)
+                        if item.pending || item.notProbed, let fix = item.fix {
+                            Text(fix).font(.caption).foregroundStyle(.secondary)
+                                .fixedSize(horizontal: false, vertical: true)
+                                .textSelection(.enabled)
+                        }
+                    }
+                    Spacer(minLength: 8)
+                    if item.pending && item.hasSettings {
+                        Button("Open Settings") { model.open(item) }
+                            .help(item.settingsPane ?? "")
+                    }
+                }
+            }
+            Divider()
+            HStack {
+                Text(!model.ready ? "Required permissions are missing."
+                    : model.items.contains { $0.notProbed } ? "Every required permission that was checked is granted."
+                    : "Every required permission is granted.")
+                    .font(.callout)
+                Spacer()
+                if model.checking { ProgressView().controlSize(.small) }
+                Button("Re-check") { model.recheck() }
+                    .keyboardShortcut("r")
+                    .disabled(model.checking)
+            }
+        }
+        .padding(20)
+        .frame(width: 620)
+    }
+}
+
+final class AppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate {
+    let model = Model()
+    var window: NSWindow?
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 620, height: 420),
+            styleMask: [.titled, .closable, .miniaturizable],
+            backing: .buffered,
+            defer: false
+        )
+        window.title = "Apple Notes MCP Permissions"
+        window.contentView = NSHostingView(rootView: ChecklistView(model: model))
+        window.delegate = self
+        window.center()
+        window.makeKeyAndOrderFront(nil)
+        self.window = window
+        NSApp.activate(ignoringOtherApps: true)
+    }
+
+    func applicationShouldTerminateAfterLastWindowClosed(_ sender: NSApplication) -> Bool { true }
+}
+
+/// Reads JSON lines from stdin on a background thread and hands reports to the UI.
+func readReports(into delegate: AppDelegate) {
+    Thread.detachNewThread {
+        while let line = readLine(strippingNewline: true) {
+            guard let data = line.data(using: .utf8),
+                  let message = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
+                  message["type"] as? String == "report",
+                  let report = message["report"] as? [String: Any] else { continue }
+            DispatchQueue.main.async { delegate.model.apply(report) }
+        }
+        // The server side went away: nothing can re-check any more.
+        DispatchQueue.main.async { NSApp.terminate(nil) }
+    }
+}
+
+@main
+struct PermissionsWindow {
+    static func main() {
+        guard let first = readLine(strippingNewline: true),
+              let data = first.data(using: .utf8),
+              let message = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
+            exit(2)
+        }
+        if message["type"] as? String == "hello" {
+            send(["type": "hello", "protocolVersion": protocolVersion, "sourceSha256": helperSourceSHA256])
+            exit(0)
+        }
+        guard message["type"] as? String == "report", let report = message["report"] as? [String: Any] else {
+            exit(2)
+        }
+        let app = NSApplication.shared
+        let delegate = AppDelegate()
+        app.delegate = delegate
+        app.setActivationPolicy(.regular)
+        delegate.model.apply(report)
+        readReports(into: delegate)
+        app.run()
+    }
+}

package/native/public-helper/apple-notes-public-helper.swift

@@ -17,6 +17,8 @@
 //   encode_drawing  strokes -> PencilKit drawing bytes (base64); used to build
 //                   synthetic test fixtures, never to write to Notes
 //   transcribe      on-device Speech transcription of one audio file
+//   speech_status   the Speech Recognition authorization status, read without
+//                   prompting, and whether transcription would need a grant
 //
 // Build (done by `apple-notes-mcp setup --public-helper`, which also generates
 // the one-line source-digest file that defines helperSourceSHA256 and the
@@ -613,9 +615,22 @@ func transcribe(_ request: [String: Any]) async throws -> [String: Any] {
     return response
 }
 
+/// Reports what `transcribe` would find, without asking for access. On
+/// macOS 26+ SpeechAnalyzer needs no grant, so only an explicit refusal
+/// blocks it; earlier releases use the legacy recognizer, which needs one.
+func speechStatus() -> [String: Any] {
+    var requiresGrant = true
+    if #available(macOS 26, *) { requiresGrant = false }
+    return [
+        "status": "ok",
+        "speechAuthorization": authorizationName(SFSpeechRecognizer.authorizationStatus()),
+        "requiresGrant": requiresGrant,
+    ]
+}
+
 // MARK: - Dispatch
 
-let actions = ["hello", "decode_drawing", "encode_drawing", "transcribe"]
+let actions = ["hello", "decode_drawing", "encode_drawing", "transcribe", "speech_status"]
 
 func handle(_ request: [String: Any]) async throws -> [String: Any] {
     guard (request["protocol"] as? NSNumber)?.intValue == protocolVersion else {
@@ -635,6 +650,8 @@ func handle(_ request: [String: Any]) async throws -> [String: Any] {
         return try encodeDrawing(request)
     case "transcribe":
         return try await transcribe(request)
+    case "speech_status":
+        return speechStatus()
     default:
         throw HelperFailure(code: "unknown_action", message: "unknown action")
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "MCP server for Apple Notes - read, search, create, edit, organize, and export notes on macOS via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",