bear-notes-mcp 2.1.0-rc.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Serhii Vasylenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# Bear Notes MCP Server
+
+Search, read, and update your Bear Notes
+
+Want to use this Bear Notes MCP server with Claude Code, Cursor, Codex, or other AI assistants? You can run it as a standalone MCP server.
+
+**Read more about the project here -- [claude-desktop-extension-bear-notes](https://github.com/vasylenko/claude-desktop-extension-bear-notes)**
+
+## Tools
+
+- **`bear-search-notes`** - Find notes by text content or tags, returns list with IDs for further actions
+- **`bear-open-note`** - Read full content of a specific note including text, formatting, and metadata
+- **`bear-create-note`** - Create new notes with optional title, content, and tags
+- **`bear-add-text-append`** - Add text to the end of existing notes or specific sections
+- **`bear-add-text-prepend`** - Insert text at the beginning of existing notes or sections
+- **`bear-add-file`** - Attach files (images, PDFs, spreadsheets, etc.) to existing notes
+
+**Requirements**: Node.js 22.13.0+
+
+## Quick Start - Claude Code (One Command)
+
+**For Node.js 22.13.0+ / 23.4.0+ / 24.x+ / 25.x+ (recommended):**
+```bash
+claude mcp add bear-notes --transport stdio -- npx -y bear-notes-mcp@latest
+```
+
+**For Node.js 22.5.0-22.12.x or 23.0.0-23.3.x (older versions):**
+```bash
+claude mcp add bear-notes --transport stdio --env NODE_OPTIONS="--experimental-sqlite" -- npx -y bear-notes-mcp@latest
+```
+
+That's it! The server will be downloaded from npm and configured automatically.
+
+## Quick Start - Other AI Assistants
+
+**Check your Node.js version:** `node --version`
+
+**For Node.js 22.13.0+ / 23.4.0+ / 24.x+ / 25.x+ (recommended):**
+```json
+{
+  "mcpServers": {
+    "bear-notes": {
+      "command": "npx",
+      "args": ["-y", "bear-notes-mcp@latest"]
+    }
+  }
+}
+```
+
+**For Node.js 22.5.0-22.12.x or 23.0.0-23.3.x (older versions):**
+```json
+{
+  "mcpServers": {
+    "bear-notes": {
+      "command": "npx",
+      "args": ["-y", "bear-notes-mcp@latest"],
+      "env": {
+        "NODE_OPTIONS": "--experimental-sqlite"
+      }
+    }
+  }
+}
+```
+
+## Advanced: Local Development Build
+
+**Step 1: Clone and build**
+```bash
+git clone https://github.com/vasylenko/claude-desktop-extension-bear-notes.git
+cd claude-desktop-extension-bear-notes
+npm install
+npm run build
+```
+
+**Step 2: Configure with local path**
+
+For Claude Code (Node.js 22.13.0+):
+```bash
+claude mcp add bear-notes --transport stdio -- node /absolute/path/to/dist/main.js
+```
+
+For Claude Code (Node.js 22.5.0-22.12.x):
+```bash
+claude mcp add bear-notes --transport stdio -- node --experimental-sqlite /absolute/path/to/dist/main.js
+```
+
+For other AI assistants (Node.js 22.13.0+):
+```json
+{
+  "mcpServers": {
+    "bear-notes": {
+      "command": "node",
+      "args": ["/absolute/path/to/dist/main.js"]
+    }
+  }
+}
+```
+
+For other AI assistants (Node.js 22.5.0-22.12.x):
+```json
+{
+  "mcpServers": {
+    "bear-notes": {
+      "command": "node",
+      "args": ["--experimental-sqlite", "/absolute/path/to/dist/main.js"]
+    }
+  }
+}
+```

package/dist/bear-urls.js

@@ -0,0 +1,87 @@
+import { spawn } from 'node:child_process';
+import { BEAR_URL_SCHEME } from './config.js';
+import { logAndThrow, logger } from './utils.js';
+/**
+ * Builds a Bear x-callback-url for various actions with proper parameter encoding.
+ * Includes required UX parameters for optimal user experience.
+ *
+ * @param action - Bear API action (e.g., 'create', 'add-text')
+ * @param params - Parameters for the specific action
+ * @returns Properly encoded x-callback-url string
+ */
+export function buildBearUrl(action, params = {}) {
+    logger.debug(`Building Bear URL for action: ${action}`);
+    if (!action || typeof action !== 'string' || !action.trim()) {
+        logAndThrow('Bear URL error: Action parameter is required and must be a non-empty string');
+    }
+    const baseUrl = `${BEAR_URL_SCHEME}${action.trim()}`;
+    const urlParams = new URLSearchParams();
+    // Add provided parameters with proper encoding
+    const stringParams = ['title', 'text', 'tags', 'id', 'header', 'file', 'filename'];
+    for (const key of stringParams) {
+        const value = params[key];
+        if (value !== undefined && value.trim()) {
+            urlParams.set(key, value.trim());
+        }
+    }
+    if (params.mode !== undefined) {
+        urlParams.set('mode', params.mode);
+    }
+    // UX params with defaults
+    urlParams.set('open_note', params.open_note ?? 'yes');
+    urlParams.set('new_window', params.new_window ?? 'no');
+    urlParams.set('show_window', params.show_window ?? 'yes');
+    // Add required Bear API parameters for add-text action
+    if (action === 'add-text') {
+        urlParams.set('new_line', 'yes'); // Ensures text appears on new line
+    }
+    // Convert URLSearchParams to proper URL encoding (Bear expects %20 not +)
+    const queryString = urlParams.toString().replace(/\+/g, '%20');
+    const finalUrl = `${baseUrl}?${queryString}`;
+    logger.debug(`Built Bear URL: ${finalUrl}`);
+    return finalUrl;
+}
+/**
+ * Executes a Bear x-callback-url using macOS subprocess execution.
+ * Platform-specific function that requires macOS with Bear Notes installed.
+ *
+ * @param url - The x-callback-url to execute
+ * @returns Promise that resolves when the command completes successfully
+ * @throws Error if platform is not macOS or subprocess execution fails
+ */
+export function executeBearXCallbackApi(url) {
+    logger.debug('Executing Bear x-callback-url');
+    if (!url || typeof url !== 'string' || !url.trim()) {
+        logAndThrow('Bear URL error: URL parameter is required and must be a non-empty string');
+    }
+    return new Promise((resolve, reject) => {
+        logger.debug('Launching Bear Notes via x-callback-url');
+        const child = spawn('open', ['-g', url.trim()], {
+            stdio: 'pipe',
+            detached: false,
+        });
+        let errorOutput = '';
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                errorOutput += data.toString();
+            });
+        }
+        child.on('close', (code) => {
+            if (code === 0) {
+                logger.debug('Bear x-callback-url executed successfully');
+                resolve();
+            }
+            else {
+                const errorMessage = `Bear URL error: Failed to execute x-callback-url (exit code: ${code})`;
+                const fullError = errorOutput ? `${errorMessage}. Error: ${errorOutput}` : errorMessage;
+                logger.error(fullError);
+                reject(new Error(fullError));
+            }
+        });
+        child.on('error', (error) => {
+            const errorMessage = `Bear URL error: Failed to spawn subprocess: ${error.message}`;
+            logger.error(errorMessage);
+            reject(new Error(errorMessage));
+        });
+    });
+}

