karma365-mcp 2.0.0 → 2.1.0

package/index.js

@@ -1,1446 +1,1795 @@
-#!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-import crypto from 'node:crypto'
-
-// ── Database connection & Auto-detect ─────────────────────────────────────────
-
-function autoDetectDbPath() {
-  if (process.env.KARMA365_DB && process.env.KARMA365_DB.trim()) {
-    const custom = path.resolve(process.env.KARMA365_DB.trim())
-    const dir = path.dirname(custom)
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
-    return custom
-  }
-
-  const home = os.homedir()
-  const candidates = [
-    // Windows AppData standard
-    process.env.APPDATA ? path.join(process.env.APPDATA, 'karma365', 'karma365.db') : null,
-    // macOS standard
-    path.join(home, 'Library', 'Application Support', 'com.karma365.app', 'karma365.db'),
-    // Linux standard
-    path.join(home, '.local', 'share', 'karma365', 'karma365.db'),
-    // Standard cross-platform hidden folder
-    path.join(home, '.karma365', 'karma365.db'),
-    // Current working directory (if user runs from repo/project folder)
-    path.join(process.cwd(), 'karma365.db'),
-  ].filter(Boolean)
-
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) return candidate
-  }
-
-  // Fallback: create default ~/.karma365/karma365.db
-  const defaultPath = path.join(home, '.karma365', 'karma365.db')
-  const dir = path.dirname(defaultPath)
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
-  return defaultPath
-}
-
-const DB_PATH = autoDetectDbPath()
-process.stderr.write(`[karma365-mcp] Using SQLite database: ${DB_PATH}\n`)
-
-let DatabaseSync
-try {
-  const mod = await import('node:sqlite')
-  DatabaseSync = mod.DatabaseSync
-} catch (_) {
-  try {
-    const mod = await import('better-sqlite3')
-    DatabaseSync = mod.default
-  } catch (err) {
-    process.stderr.write('ERROR: SQLite support requires Node 22.5+ (node:sqlite) or better-sqlite3.\n')
-    process.exit(1)
-  }
-}
-
-const db = new DatabaseSync(DB_PATH)
-db.exec('PRAGMA foreign_keys = ON;')
-
-// Initialize schema if not present
-db.exec(`
-  CREATE TABLE IF NOT EXISTS major_topics (
-    id TEXT PRIMARY KEY,
-    name TEXT NOT NULL,
-    color TEXT,
-    note TEXT,
-    note_title TEXT,
-    created_at TEXT NOT NULL,
-    is_pinned INTEGER NOT NULL DEFAULT 0,
-    is_starred INTEGER NOT NULL DEFAULT 0,
-    sort_order INTEGER NOT NULL DEFAULT 0,
-    synced INTEGER NOT NULL DEFAULT 0
-  );
-
-  CREATE TABLE IF NOT EXISTS topics (
-    id TEXT PRIMARY KEY,
-    name TEXT NOT NULL,
-    difficulty TEXT CHECK (difficulty IN ('Easy','Medium','Hard')),
-    color TEXT,
-    major_topic_id TEXT REFERENCES major_topics(id) ON DELETE SET NULL,
-    parent_topic_id TEXT REFERENCES topics(id) ON DELETE SET NULL,
-    note TEXT,
-    note_title TEXT,
-    created_at TEXT NOT NULL,
-    updated_at TEXT,
-    last_opened TEXT,
-    visit_count INTEGER NOT NULL DEFAULT 0,
-    is_pinned INTEGER NOT NULL DEFAULT 0,
-    is_starred INTEGER NOT NULL DEFAULT 0,
-    sort_order INTEGER NOT NULL DEFAULT 0,
-    synced INTEGER NOT NULL DEFAULT 0
-  );
-
-  CREATE TABLE IF NOT EXISTS resources (
-    id TEXT PRIMARY KEY,
-    topic_id TEXT NOT NULL REFERENCES topics(id) ON DELETE CASCADE,
-    type TEXT NOT NULL,
-    description TEXT NOT NULL DEFAULT '',
-    path_or_url TEXT NOT NULL,
-    original_filename TEXT,
-    youtube_video_id TEXT,
-    thumbnail_path TEXT,
-    is_completed INTEGER NOT NULL DEFAULT 0,
-    is_pinned INTEGER NOT NULL DEFAULT 0,
-    is_starred INTEGER NOT NULL DEFAULT 0,
-    sort_order INTEGER NOT NULL DEFAULT 0,
-    notes TEXT,
-    created_at TEXT,
-    synced INTEGER NOT NULL DEFAULT 0
-  );
-
-  CREATE TABLE IF NOT EXISTS todos (
-    id TEXT PRIMARY KEY,
-    name TEXT NOT NULL,
-    priority TEXT NOT NULL CHECK (priority IN ('high','medium','low')) DEFAULT 'medium',
-    is_completed INTEGER NOT NULL DEFAULT 0,
-    notes TEXT,
-    created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL
-  );
-
-  CREATE TABLE IF NOT EXISTS settings (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_topics_major ON topics(major_topic_id);
-  CREATE INDEX IF NOT EXISTS idx_topics_parent ON topics(parent_topic_id);
-  CREATE INDEX IF NOT EXISTS idx_resources_topic ON resources(topic_id);
-`)
-
-// Helpers
-function newId() { return crypto.randomUUID() }
-function nowIso() { return new Date().toISOString() }
-
-function isUuid(s) {
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(s || ''))
-}
-
-const COLOR_MAP = {
-  red: '#ef4444', laal: '#ef4444', lal: '#ef4444',
-  blue: '#3b82f6', neela: '#3b82f6', nilo: '#3b82f6',
-  green: '#22c55e', hara: '#22c55e', hario: '#22c55e',
-  yellow: '#eab308', peela: '#eab308', pilo: '#eab308',
-  purple: '#a855f7', jambli: '#a855f7',
-  pink: '#ec4899', gulabi: '#ec4899',
-  orange: '#f97316', narangi: '#f97316',
-  teal: '#14b8a6', indigo: '#6366f1', violet: '#8b5cf6',
-  gray: '#6b7280', grey: '#6b7280', coral: '#f87171',
-  navy: '#1e3a8a', rose: '#f43f5e', amber: '#f59e0b',
-}
-
-function resolveColor(c) {
-  if (!c) return null
-  const s = String(c).trim()
-  if (/^#?[0-9a-f]{6}$/i.test(s)) return s.startsWith('#') ? s : `#${s}`
-  return COLOR_MAP[s.toLowerCase()] || s
-}
-
-function cleanName(s) {
-  return ` ${String(s).toLowerCase().trim()} `
-    .replace(/\bsub[- ]?topics?\b/g, ' ')
-    .replace(/\b(major|minor)\b/g, ' ')
-    .replace(/\btopics?\b/g, ' ')
-    .replace(/\bcategor(?:y|ies)\b/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-}
-
-function findByName(items, nameOrId) {
-  const lower = String(nameOrId).toLowerCase().trim()
-  const cleaned = cleanName(nameOrId)
-  return items.find(x => x.name.toLowerCase() === lower)
-    || (cleaned && items.find(x => x.name.toLowerCase() === cleaned))
-    || (cleaned && items.find(x => x.name.toLowerCase().includes(cleaned)))
-    || (lower && items.find(x => x.name.toLowerCase().includes(lower)))
-    || null
-}
-
-function resolveTopic(nameOrId) {
-  if (isUuid(nameOrId)) {
-    const row = db.prepare('SELECT * FROM topics WHERE id = ?').get(nameOrId)
-    if (row) return row
-  }
-  const all = db.prepare('SELECT * FROM topics').all()
-  const found = findByName(all, nameOrId)
-  if (!found) throw new Error(`Topic not found: "${nameOrId}"`)
-  return found
-}
-
-function resolveMajorTopic(nameOrId) {
-  if (isUuid(nameOrId)) {
-    const row = db.prepare('SELECT * FROM major_topics WHERE id = ?').get(nameOrId)
-    if (row) return row
-  }
-  const all = db.prepare('SELECT * FROM major_topics').all()
-  const found = findByName(all, nameOrId)
-  if (!found) throw new Error(`Major topic not found: "${nameOrId}"`)
-  return found
-}
-
-function resolveTodo(nameOrId) {
-  if (isUuid(nameOrId)) {
-    const row = db.prepare('SELECT * FROM todos WHERE id = ?').get(nameOrId)
-    if (row) return row
-  }
-  const all = db.prepare('SELECT * FROM todos').all()
-  const found = all.find(t => t.name.toLowerCase() === String(nameOrId).toLowerCase().trim())
-  if (!found) throw new Error(`Todo not found: "${nameOrId}"`)
-  return found
-}
-
-// ── Search helpers (DuckDuckGo / SearXNG / YouTube) ───────────────────────────
-
-const SEARCH_UA = 'Mozilla/5.0 (compatible; KarmaSearch/2.0)'
-
-async function fetchWithTimeout(url, opts = {}, ms = 8000) {
-  const ctrl = new AbortController()
-  const t = setTimeout(() => ctrl.abort(), ms)
-  try {
-    return await fetch(url, { ...opts, signal: ctrl.signal })
-  } finally {
-    clearTimeout(t)
-  }
-}
-
-async function searchWebKeyless(query) {
-  const searx = [
-    'https://searx.be',
-    'https://searxng.world',
-    'https://search.mdosch.de',
-    'https://searx.tiekoetter.com',
-  ]
-  for (const base of searx) {
-    try {
-      const res = await fetchWithTimeout(
-        `${base}/search?q=${encodeURIComponent(query)}&format=json&categories=general&language=en-US`,
-        { headers: { 'User-Agent': SEARCH_UA, 'Accept': 'application/json' } })
-      if (!res.ok) continue
-      const data = await res.json()
-      const items = (data.results || [])
-        .filter(r => r.url && String(r.url).startsWith('http') && r.title)
-        .slice(0, 5)
-        .map(r => ({ title: String(r.title).trim(), url: String(r.url).trim(),
-          snippet: String(r.content || '').slice(0, 200) }))
-      if (items.length) return items
-    } catch { /* try next */ }
-  }
-
-  // DuckDuckGo Instant Answer fallback
-  try {
-    const res = await fetchWithTimeout(
-      `https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_html=1&skip_disambig=1`,
-      {}, 6000)
-    if (res.ok) {
-      const data = await res.json()
-      const out = []
-      if (data.AbstractText && data.AbstractURL) {
-        out.push({ title: data.Heading || query, url: data.AbstractURL,
-          snippet: String(data.AbstractText).slice(0, 200) })
-      }
-      for (const it of (data.RelatedTopics || []).slice(0, 4)) {
-        if (it.FirstURL && it.Text) {
-          out.push({ title: String(it.Text).slice(0, 100), url: it.FirstURL, snippet: '' })
-        }
-      }
-      if (out.length) return out
-    }
-  } catch { /* ignore */ }
-
-  return [{ title: `Search: ${query}`,
-    url: `https://duckduckgo.com/?q=${encodeURIComponent(query)}`,
-    snippet: `Web results for "${query}"` }]
-}
-
-async function searchYouTubeKeyless(query, maxResults = 3) {
-  const max = Math.max(1, Math.min(5, maxResults || 3))
-  const piped = [
-    'https://pipedapi.kavin.rocks',
-    'https://pipedapi.adminforge.de',
-    'https://api-piped.mha.fi',
-  ]
-  for (const base of piped) {
-    try {
-      const res = await fetchWithTimeout(
-        `${base}/search?q=${encodeURIComponent(query)}&filter=videos`,
-        { headers: { 'User-Agent': SEARCH_UA, 'Accept': 'application/json' } })
-      if (!res.ok) continue
-      const data = await res.json()
-      const items = (data.items || data || [])
-        .filter(v => v && (v.url || v.id))
-        .slice(0, max)
-        .map(v => {
-          const id = v.url ? String(v.url).split('v=')[1] : v.id
-          return { title: (v.title || 'YouTube video').trim(),
-            url: `https://www.youtube.com/watch?v=${id}` }
-        })
-        .filter(v => v.url.includes('watch?v=') && v.url.split('v=')[1])
-      if (items.length) return items
-    } catch { /* try next */ }
-  }
-
-  // Scrape the results page
-  try {
-    const res = await fetchWithTimeout(
-      `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}`,
-      { headers: { 'User-Agent': SEARCH_UA } })
-    if (res.ok) {
-      const html = await res.text()
-      const out = []
-      const seen = new Set()
-      const re = /"videoRenderer":\{"videoId":"([\w-]{11})".*?"text":"([^"]+)"/g
-      let m
-      while ((m = re.exec(html)) && out.length < max) {
-        if (seen.has(m[1])) continue
-        seen.add(m[1])
-        out.push({ title: m[2], url: `https://www.youtube.com/watch?v=${m[1]}` })
-      }
-      if (out.length) return out
-    }
-  } catch { /* ignore */ }
-
-  return [{ title: `YouTube: ${query}`,
-    url: `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}` }]
-}
-
-// ── MCP Tool Definitions ──────────────────────────────────────────────────────
-
-const TOOLS = [
-  {
-    name: 'list_major_topics',
-    description: 'List all major topic categories in KARMA 365',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'create_major_topic',
-    description: 'Create a new major topic category in KARMA 365',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name:      { type: 'string', description: 'Name of the major topic' },
-        is_pinned: { type: 'boolean', description: 'Whether to pin this major topic' }
-      }
-    }
-  },
-  {
-    name: 'delete_major_topic',
-    description: 'Delete a major topic by name or ID (topics under it stay but lose their category).',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name: { type: 'string', description: 'Major topic name or ID' },
-        pin:  { type: 'string', description: 'Optional PIN if locked' }
-      }
-    }
-  },
-  {
-    name: 'list_topics',
-    description: 'List topics in KARMA 365, optionally filtered by major topic, difficulty, or parent topic',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        major_topic_name:  { type: 'string', description: 'Filter by major topic name' },
-        difficulty:        { type: 'string', enum: ['Easy', 'Medium', 'Hard'] },
-        parent_topic_name: { type: 'string', description: 'List subtopics of this topic' }
-      }
-    }
-  },
-  {
-    name: 'get_topic',
-    description: 'Get full details of a topic including all its resources',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name: { type: 'string', description: 'Topic name or ID' }
-      }
-    }
-  },
-  {
-    name: 'create_topic',
-    description: 'Create a new topic in KARMA 365',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name:             { type: 'string', description: 'Topic name' },
-        difficulty:       { type: 'string', enum: ['Easy', 'Medium', 'Hard'] },
-        major_topic_name: { type: 'string', description: 'Assign to this major topic' },
-        color:            { type: 'string', description: 'Hex color code e.g. #FF5733' }
-      }
-    }
-  },
-  {
-    name: 'create_subtopic',
-    description: 'Create a subtopic under an existing topic',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'parent_topic_name'],
-      properties: {
-        name:              { type: 'string', description: 'Subtopic name' },
-        parent_topic_name: { type: 'string', description: 'Parent topic name or ID' },
-        difficulty:        { type: 'string', enum: ['Easy', 'Medium', 'Hard'] }
-      }
-    }
-  },
-  {
-    name: 'delete_topic',
-    description: 'Delete a topic and all its resources permanently.',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name: { type: 'string', description: 'Topic name or ID' },
-        pin:  { type: 'string', description: 'Optional PIN if locked' }
-      }
-    }
-  },
-  {
-    name: 'list_resources',
-    description: 'List all resources attached to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name'],
-      properties: {
-        topic_name: { type: 'string', description: 'Topic name or ID' },
-        type:       { type: 'string', enum: ['pdf', 'video', 'youtube', 'link', 'audio', 'image', 'code'] }
-      }
-    }
-  },
-  {
-    name: 'add_youtube',
-    description: 'Add a YouTube video link to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'url', 'description'],
-      properties: {
-        topic_name:  { type: 'string' },
-        url:         { type: 'string', description: 'YouTube URL' },
-        description: { type: 'string', description: 'Label for this resource' }
-      }
-    }
-  },
-  {
-    name: 'add_link',
-    description: 'Add a web link to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'url', 'description'],
-      properties: {
-        topic_name:  { type: 'string' },
-        url:         { type: 'string' },
-        description: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'add_pdf',
-    description: 'Add a PDF resource (URL or local file path) to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'url', 'description'],
-      properties: {
-        topic_name:  { type: 'string' },
-        url:         { type: 'string', description: 'http(s) URL or local file path' },
-        description: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'add_audio',
-    description: 'Add an audio resource (URL or local file path) to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'url', 'description'],
-      properties: {
-        topic_name:  { type: 'string' },
-        url:         { type: 'string', description: 'http(s) URL or local file path' },
-        description: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'add_video',
-    description: 'Add a video resource (URL or local file path) to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'url', 'description'],
-      properties: {
-        topic_name:  { type: 'string' },
-        url:         { type: 'string', description: 'http(s) URL or local file path' },
-        description: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'add_image',
-    description: 'Add an image resource (URL or local file path) to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'url', 'description'],
-      properties: {
-        topic_name:  { type: 'string' },
-        url:         { type: 'string', description: 'http(s) URL or local file path' },
-        description: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'add_code',
-    description: 'Add a code file resource (URL or local file path) to a topic',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'url', 'description'],
-      properties: {
-        topic_name:  { type: 'string' },
-        url:         { type: 'string', description: 'http(s) URL or local file path' },
-        description: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'delete_resource',
-    description: 'Delete a resource by its ID.',
-    inputSchema: {
-      type: 'object',
-      required: ['resource_id'],
-      properties: {
-        resource_id: { type: 'string', description: 'Resource UUID' },
-        pin:         { type: 'string', description: 'Optional PIN if locked' }
-      }
-    }
-  },
-  {
-    name: 'mark_resource_complete',
-    description: 'Mark a resource as studied/complete (or revert to incomplete)',
-    inputSchema: {
-      type: 'object',
-      required: ['resource_id', 'is_completed'],
-      properties: {
-        resource_id:  { type: 'string' },
-        is_completed: { type: 'boolean' }
-      }
-    }
-  },
-  {
-    name: 'write_topic_note',
-    description: 'Write, add, or append notes/text into a topic note',
-    inputSchema: {
-      type: 'object',
-      required: ['topic_name', 'note'],
-      properties: {
-        topic_name: { type: 'string' },
-        note:       { type: 'string' },
-        title:      { type: 'string', description: 'Optional note title' },
-        pin:        { type: 'string', description: 'Optional PIN if locked' }
-      }
-    }
-  },
-  {
-    name: 'list_todos',
-    description: 'List all todos in KARMA 365, optionally filtered by priority or completion',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        priority:     { type: 'string', enum: ['high', 'medium', 'low'] },
-        is_completed: { type: 'boolean' }
-      }
-    }
-  },
-  {
-    name: 'create_todo',
-    description: 'Create a new task/todo in KARMA 365',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name:     { type: 'string' },
-        priority: { type: 'string', enum: ['high', 'medium', 'low'], description: 'Defaults to medium' },
-        notes:    { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'complete_todo',
-    description: 'Mark a todo as done',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name: { type: 'string', description: 'Todo name or ID' }
-      }
-    }
-  },
-  {
-    name: 'update_todo',
-    description: 'Update a todo\'s name, priority, notes or completion status',
-    inputSchema: {
-      type: 'object',
-      required: ['id'],
-      properties: {
-        id:           { type: 'string', description: 'Todo ID' },
-        name:         { type: 'string' },
-        priority:     { type: 'string', enum: ['high', 'medium', 'low'] },
-        notes:        { type: 'string' },
-        is_completed: { type: 'boolean' }
-      }
-    }
-  },
-  {
-    name: 'delete_todo',
-    description: 'Delete a todo by name or ID',
-    inputSchema: {
-      type: 'object',
-      required: ['name'],
-      properties: {
-        name: { type: 'string', description: 'Todo name or ID' }
-      }
-    }
-  },
-  {
-    name: 'star_topic',
-    description: 'Star (favourite) or unstar a topic/subtopic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'starred'],
-      properties: {
-        name:    { type: 'string', description: 'Topic name or ID' },
-        starred: { type: 'boolean', description: 'true = add to favourites, false = remove' }
-      }
-    }
-  },
-  {
-    name: 'star_major_topic',
-    description: 'Star (favourite) or unstar a major topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'starred'],
-      properties: {
-        name:    { type: 'string', description: 'Major topic name or ID' },
-        starred: { type: 'boolean', description: 'true = add to favourites, false = remove' }
-      }
-    }
-  },
-  {
-    name: 'pin_major_topic',
-    description: 'Pin (lock) or unpin a major topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'pinned'],
-      properties: {
-        name:   { type: 'string', description: 'Major topic name or ID' },
-        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' }
-      }
-    }
-  },
-  {
-    name: 'pin_topic',
-    description: 'Pin (lock) or unpin a topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'pinned'],
-      properties: {
-        name:   { type: 'string', description: 'Topic name or ID' },
-        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' }
-      }
-    }
-  },
-  {
-    name: 'set_major_topic_color',
-    description: 'Change the colour of a major topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'color'],
-      properties: {
-        name:  { type: 'string', description: 'Major topic name or ID' },
-        color: { type: 'string', description: 'Hex colour or color name' }
-      }
-    }
-  },
-  {
-    name: 'set_topic_color',
-    description: 'Change the colour of a topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'color'],
-      properties: {
-        name:  { type: 'string', description: 'Topic name or ID' },
-        color: { type: 'string', description: 'Hex colour or color name' }
-      }
-    }
-  },
-  {
-    name: 'rename_major_topic',
-    description: 'Rename a major topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'new_name'],
-      properties: {
-        name:     { type: 'string', description: 'CURRENT major topic name or ID' },
-        new_name: { type: 'string', description: 'The NEW name' }
-      }
-    }
-  },
-  {
-    name: 'rename_topic',
-    description: 'Rename a topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['name', 'new_name'],
-      properties: {
-        name:     { type: 'string', description: 'CURRENT topic name or ID' },
-        new_name: { type: 'string', description: 'The NEW name' }
-      }
-    }
-  },
-  {
-    name: 'delete_completed_todos',
-    description: 'Delete ALL completed todos/tasks at once.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'clean_empty_major_topics',
-    description: 'Delete all major topics that have no resources in any of their subtopics.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'get_stats',
-    description: 'Get KARMA 365 dashboard statistics: topic counts, resource completion, todos',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'search',
-    description: 'Search across all topics, resources, and todos by keyword',
-    inputSchema: {
-      type: 'object',
-      required: ['query'],
-      properties: {
-        query: { type: 'string', description: 'Search keyword' }
-      }
-    }
-  },
-  {
-    name: 'set_dark_mode',
-    description: 'Turn the KARMA 365 app dark mode ON or OFF.',
-    inputSchema: {
-      type: 'object',
-      required: ['enabled'],
-      properties: {
-        enabled: { type: 'boolean', description: 'true = dark mode ON, false = light mode' }
-      }
-    }
-  },
-  {
-    name: 'search_web',
-    description: 'Search the public web for articles/pages by keyword (KEYLESS). Optionally save the results as link resources to a topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['query'],
-      properties: {
-        query:      { type: 'string', description: 'Web search query' },
-        topic_name: { type: 'string', description: 'If given, save the results as link resources to this topic' }
-      }
-    }
-  },
-  {
-    name: 'search_youtube',
-    description: 'Search YouTube for real videos by keyword (KEYLESS). Optionally save results to a topic.',
-    inputSchema: {
-      type: 'object',
-      required: ['query'],
-      properties: {
-        query:       { type: 'string', description: 'YouTube search query' },
-        topic_name:  { type: 'string', description: 'If given, save the found videos to this topic' },
-        max_results: { type: 'number', description: 'Number of videos to fetch (default 3, max 5)' }
-      }
-    }
-  }
-]
-
-// ── Phone Live Bridge Setup & Auto-Discovery (Wi-Fi, Hotspot, USB) ─────────
-const EXPLICIT_PHONE_URL = process.env.KARMA365_PHONE_URL ? process.env.KARMA365_PHONE_URL.trim().replace(/\/+$/, '') : null
-const KARMA_TOKEN = process.env.KARMA365_TOKEN ? process.env.KARMA365_TOKEN.trim() : null
-const PHONE_CACHE_FILE = path.join(os.homedir(), '.karma365', 'last_phone_url.txt')
-
-let activePhoneUrl = EXPLICIT_PHONE_URL || readCachedPhoneUrl()
-let isDiscoveryRunning = false
-let lastDiscoveryTime = 0
-
-function readCachedPhoneUrl() {
-  try {
-    if (fs.existsSync(PHONE_CACHE_FILE)) {
-      const u = fs.readFileSync(PHONE_CACHE_FILE, 'utf-8').trim()
-      if (u && u.startsWith('http')) return u
-    }
-  } catch (_) {}
-  return null
-}
-
-function writeCachedPhoneUrl(url) {
-  try {
-    const d = path.dirname(PHONE_CACHE_FILE)
-    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true })
-    fs.writeFileSync(PHONE_CACHE_FILE, url, 'utf-8')
-  } catch (_) {}
-}
-
-async function probePhoneHealth(baseUrl, timeoutMs = 600) {
-  try {
-    const res = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(timeoutMs) })
-    if (!res.ok) return false
-    const d = await res.json()
-    return d && d.app === 'karma365'
-  } catch (_) {
-    return false
-  }
-}
-
-async function autoDiscoverPhone(force = false) {
-  if (EXPLICIT_PHONE_URL) return EXPLICIT_PHONE_URL
-  const now = Date.now()
-  if (!force && activePhoneUrl && (now - lastDiscoveryTime < 15000)) {
-    return activePhoneUrl
-  }
-  if (isDiscoveryRunning) return activePhoneUrl
-  isDiscoveryRunning = true
-  lastDiscoveryTime = now
-
-  try {
-    // 1. Check cached URL, localhost (USB adb forward), or Android hotspot default gateway
-    const quickCandidates = [
-      activePhoneUrl,
-      'http://127.0.0.1:8365',
-      'http://192.168.43.1:8365',
-    ].filter(Boolean)
-
-    for (const url of quickCandidates) {
-      if (await probePhoneHealth(url, 350)) {
-        activePhoneUrl = url
-        writeCachedPhoneUrl(url)
-        process.stderr.write(`[karma365-mcp] 📱 Connected to KARMA 365 Mobile App: ${url}\n`)
-        return url
-      }
-    }
-
-    // 2. Fast parallel sweep across active PC network interfaces
-    const nets = os.networkInterfaces()
-    const subnets = new Set()
-    for (const name of Object.keys(nets)) {
-      for (const net of nets[name] || []) {
-        if (net.family === 'IPv4' && !net.internal) {
-          const parts = net.address.split('.')
-          if (parts.length === 4) {
-            subnets.add(`${parts[0]}.${parts[1]}.${parts[2]}.`)
-          }
-        }
-      }
-    }
-
-    const checks = []
-    for (const subnet of subnets) {
-      for (let i = 1; i <= 254; i++) {
-        const url = `http://${subnet}${i}:8365`
-        checks.push(
-          probePhoneHealth(url, 650)
-            .then(ok => (ok ? url : null))
-            .catch(() => null)
-        )
-      }
-    }
-
-    if (checks.length > 0) {
-      const results = await Promise.all(checks)
-      const found = results.find(Boolean)
-      if (found) {
-        activePhoneUrl = found
-        writeCachedPhoneUrl(found)
-        process.stderr.write(`[karma365-mcp] 📱 Auto-Discovered KARMA 365 Mobile App: ${found}\n`)
-        return found
-      }
-    }
-  } catch (e) {
-    process.stderr.write(`[karma365-mcp] Auto-discovery warning: ${e.message}\n`)
-  } finally {
-    isDiscoveryRunning = false
-  }
-
-  return activePhoneUrl
-}
-
-if (EXPLICIT_PHONE_URL) {
-  process.stderr.write(`[karma365-mcp] Phone Live Bridge Configured: ${EXPLICIT_PHONE_URL} (Token: ${KARMA_TOKEN ? 'Present' : 'None'})\n`)
-} else {
-  process.stderr.write(`[karma365-mcp] Auto-Discovery Enabled (searching on :8365, local SQLite fallback: ${DB_PATH})\n`)
-}
-
-async function callPhoneBridge(name, args) {
-  let targetBase = activePhoneUrl || (await autoDiscoverPhone())
-  if (!targetBase) return null
-
-  const targetUrl = `${targetBase}/api/execute`
-  const isLargePayload = args && args.url && String(args.url).length > 50000
-  const timeoutMs = isLargePayload ? 60000 : 8000
-  const controller = new AbortController()
-  const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
-
-  try {
-    const headers = { 'Content-Type': 'application/json' }
-    if (KARMA_TOKEN) {
-      headers['X-Karma-Token'] = KARMA_TOKEN
-    }
-
-    const res = await fetch(targetUrl, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify({ name, args }),
-      signal: controller.signal,
-    })
-    clearTimeout(timeoutId)
-
-    if (res.status === 401) {
-      const data = await res.json().catch(() => ({}))
-      throw new Error(`Phone Authentication Failed (401): ${data.error || 'Invalid or missing KARMA365_TOKEN'}. Check your pairing token in Karma 365 app settings.`)
-    }
-
-    if (!res.ok) {
-      const data = await res.json().catch(() => ({}))
-      throw new Error(`Phone returned status ${res.status}: ${data.error || res.statusText}`)
-    }
-
-    const data = await res.json()
-    if (data.success === false) {
-      throw new Error(data.error || 'Execution failed on mobile app')
-    }
-
-    return data.result
-  } catch (err) {
-    clearTimeout(timeoutId)
-    if (err.message && err.message.includes('401')) {
-      throw err
-    }
-    process.stderr.write(`[karma365-mcp] Phone bridge unreachable at ${targetBase} (${err.message}). Checking auto-discovery or local SQLite...\n`)
-
-    // Try one quick re-discovery if the phone's IP changed on Wi-Fi
-    const rediscovered = await autoDiscoverPhone(true)
-    if (rediscovered && rediscovered !== targetBase) {
-      process.stderr.write(`[karma365-mcp] Retrying request on new phone IP: ${rediscovered}\n`)
-      activePhoneUrl = rediscovered
-      return callPhoneBridge(name, args)
-    }
-
-    activePhoneUrl = null
-    return null
-  }
-}
-
-async function handleTool(name, args) {
-  // If Phone Live Bridge is active or auto-discovered, delegate directly to phone app
-  const phoneUrl = activePhoneUrl || (await autoDiscoverPhone())
-  if (phoneUrl && name !== 'search_web' && name !== 'search_youtube') {
-    let argsToSend = { ...args }
-    if (['add_image', 'add_pdf', 'add_audio', 'add_video', 'add_code'].includes(name) && argsToSend.url) {
-      const localPath = String(argsToSend.url).trim()
-      if (fs.existsSync(localPath)) {
-        try {
-          const ext = path.extname(localPath).toLowerCase()
-          const mimeMap = {
-            '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp',
-            '.pdf': 'application/pdf',
-            '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/m4a',
-            '.mp4': 'video/mp4', '.mov': 'video/quicktime',
-          }
-          const mime = mimeMap[ext] || 'application/octet-stream'
-          const fileBytes = fs.readFileSync(localPath)
-          argsToSend.url = `data:${mime};base64,${fileBytes.toString('base64')}`
-          if (!argsToSend.description && !argsToSend.title) {
-            argsToSend.description = path.basename(localPath)
-          }
-        } catch (e) {
-          process.stderr.write(`[karma365-mcp] Failed to read local file ${localPath}: ${e.message}\n`)
-        }
-      }
-    }
-    const phoneResult = await callPhoneBridge(name, argsToSend)
-    if (phoneResult !== null && phoneResult !== undefined) {
-      if (typeof phoneResult === 'string') return phoneResult
-      return JSON.stringify(phoneResult, null, 2)
-    }
-  }
-
-  switch (name) {
-
-    case 'set_dark_mode': {
-      const enabled = args.enabled === true || String(args.enabled).toLowerCase() === 'true'
-      const val = enabled ? 'true' : 'false'
-      db.prepare(`INSERT INTO settings (key, value) VALUES ('dark_mode', ?)
-                  ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(val)
-      return enabled
-        ? '✓ Dark mode turned ON 🌙 (saved to local settings)'
-        : '✓ Dark mode turned OFF — light mode ☀️ (saved to local settings)'
-    }
-
-    case 'list_major_topics': {
-      const rows = db.prepare('SELECT * FROM major_topics ORDER BY sort_order ASC, created_at DESC').all()
-      if (!rows.length) return 'No major topics found. Create one with create_major_topic.'
-      return `Found ${rows.length} major topic(s):\n` +
-        rows.map(m => `• ${m.name}${m.color ? ` [${m.color}]` : ''}${m.is_pinned ? ' 🔒' : ''}${m.is_starred ? ' ⭐' : ''} (ID: ${m.id})`).join('\n')
-    }
-
-    case 'create_major_topic': {
-      const id = newId()
-      const isPinned = args.is_pinned ? 1 : 0
-      db.prepare(`INSERT INTO major_topics (id, name, is_pinned, is_starred, sort_order, created_at, synced)
-                  VALUES (?, ?, ?, 0, 0, ?, 1)`).run(id, args.name.trim(), isPinned, nowIso())
-      return `✓ Created major topic "${args.name}" (ID: ${id})`
-    }
-
-    case 'delete_major_topic': {
-      const item = resolveMajorTopic(args.name)
-      db.prepare('UPDATE topics SET major_topic_id = NULL WHERE major_topic_id = ?').run(item.id)
-      db.prepare('DELETE FROM major_topics WHERE id = ?').run(item.id)
-      return `✓ Deleted major topic "${item.name}". Subtopics under it have been kept.`
-    }
-
-    case 'rename_major_topic': {
-      const item = resolveMajorTopic(args.name)
-      const newName = args.new_name.trim()
-      db.prepare('UPDATE major_topics SET name = ? WHERE id = ?').run(newName, item.id)
-      return `✓ Renamed major topic from "${item.name}" to "${newName}"`
-    }
-
-    case 'set_major_topic_color': {
-      const item = resolveMajorTopic(args.name)
-      const color = resolveColor(args.color)
-      db.prepare('UPDATE major_topics SET color = ? WHERE id = ?').run(color, item.id)
-      return `✓ Changed colour of major topic "${item.name}" to ${color}`
-    }
-
-    case 'pin_major_topic': {
-      const item = resolveMajorTopic(args.name)
-      const pinned = args.pinned === true || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
-      db.prepare('UPDATE major_topics SET is_pinned = ? WHERE id = ?').run(pinned, item.id)
-      return pinned ? `✓ Locked/pinned major topic "${item.name}" 🔒` : `✓ Unlocked major topic "${item.name}"`
-    }
-
-    case 'star_major_topic': {
-      const item = resolveMajorTopic(args.name)
-      const starred = args.starred === true || String(args.starred).toLowerCase() === 'true' ? 1 : 0
-      db.prepare('UPDATE major_topics SET is_starred = ? WHERE id = ?').run(starred, item.id)
-      return starred ? `✓ Added major topic "${item.name}" to favourites ⭐` : `✓ Removed major topic "${item.name}" from favourites`
-    }
-
-    case 'list_topics': {
-      let query = `SELECT t.*, m.name as major_name
-                   FROM topics t
-                   LEFT JOIN major_topics m ON t.major_topic_id = m.id
-                   WHERE 1=1`
-      const params = []
-
-      if (args.major_topic_name) {
-        const m = resolveMajorTopic(args.major_topic_name)
-        query += ' AND t.major_topic_id = ?'
-        params.push(m.id)
-      }
-      if (args.difficulty) {
-        query += ' AND t.difficulty = ?'
-        params.push(args.difficulty)
-      }
-      if (args.parent_topic_name) {
-        const p = resolveTopic(args.parent_topic_name)
-        query += ' AND t.parent_topic_id = ?'
-        params.push(p.id)
-      }
-
-      query += ' ORDER BY t.sort_order ASC, t.created_at DESC'
-      const rows = db.prepare(query).all(...params)
-
-      if (!rows.length) return 'No topics found matching criteria.'
-      return `Found ${rows.length} topic(s):\n` +
-        rows.map(t => {
-          const cat = t.major_name ? ` [Category: ${t.major_name}]` : ''
-          const diff = t.difficulty ? ` (${t.difficulty})` : ''
-          const icons = `${t.is_pinned ? ' 🔒' : ''}${t.is_starred ? ' ⭐' : ''}`
-          return `• ${t.name}${cat}${diff}${icons} (ID: ${t.id})`
-        }).join('\n')
-    }
-
-    case 'get_topic': {
-      const topic = resolveTopic(args.name)
-      const resources = db.prepare('SELECT * FROM resources WHERE topic_id = ? ORDER BY sort_order ASC, created_at DESC').all(topic.id)
-      let majorName = null
-      if (topic.major_topic_id) {
-        const m = db.prepare('SELECT name FROM major_topics WHERE id = ?').get(topic.major_topic_id)
-        if (m) majorName = m.name
-      }
-
-      let out = `Topic: ${topic.name}\n`
-      out += `ID: ${topic.id}\n`
-      if (majorName) out += `Category: ${majorName}\n`
-      if (topic.difficulty) out += `Difficulty: ${topic.difficulty}\n`
-      if (topic.color) out += `Color: ${topic.color}\n`
-      if (topic.note) out += `Note: ${topic.note}\n`
-      out += `Status: ${topic.is_pinned ? '🔒 Pinned ' : ''}${topic.is_starred ? '⭐ Starred' : ''}\n\n`
-
-      if (!resources.length) {
-        out += 'Resources: None attached yet.'
-      } else {
-        out += `Resources (${resources.length}):\n`
-        out += resources.map(r =>
-          `• [${r.type.toUpperCase()}] ${r.description || '(no description)'} ${r.is_completed ? '✓' : '○'}\n  ${r.path_or_url}`
-        ).join('\n')
-      }
-      return out
-    }
-
-    case 'create_topic': {
-      let majorId = null
-      if (args.major_topic_name) {
-        const m = resolveMajorTopic(args.major_topic_name)
-        majorId = m.id
-      }
-      const id = newId()
-      const color = resolveColor(args.color)
-      db.prepare(`INSERT INTO topics (id, name, difficulty, major_topic_id, color, created_at, synced)
-                  VALUES (?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', majorId, color, nowIso())
-      return `✓ Created topic "${args.name}" (ID: ${id})`
-    }
-
-    case 'create_subtopic': {
-      const parent = resolveTopic(args.parent_topic_name)
-      const id = newId()
-      db.prepare(`INSERT INTO topics (id, name, difficulty, parent_topic_id, major_topic_id, created_at, synced)
-                  VALUES (?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', parent.id, parent.major_topic_id, nowIso())
-      return `✓ Created subtopic "${args.name}" under parent "${parent.name}" (ID: ${id})`
-    }
-
-    case 'delete_topic': {
-      const topic = resolveTopic(args.name)
-      db.prepare('DELETE FROM resources WHERE topic_id = ?').run(topic.id)
-      db.prepare('DELETE FROM topics WHERE id = ?').run(topic.id)
-      return `✓ Deleted topic "${topic.name}" and all its resources.`
-    }
-
-    case 'rename_topic': {
-      const topic = resolveTopic(args.name)
-      const newName = args.new_name.trim()
-      db.prepare('UPDATE topics SET name = ?, updated_at = ? WHERE id = ?').run(newName, nowIso(), topic.id)
-      return `✓ Renamed topic from "${topic.name}" to "${newName}"`
-    }
-
-    case 'set_topic_color': {
-      const topic = resolveTopic(args.name)
-      const color = resolveColor(args.color)
-      db.prepare('UPDATE topics SET color = ?, updated_at = ? WHERE id = ?').run(color, nowIso(), topic.id)
-      return `✓ Changed colour of topic "${topic.name}" to ${color}`
-    }
-
-    case 'pin_topic': {
-      const topic = resolveTopic(args.name)
-      const pinned = args.pinned === true || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
-      db.prepare('UPDATE topics SET is_pinned = ?, updated_at = ? WHERE id = ?').run(pinned, nowIso(), topic.id)
-      return pinned ? `✓ Locked/pinned topic "${topic.name}" 🔒` : `✓ Unlocked topic "${topic.name}"`
-    }
-
-    case 'star_topic': {
-      const topic = resolveTopic(args.name)
-      const starred = args.starred === true || String(args.starred).toLowerCase() === 'true' ? 1 : 0
-      db.prepare('UPDATE topics SET is_starred = ?, updated_at = ? WHERE id = ?').run(starred, nowIso(), topic.id)
-      return starred ? `✓ Added topic "${topic.name}" to favourites ⭐` : `✓ Removed topic "${topic.name}" from favourites`
-    }
-
-    case 'list_resources': {
-      const topic = resolveTopic(args.topic_name)
-      let query = 'SELECT * FROM resources WHERE topic_id = ?'
-      const params = [topic.id]
-      if (args.type) {
-        query += ' AND type = ?'
-        params.push(args.type)
-      }
-      query += ' ORDER BY sort_order ASC, created_at DESC'
-      const rows = db.prepare(query).all(...params)
-      if (!rows.length) return `No resources found for topic "${topic.name}".`
-      return `Found ${rows.length} resource(s) in "${topic.name}":\n` +
-        rows.map(r => `• [${r.type.toUpperCase()}] ${r.description || '(no label)'} ${r.is_completed ? '✓ Done' : '○ Incomplete'}\n  URL/Path: ${r.path_or_url}\n  ID: ${r.id}`).join('\n')
-    }
-
-    case 'add_youtube':
-    case 'add_link':
-    case 'add_pdf':
-    case 'add_audio':
-    case 'add_video':
-    case 'add_image':
-    case 'add_code': {
-      const topic = resolveTopic(args.topic_name)
-      const type = RESOURCE_TYPE_MAP[name]
-      const id = newId()
-      let finalPathOrUrl = String(args.url || '').trim()
-
-      // For youtube, extract video ID if present
-      let ytVideoId = null
-      if (type === 'youtube') {
-        const m = finalPathOrUrl.match(/(?:youtu\.be\/|v=|\/embed\/|\/v\/|watch\?v=)([\w-]{11})/)
-        if (m) ytVideoId = m[1]
-      }
-
-      db.prepare(`INSERT INTO resources (id, topic_id, type, description, path_or_url, youtube_video_id, is_completed, created_at, synced)
-                  VALUES (?, ?, ?, ?, ?, ?, 0, ?, 1)`).run(id, topic.id, type, args.description.trim(), finalPathOrUrl, ytVideoId, nowIso())
-      return `✓ Added [${type.toUpperCase()}] "${args.description}" to "${topic.name}" (ID: ${id})`
-    }
-
-    case 'delete_resource': {
-      const row = db.prepare('SELECT * FROM resources WHERE id = ?').get(args.resource_id)
-      if (!row) throw new Error(`Resource not found with ID: "${args.resource_id}"`)
-      db.prepare('DELETE FROM resources WHERE id = ?').run(row.id)
-      return `✓ Deleted resource "${row.description || row.path_or_url}"`
-    }
-
-    case 'mark_resource_complete': {
-      const isCompleted = args.is_completed === true || String(args.is_completed).toLowerCase() === 'true' ? 1 : 0
-      const row = db.prepare('SELECT * FROM resources WHERE id = ?').get(args.resource_id)
-      if (!row) throw new Error(`Resource not found with ID: "${args.resource_id}"`)
-      db.prepare('UPDATE resources SET is_completed = ? WHERE id = ?').run(isCompleted, row.id)
-      return `✓ Resource marked as ${isCompleted ? 'completed ✓' : 'incomplete ○'}`
-    }
-
-    case 'list_todos': {
-      let query = 'SELECT * FROM todos WHERE 1=1'
-      const params = []
-      if (args.priority) {
-        query += ' AND priority = ?'
-        params.push(args.priority.toLowerCase())
-      }
-      if (args.is_completed !== undefined) {
-        query += ' AND is_completed = ?'
-        params.push(args.is_completed ? 1 : 0)
-      }
-      query += ' ORDER BY created_at DESC'
-      const rows = db.prepare(query).all(...params)
-      if (!rows.length) return 'No todos found.'
-      return `Found ${rows.length} task(s):\n` +
-        rows.map(t => `• [${t.is_completed ? '✓ Done' : '○ Todo'}] ${t.name} (Priority: ${t.priority})${t.notes ? ` - ${t.notes}` : ''} (ID: ${t.id})`).join('\n')
-    }
-
-    case 'create_todo': {
-      const id = newId()
-      const now = nowIso()
-      db.prepare(`INSERT INTO todos (id, name, priority, notes, is_completed, created_at, updated_at)
-                  VALUES (?, ?, ?, ?, 0, ?, ?)`).run(id, args.name.trim(), (args.priority || 'medium').toLowerCase(), args.notes || '', now, now)
-      return `✓ Created todo "${args.name}" (ID: ${id})`
-    }
-
-    case 'complete_todo': {
-      const item = resolveTodo(args.name)
-      db.prepare('UPDATE todos SET is_completed = 1, updated_at = ? WHERE id = ?').run(nowIso(), item.id)
-      return `✓ Completed task "${item.name}" 🎉`
-    }
-
-    case 'update_todo': {
-      const item = db.prepare('SELECT * FROM todos WHERE id = ?').get(args.id)
-      if (!item) throw new Error(`Todo not found with ID: "${args.id}"`)
-
-      const name = args.name !== undefined ? args.name.trim() : item.name
-      const priority = args.priority !== undefined ? args.priority.toLowerCase() : item.priority
-      const notes = args.notes !== undefined ? args.notes : item.notes
-      const isCompleted = args.is_completed !== undefined ? (args.is_completed ? 1 : 0) : item.is_completed
-
-      db.prepare(`UPDATE todos SET name = ?, priority = ?, notes = ?, is_completed = ?, updated_at = ?
-                  WHERE id = ?`).run(name, priority, notes, isCompleted, nowIso(), item.id)
-      return `✓ Updated todo "${name}"`
-    }
-
-    case 'delete_todo': {
-      const item = resolveTodo(args.name)
-      db.prepare('DELETE FROM todos WHERE id = ?').run(item.id)
-      return `✓ Deleted todo "${item.name}"`
-    }
-
-    case 'delete_completed_todos': {
-      const res = db.prepare('DELETE FROM todos WHERE is_completed = 1').run()
-      return `✓ Removed ${res.changes || 0} completed task(s).`
-    }
-
-    case 'write_topic_note': {
-      const topic = resolveTopic(args.topic_name)
-      checkPinIfLocked(topic.is_pinned, args.pin)
-      const existing = (topic.note || '').trim()
-      const newNote = existing ? `${existing}\n\n${args.note.trim()}` : args.note.trim()
-      const title = args.title ? args.title.trim() : topic.note_title
-      db.prepare('UPDATE topics SET note = ?, note_title = ?, updated_at = ? WHERE id = ?')
-        .run(newNote, title, nowIso(), topic.id)
-      return `✓ Note saved to topic "${topic.name}"`
-    }
-
-    case 'clean_empty_major_topics': {
-      const allMajor = db.prepare('SELECT * FROM major_topics').all()
-      let removed = 0
-      for (const m of allMajor) {
-        const countRow = db.prepare(`
-          SELECT count(r.id) as count
-          FROM topics t
-          LEFT JOIN resources r ON r.topic_id = t.id
-          WHERE t.major_topic_id = ?
-        `).get(m.id)
-        if (!countRow || countRow.count === 0) {
-          db.prepare('DELETE FROM major_topics WHERE id = ?').run(m.id)
-          removed++
-        }
-      }
-      return `✓ Cleaned ${removed} empty major topic(s) with no resources.`
-    }
-
-    case 'get_stats': {
-      const majorCount = db.prepare('SELECT count(*) as count FROM major_topics').get().count
-      const topicCount = db.prepare('SELECT count(*) as count FROM topics').get().count
-      const resTotal = db.prepare('SELECT count(*) as count FROM resources').get().count
-      const resDone = db.prepare('SELECT count(*) as count FROM resources WHERE is_completed = 1').get().count
-      const todoTotal = db.prepare('SELECT count(*) as count FROM todos').get().count
-      const todoDone = db.prepare('SELECT count(*) as count FROM todos WHERE is_completed = 1').get().count
-
-      const completionPct = resTotal > 0 ? Math.round((resDone / resTotal) * 100) : 0
-      return `📊 KARMA 365 Statistics:\n` +
-        `• Major Topics: ${majorCount}\n` +
-        `• Topics: ${topicCount}\n` +
-        `• Resources: ${resTotal} total (${resDone} studied / ${completionPct}%)\n` +
-        `• Tasks: ${todoTotal} total (${todoDone} completed)\n` +
-        `• Storage: Local SQLite DB (${DB_PATH})`
-    }
-
-    case 'search': {
-      const q = `%${args.query.trim().toLowerCase()}%`
-      const topics = db.prepare('SELECT * FROM topics WHERE LOWER(name) LIKE ? OR LOWER(note) LIKE ? LIMIT 10').all(q, q)
-      const resources = db.prepare('SELECT * FROM resources WHERE LOWER(description) LIKE ? OR LOWER(path_or_url) LIKE ? LIMIT 10').all(q, q)
-      const todos = db.prepare('SELECT * FROM todos WHERE LOWER(name) LIKE ? OR LOWER(notes) LIKE ? LIMIT 10').all(q, q)
-
-      let out = `Search results for "${args.query}":\n`
-      if (topics.length) {
-        out += `\nTopics (${topics.length}):\n` + topics.map(t => `• ${t.name} (ID: ${t.id})`).join('\n')
-      }
-      if (resources.length) {
-        out += `\nResources (${resources.length}):\n` + resources.map(r => `• [${r.type}] ${r.description} (${r.path_or_url})`).join('\n')
-      }
-      if (todos.length) {
-        out += `\nTodos (${todos.length}):\n` + todos.map(t => `• ${t.name} [${t.priority}]`).join('\n')
-      }
-      if (!topics.length && !resources.length && !todos.length) {
-        out += 'No matching items found.'
-      }
-      return out
-    }
-
-    case 'search_web': {
-      const results = await searchWebKeyless(args.query)
-      let out = `Web search results for "${args.query}":\n` +
-        results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ''}`).join('\n\n')
-
-      if (args.topic_name) {
-        const phoneUrl = activePhoneUrl || (await autoDiscoverPhone())
-        if (phoneUrl) {
-          try {
-            for (const item of results) {
-              await callPhoneBridge('add_link', { topic_name: args.topic_name, url: item.url, description: item.title })
-            }
-            out += `\n\n✓ Saved ${results.length} search links directly to topic "${args.topic_name}" on mobile app.`
-            return out
-          } catch (e) {
-            process.stderr.write(`[karma365-mcp] Failed saving search links to phone: ${e.message}. Falling back to local DB.\n`)
-          }
-        }
-        const topic = resolveTopic(args.topic_name)
-        for (const item of results) {
-          db.prepare(`INSERT INTO resources (id, topic_id, type, description, path_or_url, is_completed, created_at, synced)
-                      VALUES (?, ?, 'link', ?, ?, 0, ?, 1)`).run(newId(), topic.id, item.title, item.url, nowIso())
-        }
-        out += `\n\n✓ Saved ${results.length} search links directly to topic "${topic.name}".`
-      }
-      return out
-    }
-
-    case 'search_youtube': {
-      const results = await searchYouTubeKeyless(args.query, args.max_results || 3)
-      let out = `YouTube search results for "${args.query}":\n` +
-        results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}`).join('\n\n')
-
-      if (args.topic_name) {
-        const phoneUrl = activePhoneUrl || (await autoDiscoverPhone())
-        if (phoneUrl) {
-          try {
-            for (const item of results) {
-              await callPhoneBridge('add_youtube', { topic_name: args.topic_name, url: item.url, description: item.title })
-            }
-            out += `\n\n✓ Saved ${results.length} YouTube videos directly to topic "${args.topic_name}" on mobile app.`
-            return out
-          } catch (e) {
-            process.stderr.write(`[karma365-mcp] Failed saving YouTube videos to phone: ${e.message}. Falling back to local DB.\n`)
-          }
-        }
-        const topic = resolveTopic(args.topic_name)
-        for (const item of results) {
-          const m = item.url.match(/v=([\w-]{11})/)
-          const ytid = m ? m[1] : null
-          db.prepare(`INSERT INTO resources (id, topic_id, type, description, path_or_url, youtube_video_id, is_completed, created_at, synced)
-                      VALUES (?, ?, 'youtube', ?, ?, ?, 0, ?, 1)`).run(newId(), topic.id, item.title, item.url, ytid, nowIso())
-        }
-        out += `\n\n✓ Saved ${results.length} YouTube videos directly to topic "${topic.name}".`
-      }
-      return out
-    }
-
-    default:
-      throw new Error(`Unknown tool: ${name}`)
-  }
-}
-
-// ── MCP Server Startup ────────────────────────────────────────────────────────
-
-const server = new Server(
-  { name: 'karma365-mcp', version: '2.0.0' },
-  { capabilities: { tools: {} } }
-)
-
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return { tools: TOOLS }
-})
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  try {
-    const text = await handleTool(request.params.name, request.params.arguments || {})
-    return { content: [{ type: 'text', text: String(text) }] }
-  } catch (err) {
-    return { content: [{ type: 'text', text: `ERROR: ${err.message}` }], isError: true }
-  }
-})
-
-const transport = new StdioServerTransport()
-await server.connect(transport)
-process.stderr.write('[karma365-mcp] Server running on stdio transport (Zero-Server mode)\n')
-
-// Trigger background phone discovery on network
-autoDiscoverPhone().catch(() => {})
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import crypto from 'node:crypto'
+import { checkYouTubeVideo } from './youtube_check.js'
+
+// ── Secure link to the phone ──────────────────────────────────────────────────
+// Same protocol as karma_flutter/lib/services/device_link.dart. The device key is
+// made during pairing, never crosses the network, and stays in the file below.
+
+const LINK_FILE = path.join(os.homedir(), '.karma365', 'link.json')
+const LOCAL_ONLY = process.env.KARMA365_LOCAL_ONLY === 'true' || process.env.KARMA365_PHONE_URL === 'none' || process.env.KARMA365_PHONE_URL === 'false'
+const MAX_LOCAL_FILE_BYTES = 50 * 1024 * 1024
+
+/**
+ * The token in the MCP config. A key is made from it, so the token itself is never
+ * sent; the phone makes the same key. Same as DeviceLinks.setToken on the phone.
+ */
+function linkFromToken(token) {
+  return {
+    deviceId: crypto.createHash('sha256').update(`karma365-token-id|${token}`).digest('hex').slice(0, 24),
+    key: Buffer.from(crypto.hkdfSync('sha256', Buffer.from(token), Buffer.alloc(0), Buffer.from('karma365-token-v2'), 32)).toString('base64'),
+    fromToken: true,
+  }
+}
+
+function readLink() {
+  const token = (process.env.KARMA365_TOKEN || '').trim()
+  if (token) return linkFromToken(token)
+  try {
+    const link = JSON.parse(fs.readFileSync(LINK_FILE, 'utf-8'))
+    return link && link.deviceId && link.key ? link : null
+  } catch (_) {
+    return null
+  }
+}
+
+function writeLink(link) {
+  fs.mkdirSync(path.dirname(LINK_FILE), { recursive: true, mode: 0o700 })
+  fs.writeFileSync(LINK_FILE, JSON.stringify(link, null, 2), { mode: 0o600 })
+}
+
+const linkAad = (direction, deviceId) => Buffer.from(`karma365-v2|${direction}|${deviceId}`)
+
+function sealForPhone(link, message) {
+  const iv = crypto.randomBytes(12)
+  const cipher = crypto.createCipheriv('aes-256-gcm', Buffer.from(link.key, 'base64'), iv)
+  cipher.setAAD(linkAad('c2s', link.deviceId))
+  const body = Buffer.concat([cipher.update(JSON.stringify(message), 'utf-8'), cipher.final(), cipher.getAuthTag()])
+  return { d: link.deviceId, iv: iv.toString('base64'), c: body.toString('base64') }
+}
+
+function openFromPhone(link, envelope) {
+  const sealed = Buffer.from(envelope.c, 'base64')
+  const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(link.key, 'base64'), Buffer.from(envelope.iv, 'base64'))
+  decipher.setAAD(linkAad('s2c', link.deviceId))
+  decipher.setAuthTag(sealed.subarray(sealed.length - 16))
+  return JSON.parse(Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - 16)), decipher.final()]).toString('utf-8'))
+}
+
+/** One sealed request. Throws if whatever answers cannot prove it holds the key. */
+async function secureCall(baseUrl, link, method, routePath, body, timeoutMs = 8000) {
+  const nonce = crypto.randomBytes(16).toString('hex')
+  const res = await fetch(`${baseUrl}/api/secure`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    redirect: 'error',
+    body: JSON.stringify(sealForPhone(link, {
+      ts: Date.now(),
+      n: nonce,
+      m: method,
+      p: routePath,
+      h: { 'content-type': 'application/json' },
+      b: body === undefined ? null : Buffer.from(JSON.stringify(body)).toString('base64'),
+    })),
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (res.status === 401) {
+    const error = new Error('The phone did not accept this PC. Copy the current token from KARMA 365: Settings, AI MCP.')
+    error.notPaired = true
+    throw error
+  }
+  if (!res.ok) throw new Error(`Phone returned status ${res.status}`)
+  const message = openFromPhone(link, await res.json())
+  if (message.n !== nonce) throw new Error('Phone reply did not match this request')
+  return { status: message.s, body: message.b ? JSON.parse(Buffer.from(message.b, 'base64').toString('utf-8')) : {} }
+}
+
+async function runPairCommand() {
+  const flag = process.argv.indexOf('--phone')
+  const raw = (flag !== -1 ? process.argv[flag + 1] : process.env.KARMA365_PHONE_URL) || ''
+  if (!raw) {
+    process.stderr.write('Usage: npx karma365-mcp pair --phone http://<phone-ip>:8365\n(The address is in the app: Settings, AI MCP.)\n')
+    process.exit(1)
+  }
+  const baseUrl = raw.trim().replace(/\/+$/, '')
+  const keys = crypto.generateKeyPairSync('x25519')
+  const clientPublic = keys.publicKey.export({ type: 'spki', format: 'der' }).subarray(-32)
+
+  // Commit before seeing the phone's key, so nothing in the middle can search for
+  // keys that make the two codes come out the same.
+  const first = await fetch(`${baseUrl}/api/pair/request`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    redirect: 'error',
+    body: JSON.stringify({
+      client_name: `MCP on ${os.hostname()}`,
+      commit: crypto.createHash('sha256').update(clientPublic).digest('base64'),
+    }),
+  })
+  const started = await first.json().catch(() => ({}))
+  if (!first.ok || !started.server_pub) throw new Error(started.error || `Pairing rejected (${first.status})`)
+
+  const serverPublic = Buffer.from(started.server_pub, 'base64')
+  const phoneKey = crypto.createPublicKey({
+    key: Buffer.concat([Buffer.from('302a300506032b656e032100', 'hex'), serverPublic]),
+    format: 'der',
+    type: 'spki',
+  })
+  const shared = crypto.diffieHellman({ privateKey: keys.privateKey, publicKey: phoneKey })
+  const salt = crypto.createHash('sha256').update(Buffer.concat([clientPublic, serverPublic])).digest()
+  const derived = Buffer.from(crypto.hkdfSync('sha256', shared, salt, Buffer.from('karma365-pair-v2'), 36))
+  const code = String(derived.readUInt32BE(32) % 1000000).padStart(6, '0')
+
+  process.stderr.write(`\nPairing code: ${code}\nIf your phone shows the same code, tap Allow there. Otherwise tap Decline.\n\n`)
+
+  const second = await fetch(`${baseUrl}/api/pair/confirm`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    redirect: 'error',
+    body: JSON.stringify({ pair_id: started.pair_id, client_pub: clientPublic.toString('base64') }),
+  })
+  const finished = await second.json().catch(() => ({}))
+  if (!second.ok || !finished.device_id) throw new Error(finished.error || `Pairing rejected (${second.status})`)
+
+  writeLink({ deviceId: finished.device_id, key: derived.subarray(0, 32).toString('base64'), phoneUrl: baseUrl })
+  process.stderr.write('Paired. This PC can now reach your phone.\n')
+}
+
+if (process.argv[2] === 'pair') {
+  try {
+    await runPairCommand()
+    // Let the HTTP client finish closing its sockets; exiting mid-close can crash
+    // Node on Windows even though pairing succeeded.
+    await new Promise((resolve) => setTimeout(resolve, 200))
+    process.exit(0)
+  } catch (err) {
+    process.stderr.write(`Pairing failed: ${err.message}\n`)
+    process.exit(1)
+  }
+}
+
+/**
+ * Files an AI may send to the phone. A web page can trick an AI into asking for
+ * any path, so nothing is readable until the user names folders for it.
+ */
+function assertFileMaySend(localPath) {
+  const real = fs.realpathSync(localPath)
+  const blocked = /(^|[\\/])(\.ssh|\.aws|\.gnupg|\.env[^\\/]*|[^\\/]*\.pem|id_rsa[^\\/]*|[^\\/]*\.keystore|[^\\/]*\.jks|link\.json|\.mcp\.json|claude_desktop_config\.json|key\.properties|secret\.md|\.secret_salt[^\\/]*|\.npmrc|\.netrc|\.git-credentials)($|[\\/])/i
+  if (blocked.test(real)) throw new Error('This file holds secrets and cannot be sent.')
+  const listed = (process.env.KARMA365_ALLOWED_DIRS || '').split(path.delimiter).filter(Boolean)
+  const usual = ['Desktop', 'Documents', 'Downloads', 'Pictures', 'Music', 'Videos'].map((dir) => path.join(os.homedir(), dir))
+  const allowed = (listed.length ? listed : usual)
+    .flatMap((dir) => {
+      try { return [fs.realpathSync(dir)] } catch (_) { return [] }
+    })
+  if (!allowed.some((dir) => real === dir || real.startsWith(dir + path.sep))) {
+    throw new Error('Files can be sent from Desktop, Documents, Downloads, Pictures, Music and Videos. For other folders, list them in KARMA365_ALLOWED_DIRS.')
+  }
+  if (fs.statSync(real).size > MAX_LOCAL_FILE_BYTES) throw new Error('This file is larger than 50 MB.')
+  return real
+}
+
+// ── Database connection & Auto-detect ─────────────────────────────────────────
+
+function autoDetectDbPath() {
+  if (process.env.KARMA365_DB && process.env.KARMA365_DB.trim()) {
+    const custom = path.resolve(process.env.KARMA365_DB.trim())
+    const dir = path.dirname(custom)
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+    return custom
+  }
+
+  const home = os.homedir()
+  const candidates = [
+    // Windows AppData standard
+    process.env.APPDATA ? path.join(process.env.APPDATA, 'karma365', 'karma365.db') : null,
+    // macOS standard
+    path.join(home, 'Library', 'Application Support', 'com.karma365.app', 'karma365.db'),
+    // Linux standard
+    path.join(home, '.local', 'share', 'karma365', 'karma365.db'),
+    // Standard cross-platform hidden folder
+    path.join(home, '.karma365', 'karma365.db'),
+    // Current working directory (if user runs from repo/project folder)
+    path.join(process.cwd(), 'karma365.db'),
+  ].filter(Boolean)
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate
+  }
+
+  // Fallback: create default ~/.karma365/karma365.db
+  const defaultPath = path.join(home, '.karma365', 'karma365.db')
+  const dir = path.dirname(defaultPath)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+  return defaultPath
+}
+
+const DB_PATH = LOCAL_ONLY ? autoDetectDbPath() : null
+if (LOCAL_ONLY) process.stderr.write(`[karma365-mcp] Using SQLite database: ${DB_PATH}\n`)
+
+let DatabaseSync
+if (LOCAL_ONLY) {
+  try {
+    const mod = await import('node:sqlite')
+    DatabaseSync = mod.DatabaseSync
+  } catch (_) {
+    try {
+      const mod = await import('better-sqlite3')
+      DatabaseSync = mod.default
+    } catch (err) {
+      process.stderr.write('ERROR: SQLite support requires Node 22.5+ (node:sqlite) or better-sqlite3.\n')
+      process.exit(1)
+    }
+  }
+}
+
+const db = LOCAL_ONLY ? new DatabaseSync(DB_PATH) : null
+
+// Initialize schema if not present
+if (db) db.exec('PRAGMA foreign_keys = ON;')
+if (db) db.exec(`
+  CREATE TABLE IF NOT EXISTS major_topics (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    color TEXT,
+    note TEXT,
+    note_title TEXT,
+    created_at TEXT NOT NULL,
+    is_pinned INTEGER NOT NULL DEFAULT 0,
+    is_starred INTEGER NOT NULL DEFAULT 0,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    synced INTEGER NOT NULL DEFAULT 0
+  );
+
+  CREATE TABLE IF NOT EXISTS topics (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    difficulty TEXT CHECK (difficulty IN ('Easy','Medium','Hard')),
+    color TEXT,
+    major_topic_id TEXT REFERENCES major_topics(id) ON DELETE SET NULL,
+    parent_topic_id TEXT REFERENCES topics(id) ON DELETE SET NULL,
+    note TEXT,
+    note_title TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT,
+    last_opened TEXT,
+    visit_count INTEGER NOT NULL DEFAULT 0,
+    is_pinned INTEGER NOT NULL DEFAULT 0,
+    is_starred INTEGER NOT NULL DEFAULT 0,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    synced INTEGER NOT NULL DEFAULT 0
+  );
+
+  CREATE TABLE IF NOT EXISTS resources (
+    id TEXT PRIMARY KEY,
+    topic_id TEXT NOT NULL REFERENCES topics(id) ON DELETE CASCADE,
+    type TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    path_or_url TEXT NOT NULL,
+    original_filename TEXT,
+    youtube_video_id TEXT,
+    thumbnail_path TEXT,
+    is_completed INTEGER NOT NULL DEFAULT 0,
+    is_pinned INTEGER NOT NULL DEFAULT 0,
+    is_starred INTEGER NOT NULL DEFAULT 0,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    notes TEXT,
+    created_at TEXT,
+    synced INTEGER NOT NULL DEFAULT 0
+  );
+
+  CREATE TABLE IF NOT EXISTS todos (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    priority TEXT NOT NULL CHECK (priority IN ('high','medium','low')) DEFAULT 'medium',
+    is_completed INTEGER NOT NULL DEFAULT 0,
+    notes TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS settings (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_topics_major ON topics(major_topic_id);
+  CREATE INDEX IF NOT EXISTS idx_topics_parent ON topics(parent_topic_id);
+  CREATE INDEX IF NOT EXISTS idx_resources_topic ON resources(topic_id);
+`)
+
+// Helpers
+function newId() { return crypto.randomUUID() }
+function nowIso() { return new Date().toISOString() }
+
+function isUuid(s) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(s || ''))
+}
+
+const COLOR_MAP = {
+  red: '#ef4444', laal: '#ef4444', lal: '#ef4444',
+  blue: '#3b82f6', neela: '#3b82f6', nilo: '#3b82f6',
+  green: '#22c55e', hara: '#22c55e', hario: '#22c55e',
+  yellow: '#eab308', peela: '#eab308', pilo: '#eab308',
+  purple: '#a855f7', jambli: '#a855f7',
+  pink: '#ec4899', gulabi: '#ec4899',
+  orange: '#f97316', narangi: '#f97316',
+  teal: '#14b8a6', indigo: '#6366f1', violet: '#8b5cf6',
+  gray: '#6b7280', grey: '#6b7280', coral: '#f87171',
+  navy: '#1e3a8a', rose: '#f43f5e', amber: '#f59e0b',
+}
+
+function resolveColor(c) {
+  if (!c) return null
+  const s = String(c).trim()
+  if (/^#?[0-9a-f]{6}$/i.test(s)) return s.startsWith('#') ? s : `#${s}`
+  return COLOR_MAP[s.toLowerCase()] || s
+}
+
+function cleanName(s) {
+  return ` ${String(s).toLowerCase().trim()} `
+    .replace(/\bsub[- ]?topics?\b/g, ' ')
+    .replace(/\b(major|minor)\b/g, ' ')
+    .replace(/\btopics?\b/g, ' ')
+    .replace(/\bcategor(?:y|ies)\b/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function findByName(items, nameOrId) {
+  const lower = String(nameOrId).toLowerCase().trim()
+  const cleaned = cleanName(nameOrId)
+  return items.find(x => x.name.toLowerCase() === lower)
+    || (cleaned && items.find(x => x.name.toLowerCase() === cleaned))
+    || (cleaned && items.find(x => x.name.toLowerCase().includes(cleaned)))
+    || (lower && items.find(x => x.name.toLowerCase().includes(lower)))
+    || null
+}
+
+function resolveTopic(nameOrId) {
+  if (isUuid(nameOrId)) {
+    const row = db.prepare('SELECT * FROM topics WHERE id = ?').get(nameOrId)
+    if (row) return row
+  }
+  const all = db.prepare('SELECT * FROM topics').all()
+  const found = findByName(all, nameOrId)
+  if (!found) throw new Error(`Topic not found: "${nameOrId}"`)
+  return found
+}
+
+function resolveMajorTopic(nameOrId) {
+  if (isUuid(nameOrId)) {
+    const row = db.prepare('SELECT * FROM major_topics WHERE id = ?').get(nameOrId)
+    if (row) return row
+  }
+  const all = db.prepare('SELECT * FROM major_topics').all()
+  const found = findByName(all, nameOrId)
+  if (!found) throw new Error(`Major topic not found: "${nameOrId}"`)
+  return found
+}
+
+function resolveTodo(nameOrId) {
+  if (isUuid(nameOrId)) {
+    const row = db.prepare('SELECT * FROM todos WHERE id = ?').get(nameOrId)
+    if (row) return row
+  }
+  const all = db.prepare('SELECT * FROM todos').all()
+  const found = all.find(t => t.name.toLowerCase() === String(nameOrId).toLowerCase().trim())
+  if (!found) throw new Error(`Todo not found: "${nameOrId}"`)
+  return found
+}
+
+// ── Security & PIN System ─────────────────────────────────────────────────────
+
+function hashPin(pin, salt) {
+  return `scrypt:${crypto.scryptSync(String(pin), salt, 32).toString('hex')}`
+}
+
+const PIN_MAX_ATTEMPTS = 6
+const PIN_LOCK_MS = 30000
+
+function getSetting(key) {
+  try {
+    const row = db.prepare('SELECT value FROM settings WHERE key = ?').get(key)
+    return row ? row.value : null
+  } catch {
+    return null
+  }
+}
+
+function setSetting(key, value) {
+  db.prepare(`INSERT INTO settings (key, value) VALUES (?, ?)
+              ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(key, String(value))
+}
+
+function hasPin() {
+  const hash = getSetting('pin_hash')
+  const salt = getSetting('pin_salt')
+  return Boolean(hash && salt)
+}
+
+function setMasterPin(newPin) {
+  const trimmed = String(newPin ?? '').trim()
+  if (!trimmed) {
+    throw new Error('PIN cannot be empty. Please provide a numeric PIN (e.g. 111111).')
+  }
+  const salt = crypto.randomBytes(16).toString('hex')
+  setSetting('pin_salt', salt)
+  setSetting('pin_hash', hashPin(trimmed, salt))
+  setSetting('pin_fails', 0)
+  setSetting('pin_lock_until', 0)
+  return true
+}
+
+function sameText(a, b) {
+  const left = Buffer.from(String(a))
+  const right = Buffer.from(String(b))
+  return left.length === right.length && crypto.timingSafeEqual(left, right)
+}
+
+function verifyPin(pin) {
+  const salt = getSetting('pin_salt')
+  const storedHash = getSetting('pin_hash')
+  if (!salt || !storedHash) return false
+  const trimmed = String(pin ?? '').trim()
+  if (!trimmed) return false
+  if (Number(getSetting('pin_lock_until') || 0) > Date.now()) return false
+
+  const isOldHash = !storedHash.startsWith('scrypt:')
+  const ok = isOldHash
+    ? sameText(crypto.createHash('sha256').update(salt + trimmed).digest('hex'), storedHash)
+    : sameText(hashPin(trimmed, salt), storedHash)
+  if (ok) {
+    setSetting('pin_fails', 0)
+    if (isOldHash) setSetting('pin_hash', hashPin(trimmed, salt))
+    return true
+  }
+  const fails = Number(getSetting('pin_fails') || 0) + 1
+  if (fails >= PIN_MAX_ATTEMPTS) {
+    setSetting('pin_fails', 0)
+    setSetting('pin_lock_until', Date.now() + PIN_LOCK_MS)
+  } else {
+    setSetting('pin_fails', fails)
+  }
+  return false
+}
+
+/** True when this topic, a topic above it, or its major topic is locked. */
+function isTopicLocked(topic) {
+  const seen = new Set()
+  let current = topic
+  while (current && !seen.has(current.id)) {
+    seen.add(current.id)
+    if (current.is_pinned === 1) return true
+    if (current.major_topic_id) {
+      const major = db.prepare('SELECT is_pinned FROM major_topics WHERE id = ?').get(current.major_topic_id)
+      if (major && major.is_pinned === 1) return true
+    }
+    current = current.parent_topic_id
+      ? db.prepare('SELECT * FROM topics WHERE id = ?').get(current.parent_topic_id)
+      : null
+  }
+  return false
+}
+
+/**
+ * Checks if a locked item requires PIN verification.
+ * Returns:
+ *   'ok'       -> Not locked OR valid PIN provided
+ *   'required' -> Item is locked and no PIN provided
+ *   'invalid'  -> Item is locked and wrong PIN provided
+ */
+function checkPinIfLocked(isPinned, pin) {
+  if (!isPinned || isPinned === 0) return 'ok'
+  if (!hasPin()) return 'required'
+  const trimmed = String(pin ?? '').trim()
+  if (!trimmed) return 'required'
+  return verifyPin(trimmed) ? 'ok' : 'invalid'
+}
+
+const PIN_REQ = (name, action = 'this action') =>
+  `PIN_REQUIRED: "${name}" is locked/PIN-protected 🔒. Prompt the user for their PIN to authorize ${action}, then retry with pin="<their_pin>".`
+
+const PIN_BAD = (name, action = 'performed') =>
+  `PIN_INVALID: Authentication failed — incorrect PIN entered ❌. "${name}" was NOT ${action}.`
+
+// ── Search helpers (DuckDuckGo / SearXNG) ─────────────────────────────────────
+
+const SEARCH_UA = 'Mozilla/5.0 (compatible; KarmaSearch/2.0)'
+
+async function fetchWithTimeout(url, opts = {}, ms = 8000) {
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), ms)
+  try {
+    return await fetch(url, { ...opts, signal: ctrl.signal })
+  } finally {
+    clearTimeout(t)
+  }
+}
+
+async function searchWebKeyless(query) {
+  const searx = [
+    'https://searx.be',
+    'https://searxng.world',
+    'https://search.mdosch.de',
+    'https://searx.tiekoetter.com',
+  ]
+  for (const base of searx) {
+    try {
+      const res = await fetchWithTimeout(
+        `${base}/search?q=${encodeURIComponent(query)}&format=json&categories=general&language=en-US`,
+        { headers: { 'User-Agent': SEARCH_UA, 'Accept': 'application/json' } })
+      if (!res.ok) continue
+      const data = await res.json()
+      const items = (data.results || [])
+        .filter(r => r.url && String(r.url).startsWith('http') && r.title)
+        .slice(0, 5)
+        .map(r => ({ title: String(r.title).trim(), url: String(r.url).trim(),
+          snippet: String(r.content || '').slice(0, 200) }))
+      if (items.length) return items
+    } catch { /* try next */ }
+  }
+
+  // DuckDuckGo Instant Answer fallback
+  try {
+    const res = await fetchWithTimeout(
+      `https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_html=1&skip_disambig=1`,
+      {}, 6000)
+    if (res.ok) {
+      const data = await res.json()
+      const out = []
+      if (data.AbstractText && data.AbstractURL) {
+        out.push({ title: data.Heading || query, url: data.AbstractURL,
+          snippet: String(data.AbstractText).slice(0, 200) })
+      }
+      for (const it of (data.RelatedTopics || []).slice(0, 4)) {
+        if (it.FirstURL && it.Text) {
+          out.push({ title: String(it.Text).slice(0, 100), url: it.FirstURL, snippet: '' })
+        }
+      }
+      if (out.length) return out
+    }
+  } catch { /* ignore */ }
+
+  return [{ title: `Search: ${query}`,
+    url: `https://duckduckgo.com/?q=${encodeURIComponent(query)}`,
+    snippet: `Web results for "${query}"` }]
+}
+
+// ── MCP Tool Definitions ──────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'list_major_topics',
+    description: 'List all major topic categories in KARMA 365',
+    inputSchema: { type: 'object', properties: {} }
+  },
+  {
+    name: 'create_major_topic',
+    description: 'Create a new major topic category in KARMA 365',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name:      { type: 'string', description: 'Name of the major topic' },
+        is_pinned: { type: 'boolean', description: 'Whether to pin this major topic' }
+      }
+    }
+  },
+  {
+    name: 'delete_major_topic',
+    description: 'Delete a major topic by name or ID. Its topics and resources are kept and moved into Karma 365, unless delete_children is true.',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Major topic name or ID' },
+        delete_children: { type: 'boolean', description: 'Also permanently delete its topics and resources. Default false.' },
+        pin:  { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'list_topics',
+    description: 'List topics in KARMA 365, optionally filtered by major topic, difficulty, or parent topic',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        major_topic_name:  { type: 'string', description: 'Filter by major topic name' },
+        difficulty:        { type: 'string', enum: ['Easy', 'Medium', 'Hard'] },
+        parent_topic_name: { type: 'string', description: 'List subtopics of this topic' }
+      }
+    }
+  },
+  {
+    name: 'get_topic',
+    description: 'Get full details of a topic including all its resources. PIN required if topic is locked.',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Topic name or ID' },
+        pin:  { type: 'string', description: 'Optional PIN required if the topic is locked' }
+      }
+    }
+  },
+  {
+    name: 'create_topic',
+    description: 'Create a new topic in KARMA 365. If parent major topic is locked, PIN is required.',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name:             { type: 'string', description: 'Topic name' },
+        difficulty:       { type: 'string', enum: ['Easy', 'Medium', 'Hard'] },
+        major_topic_name: { type: 'string', description: 'Assign to this major topic' },
+        color:            { type: 'string', description: 'Hex color code e.g. #FF5733' },
+        is_pinned:        { type: 'boolean', description: 'Whether to lock/pin this topic' },
+        pin:              { type: 'string', description: 'Optional PIN if parent major topic is locked' }
+      }
+    }
+  },
+  {
+    name: 'create_subtopic',
+    description: 'Create a subtopic under an existing topic. If parent topic is locked, PIN is required.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'parent_topic_name'],
+      properties: {
+        name:              { type: 'string', description: 'Subtopic name' },
+        parent_topic_name: { type: 'string', description: 'Parent topic name or ID' },
+        difficulty:        { type: 'string', enum: ['Easy', 'Medium', 'Hard'] },
+        is_pinned:         { type: 'boolean', description: 'Whether to lock/pin this subtopic' },
+        pin:               { type: 'string', description: 'Optional PIN if parent topic is locked' }
+      }
+    }
+  },
+  {
+    name: 'delete_topic',
+    description: 'Delete a topic and all its resources permanently.',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Topic name or ID' },
+        pin:  { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'list_resources',
+    description: 'List all resources attached to a topic',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name'],
+      properties: {
+        topic_name: { type: 'string', description: 'Topic name or ID' },
+        type:       { type: 'string', enum: ['pdf', 'video', 'youtube', 'link', 'audio', 'image', 'code'] }
+      }
+    }
+  },
+  {
+    name: 'add_youtube',
+    description: 'Add one YouTube video to a topic. This server cannot search YouTube: when the user names a song or video, find it with your own web search first and pass its youtube.com/watch?v=… link. Never make up a video ID. The link is checked with YouTube before saving, and a video that does not exist is not saved. The title comes from YouTube when no description is given.',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'url'],
+      properties: {
+        topic_name:  { type: 'string' },
+        url:         { type: 'string', description: 'Link to one YouTube video (watch, youtu.be or shorts)' },
+        description: { type: 'string', description: 'Label for this resource. Optional: the video title is used when empty.' },
+        pin:         { type: 'string', description: 'Optional PIN if the topic is locked' }
+      }
+    }
+  },
+  {
+    name: 'add_link',
+    description: 'Add a web link to a topic',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'url', 'description'],
+      properties: {
+        topic_name:  { type: 'string' },
+        url:         { type: 'string' },
+        description: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'add_pdf',
+    description: 'Add a PDF resource (URL or local file path) to a topic',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'url', 'description'],
+      properties: {
+        topic_name:  { type: 'string' },
+        url:         { type: 'string', description: 'http(s) URL or local file path' },
+        description: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'add_audio',
+    description: 'Add an audio resource (URL or local file path) to a topic',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'url', 'description'],
+      properties: {
+        topic_name:  { type: 'string' },
+        url:         { type: 'string', description: 'http(s) URL or local file path' },
+        description: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'add_video',
+    description: 'Add a video resource (URL or local file path) to a topic',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'url', 'description'],
+      properties: {
+        topic_name:  { type: 'string' },
+        url:         { type: 'string', description: 'http(s) URL or local file path' },
+        description: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'add_image',
+    description: 'Add an image resource (URL or local file path) to a topic',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'url', 'description'],
+      properties: {
+        topic_name:  { type: 'string' },
+        url:         { type: 'string', description: 'http(s) URL or local file path' },
+        description: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'add_code',
+    description: 'Add a code file resource (URL or local file path) to a topic',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'url', 'description'],
+      properties: {
+        topic_name:  { type: 'string' },
+        url:         { type: 'string', description: 'http(s) URL or local file path' },
+        description: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'delete_resource',
+    description: 'Delete a resource by its ID.',
+    inputSchema: {
+      type: 'object',
+      required: ['resource_id'],
+      properties: {
+        resource_id: { type: 'string', description: 'Resource UUID' },
+        pin:         { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'mark_resource_complete',
+    description: 'Mark a resource as studied/complete (or revert to incomplete)',
+    inputSchema: {
+      type: 'object',
+      required: ['resource_id', 'is_completed'],
+      properties: {
+        resource_id:  { type: 'string' },
+        is_completed: { type: 'boolean' }
+      }
+    }
+  },
+  {
+    name: 'write_topic_note',
+    description: 'Write, add, or append notes/text into a topic note',
+    inputSchema: {
+      type: 'object',
+      required: ['topic_name', 'note'],
+      properties: {
+        topic_name: { type: 'string' },
+        note:       { type: 'string' },
+        title:      { type: 'string', description: 'Optional note title' },
+        pin:        { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'list_todos',
+    description: 'List all todos in KARMA 365, optionally filtered by priority or completion',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        priority:     { type: 'string', enum: ['high', 'medium', 'low'] },
+        is_completed: { type: 'boolean' }
+      }
+    }
+  },
+  {
+    name: 'create_todo',
+    description: 'Create a new task/todo in KARMA 365',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name:     { type: 'string' },
+        priority: { type: 'string', enum: ['high', 'medium', 'low'], description: 'Defaults to medium' },
+        notes:    { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'complete_todo',
+    description: 'Mark a todo as done',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Todo name or ID' }
+      }
+    }
+  },
+  {
+    name: 'update_todo',
+    description: 'Update a todo\'s name, priority, notes or completion status',
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id:           { type: 'string', description: 'Todo ID' },
+        name:         { type: 'string' },
+        priority:     { type: 'string', enum: ['high', 'medium', 'low'] },
+        notes:        { type: 'string' },
+        is_completed: { type: 'boolean' }
+      }
+    }
+  },
+  {
+    name: 'delete_todo',
+    description: 'Delete a todo by name or ID',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Todo name or ID' }
+      }
+    }
+  },
+  {
+    name: 'star_topic',
+    description: 'Star (favourite) or unstar a topic/subtopic.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'starred'],
+      properties: {
+        name:    { type: 'string', description: 'Topic name or ID' },
+        starred: { type: 'boolean', description: 'true = add to favourites, false = remove' }
+      }
+    }
+  },
+  {
+    name: 'star_major_topic',
+    description: 'Star (favourite) or unstar a major topic.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'starred'],
+      properties: {
+        name:    { type: 'string', description: 'Major topic name or ID' },
+        starred: { type: 'boolean', description: 'true = add to favourites, false = remove' }
+      }
+    }
+  },
+  {
+    name: 'pin_major_topic',
+    description: 'Pin (lock) or unpin a major topic. Unpinning requires PIN if locked.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'pinned'],
+      properties: {
+        name:   { type: 'string', description: 'Major topic name or ID' },
+        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' },
+        pin:    { type: 'string', description: 'Optional PIN required if currently locked and unpinning' }
+      }
+    }
+  },
+  {
+    name: 'pin_topic',
+    description: 'Pin (lock) or unpin a topic. Unpinning requires PIN if locked.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'pinned'],
+      properties: {
+        name:   { type: 'string', description: 'Topic name or ID' },
+        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' },
+        pin:    { type: 'string', description: 'Optional PIN required if currently locked and unpinning' }
+      }
+    }
+  },
+  {
+    name: 'set_major_topic_color',
+    description: 'Change the colour of a major topic. PIN required if locked.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'color'],
+      properties: {
+        name:  { type: 'string', description: 'Major topic name or ID' },
+        color: { type: 'string', description: 'Hex colour or color name' },
+        pin:   { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'set_topic_color',
+    description: 'Change the colour of a topic. PIN required if locked.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'color'],
+      properties: {
+        name:  { type: 'string', description: 'Topic name or ID' },
+        color: { type: 'string', description: 'Hex colour or color name' },
+        pin:   { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'rename_major_topic',
+    description: 'Rename a major topic. PIN required if locked.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'new_name'],
+      properties: {
+        name:     { type: 'string', description: 'CURRENT major topic name or ID' },
+        new_name: { type: 'string', description: 'The NEW name' },
+        pin:      { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'rename_topic',
+    description: 'Rename a topic. PIN required if locked.',
+    inputSchema: {
+      type: 'object',
+      required: ['name', 'new_name'],
+      properties: {
+        name:     { type: 'string', description: 'CURRENT topic name or ID' },
+        new_name: { type: 'string', description: 'The NEW name' },
+        pin:      { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'set_pin',
+    description: 'Set or update the security PIN for KARMA 365. Used to unlock, view, edit, or delete locked/PIN-protected topics and categories.',
+    inputSchema: {
+      type: 'object',
+      required: ['new_pin'],
+      properties: {
+        new_pin:     { type: 'string', description: 'New numeric PIN (e.g. 111111)' },
+        current_pin: { type: 'string', description: 'Current PIN (required if a PIN is already set)' }
+      }
+    }
+  },
+  {
+    name: 'verify_pin',
+    description: 'Verify if a PIN is correct against the KARMA 365 master PIN',
+    inputSchema: {
+      type: 'object',
+      required: ['pin'],
+      properties: {
+        pin: { type: 'string', description: 'PIN to test' }
+      }
+    }
+  },
+  {
+    name: 'delete_completed_todos',
+    description: 'Delete ALL completed todos/tasks at once.',
+    inputSchema: { type: 'object', properties: {} }
+  },
+  {
+    name: 'clean_empty_major_topics',
+    description: 'Delete all major topics that have no resources in any of their subtopics.',
+    inputSchema: { type: 'object', properties: {} }
+  },
+  {
+    name: 'get_stats',
+    description: 'Get KARMA 365 dashboard statistics: topic counts, resource completion, todos',
+    inputSchema: { type: 'object', properties: {} }
+  },
+  {
+    name: 'search',
+    description: 'Search across all topics, resources, and todos by keyword',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', description: 'Search keyword' }
+      }
+    }
+  },
+  {
+    name: 'set_dark_mode',
+    description: 'Turn the KARMA 365 app dark mode ON or OFF.',
+    inputSchema: {
+      type: 'object',
+      required: ['enabled'],
+      properties: {
+        enabled: { type: 'boolean', description: 'true = dark mode ON, false = light mode' }
+      }
+    }
+  },
+  {
+    name: 'search_web',
+    description: 'Search the public web for articles/pages by keyword (KEYLESS). Optionally save the results as link resources to a topic.',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query:      { type: 'string', description: 'Web search query' },
+        topic_name: { type: 'string', description: 'If given, save the results as link resources to this topic' }
+      }
+    }
+  }
+]
+
+// ── Phone Live Bridge Setup & Auto-Discovery (Wi-Fi, Hotspot, USB) ─────────
+const EXPLICIT_PHONE_URL = (!LOCAL_ONLY && process.env.KARMA365_PHONE_URL) ? process.env.KARMA365_PHONE_URL.trim().replace(/\/+$/, '') : null
+
+let activePhoneUrl = LOCAL_ONLY ? null : (EXPLICIT_PHONE_URL || readLink()?.phoneUrl || null)
+let isDiscoveryRunning = false
+let lastDiscoveryTime = 0
+
+/** True only if whatever answers at this address proves it holds our device key. */
+async function isOurPhone(baseUrl, timeoutMs = 1200) {
+  const link = readLink()
+  if (!link) return false
+  try {
+    const health = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(timeoutMs), redirect: 'error' })
+    if (!health.ok) return false
+    const reply = await secureCall(baseUrl, link, 'GET', '/api/stats', undefined, Math.max(timeoutMs, 2500))
+    return reply.status === 200 || reply.status === 423
+  } catch (_) {
+    return false
+  }
+}
+
+function rememberPhoneUrl(url) {
+  const link = readLink()
+  if (link && !link.fromToken && link.phoneUrl !== url) {
+    try { writeLink({ ...link, phoneUrl: url }) } catch (_) {}
+  }
+}
+
+async function autoDiscoverPhone(force = false) {
+  if (LOCAL_ONLY) return null
+  if (EXPLICIT_PHONE_URL) return EXPLICIT_PHONE_URL
+  const now = Date.now()
+  if (!force && activePhoneUrl && (now - lastDiscoveryTime < 15000)) {
+    return activePhoneUrl
+  }
+  if (isDiscoveryRunning) return activePhoneUrl
+  isDiscoveryRunning = true
+  lastDiscoveryTime = now
+
+  try {
+    // 1. Check cached URL, localhost (USB adb forward), or Android hotspot default gateway
+    const quickCandidates = [
+      activePhoneUrl,
+      'http://127.0.0.1:8365',
+      'http://192.168.43.1:8365',
+    ].filter(Boolean)
+
+    for (const url of quickCandidates) {
+      if (await isOurPhone(url, 1500)) {
+        activePhoneUrl = url
+        rememberPhoneUrl(url)
+        process.stderr.write(`[karma365-mcp] 📱 Connected to KARMA 365 Mobile App: ${url}\n`)
+        return url
+      }
+    }
+
+    // 2. Fast parallel sweep across active PC network interfaces
+    const nets = os.networkInterfaces()
+    const subnets = new Set()
+    for (const name of Object.keys(nets)) {
+      for (const net of nets[name] || []) {
+        if (net.family === 'IPv4' && !net.internal) {
+          const parts = net.address.split('.')
+          if (parts.length === 4) {
+            subnets.add(`${parts[0]}.${parts[1]}.${parts[2]}.`)
+          }
+        }
+      }
+    }
+
+    const checks = []
+    for (const subnet of subnets) {
+      for (let i = 1; i <= 254; i++) {
+        const url = `http://${subnet}${i}:8365`
+        checks.push(
+          isOurPhone(url, 650)
+            .then(ok => (ok ? url : null))
+            .catch(() => null)
+        )
+      }
+    }
+
+    if (checks.length > 0) {
+      const results = await Promise.all(checks)
+      const found = results.find(Boolean)
+      if (found) {
+        activePhoneUrl = found
+        rememberPhoneUrl(found)
+        process.stderr.write(`[karma365-mcp] 📱 Auto-Discovered KARMA 365 Mobile App: ${found}\n`)
+        return found
+      }
+    }
+  } catch (e) {
+    process.stderr.write(`[karma365-mcp] Auto-discovery warning: ${e.message}\n`)
+  } finally {
+    isDiscoveryRunning = false
+  }
+
+  return activePhoneUrl
+}
+
+if (EXPLICIT_PHONE_URL) {
+  process.stderr.write(`[karma365-mcp] Phone Live Bridge Configured: ${EXPLICIT_PHONE_URL} (Paired: ${readLink() ? 'yes' : 'no'})\n`)
+} else {
+  process.stderr.write(`[karma365-mcp] ${LOCAL_ONLY ? `Local database only: ${DB_PATH}` : 'Auto-Discovery Enabled (searching on :8365)'}\n`)
+}
+
+async function callPhoneBridge(name, args) {
+  const link = readLink()
+  if (!link) throw new Error('KARMA365_TOKEN is missing. Copy the config from KARMA 365: Settings, AI MCP.')
+
+  const targetBase = activePhoneUrl || (await autoDiscoverPhone())
+  if (!targetBase) throw new Error('Phone not found. Open KARMA 365, turn on "Allow PC connection", and use the same Wi-Fi.')
+
+  const isLargePayload = args && args.url && String(args.url).length > 50000
+  const call = (base) => secureCall(base, link, 'POST', '/api/execute', { name, args }, isLargePayload ? 120000 : 8000)
+  let reply
+  try {
+    reply = await call(targetBase)
+  } catch (err) {
+    if (err.notPaired) throw err
+    process.stderr.write(`[karma365-mcp] Phone not reachable at ${targetBase} (${err.message}).\n`)
+    activePhoneUrl = null
+    // Try one quick re-discovery if the phone's IP changed on Wi-Fi.
+    const found = await autoDiscoverPhone(true)
+    if (!found || found === targetBase) {
+      throw new Error('Phone not reachable, so nothing was changed. Open KARMA 365 on the same Wi-Fi and try again.')
+    }
+    activePhoneUrl = found
+    reply = await call(found)
+  }
+
+  if (reply.status === 423) throw new Error('KARMA 365 is locked. Unlock it on your phone first.')
+  const data = reply.body || {}
+  if (reply.status === 403 && typeof data.error === 'string') return data.error
+  if (reply.status >= 400 || data.success === false) {
+    throw new Error(data.error || `Phone returned status ${reply.status}`)
+  }
+  return data.result
+}
+
+// Resource type for each add_* tool in local mode (KARMA365_LOCAL_ONLY).
+const RESOURCE_TYPE_MAP = {
+  add_youtube: 'youtube',
+  add_link:    'link',
+  add_pdf:     'pdf',
+  add_audio:   'audio',
+  add_video:   'video',
+  add_image:   'image',
+  add_code:    'code'
+}
+
+async function handleTool(name, args) {
+  let youTubeNote = ''
+  if (name === 'add_youtube') {
+    const video = await checkYouTubeVideo(args.url)
+    if (!video.ok) return video.message
+    args = { ...args }
+    if (!String(args.description || '').trim()) {
+      args.description = video.title || `YouTube video ${video.id}`
+    }
+    if (!video.checked) youTubeNote = '(YouTube could not be reached, so this link was saved without checking it.)'
+    else if (video.restricted) youTubeNote = '(YouTube says this video is private or cannot be played outside YouTube.)'
+    else if (video.title) youTubeNote = `(YouTube: "${video.title}"${video.channel ? ` by ${video.channel}` : ''})`
+  }
+  const reply = await runTool(name, args)
+  // A failed save keeps its message as it is, so the note never hides an error.
+  if (!youTubeNote || typeof reply !== 'string' || !reply.startsWith('✓')) return reply
+  return `${reply} ${youTubeNote}`
+}
+
+async function runTool(name, args) {
+  // If Phone Live Bridge is active or auto-discovered, delegate directly to phone app
+  if (!LOCAL_ONLY && name !== 'search_web') {
+    let argsToSend = { ...args }
+    if (['add_image', 'add_pdf', 'add_audio', 'add_video', 'add_code'].includes(name) && argsToSend.url) {
+      const localPath = String(argsToSend.url).trim()
+      if (fs.existsSync(localPath)) {
+        assertFileMaySend(localPath)
+        try {
+          const ext = path.extname(localPath).toLowerCase()
+          const mimeMap = {
+            '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp',
+            '.pdf': 'application/pdf',
+            '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/m4a',
+            '.mp4': 'video/mp4', '.mov': 'video/quicktime',
+          }
+          const mime = mimeMap[ext] || 'application/octet-stream'
+          const fileBytes = fs.readFileSync(localPath)
+          argsToSend.url = `data:${mime};base64,${fileBytes.toString('base64')}`
+          if (!argsToSend.description && !argsToSend.title) {
+            argsToSend.description = path.basename(localPath)
+          }
+        } catch (e) {
+          process.stderr.write(`[karma365-mcp] Failed to read local file ${localPath}: ${e.message}\n`)
+        }
+      }
+    }
+    const phoneResult = await callPhoneBridge(name, argsToSend)
+    return typeof phoneResult === 'string' ? phoneResult : JSON.stringify(phoneResult ?? {}, null, 2)
+  }
+
+  switch (name) {
+
+    case 'set_dark_mode': {
+      const enabled = args.enabled === true || String(args.enabled).toLowerCase() === 'true'
+      const val = enabled ? 'true' : 'false'
+      db.prepare(`INSERT INTO settings (key, value) VALUES ('dark_mode', ?)
+                  ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(val)
+      return enabled
+        ? '✓ Dark mode turned ON 🌙 (saved to local settings)'
+        : '✓ Dark mode turned OFF — light mode ☀️ (saved to local settings)'
+    }
+
+    case 'list_major_topics': {
+      const rows = db.prepare('SELECT * FROM major_topics ORDER BY sort_order ASC, created_at DESC').all()
+      if (!rows.length) return 'No major topics found. Create one with create_major_topic.'
+      return `Found ${rows.length} major topic(s):\n` +
+        rows.map(m => `• ${m.name}${m.color ? ` [${m.color}]` : ''}${m.is_pinned ? ' 🔒' : ''}${m.is_starred ? ' ⭐' : ''} (ID: ${m.id})`).join('\n')
+    }
+
+    case 'create_major_topic': {
+      const id = newId()
+      const isPinned = args.is_pinned ? 1 : 0
+      db.prepare(`INSERT INTO major_topics (id, name, is_pinned, is_starred, sort_order, created_at, synced)
+                  VALUES (?, ?, ?, 0, 0, ?, 1)`).run(id, args.name.trim(), isPinned, nowIso())
+      return `✓ Created major topic "${args.name}" (ID: ${id})`
+    }
+
+    case 'delete_major_topic': {
+      const item = resolveMajorTopic(args.name)
+      if (item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'deletion')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'deleted')
+      }
+      db.prepare('UPDATE topics SET major_topic_id = NULL WHERE major_topic_id = ?').run(item.id)
+      db.prepare('DELETE FROM major_topics WHERE id = ?').run(item.id)
+      return `✓ Deleted major topic "${item.name}". Subtopics under it have been kept.`
+    }
+
+    case 'rename_major_topic': {
+      const item = resolveMajorTopic(args.name)
+      if (item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'renaming')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'renamed')
+      }
+      const newName = args.new_name.trim()
+      db.prepare('UPDATE major_topics SET name = ? WHERE id = ?').run(newName, item.id)
+      return `✓ Renamed major topic from "${item.name}" to "${newName}"`
+    }
+
+    case 'set_major_topic_color': {
+      const item = resolveMajorTopic(args.name)
+      if (item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'changing colour')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'color-changed')
+      }
+      const color = resolveColor(args.color)
+      db.prepare('UPDATE major_topics SET color = ? WHERE id = ?').run(color, item.id)
+      return `✓ Changed colour of major topic "${item.name}" to ${color}`
+    }
+
+    case 'pin_major_topic': {
+      const item = resolveMajorTopic(args.name)
+      const pinned = args.pinned === true || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      if (!pinned && item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'unlocking')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'unlocked')
+      }
+      db.prepare('UPDATE major_topics SET is_pinned = ? WHERE id = ?').run(pinned, item.id)
+      return pinned ? `✓ Locked/pinned major topic "${item.name}" 🔒` : `✓ Unlocked major topic "${item.name}"`
+    }
+
+    case 'star_major_topic': {
+      const item = resolveMajorTopic(args.name)
+      const starred = args.starred === true || String(args.starred).toLowerCase() === 'true' ? 1 : 0
+      db.prepare('UPDATE major_topics SET is_starred = ? WHERE id = ?').run(starred, item.id)
+      return starred ? `✓ Added major topic "${item.name}" to favourites ⭐` : `✓ Removed major topic "${item.name}" from favourites`
+    }
+
+    case 'list_topics': {
+      let query = `SELECT t.*, m.name as major_name
+                   FROM topics t
+                   LEFT JOIN major_topics m ON t.major_topic_id = m.id
+                   WHERE 1=1`
+      const params = []
+
+      if (args.major_topic_name) {
+        const m = resolveMajorTopic(args.major_topic_name)
+        query += ' AND t.major_topic_id = ?'
+        params.push(m.id)
+      }
+      if (args.difficulty) {
+        query += ' AND t.difficulty = ?'
+        params.push(args.difficulty)
+      }
+      if (args.parent_topic_name) {
+        const p = resolveTopic(args.parent_topic_name)
+        query += ' AND t.parent_topic_id = ?'
+        params.push(p.id)
+      }
+
+      query += ' ORDER BY t.sort_order ASC, t.created_at DESC'
+      const rows = db.prepare(query).all(...params)
+
+      if (!rows.length) return 'No topics found matching criteria.'
+      return `Found ${rows.length} topic(s):\n` +
+        rows.map(t => {
+          const cat = t.major_name ? ` [Category: ${t.major_name}]` : ''
+          const diff = t.difficulty ? ` (${t.difficulty})` : ''
+          const icons = `${t.is_pinned ? ' 🔒' : ''}${t.is_starred ? ' ⭐' : ''}`
+          return `• ${t.name}${cat}${diff}${icons} (ID: ${t.id})`
+        }).join('\n')
+    }
+
+    case 'get_topic': {
+      const topic = resolveTopic(args.name)
+      let majorIsPinned = 0
+      if (topic.major_topic_id) {
+        const m = db.prepare('SELECT is_pinned, name FROM major_topics WHERE id = ?').get(topic.major_topic_id)
+        if (m && m.is_pinned === 1) majorIsPinned = 1
+      }
+      const isLocked = topic.is_pinned === 1 || majorIsPinned === 1
+      if (isLocked) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'opening / reading')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'opened')
+      }
+
+      const resources = db.prepare('SELECT * FROM resources WHERE topic_id = ? ORDER BY sort_order ASC, created_at DESC').all(topic.id)
+      let majorName = null
+      if (topic.major_topic_id) {
+        const m = db.prepare('SELECT name FROM major_topics WHERE id = ?').get(topic.major_topic_id)
+        if (m) majorName = m.name
+      }
+
+      let out = `Topic: ${topic.name}\n`
+      out += `ID: ${topic.id}\n`
+      if (majorName) out += `Category: ${majorName}\n`
+      if (topic.difficulty) out += `Difficulty: ${topic.difficulty}\n`
+      if (topic.color) out += `Color: ${topic.color}\n`
+      if (topic.note) out += `Note: ${topic.note}\n`
+      out += `Status: ${topic.is_pinned ? '🔒 Pinned ' : ''}${topic.is_starred ? '⭐ Starred' : ''}\n\n`
+
+      if (!resources.length) {
+        out += 'Resources: None attached yet.'
+      } else {
+        out += `Resources (${resources.length}):\n`
+        out += resources.map(r =>
+          `• [${r.type.toUpperCase()}] ${r.description || '(no description)'} ${r.is_completed ? '✓' : '○'}\n  ${r.path_or_url}`
+        ).join('\n')
+      }
+      return out
+    }
+
+    case 'create_topic': {
+      let majorId = null
+      if (args.major_topic_name) {
+        const m = resolveMajorTopic(args.major_topic_name)
+        if (m.is_pinned === 1) {
+          const guard = checkPinIfLocked(m.is_pinned, args.pin)
+          if (guard === 'required') return PIN_REQ(m.name, 'adding topic under it')
+          if (guard === 'invalid')  return PIN_BAD(m.name, 'modified')
+        }
+        majorId = m.id
+      }
+      const id = newId()
+      const color = resolveColor(args.color)
+      const isPinned = args.is_pinned === true || args.pinned === true || String(args.is_pinned).toLowerCase() === 'true' || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      db.prepare(`INSERT INTO topics (id, name, difficulty, major_topic_id, color, is_pinned, created_at, synced)
+                  VALUES (?, ?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', majorId, color, isPinned, nowIso())
+      return `✓ Created topic "${args.name}" (ID: ${id})${isPinned ? ' 🔒' : ''}`
+    }
+
+    case 'create_subtopic': {
+      const parent = resolveTopic(args.parent_topic_name)
+      if (parent.is_pinned === 1) {
+        const guard = checkPinIfLocked(parent.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(parent.name, 'adding subtopic under it')
+        if (guard === 'invalid')  return PIN_BAD(parent.name, 'modified')
+      }
+      const id = newId()
+      const isPinned = args.is_pinned === true || args.pinned === true || String(args.is_pinned).toLowerCase() === 'true' || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      db.prepare(`INSERT INTO topics (id, name, difficulty, parent_topic_id, major_topic_id, is_pinned, created_at, synced)
+                  VALUES (?, ?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', parent.id, parent.major_topic_id, isPinned, nowIso())
+      return `✓ Created subtopic "${args.name}" under parent "${parent.name}" (ID: ${id})${isPinned ? ' 🔒' : ''}`
+    }
+
+    case 'delete_topic': {
+      const topic = resolveTopic(args.name)
+      let majorIsPinned = 0
+      if (topic.major_topic_id) {
+        const m = db.prepare('SELECT is_pinned FROM major_topics WHERE id = ?').get(topic.major_topic_id)
+        if (m && m.is_pinned === 1) majorIsPinned = 1
+      }
+      const isLocked = topic.is_pinned === 1 || majorIsPinned === 1
+      if (isLocked) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'deletion')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'deleted')
+      }
+      db.prepare('DELETE FROM resources WHERE topic_id = ?').run(topic.id)
+      db.prepare('DELETE FROM topics WHERE id = ?').run(topic.id)
+      return `✓ Deleted topic "${topic.name}" and all its resources.`
+    }
+
+    case 'rename_topic': {
+      const topic = resolveTopic(args.name)
+      if (isTopicLocked(topic)) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'renaming')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'renamed')
+      }
+      const newName = args.new_name.trim()
+      db.prepare('UPDATE topics SET name = ?, updated_at = ? WHERE id = ?').run(newName, nowIso(), topic.id)
+      return `✓ Renamed topic from "${topic.name}" to "${newName}"`
+    }
+
+    case 'set_topic_color': {
+      const topic = resolveTopic(args.name)
+      if (isTopicLocked(topic)) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'changing colour')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'color-changed')
+      }
+      const color = resolveColor(args.color)
+      db.prepare('UPDATE topics SET color = ?, updated_at = ? WHERE id = ?').run(color, nowIso(), topic.id)
+      return `✓ Changed colour of topic "${topic.name}" to ${color}`
+    }
+
+    case 'pin_topic': {
+      const topic = resolveTopic(args.name)
+      const pinned = args.pinned === true || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      if (!pinned && topic.is_pinned === 1) {
+        const guard = checkPinIfLocked(topic.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'unlocking')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'unlocked')
+      }
+      db.prepare('UPDATE topics SET is_pinned = ?, updated_at = ? WHERE id = ?').run(pinned, nowIso(), topic.id)
+      return pinned ? `✓ Locked/pinned topic "${topic.name}" 🔒` : `✓ Unlocked topic "${topic.name}"`
+    }
+
+    case 'star_topic': {
+      const topic = resolveTopic(args.name)
+      const starred = args.starred === true || String(args.starred).toLowerCase() === 'true' ? 1 : 0
+      db.prepare('UPDATE topics SET is_starred = ?, updated_at = ? WHERE id = ?').run(starred, nowIso(), topic.id)
+      return starred ? `✓ Added topic "${topic.name}" to favourites ⭐` : `✓ Removed topic "${topic.name}" from favourites`
+    }
+
+    case 'list_resources': {
+      const topic = resolveTopic(args.topic_name)
+      if (isTopicLocked(topic)) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'listing its resources')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'opened')
+      }
+      let query = 'SELECT * FROM resources WHERE topic_id = ?'
+      const params = [topic.id]
+      if (args.type) {
+        query += ' AND type = ?'
+        params.push(args.type)
+      }
+      query += ' ORDER BY sort_order ASC, created_at DESC'
+      const rows = db.prepare(query).all(...params)
+      if (!rows.length) return `No resources found for topic "${topic.name}".`
+      return `Found ${rows.length} resource(s) in "${topic.name}":\n` +
+        rows.map(r => `• [${r.type.toUpperCase()}] ${r.description || '(no label)'} ${r.is_completed ? '✓ Done' : '○ Incomplete'}\n  URL/Path: ${r.path_or_url}\n  ID: ${r.id}`).join('\n')
+    }
+
+    case 'add_youtube':
+    case 'add_link':
+    case 'add_pdf':
+    case 'add_audio':
+    case 'add_video':
+    case 'add_image':
+    case 'add_code': {
+      const topic = resolveTopic(args.topic_name)
+      if (isTopicLocked(topic)) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'adding resource to it')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'modified')
+      }
+      const type = RESOURCE_TYPE_MAP[name]
+      const id = newId()
+      let finalPathOrUrl = String(args.url || '').trim()
+
+      // For youtube, extract video ID if present
+      let ytVideoId = null
+      if (type === 'youtube') {
+        const m = finalPathOrUrl.match(/(?:youtu\.be\/|v=|\/embed\/|\/v\/|watch\?v=)([\w-]{11})/)
+        if (m) ytVideoId = m[1]
+      }
+
+      db.prepare(`INSERT INTO resources (id, topic_id, type, description, path_or_url, youtube_video_id, is_completed, created_at, synced)
+                  VALUES (?, ?, ?, ?, ?, ?, 0, ?, 1)`).run(id, topic.id, type, args.description.trim(), finalPathOrUrl, ytVideoId, nowIso())
+      return `✓ Added [${type.toUpperCase()}] "${args.description}" to "${topic.name}" (ID: ${id})`
+    }
+
+    case 'delete_resource': {
+      const row = db.prepare('SELECT * FROM resources WHERE id = ?').get(args.resource_id)
+      if (!row) throw new Error(`Resource not found with ID: "${args.resource_id}"`)
+      let isLocked = row.is_pinned || 0
+      if (!isLocked && row.topic_id) {
+        const t = db.prepare('SELECT is_pinned, major_topic_id FROM topics WHERE id = ?').get(row.topic_id)
+        if (t && t.is_pinned === 1) isLocked = 1
+        else if (t && t.major_topic_id) {
+          const m = db.prepare('SELECT is_pinned FROM major_topics WHERE id = ?').get(t.major_topic_id)
+          if (m && m.is_pinned === 1) isLocked = 1
+        }
+      }
+      if (isLocked) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(row.description || 'Resource', 'deletion')
+        if (guard === 'invalid')  return PIN_BAD(row.description || 'Resource', 'deleted')
+      }
+      db.prepare('DELETE FROM resources WHERE id = ?').run(row.id)
+      return `✓ Deleted resource "${row.description || row.path_or_url}"`
+    }
+
+    case 'set_pin':
+    case 'update_pin': {
+      const newPin = String(args.new_pin ?? args.pin ?? '').trim()
+      const currentPin = args.current_pin ? String(args.current_pin).trim() : undefined
+      if (!newPin) {
+        return '❌ PIN cannot be empty. Please provide a numeric PIN (e.g. 111111).'
+      }
+      if (hasPin()) {
+        if (!currentPin) {
+          return 'PIN_REQUIRED: A PIN is already set. Please provide current_pin to authorize updating to a new PIN.'
+        }
+        if (!verifyPin(currentPin)) {
+          return 'PIN_INVALID: Current PIN is incorrect. Master PIN was NOT updated.'
+        }
+      }
+      setMasterPin(newPin)
+      return `✓ Master PIN successfully updated to ${newPin.replace(/./g, '•')} 🔒`
+    }
+
+    case 'verify_pin': {
+      const pin = String(args.pin ?? '').trim()
+      if (!hasPin()) {
+        return 'ℹ️ No master PIN is set yet. Use set_pin to create one.'
+      }
+      if (verifyPin(pin)) {
+        return '✓ PIN verified successfully.'
+      }
+      return 'PIN_INVALID: Incorrect PIN.'
+    }
+
+    case 'mark_resource_complete': {
+      const isCompleted = args.is_completed === true || String(args.is_completed).toLowerCase() === 'true' ? 1 : 0
+      const row = db.prepare('SELECT * FROM resources WHERE id = ?').get(args.resource_id)
+      if (!row) throw new Error(`Resource not found with ID: "${args.resource_id}"`)
+      db.prepare('UPDATE resources SET is_completed = ? WHERE id = ?').run(isCompleted, row.id)
+      return `✓ Resource marked as ${isCompleted ? 'completed ✓' : 'incomplete ○'}`
+    }
+
+    case 'list_todos': {
+      let query = 'SELECT * FROM todos WHERE 1=1'
+      const params = []
+      if (args.priority) {
+        query += ' AND priority = ?'
+        params.push(args.priority.toLowerCase())
+      }
+      if (args.is_completed !== undefined) {
+        query += ' AND is_completed = ?'
+        params.push(args.is_completed ? 1 : 0)
+      }
+      query += ' ORDER BY created_at DESC'
+      const rows = db.prepare(query).all(...params)
+      if (!rows.length) return 'No todos found.'
+      return `Found ${rows.length} task(s):\n` +
+        rows.map(t => `• [${t.is_completed ? '✓ Done' : '○ Todo'}] ${t.name} (Priority: ${t.priority})${t.notes ? ` - ${t.notes}` : ''} (ID: ${t.id})`).join('\n')
+    }
+
+    case 'create_todo': {
+      const id = newId()
+      const now = nowIso()
+      db.prepare(`INSERT INTO todos (id, name, priority, notes, is_completed, created_at, updated_at)
+                  VALUES (?, ?, ?, ?, 0, ?, ?)`).run(id, args.name.trim(), (args.priority || 'medium').toLowerCase(), args.notes || '', now, now)
+      return `✓ Created todo "${args.name}" (ID: ${id})`
+    }
+
+    case 'complete_todo': {
+      const item = resolveTodo(args.name)
+      db.prepare('UPDATE todos SET is_completed = 1, updated_at = ? WHERE id = ?').run(nowIso(), item.id)
+      return `✓ Completed task "${item.name}" 🎉`
+    }
+
+    case 'update_todo': {
+      const item = db.prepare('SELECT * FROM todos WHERE id = ?').get(args.id)
+      if (!item) throw new Error(`Todo not found with ID: "${args.id}"`)
+
+      const name = args.name !== undefined ? args.name.trim() : item.name
+      const priority = args.priority !== undefined ? args.priority.toLowerCase() : item.priority
+      const notes = args.notes !== undefined ? args.notes : item.notes
+      const isCompleted = args.is_completed !== undefined ? (args.is_completed ? 1 : 0) : item.is_completed
+
+      db.prepare(`UPDATE todos SET name = ?, priority = ?, notes = ?, is_completed = ?, updated_at = ?
+                  WHERE id = ?`).run(name, priority, notes, isCompleted, nowIso(), item.id)
+      return `✓ Updated todo "${name}"`
+    }
+
+    case 'delete_todo': {
+      const item = resolveTodo(args.name)
+      db.prepare('DELETE FROM todos WHERE id = ?').run(item.id)
+      return `✓ Deleted todo "${item.name}"`
+    }
+
+    case 'delete_completed_todos': {
+      const res = db.prepare('DELETE FROM todos WHERE is_completed = 1').run()
+      return `✓ Removed ${res.changes || 0} completed task(s).`
+    }
+
+    case 'write_topic_note': {
+      const topic = resolveTopic(args.topic_name)
+      if (isTopicLocked(topic)) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'writing/updating note')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'updated')
+      }
+      const existing = (topic.note || '').trim()
+      const newNote = existing ? `${existing}\n\n${args.note.trim()}` : args.note.trim()
+      const title = args.title ? args.title.trim() : topic.note_title
+      db.prepare('UPDATE topics SET note = ?, note_title = ?, updated_at = ? WHERE id = ?')
+        .run(newNote, title, nowIso(), topic.id)
+      return `✓ Note saved to topic "${topic.name}"`
+    }
+
+    case 'clean_empty_major_topics': {
+      const allMajor = db.prepare('SELECT * FROM major_topics').all()
+      let removed = 0
+      for (const m of allMajor) {
+        const countRow = db.prepare(`
+          SELECT count(r.id) as count
+          FROM topics t
+          LEFT JOIN resources r ON r.topic_id = t.id
+          WHERE t.major_topic_id = ?
+        `).get(m.id)
+        if (!countRow || countRow.count === 0) {
+          db.prepare('DELETE FROM major_topics WHERE id = ?').run(m.id)
+          removed++
+        }
+      }
+      return `✓ Cleaned ${removed} empty major topic(s) with no resources.`
+    }
+
+    case 'get_stats': {
+      const majorCount = db.prepare('SELECT count(*) as count FROM major_topics').get().count
+      const topicCount = db.prepare('SELECT count(*) as count FROM topics').get().count
+      const resTotal = db.prepare('SELECT count(*) as count FROM resources').get().count
+      const resDone = db.prepare('SELECT count(*) as count FROM resources WHERE is_completed = 1').get().count
+      const todoTotal = db.prepare('SELECT count(*) as count FROM todos').get().count
+      const todoDone = db.prepare('SELECT count(*) as count FROM todos WHERE is_completed = 1').get().count
+
+      const completionPct = resTotal > 0 ? Math.round((resDone / resTotal) * 100) : 0
+      return `📊 KARMA 365 Statistics:\n` +
+        `• Major Topics: ${majorCount}\n` +
+        `• Topics: ${topicCount}\n` +
+        `• Resources: ${resTotal} total (${resDone} studied / ${completionPct}%)\n` +
+        `• Tasks: ${todoTotal} total (${todoDone} completed)\n` +
+        `• Storage: Local SQLite DB (${DB_PATH})`
+    }
+
+    case 'search': {
+      const q = `%${args.query.trim().toLowerCase()}%`
+      const pinOk = Boolean(args.pin) && verifyPin(args.pin)
+      const topics = db.prepare('SELECT * FROM topics WHERE LOWER(name) LIKE ? OR LOWER(note) LIKE ? LIMIT 10').all(q, q)
+        .filter((row) => pinOk || !isTopicLocked(row))
+      const resources = db.prepare('SELECT * FROM resources WHERE LOWER(description) LIKE ? OR LOWER(path_or_url) LIKE ? LIMIT 10').all(q, q)
+        .filter((row) => {
+          if (pinOk) return true
+          if (row.is_pinned === 1) return false
+          const owner = db.prepare('SELECT * FROM topics WHERE id = ?').get(row.topic_id)
+          return !owner || !isTopicLocked(owner)
+        })
+      const todos = db.prepare('SELECT * FROM todos WHERE LOWER(name) LIKE ? OR LOWER(notes) LIKE ? LIMIT 10').all(q, q)
+
+      let out = `Search results for "${args.query}":\n`
+      if (topics.length) {
+        out += `\nTopics (${topics.length}):\n` + topics.map(t => `• ${t.name} (ID: ${t.id})`).join('\n')
+      }
+      if (resources.length) {
+        out += `\nResources (${resources.length}):\n` + resources.map(r => `• [${r.type}] ${r.description} (${r.path_or_url})`).join('\n')
+      }
+      if (todos.length) {
+        out += `\nTodos (${todos.length}):\n` + todos.map(t => `• ${t.name} [${t.priority}]`).join('\n')
+      }
+      if (!topics.length && !resources.length && !todos.length) {
+        out += 'No matching items found.'
+      }
+      return out
+    }
+
+    case 'search_web': {
+      const results = await searchWebKeyless(args.query)
+      let out = `Web search results for "${args.query}":\n` +
+        results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ''}`).join('\n\n')
+
+      if (args.topic_name) {
+        if (!LOCAL_ONLY) {
+          for (const item of results) {
+            await callPhoneBridge('add_link', { topic_name: args.topic_name, url: item.url, description: item.title })
+          }
+          out += `\n\n✓ Saved ${results.length} search links directly to topic "${args.topic_name}" on mobile app.`
+          return out
+        }
+        const topic = resolveTopic(args.topic_name)
+        for (const item of results) {
+          db.prepare(`INSERT INTO resources (id, topic_id, type, description, path_or_url, is_completed, created_at, synced)
+                      VALUES (?, ?, 'link', ?, ?, 0, ?, 1)`).run(newId(), topic.id, item.title, item.url, nowIso())
+        }
+        out += `\n\n✓ Saved ${results.length} search links directly to topic "${topic.name}".`
+      }
+      return out
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`)
+  }
+}
+
+// ── MCP Server Startup ────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'karma365-mcp', version: '2.1.0' },
+  { capabilities: { tools: {} } }
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS }
+})
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    const text = await handleTool(request.params.name, request.params.arguments || {})
+    return { content: [{ type: 'text', text: String(text) }] }
+  } catch (err) {
+    return { content: [{ type: 'text', text: `ERROR: ${err.message}` }], isError: true }
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+process.stderr.write('[karma365-mcp] Server running on stdio transport (Zero-Server mode)\n')
+
+// Trigger background phone discovery on network
+if (!LOCAL_ONLY) autoDiscoverPhone().catch(() => {})