burn-mcp-server 1.4.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Burn MCP Server
 
-Let Claude Desktop, Cursor, or any MCP-compatible AI tool access your Burn Vault.
+Let Claude Desktop, Cursor, or any MCP-compatible AI tool access and manage your Burn bookmarks.
 
 ## Setup
 
@@ -19,7 +19,7 @@ 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": "<paste-your-token-here>"
       }
     }
   }
@@ -32,13 +32,47 @@ The Burn tools will appear in the tools menu.
 
 ## Available Tools
 
+### Read Tools
+
 | Tool | Description |
 |------|-------------|
 | `search_vault` | Search Vault bookmarks by keyword |
+| `list_vault` | List Vault bookmarks, optionally by category |
+| `list_sparks` | List Sparks (read bookmarks with 30-day lifespan) |
+| `search_sparks` | Search Sparks by keyword |
+| `list_flame` | List Flame inbox (24h countdown, AI triage info) |
+| `get_flame_detail` | Get full Flame bookmark detail with content |
 | `get_bookmark` | Get full details of a single bookmark |
+| `get_article_content` | Get article content and AI analysis by ID |
+| `fetch_content` | Fetch content from a URL (X, Reddit, YouTube, WeChat, etc.) |
 | `list_categories` | List all Vault categories with counts |
-| `get_clusters` | Get AI-generated topic clusters |
-| `get_cluster_digest` | Get cluster digest (summary + relationships) |
+| `get_collections` | List all Collections |
+| `get_collection_overview` | Get a Collection with AI overview and bookmarks |
+
+### Write Tools — Layer 1: Status Flow (决策层)
+
+| Tool | Description |
+|------|-------------|
+| `move_flame_to_spark` | Flame → Spark (worth reading). Sets 30-day lifespan. Optional `spark_insight`. |
+| `move_flame_to_ash` | Flame → Ash (burn it). Optional `reason`. |
+| `move_spark_to_vault` | Spark → Vault (permanent). Optional `vault_category`. |
+| `move_spark_to_ash` | Spark → Ash (not valuable enough to vault). |
+| `batch_triage_flame` | Triage up to 20 Flame bookmarks at once (spark or ash). |
+
+### Write Tools — Layer 2: Collections (组合层)
+
+| Tool | Description |
+|------|-------------|
+| `create_collection` | Create a new Collection, optionally with initial bookmarks. |
+| `add_to_collection` | Add bookmarks to a Collection (deduplicates). |
+| `remove_from_collection` | Remove bookmarks from a Collection. |
+| `update_collection_overview` | Write AI overview (theme, synthesis, patterns, gaps). |
+
+### Write Tools — Layer 3: AI Analysis (分析层)
+
+| Tool | Description |
+|------|-------------|
+| `write_bookmark_analysis` | Write AI analysis back to a bookmark. Agent uses its own LLM to analyze, then writes structured results (summary, strategy, takeaways, relevance, novelty, tags) into Burn. |
 
 ## Available Resources
 
@@ -47,22 +81,38 @@ The Burn tools will appear in the tools menu.
 | `burn://vault/bookmarks` | All Vault bookmarks (JSON) |
 | `burn://vault/categories` | Category list (JSON) |
 
-## Example prompts
+## Example Prompts
 
+**Reading:**
 - "What did I save about SwiftUI animations?"
+- "Show me my Flame inbox — what's about to burn?"
 - "Summarize my AI-related bookmarks"
-- "Reference my Vault article about API design patterns"
-- "What are the main topics in my knowledge base?"
+
+**Triage (Agent as your filter):**
+- "Review my Flame bookmarks and decide what to keep vs burn"
+- "Triage everything in Flame — skim the content and make decisions"
+
+**Analysis (Agent as your analyst):**
+- "Analyze this bookmark and write your assessment back to Burn"
+- "Go through my Sparks and tag them all"
+
+**Collections (Agent as your curator):**
+- "Group my Vault bookmarks about AI into a collection"
+- "Write an overview for my 'System Design' collection"
 
 ## 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` is 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
+- Your token only grants access to **your own** data (enforced by Row Level Security)
+- Write operations are scoped: status can only flow forward (Flame → Spark → Vault, or → Ash)
+- Rate limited: 30 calls/minute per session
+- Tokens expire after 30 days; regenerate from Burn App → Settings → MCP Server

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.0",
   "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
 // ---------------------------------------------------------------------------