burn-mcp-server 1.4.0 → 2.0.1

package/README.md

@@ -1,16 +1,24 @@
-# Burn MCP Server
+# Burn — Personal Knowledge Base MCP Server
 
-Let Claude Desktop, Cursor, or any MCP-compatible AI tool access your Burn Vault.
+Your reading data as an AI-accessible knowledge base. 22 tools for Claude, Cursor, Windsurf, and any MCP-compatible agent.
 
-## Setup
+## How it works
 
-### 1. Get your access token
+Burn triages your reading with a 24h timer:
+- **Flame** → New links. 24h to read or they burn.
+- **Spark** → You read it. Stays 30 days.
+- **Vault** → Permanent. Your curated knowledge.
+- **Ash** → Expired. They had their chance.
 
-Open Burn App → Settings → MCP Server → **Copy Access Token**
+The MCP server lets your AI agent search, triage, organize, and analyze everything you've saved.
+
+## Quick Start
 
-### 2. Configure Claude Desktop
+### 1. Get your token
 
-Add to your `~/.config/claude/claude_desktop_config.json`:
+Open Burn App → Settings → MCP Server → **Copy Access Token**
+
+### 2. Add to Claude Desktop
 
 ```json
 {
@@ -19,50 +27,99 @@ Add to your `~/.config/claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["burn-mcp-server"],
       "env": {
-        "BURN_SUPABASE_TOKEN": "<paste-your-token-here>"
+        "BURN_MCP_TOKEN": "<your-token>"
       }
     }
   }
 }
 ```
 
-### 3. Restart Claude Desktop
+### 3. Start asking
+
+- "What did I save about system design?"
+- "Triage my Flame — what should I keep?"
+- "Create a collection from my AI bookmarks"
+
+## Tools (22)
+
+### Search & Read
+
+| Tool | What it does |
+|------|-------------|
+| `search_vault` | Search permanent bookmarks by keyword |
+| `list_vault` | List Vault bookmarks by category |
+| `list_sparks` | List recently read bookmarks (30-day window) |
+| `search_sparks` | Search Sparks by keyword |
+| `list_flame` | List inbox — what's about to burn |
+| `get_flame_detail` | Full detail on a Flame bookmark |
+| `get_bookmark` | Get any bookmark by ID |
+| `get_article_content` | Get full article content + analysis |
+| `fetch_content` | Fetch content from a URL (X, Reddit, YouTube, WeChat) |
+| `list_categories` | All Vault categories with counts |
+| `get_collections` | List all Collections |
+| `get_collection_overview` | Collection detail with AI overview |
+
+### Triage (Agent as your filter)
+
+| Tool | What it does |
+|------|-------------|
+| `move_flame_to_spark` | Keep it — worth reading. Optional insight. |
+| `move_flame_to_ash` | Burn it. Optional reason. |
+| `move_spark_to_vault` | Promote to permanent. Optional category. |
+| `move_spark_to_ash` | Not valuable enough to keep. |
+| `batch_triage_flame` | Triage up to 20 at once. |
+
+### Collections (Agent as your curator)
 
-The Burn tools will appear in the tools menu.
+| Tool | What it does |
+|------|-------------|
+| `create_collection` | Create a topic bundle with initial bookmarks |
+| `add_to_collection` | Add bookmarks (deduplicates) |
+| `remove_from_collection` | Remove bookmarks |
+| `update_collection_overview` | Write AI overview (theme, synthesis, gaps) |
 
-## Available Tools
+### Analysis (Agent as your analyst)
 
-| Tool | Description |
+| Tool | What it does |
 |------|-------------|
-| `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) |
+| `write_bookmark_analysis` | Write structured analysis back to a bookmark |
 
-## Available Resources
+## Resources
 
-| URI | Description |
-|-----|-------------|
+| URI | Content |
+|-----|---------|
 | `burn://vault/bookmarks` | All Vault bookmarks (JSON) |
 | `burn://vault/categories` | Category list (JSON) |
 
-## Example prompts
+## Use Cases
+
+**Personal knowledge management** — Your agent searches your reading history to answer questions, find patterns, and surface forgotten gems.
+
+**Research workflows** — Create collections on topics you're exploring. Agent writes overviews synthesizing your sources.
 
-- "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?"
+**Reading triage** — Agent reviews your Flame inbox, reads the content, decides what's worth keeping based on your interests.
+
+**Cross-tool intelligence** — Use with Claude Code, Cursor, or Windsurf. Your bookmarks become context for coding, writing, and thinking.
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `BURN_SUPABASE_TOKEN` | Yes | Your Burn access token (JWT) |
-| `BURN_SUPABASE_URL` | No | Custom Supabase URL (default: production) |
+| `BURN_MCP_TOKEN` | Yes* | Long-lived MCP token (recommended) |
+| `BURN_SUPABASE_TOKEN` | Yes* | Legacy JWT token (still supported) |
+| `BURN_API_URL` | No | Custom API URL (default: production) |
+
+*One of `BURN_MCP_TOKEN` or `BURN_SUPABASE_TOKEN` required.
 
 ## 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
