bear-notes-mcp-xq7k 2.0.1

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,109 @@
+# Bear Notes MCP Server
+
+Search, read, and update your Bear Notes
+
+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
+```
+
+Read more here -- [README.npm.md](./README.npm.md)
+
+**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"]
+    }
+  }
+}
+```

package/README.npm.md

@@ -0,0 +1,109 @@
+# Bear Notes MCP Server
+
+Search, read, and update your Bear Notes
+
+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
+```
+
+Read more here -- [README.npm.md](./README.npm.md)
+
+**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"]
+    }
+  }
+}
+```

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