second-brain-bridge

SecondBrainBridge は、Model Context Protocol（MCP）コネクターです。ChatGPT が、Mac 上のメモフォルダーである Obsidian 形式の Markdown Vault を検索し、内容に基づいて推論できるようにします。読み取りはローカルで実行され、要求された結果は認証済みのリレーを経由します。すべての操作は、小さなローカルエージェントを通じて あなた自身の Mac 上で実行されます。クラウド側にあるのは、ChatGPT と Mac の間でリクエストを中継するだけの、状態を保持しないリレーのみです。

  ChatGPT  ──OAuth──►  SecondBrainBridge relay  ──job queue──►  second-brain-agent  ──►  Obsidian vault
 (connector)          (Vercel, stateless)      (your Mac, polls & executes)      (Markdown notes on your Mac)

メモが読み書きされる場所は、あなたの Mac だけです。リレーに保存されるのは、有効期間の短いジョブのペイロードとアカウント情報のみです。ジョブの実行中でない限り、リレーがメモの内容を見ることはなく、ジョブは数秒で期限切れになります。

---

ユーザー向け — 3 ステップ

1. アカウントを作成します。 secondbrainbridge.vercel.app にアクセスして、ペアリングコードを生成します。

2. Mac エージェントをインストールします（Node 18+ が必要です）。

npx second-brain-agent pair <YOUR-CODE>   # link this Mac to your account
npx second-brain-agent install            # keep it running on every restart

Vault フォルダーを指定します。SECONDBRAIN_VAULT=/path/to/your/vault を設定するか、~/.secondbrainbridge-agent.json にパスを保存してください。保護された場所（Documents、Desktop、iCloud Drive）にある Vault をエージェントが初めて読み取るとき、macOS から ファイルとフォルダーへのアクセス許可 を求められます。一度だけ OK をクリックしてください。

3. ChatGPT に接続します。 「Settings」→ Plugins → 「Developer mode」（「Security & login」）をオンにする → カスタムプラグインを Create → MCP サーバーの URL https://secondbrainbridge.vercel.app/mcp を貼り付ける → Authentication で OAuth を選択 → サインインして Allow を選択します。

これで完了です。新しいチャットで、「Q3 の計画書をメモから検索して」 や 「Project Atlas について、何を決めた？」 と尋ねてください。

エージェントの実行中は、Mac のスリープを解除しておく必要があります。npx second-brain-agent install を実行すると、ログイン時に自動起動し、クラッシュした場合も再起動します。

エージェントの管理

npx second-brain-agent status      # is it paired & reachable?
npx second-brain-agent logs        # recent activity
npx second-brain-agent uninstall   # stop auto-start

---

ChatGPT でできること

ツール	操作	プラン
search_knowledge	Vault をキーワードで検索し、関連度順の抜粋を返します	無料
ask	質問し、自分のメモに基づいた回答を得ます	無料
get_note	タイトルまたは ID を指定して、ノート全体を読み取ります	無料
list_sources	Vault 内のフォルダーとソースを一覧表示します	無料
backlinks	ノートへのリンクを含むノート（[[wikilinks]] グラフ）を表示します	Pro
create_note	Vault に新しい Markdown ノートを作成します	Pro
get_plan	現在のプランとアップグレード用リンクを表示します	無料

検索は v1 の関連度順キーワード検索とタイトル一致を使用するため、回答は実際にノートに含まれる抜粋に基づきます。（セマンティック検索／クラウド検索は Pro／クラウド向けの拡張機能です。）

---

プラン

SecondBrainBridge は無料で始められます。グラフ全体へのアクセスや書き込み機能が必要になったら、Pro にアップグレードしてください。

	無料	Pro — $8/mo
メモの検索、質問、読み取り	✓	✓
フォルダー／ソースの一覧表示	✓	✓
1 日あたりの検索回数	20 回／日	無制限
バックリンク／[[wikilinks]] グラフ	—	✓
チャットからノートを作成	—	✓
Mac 間のクラウド集約	—	近日公開

お支払いは Stripe で処理されます。secondbrainbridge.vercel.app/upgrade でアップグレードできます。また、任意のチャットで get_plan を実行すると、現在のプランとアップグレード用リンクを確認できます。リレーは無料プランの日次上限を適用し、Stripe のサブスクリプションに応じて Pro のツールを制限します（現在はテストモードです）。

---

セルフホスト

ホストされたインスタンスに依存しないよう、ご自身でリレーを実行できます。

前提条件： Vercel アカウントと Supabase プロジェクト（無料プランで問題ありません）。

1. ストレージ — Supabase プロジェクトの SQL エディターで supabase/schema.sql を実行します。RLS が有効な、Redis 形式の小規模な KV ＋キュー用インターフェース（nb_* 関数）が作成されます。
2. デプロイ — server/ ディレクトリを Vercel にデプロイします。
3. 環境変数を設定 — server/.env.example を参照してください。
   • SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY — プロジェクトとサービスロールキー
   • JWT_SECRET — openssl rand -hex 32
   • STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET — Pro プラン用（省略可能。設定しない場合は Free プランのみ）
4. 確認： curl https://YOUR-APP.vercel.app/api/health を実行し、redisConfigured、redisOk、jwtSecretSet がすべて true であることを確認します。
5. エージェントの接続先を指定します：npx second-brain-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

仕組み

