# https://github.com/n24q02m/better-notion-mcp 项目说明书
生成时间：2026-05-31 02:03:55 UTC
## 目录
- [项目介绍](#page-introduction)
- [版本更新日志](#page-changelog)
- [系统架构](#page-architecture)
- [传输模式详解](#page-transport-modes)
- [复合工具详解](#page-composite-tools)
- [安全机制](#page-security)
- [配置指南](#page-configuration)
- [部署指南](#page-deployment)
- [开发指南](#page-development-guide)
- [源代码结构](#page-source-structure)
## 项目介绍
### 相关页面
相关主题：[系统架构](#page-architecture), [复合工具详解](#page-composite-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/n24q02m/better-notion-mcp/blob/main/README.md)
- [server.json](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
- [CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
- [src/tools/registry.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/registry.ts)
- [src/tools/composite/pages.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/pages.ts)
- [src/tools/helpers/markdown.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.ts)
- [src/tools/helpers/richtext.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/richtext.ts)
- [AGENTS.md](https://github.com/n24q02m/better-notion-mcp/blob/main/AGENTS.md)
# 项目介绍
better-notion-mcp 是一个面向 AI Agent 的 TypeScript MCP（Model Context Protocol）服务器，为 Notion API 提供 Markdown 优先的标准化访问接口。
## 项目概述
### 核心定位
该项目是 MCP 协议在 Notion 生态中的具体实现，其设计理念围绕三个核心原则：
1. **Markdown 优先** - 所有内容操作以 Markdown 格式作为主要输入输出，降低 AI Agent 的理解成本
2. **复合工具聚合** - 将 Notion 的原子 API 操作封装为 10 个复合工具（mega-tools），每个工具支持多个动作
3. **双模式传输** - 支持 stdio 和 HTTP 两种传输协议，适配不同的部署场景
资料来源：[README.md](https://github.com/n24q02m/better-notion-mcp/blob/main/README.md)
### 版本与发布
当前稳定版本为 **v2.34.3**（2026-05-29），通过 semver 语义化版本管理，采用 beta 版本进行迭代测试。社区维护的依赖更新通过 Renovate 自动化机器人管理（参见 Dependency Dashboard Issue #138）。
资料来源：[server.json:5](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
### MCP 质量评级
该服务器在 Agent Tool Intel 自动化质量分析中获得 **Grade A** 评级，表明其符合 MCP 协议最佳实践，具有良好的工具描述、输入模式定义和安全性保障。
## 技术架构
### 项目结构
```
better-notion-mcp/
├── src/
│ ├── init-server.ts # 服务器入口，环境变量验证
│ ├── credential-state.ts # 凭证状态机 + stdio 回退机制
│ ├── relay-schema.ts # 中继表单模式（OAuth 令牌字段）
│ ├── tools/
│ │ ├── registry.ts # 工具注册与路由
│ │ ├── composite/ # 领域化复合工具实现
│ │ │ ├── pages.ts # 页面 CRUD 工具
│ │ │ ├── databases.ts # 数据库工具
│ │ │ ├── blocks.ts # 块级操作工具
│ │ │ ├── users.ts # 用户查询工具
│ │ │ ├── workspace.ts # 工作区信息工具
│ │ │ ├── comments.ts # 评论管理工具
│ │ │ ├── content.ts # 内容格式转换工具
│ │ │ └── file_uploads.ts # 文件上传工具
│ │ └── helpers/
│ │ ├── errors.ts # 统一错误处理
│ │ ├── markdown.ts # Markdown ↔ Notion Blocks 转换
│ │ ├── richtext.ts # 富文本构造工具
│ │ ├── pagination.ts # 分页与深度子内容处理
│ │ ├── properties.ts # 属性类型转换
│ │ ├── covers.ts # 封面格式化
│ │ ├── icons.ts # 图标格式化
│ │ └── security.ts # URL 安全校验
│ ├── auth/ # OAuth 2.1 + PKCE + DCR + Session
│ ├── transports/ # stdio + HTTP 传输层
│ └── docs/ # Markdown 文档（MCP 资源）
├── scripts/ # 构建脚本
├── tests/ # 测试文件（与源码共置）
└── skills/ # AI Agent 使用指南
```
资料来源：[CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
### 复合工具体系
项目定义了 10 个复合工具，覆盖 Notion API 的主要功能领域：
| 工具名称 | 功能范围 | 主要动作 |
|---------|---------|---------|
| `pages` | 单页和数据库行的 CRUD | create, get, get_property, update, move, archive, restore, duplicate |
| `databases` | 数据库操作 | create, get, query, update, schema, property |
| `blocks` | 块级内容操作 | list, get, append, update, delete |
| `users` | 用户查询 | me, get, list |
| `workspace` | 工作区信息与搜索 | info, search |
| `comments` | 评论管理 | list, get, create |
| `content_convert` | Markdown 与 Blocks 互转 | markdown-to-blocks, blocks-to-markdown |
| `file_uploads` | 文件上传（支持分片） | create, send, complete, retrieve, list |
| `setup` | 初始化配置引导 | - |
| `help` | 帮助信息 | - |
每个工具通过 `action` 参数区分具体操作，支持链式参数依赖（某些参数在特定 action 下变为可选）。
资料来源：[src/tools/registry.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/registry.ts)
### 凭证状态机
凭证管理采用三状态有限状态机：
```mermaid
graph TD
A[awaiting_setup] -->|用户配置| B[setup_in_progress]
B -->|配置完成| C[configured]
C -->|配置失效| A
B -->|配置失败| A
```
状态转移逻辑位于 `credential-state.ts`，stdio 模式下支持在 127.0.0.1 随机端口启动本地服务器进行 OAuth 流转。
资料来源：[CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
### 传输层架构
```mermaid
graph LR
A[AI Agent] -->|stdio| B[MCP SDK Direct]
A -->|HTTP| C[MCP SDK HTTP Client]
B --> D[Server Implementation]
C --> D
D --> E[Notion API]
```
当前默认使用 stdio 模式（MCP SDK direct routing），该架构简化了进程间通信复杂度。
资料来源：[CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
## 核心模块详解
### Markdown 转换引擎
`src/tools/helpers/markdown.ts` 实现了 Markdown 与 Notion Block JSON 的双向转换：
**支持的 Markdown 语法：**
| 类别 | 语法元素 |
|-----|---------|
| 结构 | 标题 (h1-h6)、段落、列表、有序列表、待办事项 |
| 格式 | 加粗、斜体、删除线、内联代码 |
| 引用 | 块引用、分割线 |
| 高级 | 代码块（带语言标识）、表格、折叠内容 (details) |
| 特殊 | 标注块 (> [!NOTE])、多列布局 (:::columns) |
| 媒体 | 图片、书签、内嵌、公式 ($$) |
| 导航 | [toc] 目录、[breadcrumb] 面包屑 |
**RichText 注解支持：**
- `bold` / `italic` / `strikethrough` / `underline` / `code`
- `color`（支持 default、gray、brown、orange、yellow、green、blue、purple、pink、red）
资料来源：[src/tools/helpers/markdown.ts:1-20](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.ts)
### 富文本工具库
`src/tools/helpers/richtext.ts` 提供类型化的富文本构造函数：
```typescript
text(content: string) // 普通文本
bold(content: string) // 加粗
italic(content: string) // 斜体
strikethrough(content: string) // 删除线
underline(content: string) // 下划线
code(content: string) // 内联代码
```
每个函数返回标准化的 `RichTextItem` 对象，确保与 Notion API 的兼容性。
资料来源：[src/tools/helpers/richtext.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/richtext.ts)
### 页面工具 (pages)
页面工具是使用频率最高的工具，支持完整的页面生命周期管理：
```typescript
interface GetPageResult {
page_id: string
url: string
created_time: string
last_edited_time: string
archived: boolean
icon: any
cover: any
properties: Record
content: string // Markdown 格式
block_count: number
}
```
**属性格式约定：**
- 简单值自动转换：字符串 → title/rich_text，数字 → number，布尔 → checkbox
- 数组类型使用 `multi_select`
- 日期使用 ISO 格式（如 `"2025-06-01"`）
资料来源：[src/tools/composite/pages.ts:29-40](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/pages.ts)
## 部署与配置
### 环境变量
| 变量名 | 必填 | 类型 | 说明 |
|-------|-----|-----|-----|
| `NOTION_TOKEN` | 是 | Secret | Notion 集成令牌，在 https://www.notion.so/my-integrations 创建 |
### 分发方式
项目支持两种分发渠道：
1. **npm** - `@n24q02m/better-notion-mcp`，通过 `npx` 运行
2. **OCI (Docker)** - `docker.io/n24q02m/better-notion-mcp:latest`
资料来源：[server.json:10-35](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
### 开发环境
使用 `mise` 管理的运行时版本约束：
| 运行时 | 版本范围 |
|-------|---------|
| Python | 3.13.x |
| Node.js | 24.x |
| Java | 21.x LTS |
资料来源：[renovate.json](https://github.com/n24q02m/better-notion-mcp/blob/main/renovate.json)
## 安全性特性
### URL 安全校验
内置 `isSafeUrl()` 函数防护以下危险协议：
- `javascript:` 伪协议
- 其他非 HTTP(S) 的 URL schemes
不安全链接会被解析器静默降级为纯文本或段落块，防止 XSS 攻击。
资料来源：[src/tools/helpers/markdown.security.test.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.security.test.ts)
### 头部信息脱敏
响应中的敏感 HTTP 头部会被不区分大小写地过滤，防止凭证泄露。
资料来源：[社区 Issue #713](https://github.com/n24q02m/better-notion-mcp/pull/713)
## 开发指南
### 常用命令
```bash
bun install # 安装依赖
bun run build # TypeScript 编译 + esbuild 打包
bun run check # Biome 检查 + tsc 类型检查（CI 命令）
bun run check:fix # 自动修复格式问题
bun test # 运行测试
```
### 提交规范
采用 Conventional Commits 格式：`type(scope): message`，通过 git hooks 强制执行。
### 预提交检查
1. `biome check --write` - 格式化和 lint
2. `tsc --noEmit` - 类型检查
3. `bun test` - 单元测试
资料来源：[AGENTS.md](https://github.com/n24q02m/better-notion-mcp/blob/main/AGENTS.md)
## 与同类项目的关系
该项目是 n24q02m 组织下 MCP 服务器生态的一部分，关联项目包括：
| 项目 | 定位 |
|-----|-----|
| better-email-mcp | IMAP/SMTP 邮件服务器 |
| better-godot-mcp | Godot 游戏引擎集成 |
| better-telegram-mcp | Telegram Bot 集成 |
| imagine-mcp | 图像视频理解与生成 |
所有项目共享统一的文档门户：mcp.n24q02m.com
资料来源：[README.md](https://github.com/n24q02m/better-notion-mcp/blob/main/README.md)
## 依赖管理
项目核心依赖 `@n24q02m/mcp-core`（内部 MCP 核心库），通过 Renovate 进行自动化版本管理。当前跟踪的版本包括 v1.15.0、v1.17.0、v1.17.1 等。
依赖更新会通过 Issue 自动通知维护者，执行 `bun install` 即可完成锁文件更新。
资料来源：[社区 Issue #726](https://github.com/n24q02m/better-notion-mcp/issues/726), [#769](https://github.com/n24q02m/better-notion-mcp/issues/769)
---
## 版本更新日志
### 相关页面
相关主题：[项目介绍](#page-introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [CHANGELOG.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CHANGELOG.md)
- [package.json](https://github.com/n24q02m/better-notion-mcp/blob/main/package.json)
- [renovate.json](https://github.com/n24q02m/better-notion-mcp/blob/main/renovate.json)
- [server.json](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
- [AGENTS.md](https://github.com/n24q02m/better-notion-mcp/blob/main/AGENTS.md)
# 版本更新日志
## 概述
版本更新日志（CHANGELOG）是 better-notion-mcp 项目的核心文档，记录了每个发布版本的所有变更内容。该项目采用语义化版本号（SemVer）和 beta 版本并行发布的策略，确保用户能够了解稳定版的最新变化，同时开发者也能获取最新的测试功能。
当前最新稳定版本为 **v2.34.3**，发布于 2026-05-29。资料来源：[server.json:3]()
## 版本号规范
### 语义化版本结构
better-notion-mcp 采用标准的语义化版本格式：
```
主版本号.次版本号.修订号[-预发布标签]
```
| 组成部分 | 示例 | 说明 |
|---------|------|------|
| 主版本号 | 2 | 不兼容的 API 变更 |
| 次版本号 | 34 | 向后兼容的新功能 |
| 修订号 | 3 | 向后兼容的问题修复 |
| 预发布标签 | beta.1 | 预发布版本标识 |
资料来源：[server.json:5]()
### 预发布版本策略
项目采用 beta 版本迭代模式：
```mermaid
graph LR
A[v2.31.0-beta.2] --> B[v2.31.0-beta.3]
B --> C[v2.31.0-beta.5]
C --> D[v2.31.0-beta.6]
D --> E[v2.31.0]
E --> F[v2.32.0-beta.1]
F --> G[...最终稳定版]
```
| 预发布阶段 | 描述 | 示例 |
|-----------|------|------|
| beta.N | 功能测试阶段，可能包含破坏性变更 | v2.31.0-beta.6 |
| stable | 稳定发布版，推荐生产环境使用 | v2.31.0, v2.34.3 |
## 更新日志结构
### 发布条目格式
每个发布版本包含以下标准字段：
| 字段 | 描述 |
|------|------|
| 版本号 | 发布版本的完整标识 |
| 发布日期 | ISO 8601 格式的发布日期 |
| Bug 修复 | 问题修复列表 |
| 新功能 | 功能更新列表 |
| 维护 | 依赖更新、配置变更 |
### 版本链接
每个发布版本包含指向详细变更的链接：
```
**详细变更**: [v2.31.0-beta.6...v2.31.0](https://github.com/n24q02m/better-notion-mcp/compare/v2.31.0-beta.6...v2.31.0)
```
## 更新工作流
### 依赖更新流程
项目使用 Renovate 进行自动化依赖管理：
```mermaid
graph TD
A[依赖检测] --> B[创建更新 Issue]
B --> C{是否为核心依赖}
C -->|mcp-core| D[优先级提升]
C -->|其他依赖| E[标准流程]
D --> F[生成 PR]
E --> F
F --> G[代码审查]
G --> H[自动合并]
H --> I[锁定文件更新]
```
### 依赖版本策略
项目维护严格的依赖版本控制策略，资料来源：[renovate.json:1-50]()
| 依赖类型 | 版本策略 |
|---------|---------|
| mcp-core | 跟踪最新稳定版，Issue 自动提醒 |
| Python | 固定 3.13.x |
| Node.js | 固定 24.x |
| Java | 固定 21.x LTS |
| GitHub Actions | 固定 SHA 提交 |
### mcp-core 更新流程
mcp-core 是项目的核心依赖，其更新流程如下：
1. 在 GitHub Releases 发布新版本（如 v1.17.1）
2. 自动生成更新 Issue（如 #769）
3. 手动更新 `package.json` 中的版本号
4. 执行 `bun install` 更新锁文件
5. 生成提交并发布新版本
## 近期版本历史
### v2.34 系列
| 版本 | 日期 | 主要变更 |
|------|------|---------|
| v2.34.3 | 2026-05-29 | Pin mcp-core 1.17.1 (BearerMCPApp resource_metadata #260) |
| v2.33.1-beta.1 | 2026-05-24 | Redact headers case-insensitively, optimize property extraction |
| v2.33.0-beta.1 | 2026-05-08 | Add edge case test for extractPageProperties |
### v2.31 系列
| 版本 | 日期 | 主要变更 |
|------|------|---------|
| v2.31.0 | 2026-05-04 | Bump mcp-core to 1.13.0 (STABLE) |
| v2.31.0-beta.6 | 2026-05-03 | Bump mcp-core to 1.13.0-beta.9 for /login form shell refactor |
| v2.31.0-beta.3 | 2026-05-02 | Setup docs + README reflect stdio-pure architecture |
| v2.31.0-beta.2 | 2026-04-30 | Route stdio mode to MCP SDK direct + multi-target |
### 架构演进
v2.31 系列标志着重要的架构变更：
- **stdio-pure 架构**：移除了复杂的网络依赖，采用纯 stdio 传输模式
- **MCP SDK 集成**：直接使用 MCP SDK 进行路由和传输
- **多目标支持**：支持同时连接多个 Notion 工作区
资料来源：[AGENTS.md:1-30]()
## 提交规范
项目使用 Conventional Commits 规范，确保提交历史清晰可追溯：
| 类型 | 作用域 | 说明 |
|------|-------|------|
| fix | * | 修复问题 |
| feat | * | 新增功能 |
| docs | * | 文档更新 |
| chore | * | 维护任务 |
| refactor | * | 代码重构 |
| test | * | 测试相关 |
示例：`fix(pages): resolve property extraction edge case`
### 预提交检查
每次提交前必须通过以下检查：
1. `biome check --write` - 代码格式化和 lint
2. `tsc --noEmit` - TypeScript 类型检查
3. `bun run test` - 运行测试套件
资料来源：[AGENTS.md:35-45]()
## 社区参与
### 版本评级
better-notion-mcp 在 Agent Tool Intel 评级中获得 **Grade A**，表明项目质量达到高标准。资料来源：[#772](https://github.com/n24q02m/better-notion-mcp/issues/772)
### 依赖仪表板
项目维护依赖更新仪表板，追踪所有依赖的健康状态：资料来源：[#138](https://github.com/n24q02m/better-notion-mcp/issues/138)
## 相关资源
| 资源 | 链接 |
|------|------|
| 官方文档 | https://mcp.n24q02m.com |
| GitHub Releases | https://github.com/n24q02m/better-notion-mcp/releases |
| 变更对比 | https://github.com/n24q02m/better-notion-mcp/compare/ |
| 依赖仪表板 | https://github.com/n24q02m/better-notion-mcp/issues/138 |
---
## 系统架构
### 相关页面
相关主题：[传输模式详解](#page-transport-modes), [安全机制](#page-security)
相关源码文件
以下源码文件用于生成本页说明：
- [src/init-server.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/init-server.ts)
- [src/credential-state.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/credential-state.ts)
- [src/tools/registry.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/registry.ts)
- [src/tools/helpers/errors.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/errors.ts)
- [src/tools/composite/pages.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/pages.ts)
- [src/tools/helpers/markdown.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.ts)
- [src/tools/helpers/richtext.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/richtext.ts)
- [AGENTS.md](https://github.com/n24q02m/better-notion-mcp/blob/main/AGENTS.md)
- [server.json](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
# 系统架构
## 概述
better-notion-mcp 是一个 TypeScript 编写的 Markdown 优先的 MCP (Model Context Protocol) 服务器，用于为 AI 代理提供 Notion API 的完整访问能力。该项目采用复合工具 (composite tools) 设计模式，将多个相关操作整合为单一工具接口，显著降低了 AI 代理与 Notion API 交互的复杂性。
当前版本：v2.34.3，支持双模式运行（stdio 和 http），提供 10 个复合工具和 39+ 操作动作。资料来源：[server.json:3]()
## 核心架构设计
### 架构分层
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Protocol Layer │
│ (mcp-core 统一抽象) │
├─────────────────────────────────────────────────────────────┤
│ Transport Layer │
│ stdio Transport │ http Transport │
├─────────────────────────────────────────────────────────────┤
│ Server Core │
│ credential-state.ts │ init-server.ts │ relay-schema.ts │
├─────────────────────────────────────────────────────────────┤
│ Tool Registry │
│ src/tools/registry.ts │
├─────────────────────────────────────────────────────────────┤
│ Composite Tools │
│ pages │ databases │ blocks │ users │ workspace │ comments │
│ content_convert │ file_uploads │ setup │ help │
├─────────────────────────────────────────────────────────────┤
│ Helpers │
│ errors │ markdown │ richtext │ pagination │ properties │ security │
├─────────────────────────────────────────────────────────────┤
│ Notion SDK │
│ @notionhq/client │
└─────────────────────────────────────────────────────────────┘
```
### 项目目录结构
```
better-notion-mcp/
├── src/
│ ├── init-server.ts # 服务器入口，环境验证
│ ├── credential-state.ts # 凭证状态机 + stdio fallback
│ ├── relay-schema.ts # Relay 表单模式
│ ├── tools/
│ │ ├── registry.ts # 工具注册与路由分发
│ │ ├── composite/ # 复合工具实现
│ │ │ ├── pages.ts # 页面 CRUD 操作
│ │ │ ├── databases.ts # 数据库操作
│ │ │ ├── blocks.ts # 块级操作
│ │ │ ├── comments.ts # 评论操作
│ │ │ ├── users.ts # 用户查询
│ │ │ ├── workspace.ts # 工作区信息
│ │ │ ├── content.ts # 内容格式转换
│ │ │ ├── file_uploads.ts # 文件上传
│ │ │ ├── setup.ts # 设置引导
│ │ │ └── help.ts # 帮助文档
│ │ └── helpers/
│ │ ├── errors.ts # 统一错误处理
│ │ ├── markdown.ts # Markdown ↔ Blocks 转换
│ │ ├── richtext.ts # 富文本构建
│ │ ├── pagination.ts # 分页处理
│ │ ├── properties.ts # 属性转换
│ │ ├── covers.ts # 封面格式化
│ │ ├── icons.ts # 图标格式化
│ │ └── security.ts # 安全检查
│ ├── auth/ # OAuth 2.1 + PKCE 实现
│ ├── transports/ # 传输层实现
│ └── docs/ # MCP 资源文档
├── server.json # MCP 服务器元数据
└── AGENTS.md # 代理文档
```
## 凭证状态机
凭证管理是系统的核心组件之一，采用有限状态机 (FSM) 模式管理认证流程。
### 状态定义
| 状态 | 描述 | 转换条件 |
|------|------|----------|
| `awaiting_setup` | 等待用户配置 Notion Token | 用户通过 relay 表单提交凭证 |
| `setup_in_progress` | 配置进行中 | 凭证验证开始 |
| `configured` | 配置完成 | 凭证验证通过 |
资料来源：[src/credential-state.ts:1-20]()
### 状态流转图
```mermaid
graph TD
A[awaiting_setup] -->|用户提交 NOTION_TOKEN| B[setup_in_progress]
B -->|验证成功| C[configured]
B -->|验证失败| A
C -->|需要重新配置| A
C -->|MCP 请求| D[服务正常响应]
```
### Stdio Fallback 机制
当使用 stdio 传输模式时，系统支持自动 spawn 本地服务器：
```typescript
// credential-state.ts 中的关键逻辑
runLocalServer on 127.0.0.1:random
```
资料来源：[src/credential-state.ts:15]()
## 工具注册与路由
### 工具注册表
所有 MCP 工具通过 `registry.ts` 统一注册和管理。每个工具包含：
- **name**: 工具唯一标识
- **description**: 工具描述（含支持的 actions 列表）
- **annotations**: 元数据提示（readOnlyHint, destructiveHint 等）
- **inputSchema**: JSON Schema 格式的输入参数定义
资料来源：[src/tools/registry.ts:1-50]()
### 10 个复合工具一览
| 工具名称 | 主要功能 | Actions 数量 |
|----------|----------|--------------|
| `pages` | 页面 CRUD、归档、复制、移动 | 8 |
| `databases` | 数据库查询、创建、更新、行操作 | 6 |
| `blocks` | 块 CRUD、追加、批量操作 | 6 |
| `users` | 用户查询（本人、全部、机器人） | 3 |
| `workspace` | 搜索、空间信息、块搜索 | 4 |
| `comments` | 评论列表、获取、创建 | 3 |
| `content_convert` | Markdown ↔ Notion Blocks 双向转换 | 2 |
| `file_uploads` | 文件上传管理（单文件/多部分） | 5 |
| `setup` | 设置引导、方法选择 | 3 |
| `help` | 帮助文档、资源访问 | 4 |
资料来源：[src/tools/registry.ts:50-200]()
### 路由分发机制
```mermaid
graph LR
A[MCP Request] --> B[registry.ts]
B --> C{action 参数解析}
C -->|pages| D[composite/pages.ts]
C -->|databases| E[composite/databases.ts]
C -->|blocks| F[composite/blocks.ts]
C -->|其他| G[对应 composite 模块]
D --> H[withErrorHandling 包装]
H --> I[返回统一结果格式]
```
## 核心模块详解
### 错误处理系统
采用统一的错误处理模式：
```typescript
export class NotionMCPError extends Error {
constructor(
message: string, // 用户友好的错误信息
code: string, // 错误代码
hint: string // 修复建议
)
}
// 包装函数
export function withErrorHandling(fn: () => Promise): Promise
```
资料来源：[src/tools/helpers/errors.ts:1-30]()
### Markdown 转换引擎
支持 Notion Block 与 Markdown 之间的双向转换：
```typescript
// 主要接口
markdownToBlocks(markdown: string): NotionBlock[]
blocksToMarkdown(blocks: NotionBlock[]): string
```
**支持的 Markdown 语法**：
| 类别 | 语法 |
|------|------|
| 标题 | `#` `##` `###` |
| 列表 | `-` `1.` `*` |
| 任务 | `- [ ]` `- [x]` |
| 代码块 | ``` ```语言 ``` |
| 引用 | `>` |
| 分隔线 | `---` |
| Callout | `> [!NOTE]` |
| 折叠 | `` |
| 表格 | 标准 Markdown 表格 |
| 图片 | `` |
| 链接书签 | `[name](url)` |
| 公式 | `$$...$$` |
| 栏目 | `:::columns` |
| 提及 | `@[页面名](page_id)` |
**支持的内联格式**：
- **粗体** `**text**`
- *斜体* `*text*`
- `代码` `` `code` ``
- ~~删除线~~ `~~text~~`
- [链接](url) `[text](url)`
资料来源：[src/tools/helpers/markdown.ts:1-50]()
### 富文本构建
提供链式 API 构建 Notion 富文本：
```typescript
// 基础构建函数
text(content: string): RichTextItem
bold(content: string): RichTextItem // 粗体
italic(content: string): RichTextItem // 斜体
code(content: string): RichTextItem // 行内代码
strike(content: string): RichTextItem // 删除线
link(content: string, url: string): RichTextItem
```
**支持的文本颜色**：
`default` | `gray` | `brown` | `orange` | `yellow` | `green` | `blue` | `purple` | `pink` | `red`
资料来源：[src/tools/helpers/richtext.ts:1-60]()
### 分页处理
提供智能分页支持：
```typescript
autoPaginate(notion, paginator): Promise
populateDeepChildren(notion, blocks): Promise
processBatches(notion, items, batchSize): Promise
```
资料来源：[src/tools/helpers/pagination.ts]()
### 属性转换
处理 Notion 页面属性与 API 格式之间的转换：
```typescript
convertToNotionProperties(input: Record): Record
extractPageProperties(page: PageObjectResponse): Record
```
**属性格式参考**：
```typescript
// 简单值自动转换
{ "Name": "My Page" } // → title
{ "Status": "In Progress" } // → select
{ "Tags": ["tag1", "tag2"] } // → multi_select
{ "Due": "2025-06-01" } // → date
{ "Count": 42 } // → number
{ "Done": true } // → checkbox
```
## 双模式传输架构
### Stdio 模式
标准输入/输出模式，适合本地 CLI 调用：
```json
{
"transport": { "type": "stdio" }
}
```
### HTTP 模式
远程 HTTP 模式，支持分布式部署：
```json
{
"transport": { "type": "http", "port": 3000 }
}
```
### 凭证回退机制
在 stdio 模式下，如果未提供 `NOTION_TOKEN`，系统会：
1. 检查凭证状态
2. 如果状态为 `awaiting_setup`，触发 relay 表单流程
3. 用户通过本地 HTTP 端点提交凭证
4. 凭证验证后，更新状态为 `configured`
## 复合工具实现示例
### Pages 工具
Pages 工具是最大的复合工具，整合了页面相关的所有操作：
```typescript
// 输入接口
export interface PagesInput {
action: 'create' | 'get' | 'get_property' | 'update'
| 'move' | 'archive' | 'restore' | 'duplicate'
page_id?: string
parent_id?: string
title?: string
content?: string | any[]
properties?: Record
icon?: string
cover?: string
property_id?: string
archived?: boolean
}
```
**返回值类型**：
| Action | 返回类型 |
|--------|----------|
| create | `CreatePageResult` |
| get | `GetPageResult` |
| get_property | `GetPagePropertyResult` |
| update | `UpdatePageResult` |
| move | `MovePageResult` |
| archive/restore | `ArchivePageResult` |
| duplicate | `DuplicatePageResult` |
资料来源：[src/tools/composite/pages.ts:1-80]()
### 内容转换工具
提供 Markdown 与 Notion Blocks 的精确转换：
```typescript
export interface ContentConvertInput {
direction: 'markdown-to-blocks' | 'blocks-to-markdown'
content: string | any[]
}
```
验证规则：
- `markdown-to-blocks`：content 必须为字符串
- `blocks-to-markdown`：content 必须为 JSON 数组或可解析的 JSON 字符串
资料来源：[src/tools/composite/content.ts:1-50]()
## 安全设计
### URL 安全检查
所有用户提供的 URL 都会经过安全检查：
```typescript
isSafeUrl(url: string): boolean
```
阻止的协议：
- `javascript:`
- `data:` (在某些上下文)
- 其他不安全协议
资料来源：[src/tools/helpers/security.ts]()
### 请求头过滤
在日志和响应中自动过滤敏感请求头：
```typescript
// 大小写不敏感匹配
redactHeaders(headers, ['authorization', 'cookie', 'x-api-key'])
```
## 依赖管理
### 核心依赖
| 依赖 | 版本 | 用途 |
|------|------|------|
| `@n24q02m/mcp-core` | 1.17.1 | MCP 协议核心库 |
| `@notionhq/client` | ^2.x | Notion API 客户端 |
| `zod` | ^3.x | Schema 验证 |
### 开发依赖
| 依赖 | 用途 |
|------|------|
| `vitest` | 单元测试 |
| `biome` | Lint + Format |
| `typescript` | 类型检查 |
| `esbuild` | 代码打包 |
## 社区关注点
根据项目 issue 和 release notes，以下架构相关话题受到关注：
### 依赖升级策略
项目使用 Renovate 进行依赖管理，核心依赖升级流程：
1. 创建 issue 通知新版本可用
2. 自动更新 `package.json` 中的版本约束
3. 重新生成 lockfile
最近更新：`@n24q02m/mcp-core` 升级至 1.17.1（修复 BearerMCPApp resource_metadata #260）
### 架构演进
| 版本 | 架构变化 |
|------|----------|
| v2.31.0-beta.2 | 引入 stdio-direct 路由到 MCP SDK |
| v2.31.0-beta.3 | 统一为 stdio-pure 架构 |
| v2.34.3 | Pin mcp-core 1.17.1 稳定性修复 |
## 扩展指南
### 添加新工具
1. 在 `src/tools/composite/` 创建新文件
2. 实现工具函数和类型定义
3. 在 `registry.ts` 中注册工具
4. 添加 co-located 测试文件
### 添加新 Action
1. 在对应 composite 文件中添加 action handler
2. 更新 `inputSchema` 定义
3. 在 default 分支添加错误提示
### 编写测试
测试文件与源文件同目录放置：
```
src/tools/composite/
├── pages.ts
└── pages.test.ts
```
## 总结
better-notion-mcp 的系统架构遵循以下设计原则：
1. **复合工具模式**：降低 AI 代理交互复杂度
2. **统一错误处理**：提供一致的错误响应格式
3. **Markdown 优先**：简化内容操作体验
4. **双模式支持**：灵活适配不同部署场景
5. **类型安全**：完整的 TypeScript 类型覆盖
---
## 传输模式详解
### 相关页面
相关主题：[系统架构](#page-architecture), [配置指南](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/init-server.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/init-server.ts)
- [src/credential-state.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/credential-state.ts)
- [src/relay-schema.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/relay-schema.ts)
- [server.json](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
- [docker-compose.http.yml](https://github.com/n24q02m/better-notion-mcp/blob/main/docker-compose.http.yml)
# 传输模式详解
better-notion-mcp 支持两种传输模式：本地 stdio 模式和远程 HTTP 模式。这两种模式决定了 MCP 服务器与客户端之间的通信方式，适用于不同的部署场景。
## 传输模式概述
| 特性 | stdio 模式 | HTTP 模式 |
|------|-----------|-----------|
| 部署方式 | 本地进程 | 远程服务 |
| 认证方式 | NOTION_TOKEN 环境变量 | OAuth 2.1 + PKCE |
| Token 需求 | 需要手动配置 | 无需手动管理 |
| 适用场景 | 本地开发、单用户 | 团队协作、多用户 |
| 启动命令 | 直接运行可执行文件 | Docker 或服务器进程 |
## stdio 模式
stdio 模式是传统的 MCP 传输方式，服务器通过标准输入/输出流与客户端通信。
### 工作原理
```mermaid
graph LR
A[MCP Client] -->|stdio| B[better-notion-mcp]
B -->|stdout| A
C[环境变量] -->|NOTION_TOKEN| B
```
### 配置要求
stdio 模式需要配置 `NOTION_TOKEN` 环境变量：
```bash
export NOTION_TOKEN="secret_xxxxxxxxxxxx"
npx @n24q02m/better-notion-mcp
```
### 凭证状态机
stdio 模式使用三状态凭证机管理认证流程：
```mermaid
graph TD
A[awaiting_setup] -->|检测到 NOTION_TOKEN| C[configured]
B[setup_in_progress] -->|setup 完成| C
C -->|启动本地服务器| D[runLocalServer on 127.0.0.1:random]
```
状态定义位于 `src/credential-state.ts`：
- `awaiting_setup`：等待初始配置
- `setup_in_progress`：配置进行中
- `configured`：已配置，准备运行
当配置完成后，服务器在 `127.0.0.1:随机端口` 启动本地服务器作为 fallback。
## HTTP 模式
HTTP 模式支持远程部署，使用 OAuth 2.1 协议进行认证，无需在客户端存储 token。
### OAuth 2.1 认证流程
```mermaid
sequenceDiagram
participant C as MCP Client
participant S as MCP Server
participant N as Notion API
C->>S: 请求访问
S->>C: 重定向到 Notion OAuth
C->>N: 授权请求
N->>C: 返回 Authorization Code
C->>S: 交换 Code
S->>N: 获取 Access Token
N->>S: 返回 Token
S->>C: 建立会话
```
### PKCE 安全机制
HTTP 模式实现 OAuth 2.1 的 PKCE（Proof Key for Code Exchange）扩展：
- **code_verifier**：随机生成的挑战码
- **code_challenge**：基于 verifier 的 SHA-256 哈希值
- 防止授权码被拦截后滥用
### 中继表单模式
服务器提供 `/login` 路由用于 OAuth 认证：
```typescript
// 资料来源：src/relay-schema.ts:1-20
// 表单包含 Notion token 字段，支持 OAuth 流程
```
表单 Schema 定义了认证所需字段，包括：
- Notion token 输入字段
- OAuth 回调处理
- 会话管理
## Docker 部署配置
### HTTP 模式 Docker Compose
```yaml
# 资料来源：docker-compose.http.yml
services:
better-notion-mcp:
image: docker.io/n24q02m/better-notion-mcp:latest
environment:
- NOTION_TOKEN=${NOTION_TOKEN}
- PORT=3000
ports:
- "3000:3000"
```
### 环境变量
| 变量名 | 说明 | 必需 | 默认值 |
|--------|------|------|--------|
| `NOTION_TOKEN` | Notion 集成令牌 | 是（stdio）/ 否（OAuth） | - |
| `PORT` | HTTP 服务端口 | 否 | 3000 |
| `RELAY_URL` | 中继服务 URL | 否（HTTP 模式） | - |
## 工具注册与路由
服务器初始化时根据传输模式注册工具：
```typescript
// 资料来源：src/tools/registry.ts:1-30
const TOOLS = [
{
name: 'pages',
description: 'Page CRUD for individual pages and database rows...',
annotations: {
title: 'Pages',
readOnlyHint: false,
destructiveHint: false,
idempotentHint: false,
openWorldHint: false
}
},
// ... 其他工具
]
```
### 工具列表
| 工具名称 | 功能 | 只读 | 破坏性 |
|----------|------|------|--------|
| `pages` | 页面 CRUD 操作 | 否 | 否 |
| `databases` | 数据库查询和管理 | 部分 | 否 |
| `blocks` | 块级内容操作 | 部分 | 是 |
| `users` | 用户信息查询 | 是 | 否 |
| `workspace` | 工作区操作 | 是 | 否 |
| `comments` | 评论管理 | 否 | 否 |
| `content_convert` | Markdown 与块格式转换 | 是 | 否 |
| `file_uploads` | 文件上传 | 否 | 否 |
| `setup` | 设置引导 | 否 | 否 |
| `help` | 帮助信息 | 是 | 否 |
## 架构演进
### stdio-pure 到 Dual Transport
v2.31.0-beta.3 标志着架构从纯 stdio 模式演进为双传输支持：
```mermaid
graph TD
A[v2.30.x] -->|架构重构| B[v2.31.0+]
B --> C[stdio 模式]
B --> D[HTTP 模式]
C -->|MCP SDK Direct| E[标准输入输出]
D -->|OAuth 2.1| F[远程访问]
```
关键变更：
- 添加 `src/transports/` 目录处理 stdio 和 http 传输
- 引入 OAuth 2.1 认证机制
- 实现 PKCE 安全扩展
### 版本兼容性
| 版本 | 传输模式 | 认证方式 |
|------|----------|----------|
| v2.30.x | stdio only | NOTION_TOKEN |
| v2.31.0+ | stdio + HTTP | OAuth 2.1 / NOTION_TOKEN |
| v2.34.x | 双模式 | OAuth 2.1 + PKCE |
## 安全考量
### Token 处理
- stdio 模式：token 通过环境变量传递，不记录日志
- HTTP 模式：使用短期 access token，定期刷新
### 网络安全
- HTTP 服务默认绑定 `127.0.0.1`
- Docker 部署需配置网络策略
- 支持 HTTPS 反向代理
## 快速开始
### 选择传输模式
```mermaid
graph TD
A[开始] --> B{部署场景?}
B -->|本地开发| C[stdio 模式]
B -->|远程/多用户| D[HTTP 模式]
C --> E[配置 NOTION_TOKEN]
D --> F[设置 OAuth 应用]
```
### 常用命令
```bash
# stdio 模式
export NOTION_TOKEN="secret_xxx"
bun run start
# HTTP 模式 (Docker)
docker-compose -f docker-compose.http.yml up
# HTTP 模式 (源码)
bun run build
PORT=3000 ./dist/cli.js
```
## 故障排除
| 问题 | 解决方案 |
|------|----------|
| stdio 连接失败 | 检查 NOTION_TOKEN 是否正确设置 |
| OAuth 重定向失败 | 确认 RELAY_URL 配置正确 |
| Docker 端口冲突 | 修改 PORT 环境变量 |
| Token 过期 | HTTP 模式自动刷新，stdio 需手动更新 |
## 相关文档
- [官方文档](https://mcp.n24q02m.com)
- [OAuth 配置指南](https://github.com/n24q02m/better-notion-mcp/blob/main/docs/oauth-setup.md)
- [Docker 部署说明](https://github.com/n24q02m/better-notion-mcp/blob/main/docs/docker.md)
---
## 复合工具详解
### 相关页面
相关主题：[项目介绍](#page-introduction), [安全机制](#page-security)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/registry.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/registry.ts)
- [src/tools/composite/pages.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/pages.ts)
- [src/tools/composite/blocks.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/blocks.ts)
- [src/tools/composite/content.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/content.ts)
- [src/tools/composite/comments.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/comments.ts)
- [src/tools/helpers/markdown.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.ts)
- [src/tools/helpers/richtext.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/richtext.ts)
- [src/tools/helpers/errors.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/errors.ts)
# 复合工具详解
## 概述
复合工具（Composite Tools）是 better-notion-mcp 的核心设计理念。该项目将 Notion API 的多个原子端点聚合为单一工具调用，实现"一次调用，多端协作"的模式，大幅减少 AI Agent 与 API 的交互次数。
### 核心价值
| 特性 | 描述 | 收益 |
|------|------|------|
| 端点聚合 | 将 2+ 个原子 API 调用合并为单一工具 | 减少网络往返 |
| 自动分页 | 内置游标处理，无需手动循环 | 简化批量操作 |
| 格式转换 | Markdown ↔ Notion Blocks 自动互转 | 人类可读的输出 |
| 参数归一化 | 统一的输入格式，简化 property 定义 | 降低使用门槛 |
### 工具清单
当前版本共提供 **10 个复合工具**，涵盖 44 个操作动作：
| 工具名称 | 源码文件 | 核心功能 |
|----------|----------|----------|
| pages | `src/tools/composite/pages.ts` | 页面 CRUD |
| databases | `src/tools/composite/databases.ts` | 数据库查询与操作 |
| blocks | `src/tools/composite/blocks.ts` | 块级内容操作 |
| users | `src/tools/composite/users.ts` | 用户信息获取 |
| workspace | `src/tools/composite/workspace.ts` | 工作区信息 |
| comments | `src/tools/composite/comments.ts` | 评论管理 |
| content_convert | `src/tools/composite/content.ts` | Markdown/Blocks 互转 |
| file_uploads | `src/tools/composite/file-uploads.ts` | 文件上传 |
| setup | `src/tools/composite/setup.ts` | 认证引导 |
| help | `src/tools/composite/help.ts` | 上下文帮助 |
---
## 工具注册机制
### 架构概览
```mermaid
graph TD
A[AI Agent] --> B[Tool Registry]
B --> C{路由匹配}
C -->|pages| D[pages.ts]
C -->|databases| E[databases.ts]
C -->|blocks| F[blocks.ts]
C -->|comments| G[comments.ts]
C -->|content_convert| H[content.ts]
C -->|其他| I[对应模块]
D --> J[withErrorHandling]
E --> J
F --> J
J --> K[Notion Client]
K --> L[Notion API]
```
### 注册表结构
工具定义存储在 `src/tools/registry.ts` 中，每个工具包含以下元数据：
资料来源：[src/tools/registry.ts:1-80]()
```typescript
const TOOLS = [
{
name: 'pages',
description: 'Page CRUD for individual pages and database rows.\n\nActions (required params -> optional):\n- create (parent_id -> title, content, properties, icon, cover)\n- get (page_id): returns markdown content\n- update (page_id -> title, content, properties)\n...',
annotations: {
title: 'Pages',
readOnlyHint: false,
destructiveHint: false,
idempotentHint: false,
openWorldHint: false
},
inputSchema: {
type: 'object',
properties: {
action: { type: 'string', enum: ['create', 'get', 'update', ...] },
...
},
required: ['action']
}
},
...
]
```
### 路由分发
每个复合工具采用统一的 `action` 参数进行路由分发：
```typescript
export async function pages(notion: Client, input: PagesInput): Promise {
return withErrorHandling(async () => {
switch (input.action) {
case 'create':
return await createPage(notion, input)
case 'get':
return await getPage(notion, input)
case 'update':
return await updatePage(notion, input)
// ...
}
})()
}
```
资料来源：[src/tools/composite/pages.ts:42-70]()
---
## Pages 工具详解
### 功能范围
Pages 工具是使用频率最高的复合工具，支持页面和数据库行的完整生命周期管理。
```mermaid
graph LR
A[create] --> B[页面创建]
A --> C[行创建]
D[get] --> E[获取内容]
F[update] --> G[更新属性/内容]
H[archive/restore] --> I[软删除/恢复]
J[duplicate] --> K[复制页面]
L[move] --> M[移动位置]
```
### 支持的动作
| 动作 | 必需参数 | 可选参数 | 说明 |
|------|----------|----------|------|
| create | parent_id | title, content, properties, icon, cover | 创建页面或数据库行 |
| get | page_id | - | 返回 Markdown 格式内容 |
| get_property | page_id, property_id | - | 获取特定属性值 |
| update | page_id | title, content, append_content, properties, icon, cover, archived | 更新页面 |
| move | page_id, parent_id | - | 移动页面到新父级 |
| archive | page_id | - | 归档页面 |
| restore | page_id | - | 恢复已归档页面 |
| duplicate | page_id | parent_id | 复制页面 |
### 属性格式规范
Notion API 要求特定类型的属性必须使用嵌套对象格式：
```typescript
// 正确的格式
const properties = {
"Name": "My Page", // title 自动转换
"Status": { "select": { "name": "In Progress" } },
"Tags": { "multi_select": [{ "name": "engineering" }] },
"Due": { "date": { "start": "2025-06-01" } },
"Count": { "number": 42 },
"Done": { "checkbox": true }
}
```
资料来源：[src/tools/registry.ts:50-60]()
---
## Blocks 工具详解
### 功能范围
Blocks 工具处理页面内部的内容块，支持块级 CRUD 操作。
### 支持的块类型
| 类型 | 可更新 | 说明 |
|------|--------|------|
| paragraph | ✓ | 段落 |
| heading_1/2/3 | ✓ | 标题 |
| bulleted_list_item | ✓ | 无序列表 |
| numbered_list_item | ✓ | 有序列表 |
| to_do | ✓ | 待办事项（含 checked 状态） |
| code | ✓ | 代码块（含语言） |
| quote | ✓ | 引用 |
| callout | ✓ | 标注 |
| toggle | ✓ | 可折叠内容 |
| divider | ✗ | 分隔线（不可更新内容） |
### 更新验证逻辑
```typescript
const UPDATABLE_BLOCK_TYPES = new Set([
'paragraph', 'heading_1', 'heading_2', 'heading_3',
'bulleted_list_item', 'numbered_list_item', 'to_do',
'code', 'quote', 'callout', 'toggle'
])
```
Blocks 工具会验证输入的 Markdown 是否能解析为相同类型的块：
```typescript
// Validate block type match
if (newContent.type !== blockType) {
throw new NotionMCPError(
`Block type mismatch: cannot update ${blockType} with content that parses to ${newContent.type}`,
'VALIDATION_ERROR',
`Provide markdown that parses to ${blockType}`
)
}
```
资料来源：[src/tools/composite/blocks.ts:30-50]()
---
## Content Convert 工具详解
### 功能范围
Content Convert 工具提供 Markdown 与 Notion Block JSON 之间的双向转换。
```mermaid
graph LR
A[Markdown String] -->|markdown-to-blocks| B[JSON Array of Blocks]
B -->|blocks-to-markdown| A
```
### 使用场景
- **预览/验证**: 在正式调用 pages/blocks 工具前验证 Markdown 格式
- **格式转换**: 将现有的 Notion 块导出为 Markdown，或反之
- **调试**: 检查 markdownToBlocks 的解析结果
### 支持的 Markdown 语法
| 语法 | 对应块类型 |
|------|------------|
| `# ## ###` | heading_1/2/3 |
| `- item` | bulleted_list_item |
| `1. item` | numbered_list_item |
| `- [ ] task` | to_do |
| `` `code` `` | paragraph (code 格式) |
| ```` ```lang` | code |
| `> quote` | quote |
| `---` | divider |
| `> [!NOTE]` | callout |
| `` | toggle |
| `| table |` | table |
| `` | image |
| `[text](url)` | bookmark |
| `$$equation$$` | equation |
| `:::columns` | column_list/column |
| `[toc]` | table_of_contents |
资料来源：[src/tools/helpers/markdown.ts:1-20]()
---
## Comments 工具详解
### 功能范围
Comments 工具管理页面评论，支持讨论线程操作。
### 支持的动作
| 动作 | 必需参数 | 可选参数 | 说明 |
|------|----------|----------|------|
| list | page_id | - | 列出页面所有评论 |
| get | comment_id | - | 获取单个评论 |
| create | content | page_id, discussion_id | 创建新讨论或回复 |
### 创建评论的两种模式
```typescript
// 模式 1: 创建新讨论线程
comments({
action: 'create',
page_id: 'xxx', // 必需：指定页面
content: '讨论内容'
})
// 模式 2: 回复现有讨论
comments({
action: 'create',
discussion_id: 'yyy', // 必需：指定讨论线程
content: '回复内容'
})
```
资料来源：[src/tools/registry.ts:80-100]()
---
## File Uploads 工具详解
### 功能范围
File Uploads 工具处理 Notion 文件上传，支持分片上传大文件。
### 操作流程
```mermaid
graph TD
A[create] --> B[获取 file_upload_id]
B --> C{文件大小}
C -->|< 20MB| D[单次上传]
C -->|> 20MB| E[分片上传]
E --> F[send part 1]
F --> G[send part 2]
G --> H[...]
H --> I[complete]
I --> J[retrieve 验证]
```
### 支持的动作
| 动作 | 必需参数 | 可选参数 | 说明 |
|------|----------|----------|------|
| create | filename | content_type, mode, number_of_parts | 初始化上传 |
| send | file_upload_id, file_content | part_number | 发送分片（base64） |
| complete | file_upload_id | - | 完成上传 |
| retrieve | file_upload_id | - | 获取上传状态 |
| list | - | limit | 列出上传任务 |
资料来源：[src/tools/registry.ts:25-45]()
---
## 辅助工具函数
### 错误处理
所有复合工具通过 `withErrorHandling` 包装，统一异常处理：
```typescript
import { NotionMCPError, withErrorHandling } from '../helpers/errors.js'
export async function pages(notion: Client, input: PagesInput): Promise {
return withErrorHandling(async () => {
// 业务逻辑
})()
}
```
错误类型包括：
- `VALIDATION_ERROR`: 参数验证失败
- `NOTION_API_ERROR`: Notion API 返回错误
- `AUTH_ERROR`: 认证失败
- `RATE_LIMIT`: 速率限制
### Rich Text 工具
`src/tools/helpers/richtext.ts` 提供富文本构造辅助函数：
```typescript
export function text(content: string): RichTextItem {
return {
type: 'text',
text: { content, link: null },
annotations: { ...DEFAULT_ANNOTATIONS }
}
}
export function bold(content: string): RichTextItem {
return {
type: 'text',
text: { content, link: null },
annotations: { ...DEFAULT_ANNOTATIONS, bold: true }
}
}
```
支持的格式化：
- **bold** / *italic* / ~~strikethrough~~ / `code`
- 支持的颜色: gray, brown, orange, yellow, green, blue, purple, pink, red
资料来源：[src/tools/helpers/richtext.ts:1-50]()
---
## 安全考虑
### URL 安全验证
所有 Markdown 中的链接都会经过 `isSafeUrl` 检查：
```typescript
import { isSafeUrl } from './security.js'
// javascript: 等危险协议会被拦截
const result = parseRichText('[Click](javascript:alert(1))')
// 结果: link 为 null，文本内容保留但不可点击
```
### 安全测试覆盖
`src/tools/helpers/markdown.security.test.ts` 验证了以下场景：
- `javascript:` 链接在富文本中被清除
- `javascript:` 在图片 src 中被清除
- `javascript:` 在书签中被清除
资料来源：[src/tools/helpers/markdown.security.test.ts:1-30]()
---
## 测试策略
### 测试文件组织
测试文件与源码共置，便于维护：
```
src/tools/composite/
├── pages.ts
├── pages.test.ts # 共置测试
├── databases.ts
├── databases.test.ts
└── ...
```
### 常见测试模式
```typescript
describe('Pages Tool', () => {
it('handles pages with no blocks', async () => {
mockNotion.blocks.children.list.mockResolvedValue({
results: [],
next_cursor: null,
has_more: false
})
const result = await pages(mockNotion as any, {
action: 'get',
page_id: 'page-2'
})
expect(result.block_count).toBe(0)
expect(result.properties).toEqual({})
})
})
```
---
## 最佳实践
### 1. 选择正确的属性类型
| 数据模式 | 正确类型 | 常见错误 |
|----------|----------|----------|
| 固定分类 | select | rich_text（失去筛选能力） |
| 多标签 | multi_select | select（只允许单个） |
| 跨库引用 | relation | rich_text（破坏关联） |
| 布尔标志 | checkbox | select with Yes/No |
### 2. 分块策略
- **内容 < 100 块**: 直接使用 `pages` 工具的 `content` 参数
- **内容 > 100 块**: 使用 `pages` 创建 + `blocks` 追加
- **大批量操作**: 利用工具内置的自动分页功能
### 3. 错误处理
```typescript
try {
const result = await pages(notion, { action: 'get', page_id: id })
} catch (error) {
if (error.code === 'VALIDATION_ERROR') {
// 处理参数错误
} else if (error.code === 'NOTION_API_ERROR') {
// 处理 API 错误
}
}
```
---
## 相关资源
- 源码仓库: [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp)
- 最新版本: [v2.34.3](https://github.com/n24q02m/better-notion-mcp/releases/tag/v2.34.3)
- 官方文档: [mcp.n24q02m.com](https://mcp.n24q02m.com)
---
## 安全机制
### 相关页面
相关主题：[传输模式详解](#page-transport-modes), [配置指南](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/helpers/security.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/security.ts)
- [src/tools/helpers/markdown.security.test.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.security.test.ts)
- [src/tools/helpers/markdown.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.ts)
- [src/auth/notion-token-store.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/auth/notion-token-store.ts)
- [SECURITY.md](https://github.com/n24q02m/better-notion-mcp/blob/main/SECURITY.md)
- [renovate.json](https://github.com/n24q02m/better-notion-mcp/blob/main/renovate.json)
# 安全机制
better-notion-mcp 在多个层面实现了安全防护机制，包括 URL 安全校验、敏感信息处理、依赖安全管理和 Token 认证安全。本页详细说明各安全组件的实现原理和使用方式。
## 概览
该项目的安全机制主要由以下模块组成：
| 安全组件 | 文件位置 | 防护类型 |
|----------|----------|----------|
| URL 安全校验 | `src/tools/helpers/security.ts` | XSS 攻击防护 |
| Markdown 安全解析 | `src/tools/helpers/markdown.ts` | 恶意内容过滤 |
| Token 安全存储 | `src/auth/notion-token-store.ts` | 凭证保护 |
| HTTP Header 处理 | MCP Core 集成 | 敏感信息脱敏 |
| 依赖版本锁定 | `renovate.json` | 供应链安全 |
## URL 安全校验
### 核心实现
URL 安全校验是防止 XSS（跨站脚本攻击）的第一道防线。项目使用 `isSafeUrl()` 函数对所有用户输入的 URL 进行安全检查。
资料来源：[src/tools/helpers/security.ts]()
```typescript
export function isSafeUrl(url: string): boolean {
// 检查是否包含危险协议
const lowerUrl = url.toLowerCase().trim()
// 阻止 javascript: 协议
if (lowerUrl.startsWith('javascript:')) {
return false
}
// 阻止 data: 协议（防止内联数据滥用）
if (lowerUrl.startsWith('data:')) {
return false
}
// 阻止 vbscript: 协议
if (lowerUrl.startsWith('vbscript:')) {
return false
}
return true
}
```
### 安全校验流程
```mermaid
graph TD
A[用户输入 URL] --> B{协议检查}
B -->|javascript:| C[拒绝 - XSS风险]
B -->|data:| D[拒绝 - 数据滥用风险]
B -->|vbscript:| E[拒绝 - 脚本风险]
B -->|其他协议| F[允许通过]
F --> G[用于 Notion 内容]
```
## Markdown 内容安全
### 安全解析机制
Markdown 到 Notion Block 的转换过程中，系统会对所有链接进行安全校验：
资料来源：[src/tools/helpers/markdown.ts:1-15]()
```typescript
import { isSafeUrl } from './security.js'
// 链接转换前先验证 URL 安全性
if (isSafeUrl(url)) {
// 正常创建链接
} else {
// 降级处理 - 不创建链接或转为纯文本
}
```
### 危险场景处理
| 输入场景 | 安全处理方式 | 预期结果 |
|----------|--------------|----------|
| `[点击](javascript:alert(1))` | 移除链接，仅保留文本 | 纯文本 "点击" |
| `)` | 转为段落，移除图片 | 段落类型 |
| `[书签](javascript:prompt())` | 降级为纯文本 | 纯文本 "书签" |
资料来源：[src/tools/helpers/markdown.security.test.ts:1-45]()
### 测试覆盖
项目包含专门的安全测试文件验证各类攻击场景：
```typescript
it('should sanitize javascript: links in rich text', () => {
const result = parseRichText('[Click me](javascript:alert(1))')
expect(result[0].text.link).toBeNull()
expect(result[0].text.content).toBe('Click me')
})
it('should sanitize javascript: in image src', () => {
const blocks = markdownToBlocks(')')
expect(blocks[0].type).toBe('paragraph')
})
it('should sanitize javascript: in bookmarks', () => {
const blocks = markdownToBlocks('[bookmark](javascript:void(0))')
expect(blocks[0].type).toBe('paragraph')
})
```
资料来源：[src/tools/helpers/markdown.security.test.ts:8-28]()
## Token 认证安全
### Token 管理
项目使用 `NOTION_TOKEN` 环境变量存储 Notion API 集成令牌：
| 配置项 | 类型 | 说明 |
|--------|------|------|
| `NOTION_TOKEN` | 环境变量 | Notion 集成令牌，必填 |
| 存储方式 | 环境变量注入 | 不持久化到磁盘 |
资料来源：[server.json:17-24]()
```json
{
"environmentVariables": [
{
"description": "Notion integration token. Create at https://www.notion.so/my-integrations",
"isRequired": true,
"isSecret": true,
"name": "NOTION_TOKEN"
}
]
}
```
### Token Store 实现
资料来源：[src/auth/notion-token-store.ts]()
```typescript
// Token 通过安全的环境变量机制注入
// 不在运行时暴露或记录敏感信息
```
## HTTP Header 安全处理
### Header 脱敏
项目在 v2.33.1-beta.1 版本中优化了 HTTP Header 的敏感信息处理：
- **大小写不敏感匹配**：自动识别和移除各类认证相关的 Header
- **Bearer Token 保护**：防止 Authorization Header 被意外泄露
资料来源：[v2.33.1-beta.1 Release Notes](https://github.com/n24q02m/better-notion-mcp/releases/tag/v2.33.1-beta.1)
## 依赖安全
### 依赖版本锁定
项目使用 Renovate 进行自动化依赖管理，并配置了严格的版本策略：
资料来源：[renovate.json:1-60]()
```json
{
"description": "Pin GitHub Actions to SHA for security",
"matchManagers": ["github-actions"],
"pinDigests": true
}
```
### 版本锁定策略
| 组件 | 版本约束 | 策略 |
|------|----------|------|
| Python | `>=3.13.0 <3.14.0` | 锁定次版本 |
| Node.js | `>=24.0.0 <25.0.0` | 锁定主版本 |
| Java | `>=21.0.0 <22.0.0` | 锁定 LTS 版本 |
| GitHub Actions | SHA 固定 | 防止供应链攻击 |
```json
{
"description": "Pin Python runtime to 3.13.x",
"matchPackageNames": ["python"],
"allowedVersions": ">=3.13.0 <3.14.0"
}
```
### 运行时版本更新禁用
项目配置了 mise 管理器，但禁用了运行时版本的自动更新以确保稳定性：
```json
{
"description": "Disable runtime version updates from mise (pinned in CLAUDE.md)",
"matchManagers": ["mise"],
"matchDepNames": ["python", "node", "java"],
"enabled": false
}
```
## 安全报告
### 漏洞报告流程
项目遵循标准的安全漏洞披露流程：
资料来源：[SECURITY.md]()
1. 通过 GitHub Security Advisories 报告
2. 维护者承诺在 48 小时内响应
3. 关键漏洞优先处理
## 安全架构图
```mermaid
graph TB
subgraph "输入层"
A[用户 Markdown 输入]
B[URL 链接]
C[Token 环境变量]
end
subgraph "安全校验层"
D[isSafeUrl 检查]
E[协议白名单验证]
F[XSS 模式匹配]
end
subgraph "处理层"
G[安全内容转换]
H[降级为纯文本]
end
subgraph "输出层"
I[Notion Block JSON]
J[API 调用]
end
A --> D
B --> E
D --> F
E --> F
F -->|安全| G
F -->|危险| H
G --> I
H --> I
C --> J
I --> J
```
## 最佳实践
### 开发者注意事项
1. **始终使用 `isSafeUrl()`** - 所有外部 URL 都应经过安全校验
2. **降级处理优于静默丢弃** - 不安全的链接应转为纯文本而非完全删除
3. **环境变量存储 Token** - 绝不将凭证硬编码或提交到版本控制
4. **定期更新依赖** - 使用 Renovate 自动化工具保持依赖最新
### 安全配置检查清单
- [ ] NOTION_TOKEN 通过环境变量注入
- [ ] 使用固定的 GitHub Actions SHA
- [ ] 定期检查依赖安全更新
- [ ] 测试覆盖包含安全边界场景
---
## 配置指南
### 相关页面
相关主题：[传输模式详解](#page-transport-modes), [部署指南](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/n24q02m/better-notion-mcp/blob/main/README.md)
- [CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
- [src/relay-schema.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/relay-schema.ts)
- [package.json](https://github.com/n24q02m/better-notion-mcp/blob/main/package.json)
- [server.json](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
- [src/init-server.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/init-server.ts)
# 配置指南
Better Notion MCP 是一个 Markdown 优先的 Notion API MCP 服务器，提供 10 个复合工具和 44 种操作。本指南详细说明如何配置服务器以连接 Notion 工作区。
## 环境要求
| 组件 | 最低版本 | 说明 |
|------|---------|------|
| Node.js | ≥24.16.0 | 服务器运行时 |
| Bun | 任意稳定版 | 用于依赖安装和构建 |
资料来源：[package.json:engine](./package.json#L11-L12)
## 环境变量配置
### 必需环境变量
| 变量名 | 描述 | 类型 | 必填 |
|--------|------|------|------|
| `NOTION_TOKEN` | Notion 集成令牌 | 字符串 | 是 |
**获取方式**：访问 [Notion My Integrations](https://www.notion.so/my-integrations) 创建新的集成并获取令牌。
```bash
# 设置环境变量
export NOTION_TOKEN="secret_xxxxxxxxxxxx"
```
资料来源：[server.json:环境变量定义](./server.json#L20-L24)
### 服务启动配置
服务器支持两种启动模式：
| 模式 | 环境变量 | 说明 |
|------|---------|------|
| stdio 模式 | `NOTION_TOKEN` | 本地 stdio 传输（令牌模式） |
| HTTP 模式 | `NOTION_TOKEN` + OAuth | 远程 HTTP 传输（无需令牌） |
## 认证方式
Better Notion MCP 支持两种认证流程：
### 方式一：令牌认证（stdio 模式）
适用于本地 AI 代理或 CLI 工具：
1. 在 Notion 创建集成并获取 `secret_xxx` 格式的令牌
2. 设置 `NOTION_TOKEN` 环境变量
3. 启动服务器即可使用所有工具
```bash
# 启动 stdio 模式
better-notion-mcp
```
### 方式二：OAuth 2.1 认证（HTTP 模式）
适用于远程部署和多用户场景：
- 支持 PKCE（Proof Key for Code Exchange）
- 支持 DCR（Dynamic Client Registration）
- 支持会话管理
资料来源：[CLAUDE.md:OAuth 2.1 + PKCE](./CLAUDE.md#src/auth/)
## 凭证状态机
服务器内部维护凭证状态，决定如何处理请求：
```mermaid
graph TD
A[启动] --> B{检查凭证}
B -->|无配置| C[awaiting_setup]
B -->|配置不完整| D[setup_in_progress]
B -->|配置完成| E[configured]
C -->|用户完成设置| E
D -->|用户完成设置| E
E --> F[处理请求]
```
| 状态 | 描述 | 行为 |
|------|------|------|
| `awaiting_setup` | 等待初始配置 | 返回设置引导信息 |
| `setup_in_progress` | 配置进行中 | 提示用户完成配置流程 |
| `configured` | 配置完成 | 正常处理所有请求 |
对于 stdio 模式，服务器会在 `127.0.0.1:随机端口` 启动本地服务器作为备用方案。
资料来源：[CLAUDE.md:状态机](./CLAUDE.md#src/credential-state.ts)
## 中继配置
服务器支持通过中继（Relay）服务转发请求，适用于需要代理的场景：
```typescript
// 中继表单 schema
{
"type": "object",
"properties": {
"token": {
"type": "string",
"title": "Notion Token",
"description": "secret_xxx 或 oauth_access_token"
}
},
required": ["token"]
}
```
中继服务可接收两种格式的令牌：
- `secret_xxx` - 直接集成令牌
- `oauth_access_token` - OAuth 访问令牌
资料来源：[src/relay-schema.ts](./src/relay-schema.ts#L1-L15)
## 双传输模式架构
```mermaid
graph LR
subgraph "本地模式"
A1[AI Agent] -->|stdio| B1[better-notion-mcp]
end
subgraph "远程模式"
A2[远程客户端] -->|HTTP| B2[MCP Relay]
B2 -->|转发| B3[better-notion-mcp]
end
B1 -->|API| C[Notion API]
B3 -->|API| C
```
### stdio 模式配置
```bash
# 直接运行
better-notion-mcp
# 或通过 Docker
docker run --rm -i -e NOTION_TOKEN n24q02m/better-notion-mcp:latest
```
资料来源：[README.md:双传输](./README.md#features)
### HTTP 模式配置
远程 HTTP 传输使用 OAuth 2.1，无需在服务器端存储令牌：
1. 配置 OAuth 应用
2. 客户端通过授权流程获取访问令牌
3. 请求通过 HTTPS 转发到 MCP 服务器
## 安全配置
### 令牌安全
- `NOTION_TOKEN` 应始终保密，不提交到版本控制
- 使用环境变量或密钥管理服务存储
- 中继传输时，令牌仅在建立连接时使用
### URL 安全验证
服务器内置 `isSafeUrl` 检查，防止 XSS 攻击：
```typescript
// 安全检查包括
// - javascript: 协议拦截
// - data: URL 限制
// - 外部链接验证
```
资料来源：[src/tools/helpers/markdown.ts:isSafeUrl](./src/tools/helpers/markdown.ts#L7)
## 快速开始配置
### 步骤 1：安装服务器
```bash
# 通过 npm
npx @n24q02m/better-notion-mcp
# 或从源码构建
git clone https://github.com/n24q02m/better-notion-mcp.git
cd better-notion-mcp
bun install
bun run build
```
### 步骤 2：创建 Notion 集成
1. 访问 [Notion My Integrations](https://www.notion.so/my-integrations)
2. 点击 "New integration"
3. 填写名称和关联工作区
4. 复制生成的令牌
### 步骤 3：配置环境变量
```bash
export NOTION_TOKEN="secret_xxxxxxxxxxxxxxxxxxxx"
```
### 步骤 4：授权访问
将集成连接到需要访问的 Notion 页面或数据库：
1. 打开 Notion 页面
2. 点击右上角 `...` 菜单
3. 选择 "Connections" → 添加你的集成
### 步骤 5：验证配置
```bash
# 运行检查命令
bun run check
# 运行测试
bun run test
```
## 高级配置选项
### 开发环境配置
```bash
# 安装依赖
bun install
# 代码检查
bun run check
# 自动修复
bun run check:fix
# 运行测试
bun run test
```
资料来源：[CLAUDE.md:常用命令](./CLAUDE.md#常用命令)
### Docker 配置
```bash
# 构建镜像
bun run docker:build
# 运行容器
bun run docker:run
# 推送镜像
bun run docker:push
```
## 常见配置问题
### 问题 1：凭证状态为 awaiting_setup
**原因**：`NOTION_TOKEN` 未设置或格式不正确
**解决**：
```bash
# 确认环境变量已设置
echo $NOTION_TOKEN
# 验证令牌格式（应为 secret_xxx）
```
### 问题 2：OAuth 授权失败
**原因**：
- OAuth 应用配置不正确
- PKCE 验证失败
- 重定向 URI 不匹配
**解决**：检查 OAuth 应用设置中的客户端 ID、密钥和重定向 URI
### 问题 3：权限不足
**原因**：集成未添加到 Notion 页面或数据库
**解决**：
1. 打开 Notion 页面
2. 点击 `...` → "Connections"
3. 添加对应的集成
## 工具配置矩阵
| 工具 | 操作数 | 需要配置 | 说明 |
|------|--------|---------|------|
| pages | 6 | 否 | 页面 CRUD 操作 |
| databases | 5 | 否 | 数据库查询和管理 |
| blocks | 7 | 否 | 块操作 |
| users | 3 | 否 | 用户信息 |
| workspace | 3 | 否 | 工作区信息 |
| comments | 3 | 否 | 评论管理 |
| content_convert | 2 | 否 | Markdown/Blocks 转换 |
| file_uploads | 5 | 否 | 文件上传（最大 20MB） |
| setup | 3 | 是 | 设置工具 |
| help | 1 | 否 | 帮助信息 |
资料来源：[README.md:工具](./README.md#tools)
## 版本信息
当前最新版本：**v2.34.3**
该版本已修复 mcp-core 1.17.1 中的 BearerMCPApp resource_metadata 问题。
如需更新配置依赖：
```bash
# TypeScript
bun install
# 更新 mcp-core 后重新构建
bun run build
```
## 延伸阅读
- [架构文档](./AGENTS.md) - 深入了解代码架构
- [贡献指南](./CONTRIBUTING.md) - 开发流程和提交规范
- [安全模型](./README.md#security) - 信任模型和隐私说明
---
## 部署指南
### 相关页面
相关主题：[配置指南](#page-configuration), [传输模式详解](#page-transport-modes)
相关源码文件
以下源码文件用于生成本页说明：
- [Dockerfile](https://github.com/n24q02m/better-notion-mcp/blob/main/Dockerfile)
- [docker-compose.http.yml](https://github.com/n24q02m/better-notion-mcp/blob/main/docker-compose.http.yml)
- [package.json](https://github.com/n24q02m/better-notion-mcp/blob/main/package.json)
- [server.json](https://github.com/n24q02m/better-notion-mcp/blob/main/server.json)
- [README.md](https://github.com/n24q02m/better-notion-mcp/blob/main/README.md)
- [CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
# 部署指南
本文档介绍 better-notion-mcp 的多种部署方式，帮助开发者根据不同场景选择合适的安装和运行方法。
## 部署模式概述
better-notion-mcp 支持两种传输模式：
| 模式 | 传输类型 | 认证方式 | 适用场景 |
|------|----------|----------|----------|
| **stdio** | 本地标准 I/O | NOTION_TOKEN | 本地开发、AI Agent 集成 |
| **HTTP** | 远程 HTTP | OAuth 2.1 (PKCE) | 远程服务、多租户部署 |
资料来源：[README.md:40-42]()
```mermaid
graph LR
A[better-notion-mcp] --> B{传输模式}
B --> C[stdio 模式
本地 Token 认证]
B --> D[HTTP 模式
OAuth 2.1 认证]
C --> E[直接进程通信]
D --> F[MCP SDK Direct]
D --> G[中继服务器]
```
## 前置要求
### 环境依赖
| 依赖项 | 版本要求 | 说明 |
|--------|----------|------|
| Node.js | >= 24.0.0 < 25.0.0 | JavaScript 运行时 |
| Python | >= 3.13.0 < 3.14.0 | Python SDK 支持 |
| Docker | 最新稳定版 | 容器化部署 |
| Bun | 最新稳定版 | 包管理和构建 |
资料来源：[renovate.json:14-22]()
### Notion 集成准备
1. 访问 [Notion Integrations](https://www.notion.so/my-integrations) 创建集成
2. 获取集成令牌 (Integration Token)
3. 将集成连接到目标 Notion 工作区
## 方式一：npm/npx 快速部署
### 标准安装
通过 npm 全局安装或直接使用 npx 运行：
```bash
# 使用 npx 直接运行（推荐）
npx @n24q02m/better-notion-mcp
# 或全局安装
npm install -g @n24q02m/better-notion-mcp
```
资料来源：[server.json:11-17]()
### 环境变量配置
```bash
# stdio 模式必需
NOTION_TOKEN=secret_xxxxxxxxxxxx
# HTTP 模式可选
NOTION_CLIENT_ID=your_oauth_client_id
NOTION_CLIENT_SECRET=your_oauth_client_secret
REDIRECT_URI=http://localhost:3000/callback
```
## 方式二：Docker 部署
### stdio 模式
适用于本地开发环境，使用 Notion Token 直接认证：
```dockerfile
FROM oven/bun:1-alpine
WORKDIR /app
COPY . .
RUN bun install --frozen-lockfile
RUN bun run build
ENTRYPOINT ["bun", "dist/index.js"]
```
资料来源：[Dockerfile](https://github.com/n24q02m/better-notion-mcp/blob/main/Dockerfile)
#### 运行命令
```bash
docker run -it \
-e NOTION_TOKEN=secret_xxxxxxxxxxxx \
n24q02m/better-notion-mcp:latest
```
### HTTP 模式
适用于远程服务部署，支持 OAuth 2.1 认证：
```yaml
services:
notion-mcp:
image: n24q02m/better-notion-mcp:latest
ports:
- "3000:3000"
environment:
- NOTION_CLIENT_ID=${NOTION_CLIENT_ID}
- NOTION_CLIENT_SECRET=${NOTION_CLIENT_SECRET}
- REDIRECT_URI=http://localhost:3000/callback
- MCP_SERVER_PORT=3000
restart: unless-stopped
```
资料来源：[docker-compose.http.yml](https://github.com/n24q02m/better-notion-mcp/blob/main/docker-compose.http.yml)
#### 启动服务
```bash
# 启动 HTTP 服务
docker-compose -f docker-compose.http.yml up -d
# 查看日志
docker-compose -f docker-compose.http.yml logs -f
```
## 方式三：源码构建部署
### 克隆项目
```bash
git clone https://github.com/n24q02m/better-notion-mcp.git
cd better-notion-mcp
```
### 安装依赖
```bash
bun install
```
资料来源：[CLAUDE.md:12]()
### 构建
```bash
bun run build
```
构建命令说明：
- `tsc --build` - TypeScript 编译
- `esbuild` - CLI bundle 打包
资料来源：[CLAUDE.md:13-15]()
### 运行检查
```bash
# 运行检查（lint + 类型检查 + 测试）
bun run check
# 自动修复格式问题
bun run check:fix
```
资料来源：[CLAUDE.md:16-18]()
### 本地运行
```bash
# 设置环境变量
export NOTION_TOKEN=secret_xxxxxxxxxxxx
# 运行服务器
bun run start
```
## MCP 服务器配置
### server.json 配置说明
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.n24q02m/better-notion-mcp",
"description": "Markdown-first MCP server for Notion API with 9 composite tools and 39+ actions.",
"version": "2.34.3",
"packages": [
{
"registryType": "npm",
"identifier": "@n24q02m/better-notion-mcp",
"version": "2.34.3",
"runtimeHint": "npx",
"transport": {
"type": "stdio"
},
"environmentVariables": [
{
"description": "Notion integration token. Create at https://www.notion.so/my-integrations",
"isRequired": true,
"isSecret": true,
"name": "NOTION_TOKEN"
}
]
},
{
"registryType": "oci",
"identifier": "docker.io/n24q02m/better-notion-mcp:latest",
"runtimeHint": "docker",
"transport": {
"type": "stdio"
}
}
]
}
```
资料来源：[server.json:1-36]()
### MCP 客户端配置示例
#### Claude Desktop 配置
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["@n24q02m/better-notion-mcp"],
"env": {
"NOTION_TOKEN": "secret_xxxxxxxxxxxx"
}
}
}
}
```
#### Docker 模式配置
```json
{
"mcpServers": {
"notion": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN=secret_xxxxxxxxxxxx", "n24q02m/better-notion-mcp:latest"]
}
}
}
```
## OAuth 2.1 认证流程 (HTTP 模式)
```mermaid
sequenceDiagram
participant U as 用户
participant C as MCP 客户端
participant S as MCP 服务器
participant N as Notion API
C->>S: 请求访问
S->>U: 重定向到 Notion 授权页
U->>N: 授权登录
N->>U: 授权确认
N-->>S: 返回授权码 (code)
S->>N: 交换 token (PKCE)
N-->>S: 返回 access_token
S->>N: 调用 Notion API
N-->>S: 返回数据
S-->>C: 返回结果
```
### OAuth 配置步骤
1. 在 Notion 开发者平台创建 OAuth 应用
2. 配置回调地址：`http://localhost:3000/callback`（开发环境）
3. 设置环境变量：
- `NOTION_CLIENT_ID`
- `NOTION_CLIENT_SECRET`
- `REDIRECT_URI`
## 安全注意事项
### Token 安全
| 场景 | 建议 |
|------|------|
| 本地开发 | 使用 `NOTION_TOKEN` 环境变量 |
| 生产环境 | 使用 Docker Secrets 或外部密钥管理 |
| Git 提交 | 切勿将 token 提交到版本控制系统 |
### 网络安全
- HTTP 模式建议配合反向代理 (Nginx) 使用 HTTPS
- 限制 `REDIRECT_URI` 到可信域名
- 定期轮换 OAuth 凭证
### 链接安全
项目实现了 URL 安全检查机制：
```typescript
// javascript: 协议链接会被安全过滤
it('should sanitize javascript: links', () => {
const result = parseRichText('[Click me](javascript:alert(1))')
expect(result[0].text.link).toBeNull()
})
```
资料来源：[src/tools/helpers/markdown.security.test.ts:7-14]()
## 故障排查
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| `NOTION_TOKEN` 错误 | Token 无效或未设置 | 检查环境变量配置 |
| 连接超时 | 网络问题或防火墙 | 检查网络连接和端口 |
| OAuth 重定向失败 | 回调地址配置错误 | 确认 `REDIRECT_URI` 配置 |
| 权限不足 | 未将集成添加到页面 | 在 Notion 中分享页面给集成 |
### 调试模式
```bash
# 启用详细日志
DEBUG=* bun run start
# Docker 调试
docker run --rm -e DEBUG=* n24q02m/better-notion-mcp:latest
```
## 版本管理
项目使用 Renovate 进行依赖管理，版本更新会自动创建 Pull Request。
| 分支 | 版本策略 |
|------|----------|
| main | 稳定版 (v2.x.x) |
| beta | 测试版 (v2.x.x-beta.x) |
最新稳定版本：[v2.34.3](https://github.com/n24q02m/better-notion-mcp/releases/tag/v2.34.3)
资料来源：[社区动态](https://github.com/n24q02m/better-notion-mcp/releases)
## 相关文档
| 文档 | 内容 |
|------|------|
| [README.md](https://github.com/n24q02m/better-notion-mcp/blob/main/README.md) | 功能特性、工具列表 |
| [AGENTS.md](https://github.com/n24q02m/better-notion-mcp/blob/main/AGENTS.md) | AI Agent 集成指南 |
| [CONTRIBUTING.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CONTRIBUTING.md) | 开发贡献指南 |
---
## 开发指南
### 相关页面
相关主题：[源代码结构](#page-source-structure)
相关源码文件
以下源码文件用于生成本页说明：
- [CONTRIBUTING.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CONTRIBUTING.md)
- [AGENTS.md](https://github.com/n24q02m/better-notion-mcp/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
- [package.json](https://github.com/n24q02m/better-notion-mcp/blob/main/package.json)
- [renovate.json](https://github.com/n24q02m/better-notion-mcp/blob/main/renovate.json)
# 开发指南
better-notion-mcp 是一个 TypeScript MCP 服务器，用于与 Notion API 交互。本指南涵盖项目结构、开发环境配置、常用命令、测试规范以及代码贡献流程。
## 项目结构
```
better-notion-mcp/
├── src/
│ ├── init-server.ts # 服务器入口，环境变量验证
│ ├── credential-state.ts # 凭证状态机 + stdio 后备启动
│ ├── relay-schema.ts # 中继表单架构（Notion Token 字段）
│ ├── auth/ # OAuth 2.1 + PKCE、DCR、会话管理
│ ├── transports/ # stdio + http 传输处理
│ ├── docs/ # 作为 MCP 资源服务的 Markdown 文档
│ └── tools/
│ ├── registry.ts # 工具注册与路由
│ ├── composite/ # 每个域一个文件（pages、databases、blocks 等）
│ └── helpers/ # errors、markdown、richtext、pagination、properties
├── scripts/ # 构建脚本
├── build/ # 构建输出
├── tests/ # 测试文件（与源文件同目录放置）
└── bin/ # CLI 入口脚本
```
资料来源：[CONTRIBUTING.md:1-20]()
## 核心组件说明
### 工具系统架构
项目采用组合式工具（Composite Tools）设计，将多个原子端点合并为单一工具调用：
| 组件 | 职责 |
|------|------|
| `registry.ts` | 工具注册、参数校验、路由分发 |
| `composite/` | 按域实现工具逻辑（pages、databases、blocks 等） |
| `helpers/` | 共享工具函数（错误处理、Markdown 解析、富文本处理等） |
资料来源：[AGENTS.md:1-20]()
### 状态机管理
凭证状态管理使用三态状态机：
```mermaid
graph TD
A[awaiting_setup] -->|setup 完成| B[configured]
A -->|启动配置流程| C[setup_in_progress]
C -->|配置成功| B
C -->|配置失败| A
B -->|需要重新配置| A
```
- `awaiting_setup`：初始状态，等待用户配置
- `setup_in_progress`：配置进行中
- `configured`：配置完成，可正常操作
资料来源：[CLAUDE.md:1-15]()
## 开发环境配置
### 环境要求
| 运行时 | 版本要求 |
|--------|----------|
| Node.js | `>=24.16.0` |
| Python | `>=3.13.0 <3.14.0` |
| Java | `>=21.0.0 <22.0.0` |
资料来源：[renovate.json:1-50]()
### 依赖安装
```bash
bun install
```
使用 [bun](https://bun.sh) 作为包管理器和运行时。
资料来源：[CLAUDE.md:20-25]()
## 常用开发命令
| 命令 | 功能 |
|------|------|
| `bun run build` | TypeScript 编译 + esbuild CLI 打包 |
| `bun run check` | Biome 检查 + tsc 类型检查（CI 标准命令） |
| `bun run check:fix` | 自动修复 Biome 和 TypeScript 问题 |
| `bun run test` | 运行测试套件 |
| `bun run lint` | 运行 Biome lint |
| `bun run lint:fix` | 自动修复 lint 问题 |
| `bun run format` | 格式化代码 |
| `bun run format:check` | 检查代码格式 |
| `bun run type-check` | TypeScript 类型检查 |
资料来源：[CLAUDE.md:20-35]()
### Docker 相关命令
```bash
bun run docker:build # 构建 Docker 镜像
bun run docker:push # 推送镜像到仓库
bun run docker:run # 运行容器（需要 NOTION_TOKEN 环境变量）
```
资料来源：[package.json:1-50]()
## 代码规范
### Biome 配置
项目使用 Biome 进行代码检查和格式化，配置文件位于根目录：
- 包含 lint 规则和格式化选项
- 自动应用，无需手动配置
资料来源：[CONTRIBUTING.md:30-50]()
### Pre-commit 钩子
提交前自动执行以下检查：
1. `biome check --write` - Lint + 格式化
2. `tsc --noEmit` - 类型检查
3. `bun run test` - 运行测试
资料来源：[AGENTS.md:40-50]()
## 测试规范
### 测试文件位置
测试文件与源文件同目录放置：
```
src/tools/helpers/
├── markdown.ts
├── markdown.test.ts # 测试文件
├── richtext.ts
└── richtext.test.ts
```
资料来源：[AGENTS.md:25-30]()
### 测试配置
使用 Vitest 作为测试框架：
```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config'
```
资料来源：[AGENTS.md:30-40]()
### 安全测试
`markdown.security.test.ts` 文件包含 XSS 和恶意链接防护测试：
```typescript
describe('Security: Markdown Parsing Vulnerabilities', () => {
it('should sanitize javascript: links in rich text', () => {
// 验证 javascript: 协议链接被正确过滤
})
})
```
资料来源：[src/tools/helpers/markdown.security.test.ts:1-20]()
## 提交规范
### 提交信息格式
项目使用 Conventional Commits 规范：
```
():
```
**类型说明：**
| Type | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档变更 |
| `refactor` | 重构（不影响功能） |
| `test` | 测试相关 |
| `chore` | 工具/构建变更 |
资料来源：[AGENTS.md:45-55]()
## 依赖管理
### Renovate 配置
项目使用 Renovate 自动管理依赖更新：
| 依赖类型 | 更新策略 |
|----------|----------|
| `@n24q02m/mcp-core` | 非主版本更新 |
| GitHub Actions | 固定到 SHA（安全） |
| Python | 固定到 3.13.x |
| Node.js | 固定到 24.x |
| Java | 固定到 21.x LTS |
资料来源：[renovate.json:1-60]()
### 手动更新 mcp-core
当 mcp-core 发布新版本时，需要手动执行以下操作：
```bash
# TypeScript 端
1. 更新 package.json 中的 @n24q02m/mcp-core 版本
2. 运行 bun install 更新锁文件
# Python 端（如需要）
1. 更新 pyproject.toml 中的 n24q02m-mcp-core 版本
2. 重新生成锁文件
```
资料来源：[社区 Issue #769](https://github.com/n24q02m/better-notion-mcp/issues/769)
## 工具注册与路由
### 工具注册流程
所有工具在 `registry.ts` 中注册：
```typescript
{
name: 'content_convert',
description: 'Convert between markdown and Notion block JSON...',
annotations: {
title: 'Content Convert',
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false
},
inputSchema: {
type: 'object',
properties: {
direction: {
type: 'string',
enum: ['markdown-to-blocks', 'blocks-to-markdown']
},
content: { type: 'string' }
},
required: ['direction', 'content']
}
}
```
资料来源：[src/tools/registry.ts:1-50]()
### 工具注解说明
| 注解 | 含义 |
|------|------|
| `readOnlyHint` | 是否为只读操作 |
| `destructiveHint` | 是否为破坏性操作 |
| `idempotentHint` | 是否为幂等操作 |
| `openWorldHint` | 是否访问外部资源 |
## 文档编写规范
### JSDoc 注释
- 每个函数添加 `/** */` JSDoc 注释
- 引用 Notion API 端点
- 不使用 `@param`/`@returns` 标签，依赖 TypeScript 类型
资料来源：[AGENTS.md:35-45]()
### 文件级注释
每个模块顶部添加块注释描述模块用途：
```typescript
/**
* Rich Text Utilities
* Helpers for working with Notion's rich text format
*/
```
资料来源：[src/tools/helpers/richtext.ts:1-10]()
## 贡献流程
1. **Fork 仓库** 并创建功能分支
2. **开发实现**，遵循代码规范
3. **运行检查**：`bun run check`
4. **提交代码**，使用 Conventional Commits 格式
5. **创建 Pull Request**，等待代码审查
资料来源：[CONTRIBUTING.md:1-50]()
## 发布流程
版本号遵循语义化版本（SemVer）：
- 主版本号：不兼容的 API 变更
- 次版本号：向后兼容的功能新增
- 补丁版本号：向后兼容的问题修复
项目使用 python-semantic-release 进行自动版本管理和发布，通过 GitHub Actions 自动化流程执行。
资料来源：[renovate.json:20-30]()
---
如有问题，请提交 [Issue](https://github.com/n24q02m/better-notion-mcp/issues) 或参与社区讨论。
---
## 源代码结构
### 相关页面
相关主题：[开发指南](#page-development-guide), [复合工具详解](#page-composite-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/init-server.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/init-server.ts)
- [src/tools/registry.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/registry.ts)
- [src/tools/composite/pages.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/pages.ts)
- [src/tools/composite/blocks.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/composite/blocks.ts)
- [src/tools/helpers/markdown.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/markdown.ts)
- [src/tools/helpers/richtext.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/helpers/richtext.ts)
- [AGENTS.md](https://github.com/n24q02m/better-notion-mcp/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/n24q02m/better-notion-mcp/blob/main/CONTRIBUTING.md)
# 源代码结构
## 概述
better-notion-mcp 是一个 TypeScript 编写的 MCP (Model Context Protocol) 服务器，用于为 AI 代理提供 Notion API 的访问能力。项目采用 Markdown 优先的设计理念，将 Notion 的 JSON 块格式与人类可读的 Markdown 进行双向转换。 资料来源：[AGENTS.md]()
当前版本为 **v2.34.3**，支持双传输模式（stdio 和 HTTP），并依赖 `@n24q02m/mcp-core` 核心包实现 MCP 协议。社区近期关注点集中在依赖更新（mcp-core v1.17.1）和测试覆盖增强。 资料来源：[社区上下文 - v2.34.3](https://github.com/n24q02m/better-notion-mcp/releases/tag/v2.34.3)
---
## 目录结构
```
better-notion-mcp/
├── src/
│ ├── init-server.ts # 服务器入口，环境变量验证
│ ├── credential-state.ts # 凭证状态机 + stdio 回退机制
│ ├── relay-schema.ts # Relay 表单 schema（Notion token 字段）
│ ├── tools/
│ │ ├── registry.ts # 工具注册表 + 路由
│ │ ├── composite/ # 复合工具（每个领域一个文件）
│ │ │ ├── pages.ts # 页面 CRUD
│ │ │ ├── databases.ts # 数据库操作
│ │ │ ├── blocks.ts # 块操作
│ │ │ ├── users.ts # 用户查询
│ │ │ ├── workspace.ts # 工作区信息
│ │ │ ├── comments.ts # 评论管理
│ │ │ ├── content.ts # 内容格式转换
│ │ │ ├── file_uploads.ts # 文件上传
│ │ │ ├── setup.ts # 初始设置
│ │ │ └── help.ts # 帮助工具
│ │ └── helpers/
│ │ ├── errors.ts # 错误处理
│ │ ├── markdown.ts # Markdown ↔ Notion 块转换
│ │ ├── richtext.ts # 富文本工具
│ │ ├── pagination.ts # 分页处理
│ │ ├── properties.ts # 属性解析
│ │ └── security.ts # URL 安全检查
│ ├── auth/ # OAuth 2.1 + PKCE, DCR, 会话管理
│ ├── transports/ # stdio + HTTP 传输处理器
│ └── docs/ # 作为 MCP 资源服务的 Markdown 文档
├── scripts/ # 构建脚本
├── build/ # 构建输出
└── tests/ # 测试文件
```
资料来源：[CLAUDE.md]()
---
## 核心模块
### 服务器入口 (init-server.ts)
`init-server.ts` 是应用程序的入口点，负责：
- 验证必需的环境变量
- 初始化 MCP 服务器
- 注册所有工具和资源
服务器支持两种运行模式，由环境变量 `TRANSPORT_MODE` 控制：
| 模式 | 传输类型 | 说明 |
|------|----------|------|
| `stdio` | 标准输入/输出 | 本地运行，适合 CLI 工具 |
| `http` | HTTP Server-Sent Events | 远程部署，支持 OAuth |
资料来源：[CLAUDE.md]()
### 凭证状态机 (credential-state.ts)
凭证状态机管理服务器的生命周期状态：
```mermaid
graph TD
A[等待设置
awaiting_setup] -->|用户配置NOTION_TOKEN| B[设置中
setup_in_progress]
B -->|配置完成| C[已配置
configured]
C -->|配置失效| A
B -->|stdio回退| D[本地服务器
127.0.0.1:random]
D -->|检测到凭证| C
```
关键特性：
- **stdio 回退机制**：当配置不完整时，在 `127.0.0.1` 随机端口启动本地服务器
- 支持 OAuth 2.1 + PKCE 认证流程
- DCR (Dynamic Client Registration) 支持
资料来源：[CLAUDE.md]()
---
## 工具系统
### 工具注册表 (registry.ts)
`registry.ts` 是工具系统的核心，负责：
1. 定义所有 10 个复合工具的元数据
2. 处理工具调用的路由分发
3. 提供输入 schema 验证
#### 工具列表
| 工具名称 | 功能 | 操作数 |
|----------|------|--------|
| `pages` | 页面 CRUD | 8 |
| `databases` | 数据库操作 | 6 |
| `blocks` | 块操作 | 8 |
| `users` | 用户查询 | 3 |
| `workspace` | 工作区信息 | 4 |
| `comments` | 评论管理 | 3 |
| `content_convert` | 格式转换 | 2 |
| `file_uploads` | 文件上传 | 5 |
| `setup` | 初始设置 | 3 |
| `help` | 帮助工具 | 1 |
**总计：44 个操作动作**
资料来源：[src/tools/registry.ts](https://github.com/n24q02m/better-notion-mcp/blob/main/src/tools/registry.ts)
#### 工具注解
每个工具包含标准化注解，用于 AI 代理理解工具行为：
```typescript
annotations: {
title: '工具标题',
readOnlyHint: boolean, // 是否只读
destructiveHint: boolean, // 是否有破坏性
idempotentHint: boolean, // 是否幂等
openWorldHint: boolean // 是否访问外部世界
}
```
#### 工具路由
工具调用通过统一的分发函数处理：
```typescript
switch (input.action) {
case 'create': return await createAction(...)
case 'get': return await getAction(...)
// ... 其他 action
default:
throw new NotionMCPError(
`Unknown action: ${input.action}`,
'VALIDATION_ERROR',
'Supported actions: ...'
)
}
```
资料来源：[src/tools/composite/pages.ts:47-68]()
### 复合工具 (composite/)
每个领域一个文件，包含完整的操作逻辑。
#### pages.ts - 页面工具
支持 8 种操作：
| 操作 | 描述 | 必需参数 |
|------|------|----------|
| `create` | 创建页面 | `parent_id`, `title` |
| `get` | 获取页面 | `page_id` |
| `get_property` | 获取属性 | `page_id`, `property_id` |
| `update` | 更新页面 | `page_id` |
| `move` | 移动页面 | `page_id`, `parent_id` |
| `archive` | 归档页面 | `page_id` |
| `restore` | 恢复页面 | `page_id` |
| `duplicate` | 复制页面 | `page_id` |
资料来源：[src/tools/composite/pages.ts]()
#### blocks.ts - 块工具
处理页面内的块操作，包括块类型的验证和更新：
```typescript
const UPDATABLE_BLOCK_TYPES = new Set([
'paragraph', 'heading_1', 'heading_2', 'heading_3',
'bulleted_list_item', 'numbered_list_item', 'to_do',
'toggle', 'quote', 'callout', 'code'
])
```
对于不支持直接更新的块类型（如表格、列等），需要删除后重新创建。
资料来源：[src/tools/composite/blocks.ts]()
---
## 辅助工具 (helpers/)
### 错误处理 (errors.ts)
统一的错误处理机制，定义 `NotionMCPError` 类：
```typescript
class NotionMCPError extends Error {
code: string
suggestion: string
constructor(message, code, suggestion)
}
```
`withErrorHandling` 包装器自动捕获异常并格式化响应。
### Markdown 转换 (markdown.ts)
核心模块，实现 Markdown 与 Notion 块的双向转换：
```mermaid
graph LR
A[Markdown] -->|markdownToBlocks| B[Notion Block[]]
B -->|blocksToMarkdown| A
```
**支持的 Markdown 语法：**
- 标题（h1-h6）
- 段落和文本格式
- 有序/无序列表
- 待办事项 `[ ]` / `[x]`
- 代码块（带语言标识）
- 引用块
- 分隔线
- 提示块 `> [!NOTE]`
- 可折叠内容 ``
- 表格
- 图片和书签
- 嵌入内容
- 数学公式 `$$`
- 多列布局 `:::columns`
- 目录 `[toc]`
- 面包屑导航 `[breadcrumb]`
**内联格式：**
- 粗体 `**text**`
- 斜体 `*text*`
- 行内代码 `` `code` ``
- 删除线 `~~text~~`
- 链接 `[text](url)`
资料来源：[src/tools/helpers/markdown.ts:1-20]()
#### RichText 接口
```typescript
interface RichText {
type: 'text' | 'mention'
text: {
content: string
link?: { url: string } | null
}
mention?: {
page?: { id: string }
database?: { id: string }
}
annotations: {
bold: boolean
italic: boolean
strikethrough: boolean
underline: boolean
code: boolean
color: string
}
plain_text?: string
href?: string | null
}
```
#### 提及创建
`createMention` 函数创建页面/数据库提及元素：
```typescript
function createMention(
mentionData: RichText['mention'],
title: string,
formatting: { bold, italic, code, strikethrough }
): RichText
```
**注意**：提及元素不包含 `text` 属性，Notion API 会拒绝包含空 `text` 属性的提及请求。
资料来源：[src/tools/helpers/markdown.ts:44-56]()
### 富文本工具 (richtext.ts)
提供便捷函数创建富文本元素：
| 函数 | 效果 |
|------|------|
| `text(content)` | 普通文本 |
| `bold(content)` | 粗体 |
| `italic(content)` | 斜体 |
| `code(content)` | 行内代码 |
| `strikethrough(content)` | 删除线 |
| `underline(content)` | 下划线 |
**可用颜色值：**
`default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`
资料来源：[src/tools/helpers/richtext.ts]()
### 分页处理 (pagination.ts)
自动处理 Notion API 的游标分页，无需手动循环处理 `has_more` 和 `next_cursor`。
### 属性解析 (properties.ts)
将简单的 JavaScript 值转换为 Notion API 所需的嵌套格式：
```typescript
// 输入
{ "Name": "My Page", "Status": "In Progress" }
// 输出
{
"Name": { "title": [{ "text": { "content": "My Page" } }] },
"Status": { "select": { "name": "In Progress" } }
}
```
**支持的属性类型映射：**
| 数据模式 | 正确类型 | 常见错误 |
|----------|----------|----------|
| 固定分类 | `select` | `rich_text` |
| 多标签 | `multi_select` | `select` |
| 跨库引用 | `relation` | `rich_text` |
| 计算聚合 | `rollup` | `formula` |
| 布尔标志 | `checkbox` | `select` |
资料来源：[skills/organize-database/SKILL.md]()
### 安全检查 (security.ts)
`isSafeUrl` 函数用于验证 URL 安全性：
- 阻止 `javascript:` 协议链接
- 验证 URL 格式
- 防止 XSS 攻击
**测试覆盖：** 不安全的 URL 会被静默处理（返回 `null` 链接或回退到纯文本）。
资料来源：[src/tools/helpers/markdown.security.test.ts]()
---
## 传输层 (transports/)
支持两种传输模式：
### stdio 模式
- 通过标准输入/输出通信
- 适合本地 CLI 工具集成
- 使用 MCP SDK 直连模式
### HTTP 模式
- 基于 Server-Sent Events (SSE)
- 支持 OAuth 2.1 认证
- 适合远程部署
配置通过 `TRANSPORT_MODE` 环境变量切换。
资料来源：[CLAUDE.md]()
---
## 认证 (auth/)
认证模块实现：
- **OAuth 2.1**：现代 OAuth 流程
- **PKCE**：增强安全性
- **DCR**：动态客户端注册
- **会话管理**：令牌刷新和存储
---
## 文档资源 (docs/)
Markdown 文档作为 MCP 资源提供服务，AI 代理可以动态获取使用指南和 API 参考。
---
## 测试
测试文件与源代码共置：
```
src/tools/
├── composite/
│ ├── pages.ts
│ └── pages.test.ts # 页面工具测试
└── helpers/
├── markdown.ts
├── markdown.test.ts # Markdown 转换测试
└── markdown.security.test.ts # 安全测试
```
**测试框架：** Vitest
**CI 检查项：**
1. `biome check --write` - Lint + 格式化
2. `tsc --noEmit` - 类型检查
3. `bun run test` - 运行测试
资料来源：[CONTRIBUTING.md]()
---
## 构建系统
| 命令 | 说明 |
|------|------|
| `bun install` | 安装依赖 |
| `bun run build` | `tsc --build && esbuild CLI bundle` |
| `bun run check` | Biome + TypeScript 检查（CI 命令） |
| `bun run check:fix` | 自动修复格式问题 |
---
## 社区相关
### 依赖更新
项目使用 Renovate 进行依赖管理，社区经常收到 mcp-core 版本更新通知：
- **v1.17.1**（最新）：BearerMCPApp resource_metadata #260 修复
- 更新流程：修改 `package.json` 中的 `@n24q02m/mcp-core` 版本后运行 `bun install`
资料来源：[社区上下文 - Issue #769]()
### 质量认证
项目在 Agent Tool Intel 自动化质量分析中获得 **Grade A** 评级，表明代码质量、测试覆盖和文档完整性达到高标准。
---
## 参考链接
- 官方文档：https://mcp.n24q02m.com
- GitHub 仓库：https://github.com/n24q02m/better-notion-mcp
- mcp-core 仓库：https://github.com/n24q02m/mcp-core
---
---
## Doramagic 踩坑日志
项目：n24q02m/better-notion-mcp
摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：chore: bump @n24q02m/mcp-core to 1.17.0。
## 1. 安装坑 · 来源证据：chore: bump @n24q02m/mcp-core to 1.17.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore: bump @n24q02m/mcp-core to 1.17.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b0b34124b9c047ff9f1fe770e7a45276 | https://github.com/n24q02m/better-notion-mcp/issues/768 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：chore: bump @n24q02m/mcp-core to 1.17.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore: bump @n24q02m/mcp-core to 1.17.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9689093afc81461db714925d633f4320 | https://github.com/n24q02m/better-notion-mcp/issues/769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | README/documentation is current enough for a first validation pass.
## 4. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | last_activity_observed missing
## 5. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | no_demo; severity=medium
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | no_demo; severity=medium
## 7. 安全/权限坑 · 来源证据：Dependency Dashboard
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dependency Dashboard
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_85c84b0ec750481aa04b968b66e815aa | https://github.com/n24q02m/better-notion-mcp/issues/138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | issue_or_pr_quality=unknown
## 9. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | release_recency=unknown