+- Token scoped to your data only (Row Level Security)
+- Status flow enforced: Flame → Spark → Vault, or → Ash
+- Rate limit: 30 calls/min per session
+- Tokens expire after 30 days
+
+## Links
+
+- **App**: [burn451.app](https://burn451.app)
+- **npm**: [burn-mcp-server](https://www.npmjs.com/package/burn-mcp-server)
+- **Chrome Extension**: Search "Bookmark Autopsy" on Chrome Web Store

package/dist/index.js

@@ -135,7 +135,7 @@ function checkRateLimit() {
 // ---------------------------------------------------------------------------
 const server = new mcp_js_1.McpServer({
     name: 'burn-mcp-server',
-    version: '1.3.0',
+    version: '2.0.0',
 });
 // ---------------------------------------------------------------------------
 // Helper: standard text result
@@ -144,6 +144,51 @@ function textResult(text) {
     return { content: [{ type: 'text', text }] };
 }
 // ---------------------------------------------------------------------------
+// Helper: verify bookmark exists and has expected status
+// ---------------------------------------------------------------------------
+async function verifyBookmark(id, expectedStatus) {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('*')
+        .eq('id', id)
+        .single();
+    if (error)
+        return { data: null, error: error.code === 'PGRST116' ? 'Bookmark not found' : error.message };
+    if (expectedStatus) {
+        const allowed = Array.isArray(expectedStatus) ? expectedStatus : [expectedStatus];
+        if (!allowed.includes(data.status)) {
+            const statusLabels = { active: 'Flame', read: 'Spark', absorbed: 'Vault', ash: 'Ash' };
+            return { data, error: `Bookmark is in ${statusLabels[data.status] || data.status} (expected ${allowed.map(s => statusLabels[s] || s).join(' or ')})` };
+        }
+    }
+    return { data, error: null };
+}
+// ---------------------------------------------------------------------------
+// Helper: merge fields into content_metadata JSONB without overwriting
+// ---------------------------------------------------------------------------
+async function mergeContentMetadata(bookmarkId, fields, extraColumns) {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('content_metadata')
+        .eq('id', bookmarkId)
+        .single();
+    if (error)
+        return { error: error.message };
+    const existing = (data.content_metadata || {});
+    // Only merge non-undefined fields
+    const cleaned = {};
+    for (const [k, v] of Object.entries(fields)) {
+        if (v !== undefined && v !== null)
+            cleaned[k] = v;
+    }
+    const merged = { ...existing, ...cleaned };
+    const { error: updateError } = await supabase
+        .from('bookmarks')
+        .update({ content_metadata: merged, ...extraColumns })
+        .eq('id', bookmarkId);
+    return { error: updateError?.message || null };
+}
+// ---------------------------------------------------------------------------
 // Helper: extract fields from content_metadata JSONB
 // ---------------------------------------------------------------------------
 function meta(row) {
@@ -194,6 +239,39 @@ function metaSummary(row) {
         aiTakeaway: m.ai_takeaway || [],
     };
 }
+/** Flame-specific summary with countdown and AI triage fields */
+function flameSummary(row) {
+    const m = row.content_metadata || {};
+    const expiresAt = row.countdown_expires_at ? new Date(row.countdown_expires_at) : null;
+    const now = new Date();
+    const remainingMs = expiresAt ? expiresAt.getTime() - now.getTime() : 0;
+    const remainingHours = Math.max(0, Math.round(remainingMs / 3600000 * 10) / 10);
+    return {
+        id: row.id,
+        url: row.url,
+        title: row.title,
+        author: m.author || null,
+        platform: row.platform,
+        tags: m.tags || [],
+        createdAt: row.created_at,
+        expiresAt: row.countdown_expires_at,
+        remainingHours,
+        isBurning: remainingHours <= 6,
+        isCritical: remainingHours <= 1,
+        aiPositioning: m.ai_positioning || null,
+        aiDensity: m.ai_density || null,
+        aiMinutes: m.ai_minutes || null,
+        aiTakeaway: m.ai_takeaway || [],
+        aiStrategy: m.ai_strategy || null,
+        aiStrategyReason: m.ai_strategy_reason || null,
+        aiHowToRead: m.ai_how_to_read || null,
+        aiRelevance: m.ai_relevance || null,
+        aiNovelty: m.ai_novelty || null,
+        aiOverlap: m.ai_overlap || null,
+        aiHook: m.ai_hook || null,
+        aiAbout: m.ai_about || [],
+    };
+}
 // ---------------------------------------------------------------------------
 // Tool handlers (all wrapped with rate limiting)
 // ---------------------------------------------------------------------------
@@ -528,6 +606,55 @@ async function handleSearchSparks(args) {
     });
     return textResult(JSON.stringify(results, null, 2));
 }
+async function handleListFlame(args) {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('*')
+        .eq('status', 'active')
+        .order('created_at', { ascending: false })
+        .limit(args.limit || 20);
+    if (error)
+        return textResult(`Error: ${error.message}`);
+    // Filter out already expired ones (should be ash but not yet processed)
+    const now = new Date();
+    const results = (data || [])
+        .filter((row) => {
+        if (!row.countdown_expires_at)
+            return true;
+        return new Date(row.countdown_expires_at).getTime() > now.getTime();
+    })
+        .map(flameSummary);
+    return textResult(JSON.stringify(results, null, 2));
+}
+async function handleGetFlameDetail(args) {
+    const { data, error } = await supabase
+        .from('bookmarks')
+        .select('*')
+        .eq('id', args.id)
+        .eq('status', 'active')
+        .single();
+    if (error) {
+        return textResult(error.code === 'PGRST116'
+            ? `No active Flame bookmark found with id "${args.id}". It may have already burned to Ash or been moved to Spark/Vault.`
+            : `Error: ${error.message}`);
+    }
+    // Return full detail including extracted content
+    const m = data.content_metadata || {};
+    const expiresAt = data.countdown_expires_at ? new Date(data.countdown_expires_at) : null;
+    const now = new Date();
+    const remainingMs = expiresAt ? expiresAt.getTime() - now.getTime() : 0;
+    const remainingHours = Math.max(0, Math.round(remainingMs / 3600000 * 10) / 10);
+    const result = {
+        ...flameSummary(data),
+        extractedContent: m.extracted_content || null,
+        externalURL: m.external_url || null,
+        thumbnail: m.thumbnail || null,
+        aiFocus: m.ai_focus || null,
+        aiUse: m.ai_use || null,
+        aiBuzz: m.ai_buzz || null,
+    };
+    return textResult(JSON.stringify(result, null, 2));
+}
 async function handleListVault(args) {
     let query = supabase
         .from('bookmarks')
@@ -546,6 +673,255 @@ async function handleListVault(args) {
     return textResult(JSON.stringify(results, null, 2));
 }
 // ---------------------------------------------------------------------------
+// Layer 1: Status flow handlers (决策层)
+// ---------------------------------------------------------------------------
+async function handleMoveFlameToSpark(args) {
+    const { data, error } = await verifyBookmark(args.id, 'active');
+    if (error)
+        return textResult(`Error: ${error}`);
+    const sparkExpiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
+    const metaFields = { spark_expires_at: sparkExpiresAt };
+    if (args.spark_insight)
+        metaFields.spark_insight = args.spark_insight;
+    const { error: mergeErr } = await mergeContentMetadata(args.id, metaFields, {
+        status: 'read',
+        read_at: new Date().toISOString(),
+    });
+    if (mergeErr)
+        return textResult(`Error: ${mergeErr}`);
+    return textResult(JSON.stringify({
+        success: true,
+        id: args.id,
+        title: data.title,
+        action: 'flame → spark',
+        sparkExpiresAt,
+    }, null, 2));
+}
+async function handleMoveFlameToAsh(args) {
+    const { data, error } = await verifyBookmark(args.id, 'active');
+    if (error)
+        return textResult(`Error: ${error}`);
+    const { error: updateErr } = await supabase
+        .from('bookmarks')
+        .update({ status: 'ash' })
+        .eq('id', args.id);
+    if (updateErr)
+        return textResult(`Error: ${updateErr.message}`);
+    return textResult(JSON.stringify({
+        success: true,
+        id: args.id,
+        title: data.title,
+        action: 'flame → ash',
+        reason: args.reason || null,
+    }, null, 2));
+}
+async function handleMoveSparkToVault(args) {
+    const { data, error } = await verifyBookmark(args.id, 'read');
+    if (error)
+        return textResult(`Error: ${error}`);
+    const metaFields = { vaulted_at: new Date().toISOString() };
+    if (args.vault_category)
+        metaFields.vault_category = args.vault_category;
+    const { error: mergeErr } = await mergeContentMetadata(args.id, metaFields, {
+        status: 'absorbed',
+    });
+    if (mergeErr)
+        return textResult(`Error: ${mergeErr}`);
+    return textResult(JSON.stringify({
+        success: true,
+        id: args.id,
+        title: data.title,
+        action: 'spark → vault',
+        vaultCategory: args.vault_category || null,
+    }, null, 2));
+}
+async function handleMoveSparkToAsh(args) {
+    const { data, error } = await verifyBookmark(args.id, 'read');
+    if (error)
+        return textResult(`Error: ${error}`);
+    const { error: updateErr } = await supabase
+        .from('bookmarks')
+        .update({ status: 'ash' })
+        .eq('id', args.id);
+    if (updateErr)
+        return textResult(`Error: ${updateErr.message}`);
+    return textResult(JSON.stringify({
+        success: true,
+        id: args.id,
+        title: data.title,
+        action: 'spark → ash',
+    }, null, 2));
+}
+async function handleBatchTriageFlame(args) {
+    const results = [];
+    for (const decision of args.decisions) {
+        if (decision.action === 'spark') {
+            const res = await handleMoveFlameToSpark({ id: decision.id, spark_insight: decision.spark_insight });
+            const parsed = JSON.parse(res.content[0].text);
+            results.push({ id: decision.id, action: 'flame → spark', success: !!parsed.success, error: parsed.success ? undefined : res.content[0].text, title: parsed.title });
+        }
+        else {
+            const res = await handleMoveFlameToAsh({ id: decision.id });
+            const parsed = JSON.parse(res.content[0].text);
+            results.push({ id: decision.id, action: 'flame → ash', success: !!parsed.success, error: parsed.success ? undefined : res.content[0].text, title: parsed.title });
+        }
+    }
+    const succeeded = results.filter(r => r.success).length;
+    const failed = results.filter(r => !r.success).length;
+    return textResult(JSON.stringify({
+        summary: `${succeeded} succeeded, ${failed} failed (of ${results.length} total)`,
+        results,
+    }, null, 2));
+}
+// ---------------------------------------------------------------------------
+// Layer 3: AI analysis writeback handler (分析层)
+// ---------------------------------------------------------------------------
+async function handleWriteBookmarkAnalysis(args) {
+    const { data, error } = await verifyBookmark(args.id);
+    if (error)
+        return textResult(`Error: ${error}`);
+    const { error: mergeErr } = await mergeContentMetadata(args.id, args.analysis);
+    if (mergeErr)
+        return textResult(`Error: ${mergeErr}`);
+    const fieldsWritten = Object.keys(args.analysis).filter(k => args.analysis[k] !== undefined);
+    return textResult(JSON.stringify({
+        success: true,
+        id: args.id,
+        title: data.title,
+        fieldsWritten,
+    }, null, 2));
+}
+// ---------------------------------------------------------------------------
+// Layer 2: Collection handlers (组合层)
+// ---------------------------------------------------------------------------
+async function handleCreateCollection(args) {
+    // Get user ID from an existing bookmark (RLS ensures we only see our own)
+    const { data: sample } = await supabase
+        .from('bookmarks')
+        .select('user_id')
+        .limit(1)
+        .single();
+    if (!sample)
+        return textResult('Error: No bookmarks found — cannot determine user ID');
+    const bookmarkIds = args.bookmark_ids || [];
+    // Verify bookmark_ids exist if provided
+    if (bookmarkIds.length > 0) {
+        const { data: existing } = await supabase
+            .from('bookmarks')
+            .select('id')
+            .in('id', bookmarkIds);
+        const existingIds = new Set((existing || []).map((b) => b.id));
+        const missing = bookmarkIds.filter(id => !existingIds.has(id));
+        if (missing.length > 0) {
+            return textResult(`Error: Bookmark IDs not found: ${missing.join(', ')}`);
+        }
+    }
+    const { data, error } = await supabase
+        .from('collections')
+        .insert({
+        user_id: sample.user_id,
+        name: args.name,
+        bookmark_ids: bookmarkIds,
+        is_overview_stale: true,
+    })
+        .select()
+        .single();
+    if (error)
+        return textResult(`Error: ${error.message}`);
+    return textResult(JSON.stringify({
+        success: true,
+        id: data.id,
+        name: data.name,
+        articleCount: bookmarkIds.length,
+    }, null, 2));
+}
+async function handleAddToCollection(args) {
+    const { data: collection, error } = await supabase
+        .from('collections')
+        .select('*')
+        .eq('id', args.collection_id)
+        .single();
+    if (error) {
+        return textResult(error.code === 'PGRST116' ? 'Error: Collection not found' : `Error: ${error.message}`);
+    }
+    // Verify bookmark_ids exist
+    const { data: existing } = await supabase
+        .from('bookmarks')
+        .select('id')
+        .in('id', args.bookmark_ids);
+    const existingIds = new Set((existing || []).map((b) => b.id));
+    const missing = args.bookmark_ids.filter(id => !existingIds.has(id));
+    if (missing.length > 0) {
+        return textResult(`Error: Bookmark IDs not found: ${missing.join(', ')}`);
+    }
+    // Union with existing (deduplicate)
+    const currentIds = new Set(collection.bookmark_ids || []);
+    const newIds = args.bookmark_ids.filter(id => !currentIds.has(id));
+    const merged = [...(collection.bookmark_ids || []), ...newIds];
+    const { error: updateErr } = await supabase
+        .from('collections')
+        .update({ bookmark_ids: merged, is_overview_stale: true })
+        .eq('id', args.collection_id);
+    if (updateErr)
+        return textResult(`Error: ${updateErr.message}`);
+    return textResult(JSON.stringify({
+        success: true,
+        collectionId: args.collection_id,
+        name: collection.name,
+        added: newIds.length,
+        alreadyPresent: args.bookmark_ids.length - newIds.length,
+        totalArticles: merged.length,
+    }, null, 2));
+}
+async function handleRemoveFromCollection(args) {
+    const { data: collection, error } = await supabase
+        .from('collections')
+        .select('*')
+        .eq('id', args.collection_id)
+        .single();
+    if (error) {
+        return textResult(error.code === 'PGRST116' ? 'Error: Collection not found' : `Error: ${error.message}`);
+    }
+    const removeSet = new Set(args.bookmark_ids);
+    const filtered = (collection.bookmark_ids || []).filter((id) => !removeSet.has(id));
+    const removed = (collection.bookmark_ids || []).length - filtered.length;
+    const { error: updateErr } = await supabase
+        .from('collections')
+        .update({ bookmark_ids: filtered, is_overview_stale: true })
+        .eq('id', args.collection_id);
+    if (updateErr)
+        return textResult(`Error: ${updateErr.message}`);
+    return textResult(JSON.stringify({
+        success: true,
+        collectionId: args.collection_id,
+        name: collection.name,
+        removed,
+        totalArticles: filtered.length,
+    }, null, 2));
+}
+async function handleUpdateCollectionOverview(args) {
+    const { data: collection, error } = await supabase
+        .from('collections')
+        .select('id, name')
+        .eq('id', args.collection_id)
+        .single();
+    if (error) {
+        return textResult(error.code === 'PGRST116' ? 'Error: Collection not found' : `Error: ${error.message}`);
+    }
+    const { error: updateErr } = await supabase
+        .from('collections')
+        .update({ ai_overview: args.overview, is_overview_stale: false })
+        .eq('id', args.collection_id);
+    if (updateErr)
+        return textResult(`Error: ${updateErr.message}`);
+    return textResult(JSON.stringify({
+        success: true,
+        collectionId: args.collection_id,
+        name: collection.name,
+        overviewTheme: args.overview.theme,
+    }, null, 2));
+}
+// ---------------------------------------------------------------------------
 // Register tools
 // ---------------------------------------------------------------------------
 // @ts-expect-error — MCP SDK 1.27 TS2589: type instantiation too deep with multiple .tool() calls
@@ -557,9 +933,81 @@ server.tool('get_bookmark', 'Get full details of a single bookmark including AI
 server.tool('get_article_content', 'Get full article content and AI analysis for a bookmark by ID (same as get_bookmark)', { id: zod_1.z.string().describe('Bookmark UUID') }, rateLimited(handleGetArticleContent));
 server.tool('fetch_content', 'Fetch article/tweet content from a URL. Works with X.com (bypasses GFW via proxy), Reddit, YouTube, Bilibili, WeChat, and any web page. First checks Supabase cache, then fetches live.', { url: zod_1.z.string().describe('The URL to fetch content from') }, rateLimited(handleFetchContent));
 server.tool('list_categories', 'List all Vault categories with article counts', {}, rateLimited(handleListCategories));
+server.tool('list_flame', 'List bookmarks in your Flame inbox (24h countdown). Shows AI triage info (strategy, relevance, novelty, hook) and time remaining. Use this to see what needs attention before it burns to Ash.', { limit: zod_1.z.number().optional().describe('Max results (default 20)') }, rateLimited(handleListFlame));
+server.tool('get_flame_detail', 'Get full details of a Flame bookmark including extracted article content, AI analysis, and reading guidance. Use this to deep-read a bookmark before deciding its fate.', { id: zod_1.z.string().describe('Bookmark UUID') }, rateLimited(handleGetFlameDetail));
 server.tool('get_collections', 'List all your Collections with article counts and AI overview themes', {}, rateLimited(handleGetCollections));
 server.tool('get_collection_overview', 'Get a Collection by name with its AI overview and linked bookmarks metadata', { name: zod_1.z.string().describe('Collection name') }, rateLimited(handleGetCollectionOverview));
 // ---------------------------------------------------------------------------
+// Layer 1: Status flow tools (决策层)
+// ---------------------------------------------------------------------------
+server.tool('move_flame_to_spark', 'Move a Flame bookmark to Spark (mark as worth reading). Sets 30-day Spark lifespan.', {
+    id: zod_1.z.string().describe('Bookmark UUID'),
+    spark_insight: zod_1.z.string().max(500).optional().describe('One-line insight about why this is worth reading'),
+}, rateLimited(handleMoveFlameToSpark));
+server.tool('move_flame_to_ash', 'Burn a Flame bookmark to Ash (not worth keeping).', {
+    id: zod_1.z.string().describe('Bookmark UUID'),
+    reason: zod_1.z.string().max(200).optional().describe('Why this was burned'),
+}, rateLimited(handleMoveFlameToAsh));
+server.tool('move_spark_to_vault', 'Promote a Spark bookmark to permanent Vault storage.', {
+    id: zod_1.z.string().describe('Bookmark UUID'),
+    vault_category: zod_1.z.string().max(100).optional().describe('Category to file under in the Vault'),
+}, rateLimited(handleMoveSparkToVault));
+server.tool('move_spark_to_ash', 'Burn a Spark bookmark to Ash (not valuable enough to vault).', {
+    id: zod_1.z.string().describe('Bookmark UUID'),
+}, rateLimited(handleMoveSparkToAsh));
+// @ts-expect-error — MCP SDK TS2589
+server.tool('batch_triage_flame', 'Triage multiple Flame bookmarks at once. Each decision moves a bookmark to Spark or Ash.', {
+    decisions: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string().describe('Bookmark UUID'),
+        action: zod_1.z.enum(['spark', 'ash']).describe('spark = keep, ash = burn'),
+        spark_insight: zod_1.z.string().max(500).optional().describe('Insight (only for spark action)'),
+    })).min(1).max(20).describe('Array of triage decisions'),
+}, rateLimited(handleBatchTriageFlame));
+// ---------------------------------------------------------------------------
+// Layer 3: AI analysis writeback tools (分析层)
+// ---------------------------------------------------------------------------
+// @ts-expect-error — MCP SDK TS2589
+server.tool('write_bookmark_analysis', 'Write AI analysis results into a bookmark. Agent analyzes content with its own LLM, then writes structured results back to Burn. Only provided fields are merged — existing data is preserved.', {
+    id: zod_1.z.string().describe('Bookmark UUID'),
+    analysis: zod_1.z.object({
+        ai_summary: zod_1.z.string().max(200).optional().describe('One-line summary'),
+        ai_strategy: zod_1.z.enum(['deep_read', 'skim', 'skip_read', 'reference']).optional().describe('Reading strategy'),
+        ai_strategy_reason: zod_1.z.string().max(200).optional().describe('Why this strategy'),
+        ai_minutes: zod_1.z.number().int().min(1).max(999).optional().describe('Estimated reading minutes'),
+        ai_takeaway: zod_1.z.array(zod_1.z.string().max(200)).max(5).optional().describe('Key takeaways'),
+        ai_relevance: zod_1.z.number().int().min(0).max(100).optional().describe('Relevance score 0-100'),
+        ai_novelty: zod_1.z.number().int().min(0).max(100).optional().describe('Novelty score 0-100'),
+        tags: zod_1.z.array(zod_1.z.string().max(50)).max(10).optional().describe('Topic tags'),
+    }).describe('Analysis fields to write'),
+}, rateLimited(handleWriteBookmarkAnalysis));
+// ---------------------------------------------------------------------------
+// Layer 2: Collection tools (组合层)
+// ---------------------------------------------------------------------------
+// @ts-expect-error — MCP SDK TS2589
+server.tool('create_collection', 'Create a new Collection to group related bookmarks together.', {
+    name: zod_1.z.string().min(1).max(200).describe('Collection name'),
+    bookmark_ids: zod_1.z.array(zod_1.z.string()).optional().describe('Initial bookmark UUIDs to include'),
+}, rateLimited(handleCreateCollection));
+// @ts-expect-error — MCP SDK TS2589
+server.tool('add_to_collection', 'Add bookmarks to an existing Collection. Duplicates are silently ignored.', {
+    collection_id: zod_1.z.string().describe('Collection UUID'),
+    bookmark_ids: zod_1.z.array(zod_1.z.string()).min(1).max(50).describe('Bookmark UUIDs to add'),
+}, rateLimited(handleAddToCollection));
+server.tool('remove_from_collection', 'Remove bookmarks from a Collection.', {
+    collection_id: zod_1.z.string().describe('Collection UUID'),
+    bookmark_ids: zod_1.z.array(zod_1.z.string()).min(1).describe('Bookmark UUIDs to remove'),
+}, rateLimited(handleRemoveFromCollection));
+// @ts-expect-error — MCP SDK TS2589
+server.tool('update_collection_overview', 'Write an AI-generated overview for a Collection (theme, synthesis, patterns, gaps).', {
+    collection_id: zod_1.z.string().describe('Collection UUID'),
+    overview: zod_1.z.object({
+        theme: zod_1.z.string().describe('Overarching theme'),
+        synthesis: zod_1.z.string().optional().describe('Cross-bookmark synthesis'),
+        patterns: zod_1.z.array(zod_1.z.string()).optional().describe('Patterns identified'),
+        gaps: zod_1.z.array(zod_1.z.string()).optional().describe('Knowledge gaps identified'),
+    }).describe('AI-generated overview'),
+}, rateLimited(handleUpdateCollectionOverview));
+// ---------------------------------------------------------------------------
 // Resource: burn://vault/bookmarks
 // ---------------------------------------------------------------------------
 server.resource('vault-bookmarks', 'burn://vault/bookmarks', async (uri) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burn-mcp-server",
-  "version": "1.4.0",
+  "version": "2.0.1",
   "description": "MCP Server for Burn — access your Vault from Claude/Cursor",
   "main": "dist/index.js",
   "bin": {

package/src/index.ts

@@ -153,7 +153,7 @@ function checkRateLimit(): string | null {
 
 const server = new McpServer({
   name: 'burn-mcp-server',
-  version: '1.3.0',
+  version: '2.0.0',
 })
 
 // ---------------------------------------------------------------------------
@@ -164,6 +164,66 @@ function textResult(text: string) {
   return { content: [{ type: 'text' as const, text }] }
 }
 
+// ---------------------------------------------------------------------------
+// Helper: verify bookmark exists and has expected status
+// ---------------------------------------------------------------------------
+
+async function verifyBookmark(
+  id: string,
+  expectedStatus?: string | string[]
+): Promise<{ data: any; error: string | null }> {
+  const { data, error } = await supabase
+    .from('bookmarks')
+    .select('*')
+    .eq('id', id)
+    .single()
+
+  if (error) return { data: null, error: error.code === 'PGRST116' ? 'Bookmark not found' : error.message }
+
+  if (expectedStatus) {
+    const allowed = Array.isArray(expectedStatus) ? expectedStatus : [expectedStatus]
+    if (!allowed.includes(data.status)) {
+      const statusLabels: Record<string, string> = { active: 'Flame', read: 'Spark', absorbed: 'Vault', ash: 'Ash' }
+      return { data, error: `Bookmark is in ${statusLabels[data.status] || data.status} (expected ${allowed.map(s => statusLabels[s] || s).join(' or ')})` }
+    }
+  }
+
+  return { data, error: null }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: merge fields into content_metadata JSONB without overwriting
+// ---------------------------------------------------------------------------
+
+async function mergeContentMetadata(
+  bookmarkId: string,
+  fields: Record<string, unknown>,
+  extraColumns?: Record<string, unknown>
+): Promise<{ error: string | null }> {
+  const { data, error } = await supabase
+    .from('bookmarks')
+    .select('content_metadata')
+    .eq('id', bookmarkId)
+    .single()
+
+  if (error) return { error: error.message }
+
+  const existing = (data.content_metadata || {}) as Record<string, unknown>
+  // Only merge non-undefined fields
+  const cleaned: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== undefined && v !== null) cleaned[k] = v
+  }
+  const merged = { ...existing, ...cleaned }
+
+  const { error: updateError } = await supabase
+    .from('bookmarks')
+    .update({ content_metadata: merged, ...extraColumns })
+    .eq('id', bookmarkId)
+
+  return { error: updateError?.message || null }
+}
+
 // ---------------------------------------------------------------------------
 // Helper: extract fields from content_metadata JSONB
 // ---------------------------------------------------------------------------
@@ -218,6 +278,41 @@ function metaSummary(row: any): any {
   }
 }
 
+/** Flame-specific summary with countdown and AI triage fields */
+function flameSummary(row: any): any {
+  const m = row.content_metadata || {}
+  const expiresAt = row.countdown_expires_at ? new Date(row.countdown_expires_at) : null
+  const now = new Date()
+  const remainingMs = expiresAt ? expiresAt.getTime() - now.getTime() : 0
+  const remainingHours = Math.max(0, Math.round(remainingMs / 3600000 * 10) / 10)
+
+  return {
+    id: row.id,
+    url: row.url,
+    title: row.title,
+    author: m.author || null,
+    platform: row.platform,
+    tags: m.tags || [],
+    createdAt: row.created_at,
+    expiresAt: row.countdown_expires_at,
+    remainingHours,
+    isBurning: remainingHours <= 6,
+    isCritical: remainingHours <= 1,
+    aiPositioning: m.ai_positioning || null,
+    aiDensity: m.ai_density || null,
+    aiMinutes: m.ai_minutes || null,
+    aiTakeaway: m.ai_takeaway || [],
+    aiStrategy: m.ai_strategy || null,
+    aiStrategyReason: m.ai_strategy_reason || null,
+    aiHowToRead: m.ai_how_to_read || null,
+    aiRelevance: m.ai_relevance || null,
+    aiNovelty: m.ai_novelty || null,
+    aiOverlap: m.ai_overlap || null,
+    aiHook: m.ai_hook || null,
+    aiAbout: m.ai_about || [],
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Tool handlers (all wrapped with rate limiting)
 // ---------------------------------------------------------------------------
@@ -590,6 +685,64 @@ async function handleSearchSparks(args: { query: string; limit?: number }) {
   return textResult(JSON.stringify(results, null, 2))
 }
 
+async function handleListFlame(args: { limit?: number }) {
+  const { data, error } = await supabase
+    .from('bookmarks')
+    .select('*')
+    .eq('status', 'active')
+    .order('created_at', { ascending: false })
+    .limit(args.limit || 20)
+
+  if (error) return textResult(`Error: ${error.message}`)
+
+  // Filter out already expired ones (should be ash but not yet processed)
+  const now = new Date()
+  const results = (data || [])
+    .filter((row: any) => {
+      if (!row.countdown_expires_at) return true
+      return new Date(row.countdown_expires_at).getTime() > now.getTime()
+    })
+    .map(flameSummary)
+
+  return textResult(JSON.stringify(results, null, 2))
+}
+
+async function handleGetFlameDetail(args: { id: string }) {
+  const { data, error } = await supabase
+    .from('bookmarks')
+    .select('*')
+    .eq('id', args.id)
+    .eq('status', 'active')
+    .single()
+
+  if (error) {
+    return textResult(
+      error.code === 'PGRST116'
+        ? `No active Flame bookmark found with id "${args.id}". It may have already burned to Ash or been moved to Spark/Vault.`
+        : `Error: ${error.message}`
+    )
+  }
+
+  // Return full detail including extracted content
+  const m = data.content_metadata || {}
+  const expiresAt = data.countdown_expires_at ? new Date(data.countdown_expires_at) : null
+  const now = new Date()
+  const remainingMs = expiresAt ? expiresAt.getTime() - now.getTime() : 0
+  const remainingHours = Math.max(0, Math.round(remainingMs / 3600000 * 10) / 10)
+
+  const result = {
+    ...flameSummary(data),
+    extractedContent: m.extracted_content || null,
+    externalURL: m.external_url || null,
+    thumbnail: m.thumbnail || null,
+    aiFocus: m.ai_focus || null,
+    aiUse: m.ai_use || null,
+    aiBuzz: m.ai_buzz || null,
+  }
+
+  return textResult(JSON.stringify(result, null, 2))
+}
+
 async function handleListVault(args: { limit?: number; category?: string }) {
   let query = supabase
     .from('bookmarks')
@@ -614,6 +767,311 @@ async function handleListVault(args: { limit?: number; category?: string }) {
   return textResult(JSON.stringify(results, null, 2))
 }
 
+// ---------------------------------------------------------------------------
+// Layer 1: Status flow handlers (决策层)
+// ---------------------------------------------------------------------------
+
+async function handleMoveFlameToSpark(args: { id: string; spark_insight?: string }) {
+  const { data, error } = await verifyBookmark(args.id, 'active')
+  if (error) return textResult(`Error: ${error}`)
+
+  const sparkExpiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
+  const metaFields: Record<string, unknown> = { spark_expires_at: sparkExpiresAt }
+  if (args.spark_insight) metaFields.spark_insight = args.spark_insight
+
+  const { error: mergeErr } = await mergeContentMetadata(args.id, metaFields, {
+    status: 'read',
+    read_at: new Date().toISOString(),
+  })
+  if (mergeErr) return textResult(`Error: ${mergeErr}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    id: args.id,
+    title: data.title,
+    action: 'flame → spark',
+    sparkExpiresAt,
+  }, null, 2))
+}
+
+async function handleMoveFlameToAsh(args: { id: string; reason?: string }) {
+  const { data, error } = await verifyBookmark(args.id, 'active')
+  if (error) return textResult(`Error: ${error}`)
+
+  const { error: updateErr } = await supabase
+    .from('bookmarks')
+    .update({ status: 'ash' })
+    .eq('id', args.id)
+
+  if (updateErr) return textResult(`Error: ${updateErr.message}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    id: args.id,
+    title: data.title,
+    action: 'flame → ash',
+    reason: args.reason || null,
+  }, null, 2))
+}
+
+async function handleMoveSparkToVault(args: { id: string; vault_category?: string }) {
+  const { data, error } = await verifyBookmark(args.id, 'read')
+  if (error) return textResult(`Error: ${error}`)
+
+  const metaFields: Record<string, unknown> = { vaulted_at: new Date().toISOString() }
+  if (args.vault_category) metaFields.vault_category = args.vault_category
+
+  const { error: mergeErr } = await mergeContentMetadata(args.id, metaFields, {
+    status: 'absorbed',
+  })
+  if (mergeErr) return textResult(`Error: ${mergeErr}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    id: args.id,
+    title: data.title,
+    action: 'spark → vault',
+    vaultCategory: args.vault_category || null,
+  }, null, 2))
+}
+
+async function handleMoveSparkToAsh(args: { id: string }) {
+  const { data, error } = await verifyBookmark(args.id, 'read')
+  if (error) return textResult(`Error: ${error}`)
+
+  const { error: updateErr } = await supabase
+    .from('bookmarks')
+    .update({ status: 'ash' })
+    .eq('id', args.id)
+
+  if (updateErr) return textResult(`Error: ${updateErr.message}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    id: args.id,
+    title: data.title,
+    action: 'spark → ash',
+  }, null, 2))
+}
+
+async function handleBatchTriageFlame(args: { decisions: Array<{ id: string; action: 'spark' | 'ash'; spark_insight?: string }> }) {
+  const results: Array<{ id: string; action: string; success: boolean; error?: string; title?: string }> = []
+
+  for (const decision of args.decisions) {
+    if (decision.action === 'spark') {
+      const res = await handleMoveFlameToSpark({ id: decision.id, spark_insight: decision.spark_insight })
+      const parsed = JSON.parse(res.content[0].text)
+      results.push({ id: decision.id, action: 'flame → spark', success: !!parsed.success, error: parsed.success ? undefined : res.content[0].text, title: parsed.title })
+    } else {
+      const res = await handleMoveFlameToAsh({ id: decision.id })
+      const parsed = JSON.parse(res.content[0].text)
+      results.push({ id: decision.id, action: 'flame → ash', success: !!parsed.success, error: parsed.success ? undefined : res.content[0].text, title: parsed.title })
+    }
+  }
+
+  const succeeded = results.filter(r => r.success).length
+  const failed = results.filter(r => !r.success).length
+
+  return textResult(JSON.stringify({
+    summary: `${succeeded} succeeded, ${failed} failed (of ${results.length} total)`,
+    results,
+  }, null, 2))
+}
+
+// ---------------------------------------------------------------------------
+// Layer 3: AI analysis writeback handler (分析层)
+// ---------------------------------------------------------------------------
+
+async function handleWriteBookmarkAnalysis(args: {
+  id: string
+  analysis: {
+    ai_summary?: string
+    ai_strategy?: string
+    ai_strategy_reason?: string
+    ai_minutes?: number
+    ai_takeaway?: string[]
+    ai_relevance?: number
+    ai_novelty?: number
+    tags?: string[]
+  }
+}) {
+  const { data, error } = await verifyBookmark(args.id)
+  if (error) return textResult(`Error: ${error}`)
+
+  const { error: mergeErr } = await mergeContentMetadata(args.id, args.analysis)
+  if (mergeErr) return textResult(`Error: ${mergeErr}`)
+
+  const fieldsWritten = Object.keys(args.analysis).filter(k => (args.analysis as any)[k] !== undefined)
+
+  return textResult(JSON.stringify({
+    success: true,
+    id: args.id,
+    title: data.title,
+    fieldsWritten,
+  }, null, 2))
+}
+
+// ---------------------------------------------------------------------------
+// Layer 2: Collection handlers (组合层)
+// ---------------------------------------------------------------------------
+
+async function handleCreateCollection(args: { name: string; bookmark_ids?: string[] }) {
+  // Get user ID from an existing bookmark (RLS ensures we only see our own)
+  const { data: sample } = await supabase
+    .from('bookmarks')
+    .select('user_id')
+    .limit(1)
+    .single()
+
+  if (!sample) return textResult('Error: No bookmarks found — cannot determine user ID')
+
+  const bookmarkIds = args.bookmark_ids || []
+
+  // Verify bookmark_ids exist if provided
+  if (bookmarkIds.length > 0) {
+    const { data: existing } = await supabase
+      .from('bookmarks')
+      .select('id')
+      .in('id', bookmarkIds)
+
+    const existingIds = new Set((existing || []).map((b: any) => b.id))
+    const missing = bookmarkIds.filter(id => !existingIds.has(id))
+    if (missing.length > 0) {
+      return textResult(`Error: Bookmark IDs not found: ${missing.join(', ')}`)
+    }
+  }
+
+  const { data, error } = await supabase
+    .from('collections')
+    .insert({
+      user_id: sample.user_id,
+      name: args.name,
+      bookmark_ids: bookmarkIds,
+      is_overview_stale: true,
+    })
+    .select()
+    .single()
+
+  if (error) return textResult(`Error: ${error.message}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    id: data.id,
+    name: data.name,
+    articleCount: bookmarkIds.length,
+  }, null, 2))
+}
+
+async function handleAddToCollection(args: { collection_id: string; bookmark_ids: string[] }) {
+  const { data: collection, error } = await supabase
+    .from('collections')
+    .select('*')
+    .eq('id', args.collection_id)
+    .single()
+
+  if (error) {
+    return textResult(error.code === 'PGRST116' ? 'Error: Collection not found' : `Error: ${error.message}`)
+  }
+
+  // Verify bookmark_ids exist
+  const { data: existing } = await supabase
+    .from('bookmarks')
+    .select('id')
+    .in('id', args.bookmark_ids)
+
+  const existingIds = new Set((existing || []).map((b: any) => b.id))
+  const missing = args.bookmark_ids.filter(id => !existingIds.has(id))
+  if (missing.length > 0) {
+    return textResult(`Error: Bookmark IDs not found: ${missing.join(', ')}`)
+  }
+
+  // Union with existing (deduplicate)
+  const currentIds = new Set(collection.bookmark_ids || [])
+  const newIds = args.bookmark_ids.filter(id => !currentIds.has(id))
+  const merged = [...(collection.bookmark_ids || []), ...newIds]
+
+  const { error: updateErr } = await supabase
+    .from('collections')
+    .update({ bookmark_ids: merged, is_overview_stale: true })
+    .eq('id', args.collection_id)
+
+  if (updateErr) return textResult(`Error: ${updateErr.message}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    collectionId: args.collection_id,
+    name: collection.name,
+    added: newIds.length,
+    alreadyPresent: args.bookmark_ids.length - newIds.length,
+    totalArticles: merged.length,
+  }, null, 2))
+}
+
+async function handleRemoveFromCollection(args: { collection_id: string; bookmark_ids: string[] }) {
+  const { data: collection, error } = await supabase
+    .from('collections')
+    .select('*')
+    .eq('id', args.collection_id)
+    .single()
+
+  if (error) {
+    return textResult(error.code === 'PGRST116' ? 'Error: Collection not found' : `Error: ${error.message}`)
+  }
+
+  const removeSet = new Set(args.bookmark_ids)
+  const filtered = (collection.bookmark_ids || []).filter((id: string) => !removeSet.has(id))
+  const removed = (collection.bookmark_ids || []).length - filtered.length
+
+  const { error: updateErr } = await supabase
+    .from('collections')
+    .update({ bookmark_ids: filtered, is_overview_stale: true })
+    .eq('id', args.collection_id)
+
+  if (updateErr) return textResult(`Error: ${updateErr.message}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    collectionId: args.collection_id,
+    name: collection.name,
+    removed,
+    totalArticles: filtered.length,
+  }, null, 2))
+}
+
+async function handleUpdateCollectionOverview(args: {
+  collection_id: string
+  overview: {
+    theme: string
+    synthesis?: string
+    patterns?: string[]
+    gaps?: string[]
+  }
+}) {
+  const { data: collection, error } = await supabase
+    .from('collections')
+    .select('id, name')
+    .eq('id', args.collection_id)
+    .single()
+
+  if (error) {
+    return textResult(error.code === 'PGRST116' ? 'Error: Collection not found' : `Error: ${error.message}`)
+  }
+
+  const { error: updateErr } = await supabase
+    .from('collections')
+    .update({ ai_overview: args.overview, is_overview_stale: false })
+    .eq('id', args.collection_id)
+
+  if (updateErr) return textResult(`Error: ${updateErr.message}`)
+
+  return textResult(JSON.stringify({
+    success: true,
+    collectionId: args.collection_id,
+    name: collection.name,
+    overviewTheme: args.overview.theme,
+  }, null, 2))
+}
+
 // ---------------------------------------------------------------------------
 // Register tools
 // ---------------------------------------------------------------------------
@@ -675,6 +1133,20 @@ server.tool(
   rateLimited(handleListCategories)
 )
 
+server.tool(
+  'list_flame',
+  'List bookmarks in your Flame inbox (24h countdown). Shows AI triage info (strategy, relevance, novelty, hook) and time remaining. Use this to see what needs attention before it burns to Ash.',
+  { limit: z.number().optional().describe('Max results (default 20)') },
+  rateLimited(handleListFlame)
+)
+
+server.tool(
+  'get_flame_detail',
+  'Get full details of a Flame bookmark including extracted article content, AI analysis, and reading guidance. Use this to deep-read a bookmark before deciding its fate.',
+  { id: z.string().describe('Bookmark UUID') },
+  rateLimited(handleGetFlameDetail)
+)
+
 server.tool(
   'get_collections',
   'List all your Collections with article counts and AI overview themes',
@@ -689,6 +1161,139 @@ server.tool(
   rateLimited(handleGetCollectionOverview)
 )
 
+// ---------------------------------------------------------------------------
+// Layer 1: Status flow tools (决策层)
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'move_flame_to_spark',
+  'Move a Flame bookmark to Spark (mark as worth reading). Sets 30-day Spark lifespan.',
+  {
+    id: z.string().describe('Bookmark UUID'),
+    spark_insight: z.string().max(500).optional().describe('One-line insight about why this is worth reading'),
+  },
+  rateLimited(handleMoveFlameToSpark)
+)
+
+server.tool(
+  'move_flame_to_ash',
+  'Burn a Flame bookmark to Ash (not worth keeping).',
+  {
+    id: z.string().describe('Bookmark UUID'),
+    reason: z.string().max(200).optional().describe('Why this was burned'),
+  },
+  rateLimited(handleMoveFlameToAsh)
+)
+
+server.tool(
+  'move_spark_to_vault',
+  'Promote a Spark bookmark to permanent Vault storage.',
+  {
+    id: z.string().describe('Bookmark UUID'),
+    vault_category: z.string().max(100).optional().describe('Category to file under in the Vault'),
+  },
+  rateLimited(handleMoveSparkToVault)
+)
+
+server.tool(
+  'move_spark_to_ash',
+  'Burn a Spark bookmark to Ash (not valuable enough to vault).',
+  {
+    id: z.string().describe('Bookmark UUID'),
+  },
+  rateLimited(handleMoveSparkToAsh)
+)
+
+// @ts-expect-error — MCP SDK TS2589
+server.tool(
+  'batch_triage_flame',
+  'Triage multiple Flame bookmarks at once. Each decision moves a bookmark to Spark or Ash.',
+  {
+    decisions: z.array(z.object({
+      id: z.string().describe('Bookmark UUID'),
+      action: z.enum(['spark', 'ash']).describe('spark = keep, ash = burn'),
+      spark_insight: z.string().max(500).optional().describe('Insight (only for spark action)'),
+    })).min(1).max(20).describe('Array of triage decisions'),
+  },
+  rateLimited(handleBatchTriageFlame)
+)
+
+// ---------------------------------------------------------------------------
+// Layer 3: AI analysis writeback tools (分析层)
+// ---------------------------------------------------------------------------
+
+// @ts-expect-error — MCP SDK TS2589
+server.tool(
+  'write_bookmark_analysis',
+  'Write AI analysis results into a bookmark. Agent analyzes content with its own LLM, then writes structured results back to Burn. Only provided fields are merged — existing data is preserved.',
+  {
+    id: z.string().describe('Bookmark UUID'),
+    analysis: z.object({
+      ai_summary: z.string().max(200).optional().describe('One-line summary'),
+      ai_strategy: z.enum(['deep_read', 'skim', 'skip_read', 'reference']).optional().describe('Reading strategy'),
+      ai_strategy_reason: z.string().max(200).optional().describe('Why this strategy'),
+      ai_minutes: z.number().int().min(1).max(999).optional().describe('Estimated reading minutes'),
+      ai_takeaway: z.array(z.string().max(200)).max(5).optional().describe('Key takeaways'),
+      ai_relevance: z.number().int().min(0).max(100).optional().describe('Relevance score 0-100'),
+      ai_novelty: z.number().int().min(0).max(100).optional().describe('Novelty score 0-100'),
+      tags: z.array(z.string().max(50)).max(10).optional().describe('Topic tags'),
+    }).describe('Analysis fields to write'),
+  },
+  rateLimited(handleWriteBookmarkAnalysis)
+)
+
+// ---------------------------------------------------------------------------
+// Layer 2: Collection tools (组合层)
+// ---------------------------------------------------------------------------
+
+// @ts-expect-error — MCP SDK TS2589
+server.tool(
+  'create_collection',
+  'Create a new Collection to group related bookmarks together.',
+  {
+    name: z.string().min(1).max(200).describe('Collection name'),
+    bookmark_ids: z.array(z.string()).optional().describe('Initial bookmark UUIDs to include'),
+  },
+  rateLimited(handleCreateCollection)
+)
+
+// @ts-expect-error — MCP SDK TS2589
+server.tool(
+  'add_to_collection',
+  'Add bookmarks to an existing Collection. Duplicates are silently ignored.',
+  {
+    collection_id: z.string().describe('Collection UUID'),
+    bookmark_ids: z.array(z.string()).min(1).max(50).describe('Bookmark UUIDs to add'),
+  },
+  rateLimited(handleAddToCollection)
+)
+
+server.tool(
+  'remove_from_collection',
+  'Remove bookmarks from a Collection.',
+  {
+    collection_id: z.string().describe('Collection UUID'),
+    bookmark_ids: z.array(z.string()).min(1).describe('Bookmark UUIDs to remove'),
+  },
+  rateLimited(handleRemoveFromCollection)
+)
+
+// @ts-expect-error — MCP SDK TS2589
+server.tool(
+  'update_collection_overview',
+  'Write an AI-generated overview for a Collection (theme, synthesis, patterns, gaps).',
+  {
+    collection_id: z.string().describe('Collection UUID'),
+    overview: z.object({
+      theme: z.string().describe('Overarching theme'),
+      synthesis: z.string().optional().describe('Cross-bookmark synthesis'),
+      patterns: z.array(z.string()).optional().describe('Patterns identified'),
+      gaps: z.array(z.string()).optional().describe('Knowledge gaps identified'),
+    }).describe('AI-generated overview'),
+  },
+  rateLimited(handleUpdateCollectionOverview)
+)
+
 // ---------------------------------------------------------------------------
 // Resource: burn://vault/bookmarks
 // ---------------------------------------------------------------------------