企业官网建设流程全解析

Klavis 中的 Notion MCP Server：从 OpenAPI 到 MCP 工具的自动化生成机制与实战配置指南

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

本文基于 Klavis 仓库内mcp_servers/notion_official目录中的 Notion MCP Server 项目，围绕其核心设计"由 OpenAPI 规范自动生成 MCP 工具"展开：先梳理整体架构与工具生成流水线，再讲解 Notion Integration 的创建、连接与两种客户端配置方式，随后覆盖 CLI 启动参数、stdio 与 Streamable HTTP 双传输模式、OpenAPI 驱动扩展，以及 Notion API 2025-09-03 数据源（Data Source）升级带来的工具变更。读完本文，你将掌握这套服务从配置、部署到二次扩展的完整方法论。

项目定位与核心架构

mcp_servers/notion_official是 Klavis 仓库中收录的 Notion 官方 MCP Server 实现（对应 npm 包@notionhq/notion-mcp-server），其定位是"一个把 Notion API 暴露为 MCP 工具的服务端程序"。与手写每个工具的传统做法不同，它的最大特色是工具完全由一份 OpenAPI 规范自动生成，规范是唯一的事实来源（source of truth）。

整个项目的启动流程在 scripts/start-server.ts 与 src/init-server.ts 中实现，可概括为四层流水线：

scripts/notion-openapi.json # OpenAPI 3.1.0 规范（所有工具的唯一事实来源） ↓ src/init-server.ts # 读取并校验规范，创建 MCPProxy ↓ src/openapi-mcp-server/ ├── openapi/parser.ts # 将 OpenAPI 规范转换为 MCP 工具（约 529 行） ├── mcp/proxy.ts # 向 MCP SDK 注册工具并处理调用（约 209 行） └── client/http-client.ts # 实际执行对 Notion API 的 HTTP 请求（约 198 行）

init-server.ts中的initProxy依次完成：用fs.readFileSync读取scripts/notion-openapi.json，通过openapi-schema-validator校验规范，再以MCPProxy类包裹规范（init-server.ts）。若规范读取或解析失败，进程会以错误码 1 退出并打印原因。

工具自动生成流水线：OpenAPI 到 MCP 的完整转换

工具生成的核心实现在 src/openapi-mcp-server/openapi/parser.ts 的OpenAPIToMCPConverter.convertToMCPTools()方法中，其流程与 CLAUDE.md 描述的完全一致：

1. 遍历所有路径与操作：convertToMCPTools()迭代openApiSpec.paths中的每个pathItem，过滤出get/post/put/delete/patch五类 HTTP 方法，其余（如parameters、servers等路径项）直接跳过。
2. 每个操作对应一个 MCP 工具：工具名取自操作的operationId。例如retrieve-a-database、query-data-source等（从 scripts/notion-openapi.json 可看到全部 22 个operationId）。
3. 参数与请求体 →inputSchema：路径参数、查询参数与requestBody中的application/json、multipart/form-data结构都会被展开为 JSON Schema 的properties与required数组，供 MCP 客户端做参数校验与补全。
4. 响应结构 →returnSchema：extractResponseType()优先取 200/201/202/204 状态码下的application/jsonschema 作为返回结构，若响应为image/png、image/jpeg则退化为string类型的 binary 描述。
5. 注册工具：MCPProxy.setupHandlers()通过ListToolsRequestSchema与CallToolRequestSchema两个处理器把转换结果注册进 MCP SDK。

值得注意的细节：

