burn-mcp-server 1.2.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