bear-notes-mcp 2.5.0 → 2.7.0

package/README.md

@@ -19,7 +19,7 @@ Search, read, create, and update your Bear Notes from any AI assistant.
 - **`bear-open-note`** - Read the full text content of a Bear note including OCR'd text from attached images and PDFs
 - **`bear-create-note`** - Create a new note in your Bear library with optional title, content, and tags
 - **`bear-search-notes`** - Find notes by searching text content, filtering by tags, or date ranges. Includes OCR search in attachments
-- **`bear-add-text`** - Add text to an existing Bear note at the beginning or end, optionally targeting a specific section
+- **`bear-add-text`** - Insert text at the beginning or end of a Bear note, or within a specific section identified by its header
 - **`bear-replace-text`** - Replace content in an existing Bear note — either the full body or a specific section. Requires content replacement to be enabled in settings.
 - **`bear-add-file`** - Attach a file (image, PDF, Excel, etc.) to an existing Bear note using base64-encoded content
 - **`bear-list-tags`** - List all tags in your Bear library as a hierarchical tree with note counts

package/dist/config.js

@@ -1,4 +1,4 @@
-export const APP_VERSION = '2.5.0';
+export const APP_VERSION = '2.7.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;

package/dist/database.js

@@ -19,6 +19,19 @@ function getBearDatabasePath() {
     logger.debug(`Using default Bear database path: ${defaultPath}`);
     return defaultPath;
 }
