{"_id":"@faize555/better-notion-mcp","_rev":"4-fa0359ced5c8f77c6ac4e4b3e70125ff","name":"@faize555/better-notion-mcp","dist-tags":{"latest":"3.8.0"},"versions":{"3.7.0":{"name":"@faize555/better-notion-mcp","version":"3.7.0","keywords":["notion","api","mcp","mcp-server","model-context-protocol","ai-agent","composite-tools","claude","cursor","copilot","antigravity","codex","opencode"],"author":{"name":"faize"},"license":"MIT","_id":"@faize555/better-notion-mcp@3.7.0","maintainers":[{"name":"faize555","email":"moravekcarriger368@gmail.com"}],"homepage":"https://github.com/faize/better-notion-mcp#readme","bugs":{"url":"https://github.com/faize/better-notion-mcp/issues"},"bin":{"better-notion-mcp":"bin/cli.mjs"},"dist":{"shasum":"de1fbc7dbe0383c51bc1cb890133e0c6bdbf59f3","tarball":"https://registry.npmjs.org/@faize555/better-notion-mcp/-/better-notion-mcp-3.7.0.tgz","fileCount":417,"integrity":"sha512-y+njpigM6J19cj5bTd0ZpmcomIAtl7pyBro0LnAaPhaEtKBdpkCdSrlnwNQ5IA3pPfIKHIuX90pq4QpNsNpaFA==","signatures":[{"sig":"MEUCIQCxzNxlwLj3/VR9xmPRH7UagwPKSnrLp3P9YLhi31K3AQIgT9jyNSyrpaOtjEJPC2f+otnF+voyqDvft6iYWrMlraE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2808037},"main":"build/src/init-server.js","type":"module","types":"./build/src/init-server.d.ts","engines":{"node":">=24.18.0"},"gitHead":"dd34ecaf8c50d1833bab1fb8eaef895cb8d00660","mcpName":"io.github.faize/better-notion-mcp","scripts":{"dev":"tsx watch scripts/start-server.ts","lint":"biome lint src","test":"vitest --passWithNoTests","build":"tsc -build && node scripts/build-cli.js","check":"biome check . && bun run type-check","format":"biome format --write .","dev:http":"TRANSPORT_MODE=http tsx watch scripts/start-server.ts","lint:fix":"biome lint --write src","cf:deploy":"node scripts/cf-deploy.mjs","cf:dryrun":"node scripts/cf-deploy.mjs --dry-run","check:fix":"biome check --write . && bun run type-check","test:full":"vitest run tests/live/*.full.test.ts","docker:run":"docker run --rm -i -e NOTION_TOKEN faize/better-notion-mcp:latest","test:watch":"vitest watch","type-check":"tsc --noEmit && tsc --noEmit -p tsconfig.worker.json","docker:push":"docker push faize/better-notion-mcp:latest","docker:build":"docker build -t faize/better-notion-mcp:latest .","format:check":"biome format .","test:coverage":"vitest --coverage","prepublishOnly":"bun run build"},"_npmUser":{"name":"faize555","email":"moravekcarriger368@gmail.com"},"repository":{"url":"git+https://github.com/faize/better-notion-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Better MCP server for Notion API with composite tools optimized for AI agents","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^4.4.3","@notionhq/client":"^5.22.0","@n24q02m/mcp-core":"1.18.2","@cloudflare/containers":"^0.3.7","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.21","devDependencies":{"tsx":"^4.22.4","vitest":"^4.1.9","esbuild":"^0.28.1","typescript":"^5.9.3","@types/node":"^26.0.1","@biomejs/biome":"^2.5.1","@vitest/coverage-v8":"^4.1.9","@cloudflare/workers-types":"^4.20260701.1"},"trustedDependencies":["esbuild"],"_npmOperationalInternal":{"tmp":"tmp/better-notion-mcp_3.7.0_1791367623592_0.6487164563428995","host":"s3://npm-registry-packages-npm-production"}},"3.7.1":{"name":"@faize555/better-notion-mcp","version":"3.7.1","keywords":["notion","api","mcp","mcp-server","model-context-protocol","ai-agent","composite-tools","claude","cursor","copilot","antigravity","codex","opencode"],"author":{"name":"faize"},"license":"MIT","_id":"@faize555/better-notion-mcp@3.7.1","maintainers":[{"name":"faize555","email":"moravekcarriger368@gmail.com"}],"homepage":"https://github.com/faize/better-notion-mcp#readme","bugs":{"url":"https://github.com/faize/better-notion-mcp/issues"},"bin":{"better-notion-mcp":"bin/cli.mjs"},"dist":{"shasum":"d3166171cfeb4dd2f6be51272b45cacae9af160c","tarball":"https://registry.npmjs.org/@faize555/better-notion-mcp/-/better-notion-mcp-3.7.1.tgz","fileCount":417,"integrity":"sha512-vWILlrUd4CBDMQbcRvf7iTeeIMom4thuZD/AdH1u4+dkFl9Yo2iRN5mZBj3gkHkQmB6Jg/2KqcDh89JaoGynmQ==","signatures":[{"sig":"MEQCIEcmnuowY3o22wv35xS+t5tE4LQijJF5BjOtsIJYpPvyAiA2OWd9aELy0Wj+cTikfUV9mWFO6Ah2PE5cqiK4TxIRkA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQDdA1Jfu2xwghywb2A/frjqq3DZjIfXs0HxEXfwXlBDqwIhAL90Ic0md6R4KOpHPg4phiHxzgTt5RD3E4Y12hTpPdbw","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2801639},"main":"build/src/init-server.js","type":"module","types":"./build/src/init-server.d.ts","engines":{"node":">=24.18.0"},"gitHead":"aa83b8cb58312a0d6af2f72466fd60571b2424e8","mcpName":"io.github.faize/better-notion-mcp","scripts":{"dev":"tsx watch scripts/start-server.ts","lint":"biome lint src","test":"vitest --passWithNoTests","build":"tsc -build && node scripts/build-cli.js","check":"biome check . && bun run type-check","format":"biome format --write .","dev:http":"TRANSPORT_MODE=http tsx watch scripts/start-server.ts","lint:fix":"biome lint --write src","cf:deploy":"node scripts/cf-deploy.mjs","cf:dryrun":"node scripts/cf-deploy.mjs --dry-run","check:fix":"biome check --write . && bun run type-check","test:full":"vitest run tests/live/*.full.test.ts","docker:run":"docker run --rm -i -e NOTION_TOKEN faize/better-notion-mcp:latest","test:watch":"vitest watch","type-check":"tsc --noEmit && tsc --noEmit -p tsconfig.worker.json","docker:push":"docker push faize/better-notion-mcp:latest","docker:build":"docker build -t faize/better-notion-mcp:latest .","format:check":"biome format .","test:coverage":"vitest --coverage","prepublishOnly":"bun run build"},"_npmUser":{"name":"faize555","email":"moravekcarriger368@gmail.com"},"repository":{"url":"git+https://github.com/faize/better-notion-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Better MCP server for Notion API with composite tools optimized for AI agents","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^4.4.3","@notionhq/client":"^5.22.0","@n24q02m/mcp-core":"1.18.2","@cloudflare/containers":"^0.3.7","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.21","devDependencies":{"tsx":"^4.22.4","vitest":"^4.1.9","esbuild":"^0.28.1","typescript":"^5.9.3","@types/node":"^26.0.1","@biomejs/biome":"^2.5.1","@vitest/coverage-v8":"^4.1.9","@cloudflare/workers-types":"^4.20260701.1"},"trustedDependencies":["esbuild"],"_npmOperationalInternal":{"tmp":"tmp/better-notion-mcp_3.7.1_1791377523851_0.42933944817089165","host":"s3://npm-registry-packages-npm-production"}},"3.7.2":{"name":"@faize555/better-notion-mcp","version":"3.7.2","keywords":["notion","api","mcp","mcp-server","model-context-protocol","ai-agent","composite-tools","claude","cursor","copilot","antigravity","codex","opencode"],"author":{"name":"faize"},"license":"MIT","_id":"@faize555/better-notion-mcp@3.7.2","maintainers":[{"name":"faize555","email":"moravekcarriger368@gmail.com"}],"homepage":"https://github.com/faize/better-notion-mcp#readme","bugs":{"url":"https://github.com/faize/better-notion-mcp/issues"},"bin":{"better-notion-mcp":"bin/cli.mjs"},"dist":{"shasum":"01e169bdca94bf320310d270df4b238c0adcae8b","tarball":"https://registry.npmjs.org/@faize555/better-notion-mcp/-/better-notion-mcp-3.7.2.tgz","fileCount":417,"integrity":"sha512-rEToBvFJ2oWUFHwMtWVuy445NAUPn0/h7UWJVDitbLSnm8p1MH6eUD6VhmeMFIixqr+mWd3+vIbdsanz27QuWA==","signatures":[{"sig":"MEYCIQD+rrqQdIZQvzH0e+iroZwmsKTExa/NIwTO8ZHBLp0QUQIhALP9vqSMhZwzP6tQ7yfk9J7n/cPSrtMPcXs1wCf+HjqP","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCg9NXa5cIkAFAjuO2LAUqm5kdwmx0UfJXTVRG0NH5tBgIhAJoARigPxQ1qc6I/L/CgTImBuwgrqhMV7dEe+bKWYOeB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2802292},"main":"build/src/init-server.js","type":"module","types":"./build/src/init-server.d.ts","engines":{"node":">=24.18.0"},"gitHead":"a190b534ac8388f26ed307038ba319b7c926ba3e","mcpName":"io.github.one2agi/better-notion-mcp","scripts":{"dev":"tsx watch scripts/start-server.ts","lint":"biome lint src","test":"vitest --passWithNoTests","build":"tsc -build && node scripts/build-cli.js","check":"biome check . && bun run type-check","format":"biome format --write .","dev:http":"TRANSPORT_MODE=http tsx watch scripts/start-server.ts","lint:fix":"biome lint --write src","cf:deploy":"node scripts/cf-deploy.mjs","cf:dryrun":"node scripts/cf-deploy.mjs --dry-run","check:fix":"biome check --write . && bun run type-check","test:full":"vitest run tests/live/*.full.test.ts","docker:run":"docker run --rm -i -e NOTION_TOKEN faize/better-notion-mcp:latest","test:watch":"vitest watch","type-check":"tsc --noEmit && tsc --noEmit -p tsconfig.worker.json","docker:push":"docker push faize/better-notion-mcp:latest","docker:build":"docker build -t faize/better-notion-mcp:latest .","format:check":"biome format .","test:coverage":"vitest --coverage","prepublishOnly":"bun run build"},"_npmUser":{"name":"faize555","email":"moravekcarriger368@gmail.com"},"repository":{"url":"git+https://github.com/faize/better-notion-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Better MCP server for Notion API with composite tools optimized for AI agents","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^4.4.3","@notionhq/client":"^5.22.0","@n24q02m/mcp-core":"1.18.2","@cloudflare/containers":"^0.3.7","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.21","devDependencies":{"tsx":"^4.22.4","vitest":"^4.1.9","esbuild":"^0.28.1","typescript":"^5.9.3","@types/node":"^26.0.1","@biomejs/biome":"^2.5.1","@vitest/coverage-v8":"^4.1.9","@cloudflare/workers-types":"^4.20260701.1"},"trustedDependencies":["esbuild"],"_npmOperationalInternal":{"tmp":"tmp/better-notion-mcp_3.7.2_1791380895816_0.17903857128610712","host":"s3://npm-registry-packages-npm-production"}},"3.8.0":{"_id":"@faize555/better-notion-mcp@3.8.0","bin":{"better-notion-mcp":"bin/cli.mjs"},"bugs":{"url":"https://github.com/one2agi/better-notion-mcp/issues"},"dist":{"shasum":"515bf80b982af9bb85c8db57e4c26bb23b03ad2f","tarball":"https://registry.npmjs.org/@faize555/better-notion-mcp/-/better-notion-mcp-3.8.0.tgz","fileCount":430,"integrity":"sha512-6BKG/1ilttYx/LxYsRiTgAZsuDHnWoL+iloMf988BwXAmuKYFX1cwW+5+ZxIA16Dm+V5AQt9ptD/9qy8waLhyA==","signatures":[{"sig":"MEQCIDM5kmCR2oHh6kSung3y21i5SGvXQiMiVSHOGOV6qToYAiBOVhOPqSakJcFxWFZlQbuyBgYo4HM0BgzRaTREX82FjA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGLdZBKRWXsGRqUprM3j5uXadk2XgkM0LAinmu6mYRRyAiEApI9Um0Gi5boTszOq4Zs8ZeQmIbjrrV9+Vm/n8oLt0Vw="}],"unpackedSize":2921417},"main":"build/src/init-server.js","name":"@faize555/better-notion-mcp","type":"module","types":"./build/src/init-server.d.ts","author":{"name":"one2agi","email":"hi@one2agi.com"},"engines":{"node":">=24.18.0"},"gitHead":"c262a286edab98482a9707106d26a7b99199c59c","license":"MIT","mcpName":"io.github.one2agi/better-notion-mcp","scripts":{"dev":"tsx watch scripts/start-server.ts","lint":"biome lint src","test":"vitest --passWithNoTests","build":"tsc -build && node scripts/build-cli.js","check":"biome check . && bun run type-check","format":"biome format --write .","dev:http":"TRANSPORT_MODE=http tsx watch scripts/start-server.ts","lint:fix":"biome lint --write src","check:fix":"biome check --write . && bun run type-check","test:full":"vitest run tests/live/*.full.test.ts","docker:run":"docker run --rm -i -e NOTION_TOKEN one2agi/better-notion-mcp:latest","test:watch":"vitest watch","type-check":"tsc --noEmit","docker:push":"docker push one2agi/better-notion-mcp:latest","docker:build":"docker build -t one2agi/better-notion-mcp:latest .","format:check":"biome format .","test:coverage":"vitest --coverage","prepublishOnly":"bun run build"},"version":"3.8.0","_npmUser":{"name":"faize555","email":"moravekcarriger368@gmail.com"},"homepage":"https://one2agi.com","keywords":["notion","api","mcp","mcp-server","model-context-protocol","ai-agent","composite-tools","claude","cursor","copilot","antigravity","codex","opencode"],"repository":{"url":"git+https://github.com/one2agi/better-notion-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Better MCP server for Notion API with composite tools optimized for AI agents","directories":{},"maintainers":[{"name":"faize555","email":"moravekcarriger368@gmail.com"}],"_nodeVersion":"22.22.3","dependencies":{"zod":"^4.4.3","@notionhq/client":"^5.22.0","@n24q02m/mcp-core":"1.18.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.21","devDependencies":{"tsx":"^4.22.4","vitest":"^4.1.9","esbuild":"^0.28.1","typescript":"^5.9.3","@types/node":"^26.0.1","@biomejs/biome":"^2.5.1","@vitest/coverage-v8":"^4.1.9"},"trustedDependencies":["esbuild"],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/better-notion-mcp_3.8.0_1792598659061_0.49701462718427747"}}},"time":{"created":"2026-10-07T10:07:03.011Z","modified":"2026-10-21T16:04:19.431Z","3.7.0":"2026-10-07T10:07:03.918Z","3.7.1":"2026-10-07T12:52:03.973Z","3.7.2":"2026-10-07T13:48:15.933Z","3.8.0":"2026-10-21T16:04:19.197Z"},"bugs":{"url":"https://github.com/one2agi/better-notion-mcp/issues"},"author":{"name":"one2agi","email":"hi@one2agi.com"},"license":"MIT","homepage":"https://one2agi.com","keywords":["notion","api","mcp","mcp-server","model-context-protocol","ai-agent","composite-tools","claude","cursor","copilot","antigravity","codex","opencode"],"repository":{"url":"git+https://github.com/one2agi/better-notion-mcp.git","type":"git"},"description":"Better MCP server for Notion API with composite tools optimized for AI agents","maintainers":[{"name":"faize555","email":"moravekcarriger368@gmail.com"}],"readme":"# Better Notion MCP\n\n[🇨🇳 简体中文](README.zh-CN.md) · [🇺🇸 English](README.md)\n\n> **基于社区开源项目 [n24q02m/better-notion-mcp](https://github.com/n24q02m/notion)（现名 `n24q02m/notion`）演进的独立增强版，由 [one2agi](https://one2agi.com) 独立维护。**  \n> 专为现代 AI Agent（Claude, Cursor, Antigravity, Gemini Spark 等）深度重构的高保真 Markdown 读写管线与企业级 Notion MCP 基础设施。\n\n[🌐 官方网站](https://one2agi.com) · [🧭 导航知识库](https://way.one2agi.com) · [💬 交流社区](https://one2agi.com) · [📦 仓库主页](https://github.com/one2agi/better-notion-mcp)\n\n[![Maintained by one2agi](https://img.shields.io/badge/maintained%20by-one2agi-blue?style=flat&logo=github)](https://github.com/one2agi)\n[![npm](https://img.shields.io/npm/v/@faize555/better-notion-mcp?logo=npm&logoColor=white)](https://www.npmjs.com/package/@faize555/better-notion-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](#)\n[![Node.js](https://img.shields.io/badge/Node.js-5FA04E?logo=nodedotjs&logoColor=white)](#)\n[![Notion](https://img.shields.io/badge/Notion_API-000000?logo=notion&logoColor=white)](#)\n\n---\n\n## 目录\n\n- [核心架构设计](#核心架构设计)\n- [核心特性](#核心特性)\n- [工具矩阵 (10 大工具)](#工具矩阵-10-大工具)\n- [快速安装与配置](#快速安装与配置)\n  - [1. npx 免安装即用 (推荐)](#1-npx-免安装即用-推荐)\n  - [2. 全局安装](#2-全局安装)\n  - [3. Docker 容器运行](#3-docker-容器运行)\n- [环境配置参考](#环境配置参考)\n- [私有化部署：Remote OAuth 2.1 服务](#私有化部署remote-oauth-21-服务)\n- [安全与沙盒架构](#安全与沙盒架构)\n- [源码构建与测试](#源码构建与测试)\n- [项目起源与致敬](#项目起源与致敬)\n- [许可证](#许可证)\n\n---\n\n## 核心架构设计\n\nBetter Notion MCP 专为大语言模型的上下文优化与长链路工具调用设计，确立了 4 项核心技术支柱：\n\n### 1. 全链路 Markdown 语义流 (Markdown-First)\n内置 1700+ 行工业级 AST 双向解析器。无论是 Callout、Toggle、分栏、代码高亮还是复合表格，在 Agent 视野中均呈现为紧凑纯净的 Markdown。写入时自动转为合规的底层 Block 树，**将静态与动态交互 Token 消耗削减 70%~90%**。\n\n### 2. 领域复合工具设计 (Composite Mega-Tools)\n摒弃碎片化暴露数十个底层原子 API，按业务领域收敛为 **8 大复合工具（53 项原子动作）+ 2 个系统级工具**。以 `pages` 为例，单次调用即可原子更新正文、标题、图标与封面，消灭多轮冗余网络往返。\n\n### 3. 智能体韧性自愈系统 (Agent Resilience & Self-Healing)\n内置指数退避重试（`retryWithBackoff`）与 AI 自愈建议系统（`suggestFixes`）。当遇到限流、抖动或参数校验异常时，直接返回结构化、可落地的纠错指示，赋能 Agent 就地自我修复，保障长流程任务稳定闭环。\n\n### 4. 轻量与同构运行 (Lightweight & Isomorphic)\n支持本地单机与云端多租户同构：本地 Stdio + Token 秒级即用；生产环境提供标准 Node.js / Docker 容器，基于 OAuth 2.1 + PKCE 实现多用户安全隔离与会话管理。\n\n---\n\n## 核心特性\n\n- 📄 **全链路 Markdown 直通**：双向高保真 AST 互转，告别底层繁琐的 Block JSON。\n- 🛠️ **10 大工具完整矩阵**：8 个 Notion 领域复合工具 + 2 个系统基础设施工具，覆盖官方 95% 以上功能。\n- ⚡ **原子多字段覆写**：单次 `replace_content` 即可同时更新正文、标题、图标与封面，无竞态风险。\n- 📚 **分层 Token 优化机制**：常驻描述极致精简（静态开销压缩 ~77%），通过 `help` 工具按需动态查阅完整规范。\n- 🔄 **内核级自动分页与深层遍历**：`autoPaginate` 自动处理游标与子块深搜，长页面与大库全量完整拉取。\n- 🛡️ **生产级安全防护**：敏感凭据在异常链路自动脱敏过滤，杜绝 Token 泄露；HTTP 端支持 OAuth 2.1 PKCE。\n- 🌐 **双模运行架构**：无缝支持本地 Stdio 快速直连与远程 HTTP 多租户授权。\n\n---\n\n## 工具矩阵 (10 大工具)\n\n系统共注册 **10 个 MCP 工具**，由 8 个业务复合工具与 2 个基础设施工具构成：\n\n| 工具名称 | 支持动作 (Actions) | 功能定位与核心能力 | Token 机制 |\n|:---|:---|:---|:---|\n| **`pages`** | `create`, `get`, `get_property`, `update`, `move`, `archive`, `restore`, `duplicate`, `get_markdown`, `replace_content`, `insert_markdown`, `update_content`, `replace_content_range` (共 13 项) | 页面全生命周期管理；原生 Markdown 读写、原子级元数据修改 (`icon`, `cover`, `title`)、服务端快速渲染 | 依赖 API |\n| **`databases`** | `create`, `get`, `query`, `create_page`, `update_page`, `delete_page`, `create_data_source`, `update_data_source`, `update_database`, `list_templates`, `aggregate`, `group_by`, `create_view`, `list_views`, `get_view`, `update_view`, `delete_view` (共 17 项) | 数据库 Schema 治理、多维视图配置、数据行批量 CRUD、分组聚合统计 (count/sum/avg) | 依赖 API |\n| **`blocks`** | `get`, `children`, `append`, `update`, `delete` (共 5 项) | 页面内部细粒度块级操作；树状层级遍历与增删改查 | 依赖 API |\n| **`workspace`** | `info`, `search` (共 2 项) | 跨工作区全局模糊检索与元数据查询 | 依赖 API |\n| **`users`** | `list`, `get`, `me`, `from_workspace` (共 4 项) | 团队成员、协作人及机器人身份检索 | 依赖 API |\n| **`comments`** | `list`, `get`, `create`, `update`, `delete` (共 5 项) | 页面/块级评论讨论全生命周期管理，自动规避官方 OAuth 404 Bug | 依赖 API |\n| **`content_convert`** | `markdown-to-blocks`, `blocks-to-markdown` (共 2 方向) | 纯本地离线 AST 转换引擎，可在本地将 Markdown 文本转换为 Notion Block，无需远程调用 | **纯本地离线 (免 Token)** |\n| **`file_uploads`** | `create`, `send`, `complete`, `retrieve`, `list` (共 5 项) | 上传本地文件与附件至 Notion，原生支持大文件分片断点续传 | 依赖 API |\n| **`help`** | 指定 `tool_name` | **分层 Token 优化核心**：动态拉取指定工具的详尽参数手册与使用范例 | **纯本地离线 (免 Token)** |\n| **`config`** | `status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear` (共 6 项) | **运行时自治核心**：动态检查凭证有效性、探测与重载配置，免去重启客户端的麻烦 | **纯本地离线 (免 Token)** |\n\n> **关于复合对象参数的特别说明**：针对对象或数组类型的参数（如 `properties`, `filters`, `sorts` 等），工具原生支持直接传入标准 JSON 对象，亦支持传入字符串形式的 JSON（针对某些客户端嵌套序列化截断做了自动解包兼容）。\n\n---\n\n## 快速安装与配置\n\n### 1. npx 免安装即用 (推荐)\n\n无需手动下载安装，只需拥有 Node.js (>= 24) 与 Notion 集成 Token（前往 [Notion Integrations](https://www.notion.so/my-integrations) 创建，以 `ntn_` 开头）：\n\n在您的 AI 客户端（如 Claude Desktop, Cursor, Antigravity, Windsurf）配置文件中添加：\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"better-notion-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@faize555/better-notion-mcp@latest\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_your_integration_token_here\"\n      }\n    }\n  }\n}\n```\n\n### 2. 全局安装\n\n通过 npm 进行全局安装：\n\n```bash\nnpm install -g @faize555/better-notion-mcp\n```\n\n客户端配置：\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"better-notion-mcp\": {\n      \"command\": \"better-notion-mcp\",\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_your_integration_token_here\"\n      }\n    }\n  }\n}\n```\n\n### 3. Docker 容器运行 (Stdio 模式)\n\n使用 Docker 构建并在本地 stdio 管道中运行：\n\n```bash\n# 构建镜像\ndocker build -t better-notion-mcp .\n\n# 启动容器\ndocker run --rm -i -e NOTION_TOKEN=ntn_your_integration_token_here better-notion-mcp\n```\n\n---\n\n## 环境配置参考\n\n| 配置项 | 必填 | 默认值 | 作用说明 |\n|:---|:---|:---|:---|\n| `NOTION_TOKEN` | 是 (本地模式) | - | Notion 内部集成访问凭证 (`ntn_...`) |\n| `TRANSPORT_MODE` / `MCP_TRANSPORT` | 否 | `stdio` | 运行模式；设为 `http` 进入远程多租户服务模式 |\n| `PORT` | 否 | `8080` | 远程 HTTP 服务监听端口 |\n| `HOST` | 否 | `0.0.0.0` | 远程 HTTP 监听地址 |\n| `PUBLIC_URL` | 是 (远程模式) | - | 服务的外部公网访问域名 (用于拼接 OAuth 回调地址) |\n| `NOTION_OAUTH_CLIENT_ID` | 是 (远程模式) | - | Notion 公共集成 (Public Integration) Client ID |\n| `NOTION_OAUTH_CLIENT_SECRET` | 是 (远程模式) | - | Notion 公共集成 Client Secret |\n| `CREDENTIAL_SECRET` | 否 (远程模式) | - | 32 字节随机 Hex 密钥，用于 EdDSA 签名保持会话跨重启持久化 |\n\n---\n\n## 私有化部署：Remote OAuth 2.1 服务\n\n适用场景：**团队免密使用**。通过自建远程 OAuth 2.1 服务，使用者无需复制粘贴 Token，点击浏览器一键授权即可使用。\n\n### 1. 创建 Notion Public Integration\n1. 访问 [Notion 开发者中心](https://www.notion.so/my-integrations) 新建集成；\n2. 类型选择 **Public（公共集成）**；\n3. **Redirect URIs** 填写：`https://<你的域名>/callback`；\n4. 勾选所需权限，获取 **Client ID** 与 **Client Secret**。\n\n### 2. Docker Compose 编排启动\n创建 `docker-compose.yml`：\n\n```yaml\nservices:\n  better-notion-mcp:\n    image: better-notion-mcp:latest\n    container_name: better-notion-mcp\n    restart: unless-stopped\n    ports:\n      - \"127.0.0.1:8080:8080\"\n    environment:\n      - TRANSPORT_MODE=http\n      - MCP_TRANSPORT=http\n      - PORT=8080\n      - HOST=0.0.0.0\n      - PUBLIC_URL=https://<你的域名>\n      - NOTION_OAUTH_CLIENT_ID=<你的 Client ID>\n      - NOTION_OAUTH_CLIENT_SECRET=<你的 Client Secret>\n      - CREDENTIAL_SECRET=<32字节随机hex密钥>\n```\n\n> **提示**：密钥可通过命令 `openssl rand -hex 32` 快速生成。\n\n### 3. Nginx 反向代理配置\n```nginx\nserver {\n    listen 443 ssl http2;\n    server_name <你的域名>;\n\n    ssl_certificate /path/to/fullchain.pem;\n    ssl_certificate_key /path/to/privkey.pem;\n\n    location / {\n        proxy_pass http://127.0.0.1:8080;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_buffering off;\n        proxy_cache off;\n        proxy_read_timeout 300s;\n    }\n}\n```\n\n验证健康状态：`curl https://<你的域名>/health` 返回 `{\"status\":\"ok\"}` 即部署成功。\n\n---\n\n## 安全与沙盒架构\n\n- **数据隐私与隔离**：本地 Stdio 模式下仅在您本地操作系统内存中流通，不经过任何第三方中转；HTTP 模式下使用内存化多租户隔离。\n- **敏感信息脱敏**：在错误上报与异常抛出链路中，内核自动过滤敏感的 Token 凭据与安全字段。\n- **OAuth 2.1 + PKCE S256**：防篡改授权验证流程，保障远程授权交换过程安全可信。\n\n---\n\n## 源码构建与测试\n\n本项目采用 [Bun](https://bun.sh) 与 TypeScript 构建：\n\n```bash\n# 1. 克隆代码仓库\ngit clone https://github.com/one2agi/better-notion-mcp.git\ncd better-notion-mcp\n\n# 2. 安装依赖\nbun install\n\n# 3. 运行本地开发调试\nbun run dev\n\n# 4. 执行全量代码检查与测试套件 (1500+ 测试项)\nbun run check\nbun run test\n```\n\n---\n\n## 项目起源与致敬\n\n- **上游原作**：本项目最初源自社区开源先锋 [n24q02m/better-notion-mcp](https://github.com/n24q02m/notion)（作者 [@n24q02m](https://github.com/n24q02m)，现仓库更名为 `notion`）。致敬原作者在 Notion AST 高保真解析与复合工具架构上的奠基性探索！\n- **独立维护的增强版**：本项目当前由 **[one2agi](https://one2agi.com)** 作为独立增强版持续演进。我们剥离了冗余边缘宿主负担，聚焦于更稳定纯粹的 Node.js/Docker 跨平台基座、中文与复合工作流增强，以及面向生产级自主 Agent 的长期交付。\n\n- **官方网站**: [https://one2agi.com](https://one2agi.com)\n- **AI 导航与知识库**: [https://way.one2agi.com](https://way.one2agi.com)\n- **GitHub 组织**: [https://github.com/one2agi](https://github.com/one2agi)\n\n---\n\n## 许可证\n\n本项目遵循 [MIT License](LICENSE) 开源协议。\n","readmeFilename":"README.zh-CN.md"}