personalbrain-mcp

thebrain-mcp

闪电公路上的第一座城市。

一个 MCP 服务，让 AI Agent 能够读写个人知识图谱，并通过 Bitcoin Lightning 小额支付实现自我盈利。

本项目的隐喻取材于 The Phantom Tollbooth，谨以钦佩之情致敬其作者 Norton Juster 和插画家 Jules Feiffer（1961 年）。Milo、Tock、Tollbooth、Dictionopolis 和 Digitopolis 都是 Juster 先生非凡想象力的结晶。我们只是构建了支付基础设施。

---

第一座城市

每条公路都需要它的第一座城市。在收费站开始收取费用、管理局盖下采购订单之前，总得有人先建起一处值得驶向的目的地。

thebrain-mcp 就是这座城市——一个部署在 Horizon 上的 FastMCP 服务，为 AI Agent 接入 TheBrain。TheBrain 是一个个人知识图谱，历经十年构建，包含 9,000 多个相互关联的思维条目。每项思维条目、链接、附件和笔记操作都会直接映射到 TheBrain 的云端 API api.bra.in。

它也是 Tollbooth DPYC™ 的试验场——首个通过 Bitcoin Lightning 小额支付对每次工具调用计费的 MCP 服务。预充值、使用、续充。没有订阅，没有绑定账单账户的 API 密钥，也没有法币支付处理商。这项创新的核心在于：MCP 服务的运营者可以通过 Lightning 小额支付，将 AI Agent 的访问权限变现，而且无需在对话中途打扰客户端。

入门

通过 Horizon MCP 连接

将任何兼容 MCP 的客户端（Claude Desktop、Cursor 或你自己的 Agent）连接到在线端点：

https://personal-brain.fastmcp.app/mcp

无需配置。客户端通过 OAuth 连接；连接中不会持有 npub，直到你回答一条 Nostr 私信并通过验证后才会持有（依次调用 request_npub_proof 和 receive_npub_proof）。持有你 nsec 的客户端则会为每个请求签名（NIP-98），无需私信。此后，工具只需传入 npub。

首次连接流程

1. session_status — 查看当前会话状态。
2. 从 dpyc-oracle 的 how_to_join() 工具获取你的 patron npub——这是你注册为 DPYC™ Citizen 时使用的 npub，也是你进行信用操作时的身份标识。
3. Secure Courier 入门流程：
   • 调用 request_credential_channel(sender_npub=<patron_npub>, service=<service>)——打开一个 Secure Courier 通道，向你的 Nostr 客户端发送欢迎私信，并返回该通道的 nonce。
   • 在 Nostr 客户端中回复 JSON 格式的凭证：{"api_key": "...", "brain_id": "..."}
   • 调用 receive_credentials(sender_npub=<patron_npub>, service=<service>, nonce=<that nonce>)——将凭证存入保险库并激活会话。
4. list_brains → set_active_brain — 选择要使用的脑图。
5. brain_query — 开始探索你的知识图谱。

回访用户无需重新执行此流程：首次使用时，会话会从保险库中恢复。

Secure Courier

凭证通过加密的 Nostr 私信传递，不会出现在聊天窗口中。服务首次从中继收到凭证后，会通过私信将 ncred1... 凭证卡片发送回 patron，方便扫描并粘贴复用。

人工参与： patron 必须通过 Nostr 客户端主动批准每次凭证传递。切勿自动轮询或自动重试 receive_* 调用——每次 receive_credentials 都会以破坏性方式清空中继（取回后依据 NIP-09 删除）。每次凭证传递只调用一次。

额度模型

类别	定价提示	示例
free	0 sats	session_status、check_balance、check_price
read	1 sat	get_thought、search_thoughts、get_note
write	5 sats	create_thought、create_link、update_thought
heavy	10 sats	brain_query、get_modifications

实际价格由运营者在 Neon 中通过每个工具的 api_sats 定价模型动态设定。身份验证和余额工具始终免费。

额度以批次形式发放，每批有一个 tranche_lifetime（TTL）。批次按 FIFO 顺序消耗；过期批次会自动清理。使用 check_balance 查看余额、有效批次和使用历史记录。使用 Bitcoin Lightning 通过 purchase_credits 充值。

安全

• 身份是 Nostr 密钥对 — 用户通过 npub（Nostr 公钥）识别，而非电子邮件或用户名。nsec（私钥）由用户保管，绝不共享，也绝不发送给服务。
• 身份随连接提供 — 持有 nsec 的客户端会为每个 HTTP 请求签名（NIP-98，kind 27235）；OAuth 客户端则通过回答 Nostr 私信，将 npub 一次性证明到其连接中（request_npub_proof → receive_npub_proof）。工具不携带证明参数。
• 人在回路中 — 用户会在其 Nostr 客户端中批准每项证明，并选择有效时长，最长 30 天。证明到期后，通过新一轮请求／接收流程续期。
• 通过 Secure Courier 传递凭据 — TheBrain API 密钥和 brain ID 通过 NIP-44 加密的 Nostr 私信发送，存储在 Neon Postgres 中，绝不会显示在聊天窗口中。