package/dist/config.js

@@ -0,0 +1,11 @@
+export const APP_VERSION = '2.1.0';
+export const BEAR_URL_SCHEME = 'bear://x-callback-url/';
+export const CORE_DATA_EPOCH_OFFSET = 978307200; // 2001-01-01 to Unix epoch
+export const DEFAULT_SEARCH_LIMIT = 50;
+export const BEAR_DATABASE_PATH = 'Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite';
+export const ERROR_MESSAGES = {
+    BEAR_DATABASE_NOT_FOUND: 'Bear database not found. Please ensure Bear Notes is installed and has been opened at least once.',
+    MISSING_SEARCH_PARAM: 'Please provide either a search term or a tag to search for notes.',
+    MISSING_NOTE_ID: 'Please provide a note identifier. Use bear-search-notes first to find the note ID.',
+    MISSING_TEXT_PARAM: 'Text input parameter is required and must be a non-empty string',
+};

package/dist/database.js

@@ -0,0 +1,40 @@
+import { DatabaseSync } from 'node:sqlite';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { BEAR_DATABASE_PATH, ERROR_MESSAGES } from './config.js';
+import { logAndThrow, logger } from './utils.js';
+function getBearDatabasePath() {
+    // Environment override for testing
+    const envPath = process.env.BEAR_DB_PATH;
+    if (envPath) {
+        logger.debug(`Using environment override database path: ${envPath}`);
+        return envPath;
+    }
+    const defaultPath = join(homedir(), BEAR_DATABASE_PATH);
+    if (!existsSync(defaultPath)) {
+        logger.error(`Bear database not found at: ${defaultPath}`);
+        logAndThrow(`Database error: ${ERROR_MESSAGES.BEAR_DATABASE_NOT_FOUND}`);
+    }
+    logger.debug(`Using default Bear database path: ${defaultPath}`);
+    return defaultPath;
+}
+/**
+ * Opens a read-only connection to Bear's SQLite database.
+ *
+ * @returns DatabaseSync instance for querying Bear notes
+ * @throws Error if Bear database is not found or cannot be opened
+ */
+export function openBearDatabase() {
+    const databasePath = getBearDatabasePath();
+    logger.info(`Opening Bear database at: ${databasePath}`);
+    try {
+        const db = new DatabaseSync(databasePath);
+        logger.debug('Bear database opened successfully');
+        return db;
+    }
+    catch (error) {
+        logger.error(`Failed to open Bear database: ${error}`);
+        logAndThrow(`Database error: Failed to open Bear database: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

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 [];
+}

package/dist/tags.js

@@ -0,0 +1,170 @@
+import { convertCoreDataTimestamp, logAndThrow, logger } from './utils.js';
+import { openBearDatabase } from './database.js';
+/**
+ * Decodes and normalizes Bear tag names.
+ * - Replaces '+' with spaces (Bear's URL encoding)
+ * - Converts to lowercase (matches Bear UI behavior)
+ * - Trims whitespace
+ */
+function decodeTagName(encodedName) {
+    return encodedName.replace(/\+/g, ' ').trim().toLowerCase();
+}
+/**
+ * Extracts the display name (leaf) from a full tag path.
+ * For "career/content/blog" returns "blog", for "career" returns "career".
+ */
+function getTagDisplayName(fullPath) {
+    const parts = fullPath.split('/');
+    return parts[parts.length - 1];
+}
+/**
+ * Builds a hierarchical tree from a flat list of tags.
+ * Tags with paths like "career/content" become children of "career".
+ * Tags with 0 notes are excluded (matches Bear UI behavior).
+ */
+function buildTagHierarchy(flatTags) {
+    // Filter out tags with no notes (hidden in Bear UI)
+    const activeTags = flatTags.filter((t) => t.noteCount > 0);
+    const tagMap = new Map();
+    // Two-pass approach: first create nodes, then link parent-child relationships
+    for (const tag of activeTags) {
+        tagMap.set(tag.name, {
+            name: tag.name,
+            displayName: tag.displayName,
+            noteCount: tag.noteCount,
+            children: [],
+        });
+    }
+    const roots = [];
+    // Build parent-child relationships
+    for (const tag of activeTags) {
+        const tagNode = tagMap.get(tag.name);
+        if (tag.isRoot) {
+            roots.push(tagNode);
+        }
+        else {
+            // Subtags use path notation (e.g., "career/content"), so extract parent path
+            const lastSlash = tag.name.lastIndexOf('/');
+            if (lastSlash > 0) {
+                const parentName = tag.name.substring(0, lastSlash);
+                const parent = tagMap.get(parentName);
+                if (parent) {
+                    parent.children.push(tagNode);
+                }
+                else {
+                    // Orphan subtag - parent has 0 notes or doesn't exist, treat as root
+                    roots.push(tagNode);
+                }
+            }
+        }
+    }
+    // Sort children alphabetically at each level
+    const sortChildren = (tags) => {
+        tags.sort((a, b) => a.displayName.localeCompare(b.displayName));
+        for (const tag of tags) {
+            sortChildren(tag.children);
+        }
+    };
+    sortChildren(roots);
+    return roots;
+}
+/**
+ * Retrieves all tags from Bear database as a hierarchical tree.
+ * Each tag includes note count and nested children.
+ *
+ * @returns Object with tags array (tree structure) and total count
+ */
+export function listTags() {
+    logger.info('listTags called');
+    const db = openBearDatabase();
+    try {
+        const query = `
+      SELECT t.ZTITLE as name,
+             t.ZISROOT as isRoot,
+             COUNT(nt.Z_5NOTES) as noteCount
+      FROM ZSFNOTETAG t
+      LEFT JOIN Z_5TAGS nt ON nt.Z_13TAGS = t.Z_PK
+      GROUP BY t.Z_PK
+      ORDER BY t.ZTITLE
+    `;
+        const stmt = db.prepare(query);
+        const rows = stmt.all();
+        if (!rows || rows.length === 0) {
+            logger.info('No tags found in database');
+            return { tags: [], totalCount: 0 };
+        }
+        // Transform rows: decode names and extract display names
+        const flatTags = rows.map((row) => {
+            const decodedName = decodeTagName(row.name);
+            return {
+                name: decodedName,
+                displayName: getTagDisplayName(decodedName),
+                noteCount: row.noteCount,
+                isRoot: row.isRoot === 1,
+            };
+        });
+        const hierarchy = buildTagHierarchy(flatTags);
+        logger.info(`Retrieved ${rows.length} tags, ${hierarchy.length} root tags`);
+        return { tags: hierarchy, totalCount: rows.length };
+    }
+    catch (error) {
+        logAndThrow(`Database error: Failed to retrieve tags: ${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 { tags: [], totalCount: 0 };
+}
+/**
+ * Finds notes that have no tags assigned.
+ *
+ * @param limit - Maximum number of results (default: 50)
+ * @returns Array of untagged notes
+ */
+export function findUntaggedNotes(limit = 50) {
+    logger.info(`findUntaggedNotes called with limit: ${limit}`);
+    const db = openBearDatabase();
+    try {
+        const query = `
+      SELECT ZTITLE as title,
+             ZUNIQUEIDENTIFIER as identifier,
+             ZCREATIONDATE as creationDate,
+             ZMODIFICATIONDATE as modificationDate
+      FROM ZSFNOTE
+      WHERE ZARCHIVED = 0 AND ZTRASHED = 0 AND ZENCRYPTED = 0
+        AND Z_PK NOT IN (SELECT Z_5NOTES FROM Z_5TAGS)
+      ORDER BY ZMODIFICATIONDATE DESC
+      LIMIT ?
+    `;
+        const stmt = db.prepare(query);
+        const rows = stmt.all(limit);
+        const notes = rows.map((row) => ({
+            title: row.title || 'Untitled',
+            identifier: row.identifier,
+            creation_date: convertCoreDataTimestamp(row.creationDate),
+            modification_date: convertCoreDataTimestamp(row.modificationDate),
+            pin: 'no',
+        }));
+        logger.info(`Found ${notes.length} untagged notes`);
+        return notes;
+    }
+    catch (error) {
+        logAndThrow(`Database error: Failed to find untagged notes: ${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 [];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -0,0 +1,184 @@
+import createDebug from 'debug';
+import { CORE_DATA_EPOCH_OFFSET, ERROR_MESSAGES } from './config.js';
+import { getNoteContent } from './notes.js';
+import { buildBearUrl, executeBearXCallbackApi } from './bear-urls.js';
+export const logger = {
+    debug: createDebug('bear-notes-mcp:debug'),
+    info: createDebug('bear-notes-mcp:info'),
+    error: createDebug('bear-notes-mcp:error'),
+};
+// Convert UI_DEBUG_TOGGLE boolean set from UI to DEBUG string for debug package
+// MCPB has no way to make this in one step with manifest.json
+if (process.env.UI_DEBUG_TOGGLE === 'true') {
+    process.env.DEBUG = 'bear-notes-mcp:*';
+    logger.debug.enabled = true;
+}
+// Always enable error and info logs
+logger.error.enabled = true;
+logger.info.enabled = true;
+/**
+ * Logs an error message and throws an Error to halt execution.
+ * Centralizes error handling to ensure consistent logging before failures.
+ *
+ * @param message - The error message to log and throw
+ * @throws Always throws Error with the provided message
+ */
+export function logAndThrow(message) {
+    logger.error(message);
+    throw new Error(message);
+}
+/**
+ * Cleans base64 string by removing whitespace/newlines added by base64 command.
+ * URLSearchParams in buildBearUrl will handle URL encoding of special characters.
+ *
+ * @param base64String - Raw base64 string (may contain whitespace/newlines)
+ * @returns Cleaned base64 string without whitespace
+ */
+export function cleanBase64(base64String) {
+    // Remove all whitespace/newlines from base64 (base64 command adds line breaks)
+    return base64String.trim().replace(/\s+/g, '');
+}
+/**
+ * Converts Bear's Core Data timestamp to ISO string format.
+ * Bear stores timestamps in seconds since Core Data epoch (2001-01-01).
+ *
+ * @param coreDataTimestamp - Timestamp in seconds since Core Data epoch
+ * @returns ISO string representation of the timestamp
+ */
+export function convertCoreDataTimestamp(coreDataTimestamp) {
+    const unixTimestamp = coreDataTimestamp + CORE_DATA_EPOCH_OFFSET;
+    return new Date(unixTimestamp * 1000).toISOString();
+}
+/**
+ * Converts a JavaScript Date object to Bear's Core Data timestamp format.
+ * Core Data timestamps are in seconds since 2001-01-01 00:00:00 UTC.
+ *
+ * @param date - JavaScript Date object
+ * @returns Core Data timestamp in seconds
+ */
+export function convertDateToCoreDataTimestamp(date) {
+    const unixTimestamp = Math.floor(date.getTime() / 1000);
+    return unixTimestamp - CORE_DATA_EPOCH_OFFSET;
+}
+/**
+ * Parses a date string and returns a JavaScript Date object.
+ * Supports relative dates ("today", "yesterday", "last week", "last month") and ISO date strings.
+ *
+ * @param dateString - Date string to parse (e.g., "today", "2024-01-15", "last week")
+ * @returns Parsed Date object
+ * @throws Error if the date string is invalid
+ */
+export function parseDateString(dateString) {
+    const lowerDateString = dateString.trim().toLowerCase();
+    const now = new Date();
+    // Handle relative dates to provide user-friendly natural language date input
+    switch (lowerDateString) {
+        case 'today': {
+            const today = new Date(now);
+            today.setHours(0, 0, 0, 0);
+            return today;
+        }
+        case 'yesterday': {
+            const yesterday = new Date(now);
+            yesterday.setDate(yesterday.getDate() - 1);
+            yesterday.setHours(0, 0, 0, 0);
+            return yesterday;
+        }
+        case 'last week':
+        case 'week ago': {
+            const lastWeek = new Date(now);
+            lastWeek.setDate(lastWeek.getDate() - 7);
+            lastWeek.setHours(0, 0, 0, 0);
+            return lastWeek;
+        }
+        case 'last month':
+        case 'month ago':
+        case 'start of last month': {
+            // Calculate the first day of last month; month arithmetic handles year transitions correctly via JavaScript Date constructor
+            const lastMonth = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+            lastMonth.setHours(0, 0, 0, 0);
+            return lastMonth;
+        }
+        case 'end of last month': {
+            // Calculate the last day of last month; day 0 of current month equals last day of previous month
+            const endOfLastMonth = new Date(now.getFullYear(), now.getMonth(), 0);
+            endOfLastMonth.setHours(23, 59, 59, 999);
+            return endOfLastMonth;
+        }
+        default: {
+            // Try parsing as ISO date or other standard formats as fallback for user-provided explicit dates
+            const parsed = new Date(dateString);
+            if (isNaN(parsed.getTime())) {
+                logAndThrow(`Invalid date format: "${dateString}". Use ISO format (YYYY-MM-DD) or relative dates (today, yesterday, last week, last month, start of last month, end of last month).`);
+            }
+            return parsed;
+        }
+    }
+}
+/**
+ * Creates a standardized MCP tool response with consistent formatting.
+ * Centralizes response structure to follow DRY principles.
+ *
+ * @param text - The response text content
+ * @returns Formatted CallToolResult for MCP tools
+ */
+export function createToolResponse(text) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text,
+                annotations: { audience: ['user', 'assistant'] },
+            },
+        ],
+    };
+}
+/**
+ * Shared handler for adding text to Bear notes (append or prepend).
+ * Consolidates common validation, execution, and response logic.
+ *
+ * @param mode - Whether to append or prepend text
+ * @param params - Note ID, text content, and optional header
+ * @returns Formatted response indicating success or failure
+ */
+export async function handleAddText(mode, { id, text, header }) {
+    const action = mode === 'append' ? 'appended' : 'prepended';
+    logger.info(`bear-add-text-${mode} called with id: ${id}, text length: ${text.length}, header: ${header || 'none'}`);
+    if (!id || !id.trim()) {
+        throw new Error(ERROR_MESSAGES.MISSING_NOTE_ID);
+    }
+    if (!text || !text.trim()) {
+        throw new Error(ERROR_MESSAGES.MISSING_TEXT_PARAM);
+    }
+    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.`);
+        }
+        // Strip markdown header syntax from header parameter for Bear API
+        const cleanHeader = header?.trim().replace(/^#+\s*/, '');
+        const url = buildBearUrl('add-text', {
+            id: id.trim(),
+            text: text.trim(),
+            header: cleanHeader,
+            mode,
+        });
+        logger.debug(`Executing Bear URL: ${url}`);
+        await executeBearXCallbackApi(url);
+        const responseLines = [`Text ${action} to note "${existingNote.title}" successfully!`, ''];
+        responseLines.push(`Text: ${text.trim().length} characters`);
+        if (header?.trim()) {
+            responseLines.push(`Section: ${header.trim()}`);
+        }
+        responseLines.push(`Note ID: ${id.trim()}`);
+        return createToolResponse(`${responseLines.join('\n')}
+
+The text has been added to your Bear note.`);
+    }
+    catch (error) {
+        logger.error(`bear-add-text-${mode} failed: ${error}`);
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "bear-notes-mcp",
+  "version": "2.1.0-rc.1",
+  "description": "Bear Notes MCP server with TypeScript and native SQLite",
+  "type": "module",
+  "main": "dist/main.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/main.ts --debug",
+    "start": "node --experimental-sqlite dist/main.js",
+    "lint": "eslint src --fix",
+    "lint:check": "eslint src",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src",
+    "check": "npm run lint:check && npm run format:check",
+    "fix": "npm run lint && npm run format",
+    "prepublishOnly": "npm run build && mv docs/NPM.md README.md"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "debug": "^4.4.3",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^24.10.4",
+    "@typescript-eslint/eslint-plugin": "^8.46.3",
+    "@typescript-eslint/parser": "^8.46.3",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.7.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "overrides": {
+    "body-parser": "2.2.1"
+  },
+  "keywords": [
+    "bear app",
+    "bear notes",
+    "markdown notes",
+    "notes management",
+    "productivity",
+    "typescript",
+    "mcp"
+  ],
+  "author": {
+    "name": "Serhii Vasylenko",
+    "email": "serhii@vasylenko.info",
+    "url": "https://devdosvid.blog"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vasylenko/claude-desktop-extension-bear-notes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vasylenko/claude-desktop-extension-bear-notes/issues"
+  },
+  "homepage": "https://github.com/vasylenko/claude-desktop-extension-bear-notes#readme",
+  "bin": {
+    "bear-notes-mcp": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}