Bookmarks Lifecycle

bookmarks-lifecycle

Give your saved bookmarks a lifecycle.

Saving is easy. Almost nothing you save ever gets decided about — it just accumulates. This is a local MCP server that puts every bookmark on a clock: 24 hours to decide, or 30 days to keep watching, or keep it for good. Nothing is ever deleted — a bookmark that times out without a decision just leaves your attention, not your disk, and every change (including ones an AI made) can be undone.

Aggregates via bookmarks-mcp. Writes only its own local state file, atomically. No accounts, no cloud, no network calls.

The model

Five states:

aggregate → inbox

│ drip (up to N/day, oldest first) ▼ pending ──you decide──→ watching / kept / lapsed │ └──24h, no decision────────────→ lapsed ▲ watching ──30d, no decision───────────┘ └──you decide──→ kept

lapsed ──restore──→ pending (clock resets) any state ──undo (by history event)──→ whatever it was right before that event

From pending you can go to any of the three outcomes. From watching, a decision can only be keep — that matches the model above; to back out of a watch or a drop, use undo rather than re-deciding an item that's already moved on.

Bookmarks don't all land in pending the moment you aggregate them — a one-time import of 3,000 old bookmarks would otherwise all time out on the same day and the mechanism would mean nothing. They drip in at a daily rate instead (default 15/day, oldest first — by real save date when the source provides one). This is computed lazily whenever you call a tool, not by a background timer, and it does not accumulate across a long absence: however many days you've been away, one call promotes at most one day's quota. A 3,000-bookmark backlog at 15/day realistically takes months of daily visits to clear — that's an honest tradeoff of "no reminders, nothing runs unless you ask", not a claim that this replaces a habit-forming app.

Install

No account, no API key, no configuration — it works the moment it's installed.

Claude Code:

claude mcp add -s user bookmarks-lifecycle -- npx -y bookmarks-lifecycle

Claude Desktop / Cursor / any MCP client (mcpServers JSON):

{

"mcpServers": { "bookmarks-lifecycle": { "command": "npx", "args": ["-y", "bookmarks-lifecycle"] } } }

To run from source instead (for development), clone parse-bookmarks, bookmarks-mcp, and this repo as sibling directories, run npm install in bookmarks-mcp and then in bookmarks-lifecycle, and point your client at node /absolute/path/to/bookmarks-lifecycle/src/index.js.

Use `-s user`. Without it the scope defaults to local, which registers the server only for the directory you ran the command in — you'd have to be inside that folder for your assistant to see it. Your bookmarks have nothing to do with which code project you happen to be sitting in, so register it once for your whole account.

Config file locations (for the JSON form above):

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor: ~/.cursor/mcp.json (or per-project .cursor/mcp.json)

Verifying it's connected: ask your assistant to call the stats tool, or check your client's MCP/server log — a successful initialize handshake and a tools/list containing intake, today, decide, list_layer, restore, undo, stats means it's up.

After changing any environment variable below, fully restart your MCP client's connection to this server (quit/reopen Claude Desktop, or restart the Cursor MCP process) — it reads them once at startup.

First run

If you're on macOS and want Safari bookmarks included, the app hosting this server (Claude Desktop, your terminal, Cursor) needs Full Disk Access (System Settings → Privacy & Security → Full Disk Access) — ~/Library/Safari is protected. Without it, intake's response will show "sourceStatus": "permission_denied" and a warnings entry explaining exactly that; it will NOT silently look like an empty result. Chromium browsers and Firefox need nothing extra.

Call intake first — nothing shows up in today until you do. Then today gives you the day's actual queue. If both intake and today come back completely empty and sourceStatus says "ok", that's an honest "you have no bookmarks in the sources this scanned" — check sourceStatus before assuming something's broken:

`no_sources` even though you can see bookmarks in your browser? This detects Chromium browsers (Chrome, Edge, Brave, Arc, Vivaldi, Chromium) only in their standard per-OS install locations. If your browser uses a custom profile or data directory (a separate work profile, a portable install, a renamed user data folder, …), it won't be found automatically:

1. Open chrome://version in that browser (edge://version, brave://version, etc. — the same page exists in every Chromium browser) and copy the value next to Profile Path.
2. In your MCP client's config for this server, add an environment variable CHROMIUM_BOOKMARKS_PATH set to that path with /Bookmarks appended, e.g. "/Users/you/Library/Application Support/BraveSoftware/Brave-Browser/Custom/Bookmarks". Comma-separate multiple paths if you have more than one profile to include.
3. Fully restart the MCP client's connection to this server (see Configuration below).

This doesn't apply to Safari — see the Full Disk Access note above instead.

Talking to it

You never call these tools yourself — your assistant does. You just talk. If you'd rather be walked through it, run the `clean_up_my_bookmarks` prompt once (in Claude Code: /mcp; in Claude Desktop: the prompts menu) and it will set you up and do one round with you.

Otherwise, plain sentences are enough:

Two things worth knowing on day one:

• Nothing reminds you. There is no background process and no notification. The queue only moves when you ask — which also means it can never surprise you.
• An empty result explains itself. Every response carries a nextStep telling your assistant what to suggest, so "0 items" never has to be guessed at: it will say whether you simply haven't scanned yet, whether today's batch is done, or whether a source failed to read.

Tools

Every read tool (today/list_layer/stats) may still write to disk on the call you make: expiry and drip are computed lazily, so even "just looking" can move items between layers as a side effect. It only writes when something actually changed — a call that finds nothing due and nothing to drip touches nothing.

Plus two prompts:

Both intake and today also return a nextStep object (code + why) so your assistant knows what to suggest next instead of inferring it from an empty list. It is operational guidance only — never promotion.

Honesty about authorization

This server cannot verify that a tool call attributed to `"user"` actually came from you confirming something. Every parameter it receives — including actorClaim: "user" — comes from the AI, over the same channel as everything else. There is no separate, trusted channel this code can check. An earlier version of this README claimed "AI can't act without your say-so" as a server-enforced guarantee; that was tested and shown to be false — an AI that simply omits the field, or claims "user", goes through unchallenged. We're not going to repeat that claim.

What's actually true:

• Whether an AI needs your click-through before it can call a mutating tool depends on your MCP client's own tool-approval settings — Claude Desktop and Cursor both have per-tool or per-session approval prompts. That's the real gate, and it lives in your client, not in this server.
• actorClaim: "ai" is rejected unless you've explicitly set BOOKMARKS_LIFECYCLE_AUTO_DECIDE=true — but a caller can just omit the field (recorded as "mcp-client") or claim "user" instead, so don't treat this as a security boundary either.
• What this server actually guarantees is reversibility. Every mutation — including ones made under autoDecide, including expiry, including drip — is undoable. restore reverses lapsed → pending. undo reverses *any* state change, including kept and watching, by history event, with a preview mode to check first. If an AI does something you didn't want, the fix is undo, not a promise that it couldn't have happened.
• history records by: "user" | "ai" | "mcp-client" | "drip" | "expiry" | "system" on every change. The first two are claims, not verified identity — treat them as a hint for your own review, not evidence.

Configuration

All via environment variables in your MCP client config — none require touching this package's code. Restart your MCP client's connection after changing any of these.

| BOOKMARKS_LIFECYCLE_AUTO_DECIDE | false | Whether decide/restore/undo calls claiming actorClaim: "ai" are allowed through (see [Honesty about authorization](#honesty-about-authoriz