bookmarks-lifecycle

bookmarks-lifecycle

保存したブックマークにライフサイクルを設けます。

保存するのは簡単です。保存したものについて、ほとんど何も決めないまま、ただ増えていきます。これは、すべてのブックマークに期限を設けるローカル MCP サーバーです。24 時間以内に判断するか、30 日間様子を見るか、ずっと残すかを選べます。削除されるものはありません。期限までに判断しなかったブックマークは、ディスク上から消えるのではなく、意識から外れるだけです。また、AI が行った変更を含め、すべての変更を元に戻せます。

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

モデル

状態は 5 つあります。

状態	意味	カウントダウンする？
inbox	集約済みで、まだ判断対象になっていません	いいえ
pending	24 時間のレイヤー。今日実際に取り組むべきリストです	はい
watching	30 日間のレイヤー。「もう少し時間をかける」状態です	はい
kept	判断済み。ずっと残します	いいえ
lapsed	期限切れ、または手放した状態です。完全に復元可能で、削除されることはありません	いいえ

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

pending からは、3 つの結果のどれにでも移行できます。watching から選べる判断は keep のみです。これは上記のモデルに沿っています。watch や drop を取り消すには、すでに移行した項目を再度判断するのではなく、undo を使ってください。

ブックマークは、集約した時点ですべてが pending に入るわけではありません。一度に 3,000 件の古いブックマークをインポートすると、すべてが同じ日に期限切れになり、この仕組みの意味がなくなってしまいます。代わりに、毎日一定の割合で少しずつ追加されます（デフォルトでは 1 日 15 件、古いものから順です。ソースに保存日時がある場合は、実際の保存日を基準にします）。これはバックグラウンドタイマーではなく、ツールを呼び出すたびに遅延実行で計算されます。また、長期間使わなかった分が蓄積されることはありません。何日間離れていても、1 回の呼び出しで追加されるのは最大 1 日分です。1 日 15 件のペースでは、3,000 件の未処理ブックマークを解消するのに、毎日使っても現実的には数か月かかります。これは「リマインダーなし、要求されない限り何も実行されない」という方式の正直なトレードオフであり、習慣形成アプリの代わりになるという主張ではありません。

インストール

アカウントも API キーも設定も不要です。インストールすればすぐに使えます。

Claude Code：

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

Claude Desktop／Cursor／任意の MCP クライアント（mcpServers JSON）：

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

開発のためにソースから実行する場合は、parse-bookmarks、bookmarks-mcp、このリポジトリを兄弟ディレクトリとしてクローンし、bookmarks-mcp で npm install を実行してから bookmarks-lifecycle でも実行します。次に、クライアントの接続先を node /absolute/path/to/bookmarks-lifecycle/src/index.js に設定してください。

-s user を使用してください。 これを指定しないと、スコープはデフォルトの local となり、コマンドを実行したディレクトリにのみサーバーが登録されます。そのフォルダー内にいないと、アシスタントからサーバーを参照できません。ブックマークは、作業中のコードプロジェクトとは無関係なので、アカウント全体に対して一度登録してください。

設定ファイルの場所（上記の JSON 形式の場合）：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor：~/.cursor/mcp.json（またはプロジェクトごとの .cursor/mcp.json）

接続の確認：アシスタントに stats ツールを呼び出すよう依頼するか、クライアントの MCP／サーバーログを確認してください。initialize ハンドシェイクが成功し、tools/list に intake, today, decide, list_layer, restore, undo, stats が含まれていれば、接続されています。

以下の環境変数を変更した後は、このサーバーへの MCP クライアント接続を完全に再起動してください（Claude Desktop を終了して再度開くか、Cursor の MCP プロセスを再起動します）。環境変数は起動時に一度だけ読み込まれます。

初回実行

macOS をお使いで Safari のブックマークも含めたい場合、このサーバーをホストするアプリ（Claude Desktop、ターミナル、Cursor）に フルディスクアクセス （システム設定 → プライバシーとセキュリティ → フルディスクアクセス）が必要です。~/Library/Safari は保護されています。許可しない場合、intake の応答には "sourceStatus": "permission_denied" と、理由を正確に説明する warnings エントリが表示されます。空の結果として黙って扱われることはありません。Chromium ブラウザーと Firefox では追加の設定は不要です。

