@noteplanco/noteplan-mcp 1.1.6 → 1.1.7

package/dist/server.js

@@ -19,8 +19,10 @@ import * as memoryTools from './tools/memory.js';
 import * as uiTools from './tools/ui.js';
 import * as pluginTools from './tools/plugins.js';
 import * as themeTools from './tools/themes.js';
+import * as templateTools from './tools/templates.js';
+import * as attachmentTools from './tools/attachments.js';
 import { parseFlexibleDate } from './utils/date-utils.js';
-import { upgradeMessage, getNotePlanVersion, getMcpServerVersion, MIN_BUILD_ADVANCED_FEATURES } from './utils/version.js';
+import { upgradeMessage, getNotePlanVersion, getMcpServerVersion, MIN_BUILD_ADVANCED_FEATURES, MIN_BUILD_CREATE_BACKUP } from './utils/version.js';
 import { initSqlite } from './noteplan/sqlite-loader.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -200,6 +202,8 @@ function getToolOutputSchema(toolName) {
         case 'noteplan_plugins':
         case 'noteplan_themes':
         case 'noteplan_embeddings':
+        case 'noteplan_templates':
+        case 'noteplan_attachments':
             return GENERIC_TOOL_OUTPUT_SCHEMA;
         default:
             return GENERIC_TOOL_OUTPUT_SCHEMA;
