second-brain-bridge

SecondBrainBridge 是一个 Model Context Protocol（MCP）连接器，可让 ChatGPT 搜索并基于你的 Obsidian 风格 Markdown 知识库进行推理——也就是存放在你 Mac 上的笔记文件夹。读取操作在本地执行，请求的结果通过经过身份验证的中继传递——每项操作都通过一个小型本地 Agent 在你自己的 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 Agent（需要 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

将它指向你的知识库文件夹——设置 SECONDBRAIN_VAULT=/path/to/your/vault，或将路径保存到 ~/.secondbrainbridge-agent.json。Agent 首次读取存放在受保护位置（Documents、Desktop 或 iCloud Drive）的知识库时，macOS 会询问一次是否授予“文件与文件夹”访问权限——点击好。

3. 连接 ChatGPT：设置 → Plugins → 开启开发者模式（安全与登录）→ 创建自定义插件 → 粘贴 MCP 服务 URL https://secondbrainbridge.vercel.app/mcp → 身份验证选择 OAuth → 登录并点击允许。

就这么简单。新建聊天后，试试：“搜索我的笔记，找出 Q3 规划文档”，或 “我对 Project Atlas 做了什么决定？”

你的 Mac 必须保持唤醒状态并运行 Agent。npx second-brain-agent install 可让它在登录时自动启动，并在崩溃时重新启动。

管理 Agent

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	按关键词搜索知识库；返回排序后的段落	免费
ask	提出问题，并获取基于你自己笔记的回答	免费
get_note	按标题或 ID 阅读一篇完整笔记	免费
list_sources	列出知识库中的文件夹/来源	免费
backlinks	显示链接到某篇笔记的笔记（[[wikilinks]] 图谱）	Pro
create_note	在知识库中创建一篇新的 Markdown 笔记	Pro
get_plan	显示你当前的方案和升级链接	免费

当前检索采用 v1 排序：关键词匹配加标题匹配，因此回答始终基于笔记中实际出现的段落。（语义/云端排序是 Pro/云端增强功能。）

---

方案

SecondBrainBridge 可免费开始使用。需要完整图谱和写入权限时，可升级到 Pro。

	免费	Pro — $8/mo
搜索、提问和阅读笔记	✓	✓
列出文件夹/来源	✓	✓
每日搜索次数	20 / 天	无限制
反向链接 / [[wikilinks]] 图谱	—	✓
从聊天中创建笔记	—	✓
跨多台 Mac 的云端聚合	—	即将推出

账单由 Stripe 处理。访问 secondbrainbridge.vercel.app/upgrade 升级，并在任意聊天中运行 get_plan，即可查看当前方案和升级链接。中继会强制执行免费方案的每日上限，并根据你的 Stripe 订阅控制 Pro 工具的访问权限（目前为测试模式）。

---

自托管

你可以运行自己的中继服务，这样就无需依赖托管实例。

前提条件： 一个 Vercel 账户和一个 Supabase 项目（免费套餐即可）。

1. 存储 — 在 Supabase 项目的 SQL 编辑器中运行 supabase/schema.sql。它会创建一个类似 Redis 的轻量 KV 和队列表面（nb_* 函数），并启用 RLS。
2. 部署 server/ 目录到 Vercel。
3. 设置环境变量（参见 server/.env.example）：
   • SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY — 你的项目 URL 和 service-role 密钥
   • 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. 将 Agent 指向该服务：npx second-brain-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

工作原理

• 身份验证 — 使用 PKCE 和动态客户端注册（RFC 7591）的 OAuth 2.1。ChatGPT 会自行注册，用户在 SecondBrainBridge 授权页面登录，然后 ChatGPT 获取具有特定权限范围的 MCP 访问令牌。JWT 使用 HMAC 签名；分为三种类型（session、agent、mcp），各自拥有不同权限。可选通过 Resend 验证电子邮件（RESEND_API_KEY）；默认关闭，且仅在选择启用时强制执行（REQUIRE_EMAIL_VERIFICATION）。
• 中继 — MCP 工具调用 → 作业推送到 jobs:<user>（TTL ≤ 调用方的等待时长，因此被遗弃的作业不会延迟执行）→ 向持有长轮询的 Mac Agent 分发作业，通常在约 200ms 内完成；Agent 执行作业并推送结果 → MCP 处理程序返回结果。长轮询可在作业到达时立即分发，而非按固定间隔轮询，因此中继开销约为 300ms，而不是约 1s。仅当 Agent 处于活动连接状态时，才会被视为“在线”。中继还会强制执行 Free 套餐的每日搜索上限，并根据账户的 Stripe 订阅解锁 Pro 工具。
• Agent — 一个零依赖的 Node CLI。它会为你的知识库文件夹中的 Markdown 文件建立索引，并在本地回答检索查询（按关键词和标题匹配度排序）；create_note 会在知识库中创建新的 Markdown 文件。读写操作直接针对文件系统执行——首次访问受保护的文件夹时，会触发一次性的 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 上读取和写入。中继会临时存储请求的内容，并放入短期作业/结果队列中——作业负载保存在类似 Redis 的存储中，TTL 较短，并会在交付后删除。
• Agent 令牌（以及你的知识库路径）存储在 ~/.secondbrainbridge-agent.json（模式为 600）；知识库路径也可以通过 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 仓库之外。

私有知识库索引（源 Agent 1.1）

需要 Node 22.13+。在 Agent 配置中设置确切的知识库，然后运行 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。