まず intake を呼び出してください。実行するまで today には何も表示されません。その後、today でその日の実際のキューが表示されます。intake と today の両方の結果が完全に空で、sourceStatus が "ok" の場合は、「スキャンしたソースにブックマークがない」という正しい結果です。何かが壊れていると考える前に、sourceStatus を確認してください。

sourceStatus	意味
no_sources	このマシンで対応ブラウザーがひとつも検出されませんでした
permission_denied	1 つ以上のソースを読み取れませんでした（よくあるのは、フルディスクアクセスを許可していない Safari です）
empty	すべてのソースのスキャンに成功し、実際にブックマークが 0 件でした
ok	スキャンに成功し、何かが見つかりました

ブラウザーにブックマークが見えるのに no_sources と表示されますか？ Chromium ブラウザー（Chrome、Edge、Brave、Arc、Vivaldi、Chromium）は、OS ごとの標準インストール場所にある場合のみ検出されます。ブラウザーでカスタムプロファイルまたはデータディレクトリ（別の仕事用プロファイル、ポータブルインストール、名前を変更したユーザーデータフォルダーなど）を使用している場合、自動では見つかりません。

1. そのブラウザーで chrome://version（edge://version、brave://version など。すべての Chromium ブラウザーに同じページがあります）を開き、Profile Path の横にある値をコピーします。
2. MCP クライアントの、このサーバーの設定に、環境変数 CHROMIUM_BOOKMARKS_PATH を追加し、コピーしたパスの末尾に /Bookmarks を付けた値を設定します。例： "/Users/you/Library/Application Support/BraveSoftware/Brave-Browser/Custom/Bookmarks"。 複数のプロファイルを含める場合は、パスをカンマで区切ってください。
3. MCP クライアントとこのサーバーとの接続を完全に再起動します（下記の設定を参照）。

Safari には該当しません。代わりに、上記のフルディスクアクセスに関する注意をご覧ください。

話しかけ方

これらのツールを自分で呼び出す必要はありません。アシスタントが実行します。あなたは話しかけるだけです。手順に沿って進めたい場合は、clean_up_my_bookmarks プロンプトを一度実行すると（Claude Code では /mcp、Claude Desktop ではプロンプトメニュー）、設定を済ませて一緒に一度操作できます。

それ以外の場合は、普通の文章で十分です。

たとえば、こう伝えます	実行されること
「ブラウザーのブックマークを取り込んで」	intake — ブラウザーをスキャンし、新しい URL を受信箱に追加します
「今日は何を見ればいい？」	today — その日のキューを古い順に表示します。1 日の上限まで表示されます
「最初のものは残して、最後の 2 つは削除して」	decide — 確認後に実行されます。確認前には実行されません
「やっぱり、取り消して」	undo — 「残す」も含め、あらゆる判断を元に戻します
「手放したものは何？」	list_layer で lapsed を表示 — すべて残っています
「あれを戻して」	restore — 新しい期限でキューに戻します
「あとどれくらい？」	stats — レイヤーごとの件数と、受信箱でまだ待機中の件数を表示します

初日に知っておくとよいことが 2 つあります。

• リマインダーはありません。 バックグラウンドプロセスも通知もありません。 キューが動くのは、あなたが依頼したときだけです。そのため、意図せず驚かされることもありません。
• 空の結果には理由が示されます。 すべての応答には nextStep が含まれており、アシスタントに次に何を提案すべきかを伝えます。そのため、「項目 0 件」の理由を推測する必要はありません。まだスキャンしていないのか、今日の分が終わったのか、ソースを読み取れなかったのかが示されます。

ツール

ツール	機能
intake	ブックマークのソースをスキャンし、新しいものを inbox に統合します。移動または消失したものも照合します
today	現在の pending レイヤーを古い順に表示します。毎日の開始地点です
decide	1 つ以上の項目を判断します：keep / watch / drop
list_layer	任意のレイヤーをページ分けして表示します（デフォルトは 1 ページあたり 50 件）。lapsed（「手放したもの」）も含みます
restore	lapsed の項目を pending に戻し、時計をリセットします
undo	項目を、その項目自身の履歴イベントの直前の状態に戻します。lapsed だけでなく、kept / watching にも使えます
stats	レイヤーごとの件数、今日の判断件数、inbox で待機中の件数を表示します