BrainQuery (BQL)

一种专为 TheBrain 打造的 Cypher 子集查询语言。Agent 和用户使用同一套形式化语法表达图操作 — 通过 MATCH、CREATE、SET、MERGE 和 DELETE 实现完整的 CRUD。

MATCH (n {name: "Projects"})-[:CHILD]->(m) RETURN m
MATCH (n) WHERE n.name =~ "quarterly review" RETURN n
MATCH (p {name: "Ideas"}) CREATE (p)-[:CHILD]->(n {name: "New Concept"})
MATCH (root {name: "Company"})-[:CHILD*1..3]->(d) WHERE d.name CONTAINS "Budget" RETURN d

支持可变长度路径、多跳链、包含 AND／OR／NOT／XOR 的复合 WHERE、相似度搜索和属性存在性检查。完整语法见 BRAINQUERY.md。

故障排除

工具调用失败时，请阅读响应内容 — 它会说明发生了什么以及接下来该怎么做。凭据生命周期状态并非错误，而是有明确处理指引的正常情况。

情况	处理方法
需要 proof	调用 request_npub_proof，然后调用 receive_npub_proof — 开始新一轮请求／接收流程。proof 的有效期由用户批准时选择，最长 30 天。
额度不足	调用 purchase_credits 充值。
冷启动／会话尚未就绪	10-15 秒后重试。
未找到凭据	按照 Secure Courier 入门流程（上文第 3 步）操作。
上游 API 错误	仅当错误明确提到 TheBrain API 故障时适用。这不是凭据或账单问题。

不要打扰用户： 除非错误消息明确指出凭据缺失或已过期，否则不要要求用户重新进行身份验证或重新执行 Courier 流程。

自托管

本地安装和设置说明，请参阅 INSTALL.md 和 QUICKSTART.md。

要运行自己的实例，请设置以下环境变量：

必需

变量	用途
TOLLBOOTH_NOSTR_OPERATOR_NSEC	运营者的 Nostr 私钥 — 用于身份、Secure Courier 私信和审计签名的唯一引导密钥

这是服务读取的唯一环境变量。经过认证的运营者通过加密 Nostr 私信从 Authority 获取 Neon 数据库 URL — 环境变量中不会读取 NEON_DATABASE_URL。中继集合来自共享的 dpyc-community 注册表，批次有效期和限制来自运营者的定价模型 — 它们都不是环境变量。

通过 Secure Courier 提供凭据（而非环境变量）

所有密钥都通过 Secure Courier 流转，不会出现在环境变量中：

凭据	交付方式
TheBrain API 密钥 + brain ID	Patron 通过加密的 Nostr DM 交付
BTCPay 凭据（btcpay_host、btcpay_api_key、btcpay_store_id）	Operator 通过 Secure Courier 交付

注意： THEBRAIN_API_KEY 不是环境变量。Patron 通过 Secure Courier（加密的 Nostr DM）交付其 TheBrain API 密钥和 brain ID。只有 Operator 的 nsec 配置为环境变量。

工具界面

该服务通过 tollbooth-dpyc 中的 register_standard_tools()，提供标准的 Tollbooth DPYC™ Operator 工具界面， 以及其领域工具。工具分为 DPYC 三方拓扑（Operator / Authority / Oracle）中的三条路径：

路径	工具	状态
热路径（本地账本）	check_balance、account_statement、account_statement_infographic、restore_credits、service_status	已实现 — 委托给 server.py
热路径（Secure Courier）	session_status、request_credential_channel、receive_credentials、forget_credentials	已实现 — 通过 Nostr 交付凭据，并通过 DM 发送凭据卡片
身份	request_npub_proof、receive_npub_proof、check_proof_status、held_identities	已实现 — 将 npub 验证为 OAuth 连接
委托（Authority）	purchase_credits、check_payment	已实现 — 通过 MCP-to-MCP 自动认证
委托（Oracle）	oracle_lookup_member、oracle_how_to_join、oracle_get_tax_rate、oracle_about、oracle_network_advisory	已实现 — 通过 OracleClient 使用 MCP-to-MCP

支付处理通过 Authority 自动认证（服务器到服务器 OAuth）。Secure Courier 通过 Nostr DM 交付加密凭据，并在首次接收时自动通过 DM 返回凭据卡片（ncred1...）。Oracle 社区工具直接路由至 DPYC™ Oracle，免费且无需身份验证。