@@ -371,6 +375,7 @@ function getToolAnnotations(toolName) {
         'noteplan_plugins',
         'noteplan_themes',
         'noteplan_embeddings',
+        'noteplan_attachments',
     ]);
     const nonIdempotentTools = new Set([
         'noteplan_manage_note',
@@ -384,11 +389,14 @@ function getToolAnnotations(toolName) {
         'noteplan_plugins',
         'noteplan_themes',
         'noteplan_embeddings',
+        'noteplan_templates',
+        'noteplan_attachments',
     ]);
     const openWorldTools = new Set([
         'noteplan_eventkit',
         'noteplan_embeddings',
         'noteplan_plugins',
+        'noteplan_templates',
     ]);
     return {
         readOnlyHint: readOnlyTools.has(toolName),
@@ -459,6 +467,12 @@ function getToolSearchAliases(toolName) {
         case 'noteplan_embeddings':
             aliases.push('embeddings', 'semantic search', 'vector search', 'similarity');
             break;
+        case 'noteplan_templates':
+            aliases.push('template', 'templates', 'render template', 'list templates', 'template types', 'meeting template', 'project template', 'debug template', 'test template');
+            break;
+        case 'noteplan_attachments':
+            aliases.push('attachment', 'attachments', 'image', 'file', 'upload', 'add image', 'add file', 'add attachment', 'list attachments', 'get attachment', 'base64', 'photo', 'screenshot');
+            break;
     }
     return aliases;
 }
@@ -516,7 +530,7 @@ function searchToolDefinitions(tools, query, limit) {
 function inferToolErrorMeta(toolName, errorMessage, registeredToolNames) {
     const message = errorMessage.toLowerCase();
     if (message.includes('unknown tool')) {
-        const toolList = registeredToolNames?.join(', ') ?? 'noteplan_get_notes, noteplan_search, noteplan_manage_note, noteplan_edit_content, noteplan_paragraphs, noteplan_folders, noteplan_filters, noteplan_eventkit, noteplan_memory';
+        const toolList = registeredToolNames?.join(', ') ?? 'noteplan_get_notes, noteplan_search, noteplan_manage_note, noteplan_edit_content, noteplan_paragraphs, noteplan_folders, noteplan_filters, noteplan_eventkit, noteplan_memory, noteplan_templates, noteplan_attachments';
         return {
             code: 'ERR_UNKNOWN_TOOL',
             hint: `Check tool name spelling. Available tools: ${toolList}.`,
@@ -737,6 +751,12 @@ function withSuggestedNextTools(result, toolName, availableToolNames) {
         case 'noteplan_themes':
             suggestedNextTools = ['noteplan_themes'];
             break;
+        case 'noteplan_templates':
+            suggestedNextTools = ['noteplan_templates', 'noteplan_manage_note', 'noteplan_edit_content'];
+            break;
+        case 'noteplan_attachments':
+            suggestedNextTools = ['noteplan_attachments', 'noteplan_edit_content', 'noteplan_get_notes'];
+            break;
         default:
             suggestedNextTools = [];
     }
@@ -977,14 +997,14 @@ export function createServer() {
         },
         {
             name: 'noteplan_manage_note',
-            description: 'Manage notes: create, update, delete, move, restore, rename, or manage frontmatter properties.\n\nActions:\n- create: Create a project note (requires title)\n- update: Replace note content (requires filename, content, fullReplace + confirmationToken)\n- delete/move/restore/rename: Lifecycle ops (requires id or filename + dryRun/confirmationToken)\n- set_property/remove_property: Frontmatter (requires filename + key)',
+            description: 'Manage notes: create, update, delete, move, restore, rename, or manage frontmatter properties.\n\nActions:\n- create: Create a project note (requires title). Set noteType="template" to create in @Templates with proper frontmatter. After creating a template, verify it with noteplan_templates(action: "render").\n- update: Replace note content (requires filename, content, fullReplace + confirmationToken)\n- delete/move/restore: Lifecycle ops (requires id or filename + dryRun/confirmationToken)\n- rename: Rename a note (accepts id, filename, title, or query to find the note + newTitle for the new name + dryRun/confirmationToken)\n- set_property/remove_property: Frontmatter (requires filename + key)',
             inputSchema: {
                 type: 'object',
                 properties: {
                     action: {
                         type: 'string',
                         enum: ['create', 'update', 'delete', 'move', 'restore', 'rename', 'set_property', 'remove_property'],
-                        description: 'Action to perform',
+                        description: 'Action: create | update | delete | move | restore | rename | set_property | remove_property',
                     },
                     id: {
                         type: 'string',
@@ -996,7 +1016,11 @@ export function createServer() {
                     },
                     title: {
                         type: 'string',
-                        description: 'Note title — required for create',
+                        description: 'Note title — required for create. Also used by rename to find the note by title (fuzzy matched).',
+                    },
+                    query: {
+                        type: 'string',
+                        description: 'Fuzzy search query to find the note — used by rename',
                     },
                     content: {
                         type: 'string',
@@ -1010,6 +1034,16 @@ export function createServer() {
                         type: 'boolean',
                         description: 'Bypass smart matching and create exact folder name — used by create',
                     },
+                    noteType: {
+                        type: 'string',
+                        enum: ['note', 'template'],
+                        description: 'Type of note to create. Use "template" to create in @Templates with proper frontmatter — used by create',
+                    },
+                    templateTypes: {
+                        type: 'array',
+                        items: { type: 'string', enum: ['empty-note', 'meeting-note', 'project-note', 'calendar-note'] },
+                        description: 'Template type tags — used by create with noteType="template"',
+                    },
                     space: {
                         type: 'string',
                         description: 'Space name or ID scope',
@@ -1036,11 +1070,11 @@ export function createServer() {
                     },
                     newFilename: {
                         type: 'string',
-                        description: 'New filename for local notes — used by rename',
+                        description: 'New filename for local notes — used by rename. Prefer newTitle instead.',
                     },
                     newTitle: {
                         type: 'string',
-                        description: 'New title for TeamSpace notes — used by rename',
+                        description: 'New title for the note — used by rename. Works for both local and TeamSpace notes. For local notes this renames the file and updates the # heading.',
                     },
                     keepExtension: {
                         type: 'boolean',
@@ -1060,14 +1094,14 @@ export function createServer() {
         },
         {
             name: 'noteplan_edit_content',
-            description: 'Edit note content: insert, append, delete lines, edit a line, or replace a range of lines.\n\nActions:\n- insert: Insert at position (start/end/after-heading/in-section/at-line)\n- append: Append to end (shorthand for insert at end). Use date="today" to append to today\'s daily note (replaces noteplan_add_to_today).\n- delete_lines: Delete line range (requires startLine, endLine + dryRun/confirmationToken)\n- edit_line: Edit one line (requires line + content)\n- replace_lines: Replace line range (requires startLine, endLine, content + dryRun/confirmationToken)\n\nTarget note via id, filename, title, date, or query. Calendar notes (date param) are auto-created if they don\'t exist yet — no need to create them first. Always use tab characters for indentation.\n\nNotePlan syntax: Tasks use "- [ ] text" (open), "- [x]" (done), "- [-]" (cancelled), "- [>]" (scheduled). The task marker (*/- with or without checkbox) follows user settings — prefer noteplan_paragraphs(action=add) for auto-formatted tasks. Schedule tasks to dates with >YYYY-MM-DD. Link to notes with [[Note Name]]. Never add block IDs (^id) — only the NotePlan app creates these.\n\nUse scheduleDate to auto-append >YYYY-MM-DD scheduling to content.',
+            description: 'Edit note content. IMPORTANT: action values use snake_case.\n\nValid actions (exactly these strings):\n- "insert": Insert at position. Combine any position with heading="Section Name" to scope insertion to that section. position="start" + heading inserts right after the heading. position="end" + heading appends at end of the heading\'s section. position="after-heading" inserts right after a heading. position="in-section" appends at end of a heading\'s section. position="start" (no heading) inserts after frontmatter. position="at-line" inserts at a specific line number. position="end" (no heading) appends to note.\n- "append": Shorthand for insert at end. Supports heading="Section Name" to append at end of that section. Use date="today" to append to today\'s daily note.\n- "delete_lines": Delete a line range. Requires startLine + endLine (1-indexed). Use dryRun=true first, then confirmationToken to execute.\n- "edit_line": Edit a single line. Requires line (1-indexed) + content. Set content="" to clear a line.\n- "replace_lines": Replace a line range. Requires startLine + endLine + content. Use dryRun=true first, then confirmationToken to execute.\n\nTarget note via id, filename, title, date, or query. Calendar notes (date param) are auto-created if they don\'t exist yet. Always use tab characters for indentation.\n\nAdding tasks: When inserting a task, set type="task" and pass only the task text as content (e.g. content="Buy groceries", type="task"). Do NOT include raw markers like "* [ ]" or "- [ ]" in content — the type parameter handles formatting to match the user\'s configured style. For checklists use type="checklist". For task lifecycle (complete, update, search), use noteplan_paragraphs instead.\n\nSchedule tasks with >YYYY-MM-DD. Link to notes with [[Note Name]]. Never add block IDs (^id).\n\nUse scheduleDate to auto-append >YYYY-MM-DD to content.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     action: {
                         type: 'string',
                         enum: ['insert', 'append', 'delete_lines', 'edit_line', 'replace_lines'],
-                        description: 'Action to perform',
+                        description: 'Action: insert | append | delete_lines | edit_line | replace_lines',
                     },
                     id: {
                         type: 'string',
@@ -1095,16 +1129,16 @@ export function createServer() {
                     },
                     content: {
                         type: 'string',
-                        description: 'Content to insert/append/replace, or new line content for edit_line',
+                        description: 'Content to insert/append/replace, or new line content for edit_line. NEVER include task markers like "- [ ]", "* [ ]", or "* " — instead set type="task" and pass only the task text (e.g. content="Buy groceries", NOT content="- [ ] Buy groceries").',
                     },
                     position: {
                         type: 'string',
                         enum: ['start', 'end', 'after-heading', 'at-line', 'in-section'],
-                        description: 'Where to insert: start (after frontmatter), end, after-heading (right after heading/marker line), in-section (at end of section, before next heading/marker), or at-line — used by insert',
+                        description: 'Where to insert. With heading: start=right after heading, end/in-section=end of section. Without heading: start=after frontmatter, end=bottom of note. at-line=specific line number — used by insert',
                     },
                     heading: {
                         type: 'string',
-                        description: 'Heading or section marker text (required for after-heading and in-section; matches both ## headings and **bold:** section markers) — used by insert',
+                        description: 'Heading or section marker text (required for after-heading and in-section; matches both ## headings and **bold:** section markers) — used by insert, append',
                     },
                     line: {
                         type: 'number',
@@ -1167,14 +1201,14 @@ export function createServer() {
         },
         {
             name: 'noteplan_paragraphs',
-            description: 'Paragraph and task operations on notes.\n\nParagraph actions:\n- get: Get note lines with metadata (requires filename). Returns line, lineIndex, content, type, etc.\n- search: Search for matching lines in a note (requires query + note ref via id/filename/title/date)\n\nTask actions:\n- search_global: Search tasks across all notes (requires query, supports "*" wildcard)\n- add: Add a task (requires target + content). Task marker format auto-matches user settings. Use scheduleDate to auto-append >YYYY-MM-DD scheduling to content, [[Note Name]] to link, #tag for tags, @person for mentions.\n- complete: Mark task done (requires filename + lineIndex or line)\n- update: Update task content/status (requires filename + lineIndex or line)',
+            description: 'Task lifecycle and paragraph inspection.\n\nParagraph actions:\n- get: Get note lines with metadata (requires filename). Returns line, lineIndex, content, type, etc.\n- search: Search for matching lines in a note (requires query + note ref via id/filename/title/date)\n\nTask actions:\n- search_global: Search tasks across all notes (requires query, supports "*" wildcard)\n- add: Add a task (requires target + content). Target is a date ("today", "tomorrow", "YYYY-MM-DD") for daily notes or a filename for project notes. Pass only the task text as content — formatting auto-matches user settings. Position+heading combos: position="start"+heading inserts right after the heading, position="end"+heading appends at end of that section, position="after-heading" inserts right after heading, position="in-section" appends at end of section. Default position is "end" (bottom of note). Use scheduleDate for >YYYY-MM-DD, [[Note Name]] to link, #tag for tags, @person for mentions.\n- complete: Mark task done (requires filename + lineIndex or line)\n- update: Update task content/status (requires filename + lineIndex or line)',
             inputSchema: {
                 type: 'object',
                 properties: {
                     action: {
                         type: 'string',
                         enum: ['get', 'search', 'search_global', 'add', 'complete', 'update'],
-                        description: 'Action to perform',
+                        description: 'Action: get | search | search_global | add | complete | update',
                     },
                     id: {
                         type: 'string',
@@ -1236,16 +1270,16 @@ export function createServer() {
                     },
                     target: {
                         type: 'string',
-                        description: 'Target for add: date (today/tomorrow/YYYY-MM-DD) for daily notes or filename for project notes',
+                        description: 'Target note for add: use a date string (today, tomorrow, yesterday, YYYY-MM-DD, YYYYMMDD) for daily/calendar notes, or a filename path for project notes. Daily notes are auto-created if they don\'t exist.',
                     },
                     position: {
                         type: 'string',
                         enum: ['start', 'end', 'after-heading', 'in-section'],
-                        description: 'Where to add task (default: end) — used by add',
+                        description: 'Where to add task (default: end). With heading: start=right after heading, end/in-section=end of section. Without heading: start=top of note, end=bottom of note — used by add',
                     },
                     heading: {
                         type: 'string',
-                        description: 'Heading or section marker text (matches both ## headings and **bold:** section markers) — used by add',
+                        description: 'Heading or section marker text to scope insertion (matches both ## headings and **bold:** section markers). Combine with position to control placement — used by add',
                     },
                     lineIndex: {
                         type: 'number',
@@ -1321,7 +1355,7 @@ export function createServer() {
                     action: {
                         type: 'string',
                         enum: ['list', 'find', 'resolve', 'create', 'move', 'rename', 'delete', 'list_spaces'],
-                        description: 'Action to perform',
+                        description: 'Action: list | find | resolve | create | move | rename | delete | list_spaces',
                     },
                     path: {
                         type: 'string',
@@ -1424,7 +1458,7 @@ export function createServer() {
                     action: {
                         type: 'string',
                         enum: ['list', 'get', 'get_tasks', 'list_parameters', 'save', 'rename'],
-                        description: 'Action to perform',
+                        description: 'Action: list | get | get_tasks | list_parameters | save | rename',
                     },
                     name: {
                         type: 'string',
@@ -1509,7 +1543,7 @@ export function createServer() {
                     action: {
                         type: 'string',
                         enum: ['get_events', 'list_calendars', 'create_event', 'update_event', 'delete_event', 'get', 'list_lists', 'create', 'complete', 'update', 'delete'],
-                        description: 'Action to perform',
+                        description: 'Action: get_events | list_calendars | create_event | update_event | delete_event | get | list_lists | create | complete | update | delete',
                     },
                     // Calendar params
                     eventId: {
@@ -1611,7 +1645,7 @@ export function createServer() {
                     action: {
                         type: 'string',
                         enum: ['list', 'save', 'update', 'delete'],
-                        description: 'Action to perform',
+                        description: 'Action: list | save | update | delete',
                     },
                     id: {
                         type: 'string',
@@ -1747,7 +1781,7 @@ export function createServer() {
                     action: {
                         type: 'string',
                         enum: ['status', 'search', 'sync', 'reset'],
-                        description: 'Action to perform',
+                        description: 'Action: status | search | sync | reset',
                     },
                     query: {
                         type: 'string',
@@ -1824,196 +1858,266 @@ export function createServer() {
             },
         });
     }
-    if (advancedFeaturesEnabled) {
-        toolDefinitions.push({
-            name: 'noteplan_ui',
-            description: 'NotePlan UI control via AppleScript.\n\nActions:\n- open_note: Open a note (title or filename)\n- open_today: Open today\'s note\n- search: Search in UI\n- run_plugin: Run a plugin command (requires pluginId + command)\n- open_view: Open a named view\n- toggle_sidebar: Toggle sidebar visibility\n- close_plugin_window: Close plugin window (by windowID/title, or omit both to close all)\n- list_plugin_windows: List open plugin windows',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    action: {
-                        type: 'string',
-                        enum: ['open_note', 'open_today', 'search', 'run_plugin', 'open_view', 'toggle_sidebar', 'close_plugin_window', 'list_plugin_windows'],
-                        description: 'Action to perform',
-                    },
-                    title: {
-                        type: 'string',
-                        description: 'Note title — used by open_note; window title — used by close_plugin_window',
-                    },
-                    filename: {
-                        type: 'string',
-                        description: 'Filename — used by open_note',
-                    },
-                    inNewWindow: {
-                        type: 'boolean',
-                        description: 'Open in new window — used by open_note',
-                    },
-                    inSplitView: {
-                        type: 'boolean',
-                        description: 'Open in split view — used by open_note',
-                    },
-                    query: {
-                        type: 'string',
-                        description: 'Search text — used by search',
-                    },
-                    pluginId: {
-                        type: 'string',
-                        description: 'Plugin ID — used by run_plugin',
-                    },
-                    command: {
-                        type: 'string',
-                        description: 'Command name — used by run_plugin',
-                    },
-                    arguments: {
-                        type: 'string',
-                        description: 'JSON arguments string — used by run_plugin',
-                    },
-                    name: {
-                        type: 'string',
-                        description: 'View name — used by open_view',
-                    },
-                    windowID: {
-                        type: 'string',
-                        description: 'Window ID — used by close_plugin_window',
-                    },
+    // noteplan_ui is always available — basic AppleScript commands work on all NotePlan versions
+    toolDefinitions.push({
+        name: 'noteplan_ui',
+        description: 'NotePlan UI control via AppleScript.\n\nActions:\n- open_note: Open a note (title or filename)\n- open_today: Open today\'s note\n- search: Search in UI\n- run_plugin: Run a plugin command (requires pluginId + command)\n- open_view: Open a named view\n- toggle_sidebar: Toggle sidebar visibility\n- close_plugin_window: Close plugin window (by windowID/title, or omit both to close all)\n- list_plugin_windows: List open plugin windows\n- backup: Create a full backup of all notes, calendars, themes, filters, and plugin data. Old backups are pruned automatically.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['open_note', 'open_today', 'search', 'run_plugin', 'open_view', 'toggle_sidebar', 'close_plugin_window', 'list_plugin_windows', 'backup'],
+                    description: 'Action: open_note | open_today | search | run_plugin | open_view | toggle_sidebar | close_plugin_window | list_plugin_windows | backup',
                 },
-                required: ['action'],
-            },
-        }, {
-            name: 'noteplan_plugins',
-            description: 'Plugin management: list, create, delete, install, read source/log, update HTML, screenshot.\n\nActions:\n- list: List installed plugins\n- list_available: List plugins from online repository\n- create: Create plugin with HTML view (requires pluginId, pluginName, commandName, html)\n- delete: Delete plugin (requires pluginId + confirmationToken)\n- install: Install from repository (requires pluginId)\n- log: Read plugin console log (requires pluginId)\n- source: Read plugin source (requires pluginId)\n- update_html: Apply find/replace patches (requires pluginId + patches)\n- screenshot: Capture plugin WebView screenshot (requires pluginId)',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    action: {
-                        type: 'string',
-                        enum: ['list', 'list_available', 'create', 'delete', 'install', 'log', 'source', 'update_html', 'screenshot'],
-                        description: 'Action to perform',
-                    },
-                    pluginId: {
-                        type: 'string',
-                        description: 'Plugin ID — used by create, delete, install, log, source, update_html, screenshot',
-                    },
-                    pluginName: {
-                        type: 'string',
-                        description: 'Display name — used by create',
-                    },
-                    commandName: {
-                        type: 'string',
-                        description: 'Command name — used by create',
-                    },
-                    html: {
-                        type: 'string',
-                        description: 'HTML content — used by create',
-                    },
-                    icon: {
-                        type: 'string',
-                        description: 'Font Awesome icon name — used by create',
-                    },
-                    iconColor: {
-                        type: 'string',
-                        description: 'Tailwind color — used by create',
-                    },
-                    displayMode: {
-                        type: 'string',
-                        enum: ['main', 'split', 'window'],
-                        description: 'Display mode (default: main) — used by create',
-                    },
-                    autoLaunch: {
-                        type: 'boolean',
-                        description: 'Auto-reload and run — used by create, update_html',
-                    },
-                    patches: {
-                        type: 'array',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                find: { type: 'string' },
-                                replace: { type: 'string' },
-                            },
-                            required: ['find', 'replace'],
-                        },
-                        description: 'Find/replace patches — used by update_html',
-                    },
-                    query: {
-                        type: 'string',
-                        description: 'Filter/search — used by list, list_available, source',
-                    },
-                    includeBeta: {
-                        type: 'boolean',
-                        description: 'Include beta plugins — used by list_available',
-                    },
-                    tail: {
-                        type: 'integer',
-                        description: 'Return last N lines — used by log',
-                    },
-                    clear: {
-                        type: 'boolean',
-                        description: 'Clear log after reading — used by log',
-                    },
-                    startLine: {
-                        type: 'integer',
-                        description: 'Start line (1-based) — used by source',
-                    },
-                    endLine: {
-                        type: 'integer',
-                        description: 'End line (1-based) — used by source',
-                    },
-                    contextLines: {
-                        type: 'integer',
-                        description: 'Context lines around matches — used by source',
-                    },
-                    confirmationToken: {
-                        type: 'string',
-                        description: 'Token for confirmation — used by delete',
-                    },
+                title: {
+                    type: 'string',
+                    description: 'Note title — used by open_note; window title — used by close_plugin_window',
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Filename — used by open_note',
+                },
+                inNewWindow: {
+                    type: 'boolean',
+                    description: 'Open in new window — used by open_note',
+                },
+                inSplitView: {
+                    type: 'boolean',
+                    description: 'Open in split view — used by open_note',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search text — used by search',
+                },
+                pluginId: {
+                    type: 'string',
+                    description: 'Plugin ID — used by run_plugin',
+                },
+                command: {
+                    type: 'string',
+                    description: 'Command name — used by run_plugin',
+                },
+                arguments: {
+                    type: 'string',
+                    description: 'JSON arguments string — used by run_plugin',
+                },
+                name: {
+                    type: 'string',
+                    description: 'View name — used by open_view',
+                },
+                windowID: {
+                    type: 'string',
+                    description: 'Window ID — used by close_plugin_window',
                 },
-                required: ['action'],
             },
-        }, {
-            name: 'noteplan_themes',
-            description: 'Theme management: list, get, save, set active.\n\nActions:\n- list: List all themes and active theme names\n- get: Read a custom theme JSON (requires filename)\n- save: Create/update a custom theme (requires filename + theme)\n- set_active: Activate a theme (requires name)',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    action: {
-                        type: 'string',
-                        enum: ['list', 'get', 'save', 'set_active'],
-                        description: 'Action to perform',
-                    },
-                    filename: {
-                        type: 'string',
-                        description: 'Theme filename — used by get, save',
-                    },
-                    name: {
-                        type: 'string',
-                        description: 'Theme name — used by set_active',
-                    },
-                    theme: {
+            required: ['action'],
+        },
+    });
+    // Always register all tools — if NotePlan is too old for a specific action,
+    // the action handler returns a helpful upgrade message instead of hiding the tool entirely.
+    toolDefinitions.push({
+        name: 'noteplan_plugins',
+        description: 'Plugin management: list, create, delete, install, read source/log, update HTML, screenshot.\n\nActions:\n- list: List installed plugins\n- list_available: List plugins from online repository\n- create: Create plugin with HTML view (requires pluginId, pluginName, commandName, html)\n- delete: Delete plugin (requires pluginId + confirmationToken)\n- install: Install from repository (requires pluginId)\n- log: Read plugin console log (requires pluginId)\n- source: Read plugin source (requires pluginId)\n- update_html: Apply find/replace patches (requires pluginId + patches)\n- screenshot: Capture plugin WebView screenshot (requires pluginId)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'list_available', 'create', 'delete', 'install', 'log', 'source', 'update_html', 'screenshot'],
+                    description: 'Action: list | list_available | create | delete | install | log | source | update_html | screenshot',
+                },
+                pluginId: {
+                    type: 'string',
+                    description: 'Plugin ID — used by create, delete, install, log, source, update_html, screenshot',
+                },
+                pluginName: {
+                    type: 'string',
+                    description: 'Display name — used by create',
+                },
+                commandName: {
+                    type: 'string',
+                    description: 'Command name — used by create',
+                },
+                html: {
+                    type: 'string',
+                    description: 'HTML content — used by create',
+                },
+                icon: {
+                    type: 'string',
+                    description: 'Font Awesome icon name — used by create',
+                },
+                iconColor: {
+                    type: 'string',
+                    description: 'Tailwind color — used by create',
+                },
+                displayMode: {
+                    type: 'string',
+                    enum: ['main', 'split', 'window'],
+                    description: 'Display mode (default: main) — used by create',
+                },
+                autoLaunch: {
+                    type: 'boolean',
+                    description: 'Auto-reload and run — used by create, update_html',
+                },
+                patches: {
+                    type: 'array',
+                    items: {
                         type: 'object',
-                        description: 'Theme object — used by save',
                         properties: {
-                            name: { type: 'string' },
-                            style: { type: 'string', enum: ['Light', 'Dark'] },
-                            author: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } },
-                            editor: { type: 'object' },
-                            styles: { type: 'object' },
+                            find: { type: 'string' },
+                            replace: { type: 'string' },
                         },
+                        required: ['find', 'replace'],
                     },
-                    setActive: {
-                        type: 'boolean',
-                        description: 'Apply theme immediately — used by save (default: true)',
-                    },
-                    mode: {
-                        type: 'string',
-                        enum: ['light', 'dark', 'auto'],
-                        description: 'Mode to apply for — used by save, set_active',
+                    description: 'Find/replace patches — used by update_html',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Filter/search — used by list, list_available, source',
+                },
+                includeBeta: {
+                    type: 'boolean',
+                    description: 'Include beta plugins — used by list_available',
+                },
+                tail: {
+                    type: 'integer',
+                    description: 'Return last N lines — used by log',
+                },
+                clear: {
+                    type: 'boolean',
+                    description: 'Clear log after reading — used by log',
+                },
+                startLine: {
+                    type: 'integer',
+                    description: 'Start line (1-based) — used by source',
+                },
+                endLine: {
+                    type: 'integer',
+                    description: 'End line (1-based) — used by source',
+                },
+                contextLines: {
+                    type: 'integer',
+                    description: 'Context lines around matches — used by source',
+                },
+                confirmationToken: {
+                    type: 'string',
+                    description: 'Token for confirmation — used by delete',
+                },
+            },
+            required: ['action'],
+        },
+    }, {
+        name: 'noteplan_themes',
+        description: 'Theme management: list, get, save, set active.\n\nActions:\n- list: List all themes and active theme names\n- get: Read a custom theme JSON (requires filename)\n- save: Create/update a custom theme (requires filename + theme)\n- set_active: Activate a theme (requires name)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'get', 'save', 'set_active'],
+                    description: 'Action: list | get | save | set_active',
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Theme filename — used by get, save',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Theme name — used by set_active',
+                },
+                theme: {
+                    type: 'object',
+                    description: 'Theme object — used by save',
+                    properties: {
+                        name: { type: 'string' },
+                        style: { type: 'string', enum: ['Light', 'Dark'] },
+                        author: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } },
+                        editor: { type: 'object' },
+                        styles: { type: 'object' },
                     },
                 },
-                required: ['action'],
+                setActive: {
+                    type: 'boolean',
+                    description: 'Apply theme immediately — used by save (default: true)',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['light', 'dark', 'auto'],
+                    description: 'Mode to apply for — used by save, set_active',
+                },
             },
-        });
-    }
+            required: ['action'],
+        },
+    }, {
+        name: 'noteplan_templates',
+        description: 'Template operations: list available templates or render a template.\n\nActions:\n- list: List templates from @Templates folder with their types and preview\n- render: Render a template by title (saved template) or raw content string (for debugging). Rendering requires a recent NotePlan build.\n\nDebugging workflow: After creating or editing a template, use render with its title or raw content to verify the output. Check variables, date formatting, and logic. If rendering fails or produces unexpected output, read the plugin log via noteplan_plugins(action: "log", pluginId: "np.Templating") for error details.\n\nTemplate syntax: <%- expr %> (output), <% code %> (logic), <%= expr %> (escaped output). Common helpers: date.now("YYYY-MM-DD"), web.weather(), date.tomorrow("format").',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'render'],
+                    description: 'Action: list | render',
+                },
+                templateTitle: {
+                    type: 'string',
+                    description: 'Template title — used by render (loads a saved template by title)',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Raw template content string — used by render (renders arbitrary template code for debugging)',
+                },
+                folder: {
+                    type: 'string',
+                    description: 'Template subfolder — used by list (default: @Templates)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum results — used by list',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Pagination offset — used by list',
+                },
+                cursor: {
+                    type: 'string',
+                    description: 'Cursor from previous page — used by list',
+                },
+            },
+            required: ['action'],
+        },
+    }, {
+        name: 'noteplan_attachments',
+        description: 'Attachment operations: add files/images to notes, list attachments, get attachment data, or move between notes.\n\nActions:\n- add: Write a file to the note\'s _attachments folder. Requires data (base64) + attachmentFilename. Returns markdownLink — use noteplan_edit_content to place it in the note (insertLink defaults to false).\n- list: List all attachments for a note with filenames, sizes, and markdown links.\n- get: Get attachment metadata. Set includeData=true for base64 content. Use maxDataSize to cap large images.\n- move: Move an attachment between notes. Source note via id/filename/title/date, destination via destinationId/destinationFilename/destinationTitle/destinationDate. Moves file, removes old link from source, returns new markdownLink.\n\nAttachments are stored in {notename}_attachments/ sibling folder. Images: ![image](path), files: ![file](path). Use attachmentFilename for both add, get, and move.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['add', 'list', 'get', 'move'],
+                    description: 'Action: add | list | get | move',
+                },
+                id: { type: 'string', description: 'Source note ID — used by all actions' },
+                filename: { type: 'string', description: 'Source note filename/path — used by all actions' },
+                title: { type: 'string', description: 'Source note title — used by all actions' },
+                date: { type: 'string', description: 'Source calendar note date (YYYYMMDD or YYYY-MM-DD) — used by all actions' },
+                query: { type: 'string', description: 'Search query to find the source note' },
+                space: { type: 'string', description: 'Space name or ID' },
+                data: { type: 'string', description: 'Base64-encoded file data — required for add' },
+                attachmentFilename: { type: 'string', description: 'Attachment filename (e.g. "photo.png") — required for add, get, and move' },
+                mimeType: { type: 'string', description: 'MIME type hint (e.g. "image/png") — used by add' },
+                insertLink: { type: 'boolean', description: 'Auto-insert markdown link into note — used by add (default: false). Prefer placing links yourself via noteplan_edit_content.' },
+                destinationId: { type: 'string', description: 'Destination note ID — used by move' },
+                destinationFilename: { type: 'string', description: 'Destination note filename — used by move' },
+                destinationTitle: { type: 'string', description: 'Destination note title — used by move' },
+                destinationDate: { type: 'string', description: 'Destination calendar note date — used by move' },
+                includeData: { type: 'boolean', description: 'Include base64 data in response — used by get (default: false)' },
+                maxDataSize: { type: 'number', description: 'Max file size in bytes for data inclusion — used by get. Files exceeding this are skipped.' },
+            },
+            required: ['action'],
+        },
+    });
     const annotatedToolDefinitions = toolDefinitions.map((tool) => ({
         ...tool,
         inputSchema: withDebugTimingsInputSchema(tool.inputSchema),
@@ -2121,7 +2225,7 @@ export function createServer() {
                         case 'remove_property':
                             result = noteTools.removeProperty(args);
                             break;
-                        default: throw new Error(`Unknown action: ${action}`);
+                        default: throw new Error(`Unknown action: "${action}". Valid actions: create, update, delete, move, restore, rename, set_property, remove_property`);
                     }
                     break;
                 }
@@ -2152,7 +2256,7 @@ export function createServer() {
                         case 'replace_lines':
                             result = noteTools.replaceLines(a);
                             break;
-                        default: throw new Error(`Unknown action: ${action}`);
+                        default: throw new Error(`Unknown action: "${action}". Valid actions: insert, append, delete_lines, edit_line, replace_lines (snake_case required)`);
                     }
                     break;
                 }
@@ -2166,6 +2270,10 @@ export function createServer() {
                     if (a.scheduleDate && a.content) {
                         a.content = appendScheduleDate(a.content, a.scheduleDate);
                     }
+                    // Derive `target` for addTaskToNote from date/filename when not provided
+                    if (!a.target && (a.date || a.filename)) {
+                        a.target = a.date || a.filename;
+                    }
                     const action = a?.action;
                     switch (action) {
                         case 'get':
@@ -2346,7 +2454,67 @@ export function createServer() {
                         case 'list_plugin_windows':
                             result = uiTools.listPluginWindows(args);
                             break;
-                        default: throw new Error(`Unknown action: ${action}`);
+                        case 'backup': {
+                            if (versionInfo.build < MIN_BUILD_CREATE_BACKUP) {
+                                result = { success: false, error: `Backup requires NotePlan build ${MIN_BUILD_CREATE_BACKUP}+. Current: ${versionInfo.build}.`, code: 'ERR_VERSION_GATE' };
+                            }
+                            else {
+                                result = uiTools.createBackup(args);
+                            }
+                            break;
+                        }
+                        default: {
+                            // Help the LLM recover from common mistakes (camelCase, missing underscore, etc.)
+                            const UI_ACTION_ALIASES = {
+                                open: 'open_note', opennote: 'open_note', open_notes: 'open_note',
+                                opentoday: 'open_today', today: 'open_today',
+                                openview: 'open_view', view: 'open_view',
+                                runplugin: 'run_plugin', plugin: 'run_plugin',
+                                togglesidebar: 'toggle_sidebar', sidebar: 'toggle_sidebar',
+                                closepluginwindow: 'close_plugin_window',
+                                listpluginwindows: 'list_plugin_windows',
+                                navigate: 'open_note', show: 'open_note', select: 'open_note',
+                            };
+                            const normalized = (action || '').toLowerCase().replace(/[\s_-]/g, '');
+                            const resolved = UI_ACTION_ALIASES[normalized];
+                            if (resolved) {
+                                args.action = resolved;
+                                // Re-dispatch with corrected action
+                                switch (resolved) {
+                                    case 'open_note':
+                                        result = uiTools.openNote(args);
+                                        break;
+                                    case 'open_today':
+                                        result = uiTools.openToday(args);
+                                        break;
+                                    case 'search':
+                                        result = uiTools.searchNotes(args);
+                                        break;
+                                    case 'run_plugin':
+                                        result = uiTools.runPlugin(args);
+                                        break;
+                                    case 'open_view':
+                                        result = uiTools.openView(args);
+                                        break;
+                                    case 'toggle_sidebar':
+                                        result = uiTools.toggleSidebar(args);
+                                        break;
+                                    case 'close_plugin_window':
+                                        result = uiTools.closePluginWindow(args);
+                                        break;
+                                    case 'list_plugin_windows':
+                                        result = uiTools.listPluginWindows(args);
+                                        break;
+                                    case 'backup':
+                                        result = uiTools.createBackup(args);
+                                        break;
+                                    default: throw new Error(`Unknown action: ${action}. Valid actions: open_note, open_today, search, run_plugin, open_view, toggle_sidebar, close_plugin_window, list_plugin_windows, backup`);
+                                }
+                            }
+                            else {
+                                throw new Error(`Unknown action: "${action}". Valid actions: open_note, open_today, search, run_plugin, open_view, toggle_sidebar, close_plugin_window, list_plugin_windows, backup`);
+                            }
+                        }
                     }
                     break;
                 }
@@ -2422,6 +2590,38 @@ export function createServer() {
                     }
                     break;
                 }
+                case 'noteplan_templates': {
+                    const action = args?.action;
+                    switch (action) {
+                        case 'list':
+                            result = templateTools.listTemplates(args);
+                            break;
+                        case 'render':
+                            result = templateTools.renderTemplate(args);
+                            break;
+                        default: throw new Error(`Unknown action: ${action}`);
+                    }
+                    break;
+                }
+                case 'noteplan_attachments': {
+                    const action = args?.action;
+                    switch (action) {
+                        case 'add':
+                            result = attachmentTools.addAttachment(args);
+                            break;
+                        case 'list':
+                            result = attachmentTools.listAttachments(args);
+                            break;
+                        case 'get':
+                            result = attachmentTools.getAttachment(args);
+                            break;
+                        case 'move':
+                            result = attachmentTools.moveAttachment(args);
+                            break;
+                        default: throw new Error(`Unknown action: ${action}. Valid actions: add, list, get, move`);
+                    }
+                    break;
+                }
                 default:
                     throw new Error(`Unknown tool: ${name} (normalized: ${normalizedName})`);
             }