bear-notes-mcp 2.4.1 → 2.5.0

package/README.md

@@ -6,10 +6,11 @@ Search, read, create, and update your Bear Notes from any AI assistant.
 
 ## Key Features
 
-- **9 MCP tools** for full Bear Notes integration
+- **10 MCP tools** for full Bear Notes integration
 - **OCR search** across images and PDFs attached to notes
 - **Date-based search** with relative dates ("yesterday", "last week", etc.)
 - **Configurable new note convention** for tag placement (opt-in)
+- **Content replacement** for replacing note body or specific sections (opt-in)
 - **Local-only** — no network calls, all data stays on your Mac
 
 ## Tools
@@ -19,6 +20,7 @@ Search, read, create, and update your Bear Notes from any AI assistant.
 - **`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-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
 - **`bear-find-untagged-notes`** - Find notes in your Bear library that have no tags assigned
@@ -56,6 +58,7 @@ Add to your MCP configuration file:
 |---|---|---|
 | `UI_DEBUG_TOGGLE` | `false` | Enable debug logging for troubleshooting |
 | `UI_ENABLE_NEW_NOTE_CONVENTION` | `false` | Place tags right after the note title instead of at the bottom |
+| `UI_ENABLE_CONTENT_REPLACEMENT` | `false` | Enable the `bear-replace-text` tool for replacing note content |
 
 Example with configuration:
 ```json
@@ -66,6 +69,7 @@ Example with configuration:
       "args": ["-y", "bear-notes-mcp@latest"],
       "env": {
         "UI_ENABLE_NEW_NOTE_CONVENTION": "true",
+        "UI_ENABLE_CONTENT_REPLACEMENT": "true",
         "UI_DEBUG_TOGGLE": "true"
       }
     }

package/dist/bear-urls.js

@@ -27,14 +27,13 @@ export function buildBearUrl(action, params = {}) {
     if (params.mode !== undefined) {
         urlParams.set('mode', params.mode);
     }
+    if (params.new_line !== undefined) {
+        urlParams.set('new_line', params.new_line);
+    }
     // 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}`;

package/dist/config.js

@@ -1,9 +1,10 @@
-export const APP_VERSION = '2.4.1';
+export const APP_VERSION = '2.5.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 ENABLE_NEW_NOTE_CONVENTIONS = process.env.UI_ENABLE_NEW_NOTE_CONVENTION === 'true';
+export const ENABLE_CONTENT_REPLACEMENT = process.env.UI_ENABLE_CONTENT_REPLACEMENT === 'true';
 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.',
 };

package/dist/main.js

@@ -2,9 +2,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { APP_VERSION, ENABLE_NEW_NOTE_CONVENTIONS } from './config.js';
+import { APP_VERSION, ENABLE_CONTENT_REPLACEMENT, ENABLE_NEW_NOTE_CONVENTIONS } from './config.js';
 import { applyNoteConventions } from './note-conventions.js';
-import { cleanBase64, createToolResponse, handleAddText, logger } from './utils.js';
+import { cleanBase64, createToolResponse, handleNoteTextUpdate, logger } from './utils.js';
 import { getNoteContent, searchNotes } from './notes.js';
 import { findUntaggedNotes, listTags } from './tags.js';
 import { buildBearUrl, executeBearXCallbackApi } from './bear-urls.js';