• 認証 — PKCE と Dynamic Client Registration（RFC 7591）を使用した OAuth 2.1 です。ChatGPT が自身を登録し、ユーザーは SecondBrainBridge の同意ページでサインインします。その後、ChatGPT はスコープが設定された MCP アクセストークンを取得します。JWT は HMAC 署名され、権限の異なる 3 種類（session、agent、mcp）があります。Resend（RESEND_API_KEY）によるメール認証も設定できます。設定されていない場合は無効で、必須にするかどうかは任意で設定できます（REQUIRE_EMAIL_VERIFICATION）。
• リレー — MCP ツール呼び出し → jobs:<user> にジョブを投入（TTL は呼び出し元の待機時間以下に設定されるため、放棄されたジョブが遅れて実行されることはありません）→ ロングポーリングを継続中の Mac エージェントに約 200 ms 以内にジョブを渡して実行し、結果を返送 → MCP ハンドラーが結果を返します。ロングポーリングにより、固定間隔ではなく到着時にジョブが配信されるため、リレーのオーバーヘッドは約 1 秒ではなく約 300 ms です。エージェントは、接続中のみ「オンライン」とみなされます。また、リレーは Free プランの 1 日あたりの検索上限を適用し、アカウントの Stripe サブスクリプションに基づいて Pro ツールを有効にします。
• エージェント — 依存関係のない Node CLI です。Vault フォルダー内の Markdown ファイルをインデックス化し、検索クエリにローカルで回答します（キーワードとタイトルの一致度で順位付け）。create_note は新しい Markdown ファイルを Vault に書き込みます。読み書きはファイルシステムに直接行われます。保護されたフォルダーに初めてアクセスすると、macOS の「ファイルとフォルダー」権限の確認が一度だけ表示されます。macOS LaunchAgent によって、ログイン後もクラッシュ後もエージェントが起動した状態に保たれます。

リポジトリの構成

server/    Vercel functions: OAuth + MCP endpoint + relay + Stripe billing   (deploy this)
agent/     second-brain-agent — the npm-published Mac CLI that indexes your vault  (users npx this)
kit/       Browser automations: register the dev-mode connector AND
           fill the OpenAI directory submission (see kit/README.md)
supabase/  schema.sql for self-hosting the storage
test/      end-to-end OAuth + MCP integration test

開発

# server
cd server && cp .env.example .env.local   # fill in, then: vercel dev
# end-to-end test against a live deployment (reads ../.env.local)
node test/e2e-oauth.mjs
# agent unit tests
node --test agent/test-agent-unit.mjs

セキュリティとプライバシー

• ノートの読み書きはお使いの Mac 上でのみ行われます。リレーは要求された内容を、存続期間の短いジョブ／結果キューに一時的に保存します。ジョブのペイロードは短い TTL を持つ Redis 形式のストレージに保存され、配信後に削除されます。
• エージェントトークン（および Vault のパス）は ~/.secondbrainbridge-agent.json に保存されます（モード 600）。Vault のパスは SECONDBRAIN_VAULT から取得することもできます。
• シークレットはコミットされません。.gitignore と .env.example ファイルを参照してください。
• 書き込みツール（create_note）には破壊的な操作としてマークが付いているため、ChatGPT はノートを追加する前に確認を求めます。

ライセンス

MIT © Isaiah Dupree

本番ストレージと所有者の検証

Relay 1.4 は、設定済みの共有 Supabase プロジェクト上に、サービスロール専用の分離されたテーブル／関数を使用します。本番環境では、ストレージ設定がない場合は起動せず、RPC リクエストのタイムアウトを 10 秒に制限し、ストレージまたは署名の設定が利用できない場合は HTTP 503 を返します。このバージョンをデプロイする前に、リポジトリに含まれる分離ストレージ用マイグレーションを適用してください。このマイグレーションによって、別のブリッジのアカウントテーブルや関数が置き換えられることはありません。

node --env-file=.env.local test/live-storage.mjs は、一時的な統合キーを使用して、実際の永続ストア、FIFO、有効期限、カウンターを検証します。BRIDGE_SESSION_FILE=/private/owner-session.json BRIDGE_READ_TOOL=READ_TOOL node test/live-relay.mjs は、実際の所有者セッション、PKCE OAuth、ホスト型 MCP、ペアリング済み Mac の読み取りを検証します。このブリッジのインベントリツールを選択してください。レビュアーのデータは、ライブ受け入れテストの対象にはなりません。認証情報とセッションは Git の外部に保管してください。

プライベートボルトインデックス（ソースエージェント 1.1）

Node 22.13+ が必要です。エージェントの設定で正確なボルトを指定してから、node agent/cli.mjs index-install を実行します。これにより、~/Library/Application Support/SecondBrainBridge/ の下にプライベートな SQLite スナップショットが作成され、15 分ごとに変更が差分チェックされます。Markdown／テキストファイルをインデックス化し、ドットディレクトリとシンボリックリンクを除外します。5,000 ファイルで無告知に上限を設けることなく、完全な件数を報告します。検索／一覧のレスポンスには、スナップショットの時刻と 15 分間の鮮度境界が含まれます。フェッチでは現在のファイルテキストを読み取り、ノートの作成時には上書きを拒否し、スナップショットを無効化します。埋め込み／モデルサービスは起動しません。

node agent/cli.mjs index-status は、件数と鮮度を報告します。node test/live-index.mjs は、実際の ID の網羅性、プライベートなアクセス許可、最新テキストとの比較、読み取り／検索結果を検証します。uninstall は、プライベートインデックスを保持したまま更新ジョブを削除します。このソースアップグレードについて、npm への公開は行われていません。