bear-notes-mcp 2.8.1 → 2.9.0

package/README.md

@@ -2,11 +2,11 @@
 
 Search, read, create, and update your Bear Notes from any AI assistant.
 
-**Full documentation and source code: [claude-desktop-extension-bear-notes](https://github.com/vasylenko/claude-desktop-extension-bear-notes)**
+**Full documentation and source code: [bear-notes-mcp](https://github.com/vasylenko/bear-notes-mcp)**
 
 ## Key Features
 
-- **10 MCP tools** for full Bear Notes integration
+- **12 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)
@@ -21,7 +21,7 @@ Search, read, create, and update your Bear Notes from any AI assistant.
 - **`bear-search-notes`** - Find notes by searching text content, filtering by tags, or date ranges. Includes OCR search in attachments
 - **`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-add-file`** - Attach a file to an existing Bear note. Provide a local file path (preferred) or 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
 - **`bear-add-tag`** - Add one or more tags to an existing Bear note
@@ -83,8 +83,8 @@ Example with configuration:
 
 **Step 1: Clone and build**
 ```bash
-git clone https://github.com/vasylenko/claude-desktop-extension-bear-notes.git
-cd claude-desktop-extension-bear-notes
+git clone https://github.com/vasylenko/bear-notes-mcp.git
+cd bear-notes-mcp
 npm install
 npm run build
 ```

package/dist/config.js

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

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 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 { awaitNoteCreation, getNoteContent, searchNotes } from './notes.js';
+import { awaitNoteCreation, findNotesByTitle, getNoteContent, searchNotes } from './notes.js';
 import { findUntaggedNotes, listTags } from './tags.js';
 import { buildBearUrl, executeBearXCallbackApi } from './bear-urls.js';
 const server = new McpServer({
@@ -16,7 +18,7 @@ const server = new McpServer({
         '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.',
+        'Use bear-search-notes to find note IDs before reading or modifying notes, or provide an exact title to bear-open-note for direct lookup.',
         '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.',
@@ -24,22 +26,51 @@ const server = new McpServer({
 });
 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.',
+    description: 'Read the full text content of a Bear note by its ID or title. Supports direct title lookup as an alternative to searching first. Always includes text extracted from attached images and PDFs (aka OCR search) with clear labeling.',
     inputSchema: {
         id: z
             .string()
             .trim()
-            .min(1, 'Note ID is required')
-            .describe('Exact note identifier (ID) obtained from bear-search-notes'),
+            .optional()
+            .describe('Note identifier (ID) from bear-search-notes. Either id or title must be provided.'),
+        title: z
+            .string()
+            .trim()
+            .optional()
+            .describe('Exact note title for direct lookup (case-insensitive). Either id or title must be provided. If multiple notes share the same title, returns a list for disambiguation.'),
     },
     annotations: {
         readOnlyHint: true,
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ id }) => {
-    logger.info(`bear-open-note called with id: ${id}, includeFiles: always`);
+}, async ({ id, title }) => {
+    logger.info(`bear-open-note called with id: ${id || 'none'}, title: ${title ? '"' + title + '"' : 'none'}`);
+    if (!id && !title) {
+        return createToolResponse('Either note ID or title is required. Use bear-search-notes to find the note ID, or provide the exact title.');
+    }
     try {
+        // Title lookup path: find by title, then fetch full content
+        if (!id && title) {
+            const matches = findNotesByTitle(title);
+            if (matches.length === 0) {
+                return createToolResponse(`No note found with title "${title}". The note may have been deleted, archived, or the title may be different.
+
+Use bear-search-notes to find notes by partial text match.`);
+            }
+            if (matches.length > 1) {
+                const matchList = matches
+                    .map((m, i) => `${i + 1}. ID: ${m.identifier} (modified: ${m.modification_date})`)
+                    .join('\n');
+                return createToolResponse(`Multiple notes found with title "${title}":
+
+${matchList}
+
+Use bear-open-note with a specific ID to open the desired note.`);
+            }
+            // Exactly one match — fetch full content by ID
+            id = matches[0].identifier;
+        }
         const noteWithContent = getNoteContent(id);
         if (!noteWithContent) {
             return createToolResponse(`Note with ID '${id}' not found. The note may have been deleted, archived, or the ID may be incorrect.
@@ -262,7 +293,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. To add text without replacing existing content use bear-add-text instead.',
+    description: 'Replace content in an existing Bear note — either the full body or a specific section. Requires content replacement to be enabled in 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()
@@ -293,7 +324,7 @@ server.registerTool('bear-replace-text', {
     if (!ENABLE_CONTENT_REPLACEMENT) {
         return createToolResponse(`Content replacement is not enabled.
 
-To use replace mode, enable "Content Replacement" in the Bear Notes extension settings.`);
+To use replace mode, enable "Content Replacement" in the Bear Notes server settings.`);
     }
     if (scope === 'section' && !header) {
         return createToolResponse(`scope is "section" but no header was provided.
@@ -309,18 +340,26 @@ Remove the header parameter to replace the full note body, or change scope to "s
 });
 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.',
+    description: 'Attach a file to an existing Bear note. Preferred: provide file_path for files on disk — the server reads and encodes them automatically. Alternative: provide base64_content with pre-encoded data. Use bear-search-notes first to get the note ID.',
     inputSchema: {
+        file_path: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe('Path to a file on disk. Preferred over base64_content when the file already exists locally.'),
         base64_content: z
             .string()
             .trim()
-            .min(1, 'Base64 file content is required')
-            .describe('Base64-encoded file content'),
+            .min(1)
+            .optional()
+            .describe('Base64-encoded file content. Use file_path instead when the file exists on disk.'),
         filename: z
             .string()
             .trim()
-            .min(1, 'Filename is required')
-            .describe('Filename with extension (e.g., budget.xlsx, report.pdf)'),
+            .min(1)
+            .optional()
+            .describe('Filename with extension (e.g., budget.xlsx, report.pdf). Required when using base64_content. Auto-inferred from file_path when omitted.'),
         id: z
             .string()
             .trim()
@@ -334,14 +373,49 @@ server.registerTool('bear-add-file', {
         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'}`);
+}, async ({ file_path, base64_content, filename, id, title }) => {
+    logger.info(`bear-add-file called with file_path: ${file_path || 'none'}, base64_content: ${base64_content ? 'provided' : 'none'}, filename: ${filename || 'none'}, id: ${id || 'none'}, title: ${title || 'none'}`);
     if (!id && !title) {
-        throw new Error('Either note ID or title is required. Use bear-search-notes to find the note ID.');
+        return createToolResponse('Either note ID or title is required. Use bear-search-notes to find the note ID.');
+    }
+    if (file_path && base64_content) {
+        return createToolResponse('Provide either file_path or base64_content, not both.');
+    }
+    if (!file_path && !base64_content) {
+        return createToolResponse('Either file_path or base64_content is required.');
+    }
+    if (base64_content && !filename) {
+        return createToolResponse('filename is required when using base64_content.');
     }
     try {
-        // base64 CLI adds line breaks that break URL encoding
-        const cleanedBase64 = cleanBase64(base64_content);
+        let fileData;
+        let resolvedFilename;
+        if (file_path) {
+            // Read file from disk and encode — avoids the LLM producing thousands of base64 tokens
+            try {
+                const buffer = readFileSync(file_path);
+                if (buffer.length === 0) {
+                    return createToolResponse(`File is empty: ${file_path}`);
+                }
+                fileData = buffer.toString('base64');
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === 'ENOENT') {
+                    return createToolResponse(`File not found: ${file_path}`);
+                }
+                if (code === 'EACCES') {
+                    return createToolResponse(`Permission denied: ${file_path}`);
+                }
+                return createToolResponse(`Cannot read file: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            resolvedFilename = filename || basename(file_path);
+        }
+        else {
+            // base64_content path — strip whitespace that base64 CLI adds
+            fileData = cleanBase64(base64_content);
+            resolvedFilename = filename;
+        }
         // Fail fast with helpful message rather than cryptic Bear error
         if (id) {
             const existingNote = getNoteContent(id);
@@ -354,14 +428,14 @@ Use bear-search-notes to find the correct note identifier.`);
         const url = buildBearUrl('add-file', {
             id,
             title,
-            file: cleanedBase64,
-            filename,
+            file: fileData,
+            filename: resolvedFilename,
             mode: 'append',
         });
-        logger.debug(`Executing Bear add-file URL for: ${filename}`);
+        logger.debug(`Executing Bear add-file URL for: ${resolvedFilename}`);
         await executeBearXCallbackApi(url);
         const noteIdentifier = id ? `Note ID: ${id}` : `Note title: "${title}"`;
-        return createToolResponse(`File "${filename}" added successfully!
+        return createToolResponse(`File "${resolvedFilename}" added successfully!
 
 ${noteIdentifier}
 

package/dist/notes.js

@@ -121,6 +121,57 @@ export function getNoteContent(identifier) {
     }
     return null;
 }
+/**
+ * Finds Bear notes matching an exact title (case-insensitive).
+ * Returns lightweight match objects for disambiguation — call getNoteContent()
+ * with the chosen identifier to retrieve the full note.
+ *
+ * @param title - The exact note title to match
+ * @returns Array of matching notes (empty if none found)
+ * @throws Error if database access fails
+ */
+export function findNotesByTitle(title) {
+    logger.info(`findNotesByTitle called with title: "${title}"`);
+    if (!title || typeof title !== 'string' || !title.trim()) {
+        logAndThrow('Database error: Invalid note title provided');
+    }
+    const db = openBearDatabase();
+    try {
+        const query = `
+      SELECT ZTITLE as title,
+             ZUNIQUEIDENTIFIER as identifier,
+             ZMODIFICATIONDATE as modificationDate
+      FROM ZSFNOTE
+      WHERE ZTITLE = ? COLLATE NOCASE
+        AND ZARCHIVED = 0
+        AND ZTRASHED = 0
+        AND ZENCRYPTED = 0
+      ORDER BY ZMODIFICATIONDATE DESC
+    `;
+        const stmt = db.prepare(query);
+        const rows = stmt.all(title.trim());
+        if (!rows || rows.length === 0) {
+            logger.info(`No notes found with title: "${title}"`);
+            return [];
+        }
+        logger.info(`Found ${rows.length} note(s) with title: "${title}"`);
+        return rows.map((row) => {
+            const r = row;
+            return {
+                identifier: r.identifier,
+                title: r.title || 'Untitled',
+                modification_date: convertCoreDataTimestamp(r.modificationDate),
+            };
+        });
+    }
+    catch (error) {
+        logAndThrow(`Database error: Failed to find notes by title: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        closeBearDatabase(db);
+    }
+    return [];
+}
 /**
  * Searches Bear notes by content or tags with optional filtering.
  * Returns a list of notes without full content for performance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bear-notes-mcp",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Bear Notes MCP server with TypeScript and native SQLite",
   "type": "module",
   "main": "dist/main.js",
@@ -49,7 +49,9 @@
     "notes management",
     "productivity",
     "typescript",
-    "mcp"
+    "mcp",
+    "mcp-server",
+    "ai-assistant"
   ],
   "author": {
     "name": "Serhii Vasylenko",
@@ -59,12 +61,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vasylenko/claude-desktop-extension-bear-notes.git"
+    "url": "git+https://github.com/vasylenko/bear-notes-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/vasylenko/claude-desktop-extension-bear-notes/issues"
+    "url": "https://github.com/vasylenko/bear-notes-mcp/issues"
   },
-  "homepage": "https://github.com/vasylenko/claude-desktop-extension-bear-notes#readme",
+  "homepage": "https://github.com/vasylenko/bear-notes-mcp#readme",
   "bin": {
     "bear-notes-mcp": "dist/main.js"
   },