当脚本撞墙：用Notion MCP替代本地API脚本的迁移决策

当脚本撞墙：用 Notion MCP 替代本地 API 脚本的迁移决策

上周做 PMO 数据迁移的时候，我在 Notion API 的权限体系里卡了大半天。任务本身不复杂——把本地 YAML 里的 40 多条项目记录，按结构化 schema 推到 Notion 的项目数据库里。脚本三十分钟就写完了，真正耗掉时间的是一行永远过不去的错误：object_not_found。

这是一次典型的”解决方案陷阱”。我原本的工程直觉是：错误信息明确，调通就是了。但最终我选择了放弃脚本、切换到 Notion MCP 集成。这个决策过程本身，比技术方案更值得记录。

一、问题是怎么起的：Integration Token 的权限陷阱

Notion 的官方 API 走 Integration Token 鉴权。直觉上你会认为，拿到 Token 就能访问工作区里的所有资源——事实不是。每一个 Page / Database，都需要显式共享给 Integration，否则即使这个 Page 就挂在你自己的 workspace 根目录下，API 也会给你一个冷冰冰的 Could not find database with ID。

我踩的坑是：脚本写入的目标数据库是动态创建的子页面，每创建一个新 Page，都要手动去 UI 里点”Connections → Add connection”。40 条记录跑到第 3 条就断了。我试过三种绕法：

方案 A：把父 Page 的 Integration 权限继承给所有子页面——Notion 不支持递归继承，子页面必须单独授权。 方案 B：用父 Page 作为唯一写入入口，所有内容用 Block 结构嵌套——结构扁平化后，查询和更新都变成噩梦。 方案 C：写一个半自动化脚本去调用 search + update_page_properties 组合——这条路走得通，但要再花两小时调通，且脆弱。

二、决策转折点：什么时候该停止调试

我给自己定了一条工程原则：如果调试时间开始超过”重写时间 × 1.5”，就要重新审视方案本身。

方案 C 的预估工作量是 2 小时调试 + 后续每次迁移都要维护一个脆弱的权限授权流程。而切换到 Claude MCP 的 Notion 集成，我只需要授权一次（OAuth 走用户身份），后续所有 Page / Database 的读写都继承用户权限——不需要手动共享，不需要 Integration Token，不需要为每个新创建的 Page 重复授权动作。

这里的关键差异是鉴权模型： • Integration Token：资源级白名单，默认拒绝 • MCP OAuth：用户级继承，默认允许（以用户视角为准）

在企业环境里，用户身份模型才是自然的权限边界。Integration 模型本质上是为第三方应用设计的”最小权限”，对一个给自己做数据迁移的个人项目来说，是典型的过度工程。

三、迁移后的实际体验：降维打击在哪

切到 MCP 之后，原本 200 行的 Python 脚本缩成了一段 prompt：告诉 Claude 目标 schema 和数据源路径，它直接通过 MCP 的 notion-create-pages 把记录推进去。整个流程的 “控制点” 从 API 调用变成了自然语言意图声明。

更值得注意的是错误处理的变化。API 脚本里，我要为 rate limit、网络抖动、schema mismatch 各写一套重试和回退逻辑。MCP 层把这些吸收掉了——Claude 会在工具调用失败时自己判断是否重试、是否切换策略，不需要我写一行 try/except。

当然 MCP 也有它的取舍：批量操作的吞吐不如纯脚本，对需要严格幂等的场景（比如金融对账），你仍然需要自己写代码。它不是银弹，它是把”集成工作”这一类低价值工程任务外包给平台原生能力。

四、可复用的判断框架

事后复盘，我把这次决策抽成三条原则：

1. 鉴权模型错配时，换方案优于绕权限。 你绕过的每一个权限校验，都会在未来以安全审计、维护成本、同事接手困难的形式回来找你。

2. “能不能调通” 和 “该不该调通” 是两个问题。 工程师的本能是前者，架构师的本能是后者。卡 30 分钟以上，就该切换到后者视角。

3. 平台原生集成 > 自建脚本，当这三个条件同时满足时： ①任务是非高频、非严格幂等的；②平台已提供 MCP / 官方 SDK / 一键集成；③用户身份模型比服务账号模型更贴合实际场景。PMO 数据迁移三项全中，这就是为什么 MCP 是”降维打击”而不是”妥协方案”。

下次再遇到某个脚本的第二个运行时错误，我会先问自己一句：这个问题，是我该解决的问题吗？

如果你在构建 AI 工程团队，欢迎参考我们开源的 Synapse 框架。