@noteplanco/noteplan-mcp 1.1.7 → 1.1.9

package/dist/server.js

@@ -24,9 +24,14 @@ import * as attachmentTools from './tools/attachments.js';
 import { parseFlexibleDate } from './utils/date-utils.js';
 import { upgradeMessage, getNotePlanVersion, getMcpServerVersion, MIN_BUILD_ADVANCED_FEATURES, MIN_BUILD_CREATE_BACKUP } from './utils/version.js';
 import { initSqlite } from './noteplan/sqlite-loader.js';
+import { getDatabase, getDatabasePath, listSpaces as listSpacesFromDb } from './noteplan/sqlite-reader.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 +823,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 {
@@ -842,6 +894,19 @@ export function createServer() {
         console.error('[noteplan-mcp] Failed to detect NotePlan version:', err);
     }
     console.error(`[noteplan-mcp] Detected NotePlan ${versionInfo.version} (build ${versionInfo.build}, source: ${versionInfo.source}). Advanced features: ${advancedFeaturesEnabled ? 'enabled' : 'disabled'}.`);
+    // Startup diagnostics: HOME, database, spaces
+    console.error(`[noteplan-mcp] HOME: ${process.env.HOME ?? '(unset)'}`);
+    const dbPath = getDatabasePath();
+    if (dbPath) {
+        const database = getDatabase();
+        const writable = database ? 'read-write' : 'unavailable';
+        console.error(`[noteplan-mcp] Space database: ${dbPath} (${writable})`);
+        const spaces = listSpacesFromDb();
+        console.error(`[noteplan-mcp] Spaces discovered: ${spaces.length}`);
+    }
+    else {
+        console.error('[noteplan-mcp] Space database: not found');
+    }
     const toolDefinitions = [
         // ── Consolidated tools (16 — action/param-based dispatch) ──
         {
@@ -997,18 +1062,18 @@ 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). 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)',
+            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 note ref via id/filename/title/date/query, 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 note ref via id/filename/title/date/query + key)',
             inputSchema: {
                 type: 'object',
                 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',
-                        description: 'Note ID — used by delete, move, rename, restore (preferred for TeamSpace notes)',
+                        description: 'Note ID — used by delete, move, rename, restore, set_property, remove_property (preferred for TeamSpace notes)',
                     },
                     filename: {
                         type: 'string',
@@ -1016,11 +1081,15 @@ export function createServer() {
                     },
                     title: {
                         type: 'string',
-                        description: 'Note title — required for create. Also used by rename to find the note by title (fuzzy matched).',
+                        description: 'Note title — required for create. Also used by rename, move, set_property, remove_property to find the note by title (fuzzy matched).',
+                    },
+                    date: {
+                        type: 'string',
+                        description: 'Calendar note date (YYYYMMDD, YYYY-MM-DD, today, tomorrow, yesterday) — used by set_property, remove_property, move',
                     },
                     query: {
                         type: 'string',
-                        description: 'Fuzzy search query to find the note — used by rename',
+                        description: 'Fuzzy search query to find the note — used by rename, move, set_property, remove_property',
                     },
                     content: {
                         type: 'string',
@@ -1100,8 +1169,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',
@@ -1201,18 +1270,18 @@ export function createServer() {
         },
         {
             name: 'noteplan_paragraphs',
-            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)',
+            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 note ref via id/filename/title/date + lineIndex/line or taskQuery to find by text)\n- update: Update task content/status (requires note ref via id/filename/title/date + lineIndex or line)',
             inputSchema: {
                 type: 'object',
                 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',
-                        description: 'Note ID — used by search',
+                        description: 'Note ID — used by get, search, complete, update',
                     },
                     filename: {
                         type: 'string',
@@ -1220,11 +1289,11 @@ export function createServer() {
                     },
                     title: {
                         type: 'string',
-                        description: 'Note title — used by search',
+                        description: 'Note title — used by get, search, complete, update',
                     },
                     date: {
                         type: 'string',
-                        description: 'Calendar date — used by search',
+                        description: 'Calendar date (e.g. today, YYYY-MM-DD) — used by get, search, complete, update',
                     },
                     space: {
                         type: 'string',
@@ -1289,6 +1358,10 @@ export function createServer() {
                         type: 'number',
                         description: 'Task line number (1-based) — used by complete, update',
                     },
+                    taskQuery: {
+                        type: 'string',
+                        description: 'Find task by content text instead of line number (completes first matching open task) — used by complete',
+                    },
                     priority: {
                         type: 'number',
                         description: 'Priority 1-3 — used by add',
@@ -1354,8 +1427,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 +1530,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 +1615,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 +1717,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 +1764,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 +1853,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',
@@ -1861,14 +1934,14 @@ export function createServer() {
     // 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.',
+        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',
         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',
+                    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 +1997,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 +2088,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 +2124,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 +2157,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 +2184,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 +2223,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);
         }
-        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 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);
+        }
+        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 +2403,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 +2514,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 +2830,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 +2899,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,
@@ -2690,7 +2932,7 @@ export function createServer() {
 }
 // Start the server with stdio transport
 export async function startServer() {
-    console.error(`[noteplan-mcp] Starting v${getMcpServerVersion()} (Node ${process.version}, ${process.platform} ${process.arch})`);
+    console.error(`[noteplan-mcp] Starting v${getMcpServerVersion()} (Node ${process.version}, ${process.platform} ${process.arch}, pid ${process.pid})`);
     await initSqlite();
     const server = createServer();
     const transport = new StdioServerTransport();