noteplan-mcp 1.1.1

package/README.md

@@ -0,0 +1,257 @@
+# NotePlan MCP Server
+
+An MCP (Model Context Protocol) server that exposes NotePlan's note, task, calendar, reminders, and plugin management to AI assistants like Claude.
+
+Works with **Claude Desktop** and **Claude Code**. Claude Desktop is great for conversational workflows — planning your day, reviewing tasks, asking questions about your notes. Claude Code is ideal for batch operations and automation — bulk edits, plugin development, or scripting complex workflows across many notes.
+
+## What You Can Do
+
+Once installed, just talk to Claude naturally. Here are some examples:
+
+**Notes & Tasks**
+- "What's on my schedule today?"
+- "Show me all open tasks tagged #urgent"
+- "Add a task to my Daily Note: call the dentist at 3pm"
+- "Summarize my meeting notes from last week"
+- "Move all tasks from 'Inbox' to '20 - Areas/Work'"
+- "What did I write about the product launch?"
+
+**Calendar & Reminders**
+- "What meetings do I have tomorrow?"
+- "Create a calendar event for Friday at 2pm: Design Review"
+- "Remind me to submit the report by end of day"
+- "Show me all reminders due this week"
+
+**Organization**
+- "List all notes in my Projects folder"
+- "Create a new note called 'Q1 Planning' in my Work folder"
+- "Rename the 'Old Ideas' folder to 'Archive'"
+- "Which tags am I using the most?"
+
+**Plugins & Themes**
+- "What plugins do I have installed?"
+- "Create a plugin that adds word counts to my daily notes"
+- "Switch to dark mode"
+- "Show me available plugins I can install"
+
+## Installation
+
+Requires **Node.js 18+**. Check with `node -v`, or install via [Homebrew](https://brew.sh) (`brew install node`) or [nodejs.org](https://nodejs.org).
+
+Download the latest release from the [Releases page](https://github.com/NotePlan/noteplan-mcp/releases) and extract it:
+
+```bash
+cd ~/Downloads
+unzip noteplan-mcp-v*.zip
+```
+
+### Claude Code
+
+```bash
+claude mcp add noteplan node ~/Downloads/noteplan-mcp/dist/index.js
+```
+
+### Claude Desktop
+
+Use `echo ~/Downloads/noteplan-mcp/dist/index.js` to get the full path, then open **Settings > Developer > Edit Config** and add:
+
+```json
+{
+  "mcpServers": {
+    "noteplan": {
+      "command": "node",
+      "args": ["/Users/yourname/Downloads/noteplan-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Save and restart Claude Desktop.
+
+### Optional: Semantic Embeddings
+
+To enable semantic search, add environment variables to the config:
+
+```json
+{
+  "mcpServers": {
+    "noteplan": {
+      "command": "node",
+      "args": ["/Users/yourname/Downloads/noteplan-mcp/dist/index.js"],
+      "env": {
+        "NOTEPLAN_EMBEDDINGS_ENABLED": "true",
+        "NOTEPLAN_EMBEDDINGS_PROVIDER": "openai",
+        "NOTEPLAN_EMBEDDINGS_API_KEY": "YOUR_API_KEY",
+        "NOTEPLAN_EMBEDDINGS_MODEL": "text-embedding-3-small",
+        "NOTEPLAN_EMBEDDINGS_BASE_URL": "https://api.openai.com"
+      }
+    }
+  }
+}
+```
+
+- `NOTEPLAN_EMBEDDINGS_PROVIDER`: `openai` (default), `mistral`, or `custom`.
+- `NOTEPLAN_EMBEDDINGS_BASE_URL`: for `custom`, assumes OpenAI-compatible `/v1/embeddings`.
+- `NOTEPLAN_EMBEDDINGS_ENABLED`: defaults to `false`; when false, embeddings tools are not listed.
+
+<details>
+<summary><strong>Build from Source</strong> (for contributors and development)</summary>
+
+#### Prerequisites
+
+- **Node.js 18+** (`node -v`)
+- **Xcode Command Line Tools** — needed to compile the Swift calendar/reminders helpers (`xcode-select --install`)
+
+#### Build
+
+```bash
+git clone https://github.com/NotePlan/noteplan-mcp.git
+cd noteplan-mcp
+npm install
+npm run build
+```
+
+The `build` step compiles the TypeScript source and two Swift helper binaries (`calendar-helper` and `reminders-helper`) for native Calendar and Reminders access.
+
+#### Verify
+
+```bash
+npm run smoke:workflow
+```
+
+#### Development
+
+```bash
+npm run dev   # watch mode — recompiles TypeScript on save
+```
+
+Then configure Claude Desktop or Claude Code to point at the local `dist/index.js` as shown above.
+
+</details>
+
+## Features
+
+- **Unified Access**: Search and manage both local notes (file system) and teamspace notes (SQLite)
+- **Full CRUD**: Create, read, update, and delete notes with flexible note targeting (id, filename, title, date, or query)
+- **Task Management**: Add, complete, and update tasks with auto-formatted markers matching user settings
+- **Calendar Events & Reminders**: Native macOS Calendar and Reminders integration via Swift helpers (`noteplan_eventkit`)
+- **Plugin Management**: List, create, install, delete, and run NotePlan plugins; read source/logs; capture screenshots
+- **Theme Management**: List, create, and activate themes
+- **Filter Management**: Create, save, and execute task filters
+- **UI Control**: Open notes, toggle sidebar, run plugin commands via AppleScript
+- **Memory**: Persistent user preference memory for storing formatting/style preferences across sessions
+- **Search**: Full-text search across all notes with frontmatter property filters, plus tag listing
+- **Auto-Create Calendar Notes**: Editing a date that doesn't exist yet auto-creates the daily note (matches NotePlan native behavior)
+- **Smart Folder Resolution**: Exact path matching with `Notes/` prefix support; fuzzy matching only as fallback
+- **Structured Errors**: Tool failures include machine-readable `code` plus `hint`/`suggestedTool`
+- **Fast Repeated Lookups**: Short-lived in-memory caching for expensive list/resolve paths
+- **Opt-in Timing Telemetry**: `debugTimings=true` adds `durationMs` and `stageTimings`
+- **Safer TeamSpace Deletes**: TeamSpace deletes move notes into `@Trash`; list/search excludes trash by default
+- **Optional Semantic Index**: Local embeddings index + semantic search (disabled by default; explicit opt-in)
+
+## Available Tools (12)
+
+All tools use action-based dispatch — one tool per domain, with an `action` parameter to select the operation.
+
+### `noteplan_get_notes`
+Unified note retrieval: get a single note, list notes, resolve references, fetch today/calendar/periodic notes, date ranges, or folder contents.
+- Single note by `id`, `title`, `filename`, or `date`
+- `resolve=true` — resolve a fuzzy reference to a canonical note
+- `period` + `count` — recent periodic notes (e.g., last 6 weekly notes)
+- `rangePeriod` or `startDate`/`endDate` — daily notes in date range
+- `folder` — notes in a folder
+- Fallback: list notes with optional filters
+
+### `noteplan_manage_note`
+Note lifecycle: `create`, `update`, `delete`, `move`, `restore`, `rename`, `set_property`, `remove_property`.
+
+### `noteplan_edit_content`
+Edit note content: `insert`, `append`, `delete_lines`, `edit_line`, `replace_lines`. All actions target notes via `id`, `filename`, `title`, `date`, or `query`. Calendar notes are auto-created when targeted by date.
+
+### `noteplan_paragraphs`
+Paragraph and task operations: `get` (line metadata), `search` (find lines in a note), `search_global` (tasks across all notes), `add` (task with auto-formatted marker), `complete`, `update`.
+
+### `noteplan_search`
+Search across notes or list tags.
+- `action: "search"` (default) — full-text or metadata search with `searchField`, `queryMode`, `propertyFilters`
+- `action: "list_tags"` — list all tags/hashtags with optional filtering
+
+### `noteplan_folders`
+Folder and space operations: `list`, `find`, `resolve`, `create`, `move`, `rename`, `delete`, `list_spaces`.
+
+### `noteplan_filters`
+Saved filter operations: `list`, `get`, `get_tasks`, `list_parameters`, `save`, `rename`.
+
+### `noteplan_eventkit`
+macOS Calendar and Reminders via `source` parameter.
+- `source: "calendar"` — `get_events`, `list_calendars`, `create_event`, `update_event`, `delete_event`
+- `source: "reminders"` — `get`, `list_lists`, `create`, `complete`, `update`, `delete`
+
+### `noteplan_memory`
+User preference memory: `list`, `save`, `update`, `delete`.
+
+### `noteplan_ui`
+NotePlan UI control: `open_note`, `open_today`, `search`, `run_plugin`, `open_view`, `toggle_sidebar`, `close_plugin_window`, `list_plugin_windows`.
+
+### `noteplan_plugins`
+Plugin management: `list`, `list_available`, `create`, `delete`, `install`, `log`, `source`, `update_html`, `screenshot`.
+
+### `noteplan_themes`
+Theme management: `list`, `get`, `save`, `set_active`.
+
+### `noteplan_embeddings` (opt-in)
+Embeddings/vector search: `status`, `search`, `sync`, `reset`. Only available when `NOTEPLAN_EMBEDDINGS_ENABLED=true`.
+
+## Preferred Usage Flow
+
+Prefer granular edits to avoid large context payloads and accidental full-note rewrites.
+
+1. Find the note: `noteplan_get_notes` (by id/title/filename/date) or `noteplan_search`
+2. Inspect content:
+   - `noteplan_paragraphs(action: get)` for line metadata
+   - `noteplan_paragraphs(action: search)` for text lookup inside a note
+3. Apply targeted mutation:
+   - `noteplan_edit_content(action: edit_line)` for one-line changes
+   - `noteplan_edit_content(action: insert/append)` for adding content
+   - `noteplan_edit_content(action: delete_lines)` for removals
+   - All edit actions accept `id`, `filename`, `title`, `date`, or `query` to target the note
+4. Use `noteplan_manage_note(action: update)` only for intentional full-note rewrites (`fullReplace=true`)
+5. Destructive operations (delete, move, rename, restore) use a 2-step flow:
+   - Step 1: call with `dryRun=true` to preview impact and get `confirmationToken`
+   - Step 2: call again with that `confirmationToken` to execute
+6. Calendar notes are auto-created when targeted by `date` — no need to create them first
+
+Task flow:
+1. Find tasks: `noteplan_paragraphs(action: search)` in one note, or `noteplan_paragraphs(action: search_global)` across notes
+2. Mutate: `noteplan_paragraphs(action: complete)` or `noteplan_paragraphs(action: update)`
+
+Property-filtered search:
+- `noteplan_search` with `query` + `propertyFilters`, e.g. `query: "campaign", propertyFilters: {"category":"marketing"}`
+- Folder filters accept canonical paths (e.g. `20 - Areas` or `Notes/20 - Areas`)
+
+## Data Locations
+
+The server automatically detects NotePlan's storage location. Supported paths (in order of preference):
+
+**iCloud paths (preferred):**
+- `~/Library/Mobile Documents/iCloud~co~noteplan~Today/Documents/`
+- `~/Library/Mobile Documents/iCloud~co~noteplan~NotePlan3/Documents/`
+- `~/Library/Mobile Documents/iCloud~co~noteplan~NotePlan/Documents/`
+- `~/Library/Mobile Documents/iCloud~co~noteplan~NotePlan-setapp/Documents/`
+
+**Local paths:**
+- `~/Library/Containers/co.noteplan.NotePlan3/Data/Library/Application Support/co.noteplan.NotePlan3`
+- `~/Library/Containers/co.noteplan.NotePlan-setapp/Data/Library/Application Support/co.noteplan.NotePlan-setapp`
+
+**Teamspace Database:** `~/Library/Caches/teamspace.db`
+
+## How It Works
+
+- **Local notes**: Direct file system read/write. NotePlan auto-detects changes via FolderMonitor (~300ms delay)
+- **Teamspace notes**: SQLite queries/updates. NotePlan sees changes on next sync cycle or app restart
+- **Calendar & Reminders**: Native macOS access via compiled Swift helpers using EventKit
+- **UI control & Plugins**: AppleScript bridge to the running NotePlan app
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// NotePlan MCP Server Entry Point
+import { startServer } from './server.js';
+startServer().catch((error) => {
+    console.error('Failed to start NotePlan MCP server:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,kCAAkC;AAElC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,sCAAsC,EAAE,KAAK,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/noteplan/embeddings.d.ts

@@ -0,0 +1,170 @@
+import { NoteType } from './types.js';
+export type EmbeddingsProvider = 'openai' | 'mistral' | 'custom';
+export type EmbeddingsSource = 'local' | 'space';
+export type EmbeddingsConfig = {
+    enabled: boolean;
+    provider: EmbeddingsProvider;
+    apiKey: string;
+    model: string;
+    baseUrl: string;
+    dbPath: string;
+    chunkChars: number;
+    chunkOverlap: number;
+    previewChars: number;
+    defaultBatchSize: number;
+    defaultMaxChunksPerNote: number;
+};
+type EmbeddingsScope = {
+    space?: string;
+};
+export type EmbeddingsSyncParams = {
+    space?: string;
+    types?: NoteType[];
+    noteQuery?: string;
+    limit?: number;
+    offset?: number;
+    forceReembed?: boolean;
+    pruneMissing?: boolean;
+    batchSize?: number;
+    maxChunksPerNote?: number;
+};
+export type EmbeddingsSearchParams = {
+    query: string;
+    space?: string;
+    source?: EmbeddingsSource;
+    types?: NoteType[];
+    limit?: number;
+    minScore?: number;
+    includeText?: boolean;
+    previewChars?: number;
+    maxChunks?: number;
+};
+export declare function getEmbeddingsConfig(): EmbeddingsConfig;
+export declare function areEmbeddingsEnabled(): boolean;
+export declare function getEmbeddingsStatus(scope?: EmbeddingsScope): {
+    success: boolean;
+    enabled: boolean;
+    configured: boolean;
+    provider: EmbeddingsProvider;
+    model: string;
+    baseUrl: string;
+    dbPath: string;
+    noteCount: number;
+    chunkCount: number;
+    lastSyncAt: null;
+    warning: string;
+} | {
+    warning?: string | undefined;
+    success: boolean;
+    enabled: boolean;
+    configured: boolean;
+    provider: EmbeddingsProvider;
+    model: string;
+    baseUrl: string;
+    dbPath: string;
+    hasApiKey: boolean;
+    chunkChars: number;
+    chunkOverlap: number;
+    previewChars: number;
+    noteCount: number;
+    chunkCount: number;
+    lastSyncAt: string | null;
+    lastIndexedUpdateAt: string | null;
+};
+export declare function previewResetEmbeddings(scope?: EmbeddingsScope): {
+    noteCount: number;
+    chunkCount: number;
+};
+export declare function resetEmbeddings(scope?: EmbeddingsScope): {
+    removedNotes: number;
+    removedChunks: number;
+};
+export declare function syncEmbeddings(params?: EmbeddingsSyncParams): Promise<{
+    success: boolean;
+    error: string;
+    provider?: undefined;
+    model?: undefined;
+    scope?: undefined;
+    totalCandidates?: undefined;
+    scannedNotes?: undefined;
+    indexedNotes?: undefined;
+    unchangedNotes?: undefined;
+    addedNotes?: undefined;
+    updatedNotes?: undefined;
+    indexedChunks?: undefined;
+    prunedNotes?: undefined;
+    prunedChunks?: undefined;
+    offset?: undefined;
+    limit?: undefined;
+    hasMore?: undefined;
+    nextCursor?: undefined;
+    warnings?: undefined;
+} | {
+    success: boolean;
+    provider: EmbeddingsProvider;
+    model: string;
+    scope: {
+        space: string;
+        scope?: undefined;
+    } | {
+        scope: string;
+        space?: undefined;
+    };
+    totalCandidates: number;
+    scannedNotes: number;
+    indexedNotes: number;
+    unchangedNotes: number;
+    addedNotes: number;
+    updatedNotes: number;
+    indexedChunks: number;
+    prunedNotes: number;
+    prunedChunks: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextCursor: string | null;
+    warnings: string[];
+    error?: undefined;
+}>;
+export declare function searchEmbeddings(params: EmbeddingsSearchParams): Promise<{
+    success: boolean;
+    error: string;
+    query?: undefined;
+    provider?: undefined;
+    model?: undefined;
+    includeText?: undefined;
+    minScore?: undefined;
+    scannedChunks?: undefined;
+    count?: undefined;
+    matches?: undefined;
+} | {
+    success: boolean;
+    query: string;
+    provider: EmbeddingsProvider;
+    model: string;
+    includeText: boolean;
+    minScore: number;
+    scannedChunks: number;
+    count: number;
+    matches: {
+        score: number;
+        note: {
+            id: string;
+            filename: string;
+            title: string;
+            source: string;
+            spaceId: string | null;
+            folder: string | null;
+            type: string;
+            modifiedAt: string | null;
+        };
+        chunk: {
+            text?: string | undefined;
+            index: number;
+            preview: string;
+        };
+    }[];
+    error?: undefined;
+}>;
+export {};
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/noteplan/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/noteplan/embeddings.ts"],"names":[],"mappings":"AAMA,OAAO,EAAQ,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAgCF,KAAK,eAAe,GAAG;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA2CF,wBAAgB,mBAAmB,IAAI,gBAAgB,CAsCtD;AAED,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AA4QD,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiE9D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,GAAE,eAAoB,GAAG;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAuBA;AAED,wBAAgB,eAAe,CAAC,KAAK,GAAE,eAAoB,GAAG;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB,CAiCA;AAED,wBAAsB,cAAc,CAAC,MAAM,GAAE,oBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8OrE;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuHpE"}