apple-notes-mcp 1.4.4 → 2.0.0

package/README.md

@@ -86,12 +86,21 @@ On first use, macOS will ask for permission to automate Notes.app. Click "OK" to
 | **Folder Management** | Create, list, and delete folders with full hierarchical path support |
 | **Multi-Account** | Work with iCloud, Gmail, Exchange, or any configured account |
 | **Batch Operations** | Delete or move multiple notes at once |
-| **Checklist State** | Read checklist done/undone state directly from the Notes database |
+| **Checklist State** | Read checklist done/undone state directly from the Notes database (requires Full Disk Access) |
 | **Export** | Export all notes as JSON or get individual notes as Markdown |
-| **Attachments** | List attachments in notes |
+| **Attachments** | List attachments, save them to disk, or fetch their bytes as base64 |
 | **Sync Awareness** | Detect iCloud sync in progress, warn about incomplete results |
 | **Collaboration** | Detect shared notes, warn before modifying |
-| **Diagnostics** | Health check, sync status, and statistics tools |
+| **Diagnostics** | `health-check` plus a richer `doctor` (reachability, automation permission, accounts, Full Disk Access), sync status, and statistics |
+
+Read/list/get tools also return **structured JSON** (`structuredContent`) alongside the text, so agents can consume results without parsing prose.
+
+### MCP resources & prompts
+
+Resources expose read-only context the client can attach without a tool call:
+`notes://accounts`, `notes://folders`, `notes://stats`, and the
+`notes://note/{id}` template (returns the note as Markdown). Prompts package
+common workflows: `find-note`, `weekly-review`, `new-meeting-note`.
 
 ---
 
@@ -587,6 +596,33 @@ Lists attachments in a note.
 
 ---
 
+#### `save-attachment`
+
+Saves a note attachment to disk.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `noteId` | string | Yes | CoreData note ID (from `search-notes`/`list-notes`) |
+| `attachmentId` | string | Yes | Attachment ID (from `list-attachments`) |
+| `savePath` | string | Yes | Absolute destination file path. Must be under your home directory, a temp directory, or `/Volumes` |
+
+**Returns:** Confirmation with the saved path, name, and content type (also in `structuredContent`).
+
+---
+
+#### `fetch-attachment`
+
+Returns a note attachment's bytes as base64, without writing to disk (the read counterpart to `save-attachment`).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `noteId` | string | Yes | CoreData note ID (from `search-notes`/`list-notes`) |
+| `attachmentId` | string | Yes | Attachment ID (from `list-attachments`) |
+
+**Returns:** The attachment name, content type, byte count, and base64 payload in `structuredContent.base64`.
+
+---
+
 ### Diagnostics
 
 #### `health-check`
@@ -599,6 +635,16 @@ Verifies Notes.app connectivity and permissions.
 
 ---
 
+#### `doctor`
+
+Run a full setup diagnostic: Notes.app reachability, the Automation permission, configured accounts, and Full Disk Access — each reported as ok / warn / fail with an actionable message. This is the richer counterpart to `health-check`; reach for it first when something isn't working.
+
+**Parameters:** None
+
+**Returns:** A per-check report (`structuredContent` carries the raw `{healthy, checks[]}`). The Full Disk Access check tells you whether checklist-state features will work — see [Full Disk Access Setup](docs/FULL-DISK-ACCESS.md).
+
+---
+
 #### `get-notes-stats`
 
 Gets comprehensive statistics about your notes.
@@ -730,10 +776,46 @@ The entrypoint is written as:
 
 ---
 
