notes-poke 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# notes-poke
+
+A local MCP server that lets Poke work with Apple Notes on macOS.
+
+The server runs on your Mac, talks to Apple Notes through its documented AppleScript automation surface, and exposes a Streamable HTTP MCP endpoint at `/mcp` for Poke.
+
+## Quick Start
+
+For normal users:
+
+```bash
+npm install -g notes-poke && notes-poke install
+```
+
+That installs the official Apple Notes Poke connector, checks Notes, asks macOS for Automation permission if needed, starts the local MCP server, and connects it to Poke.
+
+Then ask Poke:
+
+```text
+Use my Apple Notes integration and search my recent notes.
+```
+
+For local development from this repository:
+
+```bash
+npm install
+npm run build
+npm run start
+```
+
+In another terminal:
+
+```bash
+npm run connect
+```
+
+Normal users should use `notes-poke install` instead of running tunnel commands manually.
+
+## How It Works
+
+Apple Notes stores its data locally on each user's Mac, so every user runs their own connector and gets their own Poke tunnel.
+
+```text
+User's Poke account
+  -> user's Poke tunnel
+    -> notes-poke running on the user's Mac
+      -> Apple Notes
+```
+
+The recipe should tell users to run:
+
+```bash
+npm install -g notes-poke && notes-poke install
+```
+
+That command signs in to Poke if needed, starts the local MCP server, creates the user's own tunnel, and keeps both running with macOS LaunchAgents.
+
+## CLI
+
+```bash
+notes-poke install
+notes-poke setup
+notes-poke start
+notes-poke connect
+notes-poke connect --recipe
+notes-poke status
+notes-poke uninstall
+```
+
+`notes-poke install` creates user LaunchAgents so the server and tunnel keep running in the background after the terminal exits. Logs are written to `~/.notes-poke/logs`.
+
+If you only want the local MCP server without starting a Poke tunnel:
+
+```bash
+notes-poke install --no-tunnel
+```
+
+To create a shareable Poke recipe while installing:
+
+```bash
+notes-poke install --recipe
+```
+
+## Optional Auth
+
+For localhost-only development, auth is off by default. To require a bearer token:
+
+```bash
+export NOTES_POKE_API_TOKEN="your-secret"
+notes-poke start
+```
+
+## Environment
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `NOTES_POKE_HOST` | `127.0.0.1` | HTTP bind host |
+| `NOTES_POKE_PORT` | `8766` | HTTP port |
+| `NOTES_POKE_API_TOKEN` | empty | Optional bearer token |
+
+## Scope
+
+This project exposes Apple Notes concepts available through AppleScript: accounts, folders, notes, attachments, selection, HTML body, plaintext search, create/update/append/delete/move, and reveal in Notes.
+
+Apple Notes hashtags are not exposed as native scriptable tag objects. The connector can search/extract hashtag-like text, but cannot manage Apple Notes tags as first-class objects.

package/dist/appleScript.js

