企业官网建设流程全解析

gemini-notebook-mcp-cli源码架构剖析：CLI、Services、Core与MCP四层设计如何协作

【免费下载链接】gemini-notebook-mcp-cliProgrammatic access to Gemini Notebook - via command-line interface (CLI), Model Context Protocol (MCP) server, and AI agent skills.项目地址: https://gitcode.com/gh_mirrors/not/gemini-notebook-mcp-cli

gemini-notebook-mcp-cli 是一个开源项目，通过 CLI 命令行工具和 MCP 服务器提供对 Gemini Notebook（原 Google NotebookLM）的程序化访问：管理笔记本、添加资料、生成播客与幻灯片，并让 AI 助手直接操作你的研究笔记。本文逐层剖析它的源码架构，讲清 CLI、Services、Core、MCP 四层设计如何协作，帮助你快速读懂这份代码库。

🧭 先装再看：一个包，两个可执行入口

项目通过 PyPI 发布，单个包同时提供两个入口，定义在 pyproject.toml 中：

uv tool install notebooklm-mcp-cli # 或 pip install nlm # 命令行入口 → cli/main.py notebooklm-mcp # MCP 服务器入口 → mcp/server.py

• nlm：面向人类用户与脚本的完整命令行工具
• notebooklm-mcp：面向 AI 助手（Claude、Gemini、Cursor 等）的 MCP 服务器

理解这两个入口，是理解整个架构的钥匙。

🏗️ 四层架构全景

源码位于src/notebooklm_tools/，按职责清晰分成四层：

├── cli/ # 命令行层：参数解析、提示交互、结果渲染（薄壳） ├── mcp/ # MCP 服务器层：FastMCP 门面 + 按领域拆分的工具定义（薄壳） ├── services/ # 业务逻辑层：校验、轮询、错误处理，返回类型化结果 ├── core/ # 底层 API 客户端：HTTP/RPC 通信、认证、重试（无业务逻辑） └── utils/ # 配置路径、浏览器与 CDP Cookie 提取等公共设施

项目自带的开发指南 CLAUDE.md 明确了两条分层规则：

1. cli/与mcp/必须是"薄壳"，只处理用户体验（提示、加载动画、JSON 响应），业务一律委托给services/
2. cli/与mcp/禁止直接导入core/，所有调用必须经过services/

这正是"四层协作"的核心：两个入口共享一套业务逻辑，底层通信细节对上层完全透明。

🔩 Core 层：封装 Gemini Notebook 内部 API

Core 层是唯一的"网络世界"接触点，关键文件有两个：

• core/base.py：BaseClient基类承载全部 HTTP/RPC 基础设施——基于httpx向内部batchexecute接口发请求，内置指数退避重试（自动处理 429 与RESOURCE_EXHAUSTED限流），并支持通过环境变量热修补 Google 定期轮换的 RPC 方法 ID，无需发新版本
• core/client.py：NotebookLMClient通过多继承聚合 12 个领域 Mixin（notebooks、sources、studio、research、conversation、sharing、notes、labels、collections、exports、downloads 等），把每个领域的 API 调用组织到对应模块

此外 core/auth.py 提供基于 profile 的认证管理，Cookie 提取则复用 utils/cdp.py 的 Chrome DevTools 协议通道。

⚙️ Services 层：CLI 与 MCP 共享的业务大脑

services/目录（如 services/notebooks.py）包含所有业务逻辑，有两个显著特征：

• 类型化契约：每个模块用TypedDict声明返回结构（如NotebookInfo、NotebookListResult），CLI 和 MCP 拿到的是同一份可信数据结构
• 统一错误模型：只抛出ServiceError/ValidationError等语义化异常，绝不让裸异常穿透到入口层

这意味着：给"列出笔记本"增加排序逻辑时，只需改一处，CLI 与 MCP 的 40 多个工具自动受益。

🚪 CLI 与 MCP：两个薄壳如何接电

以 mcp/tools/notebooks.py 中的notebook_list为例，工具函数只做三件事：经get_client()获取客户端、调用notebooks_service.list_notebooks()、捕获ServiceError转成error_result。没有任何业务代码——这就是"薄壳"的具象体现。

🔁 一次请求如何穿越四层

以nlm notebook list为例，请求与响应的完整路径：

1. CLI 层：cli/commands/notebook.py 解析参数，构造客户端
2. Services 层：notebooks.list_notebooks(client)完成参数校验与结果归一化
3. Core 层：BaseClient携带认证信息发送batchexecuteRPC，自动重试限流错误
4. 反向返回：Core 解析原始响应 → Services 返回类型化 dict → CLI 渲染成表格（若走 MCP，则序列化为 JSON 交给 AI 助手）

同一条调用链，CLI 得到人类可读的表格，MCP 得到 AI 可理解的 JSON——差异只在最外层。

📚 新手源码阅读路线

建议按依赖方向从外到内阅读：

1. CLAUDE.md —— 5 分钟掌握架构、分层规则与认证机制
2. services/notebooks.py —— 最完整的业务模块范例
3. core/client.py —— 看 Mixin 如何拼装领域能力
4. mcp/tools/ —— 体会薄壳模式

配套文档可延伸阅读：docs/GETTING_STARTED.md（上手）、docs/CLI_GUIDE.md（命令参考）、docs/MCP_GUIDE.md（全部 MCP 工具）、docs/API_REFERENCE.md（内部 API 细节，适合调试时查阅）。

分层设计的真正收益：新增功能时，贡献者只需按固定套路改三处——Core 加底层方法、Services 加业务逻辑、两个薄壳各加一个包装函数（见 CLAUDE.md 中的 Contributing 章节）。这种可预期的扩展方式，正是四层架构最优雅的地方。

【免费下载链接】gemini-notebook-mcp-cliProgrammatic access to Gemini Notebook - via command-line interface (CLI), Model Context Protocol (MCP) server, and AI agent skills.项目地址: https://gitcode.com/gh_mirrors/not/gemini-notebook-mcp-cli