+## Configuration
+
+### Environment variables
+
+All configuration is optional — the server works out of the box. Override behavior with these variables (set them in your MCP client's `env` block, or via the [config file](#configuration-file-when-the-host-strips-env) below):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `APPLE_NOTES_MCP_MAX_BUFFER` | `67108864` (64 MB) | Max bytes captured from a single AppleScript invocation. Raise it if a very large export/list is truncated; lower it to cap memory. |
+| `APPLE_NOTES_MCP_CONFIG_FILE` | `~/Library/Application Support/apple-notes-mcp/config.json` | Path to the JSON config file (see below). |
+| `DEBUG` / `VERBOSE` | unset | Set either to enable verbose diagnostic logging to stderr. |
+
+### Configuration file (when the host strips `env`)
+
+Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed
+environment and ignore the `env` block in their server config, so there's no way
+to pass `APPLE_NOTES_MCP_*` settings through it. In that case, put them in a JSON
+file the host doesn't manage — `APPLE_NOTES_MCP_CONFIG_FILE`, or by default
+`~/Library/Application Support/apple-notes-mcp/config.json`:
+
+```json
+{
+  "APPLE_NOTES_MCP_MAX_BUFFER": "134217728",
+  "DEBUG": "1"
+}
+```
+
+The server reads it at startup and merges values into the environment **without
+overriding** anything already set there (so an explicit `env` still wins). This
+is the recommended way to configure the server under Claude Desktop. Apple Notes
+MCP stores no secrets, but as a general rule keep only non-secret config here.
+
+---
+
 ## Full Disk Access for Checklist Features
 
 The `get-checklist-state` tool and checklist annotations in `get-note-markdown` read directly from the Apple Notes SQLite database. This requires **Full Disk Access** for the process running the MCP server.
 
+> 📘 **For the full why-and-how walkthrough (which app to grant, verifying with `doctor`, graceful degradation), see the [Full Disk Access Setup Guide](docs/FULL-DISK-ACCESS.md).** The summary below is the quick version.
+
 ### How to Grant Full Disk Access
 
 1. Open **System Settings** (or System Preferences on older macOS)
@@ -768,13 +850,22 @@ All other tools work normally without Full Disk Access. Only checklist state fea
 | Limitation | Reason |
 |------------|--------|
 | macOS only | Apple Notes and AppleScript are macOS-specific |
-| No attachment content | Attachments can be listed but not downloaded via AppleScript |
-| No pinned notes | Pin status is not exposed via AppleScript |
+| Batch ops run per-note | `batch-delete-notes` / `batch-move-notes` apply each note individually rather than as one bulk operation — AppleScript has no bulk equivalent to IMAP's `UID STORE`/`MOVE`. This is deliberate: it preserves per-note success/failure reporting. ([#26](https://github.com/sweetrb/apple-notes-mcp/issues/26)) |
+| No pinned notes | Pin status is not exposed via AppleScript ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) |
 | Limited rich formatting | Use `format: "html"` on create/update for headings, lists, bold, code blocks; some complex formatting may not render |
 | Title matching | Most operations require exact title matches |
