bear-notes-mcp 2.0.0

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,186 @@
+[![Supply Chain](https://github.com/vasylenko/claude-desktop-extension-bear-notes/actions/workflows/workflow.yml/badge.svg)](https://github.com/vasylenko/claude-desktop-extension-bear-notes/actions/workflows/workflow.yml)
+[![Snyk](https://snyk.io/test/github/vasylenko/claude-desktop-extension-bear-notes/badge.svg)](https://snyk.io/test/github/vasylenko/claude-desktop-extension-bear-notes)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/34d7b12a-3983-40a3-876f-3cdd2ccfe3f2)
+    
+# Bear Notes Claude Extension (aka MCP Bundle)
+
+Search, read, and update your Bear Notes directly from Claude conversations.
+
+This Claude Desktop extension (bundled MCP server) provides seamless integration between AI assistance and your personal note-taking workflow with complete privacy: local-only operations, no external connections.
+
+![](./docs/demo.gif)
+
+## Staying Up To Date
+
+Consider to subscribe to release announcements to know when I release a new version of the extenstion:
+
+![](./docs/stay-updated.png)
+
+I also post to [reddit.com/r/bearapp/](https://www.reddit.com/r/bearapp/) when there's a new release.
+
+## Quick Start
+
+**Prerequisites**: [Bear app](https://bear.app/) must be installed and [Claude Desktop](https://claude.ai/download) must be installed.
+
+1. Download the latest `bear-notes-mcpb.mcpb` extension from releases
+2. Make sure your Claude Desktop is running (start if not)
+3. Doubleclick on the extension file – Claude Desktop should show you the installation prompt
+
+    If doubleclick does not work for some reason, then open Claude -> Settings -> Extensions -> Advanced Settings -> click "Install Extension".
+4. You're all set!
+
+Ask Claude to search your Bear notes with a query like "Search my Bear notes for 'meeting'" - you should see your notes appear in the response!
+
+## Standalone MCP Server Usage
+
+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.
+
+**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
+```
+
+**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
+```
+
+That's it! The server will be downloaded from npm and configured automatically.
+
+### Quick Start - Other AI Assistants
+
+**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"]
+    }
+  }
+}
+```
+
+**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"],
+      "env": {
+        "NODE_OPTIONS": "--experimental-sqlite"
+      }
+    }
+  }
+}
+```
+
+**Config file locations:**
+- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Cline**: VS Code Settings → Extensions → Cline → MCP Settings
+- **Continue**: `~/.continue/config.json`
+- **Cursor**: Settings → Cursor Settings → MCP
+
+**Check your Node.js version:** `node --version`
+
+### Advanced: Local Development Build
+
+If you want to contribute or modify the code:
+
+**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"]
+    }
+  }
+}
+```
+
+## MCP Server 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
+
+## Technical Details
+
+This server reads your Bear Notes SQLite database directly for search/read operations and uses Bear's X-callback-URL API for write operations. All data processing happens locally on your machine with no external network calls.
+
+### Platforms Supported
+macOS only because Bear desktop works only on macOS.
+
+### Logs
+- MCP server logs go into `~/Library/Logs/Claude/main.log`, look for `bear-notes-mcp`
+- MCP transport logs go to `~/Library/Logs/Claude/mcp-server-Bear\ Notes.log` 
+
+## FAQ
+
+### Could this steal my data?
+**No**. Extension only reads Bear's local database (same data Bear app shows you) and uses Bear's application native API to add text to the notes. No network transmission, no external servers.
+
+### Why SQLite and not just a native Bear app's x-callback-url API?
+
+For read operations (search/open), the x-callback-url API returns the note data in `x-success` response: that would require a server or custom binary to handle x-success responses - both risky and fragile. Direct SQLite read-only access is simpler and more reliable for searching and reading notes.
+
+### Why experimental flag for nodejs?
+
+This is to enable native SQLite support and avoid shipping an SQLite binary from third-party node packages, which poses supply chain risks and blocks the Claude extension from running on macOS.
+
+Anthropic does not sign third-party SQLite binaries (obviously), causing macOS security systems to flag that the Claude process from a binary signed by Anthropic is trying to run another binary signed by a third party. As a result, Claude cannot run the extension. 
+
+### When I install the extension, I see a red warning: "Installing will grant access to everything on your computer." - what does this mean?
+
+This is how Claude for Desktop reacts to the fact that this extension needs access to the Bear SQLite databse on your Mac.
+
+Claude warning system does not distinguish between the need to access only one file (what the extension does) versus the need to access all files (this is NOT what the extention does).
+
+One of the ways to validate this is asking your Claude to analyze the codebase (it is pretty small) before installing the extension and tell you.
+
+### How can I report a bug or contribute? 
+
+Use issues or discussions! I'd be glad to see your feedback or suggestions, or your help to make this extension better! ❤️ 
+
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/vasylenko-claude-desktop-extension-bear-notes-badge.png)](https://mseep.ai/app/vasylenko-claude-desktop-extension-bear-notes)

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.0.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)}`);
+    }
+}