bear-notes-mcp 2.0.0

package/dist/tags.js

@@ -0,0 +1,170 @@
+import { convertCoreDataTimestamp, logAndThrow, logger } from './utils.js';
+import { openBearDatabase } from './database.js';
+/**
+ * Decodes and normalizes Bear tag names.
+ * - Replaces '+' with spaces (Bear's URL encoding)
+ * - Converts to lowercase (matches Bear UI behavior)
+ * - Trims whitespace
+ */
+function decodeTagName(encodedName) {
+    return encodedName.replace(/\+/g, ' ').trim().toLowerCase();
+}
+/**
+ * Extracts the display name (leaf) from a full tag path.
+ * For "career/content/blog" returns "blog", for "career" returns "career".
+ */
+function getTagDisplayName(fullPath) {
+    const parts = fullPath.split('/');
+    return parts[parts.length - 1];
+}
+/**
+ * Builds a hierarchical tree from a flat list of tags.
+ * Tags with paths like "career/content" become children of "career".
+ * Tags with 0 notes are excluded (matches Bear UI behavior).
+ */
+function buildTagHierarchy(flatTags) {
+    // Filter out tags with no notes (hidden in Bear UI)
+    const activeTags = flatTags.filter((t) => t.noteCount > 0);
+    const tagMap = new Map();
+    // Two-pass approach: first create nodes, then link parent-child relationships
+    for (const tag of activeTags) {
+        tagMap.set(tag.name, {
+            name: tag.name,
+            displayName: tag.displayName,
+            noteCount: tag.noteCount,
+            children: [],
+        });
+    }
+    const roots = [];
+    // Build parent-child relationships
+    for (const tag of activeTags) {
+        const tagNode = tagMap.get(tag.name);
+        if (tag.isRoot) {
+            roots.push(tagNode);
+        }
+        else {
+            // Subtags use path notation (e.g., "career/content"), so extract parent path
+            const lastSlash = tag.name.lastIndexOf('/');
+            if (lastSlash > 0) {
+                const parentName = tag.name.substring(0, lastSlash);
+                const parent = tagMap.get(parentName);
+                if (parent) {
+                    parent.children.push(tagNode);
+                }
+                else {
+                    // Orphan subtag - parent has 0 notes or doesn't exist, treat as root
+                    roots.push(tagNode);
+                }
+            }
+        }
+    }
+    // Sort children alphabetically at each level
+    const sortChildren = (tags) => {
+        tags.sort((a, b) => a.displayName.localeCompare(b.displayName));
+        for (const tag of tags) {
+            sortChildren(tag.children);
+        }
+    };
+    sortChildren(roots);
+    return roots;
+}
+/**
+ * Retrieves all tags from Bear database as a hierarchical tree.
+ * Each tag includes note count and nested children.
+ *
+ * @returns Object with tags array (tree structure) and total count
+ */
+export function listTags() {
+    logger.info('listTags called');
+    const db = openBearDatabase();
+    try {
+        const query = `
+      SELECT t.ZTITLE as name,
+             t.ZISROOT as isRoot,
+             COUNT(nt.Z_5NOTES) as noteCount
+      FROM ZSFNOTETAG t
+      LEFT JOIN Z_5TAGS nt ON nt.Z_13TAGS = t.Z_PK
+      GROUP BY t.Z_PK
+      ORDER BY t.ZTITLE
+    `;
+        const stmt = db.prepare(query);
+        const rows = stmt.all();
+        if (!rows || rows.length === 0) {
+            logger.info('No tags found in database');
+            return { tags: [], totalCount: 0 };
+        }
+        // Transform rows: decode names and extract display names
+        const flatTags = rows.map((row) => {
+            const decodedName = decodeTagName(row.name);
+            return {
+                name: decodedName,
+                displayName: getTagDisplayName(decodedName),
+                noteCount: row.noteCount,
+                isRoot: row.isRoot === 1,
+            };
+        });
+        const hierarchy = buildTagHierarchy(flatTags);
+        logger.info(`Retrieved ${rows.length} tags, ${hierarchy.length} root tags`);
+        return { tags: hierarchy, totalCount: rows.length };
+    }
+    catch (error) {
+        logAndThrow(`Database error: Failed to retrieve tags: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        try {
+            db.close();
+            logger.debug('Database connection closed');
+        }
+        catch (closeError) {
+            logger.error(`Failed to close database connection: ${closeError}`);
+        }
+    }
+    return { tags: [], totalCount: 0 };
+}
+/**
+ * Finds notes that have no tags assigned.
+ *
+ * @param limit - Maximum number of results (default: 50)
+ * @returns Array of untagged notes
+ */
+export function findUntaggedNotes(limit = 50) {
+    logger.info(`findUntaggedNotes called with limit: ${limit}`);
+    const db = openBearDatabase();
+    try {
+        const query = `
+      SELECT ZTITLE as title,
+             ZUNIQUEIDENTIFIER as identifier,
+             ZCREATIONDATE as creationDate,
+             ZMODIFICATIONDATE as modificationDate
+      FROM ZSFNOTE
+      WHERE ZARCHIVED = 0 AND ZTRASHED = 0 AND ZENCRYPTED = 0
+        AND Z_PK NOT IN (SELECT Z_5NOTES FROM Z_5TAGS)
+      ORDER BY ZMODIFICATIONDATE DESC
+      LIMIT ?
+    `;
+        const stmt = db.prepare(query);
+        const rows = stmt.all(limit);
+        const notes = rows.map((row) => ({
+            title: row.title || 'Untitled',
+            identifier: row.identifier,
+            creation_date: convertCoreDataTimestamp(row.creationDate),
+            modification_date: convertCoreDataTimestamp(row.modificationDate),
+            pin: 'no',
+        }));
+        logger.info(`Found ${notes.length} untagged notes`);
+        return notes;
+    }
+    catch (error) {
+        logAndThrow(`Database error: Failed to find untagged notes: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        try {
+            db.close();
+            logger.debug('Database connection closed');
+        }
+        catch (closeError) {
+            logger.error(`Failed to close database connection: ${closeError}`);
+        }
+    }
+    return [];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -0,0 +1,184 @@
+import createDebug from 'debug';
+import { CORE_DATA_EPOCH_OFFSET, ERROR_MESSAGES } from './config.js';
+import { getNoteContent } from './notes.js';
+import { buildBearUrl, executeBearXCallbackApi } from './bear-urls.js';
+export const logger = {
+    debug: createDebug('bear-notes-mcp:debug'),
+    info: createDebug('bear-notes-mcp:info'),
+    error: createDebug('bear-notes-mcp:error'),
+};
+// Convert UI_DEBUG_TOGGLE boolean set from UI to DEBUG string for debug package
+// MCPB has no way to make this in one step with manifest.json
+if (process.env.UI_DEBUG_TOGGLE === 'true') {
+    process.env.DEBUG = 'bear-notes-mcp:*';
+    logger.debug.enabled = true;
+}
+// Always enable error and info logs
+logger.error.enabled = true;
+logger.info.enabled = true;
+/**
+ * Logs an error message and throws an Error to halt execution.
+ * Centralizes error handling to ensure consistent logging before failures.
+ *
+ * @param message - The error message to log and throw
+ * @throws Always throws Error with the provided message
+ */
+export function logAndThrow(message) {
+    logger.error(message);
+    throw new Error(message);
+}
+/**
+ * Cleans base64 string by removing whitespace/newlines added by base64 command.
+ * URLSearchParams in buildBearUrl will handle URL encoding of special characters.
+ *
+ * @param base64String - Raw base64 string (may contain whitespace/newlines)
+ * @returns Cleaned base64 string without whitespace
+ */
+export function cleanBase64(base64String) {
+    // Remove all whitespace/newlines from base64 (base64 command adds line breaks)
+    return base64String.trim().replace(/\s+/g, '');
+}
+/**
+ * Converts Bear's Core Data timestamp to ISO string format.
+ * Bear stores timestamps in seconds since Core Data epoch (2001-01-01).
+ *
+ * @param coreDataTimestamp - Timestamp in seconds since Core Data epoch
+ * @returns ISO string representation of the timestamp
+ */
+export function convertCoreDataTimestamp(coreDataTimestamp) {
+    const unixTimestamp = coreDataTimestamp + CORE_DATA_EPOCH_OFFSET;
+    return new Date(unixTimestamp * 1000).toISOString();
+}
+/**
+ * Converts a JavaScript Date object to Bear's Core Data timestamp format.
+ * Core Data timestamps are in seconds since 2001-01-01 00:00:00 UTC.
+ *
+ * @param date - JavaScript Date object
+ * @returns Core Data timestamp in seconds
+ */
+export function convertDateToCoreDataTimestamp(date) {
+    const unixTimestamp = Math.floor(date.getTime() / 1000);
+    return unixTimestamp - CORE_DATA_EPOCH_OFFSET;
+}
+/**
+ * Parses a date string and returns a JavaScript Date object.
+ * Supports relative dates ("today", "yesterday", "last week", "last month") and ISO date strings.
+ *
+ * @param dateString - Date string to parse (e.g., "today", "2024-01-15", "last week")
+ * @returns Parsed Date object
+ * @throws Error if the date string is invalid
+ */
+export function parseDateString(dateString) {
+    const lowerDateString = dateString.trim().toLowerCase();
+    const now = new Date();
+    // Handle relative dates to provide user-friendly natural language date input
+    switch (lowerDateString) {
+        case 'today': {
+            const today = new Date(now);
+            today.setHours(0, 0, 0, 0);
+            return today;
+        }
+        case 'yesterday': {
+            const yesterday = new Date(now);
+            yesterday.setDate(yesterday.getDate() - 1);
+            yesterday.setHours(0, 0, 0, 0);
+            return yesterday;
+        }
+        case 'last week':
+        case 'week ago': {
+            const lastWeek = new Date(now);
+            lastWeek.setDate(lastWeek.getDate() - 7);
+            lastWeek.setHours(0, 0, 0, 0);
+            return lastWeek;
+        }
+        case 'last month':
+        case 'month ago':
+        case 'start of last month': {
+            // Calculate the first day of last month; month arithmetic handles year transitions correctly via JavaScript Date constructor
+            const lastMonth = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+            lastMonth.setHours(0, 0, 0, 0);
+            return lastMonth;
+        }
+        case 'end of last month': {
+            // Calculate the last day of last month; day 0 of current month equals last day of previous month
+            const endOfLastMonth = new Date(now.getFullYear(), now.getMonth(), 0);
+            endOfLastMonth.setHours(23, 59, 59, 999);
+            return endOfLastMonth;
+        }
+        default: {
+            // Try parsing as ISO date or other standard formats as fallback for user-provided explicit dates
+            const parsed = new Date(dateString);
+            if (isNaN(parsed.getTime())) {
+                logAndThrow(`Invalid date format: "${dateString}". Use ISO format (YYYY-MM-DD) or relative dates (today, yesterday, last week, last month, start of last month, end of last month).`);
+            }
+            return parsed;
+        }
+    }
+}
+/**
+ * Creates a standardized MCP tool response with consistent formatting.
+ * Centralizes response structure to follow DRY principles.
+ *
+ * @param text - The response text content
+ * @returns Formatted CallToolResult for MCP tools
+ */
+export function createToolResponse(text) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text,
+                annotations: { audience: ['user', 'assistant'] },
+            },
+        ],
+    };
+}
+/**
+ * Shared handler for adding text to Bear notes (append or prepend).
+ * Consolidates common validation, execution, and response logic.
+ *
+ * @param mode - Whether to append or prepend 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'}`);
+    if (!id || !id.trim()) {
+        throw new Error(ERROR_MESSAGES.MISSING_NOTE_ID);
+    }
+    if (!text || !text.trim()) {
+        throw new Error(ERROR_MESSAGES.MISSING_TEXT_PARAM);
+    }
+    try {
+        const existingNote = getNoteContent(id.trim());
+        if (!existingNote) {
+            return createToolResponse(`Note with ID '${id}' not found. The note may have been deleted, archived, or the ID may be incorrect.
+
+Use bear-search-notes to find the correct note identifier.`);
+        }
+        // Strip markdown header syntax from header parameter for Bear API
+        const cleanHeader = header?.trim().replace(/^#+\s*/, '');
+        const url = buildBearUrl('add-text', {
+            id: id.trim(),
+            text: text.trim(),
+            header: cleanHeader,
+            mode,
+        });
+        logger.debug(`Executing Bear URL: ${url}`);
+        await executeBearXCallbackApi(url);
+        const responseLines = [`Text ${action} to note "${existingNote.title}" successfully!`, ''];
+        responseLines.push(`Text: ${text.trim().length} characters`);
+        if (header?.trim()) {
+            responseLines.push(`Section: ${header.trim()}`);
+        }
+        responseLines.push(`Note ID: ${id.trim()}`);
+        return createToolResponse(`${responseLines.join('\n')}
+
+The text has been added to your Bear note.`);
+    }
+    catch (error) {
+        logger.error(`bear-add-text-${mode} failed: ${error}`);
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "bear-notes-mcp",
+  "version": "2.0.0",
+  "description": "Bear Notes MCP server with TypeScript and native SQLite",
+  "type": "module",
+  "main": "dist/main.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/main.ts --debug",
+    "start": "node --experimental-sqlite dist/main.js",
+    "lint": "eslint src --fix",
+    "lint:check": "eslint src",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src",
+    "check": "npm run lint:check && npm run format:check",
+    "fix": "npm run lint && npm run format"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "debug": "^4.4.3",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^24.10.4",
+    "@typescript-eslint/eslint-plugin": "^8.46.3",
+    "@typescript-eslint/parser": "^8.46.3",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.7.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "overrides": {
+    "body-parser": "2.2.1"
+  },
+  "keywords": [
+    "bear app",
+    "bear notes",
+    "markdown notes",
+    "notes management",
+    "productivity",
+    "typescript",
+    "mcp"
+  ],
+  "author": {
+    "name": "Serhii Vasylenko",
+    "email": "serhii@vasylenko.info",
+    "url": "https://devdosvid.blog"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vasylenko/claude-desktop-extension-bear-notes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vasylenko/claude-desktop-extension-bear-notes/issues"
+  },
+  "homepage": "https://github.com/vasylenko/claude-desktop-extension-bear-notes#readme",
+  "bin": {
+    "bear-notes-mcp": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}