ai-bookmarks-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Bookmark Manager Authors
+
+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,63 @@
+# ai-bookmarks-mcp
+
+Model Context Protocol server that exposes your Chrome bookmarks to AI agents —
+Claude Desktop, [Antigravity](https://antigravity.google/), Cursor, Cline, or
+any other MCP client. Ask your agent to find bookmarks by topic, list your
+folder taxonomy, or look up a specific saved page.
+
+Companion to [AI Bookmark Manager](https://github.com/serguei9090/AI-Bookmark-Manager),
+a Chrome extension that tags, summarizes, and organizes bookmarks with AI —
+but this server works standalone: it reads Chrome's native `Bookmarks` file
+directly, no extension required.
+
+## Tools
+
+- **search_bookmarks** — keyword search across title/URL/summary/tags. If the
+  extension's "Semantic Search" toggle is on and bookmarks have been indexed
+  with the Local ONNX embedding provider, results are ranked by vector
+  similarity instead, so a query can match by *concept* rather than exact
+  words. Semantic scoring runs entirely locally (a small ONNX model,
+  downloaded and cached on first use) — no API key, no cloud calls.
+- **list_folders** — the full folder hierarchy and each folder's AI prompt
+  context.
+- **get_bookmark** — full details (tags, summary, dates) for one bookmark by
+  ID or URL.
+
+## Setup
+
+No installation needed — run it with `npx`:
+
+```json
+{
+  "mcpServers": {
+    "ai-bookmarks": {
+      "command": "npx",
+      "args": ["-y", "ai-bookmarks-mcp"]
+    }
+  }
+}
+```
+
+Paste that into:
+- **Claude Desktop**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Antigravity**: your user or project `mcp_config.json`
+- **Cursor / Cline**: your `mcp.json`
+
+By default it auto-detects your Chrome (or Edge/Brave) `Bookmarks` file. To
+point it at a specific file instead, set `BOOKMARKS_DATA_PATH`:
+
+```json
+{
+  "mcpServers": {
+    "ai-bookmarks": {
+      "command": "npx",
+      "args": ["-y", "ai-bookmarks-mcp"],
+      "env": { "BOOKMARKS_DATA_PATH": "C:\\path\\to\\Bookmarks" }
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Model Context Protocol (MCP) Server
+ *
+ * Exposes three primary tools for AI Assistants:
+ * 1. search_bookmarks (hybrid keyword and semantic vector search, when the
+ *    extension's semantic search toggle is on and bookmarks are indexed)
+ * 2. list_folders (returns taxonomy and promptContexts)
+ * 3. get_bookmark (retrieves tags, summary, and metadata by ID or URL)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const CHUNK_PREFIX = "bm_meta_v1_";
+const METADATA_FOLDER_NAME = ".ai_bookmark_metadata";
+/** Must match LOCAL_MODEL_ID in src/services/embeddingService.ts so query
+ * vectors and synced bookmark vectors live in the same embedding space. */
+const LOCAL_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+function getDefaultChromeBookmarksPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    const localAppData = process.env.LOCALAPPDATA || "";
+    const candidates = [
+        path.join(localAppData, "Google", "Chrome", "User Data", "Default", "Bookmarks"),
+        path.join(home, "Library", "Application Support", "Google", "Chrome", "Default", "Bookmarks"),
+        path.join(home, ".config", "google-chrome", "Default", "Bookmarks"),
+        path.join(localAppData, "Microsoft", "Edge", "User Data", "Default", "Bookmarks"),
+        path.join(localAppData, "BraveSoftware", "Brave-Browser", "User Data", "Default", "Bookmarks"),
+    ];
+    for (const p of candidates) {
+        if (p && fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+function parseChromeBookmarksFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const data = JSON.parse(raw);
+    let metadataFolder = null;
+    const findMetaFolder = (node) => {
+        if (node.type === "folder" && node.name === METADATA_FOLDER_NAME) {
+            metadataFolder = node;
+            return;
+        }
+        if (node.children) {
+            for (const child of node.children)
+                findMetaFolder(child);
+        }
+    };
+    for (const root of Object.values(data.roots || {})) {
+        findMetaFolder(root);
+    }
+    let syncedMeta = { bookmarks: {}, folders: {} };
+    if (metadataFolder && metadataFolder.children) {
+        const chunks = [];
+        for (const child of metadataFolder.children || []) {
+            if (child.name?.startsWith(CHUNK_PREFIX)) {
+                const headerEnd = child.name.indexOf(":::");
+                if (headerEnd !== -1) {
+                    const header = child.name.slice(0, headerEnd);
+                    const content = child.name.slice(headerEnd + 3);
+                    const parts = header.replace(CHUNK_PREFIX, "").split("_");
+                    const index = Number.parseInt(parts[0], 10);
+                    if (!Number.isNaN(index)) {
+                        chunks.push({ index, data: content });
+                    }
+                }
+            }
+        }
+        chunks.sort((a, b) => a.index - b.index);
+        const fullJson = chunks.map((c) => c.data).join("");
+        if (fullJson) {
+            try {
+                syncedMeta = JSON.parse(fullJson);
+            }
+            catch (e) {
+                console.error("[MCP] Error parsing shadow metadata:", e);
+            }
+        }
+    }
+    const bookmarksList = [];
+    const foldersList = [];
+    const traverse = (node, parentId) => {
+        if (node.name === METADATA_FOLDER_NAME)
+            return;
+        if (node.type === "folder") {
+            if (node.id !== "0") {
+                const meta = syncedMeta.folders[node.id] || {};
+                foldersList.push({
+                    id: node.id,
+                    parentId,
+                    name: node.name,
+                    promptContext: meta.promptContext || "",
+                });
+            }
+            if (node.children) {
+                for (const child of node.children)
+                    traverse(child, node.id);
+            }
+        }
+        else if (node.type === "url") {
+            const meta = syncedMeta.bookmarks[node.id] || {};
+            bookmarksList.push({
+                id: node.id,
+                title: node.name,
+                url: node.url || "",
+                folderId: parentId,
+                tags: meta.tags || [],
+                summary: meta.summary || "",
+                dateAdded: Number(node.date_added) || Date.now(),
+                embedding: meta.embedding,
+            });
+        }
+    };
+    for (const root of Object.values(data.roots || {})) {
+        traverse(root, null);
+    }
+    return {
+        bookmarks: bookmarksList,
+        folders: foldersList,
+        searchSettings: syncedMeta.searchSettings,
+    };
+}
+function loadBookmarkData() {
+    // 1. If an explicit file is specified, check if it's Chrome format or JSON export
+    const explicitPath = process.env.BOOKMARKS_DATA_PATH;
+    if (explicitPath && fs.existsSync(explicitPath)) {
+        try {
+            const raw = fs.readFileSync(explicitPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed.roots) {
+                return parseChromeBookmarksFile(explicitPath);
+            }
+            if (parsed.bookmarks && parsed.folders) {
+                return parsed;
+            }
+        }
+        catch (e) {
+            console.error("[MCP] Error reading explicit bookmarks data path:", e);
+        }
+    }
+    // 2. Local exported json file fallback (for development/testing)
+    const localExport = path.join(process.cwd(), "bookmarks-data.json");
+    if (fs.existsSync(localExport)) {
+        try {
+            const raw = fs.readFileSync(localExport, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch (e) {
+            console.error("[MCP] Error reading local bookmarks-data.json:", e);
+        }
+    }
+    // 3. Auto-detect native Chrome Bookmarks file (Zero configuration!)
+    const chromePath = getDefaultChromeBookmarksPath();
+    if (chromePath && fs.existsSync(chromePath)) {
+        try {
+            return parseChromeBookmarksFile(chromePath);
+        }
+        catch (e) {
+            console.error("[MCP] Error auto-parsing Chrome Bookmarks:", e);
+        }
+    }
+    return { bookmarks: [], folders: [] };
+}
+/** Cosine similarity between two equal-length float vectors. */
+function cosineSimilarity(a, b) {
+    if (!a || !b || a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+let localExtractorPromise = null;
+/**
+ * Lazily loads the local MiniLM model. MCP is called by external agents
+ * (Claude Desktop, Antigravity, Cursor, ...) that need a self-contained
+ * search tool — it deliberately never depends on the bookmark extension's
+ * own AI provider/API keys (those are for a separate concern: auto-sort and
+ * tagging). The query is always embedded locally, at no cost and no
+ * network dependency once this model is cached.
+ */
+function getLocalExtractor() {
+    if (!localExtractorPromise) {
+        localExtractorPromise = import("@huggingface/transformers").then(async ({ pipeline, env }) => {
+            env.allowLocalModels = false;
+            const extractor = await pipeline("feature-extraction", LOCAL_MODEL_ID);
+            return extractor;
+        });
+    }
+    return localExtractorPromise;
+}
+/**
+ * Embeds the search query locally so results can be scored against the
+ * bookmark vectors synced from the shadow folder. Returns null (never a
+ * fabricated vector) when semantic search is off or embedding fails, so
+ * callers fall back to plain keyword matching.
+ *
+ * Note: this only produces matches against bookmarks that were themselves
+ * indexed with the Local ONNX provider (384-dim, same model). Bookmarks
+ * indexed via the extension's Gemini provider (768-dim) won't line up with
+ * this query vector — they're excluded by the dimension check in the caller
+ * and fall back to keyword matching for those specific bookmarks.
+ */
+async function embedQueryIfEnabled(query, searchSettings) {
+    if (!searchSettings?.semanticSearchEnabled)
+        return null;
+    try {
+        const extractor = await getLocalExtractor();
+        const output = await extractor(query, { pooling: "mean", normalize: true });
+        return Array.from(output.data);
+    }
+    catch (e) {
+        console.error("[MCP] Local query embedding failed:", e);
+        return null;
+    }
+}
+const server = new Server({
+    name: "ai-bookmarks",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "search_bookmarks",
+                description: "Search bookmarks by keywords, concepts, tags, or summaries. Uses " +
+                    "semantic vector search (matching the embedding provider configured " +
+                    "in the extension) when semantic search is enabled there and " +
+                    "bookmarks have been indexed; otherwise falls back to keyword matching.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string", description: "Search query or topic" },
+                        limit: {
+                            type: "number",
+                            description: "Maximum results (default: 10)",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "list_folders",
+                description: "Lists all bookmark folders and their AI-organization prompt contexts.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "get_bookmark",
+                description: "Gets full details of a specific bookmark by ID or URL.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Bookmark ID or URL" },
+                    },
+                    required: ["id"],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const data = loadBookmarkData();
+    if (req.params.name === "list_folders") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.folders, null, 2),
+                },
+            ],
+        };
+    }
+    if (req.params.name === "get_bookmark") {
+        const id = String(req.params.arguments?.id || "");
+        const found = data.bookmarks.find((b) => b.id === id || b.url === id);
+        if (!found) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No bookmark found matching '${id}'`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(found, null, 2),
+                },
+            ],
+        };
+    }
+    if (req.params.name === "search_bookmarks") {
+        const rawQuery = String(req.params.arguments?.query || "");
+        const query = rawQuery.toLowerCase();
+        const limit = Number(req.params.arguments?.limit || 10);
+        const keywordMatch = (bm) => bm.title.toLowerCase().includes(query) ||
+            bm.url.toLowerCase().includes(query) ||
+            bm.summary.toLowerCase().includes(query) ||
+            bm.tags.some((t) => t.toLowerCase().includes(query));
+        const queryEmbedding = await embedQueryIfEnabled(rawQuery, data.searchSettings);
+        let matches;
+        if (queryEmbedding && queryEmbedding.length > 0) {
+            matches = data.bookmarks
+                .map((bm) => {
+                const keywordScore = keywordMatch(bm) ? 0.5 : 0;
+                const vectorScore = bm.embedding && bm.embedding.length === queryEmbedding.length
+                    ? Math.max(0, cosineSimilarity(queryEmbedding, bm.embedding))
+                    : 0;
+                return { bm, score: Math.max(keywordScore, vectorScore) };
+            })
+                .filter((item) => item.score > 0.15)
+                .sort((a, b) => b.score - a.score)
+                .map((item) => item.bm);
+        }
+        else {
+            matches = data.bookmarks.filter(keywordMatch);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(matches.slice(0, limit), null, 2),
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Unknown tool: ${req.params.name}`,
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("AI Bookmarks MCP server running via stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error in MCP server:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "ai-bookmarks-mcp",
+	"version": "1.0.0",
+	"description": "Model Context Protocol server exposing your Chrome bookmarks (keyword + local semantic vector search) to AI agents like Claude Desktop, Antigravity, Cursor, and Cline.",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/serguei9090/AI-Bookmark-Manager.git",
+		"directory": "mcp-server"
+	},
+	"homepage": "https://github.com/serguei9090/AI-Bookmark-Manager#readme",
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"bookmarks",
+		"chrome-bookmarks",
+		"semantic-search",
+		"claude"
+	],
+	"files": [
+		"dist"
+	],
+	"bin": {
+		"ai-bookmarks-mcp": "./dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"start": "node dist/index.js"
+	},
+	"dependencies": {
+		"@huggingface/transformers": "^4.2.0",
+		"@modelcontextprotocol/sdk": "^1.5.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.14.0",
+		"typescript": "^5.8.2"
+	}
+}