NotionBae

NotionBae

一个用于集成 Notion.com 的模型上下文协议（MCP）服务，使用 .NET C# 构建，并基于 ModelContextProtocol。NotionBae 利用 Notion API 实现 AI 助手与 Notion 工作区之间的无缝交互。

概述

NotionBae 通过模型上下文协议框架，在大语言模型与 Notion.com 之间搭建桥梁。借助它，AI 助手可以无缝、结构化地与 Notion 数据库、页面和内容交互。

功能

• 集成 Notion API
• 符合 MCP 规范的服务实现
• 针对 Notion 内容的结构化数据处理
• Notion 工作区的身份验证和安全访问

技术

• Notion SDK for .NET：一款功能全面的 Notion API .NET 客户端。我们以此 SDK 为基础，同时实现了自己的 NotionBaeRestClient，以解决若干局限：
  • 原始 SDK 的 REST 客户端实现耦合紧密，且未遵循 .NET 依赖注入的最佳实践
  • 我们的自定义客户端正确使用了 HttpClientFactory，这对正确处理连接池和生命周期管理至关重要
  • 重新设计后，可实现更好的可测试性，并支持测试套件中的多态行为
  • 此方案提供了真正的依赖注入，而非原始 SDK 中的伪 DI 实现
• Markdig：一款快速、强大且可扩展的 .NET Markdown 处理器，用于在 Notion 的区块结构与 Markdown 之间进行转换

为什么使用 Markdown？

NotionBae 将 Markdown 作为 Notion 复杂区块结构与 AI Agent 之间的中间格式，原因如下：

1. 节省 Token：Notion API 返回的数据采用冗长的区块结构，包含许多属性。转换为 Markdown 后，我们可以大幅减少 AI 模型处理的 Token 数量，从而有望提升性能并降低成本。

2. 可读性：Markdown 天生易于阅读，让人类和 AI Agent 都能更轻松地访问内容。

3. 简洁性：与直接处理 Notion 的嵌套区块结构相比，使用 Markdown 简单得多，尤其是在生成内容时。

目前尚无全面数据比较原始 Notion API 响应与 Markdown 的 Token 用量，但传闻证据表明，将 Markdown 用作中间格式可以显著提升效率。

可用工具

NotionBae 提供以下工具，用于与 Notion 交互：

工具名称	描述	参数
nb_search	搜索 Notion 页面并返回其标题和公开 URL	query：String - 用于查找匹配页面的搜索查询
nb_create_page	使用给定的标题、描述和内容创建新的 Notion 页面	parentId：String - 父页面的 ID title：String - 新页面的标题 description：String - 页面描述 content：String - 页面的 Markdown 内容
nb_get_page_content	以 Markdown 格式获取 Notion 页面及其元数据和完整内容	pageId：String - 要获取的页面 ID
nb_get_block	从 Notion 获取指定区块及其子区块	blockId：String - 要获取的区块 ID
nb_search_page	支持筛选功能的高级页面搜索	query：String - 搜索查询 filter：Object - 可选的筛选参数
nb_update_page	更新现有的 Notion 页面	pageId：String - 要更新的页面 ID content：String - 页面的新 Markdown 内容

快速开始

1. Notion 账户设置

1. 创建 Notion 账户：如果你还没有账户，请前往 notion.so 注册一个 Notion 账户。

2. 创建 Notion 集成：

   • 前往 Notion Developers
   • 点击“New integration”
   • 为集成命名（例如，“NotionBae”）
   • 选择要使用此集成的工作区
   • 设置适当的权限（至少选择“Read content”和“Update content”）
   • 点击“Submit”创建集成

3. 获取 API 密钥：

   • 创建集成后，你会看到“Internal Integration Secret”（API 密钥）
   • 复制此密钥，配置 NotionBae 时会用到

4. 与集成共享页面：

   • 打开要通过 NotionBae 访问的 Notion 页面
   • 点击右上角的“Share”
   • 在“Add people, groups, or integrations”字段中搜索集成名称
   • 选择集成，授予其访问该页面的权限

2. 克隆并设置 NotionBae

1. 克隆仓库：

   git clone https://github.com/mrcunninghamz/NotionBae.git /path/to/your/directory
   cd /path/to/your/directory
   

   将 /path/to/your/directory 替换为要克隆仓库的实际目录路径（例如，~/projects/NotionBae 或 /Users/username/Documents/Projects/NotionBae）。

2. 构建项目：

   dotnet build
   

3. 设置环境变量：

   NotionBae 服务需要以下环境变量：

   • Notion:AuthToken：用于向 Notion API 进行身份验证的 Notion API 密钥

   你可以在 Notion 工作区设置中创建集成，以获取 Notion API 密钥。请访问 Notion API documentation，了解创建集成并获取 API 密钥的更多信息。 将 appsettings.template.json 复制为 appsettings.json，并将 Notion:AuthToken 的值填写为你的 Notion API 密钥。

4. 运行项目：

   dotnet run --project PATH_TO_NOTIONBAE_PROJECT/src/NotionBae.csproj
   

   将 PATH_TO_NOTIONBAE_PROJECT 替换为 NotionBae 项目文件夹的路径（即包含 NotionBae.csproj 文件的文件夹）。

3. MCP 服务配置

要在 VS Code 中将 NotionBae 用作 MCP 服务，请将以下配置添加到 VS Code 的 settings.json 文件中：

"mcp": {
  "servers": {
      "NotionBae": {
        "url": "http://localhost:5001/mcp"
      }
  }
}

相关项目

本项目属于“Bae”工具集：

• TestBae - 一个 .NET 测试实用程序库，可通过固定装置、模拟对象和常见测试模式简化测试设置，从而让测试套件更高效、更易维护。
• AzBae - Azure DevOps 工具，提供命令行和 GUI 界面，可简化 Azure 资源管理、部署和 DevOps 工作流。

许可证