読み取りツール（today / list_layer / stats）を呼び出すと、ディスクへの書き込みが発生する場合もあります。有効期限切れと段階的な振り分けは遅延計算されるため、単に「見る」だけでも副作用として項目がレイヤー間を移動することがあります。実際に変更があった場合にのみ書き込みます。期限切れの項目も振り分け対象もない場合、呼び出しによって何も変更されません。

さらに、2 つのプロンプトがあります：

プロンプト	使用するタイミング
clean_up_my_bookmarks	初回。判断時計の仕組みを説明し、intake を実行して、小規模な仕分けを 1 回行います
daily_triage	以降、毎日。today → 項目ごとに提案 → 確認を待つ → 適用

intake と today はどちらも nextStep オブジェクト（code + why）も返すため、アシスタントは空のリストから推測するのではなく、次に何を提案すべきかを把握できます。これは運用上のガイダンスにすぎず、昇格を促すものではありません。

認可についての正確な説明

このサーバーは、"user" によるものとされるツール呼び出しが、実際にあなたの確認を経たものかどうかを検証できません。 actorClaim: "user" を含む、受け取るすべてのパラメーターは、ほかのすべての情報と同じチャネルを通じて AI から送られます。このコードが確認できる、別個の信頼できるチャネルはありません。この README の以前のバージョンには、「AI はあなたの許可なしに操作できない」とサーバーが保証しているかのような記載がありましたが、テストによって誤りであることが示されました。フィールドを省略するだけでも、"user" と名乗るだけでも、AI は何のチェックも受けずに処理を進められます。この主張を繰り返すことはしません。

実際に正しいのは、次のとおりです：

• AI が変更を伴うツールを呼び出す前にあなたのクリックによる承認を必要とするかどうかは、MCP クライアント独自のツール承認設定によって決まります — Claude Desktop と Cursor には、ツールごとまたはセッションごとの承認プロンプトがあります。これが実際の制御手段であり、このサーバーではなく、あなたのクライアントにあります。
• actorClaim: "ai" は、BOOKMARKS_LIFECYCLE_AUTO_DECIDE=true を明示的に設定していない限り拒否されます。しかし呼び出し元は、フィールドを省略する（"mcp-client" として記録されます）か、代わりに "user" と名乗るだけで済むため、これもセキュリティ境界として扱わないでください。
• このサーバーが実際に保証するのは、変更を取り消せることです。 autoDecide による変更、有効期限切れ、段階的な振り分けを含め、すべての変更を元に戻せます。restore は lapsed → pending を元に戻します。undo は preview モードで事前に確認したうえで、kept や watching を含むあらゆる状態変更を、履歴イベント単位で元に戻します。AI が望まない操作をした場合の修正方法は undo です。操作が行われるはずはなかったという約束ではありません。
• history は変更ごとに by: "user" | "ai" | "mcp-client" | "drip" | "expiry" | "system" を記録します。最初の 2 つは検証済みの身元ではなく、申告です。証拠ではなく、自分で確認する際の手がかりとして扱ってください。

設定

すべて MCP クライアントの設定にある環境変数で指定します。このパッケージのコードを変更する必要はありません。これらを変更した後は、MCP クライアントの接続を再起動してください。

変数	デフォルト	説明
BOOKMARKS_LIFECYCLE_PENDING_HOURS	24	未決定の項目が期限切れになるまで、pending レイヤーにとどまる時間
BOOKMARKS_LIFECYCLE_WATCHING_DAYS	30	未決定の項目が期限切れになるまで、watching レイヤーにとどまる日数
BOOKMARKS_LIFECYCLE_DRIP_PER_DAY	15	1 日あたりに inbox から pending に昇格できる最大項目数（間が空いても累積しません）
BOOKMARKS_LIFECYCLE_AUTO_DECIDE	false	actorClaim: "ai" を申告する decide／restore／undo 呼び出しを許可するかどうか（認可に関する注意を参照。これはセキュリティを保証するものではありません）
BOOKMARKS_LIFECYCLE_STATE_DIR	~/.bookmarks-lifecycle	state.json（およびそのロック／バックアップファイル）の保存場所

