burn-mcp-server 2.0.0 → 2.0.2

package/README.md

@@ -1,16 +1,27 @@
-# Burn MCP Server
+# Burn — Personal Knowledge Base MCP Server
 
-Let Claude Desktop, Cursor, or any MCP-compatible AI tool access and manage your Burn bookmarks.
+[![npm version](https://img.shields.io/npm/v/burn-mcp-server.svg)](https://www.npmjs.com/package/burn-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Setup
+Your reading data as an AI-accessible knowledge base. 22 tools for Claude, Cursor, Windsurf, and any MCP-compatible agent.
 
-### 1. Get your access token
+## How it works
 
-Open Burn App → Settings → MCP Server → **Copy 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.
+
+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
+
+Open Burn App → Settings → MCP Server → **Copy Access Token**
 
-Add to your `~/.config/claude/claude_desktop_config.json`:
+### 2. Add to Claude Desktop
 
 ```json
 {
@@ -19,86 +30,79 @@ Add to your `~/.config/claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["burn-mcp-server"],
       "env": {
-        "BURN_MCP_TOKEN": "<paste-your-token-here>"
+        "BURN_MCP_TOKEN": "<your-token>"
       }
     }
   }
 }
 ```
 
-### 3. Restart Claude Desktop
+### 3. Start asking
 
-The Burn tools will appear in the tools menu.
+- "What did I save about system design?"
+- "Triage my Flame — what should I keep?"
+- "Create a collection from my AI bookmarks"
 
-## Available Tools
+## Tools (22)
 
-### Read Tools
+### Search & Read
 
-| Tool | Description |
+| Tool | What it does |
 |------|-------------|
-| `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_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 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 |
+| `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` | Get a Collection with AI overview and bookmarks |
+| `get_collection_overview` | Collection detail with AI overview |
 
-### Write Tools — Layer 1: Status Flow (决策层)
+### Triage (Agent as your filter)
 
-| Tool | Description |
+| Tool | What it does |
 |------|-------------|
-| `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). |
+| `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. |
 
-### Write Tools — Layer 2: Collections (组合层)
+### Collections (Agent as your curator)
 
-| Tool | Description |
+| Tool | What it does |
 |------|-------------|
-| `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). |
+| `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) |
 
-### Write Tools — Layer 3: AI Analysis (分析层)
+### Analysis (Agent as your analyst)
 
-| Tool | Description |
+| Tool | What it does |
 |------|-------------|
-| `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. |
+| `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
 
-**Reading:**
-- "What did I save about SwiftUI animations?"
-- "Show me my Flame inbox — what's about to burn?"
-- "Summarize my AI-related bookmarks"
+**Personal knowledge management** — Your agent searches your reading history to answer questions, find patterns, and surface forgotten gems.
 
-**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"
+**Research workflows** — Create collections on topics you're exploring. Agent writes overviews synthesizing your sources.
 
-**Analysis (Agent as your analyst):**
-- "Analyze this bookmark and write your assessment back to Burn"
-- "Go through my Sparks and tag them all"
+**Reading triage** — Agent reviews your Flame inbox, reads the content, decides what's worth keeping based on your interests.
 
-**Collections (Agent as your curator):**
-- "Group my Vault bookmarks about AI into a collection"
-- "Write an overview for my 'System Design' collection"
+**Cross-tool intelligence** — Use with Claude Code, Cursor, or Windsurf. Your bookmarks become context for coding, writing, and thinking.
 
 ## Environment Variables
 
@@ -108,11 +112,22 @@ The Burn tools will appear in the tools menu.
 | `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.
+*One of `BURN_MCP_TOKEN` or `BURN_SUPABASE_TOKEN` required.
 
 ## Security
 
-- 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
+- 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.cloud](https://burn451.cloud)
+- **iOS App**: [App Store](https://apps.apple.com/us/app/burn451/id6759418544)
+- **npm**: [burn-mcp-server](https://www.npmjs.com/package/burn-mcp-server)
+- **Chrome Extension**: Search "Bookmark Autopsy" on Chrome Web Store
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "burn-mcp-server",
-  "version": "2.0.0",
-  "description": "MCP Server for Burn — access your Vault from Claude/Cursor",
+  "version": "2.0.2",
+  "mcpName": "io.github.fisher521/burn-mcp-server",
+  "description": "MCP Server for Burn — 22 tools to let your AI agent search, triage, and organize your reading. Works with Claude, Cursor, Windsurf.",
   "main": "dist/index.js",
   "bin": {
     "burn-mcp": "dist/index.js"
@@ -10,6 +11,28 @@
     "build": "tsc",
     "start": "node dist/index.js"
   },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bookmark",
+    "reading",
+    "knowledge-base",
+    "claude",
+    "cursor",
+    "windsurf",
+    "ai-agent",
+    "burn"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fisher521/burn-mcp-server.git"
+  },
+  "homepage": "https://burn451.cloud",
+  "bugs": {
+    "url": "https://github.com/Fisher521/burn-mcp-server/issues"
+  },
+  "license": "MIT",
+  "author": "Burn451 <hawking520@gmail.com>",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@supabase/supabase-js": "^2.39.0",

package/server.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.fisher521/burn-mcp-server",
+  "description": "Personal knowledge base MCP server — 22 tools to let your AI agent search, triage, and organize your reading list. Built for Burn451.",
+  "repository": {
+    "url": "https://github.com/Fisher521/burn-mcp-server",
+    "source": "github"
+  },
+  "version": "2.0.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "burn-mcp-server",
+      "version": "2.0.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "description": "Long-lived MCP access token from Burn App Settings",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true,
+          "name": "BURN_MCP_TOKEN"
+        }
+      ]
+    }
+  ]
+}