-| Checklist state | Requires Full Disk Access to read done/undone state from the database |
+| Checklist state | Requires [Full Disk Access](docs/FULL-DISK-ACCESS.md) to read done/undone state from the database |
 | Checklist **creation** | Not supported. AppleScript's `body of note` setter strips `<input type="checkbox">` and ignores any checklist-styling CSS class. Apple Notes stores checklist items as a protobuf paragraph style (`style_type=103`) that AppleScript doesn't expose, and the SQLite database is read-only. See [Creating Checklists](#creating-checklists) below for the workaround. |
 
+### Roadmap
+
+A few capabilities are deliberately deferred to a future release, tracked as open issues:
+
+- **Pinned-note support** ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) — Apple doesn't expose pin status via AppleScript.
+- **Tags / hashtags** ([#29](https://github.com/sweetrb/apple-notes-mcp/issues/29)).
+- **Note links** ([#30](https://github.com/sweetrb/apple-notes-mcp/issues/30)).
+- **Local integration-test suite** ([#31](https://github.com/sweetrb/apple-notes-mcp/issues/31)).
+
 ### Creating Checklists
 
 **There is no programmatic way to create a true Apple Notes checklist via AppleScript** — and therefore no way via this MCP server. This is an Apple limitation, not a bug.

package/build/index.js

@@ -27,6 +27,12 @@ import { AppleNotesManager } from "./services/appleNotesManager.js";
 import { getSyncStatus, withSyncAwarenessSync } from "./utils/syncDetection.js";
 import { getChecklistItems, hasFullDiskAccess } from "./utils/checklistParser.js";
 import { detectChecklistAttempt } from "./utils/contentWarnings.js";
+import { runDoctor, formatDoctorReport } from "./tools/doctor.js";
+import { loadFileConfig } from "./services/fileConfig.js";
+import { registerResourcesAndPrompts } from "./tools/resourcesAndPrompts.js";
+// Load file-based config FIRST (#24) — before anything reads APPLE_NOTES_MCP_*.
+// Lets users configure the server when the host app strips the MCP env block.
+loadFileConfig();
 // Read version from package.json to keep it in sync
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -46,25 +52,19 @@ const server = new McpServer({
  * Handles all AppleScript execution and note operations.
  */
 const notesManager = new AppleNotesManager();
-// =============================================================================
-// Response Helpers
-// =============================================================================
 /**
- * Creates a successful MCP tool response.
- *
- * @param message - The success message to display
- * @returns Formatted MCP response object
+ * Creates a successful MCP tool response. Pass `structured` to attach typed JSON
+ * (`structuredContent`) alongside the human-readable text so agents can consume
+ * results without parsing prose (#21).
  */
-function successResponse(message) {
-    return {
-        content: [{ type: "text", text: message }],
-    };
+function successResponse(message, structured) {
+    const res = { content: [{ type: "text", text: message }] };
+    if (structured)
+        res.structuredContent = structured;
+    return res;
 }
 /**
  * Creates an error MCP tool response.
- *
- * @param message - The error message to display
- * @returns Formatted MCP error response object
  */
 function errorResponse(message) {
     return {
@@ -74,10 +74,6 @@ function errorResponse(message) {
 }
 /**
  * Wraps a tool handler with consistent error handling.
- *
- * @param handler - The async function to execute
- * @param errorPrefix - Prefix for error messages (e.g., "Error creating note")
- * @returns Wrapped handler with try/catch
  */
 function withErrorHandling(handler, errorPrefix) {
     return async (params) => {
@@ -164,7 +160,7 @@ server.tool("search-notes", {
     }
     const syncNote = syncWarnings.length > 0 ? `\n\n${syncWarnings.join(" ")}` : "";
     if (notes.length === 0) {
-        return successResponse(`No notes found matching "${query}" in ${searchType}${folderInfo}${dateInfo}${syncNote}`);
+        return successResponse(`No notes found matching "${query}" in ${searchType}${folderInfo}${dateInfo}${syncNote}`, { notes: [], count: 0 });
     }
     // Format each note with ID and folder info, highlighting Recently Deleted
     const noteList = notes
@@ -179,7 +175,7 @@ server.tool("search-notes", {
         return `  - ${n.title}${idSuffix}`;
     })
         .join("\n");
-    return successResponse(`Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):\n${noteList}${syncNote}`);
+    return successResponse(`Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):\n${noteList}${syncNote}`, { notes, count: notes.length });
 }, "Error searching notes"));
 // --- get-note-content ---
 server.tool("get-note-content", {
@@ -204,7 +200,7 @@ server.tool("get-note-content", {
         if (!content) {
             return errorResponse(`Failed to read content of note "${note.title}"`);
         }
-        return successResponse(content);
+        return successResponse(content, { title: note.title, content });
     }
     // Fall back to title-based lookup
     if (!title) {
@@ -222,7 +218,7 @@ server.tool("get-note-content", {
     if (!content) {
         return errorResponse(`Failed to read content of note "${title}"`);
     }
-    return successResponse(content);
+    return successResponse(content, { title, content });
 }, "Error retrieving note content"));
 // --- get-note-by-id ---
 server.tool("get-note-by-id", {
@@ -241,7 +237,7 @@ server.tool("get-note-by-id", {
         shared: note.shared,
         passwordProtected: note.passwordProtected,
     };
-    return successResponse(JSON.stringify(metadata, null, 2));
+    return successResponse(JSON.stringify(metadata, null, 2), metadata);
 }, "Error retrieving note"));
 // --- get-note-details ---
 server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, account }) => {
@@ -259,7 +255,7 @@ server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, acc
         passwordProtected: note.passwordProtected,
         account: note.account,
     };
-    return successResponse(JSON.stringify(metadata, null, 2));
+    return successResponse(JSON.stringify(metadata, null, 2), metadata);
 }, "Error retrieving note details"));
 // --- update-note ---
 server.tool("update-note", {
@@ -433,10 +429,13 @@ server.tool("list-notes", {
     }
     const syncNote = syncWarnings.length > 0 ? `\n\n${syncWarnings.join(" ")}` : "";
     if (notes.length === 0) {
-        return successResponse(`No notes found${location}${acct}${dateInfo}${syncNote}`);
+        return successResponse(`No notes found${location}${acct}${dateInfo}${syncNote}`, {
+            notes: [],
+            count: 0,
+        });
     }
     const noteList = notes.map((t) => `  - ${t}`).join("\n");
-    return successResponse(`Found ${notes.length} notes${location}${acct}${dateInfo}${limitInfo}:\n${noteList}${syncNote}`);
+    return successResponse(`Found ${notes.length} notes${location}${acct}${dateInfo}${limitInfo}:\n${noteList}${syncNote}`, { notes, count: notes.length });
 }, "Error listing notes"));
 // =============================================================================
 // Folder Tools
@@ -458,10 +457,13 @@ server.tool("list-folders", {
     }
     const syncNote = syncWarnings.length > 0 ? `\n\n${syncWarnings.join(" ")}` : "";
     if (folders.length === 0) {
-        return successResponse(`No folders found${acct}${syncNote}`);
+        return successResponse(`No folders found${acct}${syncNote}`, { folders: [], count: 0 });
     }
     const folderList = folders.map((f) => `  - ${f.name}`).join("\n");
-    return successResponse(`Found ${folders.length} folders${acct}:\n${folderList}${syncNote}`);
+    return successResponse(`Found ${folders.length} folders${acct}:\n${folderList}${syncNote}`, {
+        folders,
+        count: folders.length,
+    });
 }, "Error listing folders"));
 // --- create-folder ---
 server.tool("create-folder", {
@@ -492,10 +494,13 @@ server.tool("delete-folder", folderNameSchema, withErrorHandling(({ name, accoun
 server.tool("list-accounts", {}, withErrorHandling(() => {
     const accounts = notesManager.listAccounts();
     if (accounts.length === 0) {
-        return successResponse("No Notes accounts found");
+        return successResponse("No Notes accounts found", { accounts: [], count: 0 });
     }
     const accountList = accounts.map((a) => `  - ${a.name}`).join("\n");
-    return successResponse(`Found ${accounts.length} accounts:\n${accountList}`);
+    return successResponse(`Found ${accounts.length} accounts:\n${accountList}`, {
+        accounts,
+        count: accounts.length,
+    });
 }, "Error listing accounts"));
 // =============================================================================
 // Collaboration Tools
@@ -504,7 +509,7 @@ server.tool("list-accounts", {}, withErrorHandling(() => {
 server.tool("list-shared-notes", {}, withErrorHandling(() => {
     const sharedNotes = notesManager.listSharedNotes();
     if (sharedNotes.length === 0) {
-        return successResponse("No shared notes found. You have no notes shared with collaborators.");
+        return successResponse("No shared notes found. You have no notes shared with collaborators.", { notes: [], count: 0 });
     }
     const noteList = sharedNotes
         .map((n) => {
@@ -513,7 +518,7 @@ server.tool("list-shared-notes", {}, withErrorHandling(() => {
     })
         .join("\n");
     return successResponse(`Found ${sharedNotes.length} shared note(s):\n${noteList}\n\n` +
-        `⚠️ Changes to shared notes are visible to all collaborators.`);
+        `⚠️ Changes to shared notes are visible to all collaborators.`, { notes: sharedNotes, count: sharedNotes.length });
 }, "Error listing shared notes"));
 // =============================================================================
 // Diagnostics Tools
@@ -522,7 +527,7 @@ server.tool("list-shared-notes", {}, withErrorHandling(() => {
 server.tool("get-sync-status", {}, withErrorHandling(() => {
     const status = getSyncStatus();
     if (status.error) {
-        return successResponse(`⚠️ Sync status unknown: ${status.error}`);
+        return successResponse(`⚠️ Sync status unknown: ${status.error}`, { ...status });
     }
     const lines = [];
     if (status.syncDetected) {
@@ -542,7 +547,7 @@ server.tool("get-sync-status", {}, withErrorHandling(() => {
         lines.push("");
         lines.push(`  Last activity: ${status.secondsSinceLastChange}s ago`);
     }
-    return successResponse(lines.join("\n"));
+    return successResponse(lines.join("\n"), { ...status });
 }, "Error checking sync status"));
 // --- health-check ---
 server.tool("health-check", {}, withErrorHandling(() => {
@@ -562,6 +567,13 @@ server.tool("health-check", {}, withErrorHandling(() => {
         : "  ⓘ full_disk_access: Not granted (optional — needed for get-checklist-state and checklist annotations in get-note-markdown). Grant in System Settings > Privacy & Security > Full Disk Access.";
     return successResponse(`${statusIcon} ${statusText}\n\n${checkLines}\n${fdaLine}`);
 }, "Error running health check"));
+// --- doctor ---
+server.tool("doctor", {}, withErrorHandling(() => {
+    // Richer than health-check: Notes.app permission, account state, and Full
+    // Disk Access with actionable messages + structuredContent (#22).
+    const report = runDoctor(notesManager);
+    return successResponse(formatDoctorReport(report), { ...report });
+}, "Error running doctor"));
 // --- get-notes-stats ---
 server.tool("get-notes-stats", {}, withErrorHandling(() => {
     const stats = notesManager.getNotesStats();
@@ -587,7 +599,7 @@ server.tool("get-notes-stats", {}, withErrorHandling(() => {
     lines.push(`  Last 24 hours: ${stats.recentlyModified.last24h}`);
     lines.push(`  Last 7 days: ${stats.recentlyModified.last7d}`);
     lines.push(`  Last 30 days: ${stats.recentlyModified.last30d}`);
-    return successResponse(lines.join("\n"));
+    return successResponse(lines.join("\n"), { ...stats });
 }, "Error getting notes statistics"));
 // --- list-attachments ---
 server.tool("list-attachments", {
@@ -606,10 +618,13 @@ server.tool("list-attachments", {
         }
         const attachments = notesManager.listAttachmentsById(id);
         if (attachments.length === 0) {
-            return successResponse(`Note "${note.title}" has no attachments`);
+            return successResponse(`Note "${note.title}" has no attachments`, {
+                attachments: [],
+                count: 0,
+            });
         }
         const attachmentList = attachments.map((a) => `  - ${a.name} (${a.contentType})`).join("\n");
-        return successResponse(`Found ${attachments.length} attachment(s) in "${note.title}":\n${attachmentList}`);
+        return successResponse(`Found ${attachments.length} attachment(s) in "${note.title}":\n${attachmentList}`, { attachments, count: attachments.length });
     }
     // Fall back to title-based lookup
     if (!title) {
@@ -621,10 +636,10 @@ server.tool("list-attachments", {
     }
     const attachments = notesManager.listAttachments(title, account);
     if (attachments.length === 0) {
-        return successResponse(`Note "${title}" has no attachments`);
+        return successResponse(`Note "${title}" has no attachments`, { attachments: [], count: 0 });
     }
     const attachmentList = attachments.map((a) => `  - ${a.name} (${a.contentType})`).join("\n");
-    return successResponse(`Found ${attachments.length} attachment(s) in "${title}":\n${attachmentList}`);
+    return successResponse(`Found ${attachments.length} attachment(s) in "${title}":\n${attachmentList}`, { attachments, count: attachments.length });
 }, "Error listing attachments"));
 // --- batch-delete-notes ---
 server.tool("batch-delete-notes", {
@@ -669,6 +684,42 @@ server.tool("batch-move-notes", {
     }
     return succeeded > 0 ? successResponse(lines.join("\n")) : errorResponse(lines.join("\n"));
 }, "Error performing batch move"));
+// --- save-attachment ---
+server.tool("save-attachment", {
+    noteId: z.string().min(1, "noteId is required").describe("CoreData note id (from search/list)"),
+    attachmentId: z
+        .string()
+        .min(1, "attachmentId is required")
+        .describe("Attachment id (from list-attachments)"),
+    savePath: z
+        .string()
+        .min(1, "savePath is required")
+        .describe("Absolute destination file path (must be under home, temp, or /Volumes)"),
+}, withErrorHandling(({ noteId, attachmentId, savePath }) => {
+    const r = notesManager.saveAttachmentById(noteId, attachmentId, savePath);
+    if (!r.success) {
+        return errorResponse(`Failed to save attachment: ${r.error ?? "unknown error"}`);
+    }
+    return successResponse(`Saved "${r.name ?? "attachment"}" to ${r.savedPath}`, {
+        savedPath: r.savedPath,
+        name: r.name,
+        contentType: r.contentType,
+    });
+}, "Error saving attachment"));
+// --- fetch-attachment ---
+server.tool("fetch-attachment", {
+    noteId: z.string().min(1, "noteId is required").describe("CoreData note id (from search/list)"),
+    attachmentId: z
+        .string()
+        .min(1, "attachmentId is required")
+        .describe("Attachment id (from list-attachments)"),
+}, withErrorHandling(({ noteId, attachmentId }) => {
+    const r = notesManager.getAttachmentBase64ById(noteId, attachmentId);
+    if (!r.success || !r.base64) {
+        return errorResponse(`Failed to fetch attachment: ${r.error ?? "unknown error"}`);
+    }
+    return successResponse(`Fetched "${r.name ?? "attachment"}" (${r.contentType ?? "unknown type"}, ${r.bytes ?? 0} bytes) as base64.`, { name: r.name, contentType: r.contentType, bytes: r.bytes, base64: r.base64 });
+}, "Error fetching attachment"));
 // --- export-notes-json ---
 server.tool("export-notes-json", {}, withErrorHandling(() => {
     const exportData = notesManager.exportNotesAsJson();
@@ -684,6 +735,7 @@ server.tool("export-notes-json", {}, withErrorHandling(() => {
                 text: JSON.stringify(exportData, null, 2),
             },
         ],
+        structuredContent: { ...exportData },
     };
 }, "Error exporting notes"));
 // --- get-note-markdown ---
@@ -701,7 +753,7 @@ server.tool("get-note-markdown", {
         if (!markdown) {
             return errorResponse(`Note with ID "${id}" not found or has no content`);
         }
-        return successResponse(markdown);
+        return successResponse(markdown, { markdown });
     }
     // Fall back to title-based lookup
     if (!title) {
@@ -711,7 +763,7 @@ server.tool("get-note-markdown", {
     if (!markdown) {
         return errorResponse(`Note "${title}" not found or has no content. Use search-notes to find notes, then use the note's ID for reliable operations.`);
     }
-    return successResponse(markdown);
+    return successResponse(markdown, { markdown });
 }, "Error getting note as markdown"));
 // --- get-checklist-state ---
 server.tool("get-checklist-state", {
@@ -733,7 +785,7 @@ server.tool("get-checklist-state", {
         .map((item) => `${item.done ? "[x]" : "[ ]"} ${item.text}`)
         .join("\n");
     const checked = result.items.filter((i) => i.done).length;
-    return successResponse(`Checklist for "${note.title}" (${checked}/${result.items.length} done):\n${summary}`);
+    return successResponse(`Checklist for "${note.title}" (${checked}/${result.items.length} done):\n${summary}`, { items: result.items, checked, total: result.items.length });
 }, "Error reading checklist state"));
 // =============================================================================
 // Server Startup
@@ -744,5 +796,7 @@ server.tool("get-checklist-state", {
  * The server uses stdio transport for communication with MCP clients.
  * This is the standard transport for CLI-based MCP servers.
  */
+// Register read-only resources and workflow prompts (#23).
+registerResourcesAndPrompts(server, notesManager);
 const transport = new StdioServerTransport();
 await server.connect(transport);