---
name: notes-management
description: Guide for effective use of che-apple-notes-mcp for macOS Apple Notes management. Use when user asks about Apple Notes, 備忘錄, note taking on Mac, creating/searching/organizing notes.
allowed-tools:
  - mcp__che-apple-notes-mcp__list_folders
  - mcp__che-apple-notes-mcp__create_folder
  - mcp__che-apple-notes-mcp__update_folder
  - mcp__che-apple-notes-mcp__delete_folder
  - mcp__che-apple-notes-mcp__list_notes
  - mcp__che-apple-notes-mcp__list_notes_quick
  - mcp__che-apple-notes-mcp__get_note
  - mcp__che-apple-notes-mcp__create_note
  - mcp__che-apple-notes-mcp__update_note
  - mcp__che-apple-notes-mcp__delete_note
  - mcp__che-apple-notes-mcp__move_note
  - mcp__che-apple-notes-mcp__search_notes
  - mcp__che-apple-notes-mcp__create_notes_batch
  - mcp__che-apple-notes-mcp__move_notes_batch
  - mcp__che-apple-notes-mcp__delete_notes_batch
  - mcp__che-apple-notes-mcp__undo
  - mcp__che-apple-notes-mcp__redo
  - mcp__che-apple-notes-mcp__undo_history
---

# macOS Apple Notes Management

Guide for operating Apple Notes.app via `che-apple-notes-mcp`.

## Architecture at a Glance

| Operation | Path | Speed | Needs |
|-----------|------|-------|-------|
| Read (list/get/search) | SQLite direct | <10 ms | Full Disk Access |
| Write (create/update/delete/move) | AppleScript | ~50 ms | Automation permission |
| Read (fallback) | AppleScript | ~500 ms | Automation permission only |

If Full Disk Access is not granted, read ops transparently fall back to AppleScript.

## Body Format (Dual-Track)

**Input**: provide `body_text` OR `body_html` (not both):

```
create_note(
  title: "Meeting notes",
  body_text: "Plain text with\nnewlines",   # will be wrapped in <div>
  folder: "Work"
)
```

```
create_note(
  title: "Styled",
  body_html: "<h1>Heading</h1><p>With <b>bold</b></p>",
  folder: "Work"
)
```

**Output**: `get_note` and `list_notes(include_body=true)` return both forms:

```
{
  "id": "x-coredata://...",
  "title": "Meeting notes",
  "body_text": "Plain text with\nnewlines",
  "body_html": "<div>Plain text with<br>newlines</div>",
  ...
}
```

## Tool Categories

### Discovery (start here)

- `list_folders` — see all folders and their account (iCloud / On My Mac)
- `list_notes_quick` with `range: "recent" | "today" | "this_week" | "pinned"` — common views
- `search_notes` — keyword search (title + snippet)

### Folders

| Task | Tool |
|------|------|
| List | `list_folders` (optional `account` filter) |
| Create | `create_folder(title, account?)` |
| Rename | `update_folder(id, title)` |
| Delete | `delete_folder(id)` — empty folders only |

### Notes CRUD

| Task | Tool | Key params |
|------|------|------------|
| List | `list_notes` | folder, folder_id, account, pinned, locked, include_body, limit, sort |
| Get | `get_note` | id |
| Create | `create_note` | title, body_text XOR body_html, folder?, account? |
| Update | `update_note` | id, title?, body_text? / body_html? |
| Delete | `delete_note` | id |
| Move | `move_note` | id, folder, account? |

### Batch (more efficient than multiple single calls)

- `create_notes_batch(notes: [{title, body_text?, body_html?, folder?, account?}, ...])`
- `move_notes_batch(ids: [...], folder, account?)`
- `delete_notes_batch(ids: [...])`

### Undo/Redo (process-local)

- `undo` — revert last write
- `redo` — reapply an undone write
- `undo_history` — show stack

## Source Disambiguation

When folder names collide across accounts (e.g., "Notes" on iCloud and On My Mac):

```
create_note(
  title: "Shopping list",
  body_text: "milk, eggs",
  folder: "Notes",
  account: "iCloud"    # disambiguate
)
```

Available accounts can vary: `iCloud`, `On My Mac`, plus any configured accounts. Use `list_folders` to inspect.

## ID Formats

- `id` field returned by SQLite path = AppleScript URL form: `x-coredata://<account-uuid>/ICNote/p<PK>`. Use this directly for `update_note`, `delete_note`, `move_note`.
- `uuid` field = raw ZIDENTIFIER (just the note's UUID). For debugging / advanced consumers.

## Common Workflows

### Capture a quick note

```
create_note(title: "Idea", body_text: "The thing I just thought of", folder: "Notes")
```

### Daily review

```
1. list_notes_quick(range: "today")  → see today's notes
2. list_notes_quick(range: "pinned") → see pinned items
```

### Find and update

```
1. search_notes(keyword: "project X")
2. get_note(id: <first result>)
3. update_note(id: ..., body_text: "<appended content>")
```

### Bulk reorganize

```
1. list_notes(folder: "Inbox")          → collect ids
2. move_notes_batch(ids, folder: "Archive")
```

## Performance Tips

1. **Default to metadata-only listing** — only pass `include_body: true` when you need body (each body requires GZIP inflate + protobuf decode, ~1ms per note).
2. **Prefer `list_notes_quick`** over `list_notes` for common ranges.
3. **Batch writes** cut AppleScript dispatch overhead from ~50ms × N to a single dispatch.
4. **Search via `search_notes`** beats listing and filtering in the caller.

## Known Limits (v0.1.0)

- Locked notes: body is AES-encrypted and cannot be decoded — `{locked: true, body: null}`.
- Note pinning: read-only (AppleScript does not expose the `pinned` attribute for writes).
- Attachment writes: not supported (read-only via `list_notes` metadata).
- Body HTML decoded from SQLite falls back to plaintext for formatting beyond bold/italic/link/list (v0.2.0 will render full attribute runs). Read via AppleScript for full HTML fidelity.
- Large bodies: hard-capped at 1 MB; split into multiple notes.

## First-Run Setup

Users must run `~/bin/CheAppleNotesMCP --setup` once to:

1. Get prompted for Automation permission to Notes.app (click Allow when the dialog appears)
2. See whether Full Disk Access is granted (if not, follow the printed instructions to enable — optional but much faster)

Without Full Disk Access: read ops fall back to AppleScript, ~50–500× slower but still functional. Features `list_notes_quick`, `search_notes` require SQLite and will error if FDA is missing.