@@ -0,0 +1,43 @@
+import { spawn } from "node:child_process";
+export async function runAppleScript(script, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    return await new Promise((resolve, reject) => {
+        const child = spawn("osascript", ["-"], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new Error(`AppleScript timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0) {
+                resolve(stdout.trim());
+                return;
+            }
+            reject(new Error(stderr.trim() || `osascript exited with code ${code}`));
+        });
+        child.stdin.end(script);
+    });
+}
+export function asString(value) {
+    return `"${value
+        .replaceAll("\\", "\\\\")
+        .replaceAll("\"", "\\\"")
+        .replaceAll("\r", "\\r")
+        .replaceAll("\n", "\\n")}"`;
+}

package/dist/cli.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { execFile, spawn } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { startServer } from "./server.js";
+import { getVersion } from "./notes.js";
+const program = new Command();
+const serverLabel = "com.notes-poke.server";
+const tunnelLabel = "com.notes-poke.tunnel";
+const cliPath = fileURLToPath(import.meta.url);
+const stateDir = join(homedir(), ".notes-poke");
+const logDir = join(stateDir, "logs");
+const launchAgentsDir = join(homedir(), "Library", "LaunchAgents");
+async function runSetup(options) {
+    await access("/usr/bin/osascript", constants.X_OK);
+    console.log("OK osascript is available");
+    await access("/System/Applications/Notes.app", constants.R_OK);
+    console.log("OK Notes.app found in /System/Applications");
+    if (options.touchNotes || options.touchThings) {
+        const version = await getVersion();
+        console.log(`OK Apple Notes responded: ${version}`);
+    }
+    else {
+        console.log("Tip: run `notes-poke setup --touch-notes` to request/check macOS Automation permission.");
+    }
+}
+function xmlEscape(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("\"", "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function userDomain() {
+    return `gui/${process.getuid?.() ?? ""}`;
+}
+function execFileAsync(file, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        execFile(file, args, (error, stdout, stderr) => {
+            const rawCode = error?.code;
+            const code = error ? (typeof rawCode === "number" ? rawCode : 1) : 0;
+            if (error && options.rejectOnError !== false) {
+                reject(new Error(stderr || stdout || error.message));
+                return;
+            }
+            resolve({ stdout, stderr, code });
+        });
+    });
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+async function runInteractive(command, args) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: "inherit" });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+        });
+    });
+}
+async function ensurePokeLogin() {
+    const whoami = await execFileAsync("npx", ["poke@latest", "whoami"], { rejectOnError: false });
+    if (whoami.code === 0) {
+        console.log(`OK Poke logged in as ${whoami.stdout.trim()}`);
+        return;
+    }
+    console.log("Poke CLI is not logged in yet. Starting `npx poke@latest login`...");
+    await runInteractive("npx", ["poke@latest", "login"]);
+}
+async function bootout(label, plistPath) {
+    await execFileAsync("launchctl", ["bootout", userDomain(), plistPath], { rejectOnError: false });
+    await execFileAsync("launchctl", ["bootout", userDomain(), label], { rejectOnError: false });
+}
+async function bootstrap(label, plistPath) {
+    await bootout(label, plistPath);
+    await execFileAsync("launchctl", ["bootstrap", userDomain(), plistPath]);
+    await execFileAsync("launchctl", ["kickstart", "-k", `${userDomain()}/${label}`], { rejectOnError: false });
+}
+async function writeLaunchAgent(path, body) {
+    await writeFile(path, body, "utf8");
+}
+function plist(label, args, stdout, stderr, env = {}) {
+    const envEntries = Object.entries(env)
+        .map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join("\n")}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(stateDir)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+${envEntries ? `\n${envEntries}` : ""}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(stdout)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(stderr)}</string>
+</dict>
+</plist>
+`;
+}
+async function installServices(options) {
+    await runSetup({ touchNotes: options.touchNotes ?? true });
+    if (options.tunnel) {
+        await ensurePokeLogin();
+    }
+    await mkdir(logDir, { recursive: true });
+    await mkdir(launchAgentsDir, { recursive: true });
+    const serverPlistPath = join(launchAgentsDir, `${serverLabel}.plist`);
+    const tunnelPlistPath = join(launchAgentsDir, `${tunnelLabel}.plist`);
+    const url = `http://localhost:${options.port}/mcp`;
+    const tunnelCommand = [
+        "exec",
+        "npx",
+        "poke@latest",
+        "tunnel",
+        url,
+        "-n",
+        shellQuote(options.name),
+        ...(options.recipe ? ["--recipe"] : []),
+    ].join(" ");
+    await writeLaunchAgent(serverPlistPath, plist(serverLabel, [process.execPath, cliPath, "start", "--host", options.host, "--port", options.port], join(logDir, "server.log"), join(logDir, "server.error.log"), {
+        NOTES_POKE_HOST: options.host,
+        NOTES_POKE_PORT: options.port,
+    }));
+    await bootstrap(serverLabel, serverPlistPath);
+    console.log(`OK installed and started ${serverLabel}`);
+    if (options.tunnel) {
+        await writeLaunchAgent(tunnelPlistPath, plist(tunnelLabel, ["/bin/zsh", "-lc", tunnelCommand], join(logDir, "tunnel.log"), join(logDir, "tunnel.error.log")));
+        await bootstrap(tunnelLabel, tunnelPlistPath);
+        console.log(`OK installed and started ${tunnelLabel}`);
+    }
+    console.log("");
+    console.log("Notes Poke is installed.");
+    console.log(`Local MCP server: ${url}`);
+    console.log(`Logs: ${logDir}`);
+    console.log("");
+    console.log("Try this in Poke:");
+    console.log("Use my Apple Notes integration and search my recent notes.");
+}
+async function uninstallServices() {
+    const serverPlistPath = join(launchAgentsDir, `${serverLabel}.plist`);
+    const tunnelPlistPath = join(launchAgentsDir, `${tunnelLabel}.plist`);
+    await bootout(tunnelLabel, tunnelPlistPath);
+    await bootout(serverLabel, serverPlistPath);
+    console.log("Stopped Notes Poke launch services. Plist files are left in ~/Library/LaunchAgents for inspection.");
+}
+async function status() {
+    for (const label of [serverLabel, tunnelLabel]) {
+        const result = await execFileAsync("launchctl", ["print", `${userDomain()}/${label}`], { rejectOnError: false });
+        if (result.code === 0) {
+            const state = result.stdout.match(/state = ([^\n]+)/)?.[1] ?? "unknown";
+            const pid = result.stdout.match(/pid = ([^\n]+)/)?.[1] ?? "not running";
+            console.log(`${label}: ${state}, pid ${pid}`);
+        }
+        else {
+            console.log(`${label}: not installed or not loaded`);
+        }
+    }
+    try {
+        const serverLog = await readFile(join(logDir, "server.log"), "utf8");
+        console.log(`\nLast server log:\n${serverLog.trim().split("\n").slice(-4).join("\n")}`);
+    }
+    catch {
+        // No logs yet.
+    }
+}
+program
+    .name("notes-poke")
+    .description("Local Apple Notes MCP server for Poke")
+    .version("0.1.0");
+program
+    .command("setup")
+    .description("Check local prerequisites for running the Apple Notes MCP server")
+    .option("--touch-notes", "Ask Apple Notes for its version, which may trigger macOS Automation permission")
+    .option("--touch-things", "Deprecated alias for --touch-notes")
+    .action(runSetup);
+program
+    .command("start")
+    .description("Start the local Streamable HTTP MCP server")
+    .option("--host <host>", "Host to bind", process.env.NOTES_POKE_HOST ?? "127.0.0.1")
+    .option("--port <port>", "Port to bind", process.env.NOTES_POKE_PORT ?? "8766")
+    .action((options) => {
+    const server = startServer({
+        host: options.host,
+        port: Number.parseInt(options.port, 10),
+    });
+    const shutdown = () => {
+        server.close(() => {
+            process.exit(0);
+        });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+});
+program
+    .command("connect")
+    .description("Connect the running local MCP server to Poke through the official Poke tunnel")
+    .option("--url <url>", "Local MCP server URL", "http://localhost:8766/mcp")
+    .option("-n, --name <name>", "Poke integration display name", "Apple Notes")
+    .option("--recipe", "Ask Poke CLI to create a shareable recipe link")
+    .action((options) => {
+    const args = ["poke@latest", "tunnel", options.url, "-n", options.name];
+    if (options.recipe) {
+        args.push("--recipe");
+    }
+    console.log(`Running: npx ${args.join(" ")}`);
+    const child = spawn("npx", args, {
+        stdio: "inherit",
+    });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
+    });
+});
+program
+    .command("install")
+    .description("One-shot install: check Apple Notes, create launchd services, start the MCP server, and connect Poke")
+    .option("-n, --name <name>", "Poke integration display name", "Apple Notes")
+    .option("--host <host>", "Host to bind", process.env.NOTES_POKE_HOST ?? "127.0.0.1")
+    .option("--port <port>", "Port to bind", process.env.NOTES_POKE_PORT ?? "8766")
+    .option("--recipe", "Ask Poke CLI to create a shareable recipe link from the tunnel")
+    .option("--no-tunnel", "Only install the local MCP server; do not start the Poke tunnel")
+    .option("--no-touch-notes", "Do not touch Apple Notes during setup")
+    .action((options) => installServices(options));
+program
+    .command("uninstall")
+    .description("Stop launchd services created by notes-poke install")
+    .action(uninstallServices);
+program
+    .command("status")
+    .description("Show launchd service state and recent logs")
+    .action(status);
+await program.parseAsync();

