burn-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,68 @@
+# Burn MCP Server
+
+Let Claude Desktop, Cursor, or any MCP-compatible AI tool access your Burn Vault.
+
+## Setup
+
+### 1. Get your access token
+
+Open Burn App → Settings → MCP Server → **Copy Access Token**
+
+### 2. Configure Claude Desktop
+
+Add to your `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "burn": {
+      "command": "npx",
+      "args": ["burn-mcp-server"],
+      "env": {
+        "BURN_SUPABASE_TOKEN": "<paste-your-token-here>"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+The Burn tools will appear in the tools menu.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_vault` | Search Vault bookmarks by keyword |
+| `get_bookmark` | Get full details of a single bookmark |
+| `list_categories` | List all Vault categories with counts |
+| `get_clusters` | Get AI-generated topic clusters |
+| `get_cluster_digest` | Get cluster digest (summary + relationships) |
+
+## Available Resources
+
+| URI | Description |
+|-----|-------------|
+| `burn://vault/bookmarks` | All Vault bookmarks (JSON) |
+| `burn://vault/categories` | Category list (JSON) |
+
+## Example prompts
+
+- "What did I save about SwiftUI animations?"
+- "Summarize my AI-related bookmarks"
+- "Reference my Vault article about API design patterns"
+- "What are the main topics in my knowledge base?"
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BURN_SUPABASE_TOKEN` | Yes | Your Burn access token (JWT) |
+| `BURN_SUPABASE_URL` | No | Custom Supabase URL (default: production) |
+
+## Security
+
+- Your token only grants access to **your own** Vault (enforced by Row Level Security)
+- The MCP Server is **read-only** — it cannot modify your bookmarks
+- Tokens expire; regenerate from the Burn App if needed

package/dist/index.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const supabase_js_1 = require("@supabase/supabase-js");
+const zod_1 = require("zod");
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const SUPABASE_URL = process.env.BURN_SUPABASE_URL || 'https://juqtxylquemiuvvmgbej.supabase.co';
+const SUPABASE_TOKEN = process.env.BURN_SUPABASE_TOKEN;
+if (!SUPABASE_TOKEN) {
+    console.error('Error: BURN_SUPABASE_TOKEN environment variable is required.');
+    console.error('Get your token from: Burn App → Settings → MCP Server → Copy Access Token');
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// Supabase client (authenticated as user via JWT)
+// ---------------------------------------------------------------------------
+const supabase = (0, supabase_js_1.createClient)(SUPABASE_URL, SUPABASE_TOKEN, {
+    auth: {
+        persistSession: false,
+        autoRefreshToken: false,
+    },
+    global: {
+        headers: {
+            Authorization: `Bearer ${SUPABASE_TOKEN}`,
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new mcp_js_1.McpServer({
+    name: 'burn-mcp-server',
+    version: '1.0.0',
+});
+// ---------------------------------------------------------------------------
+// Tool: search_vault
+// ---------------------------------------------------------------------------
+server.tool('search_vault', 'Search your Burn Vault for bookmarks by keyword', {
+    query: zod_1.z.string().describe('Search keyword'),
+    limit: zod_1.z.number().optional().default(10).describe('Max results (default 10)'),
+}, async ({ query, limit }) => {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('id, url, title, author, ai_positioning, ai_takeaway, tags, vault_category, vaulted_at')
+        .eq('status', 'vault')
+        .or(`title.ilike.%${query}%,ai_takeaway.cs.{${query}},tags.cs.{${query}}`)
+        .order('vaulted_at', { ascending: false })
+        .limit(limit || 10);
+    if (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(data, null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool: get_bookmark
+// ---------------------------------------------------------------------------
+server.tool('get_bookmark', 'Get full details of a single bookmark including AI analysis and content', {
+    id: zod_1.z.string().describe('Bookmark UUID'),
+}, async ({ id }) => {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('*')
+        .eq('id', id)
+        .single();
+    if (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(data, null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool: list_categories
+// ---------------------------------------------------------------------------
+server.tool('list_categories', 'List all Vault categories with article counts', {}, async () => {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('vault_category')
+        .eq('status', 'vault');
+    if (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+    }
+    // Group by category and count
+    const counts = {};
+    for (const row of data || []) {
+        const cat = row.vault_category || 'Uncategorized';
+        counts[cat] = (counts[cat] || 0) + 1;
+    }
+    const categories = Object.entries(counts)
+        .map(([category, count]) => ({ category, count }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(categories, null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool: get_clusters
+// ---------------------------------------------------------------------------
+server.tool('get_clusters', 'Get AI-generated topic clusters from your Vault', {}, async () => {
+    const { data, error } = await supabase
+        .from('vault_clusters')
+        .select('clusters, generated_at, stale')
+        .single();
+    if (error) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: error.code === 'PGRST116'
+                        ? 'No clusters generated yet. Open the Vault tab in Burn to generate clusters.'
+                        : `Error: ${error.message}`,
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    clusters: data.clusters,
+                    generatedAt: data.generated_at,
+                    isStale: data.stale,
+                }, null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool: get_cluster_digest
+// ---------------------------------------------------------------------------
+server.tool('get_cluster_digest', 'Get the AI-generated digest (summary, insights, relationships) for a topic cluster', {
+    clusterName: zod_1.z.string().describe('Name of the cluster'),
+}, async ({ clusterName }) => {
+    const { data, error } = await supabase
+        .from('cluster_digests')
+        .select('digest, generated_at')
+        .eq('cluster_name', clusterName)
+        .single();
+    if (error) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: error.code === 'PGRST116'
+                        ? `No digest found for cluster "${clusterName}". Open the cluster in Burn App to generate a digest first.`
+                        : `Error: ${error.message}`,
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    ...data.digest,
+                    generatedAt: data.generated_at,
+                }, null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Resource: burn://vault/bookmarks
+// ---------------------------------------------------------------------------
+server.resource('vault-bookmarks', 'burn://vault/bookmarks', async (uri) => {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('id, url, title, author, ai_positioning, tags, vault_category, vaulted_at')
+        .eq('status', 'vault')
+        .order('vaulted_at', { ascending: false });
+    if (error) {
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ error: error.message }) }] };
+    }
+    return {
+        contents: [{
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify(data, null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Resource: burn://vault/categories
+// ---------------------------------------------------------------------------
+server.resource('vault-categories', 'burn://vault/categories', async (uri) => {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('vault_category')
+        .eq('status', 'vault');
+    if (error) {
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ error: error.message }) }] };
+    }
+    const counts = {};
+    for (const row of data || []) {
+        const cat = row.vault_category || 'Uncategorized';
+        counts[cat] = (counts[cat] || 0) + 1;
+    }
+    return {
+        contents: [{
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify(Object.entries(counts).map(([category, count]) => ({ category, count })), null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('Burn MCP Server running on stdio');
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "burn-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for Burn — access your Vault from Claude/Cursor",
+  "main": "dist/index.js",
+  "bin": {
+    "burn-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.39.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { createClient, SupabaseClient } from '@supabase/supabase-js'
+import { z } from 'zod'
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const SUPABASE_URL = process.env.BURN_SUPABASE_URL || 'https://juqtxylquemiuvvmgbej.supabase.co'
+const SUPABASE_TOKEN = process.env.BURN_SUPABASE_TOKEN
+
+if (!SUPABASE_TOKEN) {
+  console.error('Error: BURN_SUPABASE_TOKEN environment variable is required.')
+  console.error('Get your token from: Burn App → Settings → MCP Server → Copy Access Token')
+  process.exit(1)
+}
+
+// ---------------------------------------------------------------------------
+// Supabase client (authenticated as user via JWT)
+// ---------------------------------------------------------------------------
+
+const supabase: SupabaseClient = createClient(SUPABASE_URL, SUPABASE_TOKEN, {
+  auth: {
+    persistSession: false,
+    autoRefreshToken: false,
+  },
+  global: {
+    headers: {
+      Authorization: `Bearer ${SUPABASE_TOKEN}`,
+    },
+  },
+})
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+  name: 'burn-mcp-server',
+  version: '1.0.0',
+})
+
+// ---------------------------------------------------------------------------
+// Tool: search_vault
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'search_vault',
+  'Search your Burn Vault for bookmarks by keyword',
+  {
+    query: z.string().describe('Search keyword'),
+    limit: z.number().optional().default(10).describe('Max results (default 10)'),
+  },
+  async ({ query, limit }) => {
+    const { data, error } = await supabase
+      .from('bookmarks')
+      .select('id, url, title, author, ai_positioning, ai_takeaway, tags, vault_category, vaulted_at')
+      .eq('status', 'vault')
+      .or(`title.ilike.%${query}%,ai_takeaway.cs.{${query}},tags.cs.{${query}}`)
+      .order('vaulted_at', { ascending: false })
+      .limit(limit || 10)
+
+    if (error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${error.message}` }] }
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(data, null, 2),
+      }],
+    }
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Tool: get_bookmark
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'get_bookmark',
+  'Get full details of a single bookmark including AI analysis and content',
+  {
+    id: z.string().describe('Bookmark UUID'),
+  },
+  async ({ id }) => {
+    const { data, error } = await supabase
+      .from('bookmarks')
+      .select('*')
+      .eq('id', id)
+      .single()
+
+    if (error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${error.message}` }] }
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(data, null, 2),
+      }],
+    }
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Tool: list_categories
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'list_categories',
+  'List all Vault categories with article counts',
+  {},
+  async () => {
+    const { data, error } = await supabase
+      .from('bookmarks')
+      .select('vault_category')
+      .eq('status', 'vault')
+
+    if (error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${error.message}` }] }
+    }
+
+    // Group by category and count
+    const counts: Record<string, number> = {}
+    for (const row of data || []) {
+      const cat = row.vault_category || 'Uncategorized'
+      counts[cat] = (counts[cat] || 0) + 1
+    }
+
+    const categories = Object.entries(counts)
+      .map(([category, count]) => ({ category, count }))
+      .sort((a, b) => b.count - a.count)
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(categories, null, 2),
+      }],
+    }
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Tool: get_clusters
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'get_clusters',
+  'Get AI-generated topic clusters from your Vault',
+  {},
+  async () => {
+    const { data, error } = await supabase
+      .from('vault_clusters')
+      .select('clusters, generated_at, stale')
+      .single()
+
+    if (error) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: error.code === 'PGRST116'
+            ? 'No clusters generated yet. Open the Vault tab in Burn to generate clusters.'
+            : `Error: ${error.message}`,
+        }],
+      }
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          clusters: data.clusters,
+          generatedAt: data.generated_at,
+          isStale: data.stale,
+        }, null, 2),
+      }],
+    }
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Tool: get_cluster_digest
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'get_cluster_digest',
+  'Get the AI-generated digest (summary, insights, relationships) for a topic cluster',
+  {
+    clusterName: z.string().describe('Name of the cluster'),
+  },
+  async ({ clusterName }) => {
+    const { data, error } = await supabase
+      .from('cluster_digests')
+      .select('digest, generated_at')
+      .eq('cluster_name', clusterName)
+      .single()
+
+    if (error) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: error.code === 'PGRST116'
+            ? `No digest found for cluster "${clusterName}". Open the cluster in Burn App to generate a digest first.`
+            : `Error: ${error.message}`,
+        }],
+      }
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          ...data.digest,
+          generatedAt: data.generated_at,
+        }, null, 2),
+      }],
+    }
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Resource: burn://vault/bookmarks
+// ---------------------------------------------------------------------------
+
+server.resource(
+  'vault-bookmarks',
+  'burn://vault/bookmarks',
+  async (uri) => {
+    const { data, error } = await supabase
+      .from('bookmarks')
+      .select('id, url, title, author, ai_positioning, tags, vault_category, vaulted_at')
+      .eq('status', 'vault')
+      .order('vaulted_at', { ascending: false })
+
+    if (error) {
+      return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ error: error.message }) }] }
+    }
+
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(data, null, 2),
+      }],
+    }
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Resource: burn://vault/categories
+// ---------------------------------------------------------------------------
+
+server.resource(
+  'vault-categories',
+  'burn://vault/categories',
+  async (uri) => {
+    const { data, error } = await supabase
+      .from('bookmarks')
+      .select('vault_category')
+      .eq('status', 'vault')
+
+    if (error) {
+      return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ error: error.message }) }] }
+    }
+
+    const counts: Record<string, number> = {}
+    for (const row of data || []) {
+      const cat = row.vault_category || 'Uncategorized'
+      counts[cat] = (counts[cat] || 0) + 1
+    }
+
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(
+          Object.entries(counts).map(([category, count]) => ({ category, count })),
+          null, 2
+        ),
+      }],
+    }
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  console.error('Burn MCP Server running on stdio')
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err)
+  process.exit(1)
+})

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}