bear-notes-mcp 2.5.0 → 2.6.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.6.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/main.js

@@ -11,6 +11,16 @@ 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',
@@ -201,7 +211,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 +227,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 +245,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 +259,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/package.json

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