@noteplanco/noteplan-mcp 1.1.7 → 1.1.8

package/dist/server.js

@@ -27,6 +27,10 @@ import { initSqlite } from './noteplan/sqlite-loader.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PLUGIN_API_DOCS_DIR = path.join(__dirname, '../docs/plugin-api');
+const DOCS_DIR = path.join(__dirname, '../docs');
+const GENERAL_DOC_RESOURCES = [
+    { file: 'x-callback-url.md', name: 'x-callback-url Reference', desc: 'NotePlan URL scheme — all actions (openNote, addText, addNote, addQuickTask, search, runPlugin, etc.), parameters, and encoding examples' },
+];
 const PLUGIN_API_RESOURCES = [
     { file: 'plugin-api-condensed.md', name: 'Plugin API Reference (Condensed)', desc: 'Complete NotePlan plugin API — all signatures, types, and patterns in one reference. Read this first.' },
     { file: 'getting-started.md', name: 'Getting Started Guide', desc: 'How to create NotePlan plugins — structure, setup, first plugin, testing, HTML views' },
@@ -818,12 +822,59 @@ function withDuration(result, durationMs, includeTiming) {
 export function createServer() {
     const server = new Server({
         name: 'NotePlan',
-        version: '1.1.4',
+        version: '1.1.7',
     }, {
         capabilities: {
             tools: {},
             resources: {},
         },
+        instructions: [
+            'You have access to NotePlan — a markdown-based note-taking and task management app for macOS/iOS.',
+            'All tools use action-based dispatch: one tool per domain, with an `action` parameter to select the operation.',
+            '',
+            '## Workflow',
+            '',
+            'Prefer granular edits over full-note rewrites to avoid large context payloads and accidental data loss.',
+            '',
+            '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',
+            '3. **Edit** with targeted mutations:',
+            '   - `noteplan_edit_content(action: edit_line)` — single-line change',
+            '   - `noteplan_edit_content(action: insert/append)` — add content at a position or heading',
+            '   - `noteplan_edit_content(action: delete_lines)` — remove lines',
+            '4. Only use `noteplan_manage_note(action: update)` for intentional full-note rewrites',
+            '',
+            '## Tasks',
+            '',
+            '- Add tasks via `noteplan_paragraphs(action: add)` — the server auto-formats the task marker to match the user\'s NotePlan settings. Never write raw markers like `- [ ]` or `* [ ]`; just pass the task text.',
+            '- Find tasks: `noteplan_paragraphs(action: search)` in one note, or `search_global` across all notes',
+            '- Complete/update: `noteplan_paragraphs(action: complete/update)`',
+            '- Use `heading` parameter to target a specific section (e.g., heading: "Tasks")',
+            '',
+            '## Destructive Operations',
+            '',
+            'Delete, move, rename, and restore use a 2-step safety flow:',
+            '1. Call with `dryRun=true` → get a preview and `confirmationToken`',
+            '2. Call again with that `confirmationToken` to execute',
+            '',
+            '## Key Behaviors',
+            '',
+            '- Calendar notes (daily/weekly/etc.) are auto-created when targeted by date — no need to create them first',
+            '- Notes can be targeted by `id`, `filename`, `title`, `date`, or `query` — prefer `id` or `filename` when available for precision',
+            '- Errors include a `hint` and often a `suggestedTool` to guide recovery',
+            '- The `noteplan_memory` tool stores user preferences (formatting, style, workflow) persistently across sessions',
+            '',
+            '## Templates',
+            '',
+            '- IMPORTANT: Before writing or editing templates, ALWAYS search the built-in documentation first: `noteplan_templates(action: "search_docs", query: "your topic")`',
+            '- Use `get_doc` to read the full text of a doc chunk returned by `search_docs`',
+            '- Then use `render` to test/debug your template code',
+            '',
+            '## Action Discovery',
+            '',
+            '- Every tool supports `action: "list_actions"` — call it to get a list of all available actions with descriptions',
+            '- Use `list_actions` when you are unsure what a tool can do or need to discover capabilities',
+        ].join('\n'),
     });
     let embeddingsToolsEnabled = false;
     try {
@@ -1003,8 +1054,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['create', 'update', 'delete', 'move', 'restore', 'rename', 'set_property', 'remove_property'],
-                        description: 'Action: create | update | delete | move | restore | rename | set_property | remove_property',
+                        enum: ['create', 'update', 'delete', 'move', 'restore', 'rename', 'set_property', 'remove_property', 'list_actions'],
+                        description: 'Action: create | update | delete | move | restore | rename | set_property | remove_property | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -1100,8 +1151,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['insert', 'append', 'delete_lines', 'edit_line', 'replace_lines'],
-                        description: 'Action: insert | append | delete_lines | edit_line | replace_lines',
+                        enum: ['insert', 'append', 'delete_lines', 'edit_line', 'replace_lines', 'list_actions'],
+                        description: 'Action: insert | append | delete_lines | edit_line | replace_lines | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -1207,8 +1258,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['get', 'search', 'search_global', 'add', 'complete', 'update'],
-                        description: 'Action: get | search | search_global | add | complete | update',
+                        enum: ['get', 'search', 'search_global', 'add', 'complete', 'update', 'list_actions'],
+                        description: 'Action: get | search | search_global | add | complete | update | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -1354,8 +1405,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['list', 'find', 'resolve', 'create', 'move', 'rename', 'delete', 'list_spaces'],
-                        description: 'Action: list | find | resolve | create | move | rename | delete | list_spaces',
+                        enum: ['list', 'find', 'resolve', 'create', 'move', 'rename', 'delete', 'list_spaces', 'list_actions'],
+                        description: 'Action: list | find | resolve | create | move | rename | delete | list_spaces | list_actions (discover all actions)',
                     },
                     path: {
                         type: 'string',
@@ -1457,8 +1508,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['list', 'get', 'get_tasks', 'list_parameters', 'save', 'rename'],
-                        description: 'Action: list | get | get_tasks | list_parameters | save | rename',
+                        enum: ['list', 'get', 'get_tasks', 'list_parameters', 'save', 'rename', 'list_actions'],
+                        description: 'Action: list | get | get_tasks | list_parameters | save | rename | list_actions (discover all actions)',
                     },
                     name: {
                         type: 'string',
@@ -1542,8 +1593,8 @@ 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: get_events | list_calendars | create_event | update_event | delete_event | get | list_lists | create | complete | update | delete',
+                        enum: ['get_events', 'list_calendars', 'create_event', 'update_event', 'delete_event', 'get', 'list_lists', 'create', 'complete', 'update', 'delete', 'list_actions'],
+                        description: 'Action: get_events | list_calendars | create_event | update_event | delete_event | get | list_lists | create | complete | update | delete | list_actions (discover all actions)',
                     },
                     // Calendar params
                     eventId: {
@@ -1644,8 +1695,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['list', 'save', 'update', 'delete'],
-                        description: 'Action: list | save | update | delete',
+                        enum: ['list', 'save', 'update', 'delete', 'list_actions'],
+                        description: 'Action: list | save | update | delete | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -1691,8 +1742,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['search', 'list_tags'],
-                        description: 'Action to perform (default: search)',
+                        enum: ['search', 'list_tags', 'list_actions'],
+                        description: 'Action to perform (default: search) | list_actions (discover all actions)',
                     },
                     query: {
                         type: 'string',
@@ -1780,8 +1831,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['status', 'search', 'sync', 'reset'],
-                        description: 'Action: status | search | sync | reset',
+                        enum: ['status', 'search', 'sync', 'reset', 'list_actions'],
+                        description: 'Action: status | search | sync | reset | list_actions (discover all actions)',
                     },
                     query: {
                         type: 'string',
@@ -1867,8 +1918,8 @@ export function createServer() {
             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',
+                    enum: ['open_note', 'open_today', 'search', 'run_plugin', 'open_view', 'toggle_sidebar', 'close_plugin_window', 'list_plugin_windows', 'backup', 'list_actions'],
+                    description: 'Action: open_note | open_today | search | run_plugin | open_view | toggle_sidebar | close_plugin_window | list_plugin_windows | backup | list_actions (discover all actions)',
                 },
                 title: {
                     type: 'string',
@@ -1924,8 +1975,8 @@ export function createServer() {
             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',
+                    enum: ['list', 'list_available', 'create', 'delete', 'install', 'log', 'source', 'update_html', 'screenshot', 'list_actions'],
+                    description: 'Action: list | list_available | create | delete | install | log | source | update_html | screenshot | list_actions (discover all actions)',
                 },
                 pluginId: {
                     type: 'string',
@@ -2015,8 +2066,8 @@ export function createServer() {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'get', 'save', 'set_active'],
-                    description: 'Action: list | get | save | set_active',
+                    enum: ['list', 'get', 'save', 'set_active', 'list_actions'],
+                    description: 'Action: list | get | save | set_active | list_actions (discover all actions)',
                 },
                 filename: {
                     type: 'string',
@@ -2051,14 +2102,14 @@ export function createServer() {
         },
     }, {
         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").',
+        description: 'Template operations: list available templates, render a template, or search template documentation.\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- search_docs: Semantic search over bundled NotePlan template documentation. Requires query param. Uses embeddings API or NotePlan built-in embedding. Returns matched doc chunks ranked by relevance — use this to look up template syntax, helpers, and examples before writing templates.\n- get_doc: Retrieve the full text of a doc chunk by noteTitle and chunkIndex (from search_docs results). Use this to read complete method signatures, format tokens, and examples that may be truncated in search_docs previews.\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',
+                    enum: ['list', 'render', 'search_docs', 'get_doc', 'list_actions'],
+                    description: 'Action: list | render | search_docs | get_doc | list_actions (discover all actions)',
                 },
                 templateTitle: {
                     type: 'string',
@@ -2084,6 +2135,22 @@ export function createServer() {
                     type: 'string',
                     description: 'Cursor from previous page — used by list',
                 },
+                query: {
+                    type: 'string',
+                    description: 'Search query — used by search_docs',
+                },
+                includeContent: {
+                    type: 'boolean',
+                    description: 'Include full chunk text in results — used by search_docs',
+                },
+                noteTitle: {
+                    type: 'string',
+                    description: 'Doc note title — used by get_doc (from search_docs results)',
+                },
+                chunkIndex: {
+                    type: 'number',
+                    description: 'Chunk index — used by get_doc (from search_docs results, default 0)',
+                },
             },
             required: ['action'],
         },
@@ -2095,8 +2162,8 @@ export function createServer() {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['add', 'list', 'get', 'move'],
-                    description: 'Action: add | list | get | move',
+                    enum: ['add', 'list', 'get', 'move', 'list_actions'],
+                    description: 'Action: add | list | get | move | list_actions (discover all actions)',
                 },
                 id: { type: 'string', description: 'Source note ID — used by all actions' },
                 filename: { type: 'string', description: 'Source note filename/path — used by all actions' },
@@ -2134,42 +2201,178 @@ export function createServer() {
     });
     // Register resource listing handler
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        return {
-            resources: PLUGIN_API_RESOURCES.map((r) => ({
-                uri: `noteplan://plugin-api/${r.file}`,
-                name: r.name,
-                description: r.desc,
-                mimeType: r.file.endsWith('.md') ? 'text/markdown' : r.file.endsWith('.json') ? 'application/json' : 'text/javascript',
-            })),
-        };
+        const pluginResources = PLUGIN_API_RESOURCES.map((r) => ({
+            uri: `noteplan://plugin-api/${r.file}`,
+            name: r.name,
+            description: r.desc,
+            mimeType: r.file.endsWith('.md') ? 'text/markdown' : r.file.endsWith('.json') ? 'application/json' : 'text/javascript',
+        }));
+        const generalResources = GENERAL_DOC_RESOURCES.map((r) => ({
+            uri: `noteplan://docs/${r.file}`,
+            name: r.name,
+            description: r.desc,
+            mimeType: 'text/markdown',
+        }));
+        return { resources: [...pluginResources, ...generalResources] };
     });
     // Register resource read handler
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const uri = request.params.uri;
-        const prefix = 'noteplan://plugin-api/';
-        if (!uri.startsWith(prefix)) {
-            throw new Error(`Unknown resource URI: ${uri}`);
+        const pluginPrefix = 'noteplan://plugin-api/';
+        const docsPrefix = 'noteplan://docs/';
+        let filePath;
+        if (uri.startsWith(pluginPrefix)) {
+            const filename = uri.slice(pluginPrefix.length);
+            const entry = PLUGIN_API_RESOURCES.find((r) => r.file === filename);
+            if (!entry) {
+                throw new Error(`Unknown resource: ${filename}. Available: ${PLUGIN_API_RESOURCES.map((r) => r.file).join(', ')}`);
+            }
+            filePath = path.join(PLUGIN_API_DOCS_DIR, entry.file);
+        }
+        else if (uri.startsWith(docsPrefix)) {
+            const filename = uri.slice(docsPrefix.length);
+            const entry = GENERAL_DOC_RESOURCES.find((r) => r.file === filename);
+            if (!entry) {
+                throw new Error(`Unknown resource: ${filename}. Available: ${GENERAL_DOC_RESOURCES.map((r) => r.file).join(', ')}`);
+            }
+            filePath = path.join(DOCS_DIR, entry.file);
         }
-        const filename = uri.slice(prefix.length);
-        const entry = PLUGIN_API_RESOURCES.find((r) => r.file === filename);
-        if (!entry) {
-            throw new Error(`Unknown resource: ${filename}. Available: ${PLUGIN_API_RESOURCES.map((r) => r.file).join(', ')}`);
+        else {
+            throw new Error(`Unknown resource URI: ${uri}`);
         }
-        const filePath = path.join(PLUGIN_API_DOCS_DIR, entry.file);
         if (!fs.existsSync(filePath)) {
             throw new Error(`Resource file not found on disk: ${filePath}`);
         }
         const content = fs.readFileSync(filePath, 'utf-8');
+        const mimeType = filePath.endsWith('.md') ? 'text/markdown' : filePath.endsWith('.json') ? 'application/json' : 'text/javascript';
         return {
-            contents: [
-                {
-                    uri,
-                    mimeType: entry.file.endsWith('.md') ? 'text/markdown' : entry.file.endsWith('.json') ? 'application/json' : 'text/javascript',
-                    text: content,
-                },
-            ],
+            contents: [{ uri, mimeType, text: content }],
         };
     });
+    // ── Action registry for list_actions discovery ──
+    const TOOL_ACTIONS = {
+        noteplan_get_notes: [
+            { action: 'get', description: 'Get a single note by id, filename, title, date, or query' },
+            { action: 'list', description: 'List notes with optional folder/type/date filtering' },
+            { action: 'resolve', description: 'Resolve a reference (title, filename, query) to a single note' },
+            { action: 'today', description: 'Get today\'s daily note' },
+            { action: 'calendar', description: 'Get a calendar note by date' },
+            { action: 'periodic', description: 'Get a periodic note (week, month, quarter, year)' },
+            { action: 'range', description: 'Get calendar notes in a date range' },
+        ],
+        noteplan_search: [
+            { action: 'search', description: 'Full-text or metadata search across notes' },
+            { action: 'list_tags', description: 'List all tags/hashtags with optional filtering' },
+        ],
+        noteplan_manage_note: [
+            { action: 'create', description: 'Create a project note (requires title)' },
+            { action: 'update', description: 'Replace note content (requires filename, content, fullReplace + confirmationToken)' },
+            { action: 'delete', description: 'Delete a note (requires dryRun/confirmationToken)' },
+            { action: 'move', description: 'Move a note to another folder (requires dryRun/confirmationToken)' },
+            { action: 'restore', description: 'Restore a trashed note (requires dryRun/confirmationToken)' },
+            { action: 'rename', description: 'Rename a note (requires newTitle)' },
+            { action: 'set_property', description: 'Set a frontmatter property (requires key + value)' },
+            { action: 'remove_property', description: 'Remove a frontmatter property (requires key)' },
+        ],
+        noteplan_edit_content: [
+            { action: 'insert', description: 'Insert content at a position. Use heading param to scope to a section' },
+            { action: 'append', description: 'Append content at end of note or section' },
+            { action: 'delete_lines', description: 'Delete a line range (requires startLine + endLine, 1-indexed)' },
+            { action: 'edit_line', description: 'Edit a single line (requires line + content)' },
+            { action: 'replace_lines', description: 'Replace a line range (requires startLine + endLine + content)' },
+        ],
+        noteplan_paragraphs: [
+            { action: 'get', description: 'Get note lines with metadata (requires filename)' },
+            { action: 'search', description: 'Search for matching lines in a note (requires query + note ref)' },
+            { action: 'search_global', description: 'Search tasks across all notes (requires query, supports "*" wildcard)' },
+            { action: 'add', description: 'Add a task (requires target + content)' },
+            { action: 'complete', description: 'Mark task done (requires filename + lineIndex or line)' },
+            { action: 'update', description: 'Update task content/status (requires filename + lineIndex or line)' },
+        ],
+        noteplan_folders: [
+            { action: 'list', description: 'List folders with optional filtering' },
+            { action: 'find', description: 'Find folder matches for exploration' },
+            { action: 'resolve', description: 'Resolve to one canonical folder path' },
+            { action: 'create', description: 'Create a folder' },
+            { action: 'move', description: 'Move a folder (requires dryRun/confirmationToken)' },
+            { action: 'rename', description: 'Rename a folder (requires dryRun/confirmationToken)' },
+            { action: 'delete', description: 'Delete folder to trash (requires dryRun/confirmationToken)' },
+            { action: 'list_spaces', description: 'List spaces/workspaces' },
+        ],
+        noteplan_filters: [
+            { action: 'list', description: 'List saved filters' },
+            { action: 'get', description: 'Get one filter with parsed params (requires name)' },
+            { action: 'get_tasks', description: 'Execute a filter against tasks (requires name)' },
+            { action: 'list_parameters', description: 'List supported filter parameter keys' },
+            { action: 'save', description: 'Create or update a filter (requires name + items)' },
+            { action: 'rename', description: 'Rename a filter (requires oldName + newName)' },
+        ],
+        noteplan_eventkit: [
+            { action: 'get_events', description: 'Get events for a date/range (source: calendar)' },
+            { action: 'list_calendars', description: 'List all calendars (source: calendar)' },
+            { action: 'create_event', description: 'Create event (source: calendar, requires title + startDate)' },
+            { action: 'update_event', description: 'Update event (source: calendar, requires eventId)' },
+            { action: 'delete_event', description: 'Delete event (source: calendar, requires eventId + dryRun/confirmationToken)' },
+            { action: 'get', description: 'Get reminders (source: reminders, optional list/query filter)' },
+            { action: 'list_lists', description: 'List reminder lists (source: reminders)' },
+            { action: 'create', description: 'Create reminder (source: reminders, requires title)' },
+            { action: 'complete', description: 'Mark reminder done (source: reminders, requires reminderId)' },
+            { action: 'update', description: 'Update reminder (source: reminders, requires reminderId)' },
+            { action: 'delete', description: 'Delete reminder (source: reminders, requires reminderId + dryRun/confirmationToken)' },
+        ],
+        noteplan_memory: [
+            { action: 'list', description: 'List/search stored memories' },
+            { action: 'save', description: 'Save a new memory (requires content)' },
+            { action: 'update', description: 'Update memory content/tags (requires id)' },
+            { action: 'delete', description: 'Delete a memory (requires id)' },
+        ],
+        noteplan_ui: [
+            { action: 'open_note', description: 'Open a note by title or filename' },
+            { action: 'open_today', description: 'Open today\'s note' },
+            { action: 'search', description: 'Search in UI' },
+            { action: 'run_plugin', description: 'Run a plugin command (requires pluginId + command)' },
+            { action: 'open_view', description: 'Open a named view' },
+            { action: 'toggle_sidebar', description: 'Toggle sidebar visibility' },
+            { action: 'close_plugin_window', description: 'Close plugin window (by windowID/title, or omit both to close all)' },
+            { action: 'list_plugin_windows', description: 'List open plugin windows' },
+            { action: 'backup', description: 'Create a full backup of all notes, calendars, themes, filters, and plugin data' },
+        ],
+        noteplan_plugins: [
+            { action: 'list', description: 'List installed plugins' },
+            { action: 'list_available', description: 'List plugins from online repository' },
+            { action: 'create', description: 'Create plugin with HTML view (requires pluginId, pluginName, commandName, html)' },
+            { action: 'delete', description: 'Delete plugin (requires pluginId + confirmationToken)' },
+            { action: 'install', description: 'Install from repository (requires pluginId)' },
+            { action: 'log', description: 'Read plugin console log (requires pluginId)' },
+            { action: 'source', description: 'Read plugin source (requires pluginId)' },
+            { action: 'update_html', description: 'Apply find/replace patches (requires pluginId + patches)' },
+            { action: 'screenshot', description: 'Capture plugin WebView screenshot (requires pluginId)' },
+        ],
+        noteplan_themes: [
+            { action: 'list', description: 'List all themes and active theme names' },
+            { action: 'get', description: 'Read a custom theme JSON (requires filename)' },
+            { action: 'save', description: 'Create/update a custom theme (requires filename + theme)' },
+            { action: 'set_active', description: 'Activate a theme (requires name)' },
+        ],
+        noteplan_embeddings: [
+            { action: 'status', description: 'Get embeddings config and index status' },
+            { action: 'search', description: 'Semantic search over indexed notes (requires query)' },
+            { action: 'sync', description: 'Build/refresh embeddings index' },
+            { action: 'reset', description: 'Delete index rows (requires dryRun/confirmationToken)' },
+        ],
+        noteplan_templates: [
+            { action: 'list', description: 'List templates from @Templates folder with types and preview' },
+            { action: 'render', description: 'Render a template by title or raw content string' },
+            { action: 'search_docs', description: 'Semantic search over bundled template documentation (requires query). Use this to look up template syntax, helpers, and examples before writing templates' },
+            { action: 'get_doc', description: 'Get full text of a doc chunk by noteTitle + chunkIndex (from search_docs results)' },
+        ],
+        noteplan_attachments: [
+            { action: 'add', description: 'Write a file to the note\'s _attachments folder (requires data + attachmentFilename)' },
+            { action: 'list', description: 'List all attachments for a note' },
+            { action: 'get', description: 'Get attachment metadata. Set includeData=true for base64 content' },
+            { action: 'move', description: 'Move an attachment between notes' },
+        ],
+    };
     // Register tool call handler
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
@@ -2178,6 +2381,12 @@ export function createServer() {
         const startTime = Date.now();
         try {
             let result;
+            // ── Intercept list_actions for any tool with an action registry ──
+            if (args?.action === 'list_actions' && TOOL_ACTIONS[normalizedName]) {
+                result = { success: true, tool: normalizedName, actions: TOOL_ACTIONS[normalizedName] };
+                const resultWithDuration = withDuration(result, Date.now() - startTime, includeTiming);
+                return { content: [{ type: 'text', text: JSON.stringify(resultWithDuration, null, 2) }] };
+            }
             switch (normalizedName) {
                 // ── Primary consolidated tools ──
                 case 'noteplan_get_notes':
@@ -2283,7 +2492,7 @@ export function createServer() {
                             result = noteTools.searchParagraphs(a);
                             break;
                         case 'search_global':
-                            result = taskTools.searchTasksGlobal(a);
+                            result = noteTools.searchParagraphsGlobal(a);
                             break;
                         case 'add':
                             result = taskTools.addTaskToNote(a);
@@ -2599,6 +2808,12 @@ export function createServer() {
                         case 'render':
                             result = templateTools.renderTemplate(args);
                             break;
+                        case 'search_docs':
+                            result = await templateTools.searchDocs(args);
+                            break;
+                        case 'get_doc':
+                            result = templateTools.getDoc(args);
+                            break;
                         default: throw new Error(`Unknown action: ${action}`);
                     }
                     break;
@@ -2662,7 +2877,12 @@ export function createServer() {
             };
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            let errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            // Append list_actions hint for unknown action errors
+            if (errorMessage.includes('Unknown action') && TOOL_ACTIONS[normalizedName]) {
+                const validActions = TOOL_ACTIONS[normalizedName].map(a => a.action).join(', ');
+                errorMessage += `. Valid actions: ${validActions}. Tip: use action "list_actions" to discover all actions with descriptions.`;
+            }
             const meta = inferToolErrorMeta(normalizedName, errorMessage, registeredToolNames);
             const errorResult = {
                 success: false,