保存される内容

ファイルは 1 つです。~/.bookmarks-lifecycle/state.json。人が読めるプレーンな JSON です。書き込みはアトミックに行われ（一時ファイル → fsync → rename、クラッシュ時に中途半端な書き込みが残ることはありません）、上書きの前に直前の世代が state.json.bak として保存されます。

ブックマークごとに、ID、URL、タイトル、認識しているブラウザーのソース（2 つのブラウザーに保存された URL は両方とも保持されます）、ブラウザーによる実際の追加日時（addedAt。古い順に並べる際に使用します。ソースから提供されなかった場合は null となり、捏造されることはありません）、現在のライフサイクル状態、その状態になった日時、すべての遷移の完全な履歴（各履歴には、固定の eventId、日時、操作を行った人／もの、任意のメモが含まれます）、および正常に再スキャンされたソースのいずれからも見つからなくなったブックマークを示す sourceGone フラグを保存します（その記録は残ります。ここでは自動削除は一切行いません。読み取りに失敗しただけのソースは、消失の根拠にはなりません）。

保存されるのは識別情報とユーザー自身の判断だけで、ページの内容自体は保存されません。ファイルには内部 version があり、将来のツールバージョンがこのバージョンでは理解できない形式を書き込んだ場合、このバージョンは推測で処理せず、ファイルに触れることを拒否します。

同時アクセス：たとえば Claude Desktop と Cursor のように、2 つの MCP クライアントが同じ状態ファイルを使ってこのサーバーを同時に実行した場合、ロックファイル（state.json.lock）によって処理が直列化されます。後から実行したクライアントは、先行したクライアントの変更を黙って上書きするのではなく、短時間待機します。

タイムゾーン

stats の「今日」（decidedToday 用）は、このサーバーを実行しているマシンのローカルカレンダーの日付を使用します。このサーバーは自分のマシン上でしか実行されず（ローカルのブラウザーファイルを直接読み取ります。リモート／ホスト型のデプロイはありません）、その時計はユーザーが使っている時計と同じです。これは意図された動作であり、修正すべき不具合ではありません。レイヤーの期間である 24 時間／30 日は、暦日数ではなく厳密な経過時間です。夏時間への移行によって壁時計の時刻は変わりますが、実際に 24 時間が経過する長さは変わりません。

保証

• ブラウザーのブックマークファイルには一切触れません。 読み取りはすべて bookmarks-mcp に委任されており、これ自体も読み取り専用です。このパッケージが書き込むファイルは、独自の state.json、state.json.bak、および一時的なロックファイルだけです。
• ライフサイクルの記録が削除されることはなく、状態の変更はすべて元に戻せます。 具体的に何が保護され、何が保護されないかについては、認可に関する注意を参照してください。
• ネットワーク呼び出し、テレメトリ、アカウントはありません。

設計上の境界

• バックグラウンドプロセスも、cron も、プッシュ通知もありません。 ここにあるものはすべて、ツールを呼び出した瞬間に遅延評価されます。これが「デーモン不要」を実現する仕組みです。正直なところ、こちらから尋ねなければ、キューは静かに期限切れになります。誰もリマインドしてくれません。
• UI はありません。 これはアプリではなく、MCP ツールのままです。
• AI はご自身でご用意ください。 このサーバーは推論を行わず、料金もかかりません。ブックマークを評価する AI は、すでに接続しているものを使います。このプロジェクトが提供するのはステートマシンとプロンプトであり、モデルではありません。

開発元

Burn 451 を手掛けるチームが開発しました。ここでの24時間／30日の仕組みは、Burn のものをモデルにしています。異なるのは、このツールは、すでに作業している場所で、呼び出したときにだけ動作する点です。同じアイデアを自動で実行し、毎日リマインドして、スマートフォンからも利用したい場合は Burn をお使いください。このプロジェクトは、どちらの場合でも単独で役立ちます。

ライセンス

MIT