notebooklm-mcp源码架构深剖MCP ServerPatchright浏览器自动化完整拆解【免费下载链接】notebooklm-mcpMCP server for NotebookLM - Let your AI agents (Claude Code, Codex) research documentation directly with grounded, citation-backed answers from Gemini. Persistent auth, library management, cross-client sharing. Zero hallucinations, just your knowledge base.项目地址: https://gitcode.com/gh_mirrors/no/notebooklm-mcpnotebooklm-mcp 是一个面向 Google NotebookLM 的 MCP ServerModel Context Protocol 服务器它让 Claude Code、Codex 等 AI 编程智能体直接基于你的 NotebookLM 知识库进行调研返回带引用、零幻觉的回答。项目用 TypeScript 编写核心链路是「MCP 协议层 → 会话管理层 → Patchright 隐身浏览器层 → NotebookLM 网页」。本文带你全景拆解这套源码架构从入口服务、配置系统到持久化认证、共享浏览器上下文和拟人化反检测设计看看它为什么能做到像真人一样地操作浏览器。一、项目全景一句话讲清分层架构整个项目只有 24 个 TypeScript 源文件却完成了AI 智能体 → 浏览器自动化 → Google 服务的完整闭环。分层如下层级目录职责MCP 服务层src/index.ts协议接入、工具路由、优雅退出工具定义层src/tools/14 个 MCP 工具的 Schema 与业务实现会话管理层src/session/多会话调度、共享浏览器上下文认证层src/auth/auth-manager.ts登录、Cookie 持久化与过期校验知识库层src/library/notebook-library.tsNotebook 增删改查与元数据管理隐身工具层src/utils/stealth-utils.ts拟人打字、鼠标轨迹、随机延迟配置层src/config.ts三级配置优先级 跨平台路径入口文件 src/index.ts 中的NotebookLMMCPServer类是总装配车间它构造 MCP SDK 的Server实例注入AuthManager、SessionManager、NotebookLibrary三大管理器再挂载工具处理器最终通过Stdio 传输与客户端通信src/index.ts。AI 客户端如 Claude Code通过标准输入输出管道发来list_tools和call_tool请求服务器按工具名switch分发到对应 handlersrc/index.ts。二、配置系统免配置文件的设计很多同类项目要求用户手动写 config.json而 notebooklm-mcp 在 src/config.ts 中声明了一个更轻的方案硬编码默认值 → 环境变量 → 工具参数三级优先级开箱即用。默认值1024×768 视口、10 个并发会话、900 秒会话超时、隐身模式默认开启、打字速度 160~240 WPM环境变量如HEADLESS、MAX_SESSIONS、NOTEBOOK_URL通过applyEnvOverrides()覆盖src/config.ts;工具参数运行时由 AI 传入的browser_options经applyBrowserOptions()合并成临时副本用后即还原不污染全局配置src/tools/handlers.ts。数据目录由env-paths库自动按平台生成src/config.tsLinux~/.local/share/notebooklm-mcp/macOS~/Library/Application Support/notebooklm-mcp/Windows%APPDATA%\notebooklm-mcp\里面存放认证状态browser_state/、持久化 Chrome 配置chrome_profile/和多实例配置chrome_profile_instances/。三、工具层AI 智能体的 14 个遥控器按钮工具定义按领域拆成四个文件全部聚合在 src/tools/definitions.ts文件代表工具作用definitions/ask-question.tsask_question向 NotebookLM 提问核心工具definitions/notebook-management.tsadd_notebook、search_notebooks管理知识库条目definitions/session-management.tslist_sessions、reset_session会话生命周期控制definitions/system.tsget_health、setup_auth系统健康检查与认证设置值得注意的一个产品级细节src/tools/handlers.ts 在每次回答末尾自动追加一段追问提醒催促 AI 智能体思考是否还有其他需要追问的问题。这一招显著提升了多轮调研的深度属于提示词工程写进代码的典型范例。另一个亮点是工具配置档位profileSettingsManager可按精简/完整等档位过滤工具集合避免给 AI 塞太多工具导致选择困难src/utils/settings-manager.ts。四、会话层一对多的浏览器编排会话层是理解本项目设计精髓的关键由三个类协作1. SessionManager —— 调度中心src/session/session-manager.ts用MapsessionId, BrowserSession管理并行会话会话 ID 是 4 字节随机 hexsrc/session/session-manager.ts内置定时器周期性清理超时会话超时时间默认 15 分钟达到maxSessions上限时自动挤走最老的会话保证服务不中断。2. BrowserSession —— 单个标签页的生命周期src/session/browser-session.tsinit()流程非常讲究创建页签 → 导航到 Notebook → 等待 2~3 秒稳定期 → 校验 Cookie →恢复 sessionStorage→ 等待textarea.query-box-input等 NotebookLM 专属选择器就绪。提问时以拟人速度逐字输入再由 src/utils/page-utils.ts 中的waitForLatestAnswer检测流式回答完成并抓取全部引用来源。3. SharedContextManager —— 全局唯一指纹src/session/shared-context-manager.ts这是整个架构中最反直觉、也最精妙的设计所有会话共享同一个持久化浏览器上下文。源码注释解释得很直白——Google 会跟踪 Canvas、WebGL、Audio 等浏览器指纹多个上下文 多个指纹 可疑而一个持久化user_data_dir让 Chrome 在每次重启后加载同一份配置Google 看到的是从第一天起就是同一个浏览器。它还处理了多实例并发的边角情况当基础 profile 被另一进程锁住SingletonLock时auto策略会自动回退到独立实例目录并按 TTL/数量上限自动修剪残留 profilesrc/session/shared-context-manager.ts。五、认证层让登录一次搞定跨重启存活AuthManager 管理完整的认证闭环状态持久化把 cookies localStorage 存到browser_state/state.jsonsessionStorage 单独存到session.jsonsrc/auth/auth-manager.ts关键 Cookie 白名单SID、HSID、APISID、SAPISID、__Secure-3PSID等 Google 会话凭证用于判断登录态是否有效src/auth/auth-manager.ts过期双保险文件超过 24 小时即视为过期 逐一校验 Cookie 的expires时间戳启动即加载SharedContextManager创建上下文时直接把storageState传进launchPersistentContext绕开了 Playwright 中 session cookie 不持久化的坑src/session/shared-context-manager.ts自动重登会话过期时可凭环境变量中的邮箱密码自动登录也支持setup_auth工具弹浏览器人工登录。六、隐身层Patchright 拟人行为模拟项目选用PatchrightPlaywright 的隐身增强分支而非原版并在启动参数中加入--disable-blink-featuresAutomationControlled抹掉自动化特征src/session/shared-context-manager.ts。更细腻的是 src/utils/stealth-utils.ts 里的一套行为拟真工具️高斯分布延迟用 Box-Muller 变换生成正态分布随机等待均值取区间 60% 处比均匀分布更像人的反应节奏⌨️拟人打字按配置 WPM 逐字输入带 2% 概率的手滑打错再修正标点符号后停顿更长️贝塞尔鼠标轨迹带抖动的曲线移动替代机械直线平滑滚动与阅读停顿模拟人类扫读网页的节奏。这些细节共同构成了零幻觉、反检测的双保险答案来自真实网页抓取零幻觉操作行为像真人反检测。七、知识库层与配套工具NotebookLibrary 把多个 Notebook 当作可检索的书库管理以library.json持久化条目URL、主题标签、用途、使用次数AI 智能体可自主决定这次任务该查哪本无需人工指定src/library/notebook-library.ts。类型定义见 src/library/types.ts。配套工具链同样完整src/utils/cleanup-manager.ts清理浏览器残留数据src/utils/cli-handler.tsnotebooklm-mcp config子命令命令行查改配置src/utils/logger.ts分级日志启动横幅与运行轨迹一目了然src/resources/resource-handlers.ts额外暴露 MCP Resources/Prompts 能力src/errors.ts自定义RateLimitError等错误类型让限流可被优雅处理。八、架构总结三个值得抄作业的设计决策单上下文多会话用一个浏览器、多个标签页模拟真实用户指纹天然一致同时用持久化 profile 让指纹跨重启存活配置三级优先级默认值 → 环境变量 → 运行时参数零配置文件起步进阶用户可随时覆盖行为级隐身不追求绕过检测的对抗而是把每个操作延迟、打字、鼠标都调校到人类行为分布内。如果你希望让 AI 智能体基于私有文档、产品手册或研究语料进行带引用的调研这套MCP Server Patchright的架构非常值得参考。更多环境变量与工具参数说明可查阅项目内置文档docs/configuration.md、docs/tools.md、docs/usage-guide.md 与 docs/troubleshooting.md。【免费下载链接】notebooklm-mcpMCP server for NotebookLM - Let your AI agents (Claude Code, Codex) research documentation directly with grounded, citation-backed answers from Gemini. Persistent auth, library management, cross-client sharing. Zero hallucinations, just your knowledge base.项目地址: https://gitcode.com/gh_mirrors/no/notebooklm-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考