Personal Knowledge Base MCP — 26 tools that let AI agents work with a user's curated reading. Search, triage, burn, vault, and analyze saved articles. Works with Claude, Cursor, Windsurf.
Static source inference · medium confidence · evidence: stateless requests
Current-spec patterns detected
Summary
Burn MCP Server demonstrates solid definition quality with 28 tools covering a coherent personal knowledge management workflow. All tools have clear, action-verb-based names following verb_noun conventions (search_, list_, get_, move_, update_, add_, delete_). Descriptions are consistently present and substantive (average ~120 chars), explaining both what the tool does and its context in the Flame→Spark→Vault lifecycle. Input schemas are uniformly present with JSON Schema draft-07 format, proper type declarations, and required field specifications. However, output schemas are not documented (only inferred from tool names and descriptions), and several tools lack parameter-level constraints that would prevent hallucinated values. Error handling guidance is minimal, tools return success/failure but offer no recovery hints. Security considerations around token injection are not evident in the server code itself (reliance on environment-based token injection is good, but not documented in tool descriptions). The tool suite is well-composed with clear chains (e.g., search_vault → get_bookmark → update_bookmark_*), and there is strong adherence to the single-responsibility principle, each tool does one thing. Naming consistency is excellent across the 28 tools, making the interface highly discoverable for LLMs.
Tools (28)
add_bookmarkwriteauth50/100
Add a new bookmark from a URL
add_to_collectionwriteauthsource verified82/100
Add a bookmark to a Collection
create_collectionwriteauthsource verified85/100
Create a new Collection
delete_bookmarkdestructiveauth50/100
Permanently delete a bookmark from all collections
delete_collectiondestructiveauth50/100
Delete a Collection (bookmarks remain in Vault)
fetch_contentread onlyauthsource verified82/100
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.
Output schemas are not documented. The server-card.js metadata declares tool names and input schemas but provides no output schema specifications. LLMs cannot determine what fields to expect from tool responses, forcing them to infer structure from descriptions or guess at response shapes.
Add output schema documentation to every tool. For each tool, document the response structure: field names, types, and descriptions. Example for get_bookmark: { id: string, title: string, url: string, tags: [string], ai_analysis: string, ... }. This enables LLMs to plan downstream calls and extract relevant fields.
Consolidate get_bookmark and get_article_content into a single tool. They are functionally identical, keep the canonical name 'get_bookmark' and remove 'get_article_content' to reduce cognitive load.
Add numeric constraints to 'limit' parameters. Change 'limit: number' to 'limit: integer, minimum: 1, maximum: 100' in all discovery and search tools (list_vault, search_vault, list_sparks, search_sparks, list_flame, list_categories, get_collections, search_all). Prevent context window exhaustion from runaway agents requesting 10,000 results.
Add recovery guidance to destructive and state-changing tools. For 'move_flame_to_ash', add: '... To recover, see list_ash or search within deleted bookmarks via a separate audit log if available. If moved by mistake, contact support or restore from backup.' Similar notes for delete_bookmark, delete_collection.
Implement a confirmation pattern for irreversible operations. Create a new 'confirm_destructive_action' step or add a 'dry_run' parameter to move_*_to_ash and delete_* tools. Alternatively, design these tools to return a 'confirmation_token' that must be passed to a separate 'finalize_delete' or 'finalize_move_to_ash' tool.
Support human-readable identifiers alongside UUIDs. For tools that accept 'id' (Bookmark UUID), also accept optional 'title_fragment' or 'url' parameters. Inside the tool, resolve the human identifier to a UUID before calling the backend. Example: get_bookmark(id='abc-123') OR get_bookmark(title_fragment='climate change'). Use fuzzy matching if multiple titles match.
Score history
Overall score trend
First recorded score · v2 rubric
71/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
B
71
2026-07-28+
v2
get_bookmarkread onlyauthsource verified82/100
Get full details of a single bookmark including AI analysis and extracted content
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.
list_categoriesread onlyauthsource verified78/100
List all Vault categories with article counts
list_flameread onlyauthsource verified85/100
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.
list_sparksread onlyauthsource verified82/100
List your Sparks (bookmarks you have read, with 30-day lifespan). Includes spark insight and expiry date.
list_vaultread onlyauthsource verified80/100
List bookmarks in your Vault, optionally filtered by category
No parameter-level constraints on several tools. For example, 'limit' parameters lack min/max boundaries (e.g., limit should be 1 - 100 to prevent context window exhaustion). 'reason' and 'spark_insight' accept open strings with maxLength but no format or pattern guidance. This invites LLMs to hallucinate invalid values.
Duplicate/near-duplicate tools create unnecessary cognitive load for LLMs. get_bookmark and get_article_content are described as identical ('same as get_bookmark'), forcing the LLM to decide between two functionally equivalent tools. Consolidate into one canonical tool.
No error recovery guidance in tool descriptions. Tools like 'move_flame_to_spark' and 'delete_bookmark' are destructive or state-changing, but descriptions do not explain failure modes or recovery steps. If a move fails (e.g., bookmark not found), the LLM has no guidance on what to try next (e.g., 'verify the bookmark exists with get_bookmark first').
No confirmation or dry-run pattern for irreversible operations. Tools 'move_flame_to_ash', 'move_spark_to_ash', 'delete_bookmark', and 'delete_collection' permanently delete or modify state without a confirmation step. Agents can inadvertently destroy data in a single call.
Parameter 'id' (Bookmark UUID) is opaque. The server accepts UUIDs as strings, but humans use bookmark titles or URLs. The tool does not accept human-friendly identifiers (title, URL substring) that would let users say 'delete the bookmark about climate change' instead of requiring the UUID. This forces extra lookup calls.
Tool descriptions do not document pagination or result limits clearly. While 'limit' parameters exist and descriptions mention defaults (e.g., 'default 10', 'default 20'), there is no explicit guidance on maximum limits or what happens when results exceed the limit. For discovery tools (list_vault, list_sparks, list_categories), the agent cannot determine if more results exist without explicit 'total_count' or 'next_cursor' guidance.
Document pagination and total count behavior in tool descriptions. For list_vault, add: '... Returns up to {limit} results (default 20). To fetch all bookmarks, iterate using offset/cursor if supported, or consult the total_count field in the response.' Update tool descriptions to mention whether total_count is returned and what pagination mechanism is supported (offset, cursor, etc.).
Add idempotency hints to write operations. Tools like add_bookmark, create_collection, update_bookmark_* should document whether they are idempotent (safe to retry with identical inputs). Example for update_bookmark_title: '... This operation is idempotent, calling it twice with the same title does not change the bookmark twice.'
Add per-item error reporting for batch-like operations. Tools like update_bookmark_tags that might operate on collections should clarify: if updating 5 bookmarks and 1 fails, do you return a partial success with per-item status? Example: { success: [id1, id2, id3], failed: [{ id: id4, error: 'not found' }] }.
Expand the fetch_content tool description to document supported URL patterns and failure modes. Example: '... Supports HTTP(S) URLs, X.com/twitter.com posts, Reddit threads, YouTube videos, Bilibili videos, WeChat articles, and generic web pages. Returns the content text and extracted metadata. If the URL is blocked or content is paywalled, returns an error with a recovery suggestion (e.g., "Try the article URL directly or search for a public summary").'
Add examples of valid values for enum-like parameters. For 'vault_category' in move_spark_to_vault, list common categories or suggest calling list_categories first. Example: 'vault_category: must match an existing category. Call list_categories() first to see available categories.'
Document any rate limits or quotas in the server card or per-tool description. If the Burn API enforces a maximum of 100 calls per minute, state this explicitly so agents can back off gracefully.