bear-notes-mcp-xq7k 2.0.1

package/dist/main.js

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { APP_VERSION, ERROR_MESSAGES } from './config.js';
+import { cleanBase64, createToolResponse, handleAddText, logger } from './utils.js';
+import { getNoteContent, searchNotes } from './notes.js';
+import { findUntaggedNotes, listTags } from './tags.js';
+import { buildBearUrl, executeBearXCallbackApi } from './bear-urls.js';
+const server = new McpServer({
+    name: 'bear-notes-mcp',
+    version: APP_VERSION,
+});
+server.registerTool('bear-open-note', {
+    title: 'Open Bear Note',
+    description: 'Read the full text content of a Bear note from your library. Always includes text extracted from attached images and PDFs (aka OCR search) with clear labeling.',
+    inputSchema: {
+        identifier: z.string().describe('Exact note identifier (ID) obtained from bear-search-notes'),
+    },
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ identifier }) => {
+    logger.info(`bear-open-note called with identifier: ${identifier}, includeFiles: always`);
+    if (!identifier || !identifier.trim()) {
+        throw new Error(ERROR_MESSAGES.MISSING_NOTE_ID);
+    }
+    try {
+        const noteWithContent = getNoteContent(identifier.trim());
+        if (!noteWithContent) {
+            return createToolResponse(`Note with ID '${identifier}' not found. The note may have been deleted, archived, or the ID may be incorrect.
+
+Use bear-search-notes to find the correct note identifier.`);
+        }
+        const noteInfo = [
+            `**${noteWithContent.title}**`,
+            `Modified: ${noteWithContent.modification_date}`,
+            `ID: ${noteWithContent.identifier}`,
+        ];
+        const noteText = noteWithContent.text || '*This note appears to be empty.*';
+        return createToolResponse(`${noteInfo.join('\n')}
+
+---
+
+${noteText}`);
+    }
+    catch (error) {
+        logger.error(`bear-open-note failed: ${error}`);
+        throw error;
+    }
+});
+server.registerTool('bear-create-note', {
+    title: 'Create New Note',
+    description: 'Create a new note in your Bear library with optional title, content, and tags. The note will be immediately available in Bear app.',
+    inputSchema: {
+        title: z
+            .string()
+            .optional()
+            .describe('Note title, e.g., "Meeting Notes" or "Research Ideas"'),
+        text: z.string().optional().describe('Note content in markdown format'),
+        tags: z.string().optional().describe('Tags separated by commas, e.g., "work,project,urgent"'),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async ({ title, text, tags }) => {
+    logger.debug(`bear-create-note called with title: ${title ? '"' + title + '"' : 'none'}, text length: ${text ? text.length : 0}, tags: ${tags || 'none'}`);
+    try {
+        const url = buildBearUrl('create', { title, text, tags });
+        await executeBearXCallbackApi(url);
+        const responseLines = ['Bear note created successfully!', ''];
+        if (title?.trim()) {
+            responseLines.push(`Title: "${title.trim()}"`);
+        }
+        if (text?.trim()) {
+            responseLines.push(`Content: ${text.trim().length} characters`);
+        }
+        if (tags?.trim()) {
+            responseLines.push(`Tags: ${tags.trim()}`);
+        }
+        const hasContent = title?.trim() || text?.trim() || tags?.trim();
+        const finalMessage = hasContent ? responseLines.join('\n') : 'Empty note created';
+        return createToolResponse(`${finalMessage}
+
+The note has been added to your Bear Notes library.`);
+    }
+    catch (error) {
+        logger.error(`bear-create-note failed: ${error}`);
+        throw error;
+    }
+});
+server.registerTool('bear-search-notes', {
+    title: 'Find Bear Notes',
+    description: 'Find notes in your Bear library by searching text content, filtering by tags, or date ranges. Always searches within attached images and PDF files via OCR. Returns a list with titles and IDs - use "Open Bear Note" to read full content.',
+    inputSchema: {
+        term: z.string().optional().describe('Text to search for in note titles and content'),
+        tag: z.string().optional().describe('Tag to filter notes by (without # symbol)'),
+        limit: z.number().optional().describe('Maximum number of results to return (default: 50)'),
+        createdAfter: z
+            .string()
+            .optional()
+            .describe('Filter notes created on or after this date. Supports: relative dates ("today", "yesterday", "last week", "start of last month"), ISO format (YYYY-MM-DD). Use "start of last month" for the beginning of the previous month.'),
+        createdBefore: z
+            .string()
+            .optional()
+            .describe('Filter notes created on or before this date. Supports: relative dates ("today", "yesterday", "last week", "end of last month"), ISO format (YYYY-MM-DD). Use "end of last month" for the end of the previous month.'),
+        modifiedAfter: z
+            .string()
+            .optional()
+            .describe('Filter notes modified on or after this date. Supports: relative dates ("today", "yesterday", "last week", "start of last month"), ISO format (YYYY-MM-DD). Use "start of last month" for the beginning of the previous month.'),
+        modifiedBefore: z
+            .string()
+            .optional()
+            .describe('Filter notes modified on or before this date. Supports: relative dates ("today", "yesterday", "last week", "end of last month"), ISO format (YYYY-MM-DD). Use "end of last month" for the end of the previous month.'),
+    },
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ term, tag, limit, createdAfter, createdBefore, modifiedAfter, modifiedBefore, }) => {
+    logger.info(`bear-search-notes called with term: "${term || 'none'}", tag: "${tag || 'none'}", limit: ${limit || 'default'}, createdAfter: "${createdAfter || 'none'}", createdBefore: "${createdBefore || 'none'}", modifiedAfter: "${modifiedAfter || 'none'}", modifiedBefore: "${modifiedBefore || 'none'}", includeFiles: always`);
+    try {
+        const dateFilter = {
+            ...(createdAfter && { createdAfter }),
+            ...(createdBefore && { createdBefore }),
+            ...(modifiedAfter && { modifiedAfter }),
+            ...(modifiedBefore && { modifiedBefore }),
+        };
+        const notes = searchNotes(term, tag, limit, Object.keys(dateFilter).length > 0 ? dateFilter : undefined);
+        if (notes.length === 0) {
+            const searchCriteria = [];
+            if (term?.trim())
+                searchCriteria.push(`term "${term.trim()}"`);
+            if (tag?.trim())
+                searchCriteria.push(`tag "${tag.trim()}"`);
+            if (createdAfter)
+                searchCriteria.push(`created after "${createdAfter}"`);
+            if (createdBefore)
+                searchCriteria.push(`created before "${createdBefore}"`);
+            if (modifiedAfter)
+                searchCriteria.push(`modified after "${modifiedAfter}"`);
+            if (modifiedBefore)
+                searchCriteria.push(`modified before "${modifiedBefore}"`);
+            return createToolResponse(`No notes found matching ${searchCriteria.join(', ')}.
+
+Try different search criteria or check if notes exist in Bear Notes.`);
+        }
+        const resultLines = [`Found ${notes.length} note${notes.length === 1 ? '' : 's'}:`, ''];
+        notes.forEach((note, index) => {
+            const noteTitle = note.title || 'Untitled';
+            const modifiedDate = new Date(note.modification_date).toLocaleDateString();
+            const createdDate = new Date(note.creation_date).toLocaleDateString();
+            resultLines.push(`${index + 1}. **${noteTitle}**`);
+            resultLines.push(`   Created: ${createdDate}`);
+            resultLines.push(`   Modified: ${modifiedDate}`);
+            resultLines.push(`   ID: ${note.identifier}`);
+            resultLines.push('');
+        });
+        resultLines.push('Use bear-open-note with an ID to read the full content of any note.');
+        return createToolResponse(resultLines.join('\n'));
+    }
+    catch (error) {
+        logger.error(`bear-search-notes failed: ${error}`);
+        throw error;
+    }
+});
+server.registerTool('bear-add-text', {
+    title: 'Add Text to Note',
+    description: 'Add text to an existing Bear note at the beginning or end. Can target a specific section using header. Use bear-search-notes first to get the note ID.',
+    inputSchema: {
+        id: z.string().describe('Note identifier (ID) from bear-search-notes'),
+        text: z.string().describe('Text content to add to the note'),
+        header: z
+            .string()
+            .optional()
+            .describe('Optional section header to target (adds text within that section)'),
+        position: z
+            .enum(['beginning', 'end'])
+            .optional()
+            .describe("Where to insert: 'end' (default) for appending, logs, updates; 'beginning' for prepending, summaries, top of mind, etc."),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async ({ id, text, header, position }) => {
+    const mode = position === 'beginning' ? 'prepend' : 'append';
+    return handleAddText(mode, { id, text, header });
+});
+server.registerTool('bear-add-file', {
+    title: 'Add File to Note',
+    description: 'Attach a file to an existing Bear note. Encode the file to base64 using shell commands (e.g., base64 /path/to/file.xlsx) and provide the encoded content. Use bear-search-notes first to get the note ID.',
+    inputSchema: {
+        base64_content: z.string().describe('Base64-encoded file content'),
+        filename: z.string().describe('Filename with extension (e.g., budget.xlsx, report.pdf)'),
+        id: z
+            .string()
+            .optional()
+            .describe('Exact note identifier (ID) obtained from bear-search-notes'),
+        title: z.string().optional().describe('Note title if ID is not available'),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async ({ base64_content, filename, id, title }) => {
+    logger.info(`bear-add-file called with base64_content: ${base64_content ? 'provided' : 'none'}, filename: ${filename || 'none'}, id: ${id || 'none'}, title: ${title || 'none'}`);
+    if (!base64_content || !base64_content.trim()) {
+        throw new Error('base64_content is required');
+    }
+    if (!filename || !filename.trim()) {
+        throw new Error('filename is required');
+    }
+    if (!id && !title) {
+        throw new Error('Either note ID or title is required. Use bear-search-notes to find the note ID.');
+    }
+    try {
+        // base64 CLI adds line breaks that break URL encoding
+        const cleanedBase64 = cleanBase64(base64_content);
+        // Fail fast with helpful message rather than cryptic Bear error
+        if (id) {
+            const existingNote = getNoteContent(id.trim());
+            if (!existingNote) {
+                return createToolResponse(`Note with ID '${id}' not found. The note may have been deleted, archived, or the ID may be incorrect.
+
+Use bear-search-notes to find the correct note identifier.`);
+            }
+        }
+        const url = buildBearUrl('add-file', {
+            id: id?.trim(),
+            title: title?.trim(),
+            file: cleanedBase64,
+            filename: filename.trim(),
+            mode: 'append',
+        });
+        logger.debug(`Executing Bear add-file URL for: ${filename.trim()}`);
+        await executeBearXCallbackApi(url);
+        const noteIdentifier = id ? `Note ID: ${id.trim()}` : `Note title: "${title.trim()}"`;
+        return createToolResponse(`File "${filename.trim()}" added successfully!
+
+${noteIdentifier}
+
+The file has been attached to your Bear note.`);
+    }
+    catch (error) {
+        logger.error(`bear-add-file failed: ${error}`);
+        throw error;
+    }
+});
+/**
+ * Formats tag hierarchy as tree-style text output.
+ * Uses box-drawing characters for visual tree structure.
+ */
+function formatTagTree(tags, isLast = []) {
+    const lines = [];
+    for (let i = 0; i < tags.length; i++) {
+        const tag = tags[i];
+        const isLastItem = i === tags.length - 1;
+        // Build the prefix using box-drawing characters
+        let linePrefix = '';
+        for (let j = 0; j < isLast.length; j++) {
+            linePrefix += isLast[j] ? '    ' : '│   ';
+        }
+        linePrefix += isLastItem ? '└── ' : '├── ';
+        lines.push(`${linePrefix}${tag.name} (${tag.noteCount})`);
+        if (tag.children.length > 0) {
+            lines.push(...formatTagTree(tag.children, [...isLast, isLastItem]));
+        }
+    }
+    return lines;
+}
+server.registerTool('bear-list-tags', {
+    title: 'List Bear Tags',
+    description: 'List all tags in your Bear library as a hierarchical tree. Shows tag names with note counts. Useful for understanding your tag structure and finding tags to apply to untagged notes.',
+    inputSchema: {},
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async () => {
+    logger.info('bear-list-tags called');
+    try {
+        const { tags, totalCount } = listTags();
+        if (totalCount === 0) {
+            return createToolResponse('No tags found in your Bear library.');
+        }
+        // Format root tags with their children as trees
+        const lines = [];
+        for (const rootTag of tags) {
+            lines.push(`${rootTag.name} (${rootTag.noteCount})`);
+            if (rootTag.children.length > 0) {
+                lines.push(...formatTagTree(rootTag.children));
+            }
+        }
+        const header = `Found ${totalCount} tag${totalCount === 1 ? '' : 's'}:\n`;
+        return createToolResponse(header + '\n' + lines.join('\n'));
+    }
+    catch (error) {
+        logger.error(`bear-list-tags failed: ${error}`);
+        throw error;
+    }
+});
+server.registerTool('bear-find-untagged-notes', {
+    title: 'Find Untagged Notes',
+    description: 'Find notes in your Bear library that have no tags. Useful for organizing and categorizing notes.',
+    inputSchema: {
+        limit: z.number().optional().describe('Maximum number of results (default: 50)'),
+    },
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ limit }) => {
+    logger.info(`bear-find-untagged-notes called with limit: ${limit || 'default'}`);
+    try {
+        const notes = findUntaggedNotes(limit);
+        if (notes.length === 0) {
+            return createToolResponse('No untagged notes found. All your notes have tags!');
+        }
+        const lines = [`Found ${notes.length} untagged note${notes.length === 1 ? '' : 's'}:`, ''];
+        notes.forEach((note, index) => {
+            const modifiedDate = new Date(note.modification_date).toLocaleDateString();
+            lines.push(`${index + 1}. **${note.title}**`);
+            lines.push(`   Modified: ${modifiedDate}`);
+            lines.push(`   ID: ${note.identifier}`);
+            lines.push('');
+        });
+        lines.push('You can also use bear-list-tags to see available tags.');
+        return createToolResponse(lines.join('\n'));
+    }
+    catch (error) {
+        logger.error(`bear-find-untagged-notes failed: ${error}`);
+        throw error;
+    }
+});
+server.registerTool('bear-add-tag', {
+    title: 'Add Tags to Note',
+    description: 'Add one or more tags to an existing Bear note. Tags are added at the beginning of the note. Use bear-list-tags to see available tags.',
+    inputSchema: {
+        id: z
+            .string()
+            .describe('Note identifier (ID) from bear-search-notes or bear-find-untagged-notes'),
+        tags: z
+            .array(z.string())
+            .describe('Tag names without # symbol (e.g., ["career", "career/meetings"])'),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async ({ id, tags }) => {
+    logger.info(`bear-add-tag called with id: ${id}, tags: [${tags.join(', ')}]`);
+    if (!id || !id.trim()) {
+        throw new Error(ERROR_MESSAGES.MISSING_NOTE_ID);
+    }
+    if (!tags || tags.length === 0) {
+        throw new Error('At least one tag is required');
+    }
+    try {
+        const existingNote = getNoteContent(id.trim());
+        if (!existingNote) {
+            return createToolResponse(`Note with ID '${id}' not found. The note may have been deleted, archived, or the ID may be incorrect.
+
+Use bear-search-notes to find the correct note identifier.`);
+        }
+        const tagsString = tags.join(',');
+        const url = buildBearUrl('add-text', {
+            id: id.trim(),
+            tags: tagsString,
+            mode: 'prepend',
+            open_note: 'no',
+            show_window: 'no',
+            new_window: 'no',
+        });
+        await executeBearXCallbackApi(url);
+        const tagList = tags.map((t) => `#${t}`).join(', ');
+        return createToolResponse(`Tags added successfully!
+
+Note: "${existingNote.title}"
+Tags: ${tagList}
+
+The tags have been added to the beginning of the note.`);
+    }
+    catch (error) {
+        logger.error(`bear-add-tag failed: ${error}`);
+        throw error;
+    }
+});
+async function main() {
+    logger.info(`Bear Notes MCP Server initializing... Version: ${APP_VERSION}`);
+    logger.debug(`Debug logs enabled: ${logger.debug.enabled}`);
+    logger.debug(`Node.js version: ${process.version}`);
+    logger.debug(`App version: ${APP_VERSION}`);
+    // Handle process errors
+    process.on('uncaughtException', (error) => {
+        logger.error('Uncaught exception:', error);
+    });
+    process.on('unhandledRejection', (reason, promise) => {
+        logger.error('Unhandled rejection at:', promise, 'reason:', reason);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('Bear Notes MCP Server connected and ready');
+}
+main().catch((error) => {
+    logger.error('Server startup failed:', error);
+    process.exit(1);
+});

package/dist/notes.js

@@ -0,0 +1,224 @@
+import { DEFAULT_SEARCH_LIMIT } from './config.js';
+import { convertCoreDataTimestamp, convertDateToCoreDataTimestamp, logAndThrow, logger, parseDateString, } from './utils.js';
+import { openBearDatabase } from './database.js';
+function formatBearNote(row) {
+    const title = row.title || 'Untitled';
+    const identifier = row.identifier;
+    const modificationDate = row.modificationDate;
+    const creationDate = row.creationDate;
+    const pinned = row.pinned;
+    const text = row.text;
+    if (!identifier) {
+        logAndThrow('Database error: Note identifier is missing from database row');
+    }
+    if (typeof modificationDate !== 'number' || typeof creationDate !== 'number') {
+        logAndThrow('Database error: Note date fields are invalid in database row');
+    }
+    const modification_date = convertCoreDataTimestamp(modificationDate);
+    const creation_date = convertCoreDataTimestamp(creationDate);
+    // Bear stores pinned as integer; API expects string literal (only needed when pinned is queried)
+    const pin = pinned ? 'yes' : 'no';
+    return {
+        title,
+        identifier,
+        modification_date,
+        creation_date,
+        pin,
+        ...(text !== undefined && { text }),
+    };
+}
+/**
+ * Retrieves a Bear note with its full content from the database.
+ *
+ * @param identifier - The unique identifier of the Bear note
+ * @returns The note with content, or null if not found
+ * @throws Error if database access fails or identifier is invalid
+ * Note: Always includes OCR'd text from attached images and PDFs with clear labeling
+ */
+export function getNoteContent(identifier) {
+    logger.info(`getNoteContent called with identifier: ${identifier}, includeFiles: always`);
+    if (!identifier || typeof identifier !== 'string' || !identifier.trim()) {
+        logAndThrow('Database error: Invalid note identifier provided');
+    }
+    const db = openBearDatabase();
+    try {
+        logger.debug(`Fetching the note content from the database, note identifier: ${identifier}`);
+        // Query with file content - always includes OCR'd text from attached files with clear labeling
+        const query = `
+      SELECT note.ZTITLE as title,
+             note.ZUNIQUEIDENTIFIER as identifier,
+             note.ZCREATIONDATE as creationDate,
+             note.ZMODIFICATIONDATE as modificationDate,
+             note.ZPINNED as pinned,
+             note.ZTEXT as text,
+             f.ZFILENAME as filename,
+             f.ZSEARCHTEXT as fileContent
+      FROM ZSFNOTE note
+      LEFT JOIN ZSFNOTEFILE f ON f.ZNOTE = note.Z_PK
+      WHERE note.ZUNIQUEIDENTIFIER = ?
+        AND note.ZARCHIVED = 0
+        AND note.ZTRASHED = 0
+        AND note.ZENCRYPTED = 0
+    `;
+        const stmt = db.prepare(query);
+        const rows = stmt.all(identifier);
+        if (!rows || rows.length === 0) {
+            logger.info(`Note not found for identifier: ${identifier}`);
+            return null;
+        }
+        // Process multiple rows (note + files) into single note object
+        const firstRow = rows[0];
+        const formattedNote = formatBearNote(firstRow);
+        // Collect file content from all rows with clear source labeling
+        const fileContents = [];
+        for (const row of rows) {
+            const rowData = row;
+            const filename = rowData.filename;
+            const fileContent = rowData.fileContent;
+            if (filename && fileContent && fileContent.trim()) {
+                fileContents.push(`##${filename}\n\n${fileContent.trim()}`);
+            }
+        }
+        // Always append file content section, even if empty, to show structure
+        const originalText = formattedNote.text || '';
+        const filesSectionHeader = '\n\n---\n\n#Attached Files\n\n';
+        if (fileContents.length > 0) {
+            const fileSection = `${filesSectionHeader}${fileContents.join('\n\n---\n\n')}`;
+            formattedNote.text = originalText + fileSection;
+        }
+        else {
+            // Add a note that no files are attached for clarity
+            formattedNote.text = originalText + `${filesSectionHeader}*No files attached to this note.*`;
+        }
+        logger.info(`Retrieved note content with ${fileContents.length} attached files for: ${formattedNote.title}`);
+        return formattedNote;
+    }
+    catch (error) {
+        logger.error(`SQLite query failed: ${error}`);
+        logAndThrow(`Database error: Failed to retrieve note content: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        try {
+            db.close();
+            logger.debug('Database connection closed');
+        }
+        catch (closeError) {
+            logger.error(`Failed to close database connection: ${closeError}`);
+        }
+    }
+    return null;
+}
+/**
+ * Searches Bear notes by content or tags with optional filtering.
+ * Returns a list of notes without full content for performance.
+ *
+ * @param searchTerm - Text to search for in note titles and content (optional)
+ * @param tag - Tag to filter notes by (optional)
+ * @param limit - Maximum number of results to return (default from config)
+ * @param dateFilter - Date range filters for creation and modification dates (optional)
+ * @returns Array of matching notes without full text content
+ * @throws Error if database access fails or no search criteria provided
+ * Note: Always searches within text extracted from attached images and PDF files via OCR for comprehensive results
+ */
+export function searchNotes(searchTerm, tag, limit, dateFilter) {
+    logger.info(`searchNotes called with term: "${searchTerm || 'none'}", tag: "${tag || 'none'}", limit: ${limit || DEFAULT_SEARCH_LIMIT}, dateFilter: ${dateFilter ? JSON.stringify(dateFilter) : 'none'}, includeFiles: always`);
+    // Validate search parameters - at least one must be provided
+    const hasSearchTerm = searchTerm && typeof searchTerm === 'string' && searchTerm.trim();
+    const hasTag = tag && typeof tag === 'string' && tag.trim();
+    const hasDateFilter = dateFilter && Object.keys(dateFilter).length > 0;
+    if (!hasSearchTerm && !hasTag && !hasDateFilter) {
+        logAndThrow('Search error: Please provide a search term, tag, or date filter to search for notes');
+    }
+    const db = openBearDatabase();
+    const queryLimit = limit || DEFAULT_SEARCH_LIMIT;
+    try {
+        let query;
+        const queryParams = [];
+        // Query with file search - uses LEFT JOIN to include OCR'd content for comprehensive search
+        query = `
+      SELECT DISTINCT note.ZTITLE as title,
+             note.ZUNIQUEIDENTIFIER as identifier,
+             note.ZCREATIONDATE as creationDate,
+             note.ZMODIFICATIONDATE as modificationDate
+      FROM ZSFNOTE note
+      LEFT JOIN ZSFNOTEFILE f ON f.ZNOTE = note.Z_PK
+      WHERE note.ZARCHIVED = 0
+        AND note.ZTRASHED = 0
+        AND note.ZENCRYPTED = 0`;
+        // Add search term filtering
+        if (hasSearchTerm) {
+            const searchPattern = `%${searchTerm.trim()}%`;
+            // Search in note title, text, and file OCR content
+            query += ' AND (note.ZTITLE LIKE ? OR note.ZTEXT LIKE ? OR f.ZSEARCHTEXT LIKE ?)';
+            queryParams.push(searchPattern, searchPattern, searchPattern);
+        }
+        // Add tag filtering
+        if (hasTag) {
+            const tagPattern = `%#${tag.trim()}%`;
+            query += ' AND note.ZTEXT LIKE ?';
+            queryParams.push(tagPattern);
+        }
+        // Add date filtering
+        if (hasDateFilter && dateFilter) {
+            if (dateFilter.createdAfter) {
+                const afterDate = parseDateString(dateFilter.createdAfter);
+                // Set to start of day (00:00:00) to include notes from the entire specified day onwards
+                afterDate.setHours(0, 0, 0, 0);
+                const timestamp = convertDateToCoreDataTimestamp(afterDate);
+                query += ' AND note.ZCREATIONDATE >= ?';
+                queryParams.push(timestamp);
+            }
+            if (dateFilter.createdBefore) {
+                const beforeDate = parseDateString(dateFilter.createdBefore);
+                // Set to end of day (23:59:59.999) to include notes through the entire specified day
+                beforeDate.setHours(23, 59, 59, 999);
+                const timestamp = convertDateToCoreDataTimestamp(beforeDate);
+                query += ' AND note.ZCREATIONDATE <= ?';
+                queryParams.push(timestamp);
+            }
+            if (dateFilter.modifiedAfter) {
+                const afterDate = parseDateString(dateFilter.modifiedAfter);
+                // Set to start of day (00:00:00) to include notes from the entire specified day onwards
+                afterDate.setHours(0, 0, 0, 0);
+                const timestamp = convertDateToCoreDataTimestamp(afterDate);
+                query += ' AND note.ZMODIFICATIONDATE >= ?';
+                queryParams.push(timestamp);
+            }
+            if (dateFilter.modifiedBefore) {
+                const beforeDate = parseDateString(dateFilter.modifiedBefore);
+                // Set to end of day (23:59:59.999) to include notes through the entire specified day
+                beforeDate.setHours(23, 59, 59, 999);
+                const timestamp = convertDateToCoreDataTimestamp(beforeDate);
+                query += ' AND note.ZMODIFICATIONDATE <= ?';
+                queryParams.push(timestamp);
+            }
+        }
+        // Add ordering and limit
+        query += ' ORDER BY note.ZMODIFICATIONDATE DESC LIMIT ?';
+        queryParams.push(queryLimit);
+        logger.debug(`Executing search query with ${queryParams.length} parameters`);
+        // Use parameter binding to prevent SQL injection attacks
+        const stmt = db.prepare(query);
+        const rows = stmt.all(...queryParams);
+        if (!rows || rows.length === 0) {
+            logger.info('No notes found matching search criteria');
+            return [];
+        }
+        const notes = rows.map((row) => formatBearNote(row));
+        logger.info(`Found ${notes.length} notes matching search criteria`);
+        return notes;
+    }
+    catch (error) {
+        logAndThrow(`SQLite search query failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        try {
+            db.close();
+            logger.debug('Database connection closed');
+        }
+        catch (closeError) {
+            logger.error(`Failed to close database connection: ${closeError}`);
+        }
+    }
+    return [];
+}