package/dist/index.js

@@ -0,0 +1,2 @@
+export { startServer } from "./server.js";
+export { createNotesPokeMcpServer } from "./mcp.js";

package/dist/mcp.js

@@ -0,0 +1,150 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { appendToNote, createFolder, createNote, deleteFolder, deleteNote, getAccounts, getAttachments, getFolders, getHashtags, getNote, getNotes, getSelection, getVersion, moveNote, searchNotes, showItem, updateNote, } from "./notes.js";
+function asContent(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+export function createNotesPokeMcpServer() {
+    const server = new McpServer({
+        name: "notes-poke",
+        version: "0.1.0",
+    }, {
+        capabilities: { logging: {} },
+        instructions: "Use these tools to operate the user's local Apple Notes app on macOS. Prefer search and small reads before broad reads. Use note and folder IDs for updates, moves, deletes, and reveals. Do not call destructive tools unless the user explicitly asks. Apple Notes exposes note bodies as HTML and plaintext; preserve user content carefully.",
+    });
+    server.registerTool("get_notes_info", {
+        title: "Get Notes Info",
+        description: "Check that Apple Notes is reachable and return its version.",
+        inputSchema: {},
+    }, async () => asContent({ version: await getVersion() }));
+    server.registerTool("get_accounts", {
+        title: "Get Accounts",
+        description: "List Apple Notes accounts and their default folders.",
+        inputSchema: {},
+    }, async () => asContent(await getAccounts()));
+    server.registerTool("get_folders", {
+        title: "Get Folders",
+        description: "List Apple Notes folders, optionally for a specific account.",
+        inputSchema: {
+            account: z.string().optional(),
+            limit: z.number().int().min(1).max(500).default(200),
+        },
+    }, async (args) => asContent(await getFolders(args)));
+    server.registerTool("get_notes", {
+        title: "Get Notes",
+        description: "List Apple Notes notes, optionally by folder or account. Use includeBody only when needed.",
+        inputSchema: {
+            folder: z.string().optional(),
+            account: z.string().optional(),
+            limit: z.number().int().min(1).max(200).default(30),
+            includeBody: z.boolean().default(false),
+        },
+    }, async (args) => asContent(await getNotes(args)));
+    server.registerTool("get_note", {
+        title: "Get Note",
+        description: "Read a single Apple Notes note by ID.",
+        inputSchema: {
+            id: z.string(),
+            includeBody: z.boolean().default(true),
+        },
+    }, async ({ id, includeBody }) => asContent(await getNote(id, includeBody)));
+    server.registerTool("search_notes", {
+        title: "Search Notes",
+        description: "Search Apple Notes by title and plaintext content.",
+        inputSchema: {
+            query: z.string(),
+            limit: z.number().int().min(1).max(200).default(30),
+        },
+    }, async ({ query, limit }) => asContent(await searchNotes(query, limit)));
+    server.registerTool("create_note", {
+        title: "Create Note",
+        description: "Create an Apple Notes note in the default folder, a named folder, or an account's default folder.",
+        inputSchema: {
+            title: z.string(),
+            body: z.string().optional(),
+            folder: z.string().optional(),
+            account: z.string().optional(),
+            reveal: z.boolean().default(false),
+        },
+    }, async (args) => asContent(await createNote(args)));
+    server.registerTool("update_note", {
+        title: "Update Note",
+        description: "Replace a note's body by ID. Provide title/body for simple plaintext-to-HTML content, or html for exact Apple Notes HTML.",
+        inputSchema: {
+            id: z.string(),
+            title: z.string().optional(),
+            body: z.string().optional(),
+            html: z.string().optional(),
+            replace: z.boolean().default(true),
+        },
+    }, async (args) => asContent(await updateNote(args)));
+    server.registerTool("append_to_note", {
+        title: "Append To Note",
+        description: "Append plaintext content to the end of an Apple Notes note by ID.",
+        inputSchema: {
+            id: z.string(),
+            text: z.string(),
+        },
+    }, async ({ id, text }) => asContent(await appendToNote(id, text)));
+    server.registerTool("create_folder", {
+        title: "Create Folder",
+        description: "Create an Apple Notes folder in the default account or a named account.",
+        inputSchema: {
+            name: z.string(),
+            account: z.string().optional(),
+        },
+    }, async ({ name, account }) => asContent(await createFolder(name, account)));
+    server.registerTool("move_note", {
+        title: "Move Note",
+        description: "Move a note by ID to a named Apple Notes folder.",
+        inputSchema: {
+            id: z.string(),
+            folder: z.string(),
+        },
+    }, async ({ id, folder }) => asContent(await moveNote(id, folder)));
+    server.registerTool("delete_note", {
+        title: "Delete Note",
+        description: "Delete an Apple Notes note by ID. Only use when the user explicitly asks.",
+        inputSchema: { id: z.string() },
+    }, async ({ id }) => asContent(await deleteNote(id)));
+    server.registerTool("delete_folder", {
+        title: "Delete Folder",
+        description: "Delete an Apple Notes folder by ID. Only use when the user explicitly asks.",
+        inputSchema: { id: z.string() },
+    }, async ({ id }) => asContent(await deleteFolder(id)));
+    server.registerTool("show_in_notes", {
+        title: "Show In Notes",
+        description: "Reveal a note, folder, or account in the Apple Notes app.",
+        inputSchema: {
+            type: z.enum(["note", "folder", "account"]),
+            id: z.string().optional(),
+            name: z.string().optional(),
+            separately: z.boolean().default(false),
+        },
+    }, async (args) => asContent(await showItem(args)));
+    server.registerTool("get_selection", {
+        title: "Get Selection",
+        description: "Return the currently selected note or notes in Apple Notes.",
+        inputSchema: {},
+    }, async () => asContent(await getSelection()));
+    server.registerTool("get_attachments", {
+        title: "Get Attachments",
+        description: "List attachments for an Apple Notes note by note ID.",
+        inputSchema: { noteId: z.string() },
+    }, async ({ noteId }) => asContent(await getAttachments(noteId)));
+    server.registerTool("get_hashtags", {
+        title: "Get Hashtags",
+        description: "Extract hashtag-like tokens from recent note plaintext. Apple Notes tags are not exposed as native scriptable objects.",
+        inputSchema: {
+            limit: z.number().int().min(1).max(500).default(100),
+        },
+    }, async ({ limit }) => asContent(await getHashtags(limit)));
+    return server;
+}

package/dist/notes.js

@@ -0,0 +1,420 @@
+import { asString, runAppleScript } from "./appleScript.js";
+function parseJson(text) {
+    return JSON.parse(text);
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("\"", "&quot;");
+}
+function paragraphs(value) {
+    return value
+        .split(/\n{2,}/)
+        .map((paragraph) => `<p>${escapeHtml(paragraph).replaceAll("\n", "<br>")}</p>`)
+        .join("");
+}
+function noteHtml(title, body = "") {
+    return `<h1>${escapeHtml(title)}</h1>${paragraphs(body)}`;
+}
+export const notesAppleScriptLibrary = String.raw `
+on replaceText(findText, replaceText, sourceText)
+  set oldDelimiters to AppleScript's text item delimiters
+  set AppleScript's text item delimiters to findText
+  set textItems to text items of sourceText
+  set AppleScript's text item delimiters to replaceText
+  set joinedText to textItems as text
+  set AppleScript's text item delimiters to oldDelimiters
+  return joinedText
+end replaceText
+
+on jsonEscape(sourceValue)
+  if sourceValue is missing value then return ""
+  set sourceText to sourceValue as text
+  set sourceText to my replaceText("\\", "\\\\", sourceText)
+  set sourceText to my replaceText("\"", "\\\"", sourceText)
+  set sourceText to my replaceText(linefeed, "\\n", sourceText)
+  set sourceText to my replaceText(return, "\\n", sourceText)
+  set sourceText to my replaceText(tab, "\\t", sourceText)
+  return sourceText
+end jsonEscape
+
+on jsonString(sourceValue)
+  return "\"" & my jsonEscape(sourceValue) & "\""
+end jsonString
+
+on jsonBool(sourceValue)
+  if sourceValue then return "true"
+  return "false"
+end jsonBool
+
+on pad2(n)
+  set nText to n as integer as text
+  if length of nText is 1 then return "0" & nText
+  return nText
+end pad2
+
+on isoDate(d)
+  if d is missing value then return ""
+  try
+    set y to year of d as integer
+    set m to month of d as integer
+    set dayNumber to day of d as integer
+    set h to hours of d as integer
+    set minNumber to minutes of d as integer
+    set secNumber to seconds of d as integer
+    return (y as text) & "-" & my pad2(m) & "-" & my pad2(dayNumber) & "T" & my pad2(h) & ":" & my pad2(minNumber) & ":" & my pad2(secNumber)
+  on error
+    return d as text
+  end try
+end isoDate
+
+on findNoteById(noteId)
+  tell application "Notes"
+    repeat with n in notes
+      if id of n is noteId then return n
+    end repeat
+  end tell
+  error "No Apple Notes note found with id " & noteId
+end findNoteById
+
+on findFolderById(folderId)
+  tell application "Notes"
+    repeat with f in folders
+      if id of f is folderId then return f
+    end repeat
+  end tell
+  error "No Apple Notes folder found with id " & folderId
+end findFolderById
+
+on folderJson(f)
+  tell application "Notes"
+    set containerName to ""
+    set containerId to ""
+    set containerKind to ""
+    try
+      set containerName to name of container of f
+      set containerId to id of container of f
+      set containerKind to class of container of f as text
+    end try
+    return "{" & ¬
+      "\"id\":" & my jsonString(id of f) & "," & ¬
+      "\"name\":" & my jsonString(name of f) & "," & ¬
+      "\"shared\":" & my jsonBool(shared of f) & "," & ¬
+      "\"containerId\":" & my jsonString(containerId) & "," & ¬
+      "\"container\":" & my jsonString(containerName) & "," & ¬
+      "\"containerKind\":" & my jsonString(containerKind) & "," & ¬
+      "\"noteCount\":" & (count of notes of f as text) & ¬
+    "}"
+  end tell
+end folderJson
+
+on noteJson(n, includeBody)
+  tell application "Notes"
+    set folderName to ""
+    set folderId to ""
+    try
+      set folderName to name of container of n
+      set folderId to id of container of n
+    end try
+    set bodyText to ""
+    if includeBody then
+      try
+        set bodyText to body of n
+      end try
+    end if
+    return "{" & ¬
+      "\"id\":" & my jsonString(id of n) & "," & ¬
+      "\"title\":" & my jsonString(name of n) & "," & ¬
+      "\"plaintext\":" & my jsonString(plaintext of n) & "," & ¬
+      "\"body\":" & my jsonString(bodyText) & "," & ¬
+      "\"folderId\":" & my jsonString(folderId) & "," & ¬
+      "\"folder\":" & my jsonString(folderName) & "," & ¬
+      "\"createdAt\":" & my jsonString(my isoDate(creation date of n)) & "," & ¬
+      "\"modifiedAt\":" & my jsonString(my isoDate(modification date of n)) & "," & ¬
+      "\"passwordProtected\":" & my jsonBool(password protected of n) & "," & ¬
+      "\"shared\":" & my jsonBool(shared of n) & "," & ¬
+      "\"attachmentCount\":" & (count of attachments of n as text) & ¬
+    "}"
+  end tell
+end noteJson
+`;
+export async function getVersion() {
+    return await runAppleScript(`
+tell application "Notes"
+  return version
+end tell
+`);
+}
+export async function getAccounts() {
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+set rows to {}
+tell application "Notes"
+  repeat with a in accounts
+    set defaultFolderName to ""
+    set defaultFolderId to ""
+    try
+      set defaultFolderName to name of default folder of a
+      set defaultFolderId to id of default folder of a
+    end try
+    set end of rows to "{" & ¬
+      "\\"id\\":" & my jsonString(id of a) & "," & ¬
+      "\\"name\\":" & my jsonString(name of a) & "," & ¬
+      "\\"upgraded\\":" & my jsonBool(upgraded of a) & "," & ¬
+      "\\"defaultFolderId\\":" & my jsonString(defaultFolderId) & "," & ¬
+      "\\"defaultFolder\\":" & my jsonString(defaultFolderName) & "," & ¬
+      "\\"folderCount\\":" & (count of folders of a as text) & "," & ¬
+      "\\"noteCount\\":" & (count of notes of a as text) & ¬
+    "}"
+  end repeat
+end tell
+set oldDelimiters to AppleScript's text item delimiters
+set AppleScript's text item delimiters to ","
+set jsonText to rows as text
+set AppleScript's text item delimiters to oldDelimiters
+return "[" & jsonText & "]"
+`);
+    return parseJson(output);
+}
+export async function getFolders(options = {}) {
+    const limit = Math.max(1, Math.min(options.limit ?? 200, 500));
+    const source = options.account ? `folders of account ${asString(options.account)}` : "folders";
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+set rows to {}
+tell application "Notes"
+  set itemCount to 0
+  repeat with f in ${source}
+    set itemCount to itemCount + 1
+    if itemCount is greater than ${limit} then exit repeat
+    set end of rows to my folderJson(f)
+  end repeat
+end tell
+set oldDelimiters to AppleScript's text item delimiters
+set AppleScript's text item delimiters to ","
+set jsonText to rows as text
+set AppleScript's text item delimiters to oldDelimiters
+return "[" & jsonText & "]"
+`);
+    return parseJson(output);
+}
+export async function getNotes(options = {}) {
+    const limit = Math.max(1, Math.min(options.limit ?? 30, 200));
+    const source = options.folder ? `notes of folder ${asString(options.folder)}` :
+        options.account ? `notes of account ${asString(options.account)}` :
+            "notes";
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+set rows to {}
+tell application "Notes"
+  set itemCount to 0
+  repeat with n in ${source}
+    set itemCount to itemCount + 1
+    if itemCount is greater than ${limit} then exit repeat
+    set end of rows to my noteJson(n, ${options.includeBody ? "true" : "false"})
+  end repeat
+end tell
+set oldDelimiters to AppleScript's text item delimiters
+set AppleScript's text item delimiters to ","
+set jsonText to rows as text
+set AppleScript's text item delimiters to oldDelimiters
+return "[" & jsonText & "]"
+`);
+    return parseJson(output);
+}
+export async function getNote(id, includeBody = true) {
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set targetNote to my findNoteById(${asString(id)})
+  return my noteJson(targetNote, ${includeBody ? "true" : "false"})
+end tell
+`);
+    return parseJson(output);
+}
+export async function searchNotes(query, limit = 30) {
+    const safeLimit = Math.max(1, Math.min(limit, 200));
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+set rows to {}
+set needle to ${asString(query)}
+tell application "Notes"
+  set itemCount to 0
+  repeat with n in notes
+    set haystack to (name of n & linefeed & plaintext of n)
+    if haystack contains needle then
+      set itemCount to itemCount + 1
+      if itemCount is greater than ${safeLimit} then exit repeat
+      set end of rows to my noteJson(n, false)
+    end if
+  end repeat
+end tell
+set oldDelimiters to AppleScript's text item delimiters
+set AppleScript's text item delimiters to ","
+set jsonText to rows as text
+set AppleScript's text item delimiters to oldDelimiters
+return "[" & jsonText & "]"
+`);
+    return parseJson(output);
+}
+export async function createNote(input) {
+    const html = noteHtml(input.title, input.body);
+    const destination = input.folder ? ` at folder ${asString(input.folder)}` :
+        input.account ? ` at default folder of account ${asString(input.account)}` :
+            " at default folder of default account";
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set newNote to make new note${destination} with properties {body:${asString(html)}}
+  if ${input.reveal ? "true" : "false"} then show newNote
+  return my noteJson(newNote, true)
+end tell
+`);
+    return parseJson(output);
+}
+export async function updateNote(input) {
+    const bodyHtml = input.html ?? (input.title !== undefined || input.body !== undefined ? noteHtml(input.title ?? "Untitled", input.body ?? "") : undefined);
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set targetNote to my findNoteById(${asString(input.id)})
+  ${bodyHtml !== undefined ? `set body of targetNote to ${input.replace === false ? `(body of targetNote) & ${asString(bodyHtml)}` : asString(bodyHtml)}` : ""}
+  return my noteJson(targetNote, true)
+end tell
+`);
+    return parseJson(output);
+}
+export async function appendToNote(id, text) {
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set targetNote to my findNoteById(${asString(id)})
+  set body of targetNote to (body of targetNote) & ${asString(paragraphs(text))}
+  return my noteJson(targetNote, true)
+end tell
+`);
+    return parseJson(output);
+}
+export async function createFolder(name, account) {
+    const destination = account ? ` at account ${asString(account)}` : " at default account";
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set newFolder to make new folder${destination} with properties {name:${asString(name)}}
+  return my folderJson(newFolder)
+end tell
+`);
+    return parseJson(output);
+}
+export async function deleteNote(id) {
+    return await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set targetNote to my findNoteById(${asString(id)})
+  delete targetNote
+  return "Deleted note: ${id}"
+end tell
+`);
+}
+export async function deleteFolder(id) {
+    return await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set targetFolder to my findFolderById(${asString(id)})
+  delete targetFolder
+  return "Deleted folder: ${id}"
+end tell
+`);
+}
+export async function moveNote(id, folder) {
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  set targetNote to my findNoteById(${asString(id)})
+  move targetNote to folder ${asString(folder)}
+  return my noteJson(targetNote, false)
+end tell
+`);
+    return parseJson(output);
+}
+export async function showItem(input) {
+    const target = input.type === "note" && input.id ? `my findNoteById(${asString(input.id)})` :
+        input.type === "folder" && input.id ? `my findFolderById(${asString(input.id)})` :
+            input.type === "folder" && input.name ? `folder ${asString(input.name)}` :
+                input.type === "account" && input.name ? `account ${asString(input.name)}` :
+                    undefined;
+    if (!target) {
+        throw new Error("Provide a valid id or name for the requested Apple Notes item type.");
+    }
+    return await runAppleScript(`
+${notesAppleScriptLibrary}
+tell application "Notes"
+  show ${target}${input.separately ? " separately true" : ""}
+  return "Shown in Notes"
+end tell
+`);
+}
+export async function getSelection() {
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+set rows to {}
+tell application "Notes"
+  repeat with n in selection
+    set end of rows to my noteJson(n, false)
+  end repeat
+end tell
+set oldDelimiters to AppleScript's text item delimiters
+set AppleScript's text item delimiters to ","
+set jsonText to rows as text
+set AppleScript's text item delimiters to oldDelimiters
+return "[" & jsonText & "]"
+`);
+    return parseJson(output);
+}
+export async function getAttachments(noteId) {
+    const output = await runAppleScript(`
+${notesAppleScriptLibrary}
+set rows to {}
+tell application "Notes"
+  set targetNote to my findNoteById(${asString(noteId)})
+  repeat with a in attachments of targetNote
+    set attachmentUrl to ""
+    try
+      set attachmentUrl to URL of a
+    end try
+    set end of rows to "{" & ¬
+      "\\"id\\":" & my jsonString(id of a) & "," & ¬
+      "\\"name\\":" & my jsonString(name of a) & "," & ¬
+      "\\"url\\":" & my jsonString(attachmentUrl) & "," & ¬
+      "\\"contentIdentifier\\":" & my jsonString(content identifier of a) & "," & ¬
+      "\\"createdAt\\":" & my jsonString(my isoDate(creation date of a)) & "," & ¬
+      "\\"modifiedAt\\":" & my jsonString(my isoDate(modification date of a)) & "," & ¬
+      "\\"shared\\":" & my jsonBool(shared of a) & ¬
+    "}"
+  end repeat
+end tell
+set oldDelimiters to AppleScript's text item delimiters
+set AppleScript's text item delimiters to ","
+set jsonText to rows as text
+set AppleScript's text item delimiters to oldDelimiters
+return "[" & jsonText & "]"
+`);
+    return parseJson(output);
+}
+export async function getHashtags(limit = 100) {
+    const output = await runAppleScript(`
+set allText to ""
+tell application "Notes"
+  set itemCount to 0
+  repeat with n in notes
+    set itemCount to itemCount + 1
+    if itemCount is greater than ${Math.max(1, Math.min(limit, 500))} then exit repeat
+    set allText to allText & " " & plaintext of n
+  end repeat
+end tell
+do shell script "/usr/bin/python3 -c " & quoted form of "import re,sys,json; print(json.dumps(sorted(set(re.findall(r'(?<!\\\\w)#[-_A-Za-z0-9]+', sys.stdin.read())))))" with input allText
+`);
+    return parseJson(output);
+}

package/dist/server.js

@@ -0,0 +1,102 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { createNotesPokeMcpServer } from "./mcp.js";
+function bearerAuth(token) {
+    return (req, res, next) => {
+        if (!token) {
+            next();
+            return;
+        }
+        const authorization = req.header("Authorization") ?? "";
+        if (authorization === `Bearer ${token}`) {
+            next();
+            return;
+        }
+        res.status(401).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32001,
+                message: "Unauthorized",
+            },
+            id: null,
+        });
+    };
+}
+function isMcpPath(path) {
+    return path === "/mcp" || path.endsWith("/mcp");
+}
+const mcpRoutePattern = /^(?:\/[^/]+)*\/mcp$/;
+export function startServer(options = {}) {
+    const host = options.host ?? process.env.NOTES_POKE_HOST ?? "127.0.0.1";
+    const port = options.port ?? Number.parseInt(process.env.NOTES_POKE_PORT ?? "8766", 10);
+    const apiToken = options.apiToken ?? process.env.NOTES_POKE_API_TOKEN;
+    const app = createMcpExpressApp({ host });
+    app.get("/", (_req, res) => {
+        res.json({
+            name: "notes-poke",
+            status: "ok",
+            mcp: "/mcp",
+            tunnelCompatibleMcp: "/*/mcp",
+            auth: apiToken ? "bearer" : "none",
+        });
+    });
+    app.use((req, res, next) => {
+        if (!isMcpPath(req.path)) {
+            next();
+            return;
+        }
+        bearerAuth(apiToken)(req, res, next);
+    });
+    app.post(mcpRoutePattern, async (req, res) => {
+        const server = createNotesPokeMcpServer();
+        try {
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            res.on("close", () => {
+                transport.close().catch(() => undefined);
+                server.close().catch(() => undefined);
+            });
+        }
+        catch (error) {
+            console.error("Error handling MCP request:", error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Internal server error",
+                    },
+                    id: null,
+                });
+            }
+        }
+    });
+    app.get(mcpRoutePattern, (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed. POST JSON-RPC requests to /mcp or a tunnel-prefixed /*/mcp path.",
+            },
+            id: null,
+        });
+    });
+    app.delete(mcpRoutePattern, (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed.",
+            },
+            id: null,
+        });
+    });
+    const httpServer = app.listen(port, host, () => {
+        console.log(`notes-poke MCP server listening at http://${host}:${port}/mcp`);
+        console.log(apiToken ? "Bearer auth enabled via NOTES_POKE_API_TOKEN" : "Bearer auth disabled for localhost development");
+    });
+    return httpServer;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "notes-poke",
+  "version": "0.1.0",
+  "description": "Local Apple Notes MCP server for Poke",
+  "type": "module",
+  "main": "dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ysmaliak/notes-poke.git"
+  },
+  "homepage": "https://github.com/ysmaliak/notes-poke#readme",
+  "bugs": {
+    "url": "https://github.com/ysmaliak/notes-poke/issues"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "notes-poke": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/cli.ts start",
+    "setup": "tsx src/cli.ts setup",
+    "connect": "tsx src/cli.ts connect",
+    "dev": "tsx src/cli.ts start",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "keywords": [
+    "notes",
+    "apple-notes",
+    "poke",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.2",
+    "express": "^5.2.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.10.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}