# https://github.com/makenotion/notion-mcp-server 项目说明书
生成时间：2026-05-16 22:56:19 UTC
## 目录
- [项目介绍与版本说明](#page-1)
- [系统架构与模块设计](#page-2)
- [MCP 工具集详解](#page-3)
- [安装与客户端配置](#page-4)
- [HTTP 客户端与网络请求处理](#page-5)
- [认证机制与安全配置](#page-6)
- [传输层配置详解](#page-7)
- [本地开发与测试指南](#page-8)
- [从 v1.x 到 v2.0.0 迁移指南](#page-9)
- [OpenAPI 规范与文件上传](#page-10)
## 项目介绍与版本说明
### 相关页面
相关主题：[MCP 工具集详解](#page-3), [从 v1.x 到 v2.0.0 迁移指南](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)
- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)
- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
# 项目介绍与版本说明
## 项目概述
Notion MCP Server 是 Notion 官方提供的 MCP（Model Context Protocol）服务器，用于将 Notion API 作为 MCP 工具暴露给 AI 客户端使用。该项目通过自动生成的方式从 OpenAPI 规范创建 MCP 工具，无需手动编写工具代码。
**核心特性：**
- 自动从 OpenAPI 3.1.0 规范生成 MCP 工具
- 支持 stdio 和 Streamable HTTP 两种传输模式
- 使用 Notion API 版本 `2025-09-03`（Data Source Edition）
- 提供 22 个 MCP 工具（v2.0.0 版本）
- 支持 Cursor、Claude、Zed、GitHub Copilot CLI 等主流 MCP 客户端
资料来源：[README.md:1-50]()
---
## 系统架构
### 架构流程图
```mermaid
graph TD
A[scripts/notion-openapi.json] --> B[OpenAPI 3.1.0 规范]
B --> C[src/init-server.ts]
C --> D[创建 MCPProxy 实例]
D --> E[OpenAPIToMCPConverter]
E --> F[生成 MCP 工具定义]
F --> G[MCPProxy.setupHandlers]
G --> H[MCP SDK 注册工具]
H --> I[AI 客户端调用工具]
I --> J[HttpClient 执行 API 请求]
J --> K[Notion API]
subgraph 核心模块
E
F
G
end
```
### 目录结构
| 路径 | 说明 |
|------|------|
| `scripts/notion-openapi.json` | OpenAPI 3.1.0 规范定义文件（所有工具的源头） |
| `scripts/start-server.ts` | 服务器入口点，处理命令行参数 |
| `src/init-server.ts` | 服务器初始化，加载和验证规范 |
| `src/openapi-mcp-server/` | 核心 MCP 服务器实现 |
| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI 到 MCP 工具的转换逻辑 |
| `src/openapi-mcp-server/mcp/proxy.ts` | MCP 工具注册和执行 |
| `src/openapi-mcp-server/client/http-client.ts` | HTTP 请求执行 |
资料来源：[CLAUDE.md:1-30]()
### 工具生成流程
```mermaid
sequenceDiagram
participant AI as AI 客户端
participant MCP as MCP SDK
participant Proxy as MCPProxy
participant Parser as OpenAPIToMCPConverter
participant Client as HttpClient
participant API as Notion API
AI->>MCP: 调用工具
MCP->>Proxy: 分发请求
Proxy->>Parser: 解析参数
Parser->>Proxy: 反序列化参数
Proxy->>Client: 执行 HTTP 请求
Client->>API: API 调用
API-->>Client: 返回数据
Client-->>Proxy: 返回结果
Proxy-->>MCP: 标准化响应
MCP-->>AI: 返回结果
```
工具生成的五个关键步骤：
1. `OpenAPIToMCPConverter.convertToMCPTools()` 遍历所有路径和操作
2. 每个操作成为一个 MCP 工具（名称来自 `operationId`）
3. 参数 + requestBody → `inputSchema`
4. 响应 schema → `returnSchema`
5. `MCPProxy.setupHandlers()` 注册工具到 MCP SDK
资料来源：[CLAUDE.md:35-55]()
---
## 版本 2.0.0 重大变更
**版本 2.0.0 迁移到 Notion API 2025-09-03**，该版本引入了数据源（Data Source）作为数据库的主要抽象。
### 变更概览
```mermaid
graph LR
A[数据库工具 v1.x] -->|迁移| B[数据源工具 v2.0]
A1[post-database-query] --> B1[query-data-source]
A2[update-a-database] --> B2[update-a-data-source]
A3[create-a-database] --> B3[create-a-data-source]
```
### 移除的工具（3个）
| 旧工具（v1.x） | 替代工具（v2.0） |
|--------------|----------------|
| `post-database-query` | `query-data-source` |
| `update-a-database` | `update-a-data-source` |
| `create-a-database` | `create-a-data-source` |
资料来源：[README.md:120-140]()
### 新增的工具（7个）
| 工具名称 | 功能描述 |
|---------|---------|
| `query-data-source` | 使用过滤器和排序查询数据源（数据库） |
| `retrieve-a-data-source` | 获取数据源的元数据和 schema |
| `update-a-data-source` | 更新数据源属性 |
| `create-a-data-source` | 创建新的数据源 |
| `list-data-source-templates` | 列出数据源中的可用模板 |
| `move-page` | 将页面移动到不同的父位置 |
| `retrieve-a-database` | 获取数据库元数据，包括数据源 ID 列表 |
资料来源：[README.md:145-165]()
### 参数变更
| 变更类型 | v1.x | v2.0 |
|---------|------|------|
| 数据库操作参数 | `database_id` | `data_source_id` |
| 搜索过滤器值 | `["page", "database"]` | `["page", "data_source"]` |
| 页面创建父级 | 仅 `page_id` | `page_id` 或 `database_id` |
资料来源：[README.md:170-185]()
---
## 迁移指南
### 是否需要迁移？
**无需代码更改。** MCP 工具在服务器启动时自动被发现。升级到 v2.0.0 后，AI 客户端将自动看到新的工具名称和参数。旧的数据库工具将不再可用。
### 迁移对照表
| 旧工具（v1.x） | 新工具（v2.0） | 参数变更 |
|--------------|---------------|---------|
| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |
| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |
| `create-a-database` | `create-a-data-source` | 无变化（使用 `parent.page_id`） |
> **注意：** `retrieve-a-database` 仍然可用，返回数据库元数据包括数据源 ID 列表。使用 `retrieve-a-data-source` 获取特定数据源的 schema 和属性。
资料来源：[README.md:190-210]()
### 工具总数
- **v1.x: 19 个工具**
- **v2.0: 22 个工具**（新增 7 个，移除 3 个，保留 1 个兼容工具）
---
## 环境配置
### 环境变量
| 变量名 | 说明 | 优先级 |
|-------|------|--------|
| `NOTION_TOKEN` | Notion 集成令牌（推荐） | - |
| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 头信息 | 替代方案 |
| `AUTH_TOKEN` | HTTP 传输认证令牌 | CLI 参数优先 |
资料来源：[README.md:55-80]()
### 传输模式
| 模式 | 说明 | 默认端口 |
|------|------|---------|
| `stdio` | 标准输入输出传输（默认） | - |
| `http` | Streamable HTTP 传输 | 3000 |
**命令行参数：**
```bash
--transport # 传输类型：'stdio' 或 'http'
--port # HTTP 服务器端口（默认：3000）
--auth-token # HTTP 传输认证令牌
--disable-auth # 禁用认证
--help, -h # 显示帮助信息
```
资料来源：[scripts/start-server.ts:1-30]()
---
## 参数反序列化机制
MCPProxy 中的 `deserializeParams` 函数处理参数反序列化：
```mermaid
flowchart TD
A[接收参数对象] --> B{参数类型判断}
B -->|string| C{是否 JSON 字符串}
B -->|array| D{遍历数组成员}
B -->|其他| G[直接传递]
C -->|是| E[JSON.parse 解析]
C -->|否| G
E --> F{解析结果是否为对象}
F -->|是| H[递归反序列化]
F -->|否| G
D --> D1{成员是否为字符串}
D1 -->|是| E
D1 -->|否| D2[保持原值]
H --> I[返回反序列化结果]
G --> I
D2 --> I
```
该机制确保嵌套的 JSON 字符串参数能够正确反序列化，防止参数传递错误。
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-60]()
---
## 快速开始
### 安装与配置
```bash
# 方式一：使用 npm
npx -y @notionhq/notion-mcp-server
# 方式二：本地开发
npm install
npm run build
npm link # 创建全局符号链接
```
### MCP 客户端配置示例
**Cursor/Claude 配置文件**（`~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
资料来源：[README.md:100-130]()
### 构建与测试
| 命令 | 说明 |
|------|------|
| `npm run build` | TypeScript 编译 + CLI 打包 |
| `npm test` | 运行 vitest 测试 |
| `npm run dev` | 启动开发服务器（热重载） |
资料来源：[CLAUDE.md:20-25]()
---
## 相关链接
- 官方文档：https://developers.notion.com/reference/intro
- MCP 协议规范：https://spec.modelcontextprotocol.io/
- 问题反馈：https://github.com/makenotion/notion-mcp-server/issues
---
## 系统架构与模块设计
### 相关页面
相关主题：[项目介绍与版本说明](#page-1), [HTTP 客户端与网络请求处理](#page-5), [认证机制与安全配置](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/openapi-mcp-server/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/index.ts)
- [src/openapi-mcp-server/auth/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts)
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)
# 系统架构与模块设计
## 概述
Notion MCP Server 是一个实现 MCP（Model Context Protocol）协议的服务器，用于将 Notion API 暴露为 MCP 工具供 AI 代理使用。该项目采用自动生成架构，通过 OpenAPI 规范定义所有工具，无需为每个 API 端点编写独立代码。
### 核心设计理念
| 设计原则 | 说明 |
|---------|------|
| 规范驱动 | 所有工具从 `notion-openapi.json` 自动生成 |
| 零手动维护 | 新增 API 端点只需修改 OpenAPI 规范 |
| 多协议兼容 | 支持 STDIO 和 HTTP 两种传输协议 |
| 标准化转换 | OpenAPI → MCP / OpenAI / Anthropic 工具格式 |
## 整体架构
```mermaid
graph TD
subgraph "数据源层"
A["scripts/notion-openapi.json
OpenAPI 3.1.0 规范"]
end
subgraph "核心处理层"
B["init-server.ts
服务器初始化"]
C["parser.ts
OpenAPI → MCP 转换器"]
D["proxy.ts
MCP 工具代理"]
end
subgraph "传输层"
E["STDIO 传输"]
F["HTTP/Streamable 传输"]
end
subgraph "外部调用"
G["AI 客户端
Cursor/Claude/Copilot"]
end
A --> B
B --> C
C --> D
D --> E
D --> F
E --> G
F --> G
style A fill:#e1f5fe
style C fill:#fff3e0
style D fill:#e8f5e9
```
## 模块详解
### 1. 入口模块 (scripts/start-server.ts)
服务器启动入口，负责命令行参数解析和传输协议选择。
#### 支持的参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--transport` | string | `stdio` | 传输类型：`stdio` 或 `http` |
| `--port` | number | `3000` | HTTP 服务器端口 |
| `--auth-token` | string | 自动生成 | HTTP 传输的认证令牌 |
| `--disable-auth` | boolean | `false` | 禁用认证 |
| `--help` | - | - | 显示帮助信息 |
#### 环境变量
| 变量名 | 说明 |
|--------|------|
| `NOTION_TOKEN` | Notion 集成令牌（推荐） |
| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 请求头 |
| `AUTH_TOKEN` | HTTP 传输认证令牌（备选） |
资料来源：[scripts/start-server.ts:1-50]()
### 2. 服务器初始化 (src/init-server.ts)
负责加载 OpenAPI 规范、验证配置并创建 MCP 服务器实例。
#### 初始化流程
```mermaid
sequenceDiagram
participant 启动脚本
participant init-server
participant MCPProxy
participant OpenAPI规范
启动脚本->>init-server: 加载 OpenAPI 规范
init-server->>MCPProxy: 创建代理实例
MCPProxy->>OpenAPI规范: 解析端点
MCPProxy->>MCPProxy: 注册工具处理器
init-server->>启动脚本: 返回服务器实例
```
资料来源：[src/init-server.ts](), [src/openapi-mcp-server/mcp/proxy.ts:1-50]()
### 3. OpenAPI 解析器 (src/openapi-mcp-server/openapi/parser.ts)
核心转换模块，将 OpenAPI 3.1.0 规范转换为 MCP 工具定义。
#### 主要功能
- 解析 OpenAPI 路径和操作
- 转换 JSON Schema 参数定义
- 生成 MCP 工具的 `inputSchema` 和 `returnSchema`
- 支持多种输出格式：MCP、OpenAI ChatCompletion、Anthropic Tool
#### 转换方法
| 方法 | 输出格式 | 用途 |
|------|----------|------|
| `convertToMCPTools()` | MCP Tool[] | MCP 协议标准格式 |
| `convertToOpenAITools()` | ChatCompletionTool[] | OpenAI 函数调用 |
| `convertToAnthropicTools()` | Tool[] | Anthropic Claude 工具 |
#### Schema 转换处理
```typescript
// 处理类型映射关系
- OpenAPI binary → JSON Schema uri-reference
- object 类型 → 保留 properties 和 additionalProperties
- array 类型 → 递归转换 items
- oneOf/anyOf/allOf → 递归处理联合类型
```
资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-100]()
### 4. MCP 代理模块 (src/openapi-mcp-server/mcp/proxy.ts)
负责 MCP 工具的注册、路由和执行。
#### 核心组件
| 组件 | 职责 |
|------|------|
| `HttpClient` | 发送 HTTP 请求到 Notion API |
| `OpenAPIToMCPConverter` | 工具定义转换 |
| `MCPProxy` | 工具注册与调用处理 |
#### 工具命名规则
- 工具名称来源：`operationId` 字段
- 长度限制：截断至 64 字符
- 显示格式：Title Case（如 `RetrieveADatabase`）
#### 请求处理流程
```mermaid
graph LR
A["MCP 调用请求"] --> B["解析工具名称"]
B --> C["查找 OpenAPI 操作"]
C --> D["提取参数"]
D --> E["构造 HTTP 请求"]
E --> F["发送请求到 Notion API"]
F --> G["返回响应结果"]
```
#### 工具注解
| HTTP 方法 | 注解 | 说明 |
|-----------|------|------|
| GET | `readOnlyHint: true` | 只读操作 |
| POST/PATCH/DELETE | `destructiveHint: true` | 可能修改数据的操作 |
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:50-150]()
### 5. HTTP 客户端 (src/openapi-mcp-server/client/http-client.ts)
负责执行实际的 API 调用。
#### 请求构造
```typescript
// 参数分类处理
1. 路径参数 (path) → URL 路径占位符
2. 查询参数 (query) → URL 查询字符串
3. 请求体 (body) → JSON 请求体
4. 表单数据 (formData) → multipart/form-data
```
#### 认证头处理
默认从环境变量读取认证信息：
- `OPENAPI_MCP_HEADERS`：JSON 格式的完整请求头
- 自动注入 `Authorization` 和 `Notion-Version`
资料来源：[src/openapi-mcp-server/client/http-client.ts:1-100]()
### 6. 认证模块 (src/openapi-mcp-server/auth/index.ts)
处理 HTTP 传输的 Bearer Token 认证。
#### 认证选项
| 方式 | 优先级 | 说明 |
|------|--------|------|
| 命令行 `--auth-token` | 最高 | 显式指定令牌 |
| 环境变量 `AUTH_TOKEN` | 中 | 环境配置 |
| 自动生成 | 最低 | 开发模式自动创建 |
#### 认证流程
```mermaid
graph TD
A["HTTP 请求到达"] --> B{"检查 --disable-auth"}
B -->|是| C["跳过认证"]
B -->|否| D["提取 Authorization 头"]
D --> E{"验证 Bearer Token"}
E -->|通过| F["处理请求"]
E -->|失败| G["返回 401 错误"]
```
资料来源：[src/openapi-mcp-server/auth/index.ts]()
## 数据流架构
```mermaid
flowchart LR
subgraph 用户层
A["AI 客户端"]
B["Notion Token"]
end
subgraph MCP服务器
C["STDIO/HTTP 接收"]
D["工具列表请求"]
E["工具调用请求"]
F["工具解析"]
G["HTTP 执行器"]
end
subgraph Notion API
H["Notion API v2025-09-03"]
end
A -->|MCP 协议| C
B -->|认证| G
C --> D
C --> E
E --> F
F --> G
G -->|HTTP/REST| H
H -->|JSON 响应| G
G -->|MCP 响应| A
```
## 传输协议
### STDIO 模式
默认传输方式，适用于本地集成。
```bash
npx @notionhq/notion-mcp-server
```
### HTTP/Streamable 模式
适用于远程部署和分布式架构。
```bash
npx @notionhq/notion-mcp-server --transport http --port 3000
```
| 特性 | STDIO | HTTP |
|------|-------|------|
| 连接方式 | 标准输入/输出 | HTTP 长连接 |
| 认证 | 无 | Bearer Token |
| 适用场景 | 本地 IDE | 远程服务 |
| 状态管理 | 无状态 | Session 支持 |
## 扩展机制
### 添加新 API 端点
仅需修改 `scripts/notion-openapi.json`，工具将自动生成：
```mermaid
graph LR
A["修改 notion-openapi.json"] --> B["添加/修改路径"]
B --> C["定义 operationId"]
C --> D["npm run build"]
D --> E["工具自动可用"]
```
### 支持的工具格式
| 格式 | 生成方法 | 使用场景 |
|------|----------|----------|
| MCP Tool | `convertToMCPTools()` | MCP SDK 原生支持 |
| OpenAI Function | `convertToOpenAITools()` | GPT 函数调用 |
| Anthropic Tool | `convertToAnthropicTools()` | Claude 工具使用 |
## 依赖关系图
```mermaid
graph TD
package.json --> express
package.json --> @modelcontextprotocol-sdk
package.json --> openapi-types
express --> src/init-server.ts
@modelcontextprotocol-sdk --> src/openapi-mcp-server/mcp/proxy.ts
src/init-server.ts --> src/openapi-mcp-server/mcp/proxy.ts
src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/openapi/parser.ts
src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/client/http-client.ts
src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/auth/index.ts
src/openapi-mcp-server/openapi/parser.ts --> openapi-types
scripts/start-server.ts --> src/init-server.ts
```
## 关键设计决策
### 1. 规范即代码
通过将 OpenAPI 规范作为唯一的工具定义来源，实现了：
- 单点维护
- 文档与实现同步
- 多格式工具自动导出
### 2. 分层架构
| 层级 | 职责 | 隔离性 |
|------|------|--------|
| 传输层 | 协议适配 (STDIO/HTTP) | 可替换 |
| 协议层 | MCP SDK 封装 | 核心依赖 |
| 转换层 | OpenAPI → MCP 转换 | 可复用 |
| 执行层 | HTTP 请求执行 | 可测试 |
### 3. 认证安全
HTTP 传输强制使用 Bearer Token 认证，支持：
- 自动生成（开发模式）
- 环境变量配置（生产推荐）
- 命令行显式指定（最高优先级）
## 总结
Notion MCP Server 采用现代化的分层架构设计，通过 OpenAPI 规范驱动实现零手动维护的工具生成机制。核心模块各司其职：解析器负责格式转换、代理负责工具注册、HTTP 客户端负责实际请求执行、认证模块负责安全控制。这种设计既保证了代码的可维护性，又为未来扩展提供了良好的基础。
---
## MCP 工具集详解
### 相关页面
相关主题：[项目介绍与版本说明](#page-1), [系统架构与模块设计](#page-2), [从 v1.x 到 v2.0.0 迁移指南](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json) - OpenAPI 3.1.0 规范定义所有 Notion API 端点
- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts) - OpenAPI 到 MCP 工具转换器
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts) - MCP 工具注册与执行代理
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts) - HTTP 客户端实现
- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts) - 服务器初始化逻辑
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts) - 服务器入口点
- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json) - 项目依赖与构建配置
# MCP 工具集详解
## 概述
MCP 工具集是 Notion MCP Server 的核心功能模块，它将 Notion OpenAPI 规范自动转换为 Model Context Protocol (MCP) 工具，使 AI 助手能够直接调用 Notion API 进行操作。
该系统的设计理念是**仅需修改 OpenAPI 规范文件**，即可自动生成对应的 MCP 工具，无需手动编写代码。工具的命名、参数定义、响应模式等全部从 OpenAPI 规范派生。
资料来源：[CLAUDE.md]()
## 架构总览
### 核心数据流
```mermaid
graph TD
A["scripts/notion-openapi.json
OpenAPI 3.1.0 规范"] --> B["src/init-server.ts
加载与验证规范"]
B --> C["OpenAPIToMCPConverter
openapi/parser.ts"]
C --> D["MCPProxy
mcp/proxy.ts"]
D --> E["HTTP Client
client/http-client.ts"]
E --> F["Notion API
api.notion.com"]
C -.->|convertToMCPTools| G["MCP 工具定义"]
C -.->|convertToOpenAITools| H["OpenAI 工具格式"]
C -.->|convertToAnthropicTools| I["Anthropic 工具格式"]
```
### 关键组件
| 组件 | 文件路径 | 职责 |
|------|---------|------|
| OpenAPI 规范 | `scripts/notion-openapi.json` | 定义所有 API 端点的规范来源 |
| 工具转换器 | `src/openapi-mcp-server/openapi/parser.ts` | 将 OpenAPI 转换为 MCP 工具格式 |
| 工具代理 | `src/openapi-mcp-server/mcp/proxy.ts` | 注册工具句柄并执行调用 |
| HTTP 客户端 | `src/openapi-mcp-server/client/http-client.ts` | 执行实际的 API 请求 |
| 服务器初始化 | `src/init-server.ts` | 加载规范并创建 MCPProxy 实例 |
资料来源：[CLAUDE.md]()
## OpenAPI 到 MCP 工具转换机制
### 转换流程
```mermaid
sequenceDiagram
participant OpenAPI as OpenAPI 规范
participant Parser as OpenAPIToMCPConverter
participant MCP as MCPProxy
OpenAPI->>Parser: 加载规范文件
Parser->>Parser: 解析 paths 和 operations
Parser->>Parser: convertOperationToJsonSchema()
Parser->>Parser: extractResponseType()
Parser->>Parser: convertToMCPTools()
Parser-->>MCP: { tools, openApiLookup, zip }
```
### 核心转换方法
`OpenAPIToMCPConverter` 类提供三种工具格式转换方法：
资料来源：[src/openapi-mcp-server/openapi/parser.ts:120-180]()
#### 1. `convertToMCPTools()`
生成原生 MCP 工具定义，返回包含三个属性的对象：
```typescript
{
tools: Record, // 按 API 名称分组的工具
openApiLookup: Record, // 操作查找表
zip: Record // 配对的 OpenAPI 与 MCP 工具
}
```
资料来源：[src/openapi-mcp-server/openapi/parser.ts:85-140]()
#### 2. `convertToOpenAITools()`
转换为 OpenAI ChatCompletion 工具格式：
```typescript
{
type: 'function',
function: {
name: operation.operationId,
description: 描述文本,
parameters: JSON Schema
}
}
```
资料来源：[src/openapi-mcp-server/openapi/parser.ts:143-165]()
#### 3. `convertToAnthropicTools()`
转换为 Anthropic Claude 工具格式：
```typescript
{
name: operation.operationId,
description: 描述文本,
input_schema: JSON Schema
}
```
资料来源：[src/openapi-mcp-server/openapi/parser.ts:168-190]()
### Schema 转换细节
#### 类型映射规则
| OpenAPI 类型 | JSON Schema 类型 | 特殊处理 |
|-------------|-----------------|---------|
| `string` | `string` | - |
| `integer` | `integer` | - |
| `number` | `number` | - |
| `boolean` | `boolean` | - |
| `array` | `array` | 包含 items 转换 |
| `object` | `object` | 包含 properties 和 additionalProperties |
| `binary` | `uri-reference` | 添加"本地文件绝对路径"描述 |
资料来源：[src/openapi-mcp-server/openapi/parser.ts:30-90]()
#### 复合类型处理
对于包含 `oneOf`、`anyOf`、`allOf` 的复杂 Schema，系统采用以下策略：
```typescript
// 如果 schema 包含 oneOf/anyOf/allOf 或是数组
if ('anyOf' in schema || 'oneOf' in schema || 'allOf' in schema) {
return { anyOf: [schema, { type: 'string' }] }
}
```
这确保了参数可以接受原始值或 JSON 字符串形式。
资料来源：[src/openapi-mcp-server/openapi/parser.ts:260-280]()
#### 响应 Schema 提取
```mermaid
graph LR
A["responses 对象"] --> B{"查找成功响应"}
B -->|"200/201/202/204"| C["解析 content"]
B -->|"无匹配"| D["返回 null"]
C --> E{"application/json?"}
E -->|是| F["转换 schema
添加 $defs"]
E -->|否| G["处理二进制格式"]
```
系统按优先级 `200 → 201 → 202 → 204` 查找成功响应，并从 `application/json` content 中提取响应 schema。
资料来源：[src/openapi-mcp-server/openapi/parser.ts:290-320]()
## 工具命名规范
### 命名来源
工具名称直接取自 OpenAPI 规范的 `operationId` 字段：
```json
{
"operationId": "retrieve-a-database"
}
```
转换后生成工具名：`Retrieve-A-Database`
资料来源：[CLAUDE.md]()
### 名称处理规则
| 处理步骤 | 说明 |
|---------|------|
| 1. 截断 | 名称被截断至 64 字符以内 |
| 2. 标题化 | 转换为 Title Case 格式 |
| 3. 分组 | 按 API 名称分组到不同的方法集合 |
## 工具注册与执行
### MCPProxy 架构
```mermaid
classDiagram
class MCPProxy {
+mcpServer: Server
+openApiSpec: OpenAPIV3.Document
+openApiLookup: Record
+setupHandlers() void
+executeTool(name, args) Promise
}
class HTTPClient {
+executeOperation(operationId, params) Promise
}
MCPProxy --> HTTPClient : 使用
```
### 参数反序列化机制
MCP 协议在传输过程中会将复杂参数序列化为字符串。`deserializeParams()` 函数负责反序列化：
```typescript
function deserializeParams(params: Record): Record
```
**处理逻辑：**
1. 检测字符串值是否以 `{`/`[` 开头并以 `}`/`]` 结尾
2. 尝试使用 `JSON.parse()` 解析
3. 对嵌套对象递归反序列化
4. 对数组中的 JSON 字符串项逐个处理
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:10-60]()
### 工具执行流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Proxy as MCPProxy
participant Deserializer as deserializeParams
participant HTTP as HTTPClient
participant API as Notion API
Client->>Proxy: 调用工具 "retrieve-a-database"
Proxy->>Deserializer: 反序列化参数
Deserializer-->>Proxy: 处理后的参数对象
Proxy->>HTTP: operationId + 参数
HTTP->>API: GET /v1/databases/{database_id}
API-->>HTTP: 200 OK + 数据库数据
HTTP-->>Proxy: API 响应
Proxy-->>Client: MCP 响应结果
```
## HTTP 客户端实现
### 请求构建流程
`HTTPClient` 负责将工具调用转换为实际的 HTTP 请求：
资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50]()
| 处理步骤 | 操作 |
|---------|------|
| 1 | 从 `operation.parameters` 提取 path 和 query 参数 |
| 2 | 识别 `application/json` 或 `multipart/form-data` 请求体 |
| 3 | 设置相应的 `Content-Type` header |
| 4 | 调用 OpenAPI 客户端生成的操作函数 |
| 5 | 转换响应 headers 为标准 Headers 对象 |
### 请求体处理
```typescript
// 根据是否有请求体设置 headers
const hasBody = Object.keys(bodyParams).length > 0
const headers = formData
? formData.getHeaders()
: { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }
// 调用格式：第一个参数为 URL 参数，第二个为 body 参数
const response = await operationFn(urlParameters, hasBody ? bodyParams : undefined, requestConfig)
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:50-80]()
## 服务器传输模式
### 支持的传输类型
| 传输模式 | 说明 | 默认端口 |
|---------|------|---------|
| `stdio` | 标准输入/输出流 | N/A |
| `http` | Streamable HTTP 传输 | 3000 |
资料来源：[scripts/start-server.ts:20-40]()
### 命令行参数
| 参数 | 说明 |
|------|------|
| `--transport ` | 指定传输类型 (`stdio` 或 `http`) |
| `--port ` | HTTP 服务器端口 (默认: 3000) |
| `--auth-token ` | HTTP 传输认证的 Bearer token |
| `--disable-auth` | 禁用 HTTP 传输的 Bearer token 认证 |
| `--help`, `-h` | 显示帮助信息 |
### 环境变量配置
| 变量 | 说明 | 优先级 |
|------|------|-------|
| `NOTION_TOKEN` | Notion 集成密钥 (推荐) | 高 |
| `OPENAPI_MCP_HEADERS` | JSON 格式的 API headers | 低 |
`--auth-token` 参数优先于 `AUTH_TOKEN` 环境变量。
资料来源：[scripts/start-server.ts:60-100]()
## API 版本支持
服务器使用 Notion API 版本 **`2025-09-03`** (Data Source Edition)。
规范文件同时包含两类端点：
| 端点类型 | 示例路径 |
|---------|---------|
| 传统数据库端点 | `/v1/databases/{database_id}` |
| 数据源端点 | `/v1/data_sources/{data_source_id}` |
资料来源：[CLAUDE.md]()
## 使用示例
### 工具调用示例
当用户发出以下指令时：
```
Add a page titled "Notion MCP" to page "Development"
```
AI 助手会自动规划并调用以下 API 操作：
1. `v1/search` - 查找名为 "Development" 的页面
2. `v1/pages` - 创建新页面
### 工具引用方式
工具支持以下引用方式：
| 方式 | 示例 |
|------|------|
| 页面标题 | `Comment "Hello MCP" on page "Getting started"` |
| 页面 ID | `Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2` |
## 测试框架
### 测试配置
测试文件位于源文件同级的 `__tests__` 目录中，使用 Vitest 测试框架：
```bash
npm test # 运行所有测试
npm run test:watch # 监视模式
npm run test:coverage # 生成覆盖率报告
```
### 依赖包
| 包名 | 用途 |
|------|------|
| `@modelcontextprotocol/sdk` | MCP 协议实现 |
| `axios` | HTTP 请求处理 |
| `openapi-client-axios` | OpenAPI 客户端生成 |
| `zod` | Schema 验证 |
资料来源：[package.json]()
## 扩展机制
### 添加新端点
要添加新的 API 端点，只需修改 `scripts/notion-openapi.json` 文件，无需修改其他代码：
1. 在 `paths` 对象中添加新的端点定义
2. 设置唯一的 `operationId`
3. 定义 parameters 和 requestBody
4. 定义 response schema
系统会自动：
- 生成新的 MCP 工具定义
- 更新工具注册表
- 处理参数序列化和反序列化
资料来源：[CLAUDE.md]()
### 自定义 Header 配置
对于需要自定义 headers 的高级用例，可通过 `OPENAPI_MCP_HEADERS` 环境变量传入：
```json
{
"Authorization": "Bearer ntn_****",
"Notion-Version": "2025-09-03"
}
---
## 安装与客户端配置
### 相关页面
相关主题：[传输层配置详解](#page-7), [本地开发与测试指南](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
- [docker-compose.yml](https://github.com/makenotion/notion-mcp-server/blob/main/docker-compose.yml)
- [Dockerfile](https://github.com/makenotion/notion-mcp-server/blob/main/Dockerfile)
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
# 安装与客户端配置
本文档详细说明 Notion MCP Server 的安装方式、Docker 部署方案以及各主流 AI 客户端的配置方法。
## 概述
Notion MCP Server 是官方提供的 Model Context Protocol (MCP) 服务器，用于将 Notion API 以 MCP 工具的形式暴露给 AI 客户端。项目采用 TypeScript 开发，支持两种传输模式（STDIO 和 Streamable HTTP）和多种认证方式。
核心依赖包括：
- `@modelcontextprotocol/sdk` (^1.25.1) - MCP 协议实现
- `axios` (^1.8.4) - HTTP 请求处理
- `express` (^4.21.2) - HTTP 传输层支持
- `zod` (3.24.1) - 参数验证
资料来源：[package.json:1-50]()
## 环境准备
### 前置条件
| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | 18+ | 支持原生 Headers 类 |
| npm | 9+ | 包管理 |
| Docker | 20+ | Docker 部署方式 |
> **注意**：Headers 类在 Node.js 18+ 才原生支持，较低版本使用 polyfill 实现。
资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-10]()
### Notion 集成配置
1. 访问 [Notion 开发者平台](https://www.notion.so/profile/integrations) 创建内部集成或选择已有集成
2. 复制集成的 Secret Token（格式：`ntn_****`）
3. 访问目标页面，点击右上角「...」→「连接」→「连接到集成」
## 安装方式
### NPM 安装（推荐）
NPM 安装是使用 Notion MCP Server 最便捷的方式，适用于 Cursor、Claude Desktop、Zed 等主流 AI 客户端。
```bash
# 使用 NOTION_TOKEN（推荐）
npx -y @notionhq/notion-mcp-server
# 或使用 OPENAPI_MCP_HEADERS（高级场景）
npx -y @notionhq/notion-mcp-server --transport http
```
资料来源：[README.md:80-95]()
### Docker 安装
#### 选项一：使用官方 Docker Hub 镜像
官方镜像 `mcp/notion` 托管在 Docker Hub，无需本地构建即可快速部署。
```bash
# 拉取官方镜像
docker pull mcp/notion
# 使用 NOTION_TOKEN 运行
docker run --rm -i -e NOTION_TOKEN="ntn_****" mcp/notion
```
资料来源：[README.md:140-155]()
#### 选项二：本地构建 Docker 镜像
如果需要自定义配置或使用最新代码，可选择本地构建：
```bash
# 构建镜像
docker compose build
# 或使用 docker build
docker build -t notion-mcp-server .
```
构建配置如下：
```dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
CMD ["node", "bin/cli.mjs"]
```
资料来源：[Dockerfile:1-10]()
```yaml
services:
notion-mcp-server:
build: .
container_name: notion-mcp-server
environment:
- NOTION_TOKEN=${NOTION_TOKEN}
stdin_open: true
tty: true
```
资料来源：[docker-compose.yml:1-15]()
## 客户端配置
### 配置架构图
```mermaid
graph TD
A[AI 客户端] --> B[MCP 配置文件]
B --> C{传输模式}
C -->|STDIO| D[notion-mcp-server 进程]
C -->|HTTP| E[notion-mcp-server HTTP 服务]
D --> F[Notion API]
E --> F
```
### Cursor / Claude Desktop
#### 配置路径
- **Cursor**: `~/.cursor/mcp.json`
- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
#### 使用 NOTION_TOKEN（推荐）
```json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
#### 使用 OPENAPI_MCP_HEADERS（高级场景）
```json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
}
}
}
}
```
资料来源：[README.md:95-125]()
### Zed 编辑器
Zed 通过 `settings.json` 的 `context_servers` 配置项支持 MCP 服务器。
```json
{
"context_servers": {
"some-context-server": {
"command": {
"path": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
}
},
"settings": {}
}
}
}
```
资料来源：[README.md:75-88]()
### GitHub Copilot CLI
#### 交互式配置
```bash
/mcp add
```
#### 手动配置
编辑 `~/.copilot/mcp-config.json`：
```json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
资料来源：[README.md:88-103]()
### Docker 环境下的客户端配置
#### 使用 Docker Hub 镜像
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"NOTION_TOKEN",
"mcp/notion"
],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
#### 本地构建镜像
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"NOTION_TOKEN=ntn_****",
"notion-mcp-server"
]
}
}
}
```
资料来源：[README.md:155-185]()
## 传输模式与认证
### STDIO 传输模式（默认）
STDIO 是默认传输模式，通过标准输入输出与客户端通信：
```bash
npx -y @notionhq/notion-mcp-server
```
### HTTP 传输模式
HTTP 传输模式启动一个 HTTP 服务器，适合远程部署和需要认证的场景：
```bash
npx @notionhq/notion-mcp-server --transport http --port 3000
```
服务器默认监听 `http://0.0.0.0:3000/mcp`。
资料来源：[scripts/start-server.ts:20-35]()
### 认证机制
HTTP 传输模式支持 bearer token 认证：
| 认证方式 | 配置方法 | 优先级 |
|----------|----------|--------|
| 命令行参数 | `--auth-token "token"` | 最高 |
| 环境变量 | `AUTH_TOKEN="token"` | 中 |
| 自动生成 | 不指定则自动生成 | 仅开发环境 |
#### 自动生成 token（仅开发环境）
```bash
npx @notionhq/notion-mcp-server --transport http
```
输出示例：
```
Generated auth token: a1b2c3d4e5f6789...
Use this token in the Authorization header: Bearer a1b2c3d4e5f6789...
```
#### 自定义 token（生产环境推荐）
```bash
# 通过命令行
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
# 或通过环境变量
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http
```
#### 禁用认证（不推荐）
```bash
npx @notionhq/notion-mcp-server --transport http --disable-auth
```
#### HTTP 请求示例
```bash
curl -H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "mcp-session-id: your-session-id" \
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
http://localhost:3000/mcp
```
资料来源：[scripts/start-server.ts:1-50]()
## 命令行参数
```bash
notion-mcp-server [options]
Options:
--transport 传输类型: 'stdio' 或 'http'（默认: stdio）
--port HTTP 服务器端口（默认: 3000）
--auth-token Bearer token 认证
--disable-auth 禁用认证
--help, -h 显示帮助信息
Environment Variables:
NOTION_TOKEN Notion 集成 token（推荐）
OPENAPI_MCP_HEADERS JSON 格式的 Notion API 请求头
AUTH_TOKEN HTTP 传输认证 token
```
资料来源：[scripts/start-server.ts:10-30]()
## 开发环境配置
### 本地开发设置
1. **链接本地包**：
```bash
npm link
```
2. **配置 MCP 客户端**：
```json
{
"mcpServers": {
"notion-local-package": {
"command": "notion-mcp-server",
"env": {
"NOTION_TOKEN": "ntn_..."
}
}
}
}
```
3. **清理**：
```bash
npm unlink
```
### 构建与测试
```bash
# 构建项目
npm run build
# 运行测试
npm test
# 监听模式开发
npm run dev
```
### 本地执行
```bash
npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server
```
资料来源：[README.md:200-230]()
## 环境变量详解
| 变量名 | 用途 | 示例值 |
|--------|------|--------|
| `NOTION_TOKEN` | Notion 集成 Secret Token | `ntn_1a2b3c4d5e...` |
| `OPENAPI_MCP_HEADERS` | 自定义 API 请求头（JSON） | `{"Authorization": "Bearer ...", "Notion-Version": "2025-09-03"}` |
| `AUTH_TOKEN` | HTTP 传输认证 token | `my-secret-token` |
> **注意**：`OPENAPI_MCP_HEADERS` 中的 JSON 必须正确转义。在 shell 中使用时，建议使用单引号包裹整个 JSON 字符串。
资料来源：[src/openapi-mcp-server/client/http-client.ts:1-30]()
## 参数反序列化
MCP 工具调用时，参数以字符串形式传递。服务器会自动反序列化 JSON 格式的参数字符串：
```mermaid
graph LR
A[MCP 客户端
参数值: '{"filter": {...}}'] --> B[字符串传递]
B --> C[反序列化检查]
C -->|JSON 对象/数组| D[解析为对象]
C -->|其他| E[保持原值]
```
支持的类型：
- JSON 对象字符串：`'{"key": "value"}'`
- JSON 数组字符串：`'["item1", "item2"]'`
- 嵌套对象的递归反序列化
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-40]()
## 故障排除
### 常见问题
| 问题 | 解决方案 |
|------|----------|
| 认证失败 401 | 检查 `NOTION_TOKEN` 是否正确，或确认 Bearer token 与 `--auth-token` 匹配 |
| 页面访问被拒绝 | 确认已在目标页面「连接」到对应集成 |
| Docker 容器启动失败 | 检查 `NOTION_TOKEN` 环境变量是否正确传递 |
| Node 版本过低 | 升级到 Node.js 18+ |
### 验证配置
1. 启动服务器并检查输出日志
2. 确认客户端成功连接（查看客户端日志）
3. 尝试执行简单命令如搜索页面
## 发布包
```bash
npm login
npm publish --access public
```
资料来源：[README.md:230-235]()
## 相关文档
- [官方 README](https://github.com/makenotion/notion-mcp-server#readme)
- [Notion API 文档](https://developers.notion.com/reference/intro)
- [MCP 协议规范](https://spec.modelcontextprotocol.io/)
---
## HTTP 客户端与网络请求处理
### 相关页面
相关主题：[系统架构与模块设计](#page-2), [认证机制与安全配置](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)
- [src/openapi-mcp-server/client/polyfill-headers.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/polyfill-headers.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
# HTTP 客户端与网络请求处理
## 概述
Notion MCP Server 的 HTTP 客户端模块负责执行所有与 Notion API 的网络通信。该模块封装了底层的 HTTP 请求逻辑，将 OpenAPI 规范定义的 API 操作转换为可执行的 HTTP 调用。
核心职责包括：
- 构建符合 Notion API 规范的 HTTP 请求
- 处理请求参数（路径参数、查询参数、请求体）
- 管理请求头和认证信息
- 处理表单数据和二进制内容
- 转换响应格式
资料来源：[src/openapi-mcp-server/client/http-client.ts:1-198]()
## 架构设计
### 模块结构
```
┌─────────────────────────────────────────────────────────────┐
│ MCPProxy │
│ (工具注册与请求路由) │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ HttpClient │
│ (HTTP 请求执行层) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 参数处理 │ 请求构建 │ 响应转换 │ 错误处理 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Notion API │
│ (https://api.notion.com) │
└─────────────────────────────────────────────────────────────┘
```
### HTTP 客户端类
`HttpClient` 类是网络请求的核心执行器，在初始化时接收基础配置：
| 配置项 | 类型 | 说明 |
|--------|------|------|
| `baseUrl` | `string` | API 基础地址（默认 Notion API） |
| `headers` | `Record` | 全局请求头 |
| `openApiSpec` | `OpenAPIV3.Document` | OpenAPI 规范文档 |
资料来源：[src/openapi-mcp-server/client/http-client.ts:18-23]()
## HttpClient 实现详解
### 类初始化
```typescript
export class HttpClient {
constructor(
private config: HttpClientConfig,
private openApiSpec: OpenAPIV3.Document
) {
this.api = this.createApiClient()
}
}
```
构造函数完成以下初始化：
1. 存储配置参数
2. 创建 axios API 客户端实例
3. 准备处理 OpenAPI 规范中定义的请求
资料来源：[src/openapi-mcp-server/client/http-client.ts:15-26]()
### 请求参数处理
`HttpClient` 根据 OpenAPI 规范中的参数定义，智能分配参数到不同的请求位置：
```mermaid
graph TD
A[接收参数对象] --> B{存在 requestBody?}
B -->|是| C{参数类型为 FormData?}
B -->|否| D[将参数转为 URL 查询参数]
C -->|是| E[设置 FormData Headers]
C -->|否| F[设置 JSON Content-Type]
D --> G[执行 HTTP 请求]
E --> G
F --> G
```
参数分配逻辑：
| 参数位置 | 处理方式 | 来源 |
|----------|----------|------|
| `path` | 直接替换 URL 路径占位符 | `operation.parameters` |
| `query` | 添加到 URL 查询字符串 | `operation.parameters` |
| `body` | 作为请求体发送 | `operation.requestBody` |
资料来源：[src/openapi-mcp-server/client/http-client.ts:55-77]()
### 请求体处理
当没有定义 `requestBody` 且没有 FormData 时，所有剩余参数自动转为 URL 参数：
```typescript
// Add all parameters as url parameters if there is no requestBody defined
if (!operation.requestBody && !formData) {
for (const key in bodyParams) {
if (bodyParams[key] !== undefined) {
urlParameters[key] = bodyParams[key]
delete bodyParams[key]
}
}
}
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:66-74]()
### Content-Type 处理
`HttpClient` 根据请求内容类型动态设置请求头：
| 场景 | Content-Type |
|------|--------------|
| 有请求体 | `application/json` |
| FormData | 使用 FormData 的自动检测 |
| 无请求体 | `null`（移除 Content-Type） |
```typescript
const hasBody = Object.keys(bodyParams).length > 0
const headers = formData
? formData.getHeaders()
: { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:79-88]()
## 请求头管理
### Headers Polyfill
由于 Node.js 18 之前版本不支持原生的 `Headers` 类，项目实现了兼容性 polyfill：
```typescript
class PolyfillHeaders {
private headers: Map = new Map();
public append(name: string, value: string): void {
const key = name.toLowerCase();
if (!this.headers.has(key)) {
this.headers.set(key, []);
}
this.headers.get(key)!.push(value);
}
public get(name: string): string | null {
const key = name.toLowerCase();
if (!this.headers.has(key)) {
return null;
}
return this.headers.get(key)!.join(', ');
}
}
```
资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-45]()
### Polyfill 特性
| 特性 | 实现说明 |
|------|----------|
| 大小写不敏感 | 所有 key 自动转为小写存储 |
| 多值支持 | `append()` 方法支持添加多个同名值 |
| 兼容性 | 优先使用原生 `Headers`，回退到 polyfill |
### 响应头转换
axios 响应的 headers 对象会被转换为标准 `Headers` 实例：
```typescript
const responseHeaders = new Headers()
Object.entries(response.headers).forEach(([key, value]) => {
if (typeof value === 'string') {
responseHeaders.append(key, value)
}
})
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:103-108]()
## 请求执行流程
### 完整请求流程
```mermaid
sequenceDiagram
participant 调用方
participant MCPProxy
participant HttpClient
participant NotionAPI
调用方->>MCPProxy: 调用工具
MCPProxy->>HttpClient: executeOperation(operationId, params)
HttpClient->>HttpClient: 解析 OpenAPI 操作定义
HttpClient->>HttpClient: 分离 path/query/body 参数
HttpClient->>HttpClient: 构建请求配置
HttpClient->>NotionAPI: HTTP 请求
NotionAPI-->>HttpClient: 响应数据
HttpClient->>HttpClient: 转换响应头
HttpClient-->>MCPProxy: 格式化响应
MCPProxy-->>调用方: 返回结果
```
### 操作查找
每个 API 操作通过 `operationId` 查找对应的 HTTP 方法：
```typescript
const operationFn = (api as any)[operationId]
if (!operationFn) {
throw new Error(`Operation ${operationId} not found`)
}
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:75-78]()
## 配置与初始化
### MCPProxy 中的 HTTP 客户端
`MCPProxy` 在初始化时创建 `HttpClient` 实例：
```typescript
this.httpClient = new HttpClient(
{
baseUrl,
headers: this.parseHeadersFromEnv(),
},
openApiSpec,
)
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:29-35]()
### 从环境变量解析请求头
项目支持通过 `OPENAPI_MCP_HEADERS` 环境变量配置请求头：
```typescript
private parseHeadersFromEnv(): Record {
const headersEnv = process.env.OPENAPI_MCP_HEADERS
if (headersEnv) {
try {
return JSON.parse(headersEnv)
} catch {
return {}
}
}
return {}
}
```
常用配置示例：
```json
{
"Authorization": "Bearer ntn_xxxx",
"Notion-Version": "2025-09-03"
}
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:15-26]()
### 服务端初始化
`init-server.ts` 负责加载 OpenAPI 规范并创建代理：
```typescript
export async function initProxy(specPath: string, baseUrl: string | undefined) {
const openApiSpec = await loadOpenApiSpec(specPath, baseUrl)
const proxy = new MCPProxy('Notion API', openApiSpec)
return proxy
}
```
资料来源：[src/init-server.ts:44-50]()
## 错误处理
### 操作未找到
当 `operationId` 不存在于 API 客户端中时：
```typescript
const operationFn = (api as any)[operationId]
if (!operationFn) {
throw new Error(`Operation ${operationId} not found`)
}
```
### 文件读取错误
规范文件加载失败时的处理：
```typescript
try {
rawSpec = fs.readFileSync(path.resolve(process.cwd(), specPath), 'utf-8')
} catch (error) {
console.error('Failed to read OpenAPI specification file:', (error as Error).message)
process.exit(1)
}
```
资料来源：[src/init-server.ts:22-27]()
## 传输层支持
### STDIO 传输（默认）
默认情况下，MCP 服务器使用 STDIO 传输，适用于本地集成：
```bash
notion-mcp-server
```
### HTTP 传输
支持 HTTP 传输模式，用于远程访问：
```bash
notion-mcp-server --transport http --port 3000
```
HTTP 传输需要认证令牌：
```bash
# 自动生成令牌
notion-mcp-server --transport http
# 自定义令牌
notion-mcp-server --transport http --auth-token "your-token"
```
资料来源：[scripts/start-server.ts:1-40]()
## 最佳实践
### 请求头配置
推荐使用 `NOTION_TOKEN` 环境变量进行配置：
```bash
NOTION_TOKEN=ntn_xxxx notion-mcp-server
```
高级场景可使用 `OPENAPI_MCP_HEADERS`：
```bash
OPENAPI_MCP_HEADERS='{"Authorization": "Bearer ntn_xxxx", "Notion-Version": "2025-09-03"}' notion-mcp-server
```
### 本地开发测试
使用 `npm link` 创建全局符号链接进行本地测试：
```bash
npm link
```
配置客户端使用本地包：
```json
{
"mcpServers": {
"notion-local-package": {
"command": "notion-mcp-server",
"env": {
"NOTION_TOKEN": "ntn_..."
}
}
}
}
```
## 总结
HTTP 客户端模块是 Notion MCP Server 与 Notion API 通信的桥梁。通过封装底层的 HTTP 请求逻辑，提供了：
- **参数自动路由**：智能区分 path、query、body 参数
- **格式自动适配**：根据内容类型设置正确的 Content-Type
- **跨版本兼容**：Headers polyfill 确保 Node.js 18 以下版本兼容
- **配置灵活**：支持环境变量和命令行参数配置
该设计遵循了单一职责原则，使网络请求处理与业务逻辑解耦，便于维护和测试。
---
## 认证机制与安全配置
### 相关页面
相关主题：[系统架构与模块设计](#page-2), [传输层配置详解](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)
- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
# 认证机制与安全配置
Notion MCP Server 提供多层认证机制，支持通过环境变量、命令行参数和 HTTP 传输层认证来保护对 Notion API 的访问。本页面详细说明服务器启动、API 认证和 HTTP 传输安全的完整配置流程。
## 认证体系概述
Notion MCP Server 采用双层认证架构：
| 层级 | 认证对象 | 认证方式 | 配置方式 |
|------|----------|----------|----------|
| **API 认证层** | Notion API 请求 | Bearer Token / Header | `NOTION_TOKEN` 或 `OPENAPI_MCP_HEADERS` |
| **传输认证层** | HTTP 传输通道 | Bearer Token | `--auth-token` 或 `AUTH_TOKEN` |
资料来源：[scripts/start-server.ts:1-100]()
```mermaid
graph TD
A[客户端请求] --> B{传输类型}
B -->|stdio| C[直接通信]
B -->|http| D[传输层认证]
D --> E{验证 Bearer Token}
E -->|通过| F[解析请求]
E -->|失败| G[401 未授权]
F --> H{API 认证}
H -->|NOTION_TOKEN| I[使用环境变量 Token]
H -->|OPENAPI_MCP_HEADERS| J[使用自定义 Header]
I --> K[调用 Notion API]
J --> K
```
## 环境变量配置
### NOTION_TOKEN（推荐方式）
Notion 集成令牌是访问 Notion API 的主要认证凭证。
```bash
NOTION_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxx npx -y @notionhq/notion-mcp-server
```
**配置位置**：[scripts/start-server.ts:26-27]() 在启动时读取环境变量
```typescript
const notionToken = process.env.NOTION_TOKEN
```
> **注意**：集成令牌需在 Notion 开发者门户中创建，并为目标页面授予访问权限。
### OPENAPI_MCP_HEADERS（高级配置）
当需要自定义请求头时使用，如指定 Notion API 版本：
```bash
OPENAPI_MCP_HEADERS='{"Authorization": "Bearer ntn_xxxx", "Notion-Version": "2025-09-03"}' \
npx -y @notionhq/notion-mcp-server
```
**Header 解析逻辑**：[src/init-server.ts:39-52]() 通过 `parseHeadersFromEnv()` 方法处理
```typescript
private parseHeadersFromEnv(): Record {
const headersEnv = process.env.OPENAPI_MCP_HEADERS
if (!headersEnv) return {}
try {
return JSON.parse(headersEnv)
} catch {
throw new Error('OPENAPI_MCP_HEADERS must be valid JSON')
}
}
```
## HTTP 传输层认证
当使用 `--transport http` 模式时，服务器启用额外的 Bearer Token 认证层。
### 命令行参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--transport ` | 传输类型：`stdio` 或 `http` | `stdio` |
| `--port ` | HTTP 服务器端口 | `3000` |
| `--auth-token ` | 传输层认证令牌 | 自动生成 |
| `--disable-auth` | 禁用传输层认证 | `false`（默认启用） |
| `--help`, `-h` | 显示帮助信息 | - |
资料来源：[scripts/start-server.ts:1-35]()
### 认证模式
#### 自动生成令牌（仅限开发环境）
```bash
npx @notionhq/notion-mcp-server --transport http
```
服务器启动时会输出自动生成的令牌：
```
Generated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab
Use this token in the Authorization header: Bearer a1b2c3d4e5f6789...
```
#### 自定义令牌（推荐用于生产环境）
```bash
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
```
#### 环境变量配置
```bash
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http
```
**优先级**：`--auth-token` > `AUTH_TOKEN` 环境变量
资料来源：[scripts/start-server.ts:17-24]()
### 令牌验证流程
```mermaid
sequenceDiagram
participant C as 客户端
participant S as MCP Server
C->>S: HTTP POST /mcp (无 Authorization)
S-->>C: 401 Unauthorized
C->>S: HTTP POST /mcp (Bearer invalid-token)
S-->>C: 401 Unauthorized
C->>S: HTTP POST /mcp (Bearer valid-token)
S->>S: 验证令牌
S->>S: 解析 JSON-RPC 请求
S->>C: JSON-RPC 响应
```
## 认证头传递机制
HTTP 客户端负责将认证信息传递给 Notion API：
```mermaid
graph LR
A[环境变量] -->|OPENAPI_MCP_HEADERS| B[HttpClient]
C[NOTION_TOKEN] -->|Bearer Token| B
B --> D[Authorization: Bearer ntn_xxx]
B --> E[Notion-Version: 2025-09-03]
D --> F[Notion API]
E --> F
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50]()
### 客户端初始化
```typescript
this.httpClient = new HttpClient(
{
baseUrl,
headers: this.parseHeadersFromEnv(),
},
openApiSpec,
)
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:35-42]()
## 安全配置最佳实践
### 生产环境配置
| 配置项 | 建议值 | 理由 |
|--------|--------|------|
| `NOTION_TOKEN` | 必需设置 | API 访问凭证 |
| `AUTH_TOKEN` | 使用强随机字符串 | 保护 HTTP 传输通道 |
| `--disable-auth` | **勿使用** | 关闭认证存在安全风险 |
| `--port` | 非标准端口 | 减少暴露面 |
### Docker 环境配置
#### 方式一：使用 NOTION_TOKEN
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN", "mcp/notion"],
"env": {
"NOTION_TOKEN": "ntn_xxxx"
}
}
}
}
```
#### 方式二：使用 OPENAPI_MCP_HEADERS
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "OPENAPI_MCP_HEADERS", "mcp/notion"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_xxxx\",\"Notion-Version\":\"2025-09-03\"}"
}
}
}
}
```
### Cursor/Claude Desktop 配置
```json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_xxxx"
}
}
}
}
```
## 错误处理
| 错误场景 | HTTP 状态码 | 响应 |
|----------|-------------|------|
| 未提供传输层令牌 | 401 | `Unauthorized` |
| 令牌验证失败 | 401 | `Unauthorized` |
| JSON 解析失败 | 400 | `Bad Request` |
| Notion API 错误 | 相应状态码 | API 响应内容 |
```typescript
// 错误处理示例
} catch (error) {
if (error instanceof ValidationError) {
console.error('Invalid OpenAPI 3.1 specification:')
error.errors.forEach(err => console.error(err))
} else {
console.error('Error:', error)
}
process.exit(1)
}
```
资料来源：[scripts/start-server.ts:85-93]()
## 命令行帮助信息
```bash
Usage: notion-mcp-server [options]
Options:
--transport Transport type: 'stdio' or 'http' (default: stdio)
--port Port for HTTP server when using Streamable HTTP transport (default: 3000)
--auth-token Bearer token for HTTP transport authentication (auto-generated if not provided)
--disable-auth Disable bearer token authentication for HTTP transport
--help, -h Show this help message
Environment Variables:
NOTION_TOKEN Notion integration token (recommended)
OPENAPI_MCP_HEADERS JSON string with Notion API headers (alternative)
AUTH_TOKEN Bearer token for HTTP transport authentication (alternative to --auth-token)
```
## 快速参考
| 场景 | 推荐配置 |
|------|----------|
| 本地开发 (stdio) | `NOTION_TOKEN=ntn_xxx notion-mcp-server` |
| 本地开发 (HTTP) | `NOTION_TOKEN=ntn_xxx notion-mcp-server --transport http` |
| 生产环境 | 使用 `--auth-token` 指定强密码，启用 HTTPS 反向代理 |
| Docker 运行 | 使用环境变量挂载或配置文件 |
---
## 传输层配置详解
### 相关页面
相关主题：[安装与客户端配置](#page-4), [认证机制与安全配置](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)
- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)
- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
# 传输层配置详解
## 概述
Notion MCP Server 支持两种传输层协议，用于与 MCP 客户端进行通信。传输层是 MCP 服务器与客户端之间数据传输的核心抽象，负责处理请求的序列化和反序列化、会话管理以及认证机制。资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
## 传输类型
| 传输类型 | 说明 | 默认端口 | 适用场景 |
|---------|------|---------|---------|
| `stdio` | 标准输入输出流 | - | 本地开发、直接进程调用 |
| `http` | Streamable HTTP | 3000 | 远程访问、微服务架构 |
资料来源：[scripts/start-server.ts:1-50]()
## stdio 传输模式
stdio（Standard Input/Output）是 MCP 协议的默认传输方式，适用于本地进程通信场景。在这种模式下，服务器通过标准输入读取来自客户端的 JSON-RPC 请求，并通过标准输出返回响应。
### 工作原理
```mermaid
graph LR
A[MCP 客户端] -->|stdin| B[notion-mcp-server]
B -->|stdout| A
```
stdio 传输模式的优势在于：
- 配置简单，无需额外的网络配置
- 适合自动化测试和本地开发
- 进程生命周期由客户端管理
### 使用方式
```bash
# 默认使用 stdio 传输
npx -y @notionhq/notion-mcp-server
# 显式指定 stdio 传输
npx @notionhq/notion-mcp-server --transport stdio
```
资料来源：[scripts/start-server.ts:1-30]()
## HTTP 传输模式
HTTP 传输模式基于 Model Context Protocol 的 Streamable HTTP 规范实现，提供了更灵活的远程访问能力。资料来源：[scripts/start-server.ts:1-80]()
### 架构设计
```mermaid
graph TD
A[MCP 客户端] -->|HTTP 请求| B[Express 服务器]
B -->|路由| C[Streamable HTTP Handler]
C -->|认证检查| D{认证状态}
D -->|有效| E[MCP 代理]
D -->|无效| F[401 Unauthorized]
E -->|处理请求| G[Notion API]
G -->|响应| E
E -->|JSON-RPC 响应| B
```
### 启动参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--transport` | string | `stdio` | 传输类型 |
| `--port` | number | `3000` | HTTP 服务端口 |
| `--auth-token` | string | 自动生成 | 认证令牌 |
| `--disable-auth` | boolean | `false` | 禁用认证 |
资料来源：[scripts/start-server.ts:15-40]()
### 命令行示例
```bash
# 基础 HTTP 模式（自动生成认证令牌）
npx @notionhq/notion-mcp-server --transport http
# 指定端口
npx @notionhq/notion-mcp-server --transport http --port 8080
# 自定义认证令牌（推荐用于生产环境）
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
# 禁用认证（仅用于开发环境）
npx @notionhq/notion-mcp-server --transport http --disable-auth
```
资料来源：[scripts/start-server.ts:10-45]()
## 认证机制
HTTP 传输模式强制使用 Bearer Token 认证，以防止未授权访问。
### 认证方式优先级
1. **命令行参数** `--auth-token`（最高优先级）
2. **环境变量** `AUTH_TOKEN`
3. **自动生成**（仅开发模式）
### 认证流程
```mermaid
sequenceDiagram
participant C as MCP 客户端
participant S as MCP 服务器
participant N as Notion API
C->>S: HTTP 请求 + Authorization Header
Note over S: 验证 Bearer Token
alt 认证失败
S-->>C: 401 Unauthorized
else 认证成功
S->>N: API 请求
N-->>S: API 响应
S-->>C: JSON-RPC 响应
end
```
### 请求示例
```bash
curl -H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "mcp-session-id: your-session-id" \
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
http://localhost:3000/mcp
```
## 环境变量配置
Notion MCP Server 支持多种环境变量配置方式，用于设置 API 凭证和自定义请求头。
### 配置参数
| 环境变量 | 说明 | 推荐用途 |
|---------|------|---------|
| `NOTION_TOKEN` | Notion 集成令牌 | 推荐用于标准配置 |
| `OPENAPI_MCP_HEADERS` | JSON 格式的自定义请求头 | 高级配置场景 |
| `AUTH_TOKEN` | HTTP 传输认证令牌 | 生产环境部署 |
### 配置示例
```bash
# 方式一：使用 NOTION_TOKEN（推荐）
export NOTION_TOKEN="ntn_****"
npx @notionhq/notion-mcp-server --transport http
# 方式二：使用 OPENAPI_MCP_HEADERS
export OPENAPI_MCP_HEADERS='{"Authorization":"Bearer ntn_****","Notion-Version":"2025-09-03"}'
npx @notionhq/notion-mcp-server --transport http
# 方式三：使用 AUTH_TOKEN
export AUTH_TOKEN="secure-auth-token"
npx @notionhq/notion-mcp-server --transport http
```
## 客户端配置
### Cursor / Claude Desktop
```json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
### Zed Editor
```json
{
"context_servers": {
"some-context-server": {
"command": {
"path": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
}
},
"settings": {}
}
}
}
```
### GitHub Copilot CLI
```json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
## Docker 部署
### 方式一：使用官方镜像
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN", "mcp/notion"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
### 方式二：本地构建
```bash
docker compose build
```
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"NOTION_TOKEN=ntn_****",
"notion-mcp-server"
]
}
}
}
```
## 核心组件架构
```mermaid
graph TD
subgraph 传输层
A[stdio 传输]
B[HTTP 传输]
end
subgraph 核心服务
C[MCPProxy]
D[HttpClient]
E[OpenAPIToMCPConverter]
end
subgraph 工具系统
F[工具注册]
G[参数反序列化]
H[API 执行]
end
A --> C
B --> C
C --> D
C --> E
E --> F
F --> G
G --> H
```
### MCPProxy 类
`MCPProxy` 是传输层与工具系统之间的桥梁，负责：
- 初始化 MCP 服务器实例
- 注册 OpenAPI 转换后的工具
- 处理请求参数的反序列化
- 执行 API 调用并返回响应
```typescript
export class MCPProxy {
private server: Server
private httpClient: HttpClient
private tools: Record
private openApiLookup: Record
}
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:50-100]()
### 参数反序列化
MCP 协议在传输过程中会将嵌套对象序列化为字符串，服务器端需要反序列化这些参数：
```typescript
function deserializeParams(params: Record): Record {
// 处理 JSON 字符串形式的嵌套对象
// 处理数组中的 JSON 字符串元素
// 递归反序列化
}
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:10-50]()
## 配置决策矩阵
| 使用场景 | 传输模式 | 认证方式 | 推荐配置 |
|---------|---------|---------|---------|
| 本地开发调试 | stdio | 无 | `npm run dev` |
| 生产环境（远程） | http | `--auth-token` | 环境变量 + 令牌 |
| Docker 部署 | http | 环境变量 | `NOTION_TOKEN` |
| 团队共享 | http | 统一令牌 | 配置文件管理 |
## 故障排除
### 常见问题
1. **连接被拒绝**
- 检查端口是否被占用：`lsof -i :3000`
- 确认防火墙规则允许访问
2. **认证失败**
- 验证 Bearer Token 与服务器配置一致
- 检查 `Authorization` 头部格式是否正确
3. **工具调用失败**
- 确认 `NOTION_TOKEN` 有效且已配置到目标页面
- 检查 OpenAPI 请求头配置
### 调试模式
使用 `tsx watch` 启动开发服务器以获取详细日志：
```bash
npm run dev
```
资料来源：[package.json:10-20]()
## 总结
Notion MCP Server 的传输层设计遵循 Model Context Protocol 规范，提供了 stdio 和 HTTP 两种传输模式以适应不同的部署场景。stdio 模式适合本地开发和测试，而 HTTP 模式则支持远程访问和微服务架构。通过命令行参数和环境变量的灵活组合，用户可以根据实际需求选择合适的认证和配置方案。
---
## 本地开发与测试指南
### 相关页面
相关主题：[安装与客户端配置](#page-4), [从 v1.x 到 v2.0.0 迁移指南](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)
- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
# 本地开发与测试指南
本指南详细介绍如何搭建本地开发环境、运行测试、调试代码以及发布 `notion-mcp-server` 包。该服务器是基于 MCP (Model Context Protocol) 的 Notion API 实现，通过 OpenAPI 规范自动生成 MCP 工具。
## 环境准备
### 系统要求
| 要求项 | 最低版本 | 推荐版本 |
|--------|----------|----------|
| Node.js | Node.js 20+ | Node.js 22 LTS |
| npm | npm 10+ | npm 10+ |
| Docker | Docker 24+ | Docker 最新版 |
### 安装依赖
项目使用 ES Modules (ESM) 模块系统，TypeScript 版本为 5.8.2。安装依赖前请确保 Node.js 版本符合要求：
```bash
# 克隆仓库
git clone https://github.com/makenotion/notion-mcp-server.git
cd notion-mcp-server
# 安装依赖
npm install
```
资料来源：[package.json:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
### 环境变量配置
开发环境需要配置 Notion API 认证信息。可通过以下方式配置：
| 环境变量 | 说明 | 必需 |
|----------|------|------|
| `NOTION_TOKEN` | Notion 集成密钥（推荐） | 是 |
| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 请求头 | 否 |
| `AUTH_TOKEN` | HTTP 传输层认证令牌 | 仅 HTTP 模式 |
| `NODE_ENV` | 运行环境 (`test` 用于测试) | 测试时必需 |
资料来源：[README.md:100-120](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)
## 项目架构
### 核心模块结构
```
notion-mcp-server/
├── scripts/
│ ├── notion-openapi.json # OpenAPI 3.1.0 规范（所有工具的来源）
│ └── start-server.ts # 服务器启动入口
├── src/
│ └── openapi-mcp-server/
│ ├── openapi/
│ │ └── parser.ts # OpenAPI → MCP 工具转换
│ ├── mcp/
│ │ └── proxy.ts # MCP 工具注册与执行
│ └── client/
│ └── http-client.ts # HTTP 请求执行
└── __tests__/ # 测试文件目录
```
### 工具生成流程
MCP 工具通过 OpenAPI 规范自动生成，无需手动编写代码：
```mermaid
graph TD
A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]
B --> C[每个 operation 生成一个 MCP 工具]
C --> D[参数 → inputSchema]
C --> E[响应 → returnSchema]
D --> F[MCPProxy.setupHandlers]
E --> F
F --> G[MCP SDK 注册工具]
```
资料来源：[CLAUDE.md:20-35](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)
## 开发命令
### 常用命令
| 命令 | 说明 | 用途 |
|------|------|------|
| `npm run build` | TypeScript 编译 + CLI 打包 | 生产构建 |
| `npm run dev` | 热重载开发服务器 | 实时调试 |
| `npm test` | 运行 vitest 测试 | 单元测试 |
| `npm run test:watch` | 监听模式运行测试 | TDD 开发 |
| `npm run test:coverage` | 生成测试覆盖率报告 | 代码覆盖率 |
资料来源：[package.json:8-13](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
### 构建流程
`npm run build` 命令执行两个步骤：
1. **TypeScript 编译**：`tsc -build` 编译 TypeScript 源代码
2. **CLI 打包**：`node scripts/build-cli.js` 将代码打包为 CLI 可执行文件
构建产物：
- `index.js`：主入口
- `bin/cli.mjs`：CLI 可执行文件
```bash
# 完整构建
npm run build
# 仅编译 TypeScript（不打包 CLI）
tsc -build
# 热重载开发
npm run dev
```
资料来源：[package.json:8](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
## 测试框架
### Vitest 配置
项目使用 Vitest 4.0.18 作为测试框架，与 Vite 集成提供快速的单元测试能力。
测试文件位置遵循约定：与源文件同目录的 `__tests__` 子目录：
```
src/openapi-mcp-server/openapi/
├── parser.ts
└── __tests__/
└── parser.test.ts
```
运行测试时需要设置 `NODE_ENV=test` 环境变量：
```bash
# 运行所有测试
npm test
# 监听模式（文件变化时自动重新运行）
npm run test:watch
# 生成覆盖率报告
npm run test:coverage
```
资料来源：[package.json:11-13](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
### 参数反序列化测试
`proxy.ts` 中的 `deserializeParams` 函数负责将 JSON 字符串参数反序列化为对象。测试覆盖以下场景：
- JSON 对象字符串 → 对象
- JSON 数组字符串 → 数组
- 嵌套对象的递归反序列化
- 无效 JSON 字符串保留原值
```typescript
// 测试示例
const input = { filter: '[{"property":"Name","checkbox":{"equals":true}}]' }
const result = deserializeParams(input)
// result.filter 变为数组而非字符串
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:170-210](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
## 本地测试配置
### Cursor 客户端测试
在 Cursor 中测试本地修改的步骤：
```mermaid
graph LR
A[npm link] --> B[创建全局符号链接]
B --> C[修改 mcp.json 配置]
C --> D[Cursor 连接本地包]
D --> E[测试 MCP 工具]
E --> F{npm unlink 清理}
```
**步骤 1**：在仓库根目录创建符号链接
```bash
npm link
```
**步骤 2**：修改 Cursor 的 `mcp.json` 配置
```json
{
"mcpServers": {
"notion-local-package": {
"command": "notion-mcp-server",
"env": {
"NOTION_TOKEN": "ntn_..."
}
}
}
}
```
**步骤 3**：测试完成后清理
```bash
npm unlink
```
资料来源：[README.md:85-105](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)
### 命令行直接执行
本地构建后可使用 `npx` 直接执行：
```bash
# 使用本地路径执行
npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server
```
## HTTP 传输模式调试
### 启动带认证的 HTTP 服务器
```bash
# 自动生成认证令牌（仅用于开发）
npx @notionhq/notion-mcp-server --transport http
# 指定自定义令牌
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
# 使用环境变量指定令牌
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http
```
### 启动参数说明
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--transport` | 传输类型：`stdio` 或 `http` | `stdio` |
| `--port` | HTTP 服务器端口 | `3000` |
| `--auth-token` | 认证令牌 | 自动生成 |
| `--disable-auth` | 禁用认证 | - |
| `--help`, `-h` | 显示帮助信息 | - |
资料来源：[scripts/start-server.ts:15-30](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
### HTTP 请求示例
使用认证令牌发起请求：
```bash
curl -H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "mcp-session-id: your-session-id" \
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
http://localhost:3000/mcp
```
## Docker 开发
### 本地构建 Docker 镜像
```bash
# 构建镜像
docker compose build
# 运行容器
docker compose up
```
### Docker 配置示例
使用环境变量传递 Notion 令牌（推荐）：
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"NOTION_TOKEN",
"notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
```
使用 OPENAPI_MCP_HEADERS（高级场景）：
```json
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"OPENAPI_MCP_HEADERS",
"notion-mcp-server"
],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
}
}
}
}
```
资料来源：[README.md:55-90](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)
## 发布流程
### npm 发布
```bash
# 登录 npm
npm login
# 发布包（需要 public 访问权限）
npm publish --access public
```
### 版本管理
当前版本：`2.3.0`
包名称：`@notionhq/notion-mcp-server`
发布前请确保：
1. 所有测试通过：`npm test`
2. 构建成功：`npm run build`
3. 更新版本号（在 `package.json` 中）
资料来源：[package.json:4-7](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
## OpenAPI 解析器开发
### 模式转换逻辑
`parser.ts` 实现了 OpenAPI Schema 到 JSON Schema 的转换：
```mermaid
graph TD
A[OpenAPI Schema] --> B{类型判断}
B -->|binary format| C[转换为 uri-reference]
B -->|object| D[处理 properties]
B -->|array| E[递归处理 items]
B -->|enum| F[保留 enum 值]
B -->|oneOf/anyOf| G[递归转换子模式]
C --> H[JSON Schema]
D --> H
E --> H
F --> H
G --> H
```
### 关键转换规则
| OpenAPI 特性 | 转换处理 |
|--------------|----------|
| `format: binary` | 转为 `format: uri-reference` |
| `type: object` | 保留 `properties` 和 `required` |
| `type: array` | 递归处理 `items` |
| `additionalProperties` | 布尔值或递归处理对象 |
| `oneOf/anyOf/allOf` | 递归转换子模式 |
| `const` | 保留用于 discriminator |
资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-80](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)
## 常见问题排查
### 问题：模块导入错误
确保使用 ES Modules 运行，检查 `package.json` 中 `"type": "module"` 配置。
### 问题：测试找不到文件
检查测试文件是否位于源文件同级的 `__tests__` 目录中，文件名应匹配 `*.test.ts` 模式。
### 问题：HTTP 认证失败
确认请求头中包含正确的 `Authorization: Bearer `，且令牌与服务器配置一致。
### 问题：TypeScript 编译错误
运行 `npm run build` 前确保已安装所有依赖，必要时删除 `node_modules` 后重新安装。
---
## 从 v1.x 到 v2.0.0 迁移指南
### 相关页面
相关主题：[项目介绍与版本说明](#page-1), [MCP 工具集详解](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)
- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)
- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)
- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)
- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)
# 从 v1.x 到 v2.0.0 迁移指南
## 概述
Notion MCP Server v2.0.0 是该项目的重大版本更新，主要迁移到 **Notion API 2025-09-03** 版本（即 Data Source Edition）。此次更新引入了 **data sources（数据源）** 作为数据库的主要抽象概念，取代了传统的 `database` 概念。
> **重要提示**：v2.0.0 **不需要代码更改**。MCP 工具在服务器启动时自动被发现。当你升级到 v2.0.0 时，AI 客户端将自动看到新的工具名称和参数，旧版数据库工具将不再可用。
资料来源：[README.md:100-105]()
## 版本变化总览
### 工具变化统计
| 变更类型 | 数量 | 说明 |
|---------|------|------|
| 移除工具 | 3 个 | 被新数据源工具替代 |
| 新增工具 | 7 个 | 完整的数据源操作能力 |
| 工具总数 | 22 个 | v1.x 为 19 个 |
资料来源：[README.md:106-108]()
### 架构变化图示
```mermaid
graph TD
subgraph v1.x 架构
A1[数据库操作] -->|database_id| B1[post-database-query]
A1 -->|database_id| B2[update-a-database]
A1 -->|database_id| B3[create-a-database]
end
subgraph v2.0.0 架构
A2[数据源操作] -->|data_source_id| C1[query-data-source]
A2 -->|data_source_id| C2[update-a-data-source]
A2 -->|data_source_id| C3[create-a-data-source]
A2 -->|data_source_id| C4[retrieve-a-data-source]
A2 -->|data_source_id| C5[list-data-source-templates]
end
A2 -.->|page_id / database_id| C6[move-page]
A2 -.->|向后兼容| C7[retrieve-a-database]
style A1 fill:#ffcccc
style A2 fill:#ccffcc
style B1 fill:#ffcccc
style B2 fill:#ffcccc
style B3 fill:#ffcccc
style C1 fill:#ccffcc
style C2 fill:#ccffcc
style C3 fill:#ccffcc
style C4 fill:#ccffcc
style C5 fill:#ccffcc
```
## 移除的工具
以下三个工具已被新工具替代，不再可用：
| 旧工具名称 (v1.x) | 替代工具 (v2.0) | 用途 |
|-----------------|---------------|------|
| `post-database-query` | `query-data-source` | 查询数据源 |
| `update-a-database` | `update-a-data-source` | 更新数据源 |
| `create-a-database` | `create-a-data-source` | 创建数据源 |
资料来源：[README.md:72-74]()
## 新增的工具
### 数据源操作工具
| 工具名称 | 功能描述 |
|---------|---------|
| `query-data-source` | 使用过滤器和排序查询数据源 |
| `retrieve-a-data-source` | 获取数据源的元数据和架构 |
| `update-a-data-source` | 更新数据源属性 |
| `create-a-data-source` | 创建新的数据源 |
| `list-data-source-templates` | 列出数据源中的可用模板 |
### 页面操作工具
| 工具名称 | 功能描述 |
|---------|---------|
| `move-page` | 将页面移动到不同的父级位置 |
| `retrieve-a-database` | 获取数据库元数据（包括数据源 ID 列表） |
资料来源：[README.md:75-83]()
## 参数变更说明
### 核心参数变化
| 变更项 | v1.x | v2.0.0 | 说明 |
|-------|------|--------|------|
| 数据库标识符 | `database_id` | `data_source_id` | 所有数据源操作使用新参数名 |
| 搜索过滤器值 | `["page", "database"]` | `["page", "data_source"]` | 搜索 API 的过滤器值变更 |
| 页面创建父级 | 仅 `page_id` | `page_id` 或 `database_id` | 现在支持数据源作为父级 |
资料来源：[README.md:84-87]()
### 参数转换示例
```mermaid
graph LR
subgraph v1.x 参数传递
A1["database_id: 'xxx'"] --> B1[数据库操作]
end
subgraph v2.0.0 参数传递
A2["data_source_id: 'xxx'"] --> B2[数据源操作]
end
style A1 fill:#ffcccc
style A2 fill:#ccffcc
```
## API 版本与端点
### 使用的 API 版本
v2.0.0 使用 **Notion API 版本 `2025-09-03`**（Data Source Edition）。
> 此版本引入了数据源作为数据库的主要抽象，是 Notion API 的重大更新。
资料来源：[CLAUDE.md:38]()
### 新增的 API 端点
| 端点类型 | 端点路径 | 说明 |
|---------|---------|------|
| 传统端点 | `/v1/databases/{database_id}` | 保留传统数据库端点 |
| 新端点 | `/v1/data_sources/{data_source_id}` | 新增数据源端点 |
资料来源：[CLAUDE.md:39-40]()
## 迁移操作指南
### 步骤一：识别硬编码的工具引用
如果你的代码或提示词中硬编码了旧版工具名称，需要进行以下更新：
| 旧工具 (v1.x) | 新工具 (v2.0) | 参数变更 |
|--------------|---------------|---------|
| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |
| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |
| `create-a-database` | `create-a-data-source` | 参数不变（使用 `parent.page_id`） |
资料来源：[README.md:117-121]()
### 步骤二：更新参数名称
```diff
# 数据库查询操作
- tool: "post-database-query"
- params: { "database_id": "xxx" }
+ tool: "query-data-source"
+ params: { "data_source_id": "xxx" }
# 数据库更新操作
- tool: "update-a-database"
- params: { "database_id": "xxx", ... }
+ tool: "update-a-data-source"
+ params: { "data_source_id": "xxx", ... }
```
### 步骤三：理解保留的工具
`retrieve-a-database` 工具仍然可用，用于获取数据库元数据。该工具现在会返回数据源 ID 列表。使用 `retrieve-a-data-source` 获取特定数据源的架构和属性。
```mermaid
graph TD
A[retrieve-a-database] -->|获取数据库元数据| B[data_source_ids 列表]
B --> C[retrieve-a-data-source]
C -->|获取数据源架构| D[schema 和 properties]
```
资料来源：[README.md:123-125]()
## MCP 服务器工具自动发现机制
Notion MCP Server 的一个关键特性是**工具自动生成**机制。工具从 OpenAPI 规范自动派生，无需手动代码更改。
### 工具生成流程
```mermaid
graph TD
A["scripts/notion-openapi.json
OpenAPI 3.1.0 规范"] --> B["src/init-server.ts
加载并验证规范"]
B --> C["openapi/parser.ts
OpenAPIToMCPConverter"]
C --> D["convertToMCPTools() 方法"]
D --> E["mcp/proxy.ts
MCPProxy.setupHandlers()"]
E --> F["MCP SDK 注册工具"]
subgraph 关键转换逻辑
C -.->|1. operationId → 工具名| G["retrieve-a-data-source"]
C -.->|2. parameters + requestBody → inputSchema| H["输入参数模式"]
C -.->|3. Response schema → returnSchema| I["返回模式"]
end
```
资料来源：[CLAUDE.md:18-30]()
### 文件结构说明
| 文件路径 | 职责 |
|---------|------|
| `scripts/notion-openapi.json` | OpenAPI 3.1.0 规范（所有工具的来源） |
| `src/init-server.ts` | 服务器初始化 |
| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI → MCP 工具转换 |
| `src/openapi-mcp-server/mcp/proxy.ts` | MCP 工具注册和执行 |
| `src/openapi-mcp-server/client/http-client.ts` | HTTP 请求执行 |
资料来源：[CLAUDE.md:33-36]()
## 搜索功能变更
### 搜索过滤器值变化
v2.0.0 中，搜索 API 的过滤器值发生了以下变化：
| 对象类型 | v1.x 值 | v2.0.0 值 |
|---------|---------|----------|
| 页面 | `"page"` | `"page"` |
| 数据库/数据源 | `"database"` | `"data_source"` |
```mermaid
graph LR
A[搜索过滤器] -->|v1.x| B["value: 'database'"]
A -->|v2.0.0| C["value: 'data_source'"]
style B fill:#ffcccc
style C fill:#ccffcc
```
资料来源：[README.md:85-86]()
## 页面创建增强
### 新增的父级类型支持
v2.0.0 增强了页面创建功能，现在支持两种父级类型：
| 父级类型 | 参数名 | 说明 |
|---------|--------|------|
| 页面 | `page_id` | 在现有页面下创建 |
| 数据源（数据库） | `database_id` | 在数据源下创建页面 |
这使得在数据源中创建条目更加直接，无需先获取数据源对应的页面 ID。
资料来源：[README.md:87-88]()
## 常见问题
### Q1：是否需要修改代码？
**否**。MCP 工具在服务器启动时自动被发现。升级到 v2.0.0 后，AI 客户端会自动看到新的工具名称和参数。
> **唯一例外**：如果你在代码或提示词中**硬编码**了旧版工具名称，则需要手动更新为新工具名称和参数。
资料来源：[README.md:109-113]()
### Q2：如何区分数据库和数据源？
- **数据库（Database）**：传统概念，保留用于向后兼容
- **数据源（Data Source）**：API 2025-09-03 引入的新概念，是当前的主要抽象
使用 `retrieve-a-database` 获取数据库元数据，其中包含关联的 `data_source_ids` 列表。
资料来源：[README.md:123-125]()
### Q3：如何获取数据源的详细信息？
使用 `retrieve-a-data-source` 工具获取特定数据源的架构和属性：
```typescript
// 获取数据源详情
tool: "retrieve-a-data-source"
params: {
"data_source_id": ""
}
```
资料来源：[README.md:77]()
## 环境变量配置
### Notion 认证
| 环境变量 | 说明 | 推荐度 |
|---------|------|--------|
| `NOTION_TOKEN` | Notion 集成令牌 | ⭐ 推荐 |
| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 头信息 | 高级用法 |
### HTTP 传输认证
| 环境变量 | 说明 |
|---------|------|
| `AUTH_TOKEN` | HTTP 传输的 Bearer 令牌（可通过 `--auth-token` 命令行参数覆盖） |
资料来源：[scripts/start-server.ts:1-30]()
## 构建和测试命令
### 常用命令
| 命令 | 功能 |
|-----|------|
| `npm run build` | TypeScript 编译 + CLI 打包 |
| `npm test` | 运行 Vitest 测试 |
| `npm run dev` | 启动热重载的开发服务器 |
资料来源：[CLAUDE.md:32]()
### 本地测试配置
1. 在仓库根目录运行 `npm link` 创建全局符号链接
2. 在 Cursor 的 `mcp.json` 中添加配置：
```json
{
"mcpServers": {
"notion-local-package": {
"command": "notion-mcp-server",
"env": {
"NOTION_TOKEN": "ntn_..."
}
}
}
}
```
3. 测试完成后，运行 `npm unlink` 清理
资料来源：[README.md:26-40]()
## 总结
### 迁移检查清单
- [ ] 识别代码中硬编码的旧版工具名称
- [ ] 将 `database_id` 参数更新为 `data_source_id`
- [ ] 将搜索过滤器值从 `"database"` 更新为 `"data_source"`
- [ ] 验证 AI 客户端能自动发现新工具
- [ ] 测试数据源相关操作（查询、更新、创建）
### 关键变更一览
| 变更类别 | 变更内容 |
|---------|---------|
| API 版本 | `2022-06-28` → `2025-09-03` |
| 移除工具 | 3 个数据库工具 |
| 新增工具 | 7 个数据源和页面工具 |
| 工具总数 | 19 → 22 |
| 核心参数 | `database_id` → `data_source_id` |
| 搜索过滤器 | `database` → `data_source` |
| 页面创建 | 支持 `database_id` 作为父级 |
> **记住**：最关键的迁移点是参数名称的变更（`database_id` → `data_source_id`）和搜索过滤器值的变化。只要更新这两处，你的应用就能平滑迁移到 v2.0.0。
---
## OpenAPI 规范与文件上传
### 相关页面
相关主题：[系统架构与模块设计](#page-2), [MCP 工具集详解](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)
- [src/openapi-mcp-server/openapi/file-upload.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/file-upload.ts)
- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)
- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)
- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)
# OpenAPI 规范与文件上传
## 概述
Notion MCP Server 的核心设计理念是通过 OpenAPI 3.1.0 规范文件自动生成 MCP 工具。文件上传功能是该架构中的重要组成部分，允许用户通过 MCP 协议上传本地文件到 Notion 服务端。
本文档详细说明 OpenAPI 规范解析机制与二进制文件上传处理的实现原理。
## 架构总览
```
scripts/notion-openapi.json
↓
OpenAPI 3.1.0 规范
↓
src/openapi-mcp-server/openapi/parser.ts
↓
OpenAPI → MCP 工具转换
↓
src/openapi-mcp-server/mcp/proxy.ts
↓
MCP 工具注册与调用
↓
src/openapi-mcp-server/client/http-client.ts
↓
Notion API HTTP 请求执行
```
资料来源：[CLAUDE.md:1-30]()
## OpenAPI 规范解析机制
### 规范文件结构
`scripts/notion-openapi.json` 是整个项目的核心数据源，采用 OpenAPI 3.1.0 标准定义所有 Notion API 端点：
| 组件 | 说明 |
|------|------|
| `paths` | API 路径与方法定义 |
| `components.schemas` | 数据模型与类型定义 |
| `components.parameters` | 可复用参数定义 |
| `operationId` | 工具名称来源 |
资料来源：[CLAUDE.md:21-22]()
### Schema 转换流程
`OpenAPIToMCPConverter` 类负责将 OpenAPI Schema 转换为 MCP 可用的 JSON Schema：
```typescript
convertOpenApiSchemaToJsonSchema(
schema: OpenAPIV3.SchemaObject,
resolvedRefs: Set,
resolveRefs: boolean
): IJsonSchema
```
转换过程中包含以下关键处理：
| 特性 | 处理方式 |
|------|----------|
| 二进制格式 | 转换为 `uri-reference` |
| 对象属性 | 递归转换 `properties` |
| 数组类型 | 递归转换 `items` |
| 组合类型 | 处理 `oneOf`、`anyOf`、`allOf` |
| 常量值 | 保留 `const` 字段 |
| 默认值 | 保留 `default` 字段 |
资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-100]()
## 二进制文件与上传处理
### Binary 格式转换
当 OpenAPI Schema 中的 `format` 字段为 `binary` 时，解析器会自动进行以下转换：
```typescript
if (schema.format === 'binary') {
result.format = 'uri-reference'
const binaryDesc = 'absolute paths to local files'
result.description = schema.description
? `${schema.description} (${binaryDesc})`
: binaryDesc
}
```
此转换使得 MCP 客户端可以传入本地文件的绝对路径，系统会自动处理文件上传逻辑。
资料来源：[src/openapi-mcp-server/openapi/parser.ts:50-60]()
### 文件上传流程图
```mermaid
graph TD
A[MCP 客户端调用工具] --> B[解析参数中的 binary 字段]
B --> C{文件是否存在?}
C -->|不存在| D[抛出参数错误]
C -->|存在| E[读取本地文件内容]
E --> F[构造 multipart/form-data 请求]
F --> G[HTTP 客户端执行上传]
G --> H{响应状态}
H -->|2xx| I[返回成功结果]
H -->|4xx/5xx| J[抛出 HttpClientError]
```
## 参数反序列化机制
### 参数处理策略
`deserializeParams` 函数解决了 MCP 协议传输过程中的双重序列化问题：
| 问题场景 | 处理方式 |
|----------|----------|
| JSON 字符串对象 | 自动解析为对象 |
| JSON 字符串数组 | 自动解析为数组 |
| 嵌套 JSON 字符串 | 递归反序列化 |
| 普通字符串 | 保持原样 |
```typescript
function deserializeParams(params: Record): Record {
const result: Record = {}
for (const [key, value] of Object.entries(params)) {
if (typeof value === 'string') {
const trimmed = value.trim()
if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
(trimmed.startsWith('[') && trimmed.endsWith(']'))) {
// JSON.parse and validate...
}
}
// ... more handling
}
return result
}
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:176-210]()
### 数组元素反序列化
数组内的 JSON 字符串元素也会被递归处理：
```typescript
} else if (Array.isArray(value)) {
result[key] = value.map((item) => {
if (typeof item !== 'string') return item
// ... check and parse JSON strings in array
})
}
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:195-208]()
## HTTP 客户端与请求执行
### 请求参数分类
HTTP 客户端将参数分为三类处理：
| 参数类型 | 来源 | 用途 |
|----------|------|------|
| `urlParameters` | `path` 和 `query` 参数 | URL 路径与查询字符串 |
| `bodyParams` | `requestBody` 内容 | JSON 请求体 |
| `formData` | multipart/form-data | 文件上传表单 |
```typescript
// 提取 path 和 query 参数
if (operation.parameters) {
for (const param of operation.parameters) {
if (param.in === 'path' || param.in === 'query') {
if (params[param.name] !== undefined) {
urlParameters[param.name] = params[param.name]
}
}
}
}
// 无 requestBody 时，将 bodyParams 转为 URL 参数
if (!operation.requestBody && !formData) {
for (const key in bodyParams) {
if (bodyParams[key] !== undefined) {
urlParameters[key] = bodyParams[key]
delete bodyParams[key]
}
}
}
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:80-100]()
### 表单数据处理
当存在 `formData` 时，HTTP 客户端自动设置正确的 `Content-Type` 头：
```typescript
const hasBody = Object.keys(bodyParams).length > 0
const headers = formData
? formData.getHeaders()
: { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }
```
资料来源：[src/openapi-mcp-server/client/http-client.ts:110-115]()
## 工具注册与执行
### MCP 工具生成
`MCPProxy.setupHandlers()` 方法负责将 OpenAPI 操作转换为 MCP 工具：
```typescript
setupHandlers(tools: Record) {
this.server.setRequestHandler(ListToolsRequestSchema, async () => {
const toolDefs = []
for (const method of methods) {
toolDefs.push({
name: method.name,
description: method.description,
inputSchema: method.inputSchema,
annotations: {
title: this.operationIdToTitle(method.name),
...(isReadOnly ? { readOnlyHint: true } : { destructiveHint: true }),
},
})
}
return { tools: toolDefs }
})
}
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:150-170]()
### 工具调用处理
当 MCP 客户端调用工具时，系统执行以下步骤：
```mermaid
sequenceDiagram
客户端->>MCP服务器: CallToolRequest(name, arguments)
MCP服务器->>代理: findOperation(name)
代理-->>MCP服务器: OperationObject
MCP服务器->>参数反序列化: deserializeParams(arguments)
参数反序列化-->>MCP服务器: deserializedParams
MCP服务器->>HTTP客户端: executeOperation(operation, deserializedParams)
HTTP客户端->>Notion API: HTTP Request
Notion API-->>HTTP客户端: Response
HTTP客户端-->>MCP服务器: response.data
MCP服务器-->>客户端: { content: [{ type: 'text', text: JSON.stringify(data) }] }
```
## 错误处理
### HTTP 客户端错误
`HttpClientError` 异常包含状态码和响应数据：
```typescript
return {
content: [
{
type: 'text',
text: JSON.stringify(error.data?.response?.data ?? error.data ?? {}),
},
],
isError: true,
}
```
资料来源：[src/openapi-mcp-server/mcp/proxy.ts:200-210]()
## 配置与运行环境
### 环境变量
| 变量名 | 说明 | 优先级 |
|--------|------|--------|
| `NOTION_TOKEN` | Notion 集成令牌（推荐） | 高 |
| `OPENAPI_MCP_HEADERS` | JSON 格式的自定义请求头 | 中 |
### 命令行参数
```bash
notion-mcp-server [选项]
选项:
--transport 传输类型: 'stdio' 或 'http'
--port HTTP 服务端口 (默认: 3000)
--auth-token HTTP 传输认证令牌
--disable-auth 禁用 HTTP 认证
--help, -h 显示帮助信息
```
资料来源：[scripts/start-server.ts:60-80]()
## 开发指南
### 本地测试文件上传
1. **构建项目**：
```bash
npm run build
```
2. **链接本地包**：
```bash
npm link
```
3. **配置 MCP 客户端**：
```json
{
"mcpServers": {
"notion-local-package": {
"command": "notion-mcp-server",
"env": {
"NOTION_TOKEN": "ntn_..."
}
}
}
}
```
4. **测试文件上传**：
```
Upload file "/path/to/document.pdf" to page "My Page"
```
5. **清理**：
```bash
npm unlink
```
资料来源：[README.md:Development]()
## 相关资源
- **OpenAPI 规范文件**：[scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)
- **Notion API 版本**：`2025-09-03` (Data Source Edition)
- **API 端点类型**：
- `/v1/databases/{database_id}` - 传统数据库端点
- `/v1/data_sources/{data_source_id}` - 新数据源端点
资料来源：[CLAUDE.md:40-45]()
---
---
## Doramagic 踩坑日志
项目：makenotion/notion-mcp-server
摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。
## 1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property "in_progress" Group Options Not Recognized via API
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property "in_progress" Group Options Not Recognized via API
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。
## 8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。
## 12. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass.
## 13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。
## 14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。
## 15. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing
## 16. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium
## 17. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium
## 18. 安全/权限坑 · 来源证据：v2.1.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 20. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown
## 21. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown