使用说明

项目简介

该仓库实现了一个基于 Model Context Protocol (MCP) 的服务器端应用，用于为 AI 客户端提供对 Notion 的统一上下文服务。核心功能包括：托管和管理资源（资源/数据访问）、注册和执行工具（外部功能调用）、定义和渲染提示模板等。服务器通过 JSON-RPC 与客户端通信，支持多种传输方式（此实现以标准输入/输出（stdio）为传输通道，便于与 AI 代理集成进行本地开发与调试）。

主要功能点

MCP 服务器实现
- 使用 @modelcontextprotocol/sdk 提供的 Server、StdioServerTransport，以及 ListTools/CallTool 请求处理能力
- 注册并暴露 7 个 Mega Tools 的 composite 工具集合，覆盖 Notion 的核心工作流
工具集合（7 Mega Tools）
- pages、databases、blocks、users、workspace、comments、content_convert
- 支持创建、获取、更新、归档、复制等操作，以及数据库的数据源、数据结构转换等高级能力
组合工具设计
- 针对 Notion 的复杂操作采用组合实现，减少对外暴露的单体接口数量
- 自动分页、批量操作、智能查询等能力，提升对 AI 客户端的可用性
错误处理与可观测性
- 详细的错误封装与 AI-友好错误信息，帮助上层代理快速定位问题
运行与打包
- 提供用于启动服务器的脚本和构建 CLI 的脚本，便于本地快速启动与分发

安装步骤

准备工作
- 需要 Node.js 环境
- 获取 Notion 集成 Token，并设置环境变量 NOTION_TOKEN
安装依赖
- 在本仓库根目录执行依赖安装（如 npm 或 pnpm 安装命令）
启动服务器
- 使用开发模式启动，监听标准输入/输出传输，便于和 AI 客户端集成进行调试
验证运行
- 启动后通过 MCP 客户端发送 JSON-RPC 请求，检查 Tools 列表与 Tool 调用是否返回结构化结果

服务器配置（给 MCP 客户端的配置示例说明）

说明：MCP 客户端不需要运行该服务器，但若需通过配置管理来启动 MCP 服务器，请按下面的 JSON 结构配置，并在相应位置替换 token/路径等信息。

配置要点

server name: 与仓库内部标识保持一致，以便客户端正确识别
command: 启动命令，例如使用 npx 拉取并执行对应的 MCP 服务器包
args: 启动参数，包含版本及开启方式
env: 环境变量，其中 NOTION_TOKEN 需填写为你的 Notion 集成 Token

示例（JSON 格式，含字段注释，供参考；实际使用时不需要代码块）: { "server": { "name": "@n24q02m/better-notion-mcp", "version": "1.0.0" }, "mcpServers": { "better-notion": { "command": "npx", "args": ["-y", "@n24q02m/better-notion-mcp@latest"], "env": { "NOTION_TOKEN": "your_token_here" } } } }

基本使用方法

启动后，MCP 客户端可通过 JSON-RPC 请求与服务器交互，调用注册的工具集合
首先通过 ListTools 接口获取可用工具列表（名称包括 pages、databases、blocks、users、workspace、comments、content_convert）
通过 CallTool 接口按名称执行工具，传入 actions 所需的输入参数，服务器会返回结构化结果
如遇 Notion API 权限、参数格式等问题，系统会返回 AI 友好错误信息和修复建议

运行与调试注意

请确保环境变量 NOTION_TOKEN 设置正确且令牌具备对相应页面/数据库的访问权限
开发环境可使用脚本启动（如 pnpm dev），生产环境可通过打包后启动执行
本实现以 StdIO 传输为 MCP 服务器的通信通道，便于与本地 AI 代理/工具链集成进行调试

关键词