+/**
+ * Closes a Bear database connection, logging but swallowing close errors.
+ * Centralizes the try/catch-close pattern used after every DB operation.
+ */
+export function closeBearDatabase(db) {
+    try {
+        db.close();
+        logger.debug('Database connection closed');
+    }
+    catch (closeError) {
+        logger.error(`Failed to close database connection: ${closeError}`);
+    }
+}
 /**
  * Opens a read-only connection to Bear's SQLite database.
  *

package/dist/main.js

@@ -5,12 +5,22 @@ import { z } from 'zod';
 import { APP_VERSION, ENABLE_CONTENT_REPLACEMENT, ENABLE_NEW_NOTE_CONVENTIONS } from './config.js';
 import { applyNoteConventions } from './note-conventions.js';
 import { cleanBase64, createToolResponse, handleNoteTextUpdate, logger } from './utils.js';
-import { getNoteContent, searchNotes } from './notes.js';
+import { awaitNoteCreation, 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,
+}, {
+    instructions: [
+        'This server integrates with Bear, a markdown note-taking app.',
+        'Each note has a unique ID, a title, a body, and optional tags.',
+        'Notes use markdown headings (##, ###, etc.) to define sections.',
+        'Use bear-search-notes to find note IDs before reading or modifying notes.',
+        'To modify note content: bear-add-text inserts text without touching existing content; bear-replace-text overwrites content.',
+        'When targeting a section by header, operations apply only to the direct content under that header — not nested sub-sections.',
+        'To modify sub-sections, make separate calls targeting each sub-header.',
+    ].join('\n'),
 });
 server.registerTool('bear-open-note', {
     title: 'Open Bear Note',
@@ -55,7 +65,7 @@ ${noteText}`);
 });
 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.',
+    description: 'Create a new note in your Bear library with optional title, content, and tags. Returns the note ID when a title is provided, enabling immediate follow-up operations. The note will be immediately available in Bear app.',
     inputSchema: {
         title: z
             .string()
@@ -88,16 +98,17 @@ server.registerTool('bear-create-note', {
             : { text, tags };
         const url = buildBearUrl('create', { title, text: createText, tags: createTags });
         await executeBearXCallbackApi(url);
+        const createdNoteId = title ? await awaitNoteCreation(title) : undefined;
         const responseLines = ['Bear note created successfully!', ''];
         if (title) {
             responseLines.push(`Title: "${title}"`);
         }
-        if (text) {
-            responseLines.push(`Content: ${text.length} characters`);
-        }
         if (tags) {
             responseLines.push(`Tags: ${tags}`);
         }
+        if (createdNoteId) {
+            responseLines.push(`Note ID: ${createdNoteId}`);
+        }
         const hasContent = title || text || tags;
         const finalMessage = hasContent ? responseLines.join('\n') : 'Empty note created';
         return createToolResponse(`${finalMessage}
@@ -201,7 +212,7 @@ Try different search criteria or check if notes exist in Bear Notes.`);
 });
 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.',
+    description: 'Insert text at the beginning or end of a Bear note, or within a specific section identified by its header. Use bear-search-notes first to get the note ID. To insert without replacing existing text use this tool; to overwrite the direct content under a header use bear-replace-text.',
     inputSchema: {
         id: z
             .string()
@@ -217,7 +228,7 @@ server.registerTool('bear-add-text', {
             .string()
             .trim()
             .optional()
-            .describe('Optional section header to target (adds text within that section)'),
+            .describe('Optional section header to target (adds text within that section). Accepts any heading level, including the note title (H1).'),
         position: z
             .enum(['beginning', 'end'])
             .optional()
@@ -235,7 +246,7 @@ server.registerTool('bear-add-text', {
 });
 server.registerTool('bear-replace-text', {
     title: 'Replace Note Content',
-    description: 'Replace content in an existing Bear note — either the full body or a specific section. Requires content replacement to be enabled in extension settings. Use bear-search-notes first to get the note ID.',
+    description: 'Replace content in an existing Bear note — either the full body or a specific section. Requires content replacement to be enabled in extension settings. Use bear-search-notes first to get the note ID. To add text without replacing existing content use bear-add-text instead.',
     inputSchema: {
         id: z
             .string()
@@ -249,12 +260,12 @@ server.registerTool('bear-replace-text', {
             .string()
             .trim()
             .min(1, 'Text content is required')
-            .describe('Replacement text content'),
+            .describe('Replacement text content. When scope is "section", provide only the direct content for the targeted header — do not include markdown sub-headers (###). Replace sub-sections with separate calls targeting each sub-header.'),
         header: z
             .string()
             .trim()
             .optional()
-            .describe('Section header to target — required when scope is "section", forbidden when scope is "full-note-body"'),
+            .describe('Section header to target — required when scope is "section", forbidden when scope is "full-note-body". Accepts any heading level, including the note title (H1).'),
     },
     annotations: {
         readOnlyHint: false,

package/dist/notes.js

@@ -1,6 +1,11 @@
+import { setTimeout } from 'node:timers/promises';
 import { DEFAULT_SEARCH_LIMIT } from './config.js';
 import { convertCoreDataTimestamp, convertDateToCoreDataTimestamp, logAndThrow, logger, parseDateString, } from './utils.js';
-import { openBearDatabase } from './database.js';
+import { closeBearDatabase, openBearDatabase } from './database.js';
+const POLL_INTERVAL_MS = 25;
+const POLL_TIMEOUT_MS = 2_000;
+// Safety window wider than POLL_TIMEOUT_MS to avoid matching a stale note with the same title
+const CREATION_LOOKBACK_MS = 10_000;
 // SQL equivalent of decodeTagName() in tags.ts — both MUST apply the same transformations
 const DECODED_TAG_TITLE = "LOWER(TRIM(REPLACE(t.ZTITLE, '+', ' ')))";
 /**
@@ -115,13 +120,7 @@ export function getNoteContent(identifier) {
         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}`);
-        }
+        closeBearDatabase(db);
     }
     return null;
 }
@@ -257,13 +256,55 @@ export function searchNotes(searchTerm, tag, limit, dateFilter, pinned) {
         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}`);
-        }
+        closeBearDatabase(db);
     }
     return { notes: [], totalCount: 0 };
 }
+/**
+ * Polls Bear's SQLite database for the identifier of a recently created note.
+ * Designed for use after bear-create-note fires the URL API — the note creation already
+ * succeeded, so errors here degrade gracefully to null instead of throwing.
+ *
+ * @param title - Exact title to match (case-sensitive, as Bear stores it)
+ * @returns The created note's identifier, or null if not found within the timeout window
+ */
+export async function awaitNoteCreation(title) {
+    if (!title?.trim()) {
+        logger.debug('awaitNoteCreation: skipped — no title provided');
+        return null;
+    }
+    logger.debug(`awaitNoteCreation: polling for note "${title}"`);
+    const sinceTimestamp = convertDateToCoreDataTimestamp(new Date(Date.now() - CREATION_LOOKBACK_MS));
+    let db;
+    try {
+        db = openBearDatabase();
+        const stmt = db.prepare(`
+      SELECT ZUNIQUEIDENTIFIER as identifier
+      FROM ZSFNOTE
+      WHERE ZTITLE = ? AND ZCREATIONDATE >= ?
+        AND ZARCHIVED = 0 AND ZTRASHED = 0 AND ZENCRYPTED = 0
+      ORDER BY ZCREATIONDATE DESC LIMIT 1
+    `);
+        const deadline = Date.now() + POLL_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            const row = stmt.get(title, sinceTimestamp);
+            if (row) {
+                logger.debug(`awaitNoteCreation: found note "${title}"`);
+                return row.identifier;
+            }
+            await setTimeout(POLL_INTERVAL_MS);
+        }
+        logger.info(`awaitNoteCreation: timed out waiting for note "${title}"`);
+        return null;
+    }
+    catch (error) {
+        // Intentionally not using logAndThrow — the note was already created via URL API,
+        // failing to retrieve its ID should not turn a successful creation into an error
+        logger.error('awaitNoteCreation failed:', error);
+        return null;
+    }
+    finally {
+        if (db)
+            closeBearDatabase(db);
+    }
+}

package/dist/tags.js

@@ -1,5 +1,5 @@
 import { convertCoreDataTimestamp, logAndThrow, logger } from './utils.js';
-import { openBearDatabase } from './database.js';
+import { closeBearDatabase, openBearDatabase } from './database.js';
 /**
  * Decodes and normalizes Bear tag names.
  * - Replaces '+' with spaces (Bear's URL encoding)
@@ -112,13 +112,7 @@ export function listTags() {
         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}`);
-        }
+        closeBearDatabase(db);
     }
     return { tags: [], totalCount: 0 };
 }
@@ -167,13 +161,7 @@ export function findUntaggedNotes(limit = 50) {
         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}`);
-        }
+        closeBearDatabase(db);
     }
     return { notes: [], totalCount: 0 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bear-notes-mcp",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Bear Notes MCP server with TypeScript and native SQLite",
   "type": "module",
   "main": "dist/main.js",