• 错误响应被织入工具描述：转换时会把 4xx/5xx 状态码及其描述追加到工具 description 末尾（Error Responses:段落），让 AI 客户端在规划调用时就能预知失败形态。
• $ref递归解析与缓存：convertOpenApiSchemaToJsonSchema对组件引用做了缓存（schemaCache），并用resolvedRefs集合防环，确保递归 schema 能被安全转换。
• 文件名截断规则：工具名先由proxy.ts的truncateToolName截断到 64 字符，再由operationIdToTitle把 camelCase 拆分为可读标题（如createDatabase→Create Database），parser.ts的ensureUniqueName则负责在重名时追加-0001风格后缀。
• 调用时的参数反序列化：proxy.ts中的deserializeParams会递归地把被客户端二次序列化成 JSON 字符串的对象/数组参数还原为真实对象，修复了 Cursor、Claude Code 等客户端常见的双重序列化问题（见 proxy.ts）。

关键配置项：认证头与 API 版本

工具在构造HttpClient时决定如何携带认证信息，优先级逻辑位于 proxy.ts 的parseHeadersFromEnv：

需要说明：parseHeadersFromEnv中硬编码的版本号仍是2022-06-28，而本项目规范声明的 API 版本为2025-09-03（Data Source Edition）。因此当你使用OPENAPI_MCP_HEADERS方式配置时，务必像官方 README 示例那样在 JSON 中显式带上"Notion-Version": "2025-09-03"，否则请求可能命中旧版 API 语义，与工具生成的输入输出结构不一致。

HTTP 请求的真正执行落在 src/openapi-mcp-server/client/http-client.ts：HttpClient基于openapi-client-axios根据规范生成 API 客户端，executeOperation会按参数的in（path/query）与requestBody拆分 URL 参数和请求体，并正确设置Content-Type；文件上传类操作则通过prepareFileUpload把本地文件路径转成multipart/form-data流。请求失败时会抛出携带状态码与响应体的HttpClientError，由proxy.ts转为结构化的 MCP 错误文本返回给客户端。

环境准备：创建并连接 Notion Integration

服务端本身不需要任何配置，真正的前置工作在 Notion 侧。官方 README（README.md）给出的三步流程如下：

1. 创建内部 Integration

登录 Notion 开发者后台创建新的internalintegration（或复用已有的）。由于 MCP 会把工作区数据暴露给 LLM，即使服务端已限制部分高危能力（例如不能通过 MCP 删除数据库），仍存在非零的数据风险。安全敏感的用户应进一步收紧 Integration 的Capabilities——例如在"Configuration"标签页只勾选 "Read content"，即可得到一个只读令牌。

2. 把内容连接到 Integration

在 Integration 设置的Access标签页编辑访问权限，勾选希望暴露给 AI 的页面；也可以进入目标页面，点击右上角"..."菜单选择 "Connect to integration" 逐个授权。

3. 获取令牌

从 Integration 的 Configuration 标签页复制形如ntn_****的 secret，替换下文所有配置中的占位符。

注意：Notion 官方已在推广远程版Notion MCP（基于标准 OAuth 安装、面向 AI Agent 优化、按 token 消耗设计），并声明只对远程版提供积极支持，本仓库（本地版）未来可能被下线，Issue/PR 不再被积极维护。如果你的场景以 OAuth 远程接入为主，建议优先评估官方 Notion MCP 文档；本文所述内容适用于在 Klavis 中自行部署本地 MCP Server 的场景。

客户端接入：npx 与 Docker 两种部署形态

形态一：npx 直跑

在.cursor/mcp.json（Cursor）或claude_desktop_config.json（Claude Desktop，macOS 路径为~/Library/Application Support/Claude/claude_desktop_config.json）中追加：

推荐方式：NOTION_TOKEN环境变量

{ "mcpServers": { "notionApi": { "command": "npx", "args": ["-y", "@notionhq/notion-mcp-server"], "env": { "NOTION_TOKEN": "ntn_****" } } } }

进阶方式：OPENAPI_MCP_HEADERS（完全控制请求头）

{ "mcpServers": { "notionApi": { "command": "npx", "args": ["-y", "@notionhq/notion-mcp-server"], "env": { "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }" } } } }

Zed 的配置位置在settings.json，把mcpServers换成context_servers并套一层command对象即可；GitHub Copilot CLI 可用/mcp add交互式添加，或直接编辑~/.copilot/mcp-config.json（写法与 Cursor 相同，推荐NOTION_TOKEN方式）。