@@ -225,13 +225,60 @@ server.registerTool('bear-add-text', {
     },
     annotations: {
         readOnlyHint: false,
-        destructiveHint: true,
+        destructiveHint: false,
         idempotentHint: false,
         openWorldHint: true,
     },
 }, async ({ id, text, header, position }) => {
     const mode = position === 'beginning' ? 'prepend' : 'append';
-    return handleAddText(mode, { id, text, header });
+    return handleNoteTextUpdate(mode, { id, text, header });
+});
+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.',
+    inputSchema: {
+        id: z
+            .string()
+            .trim()
+            .min(1, 'Note ID is required')
+            .describe('Note identifier (ID) from bear-search-notes'),
+        scope: z
+            .enum(['section', 'full-note-body'])
+            .describe("Replacement target: 'section' replaces under a specific header (requires header), 'full-note-body' replaces the entire note body (header must not be set)"),
+        text: z
+            .string()
+            .trim()
+            .min(1, 'Text content is required')
+            .describe('Replacement text content'),
+        header: z
+            .string()
+            .trim()
+            .optional()
+            .describe('Section header to target — required when scope is "section", forbidden when scope is "full-note-body"'),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async ({ id, scope, text, header }) => {
+    if (!ENABLE_CONTENT_REPLACEMENT) {
+        return createToolResponse(`Content replacement is not enabled.
+
+To use replace mode, enable "Content Replacement" in the Bear Notes extension settings.`);
+    }
+    if (scope === 'section' && !header) {
+        return createToolResponse(`scope is "section" but no header was provided.
+
+Set the header parameter to the section heading you want to replace.`);
+    }
+    if (scope === 'full-note-body' && header) {
+        return createToolResponse(`scope is "full-note-body" but a header was provided.
+
+Remove the header parameter to replace the full note body, or change scope to "section".`);
+    }
+    return handleNoteTextUpdate('replace', { id, text, header });
 });
 server.registerTool('bear-add-file', {
     title: 'Add File to Note',

package/dist/utils.js

@@ -134,16 +134,43 @@ export function createToolResponse(text) {
     };
 }
 /**
- * Shared handler for adding text to Bear notes (append or prepend).
+ * Strips a matching markdown heading from the start of text to prevent header duplication.
+ * Bear's add-text API with mode=replace keeps the original section header, so if the
+ * replacement text also starts with that header, it appears twice in the note.
+ *
+ * @param text - The replacement text that may start with a duplicate heading
+ * @param header - The cleaned header name (no # prefix) to match against
+ * @returns Text with the leading heading removed if it matched, otherwise unchanged
+ */
+export function stripLeadingHeader(text, header) {
+    if (!header)
+        return text;
+    const escaped = header.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const leadingHeaderRegex = new RegExp(`^#{1,6}\\s+${escaped}\\s*\\n?`, 'i');
+    return text.replace(leadingHeaderRegex, '');
+}
+/**
+ * Checks whether a markdown heading matching the given header text exists in the note.
+ * Strips markdown prefix from input (e.g., "## Foo" → "Foo") and matches case-insensitively.
+ * Escapes regex special characters so headers like "Q&A" or "Details (v2)" match literally.
+ */
+export function noteHasHeader(noteText, header) {
+    const cleanHeader = header.replace(/^#+\s*/, '');
+    const escaped = cleanHeader.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const headerRegex = new RegExp(`^#{1,6}\\s+${escaped}\\s*$`, 'mi');
+    return headerRegex.test(noteText);
+}
+/**
+ * Shared handler for note text operations (append, prepend, or replace).
  * Consolidates common validation, execution, and response logic.
  *
- * @param mode - Whether to append or prepend text
+ * @param mode - Whether to append, prepend, or replace 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'}`);
+export async function handleNoteTextUpdate(mode, { id, text, header }) {
+    const action = mode === 'append' ? 'appended' : mode === 'prepend' ? 'prepended' : 'replaced';
+    logger.info(`handleNoteTextUpdate(${mode}) id: ${id}, text length: ${text.length}, header: ${header || 'none'}`);
     try {
         const existingNote = getNoteContent(id);
         if (!existingNote) {
@@ -151,28 +178,51 @@ export async function handleAddText(mode, { id, text, header }) {
 
 Use bear-search-notes to find the correct note identifier.`);
         }
-        // Strip markdown header syntax from header parameter for Bear API
+        // Strip markdown header syntax once — reused for both validation and Bear API
         const cleanHeader = header?.replace(/^#+\s*/, '');
+        // Bear silently ignores replace-with-header when the section doesn't exist — fail early with a clear message
+        if (mode === 'replace' && cleanHeader) {
+            if (!existingNote.text || !noteHasHeader(existingNote.text, cleanHeader)) {
+                return createToolResponse(`Section "${cleanHeader}" not found in note "${existingNote.title}".
+
+Check the note content with bear-open-note to see available sections.`);
+            }
+        }
+        // Bear's replace mode preserves the original heading (section header or note title),
+        // so if the AI includes it in the replacement text, the result has a duplicate.
+        const cleanText = mode === 'replace' ? stripLeadingHeader(text, cleanHeader || existingNote.title) : text;
         const url = buildBearUrl('add-text', {
             id,
-            text,
+            text: cleanText,
             header: cleanHeader,
             mode,
+            // Ensures appended/prepended text starts on its own line, not glued to existing content.
+            // Not needed for replace — there's no preceding content to separate from.
+            new_line: mode !== 'replace' ? 'yes' : undefined,
         });
         logger.debug(`Executing Bear URL: ${url}`);
         await executeBearXCallbackApi(url);
-        const responseLines = [`Text ${action} to note "${existingNote.title}" successfully!`, ''];
+        const preposition = mode === 'replace' ? 'in' : 'to';
+        const responseLines = [
+            `Text ${action} ${preposition} note "${existingNote.title}" successfully!`,
+            '',
+        ];
         responseLines.push(`Text: ${text.length} characters`);
-        if (header) {
-            responseLines.push(`Section: ${header}`);
+        if (cleanHeader) {
+            responseLines.push(`Section: ${cleanHeader}`);
         }
         responseLines.push(`Note ID: ${id}`);
+        const trailingMessage = mode === 'replace'
+            ? cleanHeader
+                ? 'The section content has been replaced in your Bear note.'
+                : 'The note content has been replaced in your Bear note.'
+            : 'The text has been added to your Bear note.';
         return createToolResponse(`${responseLines.join('\n')}
 
-The text has been added to your Bear note.`);
+${trailingMessage}`);
     }
     catch (error) {
-        logger.error(`bear-add-text-${mode} failed: ${error}`);
+        logger.error(`handleNoteTextUpdate(${mode}) failed: ${error}`);
         throw error;
     }
 }

package/dist/utils.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { convertCoreDataTimestamp, parseDateString } from './utils.js';
+import { convertCoreDataTimestamp, noteHasHeader, parseDateString, stripLeadingHeader, } from './utils.js';
 describe('parseDateString', () => {
     beforeEach(() => {
         // Fix "now" to January 15, 2026 for predictable tests
@@ -25,6 +25,79 @@ describe('parseDateString', () => {
         expect(result.getSeconds()).toBe(59);
     });
 });
+describe('noteHasHeader', () => {
+    const noteText = [
+        '# Title',
+        'Intro paragraph',
+        '',
+        '## Details',
+        'Some details here',
+        '',
+        '### Q&A',
+        'Questions and answers',
+        '',
+        '## Details (v2)',
+        'Updated details',
+        '',
+        '## v1.0 Release',
+        'Release notes',
+    ].join('\n');
+    it('finds an exact header match', () => {
+        expect(noteHasHeader(noteText, 'Details')).toBe(true);
+    });
+    it('strips markdown prefix from header input', () => {
+        expect(noteHasHeader(noteText, '## Details')).toBe(true);
+        expect(noteHasHeader(noteText, '### Q&A')).toBe(true);
+    });
+    it('matches case-insensitively', () => {
+        expect(noteHasHeader(noteText, 'details')).toBe(true);
+        expect(noteHasHeader(noteText, 'DETAILS')).toBe(true);
+    });
+    it('rejects partial header name', () => {
+        expect(noteHasHeader(noteText, 'Detail')).toBe(false);
+    });
+    it('handles parentheses in header name', () => {
+        expect(noteHasHeader(noteText, 'Details (v2)')).toBe(true);
+    });
+    it('handles ampersand in header name', () => {
+        expect(noteHasHeader(noteText, 'Q&A')).toBe(true);
+    });
+    it('handles dots in header name', () => {
+        expect(noteHasHeader(noteText, 'v1.0 Release')).toBe(true);
+    });
+    it('returns false for empty note text', () => {
+        expect(noteHasHeader('', 'Details')).toBe(false);
+    });
+    it('returns false for empty header input', () => {
+        expect(noteHasHeader(noteText, '')).toBe(false);
+    });
+});
+describe('stripLeadingHeader', () => {
+    it('strips matching header with exact case', () => {
+        expect(stripLeadingHeader('## Details\nNew content', 'Details')).toBe('New content');
+    });
+    it('strips matching header case-insensitively', () => {
+        expect(stripLeadingHeader('## DETAILS\nNew content', 'Details')).toBe('New content');
+        expect(stripLeadingHeader('## details\nNew content', 'Details')).toBe('New content');
+    });
+    it('strips matching header at any heading level', () => {
+        expect(stripLeadingHeader('### Details\nNew content', 'Details')).toBe('New content');
+        expect(stripLeadingHeader('#### Details\nNew content', 'Details')).toBe('New content');
+    });
+    it('does not strip when header text does not match', () => {
+        expect(stripLeadingHeader('## Other\nNew content', 'Details')).toBe('## Other\nNew content');
+    });
+    it('does not strip when text does not start with a header', () => {
+        expect(stripLeadingHeader('New content', 'Details')).toBe('New content');
+    });
+    it('handles special characters in header name', () => {
+        expect(stripLeadingHeader('## Details (v2)\nNew content', 'Details (v2)')).toBe('New content');
+        expect(stripLeadingHeader('## Q&A\nNew content', 'Q&A')).toBe('New content');
+    });
+    it('returns text unchanged when header is empty string', () => {
+        expect(stripLeadingHeader('## Details\nNew content', '')).toBe('## Details\nNew content');
+    });
+});
 describe('convertCoreDataTimestamp', () => {
     it('converts Core Data timestamp to correct ISO string', () => {
         // Core Data timestamp 0 = 2001-01-01 00:00:00 UTC

package/package.json

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