架构

Tollbooth DPYC™ 生态系统是一个跨越三个代码库的三方协议：

代码库	角色
tollbooth-authority	机构 — 征税、Schnorr 签名、采购订单认证
tollbooth-dpyc	收费站 — Operator 侧的信用额度账本、BTCPay 客户端、工具门控
dpyc-oracle	礼宾服务 — 社区入门、税率、成员查询
thebrain-mcp（本代码库）	首座城市 — 由 Tollbooth DPYC™ 驱动的参考 MCP 服务

完整架构请参阅三方协议图。另可查看Operator 侧流程图。

项目结构

thebrain-mcp/
├── src/thebrain_mcp/        # Server source, BQL engine, Tollbooth
├── tests/                   # Test suite (465+ tests)
├── fastmcp.json             # Horizon deploy entrypoint (src/thebrain_mcp/server.py)
├── pyproject.toml           # Package metadata and dependencies
├── BRAINQUERY.md            # BQL grammar and reference
├── INSTALL.md / QUICKSTART.md  # Local install and setup
├── docs/diagrams/           # Architecture and protocol flow diagrams
├── LICENSE                  # Apache License 2.0
└── NOTICE                   # Attribution notice

先前技术与署名

本代码库中包含的方法、算法和实现可能代表 Lonnie VanZandt 的原创作品，首次发表于 2026 年 2 月 16 日。此公开披露依据美国专利法（35 U.S.C. 102）确立先前技术。

所有使用、复制或衍生作品均须遵守本代码库所含的 Apache License 2.0，并根据 NOTICE 文件正确注明原作者。

如何署名

如果您使用或基于此作品进行开发，请在文档或源代码中加入以下内容：

基于 Lonnie VanZandt 和 Claude.ai 的原创作品
首次发布：2026 年 2 月 16 日
来源：https://github.com/lonniev/thebrain-mcp
采用 Apache License 2.0 授权

欢迎访问这位技术爱好者为 Bitcoin 支持者和咖啡爱好者开设的虚拟咖啡馆：stablecoin.myshopify.com。

专利声明

作者保留对本文所述新颖方法和系统寻求专利保护的一切权利。公开披露本作品确立了 2026 年 2 月 16 日这一优先权日。根据《美国发明法案》，作者自首次公开披露之日起保留一年的宽限期，可在此期间提交专利申请。

致潜在申请人的说明： 本公开仓库及其完整 Git 历史记录可作为现有技术的证据。任何在本仓库发布日之后提交、涉及实质相似方法的专利申请，都可能依据 35 U.S.C. 102(a) 被宣告无效。

DPYC™ 生态系统

• tollbooth-dpyc — Python SDK（保险库、身份验证、定价、Lightning、Nostr 身份）
• dpyc-community — 治理注册表：成员资格、公告、威胁模型
• dpyc-oracle — 社区接待服务（免费入门指导 + 成员查询）
• tollbooth-authority — 认证骨干服务（Schnorr 签名证书）
• tollbooth-sample — 示例运营方（规范模板）
• tollbooth-pricing-studio — iOS 定价模型编辑器 / 运营方控制台
• cypher-mcp — 付费图查询答案：针对 Neo4j/AuraDB 的命名 Cypher 模板
• schwab-mcp — Charles Schwab 经纪业务数据
• thebrain-mcp — TheBrain 个人知识图谱
• excalibur-mcp — X/Twitter 发帖
• taxsort-mcp — 税务分类 + Cloudflare Pages 界面
• optionality-mcp — 期权分析（经纪业务数据运营方）
• tollbooth-oauth2-collector — OAuth2 回调处理程序（倡导者服务）
• tollbooth-shortlinks — URL 缩短工具
• goodearth-mcp — 小型特色作物农场的气候分析
• beesknees-mcp — The Bee's Knees 竞速游戏
• roastify-mcp — Roastify 咖啡目录和包装插画
• ChartRemotely-mcp — 通过语音或工具调用，在桌面图表上绘制证券
• tollbooth-web — DPYC™ 运营方前端共用的浏览器 SDK

延伸阅读

《闪电收费公路上的幻影收费亭》 — 讲述我们如何将 AI API 的变现过程本身变现，然后退居幕后。

商标

DPYC™、Tollbooth DPYC™ 和 Don't Pester Your Customer™ 是 Lonnie VanZandt 的商标。有关使用指南，请参阅 dpyc-community 仓库中的 TRADEMARKS.md。

许可证

Apache License 2.0 — 详情请参阅 LICENSE 和 NOTICE。

---

因为归根结底，收费亭从来都不是目的地。它始终只是旅程的起点。