形态二：Docker 部署

使用官方镜像mcp/notion（推荐，环境变量传值可规避 JSON 转义问题）：

{ "mcpServers": { "notionApi": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN", "mcp/notion"], "env": { "NOTION_TOKEN": "ntn_****" } } } }

本地构建镜像：仓库根目录下执行docker compose build（对应的 docker-compose.yml 配置了stdin_open: true与tty: true以支持 stdio 交互），随后在客户端配置中指向本地镜像notion-mcp-server：

{ "mcpServers": { "notionApi": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN=ntn_****", "notion-mcp-server"] } } }

若本地部署，建议先查看 Dockerfile：它以 Node 20 slim 为基础镜像、npm ci --omit-dev安装依赖、npm link全局链接 CLI，并在运行时阶段以--transport http --port 5000 --disable-auth作为默认入口——这与你手动配置的客户端启动方式不同，需按你的传输需求对齐。

本地调试：在仓库根目录执行npm link建立全局符号链接，再把客户端配置中的命令改成notion-mcp-server并注入NOTION_TOKEN，即可用本地改动调试；结束后执行npm unlink清理。

传输模式与命令行参数

启动入口 start-server.ts 支持两种传输模式，完整参数如下（也可见--help输出）：

环境变量：NOTION_TOKEN（Notion 集成令牌，推荐）、OPENAPI_MCP_HEADERS（Notion API 请求头的 JSON 串，备选）、AUTH_TOKEN（HTTP 传输鉴权令牌，备选）、BASE_URL（覆盖规范中的 API 基地址，用于代理/镜像场景）。

stdio 模式（默认）

npx @notionhq/notion-mcp-server # 默认 stdio npx @notionhq/notion-mcp-server --transport stdio # 显式指定

这是大多数桌面客户端（Claude Desktop 等）使用的标准 MCP 传输方式，客户端以子进程方式拉起服务并通过标准输入输出通信。

Streamable HTTP 模式

npx @notionhq/notion-mcp-server --transport http # 端口 3000 npx @notionhq/notion-mcp-server --transport http --port 8080 npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

启动后端点位于http://0.0.0.0:<port>/mcp，另有免鉴权的健康检查端点GET /health。该模式采用无状态（stateless）模型：每次 POST/mcp都会新建 proxy 与 transport 实例、请求完成后即关闭（见 start-server.ts），因此GET/DELETE /mcp一律返回 405。

HTTP 模式鉴权有三种令牌来源，优先级从高到低为：--auth-token命令行参数 >AUTH_TOKEN环境变量 > 自动生成的随机令牌（randomBytes(32)，启动时打印到控制台）：

Generated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab Use this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789ab

请求示例（需带mcp-session-id，鉴权失败返回 JSON-RPC 错误码 -32001/-32002）：

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

开发期可直接用自动生成令牌；生产环境推荐显式传--auth-token或AUTH_TOKEN。此外 HTTP 模式还支持通过x-auth-data请求头（base64 编码的 JSON，含access_token字段）或AUTH_DATA环境变量为每次请求注入 Notion 令牌，便于网关统一管理多租户凭据（见 start-server.ts）。

OpenAPI 驱动的扩展方式：新增端点只需改规范

得益于"规范即事实来源"的架构，扩展能力不需要写任何 TypeScript 代码：CLAUDE.md 明确指出，新增端点时只修改scripts/notion-openapi.json，重启后新工具即被自动发现。

该文件是 OpenAPI 3.1.0 规范（info.title为 "Notion API"，版本 2.0.0，服务器基地址https://api.notion.com），定义了两个安全方案：bearerAuth（HTTP Bearer）与basicAuth。规范的components.parameters.notionVersion声明了Notion-Version请求头，默认值为2025-09-03。

这套转换逻辑并非 Notion 专用——OpenAPIToMCPConverter的输入是任意合法 OpenAPI 文档，proxy.ts中的getDescription也只为info.title === 'Notion API'的规范添加"Notion | "前缀。因此该目录下从 fork 演进的 openapi-mcp-server 模块 可以视为一个通用"OpenAPI → MCP"转换器，parser.ts内还同时提供了convertToOpenAITools与convertToAnthropicTools，可将同一份规范输出为 OpenAI ChatCompletion 工具与 Anthropic 工具格式，便于跨平台复用。

版本升级：Notion API 2025-09-03 与 Data Source 迁移

项目版本 2.0.0 起迁移到 Notion API2025-09-03（Data Source Edition），将"数据源（data source）"作为数据库的新一等抽象。共 22 个工具（v1.x 为 19 个），具体变更如下：

移除的 3 个工具（旧数据库操作）：

• post-database-query→ 由query-data-source取代
• update-a-database→ 由update-a-data-source取代
• create-a-database→ 由create-a-data-source取代

新增的 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：获取数据库元数据（含其 data source ID 列表）

参数变更：

• 所有数据库操作的参数由database_id改为data_source_id
• Search 的过滤值从["page", "database"]变为["page", "data_source"]
• 创建页面时parent同时支持page_id与database_id两种父级

迁移成本：客户端无需任何代码改动——MCP 工具在服务启动时自动发现，升级到 v2.0.0 后 AI 客户端自动看到新工具名与新参数，旧数据库工具不再可用。仅当你在提示词或代码里硬编码了旧工具名时，才需要按下表更新：

注意retrieve-a-database仍然保留，用于获取含 data source ID 列表的数据库元数据；要获取某个数据源的具体 schema 与属性，应改用retrieve-a-data-source。

实战示例与测试

接入完成后，向 AI 客户端下发自然语言指令即可看到工具编排效果（README 中的官方示例）：

1. 指令Comment "Hello MCP" on page "Getting started"——AI 会规划两次 API 调用v1/search与v1/comments完成任务。
2. 指令Add a page titled "Notion MCP" to page "Development"——AI 会在父页面 "Development" 下新建页面。
3. 直接引用内容 ID：Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2。

仓库自带完整的测试体系保障这些行为，测试位于源码旁的__tests__目录，覆盖三条主线：

• parser 测试：schema 转换、$ref解析、multipart 文件上传参数的生成（另有 parser-multipart.test.ts 与 file-upload.test.ts）。
• proxy 测试：工具注册、参数反序列化、错误响应转换。
• http-client 测试：请求/响应处理与文件上传（含 http-client.integration.test.ts 集成测试）。

开发与自检命令速查

npm run build # TypeScript 编译 + CLI 打包（scripts/build-cli.js） npm test # 运行 vitest 测试 npm run dev # tsx watch 热重载启动开发服务器 npm run test:watch # 监听模式运行测试 npm run test:coverage # 生成测试覆盖率报告

开发期在本地验证完整流程：先在仓库根目录执行npm link，再在 Cursor 的mcp.json中配置：

{ "mcpServers": { "notion-local-package": { "command": "notion-mcp-server", "env": { "NOTION_TOKEN": "ntn_..." } } } }

最后执行npm unlink清理全局链接。发布新版本时则依次执行npm login与npm publish --access public。

总结

在 Klavis 的mcp_servers/notion_official中，Notion MCP Server 展示了一种高可维护的 MCP 服务端设计范式：以 OpenAPI 3.1.0 规范为单一事实来源，通过 parser.ts 自动生成 MCP 工具、proxy.ts 注册与分发调用、http-client.ts 执行真实请求，新增能力只需改规范、无需改代码。配合 Notion API 2025-09-03 的 Data Source 迁移、stdio/Streamable HTTP 双传输模式以及灵活的环境变量鉴权，这套服务既适合桌面客户端快速接入，也适合在 Klavis 中以 Docker 形态进行远程部署与多租户管理。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis