karma365-mcp 2.0.0

package/index.js

@@ -0,0 +1,1446 @@
+#!/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(() => {})