{ "canonical_name": "makenotion/notion-mcp-server", "compilation_id": "pack_1a5deccf60e54989b7e02e5737bda9a4", "created_at": "2026-05-16T23:15:50.742623+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npx @notionhq/notion-mcp-server` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npx @notionhq/notion-mcp-server", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_51b5de7cb47e487a98a3df8421b43c16" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_156f9924bda5b004c930694c89bce508", "canonical_name": "makenotion/notion-mcp-server", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/makenotion/notion-mcp-server", "slug": "notion-mcp-server", "source_packet_id": "phit_37d8ace822fd44888f0126b58a6e004f", "source_validation_id": "dval_8ca90274aa7b4b399787d5d55144dc3a" }, "merchandising": { "best_for": "需要工具连接与集成能力，并使用 mcp_host的用户", "github_forks": 568, "github_stars": 4334, "one_liner_en": "Official Notion MCP Server", "one_liner_zh": "Official Notion MCP Server", "primary_category": { "category_id": "tool-integrations", "confidence": "high", "name_en": "Tool Integrations", "name_zh": "工具连接与集成", "reason": "matched_keywords:mcp, server, notion" }, "target_user": "使用 mcp_host 等宿主 AI 的用户", "title_en": "notion-mcp-server", "title_zh": "notion-mcp-server 能力包", "visible_tags": [ { "label_en": "MCP Tools", "label_zh": "MCP 工具", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-mcp-tools", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "TDD Workflow", "label_zh": "TDD 工作流", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-tdd-workflow", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_37d8ace822fd44888f0126b58a6e004f", "page_model": { "artifacts": { "artifact_slug": "notion-mcp-server", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npx @notionhq/notion-mcp-server", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/makenotion/notion-mcp-server#readme", "verified": true } ], "display_tags": [ "MCP 工具", "知识库问答", "TDD 工作流", "节点式流程编排", "本地优先" ], "eyebrow": "工具连接与集成", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要工具连接与集成能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Official Notion MCP Server" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：BUG: Tool `query_data_sources` not available", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Notion MCP server does not work with Claude Code", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Feature Request: Property-based filtering in notion-search for database queries", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Ontheia listed as compatible client — works great with notion-mcp-server", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Schema quality: 8 required parameters missing descriptions", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。", "title": "踩坑日志" }, "snapshot": { "contributors": 22, "forks": 568, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 4334 }, "source_url": "https://github.com/makenotion/notion-mcp-server", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Official Notion MCP Server", "title": "notion-mcp-server 能力包", "trial_prompt": "# notion-mcp-server - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 notion-mcp-server 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Official Notion MCP Server 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目介绍与版本说明。围绕“项目介绍与版本说明”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构与模块设计。围绕“系统架构与模块设计”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：MCP 工具集详解。围绕“MCP 工具集详解”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：安装与客户端配置。围绕“安装与客户端配置”模拟一次用户任务，不展示安装或运行结果。\n5. page-6：认证机制与安全配置。围绕“认证机制与安全配置”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目介绍与版本说明”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构与模块设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“MCP 工具集详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“安装与客户端配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-6\n输入：用户提供的“认证机制与安全配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目介绍与版本说明”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构与模块设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“MCP 工具集详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“安装与客户端配置”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-6：Step 5 必须围绕“认证机制与安全配置”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/makenotion/notion-mcp-server\n- https://github.com/makenotion/notion-mcp-server#readme\n- README.md\n- package.json\n- src/openapi-mcp-server/index.ts\n- src/openapi-mcp-server/auth/index.ts\n- src/openapi-mcp-server/client/http-client.ts\n- src/openapi-mcp-server/mcp/proxy.ts\n- scripts/notion-openapi.json\n- src/openapi-mcp-server/openapi/parser.ts\n- docker-compose.yml\n- Dockerfile\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 notion-mcp-server 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Ontheia listed as compatible client — works great with notion-mcp-server（https://github.com/makenotion/notion-mcp-server/issues/287）；github/github_issue: synced_block_reference: URL inside url= attribute gets auto-converted to（https://github.com/makenotion/notion-mcp-server/issues/286）；github/github_issue: API-create-a-data-source and API-update-a-data-source return invalid_req（https://github.com/makenotion/notion-mcp-server/issues/218）；github/github_issue: v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not in（https://github.com/makenotion/notion-mcp-server/issues/284）；github/github_issue: Feature Request: Support local file upload for images and files（https://github.com/makenotion/notion-mcp-server/issues/191）；github/github_issue: Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not（https://github.com/makenotion/notion-mcp-server/issues/232）；github/github_issue: Bug: notion-create-view silently drops FILTER on Status property (no err（https://github.com/makenotion/notion-mcp-server/issues/283）；github/github_issue: Enhancement: Expand blockObjectRequest to support all Notion block types（https://github.com/makenotion/notion-mcp-server/issues/282）；github/github_issue: BUG: Tool `query_data_sources` not available（https://github.com/makenotion/notion-mcp-server/issues/256）；github/github_issue: [Bug] FILTER directive in view DSL silently drops filters for Relation a（https://github.com/makenotion/notion-mcp-server/issues/281）；github/github_issue: Schema quality: 8 required parameters missing descriptions（https://github.com/makenotion/notion-mcp-server/issues/280）；github/github_issue: OAuth token expires too frequently — requires re-authentication 3+ times（https://github.com/makenotion/notion-mcp-server/issues/225）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Ontheia listed as compatible client — works great with notion-mcp-server", "url": "https://github.com/makenotion/notion-mcp-server/issues/287" }, { "kind": "github_issue", "source": "github", "title": "synced_block_reference: URL inside url= attribute gets auto-converted to", "url": "https://github.com/makenotion/notion-mcp-server/issues/286" }, { "kind": "github_issue", "source": "github", "title": "API-create-a-data-source and API-update-a-data-source return invalid_req", "url": "https://github.com/makenotion/notion-mcp-server/issues/218" }, { "kind": "github_issue", "source": "github", "title": "v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not in", "url": "https://github.com/makenotion/notion-mcp-server/issues/284" }, { "kind": "github_issue", "source": "github", "title": "Feature Request: Support local file upload for images and files", "url": "https://github.com/makenotion/notion-mcp-server/issues/191" }, { "kind": "github_issue", "source": "github", "title": "Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not", "url": "https://github.com/makenotion/notion-mcp-server/issues/232" }, { "kind": "github_issue", "source": "github", "title": "Bug: notion-create-view silently drops FILTER on Status property (no err", "url": "https://github.com/makenotion/notion-mcp-server/issues/283" }, { "kind": "github_issue", "source": "github", "title": "Enhancement: Expand blockObjectRequest to support all Notion block types", "url": "https://github.com/makenotion/notion-mcp-server/issues/282" }, { "kind": "github_issue", "source": "github", "title": "BUG: Tool `query_data_sources` not available", "url": "https://github.com/makenotion/notion-mcp-server/issues/256" }, { "kind": "github_issue", "source": "github", "title": "[Bug] FILTER directive in view DSL silently drops filters for Relation a", "url": "https://github.com/makenotion/notion-mcp-server/issues/281" }, { "kind": "github_issue", "source": "github", "title": "Schema quality: 8 required parameters missing descriptions", "url": "https://github.com/makenotion/notion-mcp-server/issues/280" }, { "kind": "github_issue", "source": "github", "title": "OAuth token expires too frequently — requires re-authentication 3+ times", "url": "https://github.com/makenotion/notion-mcp-server/issues/225" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "工具连接与集成", "desc": "Official Notion MCP Server", "effort": "安装已验证", "forks": 568, "icon": "link", "name": "notion-mcp-server 能力包", "risk": "可发布", "slug": "notion-mcp-server", "stars": 4334, "tags": [ "MCP 工具", "知识库问答", "TDD 工作流", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/makenotion/notion-mcp-server 项目说明书\n\n生成时间：2026-05-16 22:56:19 UTC\n\n## 目录\n\n- [项目介绍与版本说明](#page-1)\n- [系统架构与模块设计](#page-2)\n- [MCP 工具集详解](#page-3)\n- [安装与客户端配置](#page-4)\n- [HTTP 客户端与网络请求处理](#page-5)\n- [认证机制与安全配置](#page-6)\n- [传输层配置详解](#page-7)\n- [本地开发与测试指南](#page-8)\n- [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n- [OpenAPI 规范与文件上传](#page-10)\n\n\n\n## 项目介绍与版本说明\n\n### 相关页面\n\n相关主题：[MCP 工具集详解](#page-3), [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# 项目介绍与版本说明\n\n## 项目概述\n\nNotion MCP Server 是 Notion 官方提供的 MCP（Model Context Protocol）服务器，用于将 Notion API 作为 MCP 工具暴露给 AI 客户端使用。该项目通过自动生成的方式从 OpenAPI 规范创建 MCP 工具，无需手动编写工具代码。\n\n**核心特性：**\n\n- 自动从 OpenAPI 3.1.0 规范生成 MCP 工具\n- 支持 stdio 和 Streamable HTTP 两种传输模式\n- 使用 Notion API 版本 `2025-09-03`（Data Source Edition）\n- 提供 22 个 MCP 工具（v2.0.0 版本）\n- 支持 Cursor、Claude、Zed、GitHub Copilot CLI 等主流 MCP 客户端\n\n资料来源：[README.md:1-50]()\n\n---\n\n## 系统架构\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json] --> B[OpenAPI 3.1.0 规范]\n B --> C[src/init-server.ts]\n C --> D[创建 MCPProxy 实例]\n D --> E[OpenAPIToMCPConverter]\n E --> F[生成 MCP 工具定义]\n F --> G[MCPProxy.setupHandlers]\n G --> H[MCP SDK 注册工具]\n H --> I[AI 客户端调用工具]\n I --> J[HttpClient 执行 API 请求]\n J --> K[Notion API]\n \n subgraph 核心模块\n E\n F\n G\n end\n```\n\n### 目录结构\n\n| 路径 | 说明 |\n|------|------|\n| `scripts/notion-openapi.json` | OpenAPI 3.1.0 规范定义文件（所有工具的源头） |\n| `scripts/start-server.ts` | 服务器入口点，处理命令行参数 |\n| `src/init-server.ts` | 服务器初始化，加载和验证规范 |\n| `src/openapi-mcp-server/` | 核心 MCP 服务器实现 |\n| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI 到 MCP 工具的转换逻辑 |\n| `src/openapi-mcp-server/mcp/proxy.ts` | MCP 工具注册和执行 |\n| `src/openapi-mcp-server/client/http-client.ts` | HTTP 请求执行 |\n\n资料来源：[CLAUDE.md:1-30]()\n\n### 工具生成流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 客户端\n participant MCP as MCP SDK\n participant Proxy as MCPProxy\n participant Parser as OpenAPIToMCPConverter\n participant Client as HttpClient\n participant API as Notion API\n \n AI->>MCP: 调用工具\n MCP->>Proxy: 分发请求\n Proxy->>Parser: 解析参数\n Parser->>Proxy: 反序列化参数\n Proxy->>Client: 执行 HTTP 请求\n Client->>API: API 调用\n API-->>Client: 返回数据\n Client-->>Proxy: 返回结果\n Proxy-->>MCP: 标准化响应\n MCP-->>AI: 返回结果\n```\n\n工具生成的五个关键步骤：\n\n1. `OpenAPIToMCPConverter.convertToMCPTools()` 遍历所有路径和操作\n2. 每个操作成为一个 MCP 工具（名称来自 `operationId`）\n3. 参数 + requestBody → `inputSchema`\n4. 响应 schema → `returnSchema`\n5. `MCPProxy.setupHandlers()` 注册工具到 MCP SDK\n\n资料来源：[CLAUDE.md:35-55]()\n\n---\n\n## 版本 2.0.0 重大变更\n\n**版本 2.0.0 迁移到 Notion API 2025-09-03**，该版本引入了数据源（Data Source）作为数据库的主要抽象。\n\n### 变更概览\n\n```mermaid\ngraph LR\n A[数据库工具 v1.x] -->|迁移| B[数据源工具 v2.0]\n A1[post-database-query] --> B1[query-data-source]\n A2[update-a-database] --> B2[update-a-data-source]\n A3[create-a-database] --> B3[create-a-data-source]\n```\n\n### 移除的工具（3个）\n\n| 旧工具（v1.x） | 替代工具（v2.0） |\n|--------------|----------------|\n| `post-database-query` | `query-data-source` |\n| `update-a-database` | `update-a-data-source` |\n| `create-a-database` | `create-a-data-source` |\n\n资料来源：[README.md:120-140]()\n\n### 新增的工具（7个）\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `query-data-source` | 使用过滤器和排序查询数据源（数据库） |\n| `retrieve-a-data-source` | 获取数据源的元数据和 schema |\n| `update-a-data-source` | 更新数据源属性 |\n| `create-a-data-source` | 创建新的数据源 |\n| `list-data-source-templates` | 列出数据源中的可用模板 |\n| `move-page` | 将页面移动到不同的父位置 |\n| `retrieve-a-database` | 获取数据库元数据，包括数据源 ID 列表 |\n\n资料来源：[README.md:145-165]()\n\n### 参数变更\n\n| 变更类型 | v1.x | v2.0 |\n|---------|------|------|\n| 数据库操作参数 | `database_id` | `data_source_id` |\n| 搜索过滤器值 | `[\"page\", \"database\"]` | `[\"page\", \"data_source\"]` |\n| 页面创建父级 | 仅 `page_id` | `page_id` 或 `database_id` |\n\n资料来源：[README.md:170-185]()\n\n---\n\n## 迁移指南\n\n### 是否需要迁移？\n\n**无需代码更改。** MCP 工具在服务器启动时自动被发现。升级到 v2.0.0 后，AI 客户端将自动看到新的工具名称和参数。旧的数据库工具将不再可用。\n\n### 迁移对照表\n\n| 旧工具（v1.x） | 新工具（v2.0） | 参数变更 |\n|--------------|---------------|---------|\n| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |\n| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |\n| `create-a-database` | `create-a-data-source` | 无变化（使用 `parent.page_id`） |\n\n> **注意：** `retrieve-a-database` 仍然可用，返回数据库元数据包括数据源 ID 列表。使用 `retrieve-a-data-source` 获取特定数据源的 schema 和属性。\n\n资料来源：[README.md:190-210]()\n\n### 工具总数\n\n- **v1.x: 19 个工具**\n- **v2.0: 22 个工具**（新增 7 个，移除 3 个，保留 1 个兼容工具）\n\n---\n\n## 环境配置\n\n### 环境变量\n\n| 变量名 | 说明 | 优先级 |\n|-------|------|--------|\n| `NOTION_TOKEN` | Notion 集成令牌（推荐） | - |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 头信息 | 替代方案 |\n| `AUTH_TOKEN` | HTTP 传输认证令牌 | CLI 参数优先 |\n\n资料来源：[README.md:55-80]()\n\n### 传输模式\n\n| 模式 | 说明 | 默认端口 |\n|------|------|---------|\n| `stdio` | 标准输入输出传输（默认） | - |\n| `http` | Streamable HTTP 传输 | 3000 |\n\n**命令行参数：**\n\n```bash\n--transport # 传输类型：'stdio' 或 'http'\n--port # HTTP 服务器端口（默认：3000）\n--auth-token # HTTP 传输认证令牌\n--disable-auth # 禁用认证\n--help, -h # 显示帮助信息\n```\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n---\n\n## 参数反序列化机制\n\nMCPProxy 中的 `deserializeParams` 函数处理参数反序列化：\n\n```mermaid\nflowchart TD\n A[接收参数对象] --> B{参数类型判断}\n B -->|string| C{是否 JSON 字符串}\n B -->|array| D{遍历数组成员}\n B -->|其他| G[直接传递]\n \n C -->|是| E[JSON.parse 解析]\n C -->|否| G\n \n E --> F{解析结果是否为对象}\n F -->|是| H[递归反序列化]\n F -->|否| G\n \n D --> D1{成员是否为字符串}\n D1 -->|是| E\n D1 -->|否| D2[保持原值]\n \n H --> I[返回反序列化结果]\n G --> I\n D2 --> I\n```\n\n该机制确保嵌套的 JSON 字符串参数能够正确反序列化，防止参数传递错误。\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-60]()\n\n---\n\n## 快速开始\n\n### 安装与配置\n\n```bash\n# 方式一：使用 npm\nnpx -y @notionhq/notion-mcp-server\n\n# 方式二：本地开发\nnpm install\nnpm run build\nnpm link # 创建全局符号链接\n```\n\n### MCP 客户端配置示例\n\n**Cursor/Claude 配置文件**（`~/.cursor/mcp.json`）：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:100-130]()\n\n### 构建与测试\n\n| 命令 | 说明 |\n|------|------|\n| `npm run build` | TypeScript 编译 + CLI 打包 |\n| `npm test` | 运行 vitest 测试 |\n| `npm run dev` | 启动开发服务器（热重载） |\n\n资料来源：[CLAUDE.md:20-25]()\n\n---\n\n## 相关链接\n\n- 官方文档：https://developers.notion.com/reference/intro\n- MCP 协议规范：https://spec.modelcontextprotocol.io/\n- 问题反馈：https://github.com/makenotion/notion-mcp-server/issues\n\n---\n\n\n\n## 系统架构与模块设计\n\n### 相关页面\n\n相关主题：[项目介绍与版本说明](#page-1), [HTTP 客户端与网络请求处理](#page-5), [认证机制与安全配置](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/openapi-mcp-server/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/index.ts)\n- [src/openapi-mcp-server/auth/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts)\n- [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)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n
\n\n# 系统架构与模块设计\n\n## 概述\n\nNotion MCP Server 是一个实现 MCP（Model Context Protocol）协议的服务器，用于将 Notion API 暴露为 MCP 工具供 AI 代理使用。该项目采用自动生成架构，通过 OpenAPI 规范定义所有工具，无需为每个 API 端点编写独立代码。\n\n### 核心设计理念\n\n| 设计原则 | 说明 |\n|---------|------|\n| 规范驱动 | 所有工具从 `notion-openapi.json` 自动生成 |\n| 零手动维护 | 新增 API 端点只需修改 OpenAPI 规范 |\n| 多协议兼容 | 支持 STDIO 和 HTTP 两种传输协议 |\n| 标准化转换 | OpenAPI → MCP / OpenAI / Anthropic 工具格式 |\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph \"数据源层\"\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 规范\"]\n end\n \n subgraph \"核心处理层\"\n B[\"init-server.ts
服务器初始化\"]\n C[\"parser.ts
OpenAPI → MCP 转换器\"]\n D[\"proxy.ts
MCP 工具代理\"]\n end\n \n subgraph \"传输层\"\n E[\"STDIO 传输\"]\n F[\"HTTP/Streamable 传输\"]\n end\n \n subgraph \"外部调用\"\n G[\"AI 客户端
Cursor/Claude/Copilot\"]\n end\n \n A --> B\n B --> C\n C --> D\n D --> E\n D --> F\n E --> G\n F --> G\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e9\n```\n\n## 模块详解\n\n### 1. 入口模块 (scripts/start-server.ts)\n\n服务器启动入口，负责命令行参数解析和传输协议选择。\n\n#### 支持的参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--transport` | string | `stdio` | 传输类型：`stdio` 或 `http` |\n| `--port` | number | `3000` | HTTP 服务器端口 |\n| `--auth-token` | string | 自动生成 | HTTP 传输的认证令牌 |\n| `--disable-auth` | boolean | `false` | 禁用认证 |\n| `--help` | - | - | 显示帮助信息 |\n\n#### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `NOTION_TOKEN` | Notion 集成令牌（推荐） |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 请求头 |\n| `AUTH_TOKEN` | HTTP 传输认证令牌（备选） |\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n### 2. 服务器初始化 (src/init-server.ts)\n\n负责加载 OpenAPI 规范、验证配置并创建 MCP 服务器实例。\n\n#### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant 启动脚本\n participant init-server\n participant MCPProxy\n participant OpenAPI规范\n \n 启动脚本->>init-server: 加载 OpenAPI 规范\n init-server->>MCPProxy: 创建代理实例\n MCPProxy->>OpenAPI规范: 解析端点\n MCPProxy->>MCPProxy: 注册工具处理器\n init-server->>启动脚本: 返回服务器实例\n```\n\n资料来源：[src/init-server.ts](), [src/openapi-mcp-server/mcp/proxy.ts:1-50]()\n\n### 3. OpenAPI 解析器 (src/openapi-mcp-server/openapi/parser.ts)\n\n核心转换模块，将 OpenAPI 3.1.0 规范转换为 MCP 工具定义。\n\n#### 主要功能\n\n- 解析 OpenAPI 路径和操作\n- 转换 JSON Schema 参数定义\n- 生成 MCP 工具的 `inputSchema` 和 `returnSchema`\n- 支持多种输出格式：MCP、OpenAI ChatCompletion、Anthropic Tool\n\n#### 转换方法\n\n| 方法 | 输出格式 | 用途 |\n|------|----------|------|\n| `convertToMCPTools()` | MCP Tool[] | MCP 协议标准格式 |\n| `convertToOpenAITools()` | ChatCompletionTool[] | OpenAI 函数调用 |\n| `convertToAnthropicTools()` | Tool[] | Anthropic Claude 工具 |\n\n#### Schema 转换处理\n\n```typescript\n// 处理类型映射关系\n- OpenAPI binary → JSON Schema uri-reference\n- object 类型 → 保留 properties 和 additionalProperties\n- array 类型 → 递归转换 items\n- oneOf/anyOf/allOf → 递归处理联合类型\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-100]()\n\n### 4. MCP 代理模块 (src/openapi-mcp-server/mcp/proxy.ts)\n\n负责 MCP 工具的注册、路由和执行。\n\n#### 核心组件\n\n| 组件 | 职责 |\n|------|------|\n| `HttpClient` | 发送 HTTP 请求到 Notion API |\n| `OpenAPIToMCPConverter` | 工具定义转换 |\n| `MCPProxy` | 工具注册与调用处理 |\n\n#### 工具命名规则\n\n- 工具名称来源：`operationId` 字段\n- 长度限制：截断至 64 字符\n- 显示格式：Title Case（如 `RetrieveADatabase`）\n\n#### 请求处理流程\n\n```mermaid\ngraph LR\n A[\"MCP 调用请求\"] --> B[\"解析工具名称\"]\n B --> C[\"查找 OpenAPI 操作\"]\n C --> D[\"提取参数\"]\n D --> E[\"构造 HTTP 请求\"]\n E --> F[\"发送请求到 Notion API\"]\n F --> G[\"返回响应结果\"]\n```\n\n#### 工具注解\n\n| HTTP 方法 | 注解 | 说明 |\n|-----------|------|------|\n| GET | `readOnlyHint: true` | 只读操作 |\n| POST/PATCH/DELETE | `destructiveHint: true` | 可能修改数据的操作 |\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:50-150]()\n\n### 5. HTTP 客户端 (src/openapi-mcp-server/client/http-client.ts)\n\n负责执行实际的 API 调用。\n\n#### 请求构造\n\n```typescript\n// 参数分类处理\n1. 路径参数 (path) → URL 路径占位符\n2. 查询参数 (query) → URL 查询字符串\n3. 请求体 (body) → JSON 请求体\n4. 表单数据 (formData) → multipart/form-data\n```\n\n#### 认证头处理\n\n默认从环境变量读取认证信息：\n- `OPENAPI_MCP_HEADERS`：JSON 格式的完整请求头\n- 自动注入 `Authorization` 和 `Notion-Version`\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-100]()\n\n### 6. 认证模块 (src/openapi-mcp-server/auth/index.ts)\n\n处理 HTTP 传输的 Bearer Token 认证。\n\n#### 认证选项\n\n| 方式 | 优先级 | 说明 |\n|------|--------|------|\n| 命令行 `--auth-token` | 最高 | 显式指定令牌 |\n| 环境变量 `AUTH_TOKEN` | 中 | 环境配置 |\n| 自动生成 | 最低 | 开发模式自动创建 |\n\n#### 认证流程\n\n```mermaid\ngraph TD\n A[\"HTTP 请求到达\"] --> B{\"检查 --disable-auth\"}\n B -->|是| C[\"跳过认证\"]\n B -->|否| D[\"提取 Authorization 头\"]\n D --> E{\"验证 Bearer Token\"}\n E -->|通过| F[\"处理请求\"]\n E -->|失败| G[\"返回 401 错误\"]\n```\n\n资料来源：[src/openapi-mcp-server/auth/index.ts]()\n\n## 数据流架构\n\n```mermaid\nflowchart LR\n subgraph 用户层\n A[\"AI 客户端\"]\n B[\"Notion Token\"]\n end\n \n subgraph MCP服务器\n C[\"STDIO/HTTP 接收\"]\n D[\"工具列表请求\"]\n E[\"工具调用请求\"]\n F[\"工具解析\"]\n G[\"HTTP 执行器\"]\n end\n \n subgraph Notion API\n H[\"Notion API v2025-09-03\"]\n end\n \n A -->|MCP 协议| C\n B -->|认证| G\n C --> D\n C --> E\n E --> F\n F --> G\n G -->|HTTP/REST| H\n H -->|JSON 响应| G\n G -->|MCP 响应| A\n```\n\n## 传输协议\n\n### STDIO 模式\n\n默认传输方式，适用于本地集成。\n\n```bash\nnpx @notionhq/notion-mcp-server\n```\n\n### HTTP/Streamable 模式\n\n适用于远程部署和分布式架构。\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --port 3000\n```\n\n| 特性 | STDIO | HTTP |\n|------|-------|------|\n| 连接方式 | 标准输入/输出 | HTTP 长连接 |\n| 认证 | 无 | Bearer Token |\n| 适用场景 | 本地 IDE | 远程服务 |\n| 状态管理 | 无状态 | Session 支持 |\n\n## 扩展机制\n\n### 添加新 API 端点\n\n仅需修改 `scripts/notion-openapi.json`，工具将自动生成：\n\n```mermaid\ngraph LR\n A[\"修改 notion-openapi.json\"] --> B[\"添加/修改路径\"]\n B --> C[\"定义 operationId\"]\n C --> D[\"npm run build\"]\n D --> E[\"工具自动可用\"]\n```\n\n### 支持的工具格式\n\n| 格式 | 生成方法 | 使用场景 |\n|------|----------|----------|\n| MCP Tool | `convertToMCPTools()` | MCP SDK 原生支持 |\n| OpenAI Function | `convertToOpenAITools()` | GPT 函数调用 |\n| Anthropic Tool | `convertToAnthropicTools()` | Claude 工具使用 |\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n package.json --> express\n package.json --> @modelcontextprotocol-sdk\n package.json --> openapi-types\n \n express --> src/init-server.ts\n @modelcontextprotocol-sdk --> src/openapi-mcp-server/mcp/proxy.ts\n \n src/init-server.ts --> src/openapi-mcp-server/mcp/proxy.ts\n src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/openapi/parser.ts\n src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/client/http-client.ts\n src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/auth/index.ts\n \n src/openapi-mcp-server/openapi/parser.ts --> openapi-types\n scripts/start-server.ts --> src/init-server.ts\n```\n\n## 关键设计决策\n\n### 1. 规范即代码\n\n通过将 OpenAPI 规范作为唯一的工具定义来源，实现了：\n- 单点维护\n- 文档与实现同步\n- 多格式工具自动导出\n\n### 2. 分层架构\n\n| 层级 | 职责 | 隔离性 |\n|------|------|--------|\n| 传输层 | 协议适配 (STDIO/HTTP) | 可替换 |\n| 协议层 | MCP SDK 封装 | 核心依赖 |\n| 转换层 | OpenAPI → MCP 转换 | 可复用 |\n| 执行层 | HTTP 请求执行 | 可测试 |\n\n### 3. 认证安全\n\nHTTP 传输强制使用 Bearer Token 认证，支持：\n- 自动生成（开发模式）\n- 环境变量配置（生产推荐）\n- 命令行显式指定（最高优先级）\n\n## 总结\n\nNotion MCP Server 采用现代化的分层架构设计，通过 OpenAPI 规范驱动实现零手动维护的工具生成机制。核心模块各司其职：解析器负责格式转换、代理负责工具注册、HTTP 客户端负责实际请求执行、认证模块负责安全控制。这种设计既保证了代码的可维护性，又为未来扩展提供了良好的基础。\n\n---\n\n\n\n## MCP 工具集详解\n\n### 相关页面\n\n相关主题：[项目介绍与版本说明](#page-1), [系统架构与模块设计](#page-2), [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json) - OpenAPI 3.1.0 规范定义所有 Notion API 端点\n- [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 工具转换器\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts) - MCP 工具注册与执行代理\n- [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 客户端实现\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts) - 服务器初始化逻辑\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts) - 服务器入口点\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json) - 项目依赖与构建配置\n
\n\n# MCP 工具集详解\n\n## 概述\n\nMCP 工具集是 Notion MCP Server 的核心功能模块，它将 Notion OpenAPI 规范自动转换为 Model Context Protocol (MCP) 工具，使 AI 助手能够直接调用 Notion API 进行操作。\n\n该系统的设计理念是**仅需修改 OpenAPI 规范文件**，即可自动生成对应的 MCP 工具，无需手动编写代码。工具的命名、参数定义、响应模式等全部从 OpenAPI 规范派生。\n\n资料来源：[CLAUDE.md]()\n\n## 架构总览\n\n### 核心数据流\n\n```mermaid\ngraph TD\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 规范\"] --> B[\"src/init-server.ts
加载与验证规范\"]\n B --> C[\"OpenAPIToMCPConverter
openapi/parser.ts\"]\n C --> D[\"MCPProxy
mcp/proxy.ts\"]\n D --> E[\"HTTP Client
client/http-client.ts\"]\n E --> F[\"Notion API
api.notion.com\"]\n \n C -.->|convertToMCPTools| G[\"MCP 工具定义\"]\n C -.->|convertToOpenAITools| H[\"OpenAI 工具格式\"]\n C -.->|convertToAnthropicTools| I[\"Anthropic 工具格式\"]\n```\n\n### 关键组件\n\n| 组件 | 文件路径 | 职责 |\n|------|---------|------|\n| OpenAPI 规范 | `scripts/notion-openapi.json` | 定义所有 API 端点的规范来源 |\n| 工具转换器 | `src/openapi-mcp-server/openapi/parser.ts` | 将 OpenAPI 转换为 MCP 工具格式 |\n| 工具代理 | `src/openapi-mcp-server/mcp/proxy.ts` | 注册工具句柄并执行调用 |\n| HTTP 客户端 | `src/openapi-mcp-server/client/http-client.ts` | 执行实际的 API 请求 |\n| 服务器初始化 | `src/init-server.ts` | 加载规范并创建 MCPProxy 实例 |\n\n资料来源：[CLAUDE.md]()\n\n## OpenAPI 到 MCP 工具转换机制\n\n### 转换流程\n\n```mermaid\nsequenceDiagram\n participant OpenAPI as OpenAPI 规范\n participant Parser as OpenAPIToMCPConverter\n participant MCP as MCPProxy\n \n OpenAPI->>Parser: 加载规范文件\n Parser->>Parser: 解析 paths 和 operations\n Parser->>Parser: convertOperationToJsonSchema()\n Parser->>Parser: extractResponseType()\n Parser->>Parser: convertToMCPTools()\n Parser-->>MCP: { tools, openApiLookup, zip }\n```\n\n### 核心转换方法\n\n`OpenAPIToMCPConverter` 类提供三种工具格式转换方法：\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:120-180]()\n\n#### 1. `convertToMCPTools()`\n\n生成原生 MCP 工具定义，返回包含三个属性的对象：\n\n```typescript\n{\n tools: Record, // 按 API 名称分组的工具\n openApiLookup: Record, // 操作查找表\n zip: Record // 配对的 OpenAPI 与 MCP 工具\n}\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:85-140]()\n\n#### 2. `convertToOpenAITools()`\n\n转换为 OpenAI ChatCompletion 工具格式：\n\n```typescript\n{\n type: 'function',\n function: {\n name: operation.operationId,\n description: 描述文本,\n parameters: JSON Schema\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:143-165]()\n\n#### 3. `convertToAnthropicTools()`\n\n转换为 Anthropic Claude 工具格式：\n\n```typescript\n{\n name: operation.operationId,\n description: 描述文本,\n input_schema: JSON Schema\n}\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:168-190]()\n\n### Schema 转换细节\n\n#### 类型映射规则\n\n| OpenAPI 类型 | JSON Schema 类型 | 特殊处理 |\n|-------------|-----------------|---------|\n| `string` | `string` | - |\n| `integer` | `integer` | - |\n| `number` | `number` | - |\n| `boolean` | `boolean` | - |\n| `array` | `array` | 包含 items 转换 |\n| `object` | `object` | 包含 properties 和 additionalProperties |\n| `binary` | `uri-reference` | 添加\"本地文件绝对路径\"描述 |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:30-90]()\n\n#### 复合类型处理\n\n对于包含 `oneOf`、`anyOf`、`allOf` 的复杂 Schema，系统采用以下策略：\n\n```typescript\n// 如果 schema 包含 oneOf/anyOf/allOf 或是数组\nif ('anyOf' in schema || 'oneOf' in schema || 'allOf' in schema) {\n return { anyOf: [schema, { type: 'string' }] }\n}\n```\n\n这确保了参数可以接受原始值或 JSON 字符串形式。\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:260-280]()\n\n#### 响应 Schema 提取\n\n```mermaid\ngraph LR\n A[\"responses 对象\"] --> B{\"查找成功响应\"}\n B -->|\"200/201/202/204\"| C[\"解析 content\"]\n B -->|\"无匹配\"| D[\"返回 null\"]\n C --> E{\"application/json?\"}\n E -->|是| F[\"转换 schema
添加 $defs\"]\n E -->|否| G[\"处理二进制格式\"]\n```\n\n系统按优先级 `200 → 201 → 202 → 204` 查找成功响应，并从 `application/json` content 中提取响应 schema。\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:290-320]()\n\n## 工具命名规范\n\n### 命名来源\n\n工具名称直接取自 OpenAPI 规范的 `operationId` 字段：\n\n```json\n{\n \"operationId\": \"retrieve-a-database\"\n}\n```\n\n转换后生成工具名：`Retrieve-A-Database`\n\n资料来源：[CLAUDE.md]()\n\n### 名称处理规则\n\n| 处理步骤 | 说明 |\n|---------|------|\n| 1. 截断 | 名称被截断至 64 字符以内 |\n| 2. 标题化 | 转换为 Title Case 格式 |\n| 3. 分组 | 按 API 名称分组到不同的方法集合 |\n\n## 工具注册与执行\n\n### MCPProxy 架构\n\n```mermaid\nclassDiagram\n class MCPProxy {\n +mcpServer: Server\n +openApiSpec: OpenAPIV3.Document\n +openApiLookup: Record\n +setupHandlers() void\n +executeTool(name, args) Promise\n }\n \n class HTTPClient {\n +executeOperation(operationId, params) Promise\n }\n \n MCPProxy --> HTTPClient : 使用\n```\n\n### 参数反序列化机制\n\nMCP 协议在传输过程中会将复杂参数序列化为字符串。`deserializeParams()` 函数负责反序列化：\n\n```typescript\nfunction deserializeParams(params: Record): Record\n```\n\n**处理逻辑：**\n\n1. 检测字符串值是否以 `{`/`[` 开头并以 `}`/`]` 结尾\n2. 尝试使用 `JSON.parse()` 解析\n3. 对嵌套对象递归反序列化\n4. 对数组中的 JSON 字符串项逐个处理\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:10-60]()\n\n### 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Proxy as MCPProxy\n participant Deserializer as deserializeParams\n participant HTTP as HTTPClient\n participant API as Notion API\n \n Client->>Proxy: 调用工具 \"retrieve-a-database\"\n Proxy->>Deserializer: 反序列化参数\n Deserializer-->>Proxy: 处理后的参数对象\n Proxy->>HTTP: operationId + 参数\n HTTP->>API: GET /v1/databases/{database_id}\n API-->>HTTP: 200 OK + 数据库数据\n HTTP-->>Proxy: API 响应\n Proxy-->>Client: MCP 响应结果\n```\n\n## HTTP 客户端实现\n\n### 请求构建流程\n\n`HTTPClient` 负责将工具调用转换为实际的 HTTP 请求：\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50]()\n\n| 处理步骤 | 操作 |\n|---------|------|\n| 1 | 从 `operation.parameters` 提取 path 和 query 参数 |\n| 2 | 识别 `application/json` 或 `multipart/form-data` 请求体 |\n| 3 | 设置相应的 `Content-Type` header |\n| 4 | 调用 OpenAPI 客户端生成的操作函数 |\n| 5 | 转换响应 headers 为标准 Headers 对象 |\n\n### 请求体处理\n\n```typescript\n// 根据是否有请求体设置 headers\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n\n// 调用格式：第一个参数为 URL 参数，第二个为 body 参数\nconst response = await operationFn(urlParameters, hasBody ? bodyParams : undefined, requestConfig)\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:50-80]()\n\n## 服务器传输模式\n\n### 支持的传输类型\n\n| 传输模式 | 说明 | 默认端口 |\n|---------|------|---------|\n| `stdio` | 标准输入/输出流 | N/A |\n| `http` | Streamable HTTP 传输 | 3000 |\n\n资料来源：[scripts/start-server.ts:20-40]()\n\n### 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--transport ` | 指定传输类型 (`stdio` 或 `http`) |\n| `--port ` | HTTP 服务器端口 (默认: 3000) |\n| `--auth-token ` | HTTP 传输认证的 Bearer token |\n| `--disable-auth` | 禁用 HTTP 传输的 Bearer token 认证 |\n| `--help`, `-h` | 显示帮助信息 |\n\n### 环境变量配置\n\n| 变量 | 说明 | 优先级 |\n|------|------|-------|\n| `NOTION_TOKEN` | Notion 集成密钥 (推荐) | 高 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API headers | 低 |\n\n`--auth-token` 参数优先于 `AUTH_TOKEN` 环境变量。\n\n资料来源：[scripts/start-server.ts:60-100]()\n\n## API 版本支持\n\n服务器使用 Notion API 版本 **`2025-09-03`** (Data Source Edition)。\n\n规范文件同时包含两类端点：\n\n| 端点类型 | 示例路径 |\n|---------|---------|\n| 传统数据库端点 | `/v1/databases/{database_id}` |\n| 数据源端点 | `/v1/data_sources/{data_source_id}` |\n\n资料来源：[CLAUDE.md]()\n\n## 使用示例\n\n### 工具调用示例\n\n当用户发出以下指令时：\n\n```\nAdd a page titled \"Notion MCP\" to page \"Development\"\n```\n\nAI 助手会自动规划并调用以下 API 操作：\n\n1. `v1/search` - 查找名为 \"Development\" 的页面\n2. `v1/pages` - 创建新页面\n\n### 工具引用方式\n\n工具支持以下引用方式：\n\n| 方式 | 示例 |\n|------|------|\n| 页面标题 | `Comment \"Hello MCP\" on page \"Getting started\"` |\n| 页面 ID | `Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2` |\n\n## 测试框架\n\n### 测试配置\n\n测试文件位于源文件同级的 `__tests__` 目录中，使用 Vitest 测试框架：\n\n```bash\nnpm test # 运行所有测试\nnpm run test:watch # 监视模式\nnpm run test:coverage # 生成覆盖率报告\n```\n\n### 依赖包\n\n| 包名 | 用途 |\n|------|------|\n| `@modelcontextprotocol/sdk` | MCP 协议实现 |\n| `axios` | HTTP 请求处理 |\n| `openapi-client-axios` | OpenAPI 客户端生成 |\n| `zod` | Schema 验证 |\n\n资料来源：[package.json]()\n\n## 扩展机制\n\n### 添加新端点\n\n要添加新的 API 端点，只需修改 `scripts/notion-openapi.json` 文件，无需修改其他代码：\n\n1. 在 `paths` 对象中添加新的端点定义\n2. 设置唯一的 `operationId`\n3. 定义 parameters 和 requestBody\n4. 定义 response schema\n\n系统会自动：\n- 生成新的 MCP 工具定义\n- 更新工具注册表\n- 处理参数序列化和反序列化\n\n资料来源：[CLAUDE.md]()\n\n### 自定义 Header 配置\n\n对于需要自定义 headers 的高级用例，可通过 `OPENAPI_MCP_HEADERS` 环境变量传入：\n\n```json\n{\n \"Authorization\": \"Bearer ntn_****\",\n \"Notion-Version\": \"2025-09-03\"\n}\n\n---\n\n\n\n## 安装与客户端配置\n\n### 相关页面\n\n相关主题：[传输层配置详解](#page-7), [本地开发与测试指南](#page-8)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [docker-compose.yml](https://github.com/makenotion/notion-mcp-server/blob/main/docker-compose.yml)\n- [Dockerfile](https://github.com/makenotion/notion-mcp-server/blob/main/Dockerfile)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [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)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n
\n\n# 安装与客户端配置\n\n本文档详细说明 Notion MCP Server 的安装方式、Docker 部署方案以及各主流 AI 客户端的配置方法。\n\n## 概述\n\nNotion MCP Server 是官方提供的 Model Context Protocol (MCP) 服务器，用于将 Notion API 以 MCP 工具的形式暴露给 AI 客户端。项目采用 TypeScript 开发，支持两种传输模式（STDIO 和 Streamable HTTP）和多种认证方式。\n\n核心依赖包括：\n- `@modelcontextprotocol/sdk` (^1.25.1) - MCP 协议实现\n- `axios` (^1.8.4) - HTTP 请求处理\n- `express` (^4.21.2) - HTTP 传输层支持\n- `zod` (3.24.1) - 参数验证\n\n资料来源：[package.json:1-50]()\n\n## 环境准备\n\n### 前置条件\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 18+ | 支持原生 Headers 类 |\n| npm | 9+ | 包管理 |\n| Docker | 20+ | Docker 部署方式 |\n\n> **注意**：Headers 类在 Node.js 18+ 才原生支持，较低版本使用 polyfill 实现。\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-10]()\n\n### Notion 集成配置\n\n1. 访问 [Notion 开发者平台](https://www.notion.so/profile/integrations) 创建内部集成或选择已有集成\n2. 复制集成的 Secret Token（格式：`ntn_****`）\n3. 访问目标页面，点击右上角「...」→「连接」→「连接到集成」\n\n## 安装方式\n\n### NPM 安装（推荐）\n\nNPM 安装是使用 Notion MCP Server 最便捷的方式，适用于 Cursor、Claude Desktop、Zed 等主流 AI 客户端。\n\n```bash\n# 使用 NOTION_TOKEN（推荐）\nnpx -y @notionhq/notion-mcp-server\n\n# 或使用 OPENAPI_MCP_HEADERS（高级场景）\nnpx -y @notionhq/notion-mcp-server --transport http\n```\n\n资料来源：[README.md:80-95]()\n\n### Docker 安装\n\n#### 选项一：使用官方 Docker Hub 镜像\n\n官方镜像 `mcp/notion` 托管在 Docker Hub，无需本地构建即可快速部署。\n\n```bash\n# 拉取官方镜像\ndocker pull mcp/notion\n\n# 使用 NOTION_TOKEN 运行\ndocker run --rm -i -e NOTION_TOKEN=\"ntn_****\" mcp/notion\n```\n\n资料来源：[README.md:140-155]()\n\n#### 选项二：本地构建 Docker 镜像\n\n如果需要自定义配置或使用最新代码，可选择本地构建：\n\n```bash\n# 构建镜像\ndocker compose build\n\n# 或使用 docker build\ndocker build -t notion-mcp-server .\n```\n\n构建配置如下：\n\n```dockerfile\nFROM node:20-slim\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --production\nCOPY . .\nCMD [\"node\", \"bin/cli.mjs\"]\n```\n\n资料来源：[Dockerfile:1-10]()\n\n```yaml\nservices:\n notion-mcp-server:\n build: .\n container_name: notion-mcp-server\n environment:\n - NOTION_TOKEN=${NOTION_TOKEN}\n stdin_open: true\n tty: true\n```\n\n资料来源：[docker-compose.yml:1-15]()\n\n## 客户端配置\n\n### 配置架构图\n\n```mermaid\ngraph TD\n A[AI 客户端] --> B[MCP 配置文件]\n B --> C{传输模式}\n C -->|STDIO| D[notion-mcp-server 进程]\n C -->|HTTP| E[notion-mcp-server HTTP 服务]\n D --> F[Notion API]\n E --> F\n```\n\n### Cursor / Claude Desktop\n\n#### 配置路径\n\n- **Cursor**: `~/.cursor/mcp.json`\n- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n#### 使用 NOTION_TOKEN（推荐）\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n#### 使用 OPENAPI_MCP_HEADERS（高级场景）\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:95-125]()\n\n### Zed 编辑器\n\nZed 通过 `settings.json` 的 `context_servers` 配置项支持 MCP 服务器。\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n资料来源：[README.md:75-88]()\n\n### GitHub Copilot CLI\n\n#### 交互式配置\n\n```bash\n/mcp add\n```\n\n#### 手动配置\n\n编辑 `~/.copilot/mcp-config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:88-103]()\n\n### Docker 环境下的客户端配置\n\n#### 使用 Docker Hub 镜像\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n#### 本地构建镜像\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md:155-185]()\n\n## 传输模式与认证\n\n### STDIO 传输模式（默认）\n\nSTDIO 是默认传输模式，通过标准输入输出与客户端通信：\n\n```bash\nnpx -y @notionhq/notion-mcp-server\n```\n\n### HTTP 传输模式\n\nHTTP 传输模式启动一个 HTTP 服务器，适合远程部署和需要认证的场景：\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --port 3000\n```\n\n服务器默认监听 `http://0.0.0.0:3000/mcp`。\n\n资料来源：[scripts/start-server.ts:20-35]()\n\n### 认证机制\n\nHTTP 传输模式支持 bearer token 认证：\n\n| 认证方式 | 配置方法 | 优先级 |\n|----------|----------|--------|\n| 命令行参数 | `--auth-token \"token\"` | 最高 |\n| 环境变量 | `AUTH_TOKEN=\"token\"` | 中 |\n| 自动生成 | 不指定则自动生成 | 仅开发环境 |\n\n#### 自动生成 token（仅开发环境）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http\n```\n\n输出示例：\n\n```\nGenerated auth token: a1b2c3d4e5f6789...\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789...\n```\n\n#### 自定义 token（生产环境推荐）\n\n```bash\n# 通过命令行\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# 或通过环境变量\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n#### 禁用认证（不推荐）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --disable-auth\n```\n\n#### HTTP 请求示例\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n## 命令行参数\n\n```bash\nnotion-mcp-server [options]\n\nOptions:\n --transport 传输类型: 'stdio' 或 'http'（默认: stdio）\n --port HTTP 服务器端口（默认: 3000）\n --auth-token Bearer token 认证\n --disable-auth 禁用认证\n --help, -h 显示帮助信息\n\nEnvironment Variables:\n NOTION_TOKEN Notion 集成 token（推荐）\n OPENAPI_MCP_HEADERS JSON 格式的 Notion API 请求头\n AUTH_TOKEN HTTP 传输认证 token\n```\n\n资料来源：[scripts/start-server.ts:10-30]()\n\n## 开发环境配置\n\n### 本地开发设置\n\n1. **链接本地包**：\n\n```bash\nnpm link\n```\n\n2. **配置 MCP 客户端**：\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. **清理**：\n\n```bash\nnpm unlink\n```\n\n### 构建与测试\n\n```bash\n# 构建项目\nnpm run build\n\n# 运行测试\nnpm test\n\n# 监听模式开发\nnpm run dev\n```\n\n### 本地执行\n\n```bash\nnpx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server\n```\n\n资料来源：[README.md:200-230]()\n\n## 环境变量详解\n\n| 变量名 | 用途 | 示例值 |\n|--------|------|--------|\n| `NOTION_TOKEN` | Notion 集成 Secret Token | `ntn_1a2b3c4d5e...` |\n| `OPENAPI_MCP_HEADERS` | 自定义 API 请求头（JSON） | `{\"Authorization\": \"Bearer ...\", \"Notion-Version\": \"2025-09-03\"}` |\n| `AUTH_TOKEN` | HTTP 传输认证 token | `my-secret-token` |\n\n> **注意**：`OPENAPI_MCP_HEADERS` 中的 JSON 必须正确转义。在 shell 中使用时，建议使用单引号包裹整个 JSON 字符串。\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-30]()\n\n## 参数反序列化\n\nMCP 工具调用时，参数以字符串形式传递。服务器会自动反序列化 JSON 格式的参数字符串：\n\n```mermaid\ngraph LR\n A[MCP 客户端
参数值: '{\"filter\": {...}}'] --> B[字符串传递]\n B --> C[反序列化检查]\n C -->|JSON 对象/数组| D[解析为对象]\n C -->|其他| E[保持原值]\n```\n\n支持的类型：\n- JSON 对象字符串：`'{\"key\": \"value\"}'`\n- JSON 数组字符串：`'[\"item1\", \"item2\"]'`\n- 嵌套对象的递归反序列化\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-40]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 认证失败 401 | 检查 `NOTION_TOKEN` 是否正确，或确认 Bearer token 与 `--auth-token` 匹配 |\n| 页面访问被拒绝 | 确认已在目标页面「连接」到对应集成 |\n| Docker 容器启动失败 | 检查 `NOTION_TOKEN` 环境变量是否正确传递 |\n| Node 版本过低 | 升级到 Node.js 18+ |\n\n### 验证配置\n\n1. 启动服务器并检查输出日志\n2. 确认客户端成功连接（查看客户端日志）\n3. 尝试执行简单命令如搜索页面\n\n## 发布包\n\n```bash\nnpm login\nnpm publish --access public\n```\n\n资料来源：[README.md:230-235]()\n\n## 相关文档\n\n- [官方 README](https://github.com/makenotion/notion-mcp-server#readme)\n- [Notion API 文档](https://developers.notion.com/reference/intro)\n- [MCP 协议规范](https://spec.modelcontextprotocol.io/)\n\n---\n\n\n\n## HTTP 客户端与网络请求处理\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#page-2), [认证机制与安全配置](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# HTTP 客户端与网络请求处理\n\n## 概述\n\nNotion MCP Server 的 HTTP 客户端模块负责执行所有与 Notion API 的网络通信。该模块封装了底层的 HTTP 请求逻辑，将 OpenAPI 规范定义的 API 操作转换为可执行的 HTTP 调用。\n\n核心职责包括：\n\n- 构建符合 Notion API 规范的 HTTP 请求\n- 处理请求参数（路径参数、查询参数、请求体）\n- 管理请求头和认证信息\n- 处理表单数据和二进制内容\n- 转换响应格式\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-198]()\n\n## 架构设计\n\n### 模块结构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCPProxy │\n│ (工具注册与请求路由) │\n└─────────────────────┬───────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ HttpClient │\n│ (HTTP 请求执行层) │\n│ ┌─────────────────────────────────────────────────────┐ │\n│ │ 参数处理 │ 请求构建 │ 响应转换 │ 错误处理 │ │\n│ └─────────────────────────────────────────────────────┘ │\n└─────────────────────┬───────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Notion API │\n│ (https://api.notion.com) │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### HTTP 客户端类\n\n`HttpClient` 类是网络请求的核心执行器，在初始化时接收基础配置：\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `baseUrl` | `string` | API 基础地址（默认 Notion API） |\n| `headers` | `Record` | 全局请求头 |\n| `openApiSpec` | `OpenAPIV3.Document` | OpenAPI 规范文档 |\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:18-23]()\n\n## HttpClient 实现详解\n\n### 类初始化\n\n```typescript\nexport class HttpClient {\n constructor(\n private config: HttpClientConfig,\n private openApiSpec: OpenAPIV3.Document\n ) {\n this.api = this.createApiClient()\n }\n}\n```\n\n构造函数完成以下初始化：\n\n1. 存储配置参数\n2. 创建 axios API 客户端实例\n3. 准备处理 OpenAPI 规范中定义的请求\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:15-26]()\n\n### 请求参数处理\n\n`HttpClient` 根据 OpenAPI 规范中的参数定义，智能分配参数到不同的请求位置：\n\n```mermaid\ngraph TD\n A[接收参数对象] --> B{存在 requestBody?}\n B -->|是| C{参数类型为 FormData?}\n B -->|否| D[将参数转为 URL 查询参数]\n C -->|是| E[设置 FormData Headers]\n C -->|否| F[设置 JSON Content-Type]\n D --> G[执行 HTTP 请求]\n E --> G\n F --> G\n```\n\n参数分配逻辑：\n\n| 参数位置 | 处理方式 | 来源 |\n|----------|----------|------|\n| `path` | 直接替换 URL 路径占位符 | `operation.parameters` |\n| `query` | 添加到 URL 查询字符串 | `operation.parameters` |\n| `body` | 作为请求体发送 | `operation.requestBody` |\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:55-77]()\n\n### 请求体处理\n\n当没有定义 `requestBody` 且没有 FormData 时，所有剩余参数自动转为 URL 参数：\n\n```typescript\n// Add all parameters as url parameters if there is no requestBody defined\nif (!operation.requestBody && !formData) {\n for (const key in bodyParams) {\n if (bodyParams[key] !== undefined) {\n urlParameters[key] = bodyParams[key]\n delete bodyParams[key]\n }\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:66-74]()\n\n### Content-Type 处理\n\n`HttpClient` 根据请求内容类型动态设置请求头：\n\n| 场景 | Content-Type |\n|------|--------------|\n| 有请求体 | `application/json` |\n| FormData | 使用 FormData 的自动检测 |\n| 无请求体 | `null`（移除 Content-Type） |\n\n```typescript\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:79-88]()\n\n## 请求头管理\n\n### Headers Polyfill\n\n由于 Node.js 18 之前版本不支持原生的 `Headers` 类，项目实现了兼容性 polyfill：\n\n```typescript\nclass PolyfillHeaders {\n private headers: Map = new Map();\n\n public append(name: string, value: string): void {\n const key = name.toLowerCase();\n if (!this.headers.has(key)) {\n this.headers.set(key, []);\n }\n this.headers.get(key)!.push(value);\n }\n\n public get(name: string): string | null {\n const key = name.toLowerCase();\n if (!this.headers.has(key)) {\n return null;\n }\n return this.headers.get(key)!.join(', ');\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-45]()\n\n### Polyfill 特性\n\n| 特性 | 实现说明 |\n|------|----------|\n| 大小写不敏感 | 所有 key 自动转为小写存储 |\n| 多值支持 | `append()` 方法支持添加多个同名值 |\n| 兼容性 | 优先使用原生 `Headers`，回退到 polyfill |\n\n### 响应头转换\n\naxios 响应的 headers 对象会被转换为标准 `Headers` 实例：\n\n```typescript\nconst responseHeaders = new Headers()\nObject.entries(response.headers).forEach(([key, value]) => {\n if (typeof value === 'string') {\n responseHeaders.append(key, value)\n }\n})\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:103-108]()\n\n## 请求执行流程\n\n### 完整请求流程\n\n```mermaid\nsequenceDiagram\n participant 调用方\n participant MCPProxy\n participant HttpClient\n participant NotionAPI\n\n 调用方->>MCPProxy: 调用工具\n MCPProxy->>HttpClient: executeOperation(operationId, params)\n HttpClient->>HttpClient: 解析 OpenAPI 操作定义\n HttpClient->>HttpClient: 分离 path/query/body 参数\n HttpClient->>HttpClient: 构建请求配置\n HttpClient->>NotionAPI: HTTP 请求\n NotionAPI-->>HttpClient: 响应数据\n HttpClient->>HttpClient: 转换响应头\n HttpClient-->>MCPProxy: 格式化响应\n MCPProxy-->>调用方: 返回结果\n```\n\n### 操作查找\n\n每个 API 操作通过 `operationId` 查找对应的 HTTP 方法：\n\n```typescript\nconst operationFn = (api as any)[operationId]\nif (!operationFn) {\n throw new Error(`Operation ${operationId} not found`)\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:75-78]()\n\n## 配置与初始化\n\n### MCPProxy 中的 HTTP 客户端\n\n`MCPProxy` 在初始化时创建 `HttpClient` 实例：\n\n```typescript\nthis.httpClient = new HttpClient(\n {\n baseUrl,\n headers: this.parseHeadersFromEnv(),\n },\n openApiSpec,\n)\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:29-35]()\n\n### 从环境变量解析请求头\n\n项目支持通过 `OPENAPI_MCP_HEADERS` 环境变量配置请求头：\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headersEnv = process.env.OPENAPI_MCP_HEADERS\n if (headersEnv) {\n try {\n return JSON.parse(headersEnv)\n } catch {\n return {}\n }\n }\n return {}\n}\n```\n\n常用配置示例：\n\n```json\n{\n \"Authorization\": \"Bearer ntn_xxxx\",\n \"Notion-Version\": \"2025-09-03\"\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:15-26]()\n\n### 服务端初始化\n\n`init-server.ts` 负责加载 OpenAPI 规范并创建代理：\n\n```typescript\nexport async function initProxy(specPath: string, baseUrl: string | undefined) {\n const openApiSpec = await loadOpenApiSpec(specPath, baseUrl)\n const proxy = new MCPProxy('Notion API', openApiSpec)\n return proxy\n}\n```\n\n资料来源：[src/init-server.ts:44-50]()\n\n## 错误处理\n\n### 操作未找到\n\n当 `operationId` 不存在于 API 客户端中时：\n\n```typescript\nconst operationFn = (api as any)[operationId]\nif (!operationFn) {\n throw new Error(`Operation ${operationId} not found`)\n}\n```\n\n### 文件读取错误\n\n规范文件加载失败时的处理：\n\n```typescript\ntry {\n rawSpec = fs.readFileSync(path.resolve(process.cwd(), specPath), 'utf-8')\n} catch (error) {\n console.error('Failed to read OpenAPI specification file:', (error as Error).message)\n process.exit(1)\n}\n```\n\n资料来源：[src/init-server.ts:22-27]()\n\n## 传输层支持\n\n### STDIO 传输（默认）\n\n默认情况下，MCP 服务器使用 STDIO 传输，适用于本地集成：\n\n```bash\nnotion-mcp-server\n```\n\n### HTTP 传输\n\n支持 HTTP 传输模式，用于远程访问：\n\n```bash\nnotion-mcp-server --transport http --port 3000\n```\n\nHTTP 传输需要认证令牌：\n\n```bash\n# 自动生成令牌\nnotion-mcp-server --transport http\n\n# 自定义令牌\nnotion-mcp-server --transport http --auth-token \"your-token\"\n```\n\n资料来源：[scripts/start-server.ts:1-40]()\n\n## 最佳实践\n\n### 请求头配置\n\n推荐使用 `NOTION_TOKEN` 环境变量进行配置：\n\n```bash\nNOTION_TOKEN=ntn_xxxx notion-mcp-server\n```\n\n高级场景可使用 `OPENAPI_MCP_HEADERS`：\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_xxxx\", \"Notion-Version\": \"2025-09-03\"}' notion-mcp-server\n```\n\n### 本地开发测试\n\n使用 `npm link` 创建全局符号链接进行本地测试：\n\n```bash\nnpm link\n```\n\n配置客户端使用本地包：\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n## 总结\n\nHTTP 客户端模块是 Notion MCP Server 与 Notion API 通信的桥梁。通过封装底层的 HTTP 请求逻辑，提供了：\n\n- **参数自动路由**：智能区分 path、query、body 参数\n- **格式自动适配**：根据内容类型设置正确的 Content-Type\n- **跨版本兼容**：Headers polyfill 确保 Node.js 18 以下版本兼容\n- **配置灵活**：支持环境变量和命令行参数配置\n\n该设计遵循了单一职责原则，使网络请求处理与业务逻辑解耦，便于维护和测试。\n\n---\n\n\n\n## 认证机制与安全配置\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#page-2), [传输层配置详解](#page-7)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# 认证机制与安全配置\n\nNotion MCP Server 提供多层认证机制，支持通过环境变量、命令行参数和 HTTP 传输层认证来保护对 Notion API 的访问。本页面详细说明服务器启动、API 认证和 HTTP 传输安全的完整配置流程。\n\n## 认证体系概述\n\nNotion MCP Server 采用双层认证架构：\n\n| 层级 | 认证对象 | 认证方式 | 配置方式 |\n|------|----------|----------|----------|\n| **API 认证层** | Notion API 请求 | Bearer Token / Header | `NOTION_TOKEN` 或 `OPENAPI_MCP_HEADERS` |\n| **传输认证层** | HTTP 传输通道 | Bearer Token | `--auth-token` 或 `AUTH_TOKEN` |\n\n资料来源：[scripts/start-server.ts:1-100]()\n\n```mermaid\ngraph TD\n A[客户端请求] --> B{传输类型}\n B -->|stdio| C[直接通信]\n B -->|http| D[传输层认证]\n \n D --> E{验证 Bearer Token}\n E -->|通过| F[解析请求]\n E -->|失败| G[401 未授权]\n \n F --> H{API 认证}\n H -->|NOTION_TOKEN| I[使用环境变量 Token]\n H -->|OPENAPI_MCP_HEADERS| J[使用自定义 Header]\n \n I --> K[调用 Notion API]\n J --> K\n```\n\n## 环境变量配置\n\n### NOTION_TOKEN（推荐方式）\n\nNotion 集成令牌是访问 Notion API 的主要认证凭证。\n\n```bash\nNOTION_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxx npx -y @notionhq/notion-mcp-server\n```\n\n**配置位置**：[scripts/start-server.ts:26-27]() 在启动时读取环境变量\n\n```typescript\nconst notionToken = process.env.NOTION_TOKEN\n```\n\n> **注意**：集成令牌需在 Notion 开发者门户中创建，并为目标页面授予访问权限。\n\n### OPENAPI_MCP_HEADERS（高级配置）\n\n当需要自定义请求头时使用，如指定 Notion API 版本：\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_xxxx\", \"Notion-Version\": \"2025-09-03\"}' \\\nnpx -y @notionhq/notion-mcp-server\n```\n\n**Header 解析逻辑**：[src/init-server.ts:39-52]() 通过 `parseHeadersFromEnv()` 方法处理\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headersEnv = process.env.OPENAPI_MCP_HEADERS\n if (!headersEnv) return {}\n \n try {\n return JSON.parse(headersEnv)\n } catch {\n throw new Error('OPENAPI_MCP_HEADERS must be valid JSON')\n }\n}\n```\n\n## HTTP 传输层认证\n\n当使用 `--transport http` 模式时，服务器启用额外的 Bearer Token 认证层。\n\n### 命令行参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--transport ` | 传输类型：`stdio` 或 `http` | `stdio` |\n| `--port ` | HTTP 服务器端口 | `3000` |\n| `--auth-token ` | 传输层认证令牌 | 自动生成 |\n| `--disable-auth` | 禁用传输层认证 | `false`（默认启用） |\n| `--help`, `-h` | 显示帮助信息 | - |\n\n资料来源：[scripts/start-server.ts:1-35]()\n\n### 认证模式\n\n#### 自动生成令牌（仅限开发环境）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http\n```\n\n服务器启动时会输出自动生成的令牌：\n\n```\nGenerated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789...\n```\n\n#### 自定义令牌（推荐用于生产环境）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n#### 环境变量配置\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n**优先级**：`--auth-token` > `AUTH_TOKEN` 环境变量\n\n资料来源：[scripts/start-server.ts:17-24]()\n\n### 令牌验证流程\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant S as MCP Server\n \n C->>S: HTTP POST /mcp (无 Authorization)\n S-->>C: 401 Unauthorized\n \n C->>S: HTTP POST /mcp (Bearer invalid-token)\n S-->>C: 401 Unauthorized\n \n C->>S: HTTP POST /mcp (Bearer valid-token)\n S->>S: 验证令牌\n S->>S: 解析 JSON-RPC 请求\n S->>C: JSON-RPC 响应\n```\n\n## 认证头传递机制\n\nHTTP 客户端负责将认证信息传递给 Notion API：\n\n```mermaid\ngraph LR\n A[环境变量] -->|OPENAPI_MCP_HEADERS| B[HttpClient]\n C[NOTION_TOKEN] -->|Bearer Token| B\n B --> D[Authorization: Bearer ntn_xxx]\n B --> E[Notion-Version: 2025-09-03]\n D --> F[Notion API]\n E --> F\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50]()\n\n### 客户端初始化\n\n```typescript\nthis.httpClient = new HttpClient(\n {\n baseUrl,\n headers: this.parseHeadersFromEnv(),\n },\n openApiSpec,\n)\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:35-42]()\n\n## 安全配置最佳实践\n\n### 生产环境配置\n\n| 配置项 | 建议值 | 理由 |\n|--------|--------|------|\n| `NOTION_TOKEN` | 必需设置 | API 访问凭证 |\n| `AUTH_TOKEN` | 使用强随机字符串 | 保护 HTTP 传输通道 |\n| `--disable-auth` | **勿使用** | 关闭认证存在安全风险 |\n| `--port` | 非标准端口 | 减少暴露面 |\n\n### Docker 环境配置\n\n#### 方式一：使用 NOTION_TOKEN\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"mcp/notion\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_xxxx\"\n }\n }\n }\n}\n```\n\n#### 方式二：使用 OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"OPENAPI_MCP_HEADERS\", \"mcp/notion\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_xxxx\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n### Cursor/Claude Desktop 配置\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_xxxx\"\n }\n }\n }\n}\n```\n\n## 错误处理\n\n| 错误场景 | HTTP 状态码 | 响应 |\n|----------|-------------|------|\n| 未提供传输层令牌 | 401 | `Unauthorized` |\n| 令牌验证失败 | 401 | `Unauthorized` |\n| JSON 解析失败 | 400 | `Bad Request` |\n| Notion API 错误 | 相应状态码 | API 响应内容 |\n\n```typescript\n// 错误处理示例\n} catch (error) {\n if (error instanceof ValidationError) {\n console.error('Invalid OpenAPI 3.1 specification:')\n error.errors.forEach(err => console.error(err))\n } else {\n console.error('Error:', error)\n }\n process.exit(1)\n}\n```\n\n资料来源：[scripts/start-server.ts:85-93]()\n\n## 命令行帮助信息\n\n```bash\nUsage: notion-mcp-server [options]\n\nOptions:\n --transport Transport type: 'stdio' or 'http' (default: stdio)\n --port Port for HTTP server when using Streamable HTTP transport (default: 3000)\n --auth-token Bearer token for HTTP transport authentication (auto-generated if not provided)\n --disable-auth Disable bearer token authentication for HTTP transport\n --help, -h Show this help message\n\nEnvironment Variables:\n NOTION_TOKEN Notion integration token (recommended)\n OPENAPI_MCP_HEADERS JSON string with Notion API headers (alternative)\n AUTH_TOKEN Bearer token for HTTP transport authentication (alternative to --auth-token)\n```\n\n## 快速参考\n\n| 场景 | 推荐配置 |\n|------|----------|\n| 本地开发 (stdio) | `NOTION_TOKEN=ntn_xxx notion-mcp-server` |\n| 本地开发 (HTTP) | `NOTION_TOKEN=ntn_xxx notion-mcp-server --transport http` |\n| 生产环境 | 使用 `--auth-token` 指定强密码，启用 HTTPS 反向代理 |\n| Docker 运行 | 使用环境变量挂载或配置文件 |\n\n---\n\n\n\n## 传输层配置详解\n\n### 相关页面\n\n相关主题：[安装与客户端配置](#page-4), [认证机制与安全配置](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# 传输层配置详解\n\n## 概述\n\nNotion MCP Server 支持两种传输层协议，用于与 MCP 客户端进行通信。传输层是 MCP 服务器与客户端之间数据传输的核心抽象，负责处理请求的序列化和反序列化、会话管理以及认证机制。资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## 传输类型\n\n| 传输类型 | 说明 | 默认端口 | 适用场景 |\n|---------|------|---------|---------|\n| `stdio` | 标准输入输出流 | - | 本地开发、直接进程调用 |\n| `http` | Streamable HTTP | 3000 | 远程访问、微服务架构 |\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n## stdio 传输模式\n\nstdio（Standard Input/Output）是 MCP 协议的默认传输方式，适用于本地进程通信场景。在这种模式下，服务器通过标准输入读取来自客户端的 JSON-RPC 请求，并通过标准输出返回响应。\n\n### 工作原理\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|stdin| B[notion-mcp-server]\n B -->|stdout| A\n```\n\nstdio 传输模式的优势在于：\n- 配置简单，无需额外的网络配置\n- 适合自动化测试和本地开发\n- 进程生命周期由客户端管理\n\n### 使用方式\n\n```bash\n# 默认使用 stdio 传输\nnpx -y @notionhq/notion-mcp-server\n\n# 显式指定 stdio 传输\nnpx @notionhq/notion-mcp-server --transport stdio\n```\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n## HTTP 传输模式\n\nHTTP 传输模式基于 Model Context Protocol 的 Streamable HTTP 规范实现，提供了更灵活的远程访问能力。资料来源：[scripts/start-server.ts:1-80]()\n\n### 架构设计\n\n```mermaid\ngraph TD\n A[MCP 客户端] -->|HTTP 请求| B[Express 服务器]\n B -->|路由| C[Streamable HTTP Handler]\n C -->|认证检查| D{认证状态}\n D -->|有效| E[MCP 代理]\n D -->|无效| F[401 Unauthorized]\n E -->|处理请求| G[Notion API]\n G -->|响应| E\n E -->|JSON-RPC 响应| B\n```\n\n### 启动参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--transport` | string | `stdio` | 传输类型 |\n| `--port` | number | `3000` | HTTP 服务端口 |\n| `--auth-token` | string | 自动生成 | 认证令牌 |\n| `--disable-auth` | boolean | `false` | 禁用认证 |\n\n资料来源：[scripts/start-server.ts:15-40]()\n\n### 命令行示例\n\n```bash\n# 基础 HTTP 模式（自动生成认证令牌）\nnpx @notionhq/notion-mcp-server --transport http\n\n# 指定端口\nnpx @notionhq/notion-mcp-server --transport http --port 8080\n\n# 自定义认证令牌（推荐用于生产环境）\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# 禁用认证（仅用于开发环境）\nnpx @notionhq/notion-mcp-server --transport http --disable-auth\n```\n\n资料来源：[scripts/start-server.ts:10-45]()\n\n## 认证机制\n\nHTTP 传输模式强制使用 Bearer Token 认证，以防止未授权访问。\n\n### 认证方式优先级\n\n1. **命令行参数** `--auth-token`（最高优先级）\n2. **环境变量** `AUTH_TOKEN`\n3. **自动生成**（仅开发模式）\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant C as MCP 客户端\n participant S as MCP 服务器\n participant N as Notion API\n \n C->>S: HTTP 请求 + Authorization Header\n Note over S: 验证 Bearer Token\n alt 认证失败\n S-->>C: 401 Unauthorized\n else 认证成功\n S->>N: API 请求\n N-->>S: API 响应\n S-->>C: JSON-RPC 响应\n end\n```\n\n### 请求示例\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n## 环境变量配置\n\nNotion MCP Server 支持多种环境变量配置方式，用于设置 API 凭证和自定义请求头。\n\n### 配置参数\n\n| 环境变量 | 说明 | 推荐用途 |\n|---------|------|---------|\n| `NOTION_TOKEN` | Notion 集成令牌 | 推荐用于标准配置 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的自定义请求头 | 高级配置场景 |\n| `AUTH_TOKEN` | HTTP 传输认证令牌 | 生产环境部署 |\n\n### 配置示例\n\n```bash\n# 方式一：使用 NOTION_TOKEN（推荐）\nexport NOTION_TOKEN=\"ntn_****\"\nnpx @notionhq/notion-mcp-server --transport http\n\n# 方式二：使用 OPENAPI_MCP_HEADERS\nexport OPENAPI_MCP_HEADERS='{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}'\nnpx @notionhq/notion-mcp-server --transport http\n\n# 方式三：使用 AUTH_TOKEN\nexport AUTH_TOKEN=\"secure-auth-token\"\nnpx @notionhq/notion-mcp-server --transport http\n```\n\n## 客户端配置\n\n### Cursor / Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Zed Editor\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n## Docker 部署\n\n### 方式一：使用官方镜像\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"mcp/notion\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### 方式二：本地构建\n\n```bash\ndocker compose build\n```\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n## 核心组件架构\n\n```mermaid\ngraph TD\n subgraph 传输层\n A[stdio 传输]\n B[HTTP 传输]\n end\n \n subgraph 核心服务\n C[MCPProxy]\n D[HttpClient]\n E[OpenAPIToMCPConverter]\n end\n \n subgraph 工具系统\n F[工具注册]\n G[参数反序列化]\n H[API 执行]\n end\n \n A --> C\n B --> C\n C --> D\n C --> E\n E --> F\n F --> G\n G --> H\n```\n\n### MCPProxy 类\n\n`MCPProxy` 是传输层与工具系统之间的桥梁，负责：\n\n- 初始化 MCP 服务器实例\n- 注册 OpenAPI 转换后的工具\n- 处理请求参数的反序列化\n- 执行 API 调用并返回响应\n\n```typescript\nexport class MCPProxy {\n private server: Server\n private httpClient: HttpClient\n private tools: Record\n private openApiLookup: Record\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:50-100]()\n\n### 参数反序列化\n\nMCP 协议在传输过程中会将嵌套对象序列化为字符串，服务器端需要反序列化这些参数：\n\n```typescript\nfunction deserializeParams(params: Record): Record {\n // 处理 JSON 字符串形式的嵌套对象\n // 处理数组中的 JSON 字符串元素\n // 递归反序列化\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:10-50]()\n\n## 配置决策矩阵\n\n| 使用场景 | 传输模式 | 认证方式 | 推荐配置 |\n|---------|---------|---------|---------|\n| 本地开发调试 | stdio | 无 | `npm run dev` |\n| 生产环境（远程） | http | `--auth-token` | 环境变量 + 令牌 |\n| Docker 部署 | http | 环境变量 | `NOTION_TOKEN` |\n| 团队共享 | http | 统一令牌 | 配置文件管理 |\n\n## 故障排除\n\n### 常见问题\n\n1. **连接被拒绝**\n - 检查端口是否被占用：`lsof -i :3000`\n - 确认防火墙规则允许访问\n\n2. **认证失败**\n - 验证 Bearer Token 与服务器配置一致\n - 检查 `Authorization` 头部格式是否正确\n\n3. **工具调用失败**\n - 确认 `NOTION_TOKEN` 有效且已配置到目标页面\n - 检查 OpenAPI 请求头配置\n\n### 调试模式\n\n使用 `tsx watch` 启动开发服务器以获取详细日志：\n\n```bash\nnpm run dev\n```\n\n资料来源：[package.json:10-20]()\n\n## 总结\n\nNotion MCP Server 的传输层设计遵循 Model Context Protocol 规范，提供了 stdio 和 HTTP 两种传输模式以适应不同的部署场景。stdio 模式适合本地开发和测试，而 HTTP 模式则支持远程访问和微服务架构。通过命令行参数和环境变量的灵活组合，用户可以根据实际需求选择合适的认证和配置方案。\n\n---\n\n\n\n## 本地开发与测试指南\n\n### 相关页面\n\n相关主题：[安装与客户端配置](#page-4), [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n
\n\n# 本地开发与测试指南\n\n本指南详细介绍如何搭建本地开发环境、运行测试、调试代码以及发布 `notion-mcp-server` 包。该服务器是基于 MCP (Model Context Protocol) 的 Notion API 实现，通过 OpenAPI 规范自动生成 MCP 工具。\n\n## 环境准备\n\n### 系统要求\n\n| 要求项 | 最低版本 | 推荐版本 |\n|--------|----------|----------|\n| Node.js | Node.js 20+ | Node.js 22 LTS |\n| npm | npm 10+ | npm 10+ |\n| Docker | Docker 24+ | Docker 最新版 |\n\n### 安装依赖\n\n项目使用 ES Modules (ESM) 模块系统，TypeScript 版本为 5.8.2。安装依赖前请确保 Node.js 版本符合要求：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/makenotion/notion-mcp-server.git\ncd notion-mcp-server\n\n# 安装依赖\nnpm install\n```\n\n资料来源：[package.json:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### 环境变量配置\n\n开发环境需要配置 Notion API 认证信息。可通过以下方式配置：\n\n| 环境变量 | 说明 | 必需 |\n|----------|------|------|\n| `NOTION_TOKEN` | Notion 集成密钥（推荐） | 是 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 请求头 | 否 |\n| `AUTH_TOKEN` | HTTP 传输层认证令牌 | 仅 HTTP 模式 |\n| `NODE_ENV` | 运行环境 (`test` 用于测试) | 测试时必需 |\n\n资料来源：[README.md:100-120](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## 项目架构\n\n### 核心模块结构\n\n```\nnotion-mcp-server/\n├── scripts/\n│ ├── notion-openapi.json # OpenAPI 3.1.0 规范（所有工具的来源）\n│ └── start-server.ts # 服务器启动入口\n├── src/\n│ └── openapi-mcp-server/\n│ ├── openapi/\n│ │ └── parser.ts # OpenAPI → MCP 工具转换\n│ ├── mcp/\n│ │ └── proxy.ts # MCP 工具注册与执行\n│ └── client/\n│ └── http-client.ts # HTTP 请求执行\n└── __tests__/ # 测试文件目录\n```\n\n### 工具生成流程\n\nMCP 工具通过 OpenAPI 规范自动生成，无需手动编写代码：\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[每个 operation 生成一个 MCP 工具]\n C --> D[参数 → inputSchema]\n C --> E[响应 → returnSchema]\n D --> F[MCPProxy.setupHandlers]\n E --> F\n F --> G[MCP SDK 注册工具]\n```\n\n资料来源：[CLAUDE.md:20-35](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## 开发命令\n\n### 常用命令\n\n| 命令 | 说明 | 用途 |\n|------|------|------|\n| `npm run build` | TypeScript 编译 + CLI 打包 | 生产构建 |\n| `npm run dev` | 热重载开发服务器 | 实时调试 |\n| `npm test` | 运行 vitest 测试 | 单元测试 |\n| `npm run test:watch` | 监听模式运行测试 | TDD 开发 |\n| `npm run test:coverage` | 生成测试覆盖率报告 | 代码覆盖率 |\n\n资料来源：[package.json:8-13](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### 构建流程\n\n`npm run build` 命令执行两个步骤：\n\n1. **TypeScript 编译**：`tsc -build` 编译 TypeScript 源代码\n2. **CLI 打包**：`node scripts/build-cli.js` 将代码打包为 CLI 可执行文件\n\n构建产物：\n- `index.js`：主入口\n- `bin/cli.mjs`：CLI 可执行文件\n\n```bash\n# 完整构建\nnpm run build\n\n# 仅编译 TypeScript（不打包 CLI）\ntsc -build\n\n# 热重载开发\nnpm run dev\n```\n\n资料来源：[package.json:8](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## 测试框架\n\n### Vitest 配置\n\n项目使用 Vitest 4.0.18 作为测试框架，与 Vite 集成提供快速的单元测试能力。\n\n测试文件位置遵循约定：与源文件同目录的 `__tests__` 子目录：\n\n```\nsrc/openapi-mcp-server/openapi/\n├── parser.ts\n└── __tests__/\n └── parser.test.ts\n```\n\n运行测试时需要设置 `NODE_ENV=test` 环境变量：\n\n```bash\n# 运行所有测试\nnpm test\n\n# 监听模式（文件变化时自动重新运行）\nnpm run test:watch\n\n# 生成覆盖率报告\nnpm run test:coverage\n```\n\n资料来源：[package.json:11-13](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### 参数反序列化测试\n\n`proxy.ts` 中的 `deserializeParams` 函数负责将 JSON 字符串参数反序列化为对象。测试覆盖以下场景：\n\n- JSON 对象字符串 → 对象\n- JSON 数组字符串 → 数组\n- 嵌套对象的递归反序列化\n- 无效 JSON 字符串保留原值\n\n```typescript\n// 测试示例\nconst input = { filter: '[{\"property\":\"Name\",\"checkbox\":{\"equals\":true}}]' }\nconst result = deserializeParams(input)\n// result.filter 变为数组而非字符串\n```\n\n资料来源：[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)\n\n## 本地测试配置\n\n### Cursor 客户端测试\n\n在 Cursor 中测试本地修改的步骤：\n\n```mermaid\ngraph LR\n A[npm link] --> B[创建全局符号链接]\n B --> C[修改 mcp.json 配置]\n C --> D[Cursor 连接本地包]\n D --> E[测试 MCP 工具]\n E --> F{npm unlink 清理}\n```\n\n**步骤 1**：在仓库根目录创建符号链接\n\n```bash\nnpm link\n```\n\n**步骤 2**：修改 Cursor 的 `mcp.json` 配置\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n**步骤 3**：测试完成后清理\n\n```bash\nnpm unlink\n```\n\n资料来源：[README.md:85-105](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### 命令行直接执行\n\n本地构建后可使用 `npx` 直接执行：\n\n```bash\n# 使用本地路径执行\nnpx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server\n```\n\n## HTTP 传输模式调试\n\n### 启动带认证的 HTTP 服务器\n\n```bash\n# 自动生成认证令牌（仅用于开发）\nnpx @notionhq/notion-mcp-server --transport http\n\n# 指定自定义令牌\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# 使用环境变量指定令牌\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n### 启动参数说明\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--transport` | 传输类型：`stdio` 或 `http` | `stdio` |\n| `--port` | HTTP 服务器端口 | `3000` |\n| `--auth-token` | 认证令牌 | 自动生成 |\n| `--disable-auth` | 禁用认证 | - |\n| `--help`, `-h` | 显示帮助信息 | - |\n\n资料来源：[scripts/start-server.ts:15-30](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### HTTP 请求示例\n\n使用认证令牌发起请求：\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n## Docker 开发\n\n### 本地构建 Docker 镜像\n\n```bash\n# 构建镜像\ndocker compose build\n\n# 运行容器\ndocker compose up\n```\n\n### Docker 配置示例\n\n使用环境变量传递 Notion 令牌（推荐）：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"notion-mcp-server\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n使用 OPENAPI_MCP_HEADERS（高级场景）：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"OPENAPI_MCP_HEADERS\",\n \"notion-mcp-server\"\n ],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_****\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:55-90](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## 发布流程\n\n### npm 发布\n\n```bash\n# 登录 npm\nnpm login\n\n# 发布包（需要 public 访问权限）\nnpm publish --access public\n```\n\n### 版本管理\n\n当前版本：`2.3.0`\n\n包名称：`@notionhq/notion-mcp-server`\n\n发布前请确保：\n1. 所有测试通过：`npm test`\n2. 构建成功：`npm run build`\n3. 更新版本号（在 `package.json` 中）\n\n资料来源：[package.json:4-7](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## OpenAPI 解析器开发\n\n### 模式转换逻辑\n\n`parser.ts` 实现了 OpenAPI Schema 到 JSON Schema 的转换：\n\n```mermaid\ngraph TD\n A[OpenAPI Schema] --> B{类型判断}\n B -->|binary format| C[转换为 uri-reference]\n B -->|object| D[处理 properties]\n B -->|array| E[递归处理 items]\n B -->|enum| F[保留 enum 值]\n B -->|oneOf/anyOf| G[递归转换子模式]\n C --> H[JSON Schema]\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n### 关键转换规则\n\n| OpenAPI 特性 | 转换处理 |\n|--------------|----------|\n| `format: binary` | 转为 `format: uri-reference` |\n| `type: object` | 保留 `properties` 和 `required` |\n| `type: array` | 递归处理 `items` |\n| `additionalProperties` | 布尔值或递归处理对象 |\n| `oneOf/anyOf/allOf` | 递归转换子模式 |\n| `const` | 保留用于 discriminator |\n\n资料来源：[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)\n\n## 常见问题排查\n\n### 问题：模块导入错误\n\n确保使用 ES Modules 运行，检查 `package.json` 中 `\"type\": \"module\"` 配置。\n\n### 问题：测试找不到文件\n\n检查测试文件是否位于源文件同级的 `__tests__` 目录中，文件名应匹配 `*.test.ts` 模式。\n\n### 问题：HTTP 认证失败\n\n确认请求头中包含正确的 `Authorization: Bearer `，且令牌与服务器配置一致。\n\n### 问题：TypeScript 编译错误\n\n运行 `npm run build` 前确保已安装所有依赖，必要时删除 `node_modules` 后重新安装。\n\n---\n\n\n\n## 从 v1.x 到 v2.0.0 迁移指南\n\n### 相关页面\n\n相关主题：[项目介绍与版本说明](#page-1), [MCP 工具集详解](#page-3)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# 从 v1.x 到 v2.0.0 迁移指南\n\n## 概述\n\nNotion MCP Server v2.0.0 是该项目的重大版本更新，主要迁移到 **Notion API 2025-09-03** 版本（即 Data Source Edition）。此次更新引入了 **data sources（数据源）** 作为数据库的主要抽象概念，取代了传统的 `database` 概念。\n\n> **重要提示**：v2.0.0 **不需要代码更改**。MCP 工具在服务器启动时自动被发现。当你升级到 v2.0.0 时，AI 客户端将自动看到新的工具名称和参数，旧版数据库工具将不再可用。\n\n资料来源：[README.md:100-105]()\n\n## 版本变化总览\n\n### 工具变化统计\n\n| 变更类型 | 数量 | 说明 |\n|---------|------|------|\n| 移除工具 | 3 个 | 被新数据源工具替代 |\n| 新增工具 | 7 个 | 完整的数据源操作能力 |\n| 工具总数 | 22 个 | v1.x 为 19 个 |\n\n资料来源：[README.md:106-108]()\n\n### 架构变化图示\n\n```mermaid\ngraph TD\n subgraph v1.x 架构\n A1[数据库操作] -->|database_id| B1[post-database-query]\n A1 -->|database_id| B2[update-a-database]\n A1 -->|database_id| B3[create-a-database]\n end\n \n subgraph v2.0.0 架构\n A2[数据源操作] -->|data_source_id| C1[query-data-source]\n A2 -->|data_source_id| C2[update-a-data-source]\n A2 -->|data_source_id| C3[create-a-data-source]\n A2 -->|data_source_id| C4[retrieve-a-data-source]\n A2 -->|data_source_id| C5[list-data-source-templates]\n end\n \n A2 -.->|page_id / database_id| C6[move-page]\n A2 -.->|向后兼容| C7[retrieve-a-database]\n \n style A1 fill:#ffcccc\n style A2 fill:#ccffcc\n style B1 fill:#ffcccc\n style B2 fill:#ffcccc\n style B3 fill:#ffcccc\n style C1 fill:#ccffcc\n style C2 fill:#ccffcc\n style C3 fill:#ccffcc\n style C4 fill:#ccffcc\n style C5 fill:#ccffcc\n```\n\n## 移除的工具\n\n以下三个工具已被新工具替代，不再可用：\n\n| 旧工具名称 (v1.x) | 替代工具 (v2.0) | 用途 |\n|-----------------|---------------|------|\n| `post-database-query` | `query-data-source` | 查询数据源 |\n| `update-a-database` | `update-a-data-source` | 更新数据源 |\n| `create-a-database` | `create-a-data-source` | 创建数据源 |\n\n资料来源：[README.md:72-74]()\n\n## 新增的工具\n\n### 数据源操作工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `query-data-source` | 使用过滤器和排序查询数据源 |\n| `retrieve-a-data-source` | 获取数据源的元数据和架构 |\n| `update-a-data-source` | 更新数据源属性 |\n| `create-a-data-source` | 创建新的数据源 |\n| `list-data-source-templates` | 列出数据源中的可用模板 |\n\n### 页面操作工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `move-page` | 将页面移动到不同的父级位置 |\n| `retrieve-a-database` | 获取数据库元数据（包括数据源 ID 列表） |\n\n资料来源：[README.md:75-83]()\n\n## 参数变更说明\n\n### 核心参数变化\n\n| 变更项 | v1.x | v2.0.0 | 说明 |\n|-------|------|--------|------|\n| 数据库标识符 | `database_id` | `data_source_id` | 所有数据源操作使用新参数名 |\n| 搜索过滤器值 | `[\"page\", \"database\"]` | `[\"page\", \"data_source\"]` | 搜索 API 的过滤器值变更 |\n| 页面创建父级 | 仅 `page_id` | `page_id` 或 `database_id` | 现在支持数据源作为父级 |\n\n资料来源：[README.md:84-87]()\n\n### 参数转换示例\n\n```mermaid\ngraph LR\n subgraph v1.x 参数传递\n A1[\"database_id: 'xxx'\"] --> B1[数据库操作]\n end\n \n subgraph v2.0.0 参数传递\n A2[\"data_source_id: 'xxx'\"] --> B2[数据源操作]\n end\n \n style A1 fill:#ffcccc\n style A2 fill:#ccffcc\n```\n\n## API 版本与端点\n\n### 使用的 API 版本\n\nv2.0.0 使用 **Notion API 版本 `2025-09-03`**（Data Source Edition）。\n\n> 此版本引入了数据源作为数据库的主要抽象，是 Notion API 的重大更新。\n\n资料来源：[CLAUDE.md:38]()\n\n### 新增的 API 端点\n\n| 端点类型 | 端点路径 | 说明 |\n|---------|---------|------|\n| 传统端点 | `/v1/databases/{database_id}` | 保留传统数据库端点 |\n| 新端点 | `/v1/data_sources/{data_source_id}` | 新增数据源端点 |\n\n资料来源：[CLAUDE.md:39-40]()\n\n## 迁移操作指南\n\n### 步骤一：识别硬编码的工具引用\n\n如果你的代码或提示词中硬编码了旧版工具名称，需要进行以下更新：\n\n| 旧工具 (v1.x) | 新工具 (v2.0) | 参数变更 |\n|--------------|---------------|---------|\n| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |\n| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |\n| `create-a-database` | `create-a-data-source` | 参数不变（使用 `parent.page_id`） |\n\n资料来源：[README.md:117-121]()\n\n### 步骤二：更新参数名称\n\n```diff\n# 数据库查询操作\n- tool: \"post-database-query\"\n- params: { \"database_id\": \"xxx\" }\n+ tool: \"query-data-source\"\n+ params: { \"data_source_id\": \"xxx\" }\n\n# 数据库更新操作\n- tool: \"update-a-database\"\n- params: { \"database_id\": \"xxx\", ... }\n+ tool: \"update-a-data-source\"\n+ params: { \"data_source_id\": \"xxx\", ... }\n```\n\n### 步骤三：理解保留的工具\n\n`retrieve-a-database` 工具仍然可用，用于获取数据库元数据。该工具现在会返回数据源 ID 列表。使用 `retrieve-a-data-source` 获取特定数据源的架构和属性。\n\n```mermaid\ngraph TD\n A[retrieve-a-database] -->|获取数据库元数据| B[data_source_ids 列表]\n B --> C[retrieve-a-data-source]\n C -->|获取数据源架构| D[schema 和 properties]\n```\n\n资料来源：[README.md:123-125]()\n\n## MCP 服务器工具自动发现机制\n\nNotion MCP Server 的一个关键特性是**工具自动生成**机制。工具从 OpenAPI 规范自动派生，无需手动代码更改。\n\n### 工具生成流程\n\n```mermaid\ngraph TD\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 规范\"] --> B[\"src/init-server.ts
加载并验证规范\"]\n B --> C[\"openapi/parser.ts
OpenAPIToMCPConverter\"]\n C --> D[\"convertToMCPTools() 方法\"]\n D --> E[\"mcp/proxy.ts
MCPProxy.setupHandlers()\"]\n E --> F[\"MCP SDK 注册工具\"]\n \n subgraph 关键转换逻辑\n C -.->|1. operationId → 工具名| G[\"retrieve-a-data-source\"]\n C -.->|2. parameters + requestBody → inputSchema| H[\"输入参数模式\"]\n C -.->|3. Response schema → returnSchema| I[\"返回模式\"]\n end\n```\n\n资料来源：[CLAUDE.md:18-30]()\n\n### 文件结构说明\n\n| 文件路径 | 职责 |\n|---------|------|\n| `scripts/notion-openapi.json` | OpenAPI 3.1.0 规范（所有工具的来源） |\n| `src/init-server.ts` | 服务器初始化 |\n| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI → MCP 工具转换 |\n| `src/openapi-mcp-server/mcp/proxy.ts` | MCP 工具注册和执行 |\n| `src/openapi-mcp-server/client/http-client.ts` | HTTP 请求执行 |\n\n资料来源：[CLAUDE.md:33-36]()\n\n## 搜索功能变更\n\n### 搜索过滤器值变化\n\nv2.0.0 中，搜索 API 的过滤器值发生了以下变化：\n\n| 对象类型 | v1.x 值 | v2.0.0 值 |\n|---------|---------|----------|\n| 页面 | `\"page\"` | `\"page\"` |\n| 数据库/数据源 | `\"database\"` | `\"data_source\"` |\n\n```mermaid\ngraph LR\n A[搜索过滤器] -->|v1.x| B[\"value: 'database'\"]\n A -->|v2.0.0| C[\"value: 'data_source'\"]\n \n style B fill:#ffcccc\n style C fill:#ccffcc\n```\n\n资料来源：[README.md:85-86]()\n\n## 页面创建增强\n\n### 新增的父级类型支持\n\nv2.0.0 增强了页面创建功能，现在支持两种父级类型：\n\n| 父级类型 | 参数名 | 说明 |\n|---------|--------|------|\n| 页面 | `page_id` | 在现有页面下创建 |\n| 数据源（数据库） | `database_id` | 在数据源下创建页面 |\n\n这使得在数据源中创建条目更加直接，无需先获取数据源对应的页面 ID。\n\n资料来源：[README.md:87-88]()\n\n## 常见问题\n\n### Q1：是否需要修改代码？\n\n**否**。MCP 工具在服务器启动时自动被发现。升级到 v2.0.0 后，AI 客户端会自动看到新的工具名称和参数。\n\n> **唯一例外**：如果你在代码或提示词中**硬编码**了旧版工具名称，则需要手动更新为新工具名称和参数。\n\n资料来源：[README.md:109-113]()\n\n### Q2：如何区分数据库和数据源？\n\n- **数据库（Database）**：传统概念，保留用于向后兼容\n- **数据源（Data Source）**：API 2025-09-03 引入的新概念，是当前的主要抽象\n\n使用 `retrieve-a-database` 获取数据库元数据，其中包含关联的 `data_source_ids` 列表。\n\n资料来源：[README.md:123-125]()\n\n### Q3：如何获取数据源的详细信息？\n\n使用 `retrieve-a-data-source` 工具获取特定数据源的架构和属性：\n\n```typescript\n// 获取数据源详情\ntool: \"retrieve-a-data-source\"\nparams: {\n \"data_source_id\": \"\"\n}\n```\n\n资料来源：[README.md:77]()\n\n## 环境变量配置\n\n### Notion 认证\n\n| 环境变量 | 说明 | 推荐度 |\n|---------|------|--------|\n| `NOTION_TOKEN` | Notion 集成令牌 | ⭐ 推荐 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 头信息 | 高级用法 |\n\n### HTTP 传输认证\n\n| 环境变量 | 说明 |\n|---------|------|\n| `AUTH_TOKEN` | HTTP 传输的 Bearer 令牌（可通过 `--auth-token` 命令行参数覆盖） |\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n## 构建和测试命令\n\n### 常用命令\n\n| 命令 | 功能 |\n|-----|------|\n| `npm run build` | TypeScript 编译 + CLI 打包 |\n| `npm test` | 运行 Vitest 测试 |\n| `npm run dev` | 启动热重载的开发服务器 |\n\n资料来源：[CLAUDE.md:32]()\n\n### 本地测试配置\n\n1. 在仓库根目录运行 `npm link` 创建全局符号链接\n2. 在 Cursor 的 `mcp.json` 中添加配置：\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. 测试完成后，运行 `npm unlink` 清理\n\n资料来源：[README.md:26-40]()\n\n## 总结\n\n### 迁移检查清单\n\n- [ ] 识别代码中硬编码的旧版工具名称\n- [ ] 将 `database_id` 参数更新为 `data_source_id`\n- [ ] 将搜索过滤器值从 `\"database\"` 更新为 `\"data_source\"`\n- [ ] 验证 AI 客户端能自动发现新工具\n- [ ] 测试数据源相关操作（查询、更新、创建）\n\n### 关键变更一览\n\n| 变更类别 | 变更内容 |\n|---------|---------|\n| API 版本 | `2022-06-28` → `2025-09-03` |\n| 移除工具 | 3 个数据库工具 |\n| 新增工具 | 7 个数据源和页面工具 |\n| 工具总数 | 19 → 22 |\n| 核心参数 | `database_id` → `data_source_id` |\n| 搜索过滤器 | `database` → `data_source` |\n| 页面创建 | 支持 `database_id` 作为父级 |\n\n> **记住**：最关键的迁移点是参数名称的变更（`database_id` → `data_source_id`）和搜索过滤器值的变化。只要更新这两处，你的应用就能平滑迁移到 v2.0.0。\n\n---\n\n\n\n## OpenAPI 规范与文件上传\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#page-2), [MCP 工具集详解](#page-3)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)\n- [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)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n
\n\n# OpenAPI 规范与文件上传\n\n## 概述\n\nNotion MCP Server 的核心设计理念是通过 OpenAPI 3.1.0 规范文件自动生成 MCP 工具。文件上传功能是该架构中的重要组成部分，允许用户通过 MCP 协议上传本地文件到 Notion 服务端。\n\n本文档详细说明 OpenAPI 规范解析机制与二进制文件上传处理的实现原理。\n\n## 架构总览\n\n```\nscripts/notion-openapi.json\n ↓\n OpenAPI 3.1.0 规范\n ↓\nsrc/openapi-mcp-server/openapi/parser.ts\n ↓\n OpenAPI → MCP 工具转换\n ↓\nsrc/openapi-mcp-server/mcp/proxy.ts\n ↓\n MCP 工具注册与调用\n ↓\nsrc/openapi-mcp-server/client/http-client.ts\n ↓\n Notion API HTTP 请求执行\n```\n\n资料来源：[CLAUDE.md:1-30]()\n\n## OpenAPI 规范解析机制\n\n### 规范文件结构\n\n`scripts/notion-openapi.json` 是整个项目的核心数据源，采用 OpenAPI 3.1.0 标准定义所有 Notion API 端点：\n\n| 组件 | 说明 |\n|------|------|\n| `paths` | API 路径与方法定义 |\n| `components.schemas` | 数据模型与类型定义 |\n| `components.parameters` | 可复用参数定义 |\n| `operationId` | 工具名称来源 |\n\n资料来源：[CLAUDE.md:21-22]()\n\n### Schema 转换流程\n\n`OpenAPIToMCPConverter` 类负责将 OpenAPI Schema 转换为 MCP 可用的 JSON Schema：\n\n```typescript\nconvertOpenApiSchemaToJsonSchema(\n schema: OpenAPIV3.SchemaObject,\n resolvedRefs: Set,\n resolveRefs: boolean\n): IJsonSchema\n```\n\n转换过程中包含以下关键处理：\n\n| 特性 | 处理方式 |\n|------|----------|\n| 二进制格式 | 转换为 `uri-reference` |\n| 对象属性 | 递归转换 `properties` |\n| 数组类型 | 递归转换 `items` |\n| 组合类型 | 处理 `oneOf`、`anyOf`、`allOf` |\n| 常量值 | 保留 `const` 字段 |\n| 默认值 | 保留 `default` 字段 |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-100]()\n\n## 二进制文件与上传处理\n\n### Binary 格式转换\n\n当 OpenAPI Schema 中的 `format` 字段为 `binary` 时，解析器会自动进行以下转换：\n\n```typescript\nif (schema.format === 'binary') {\n result.format = 'uri-reference'\n const binaryDesc = 'absolute paths to local files'\n result.description = schema.description \n ? `${schema.description} (${binaryDesc})` \n : binaryDesc\n}\n```\n\n此转换使得 MCP 客户端可以传入本地文件的绝对路径，系统会自动处理文件上传逻辑。\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:50-60]()\n\n### 文件上传流程图\n\n```mermaid\ngraph TD\n A[MCP 客户端调用工具] --> B[解析参数中的 binary 字段]\n B --> C{文件是否存在?}\n C -->|不存在| D[抛出参数错误]\n C -->|存在| E[读取本地文件内容]\n E --> F[构造 multipart/form-data 请求]\n F --> G[HTTP 客户端执行上传]\n G --> H{响应状态}\n H -->|2xx| I[返回成功结果]\n H -->|4xx/5xx| J[抛出 HttpClientError]\n```\n\n## 参数反序列化机制\n\n### 参数处理策略\n\n`deserializeParams` 函数解决了 MCP 协议传输过程中的双重序列化问题：\n\n| 问题场景 | 处理方式 |\n|----------|----------|\n| JSON 字符串对象 | 自动解析为对象 |\n| JSON 字符串数组 | 自动解析为数组 |\n| 嵌套 JSON 字符串 | 递归反序列化 |\n| 普通字符串 | 保持原样 |\n\n```typescript\nfunction deserializeParams(params: Record): Record {\n const result: Record = {}\n \n for (const [key, value] of Object.entries(params)) {\n if (typeof value === 'string') {\n const trimmed = value.trim()\n if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||\n (trimmed.startsWith('[') && trimmed.endsWith(']'))) {\n // JSON.parse and validate...\n }\n }\n // ... more handling\n }\n return result\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:176-210]()\n\n### 数组元素反序列化\n\n数组内的 JSON 字符串元素也会被递归处理：\n\n```typescript\n} else if (Array.isArray(value)) {\n result[key] = value.map((item) => {\n if (typeof item !== 'string') return item\n // ... check and parse JSON strings in array\n })\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:195-208]()\n\n## HTTP 客户端与请求执行\n\n### 请求参数分类\n\nHTTP 客户端将参数分为三类处理：\n\n| 参数类型 | 来源 | 用途 |\n|----------|------|------|\n| `urlParameters` | `path` 和 `query` 参数 | URL 路径与查询字符串 |\n| `bodyParams` | `requestBody` 内容 | JSON 请求体 |\n| `formData` | multipart/form-data | 文件上传表单 |\n\n```typescript\n// 提取 path 和 query 参数\nif (operation.parameters) {\n for (const param of operation.parameters) {\n if (param.in === 'path' || param.in === 'query') {\n if (params[param.name] !== undefined) {\n urlParameters[param.name] = params[param.name]\n }\n }\n }\n}\n\n// 无 requestBody 时，将 bodyParams 转为 URL 参数\nif (!operation.requestBody && !formData) {\n for (const key in bodyParams) {\n if (bodyParams[key] !== undefined) {\n urlParameters[key] = bodyParams[key]\n delete bodyParams[key]\n }\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:80-100]()\n\n### 表单数据处理\n\n当存在 `formData` 时，HTTP 客户端自动设置正确的 `Content-Type` 头：\n\n```typescript\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:110-115]()\n\n## 工具注册与执行\n\n### MCP 工具生成\n\n`MCPProxy.setupHandlers()` 方法负责将 OpenAPI 操作转换为 MCP 工具：\n\n```typescript\nsetupHandlers(tools: Record) {\n this.server.setRequestHandler(ListToolsRequestSchema, async () => {\n const toolDefs = []\n for (const method of methods) {\n toolDefs.push({\n name: method.name,\n description: method.description,\n inputSchema: method.inputSchema,\n annotations: {\n title: this.operationIdToTitle(method.name),\n ...(isReadOnly ? { readOnlyHint: true } : { destructiveHint: true }),\n },\n })\n }\n return { tools: toolDefs }\n })\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:150-170]()\n\n### 工具调用处理\n\n当 MCP 客户端调用工具时，系统执行以下步骤：\n\n```mermaid\nsequenceDiagram\n 客户端->>MCP服务器: CallToolRequest(name, arguments)\n MCP服务器->>代理: findOperation(name)\n 代理-->>MCP服务器: OperationObject\n MCP服务器->>参数反序列化: deserializeParams(arguments)\n 参数反序列化-->>MCP服务器: deserializedParams\n MCP服务器->>HTTP客户端: executeOperation(operation, deserializedParams)\n HTTP客户端->>Notion API: HTTP Request\n Notion API-->>HTTP客户端: Response\n HTTP客户端-->>MCP服务器: response.data\n MCP服务器-->>客户端: { content: [{ type: 'text', text: JSON.stringify(data) }] }\n```\n\n## 错误处理\n\n### HTTP 客户端错误\n\n`HttpClientError` 异常包含状态码和响应数据：\n\n```typescript\nreturn {\n content: [\n {\n type: 'text',\n text: JSON.stringify(error.data?.response?.data ?? error.data ?? {}),\n },\n ],\n isError: true,\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:200-210]()\n\n## 配置与运行环境\n\n### 环境变量\n\n| 变量名 | 说明 | 优先级 |\n|--------|------|--------|\n| `NOTION_TOKEN` | Notion 集成令牌（推荐） | 高 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的自定义请求头 | 中 |\n\n### 命令行参数\n\n```bash\nnotion-mcp-server [选项]\n\n选项:\n --transport 传输类型: 'stdio' 或 'http'\n --port HTTP 服务端口 (默认: 3000)\n --auth-token HTTP 传输认证令牌\n --disable-auth 禁用 HTTP 认证\n --help, -h 显示帮助信息\n```\n\n资料来源：[scripts/start-server.ts:60-80]()\n\n## 开发指南\n\n### 本地测试文件上传\n\n1. **构建项目**：\n ```bash\n npm run build\n ```\n\n2. **链接本地包**：\n ```bash\n npm link\n ```\n\n3. **配置 MCP 客户端**：\n ```json\n {\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n }\n ```\n\n4. **测试文件上传**：\n ```\n Upload file \"/path/to/document.pdf\" to page \"My Page\"\n ```\n\n5. **清理**：\n ```bash\n npm unlink\n ```\n\n资料来源：[README.md:Development]()\n\n## 相关资源\n\n- **OpenAPI 规范文件**：[scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)\n- **Notion API 版本**：`2025-09-03` (Data Source Edition)\n- **API 端点类型**：\n - `/v1/databases/{database_id}` - 传统数据库端点\n - `/v1/data_sources/{data_source_id}` - 新数据源端点\n\n资料来源：[CLAUDE.md:40-45]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：makenotion/notion-mcp-server\n\n摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。\n\n## 1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown\n\n\n", "markdown_key": "notion-mcp-server", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:946169991", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/makenotion/notion-mcp-server" }, { "evidence_id": "art_bfa1c23dbdf04dfb9dd7a72bb6d25333", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/makenotion/notion-mcp-server#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "notion-mcp-server 说明书", "toc": [ "https://github.com/makenotion/notion-mcp-server 项目说明书", "目录", "项目介绍与版本说明", "项目概述", "系统架构", "版本 2.0.0 重大变更", "迁移指南", "环境配置", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "3bef7addac59b237da3bb41f36a520babc47fa3c", "repo_inspection_error": null, "repo_inspection_files": [ "Dockerfile", "package.json", "README.md", "docker-compose.yml", "src/init-server.ts", "src/openapi-mcp-server/index.ts", "src/openapi-mcp-server/README.md", "src/openapi-mcp-server/mcp/proxy.ts", "src/openapi-mcp-server/client/polyfill-headers.ts", "src/openapi-mcp-server/client/http-client.ts", "src/openapi-mcp-server/openapi/parser.ts", "src/openapi-mcp-server/openapi/file-upload.ts", "src/openapi-mcp-server/auth/template.ts", "src/openapi-mcp-server/auth/index.ts", "src/openapi-mcp-server/auth/types.ts", "src/openapi-mcp-server/mcp/__tests__/proxy.test.ts", "src/openapi-mcp-server/client/__tests__/http-client.integration.test.ts", "src/openapi-mcp-server/client/__tests__/http-client.test.ts", "src/openapi-mcp-server/client/__tests__/http-client-upload.test.ts", "src/openapi-mcp-server/openapi/__tests__/parser-multipart.test.ts", "src/openapi-mcp-server/openapi/__tests__/parser.test.ts", "src/openapi-mcp-server/openapi/__tests__/file-upload.test.ts" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# @notionhq/notion-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @notionhq/notion-mcp-server 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx @notionhq/notion-mcp-server` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86 等\n- `npx @notionhq/notion-mcp-server --transport stdio` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx @notionhq/notion-mcp-server --transport http` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86\n- `npx @notionhq/notion-mcp-server --transport http --port 8080` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `curl -H \"Authorization: Bearer your-token-here\" \\` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server` 证据：`README.md` Claim：`clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `scripts/start-server.ts`, `src/openapi-mcp-server/mcp/__tests__/proxy.test.ts`, `src/openapi-mcp-server/mcp/proxy.ts`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：33\n- 重要文件覆盖：16/33\n- 证据索引条目：16\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @notionhq/notion-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @notionhq/notion-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @notionhq/notion-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **CLAUDE.md**（project_doc）：This file provides guidance for Claude Code when working with this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **Notion MCP Server**（project_doc）：!NOTE We’ve introduced Notion MCP , a remote MCP server with the following improvements: - Easy installation via standard OAuth. No need to fiddle with JSON or API tokens anymore. - Powerful tools tailored to AI agents, including editing pages in Markdown. These tools are designed with optimized token consumption in mind. Learn more and get started at Notion MCP documentation https://developers.notion.com/docs/mcp .… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Readme**（project_doc）：Note: This is a fork from v1 of https://github.com/snaggle-ai/openapi-mcp-server. The library took a different direction with v2 which is not compatible with our development approach. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`src/openapi-mcp-server/README.md`\n- **Description**（project_doc）：- Automated test unit, integration, etc. - Manual test provide reproducible testing steps below 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/pull_request_template.md`\n\n## 证据索引\n\n- 共索引 16 条证据。\n\n- **CLAUDE.md**（documentation）：This file provides guidance for Claude Code when working with this repository. 证据：`CLAUDE.md`\n- **Notion MCP Server**（documentation）：!NOTE We’ve introduced Notion MCP , a remote MCP server with the following improvements: - Easy installation via standard OAuth. No need to fiddle with JSON or API tokens anymore. - Powerful tools tailored to AI agents, including editing pages in Markdown. These tools are designed with optimized token consumption in mind. Learn more and get started at Notion MCP documentation https://developers.notion.com/docs/mcp . We are prioritizing, and only providing active support for, Notion MCP remote . As a result: - We may sunset this local MCP server repository in the future. - Issues and pull requests here are not actively monitored. - Please do not file issues relating to the remote MCP here; i… 证据：`README.md`\n- **Readme**（documentation）：Note: This is a fork from v1 of https://github.com/snaggle-ai/openapi-mcp-server. The library took a different direction with v2 which is not compatible with our development approach. 证据：`src/openapi-mcp-server/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@notionhq/notion-mcp-server\", \"keywords\": \"notion\", \"api\", \"mcp\", \"server\" , \"version\": \"2.3.0\", \"license\": \"MIT\", \"type\": \"module\", \"scripts\": { \"build\": \"tsc -build && node scripts/build-cli.js\", \"dev\": \"tsx watch scripts/start-server.ts\", \"test\": \"NODE ENV=test vitest run\", \"test:watch\": \"NODE ENV=test vitest\", \"test:coverage\": \"NODE ENV=test vitest run --coverage\" }, \"bin\": { \"notion-mcp-server\": \"bin/cli.mjs\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.25.1\", \"axios\": \"^1.8.4\", \"express\": \"^4.21.2\", \"form-data\": \"^4.0.1\", \"mustache\": \"^4.2.0\", \"node-fetch\": \"^3.3.2\", \"openapi-client-axios\": \"^7.5.5\", \"openapi-schema-validator\": \"^12.1.3\", \"openapi-types\": \"^12.1.3\"… 证据：`package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Description**（documentation）：- Automated test unit, integration, etc. - Manual test provide reproducible testing steps below 证据：`.github/pull_request_template.md`\n- **Notion Openapi**（structured_config）：{ \"openapi\": \"3.1.0\", \"info\": { \"title\": \"Notion API\", \"version\": \"2.0.0\", \"description\": \"Notion API 2025-09-03 - Data Source Edition. Breaking change: Database endpoints replaced with data source endpoints.\", \"license\": { \"name\": \"MIT\", \"url\": \"https://github.com/makenotion/notion-sdk-js/blob/main/LICENSE\" } }, \"servers\": { \"url\": \"https://api.notion.com\" } , \"components\": { \"securitySchemes\": { \"bearerAuth\": { \"type\": \"http\", \"scheme\": \"bearer\" }, \"basicAuth\": { \"type\": \"http\", \"scheme\": \"basic\" } }, \"parameters\": { \"notionVersion\": { \"name\": \"Notion-Version\", \"in\": \"header\", \"required\": false, \"schema\": { \"type\": \"string\", \"default\": \"2025-09-03\" }, \"description\": \"The Notion API versio… 证据：`scripts/notion-openapi.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"composite\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"outDir\": \"./build\", \"target\": \"es2021\", \"lib\": \"es2022\" , \"jsx\": \"react-jsx\", \"module\": \"es2022\", \"moduleResolution\": \"Bundler\", \"types\": \"node\" , \"resolveJsonModule\": true, \"allowJs\": true, \"checkJs\": false, \"isolatedModules\": true, \"allowSyntheticDefaultImports\": true, \"forceConsistentCasingInFileNames\": true, \"strict\": true, \"skipLibCheck\": true }, \"include\": \"test/ / .ts\", \"scripts/ / .ts\", \"src/ / .ts\" } 证据：`tsconfig.json`\n- **.dockerignore**（source_file）：node modules Dockerfile docker-compose.yml 证据：`.dockerignore`\n- **.gitignore**（source_file）：node modules/ build/ dist bin/ .cache .yarn/cache .eslintcache .cursor .DS Store 证据：`.gitignore`\n- **syntax=docker/dockerfile:1**（source_file）：Use Node.js LTS as the base image FROM node:20-slim AS builder 证据：`Dockerfile`\n- **Docker Compose**（source_file）：services: notion-mcp-server: build: . stdin open: true tty: true restart: unless-stopped 证据：`docker-compose.yml`\n- **Build Cli**（source_file）：import as esbuild from 'esbuild'; import { chmod } from 'fs/promises'; import { fileURLToPath } from 'url'; import { dirname, join } from 'path'; 证据：`scripts/build-cli.js`\n- **Start Server**（source_file）：import path from 'node:path' import { fileURLToPath } from 'url' import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js' import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js' import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js' import { randomUUID, randomBytes } from 'node:crypto' import fs from 'node:fs' import os from 'node:os' import express from 'express' 证据：`scripts/start-server.ts`\n- **Init Server**（source_file）：import fs from 'node:fs' import path from 'node:path' 证据：`src/init-server.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from 'vitest/config' 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `src/openapi-mcp-server/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `src/openapi-mcp-server/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍与版本说明**：importance `high`\n - source_paths: README.md, package.json\n- **系统架构与模块设计**：importance `high`\n - source_paths: src/openapi-mcp-server/index.ts, src/openapi-mcp-server/auth/index.ts, src/openapi-mcp-server/client/http-client.ts, src/openapi-mcp-server/mcp/proxy.ts\n- **MCP 工具集详解**：importance `high`\n - source_paths: scripts/notion-openapi.json, src/openapi-mcp-server/openapi/parser.ts\n- **安装与客户端配置**：importance `high`\n - source_paths: package.json, docker-compose.yml, Dockerfile\n- **HTTP 客户端与网络请求处理**：importance `medium`\n - source_paths: src/openapi-mcp-server/client/http-client.ts, src/openapi-mcp-server/client/polyfill-headers.ts\n- **认证机制与安全配置**：importance `high`\n - source_paths: src/openapi-mcp-server/auth/index.ts, src/openapi-mcp-server/auth/template.ts, src/openapi-mcp-server/auth/types.ts\n- **传输层配置详解**：importance `high`\n - source_paths: src/init-server.ts, scripts/start-server.ts\n- **本地开发与测试指南**：importance `medium`\n - source_paths: package.json, vitest.config.ts, tsconfig.json\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `3bef7addac59b237da3bb41f36a520babc47fa3c`\n- inspected_files: `Dockerfile`, `package.json`, `README.md`, `docker-compose.yml`, `src/init-server.ts`, `src/openapi-mcp-server/index.ts`, `src/openapi-mcp-server/README.md`, `src/openapi-mcp-server/mcp/proxy.ts`, `src/openapi-mcp-server/client/polyfill-headers.ts`, `src/openapi-mcp-server/client/http-client.ts`, `src/openapi-mcp-server/openapi/parser.ts`, `src/openapi-mcp-server/openapi/file-upload.ts`, `src/openapi-mcp-server/auth/template.ts`, `src/openapi-mcp-server/auth/index.ts`, `src/openapi-mcp-server/auth/types.ts`, `src/openapi-mcp-server/mcp/__tests__/proxy.test.ts`, `src/openapi-mcp-server/client/__tests__/http-client.integration.test.ts`, `src/openapi-mcp-server/client/__tests__/http-client.test.ts`, `src/openapi-mcp-server/client/__tests__/http-client-upload.test.ts`, `src/openapi-mcp-server/openapi/__tests__/parser-multipart.test.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：BUG: Tool `query_data_sources` not available\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Notion MCP server does not work with Claude Code\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：makenotion/notion-mcp-server\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：BUG: Tool `query_data_sources` not available（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Notion MCP server does not work with Claude Code（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/makenotion/notion-mcp-server 项目说明书\n\n生成时间：2026-05-16 22:56:19 UTC\n\n## 目录\n\n- [项目介绍与版本说明](#page-1)\n- [系统架构与模块设计](#page-2)\n- [MCP 工具集详解](#page-3)\n- [安装与客户端配置](#page-4)\n- [HTTP 客户端与网络请求处理](#page-5)\n- [认证机制与安全配置](#page-6)\n- [传输层配置详解](#page-7)\n- [本地开发与测试指南](#page-8)\n- [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n- [OpenAPI 规范与文件上传](#page-10)\n\n\n\n## 项目介绍与版本说明\n\n### 相关页面\n\n相关主题：[MCP 工具集详解](#page-3), [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# 项目介绍与版本说明\n\n## 项目概述\n\nNotion MCP Server 是 Notion 官方提供的 MCP（Model Context Protocol）服务器，用于将 Notion API 作为 MCP 工具暴露给 AI 客户端使用。该项目通过自动生成的方式从 OpenAPI 规范创建 MCP 工具，无需手动编写工具代码。\n\n**核心特性：**\n\n- 自动从 OpenAPI 3.1.0 规范生成 MCP 工具\n- 支持 stdio 和 Streamable HTTP 两种传输模式\n- 使用 Notion API 版本 `2025-09-03`（Data Source Edition）\n- 提供 22 个 MCP 工具（v2.0.0 版本）\n- 支持 Cursor、Claude、Zed、GitHub Copilot CLI 等主流 MCP 客户端\n\n资料来源：[README.md:1-50]()\n\n---\n\n## 系统架构\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json] --> B[OpenAPI 3.1.0 规范]\n B --> C[src/init-server.ts]\n C --> D[创建 MCPProxy 实例]\n D --> E[OpenAPIToMCPConverter]\n E --> F[生成 MCP 工具定义]\n F --> G[MCPProxy.setupHandlers]\n G --> H[MCP SDK 注册工具]\n H --> I[AI 客户端调用工具]\n I --> J[HttpClient 执行 API 请求]\n J --> K[Notion API]\n \n subgraph 核心模块\n E\n F\n G\n end\n```\n\n### 目录结构\n\n| 路径 | 说明 |\n|------|------|\n| `scripts/notion-openapi.json` | OpenAPI 3.1.0 规范定义文件（所有工具的源头） |\n| `scripts/start-server.ts` | 服务器入口点，处理命令行参数 |\n| `src/init-server.ts` | 服务器初始化，加载和验证规范 |\n| `src/openapi-mcp-server/` | 核心 MCP 服务器实现 |\n| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI 到 MCP 工具的转换逻辑 |\n| `src/openapi-mcp-server/mcp/proxy.ts` | MCP 工具注册和执行 |\n| `src/openapi-mcp-server/client/http-client.ts` | HTTP 请求执行 |\n\n资料来源：[CLAUDE.md:1-30]()\n\n### 工具生成流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 客户端\n participant MCP as MCP SDK\n participant Proxy as MCPProxy\n participant Parser as OpenAPIToMCPConverter\n participant Client as HttpClient\n participant API as Notion API\n \n AI->>MCP: 调用工具\n MCP->>Proxy: 分发请求\n Proxy->>Parser: 解析参数\n Parser->>Proxy: 反序列化参数\n Proxy->>Client: 执行 HTTP 请求\n Client->>API: API 调用\n API-->>Client: 返回数据\n Client-->>Proxy: 返回结果\n Proxy-->>MCP: 标准化响应\n MCP-->>AI: 返回结果\n```\n\n工具生成的五个关键步骤：\n\n1. `OpenAPIToMCPConverter.convertToMCPTools()` 遍历所有路径和操作\n2. 每个操作成为一个 MCP 工具（名称来自 `operationId`）\n3. 参数 + requestBody → `inputSchema`\n4. 响应 schema → `returnSchema`\n5. `MCPProxy.setupHandlers()` 注册工具到 MCP SDK\n\n资料来源：[CLAUDE.md:35-55]()\n\n---\n\n## 版本 2.0.0 重大变更\n\n**版本 2.0.0 迁移到 Notion API 2025-09-03**，该版本引入了数据源（Data Source）作为数据库的主要抽象。\n\n### 变更概览\n\n```mermaid\ngraph LR\n A[数据库工具 v1.x] -->|迁移| B[数据源工具 v2.0]\n A1[post-database-query] --> B1[query-data-source]\n A2[update-a-database] --> B2[update-a-data-source]\n A3[create-a-database] --> B3[create-a-data-source]\n```\n\n### 移除的工具（3个）\n\n| 旧工具（v1.x） | 替代工具（v2.0） |\n|--------------|----------------|\n| `post-database-query` | `query-data-source` |\n| `update-a-database` | `update-a-data-source` |\n| `create-a-database` | `create-a-data-source` |\n\n资料来源：[README.md:120-140]()\n\n### 新增的工具（7个）\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `query-data-source` | 使用过滤器和排序查询数据源（数据库） |\n| `retrieve-a-data-source` | 获取数据源的元数据和 schema |\n| `update-a-data-source` | 更新数据源属性 |\n| `create-a-data-source` | 创建新的数据源 |\n| `list-data-source-templates` | 列出数据源中的可用模板 |\n| `move-page` | 将页面移动到不同的父位置 |\n| `retrieve-a-database` | 获取数据库元数据，包括数据源 ID 列表 |\n\n资料来源：[README.md:145-165]()\n\n### 参数变更\n\n| 变更类型 | v1.x | v2.0 |\n|---------|------|------|\n| 数据库操作参数 | `database_id` | `data_source_id` |\n| 搜索过滤器值 | `[\"page\", \"database\"]` | `[\"page\", \"data_source\"]` |\n| 页面创建父级 | 仅 `page_id` | `page_id` 或 `database_id` |\n\n资料来源：[README.md:170-185]()\n\n---\n\n## 迁移指南\n\n### 是否需要迁移？\n\n**无需代码更改。** MCP 工具在服务器启动时自动被发现。升级到 v2.0.0 后，AI 客户端将自动看到新的工具名称和参数。旧的数据库工具将不再可用。\n\n### 迁移对照表\n\n| 旧工具（v1.x） | 新工具（v2.0） | 参数变更 |\n|--------------|---------------|---------|\n| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |\n| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |\n| `create-a-database` | `create-a-data-source` | 无变化（使用 `parent.page_id`） |\n\n> **注意：** `retrieve-a-database` 仍然可用，返回数据库元数据包括数据源 ID 列表。使用 `retrieve-a-data-source` 获取特定数据源的 schema 和属性。\n\n资料来源：[README.md:190-210]()\n\n### 工具总数\n\n- **v1.x: 19 个工具**\n- **v2.0: 22 个工具**（新增 7 个，移除 3 个，保留 1 个兼容工具）\n\n---\n\n## 环境配置\n\n### 环境变量\n\n| 变量名 | 说明 | 优先级 |\n|-------|------|--------|\n| `NOTION_TOKEN` | Notion 集成令牌（推荐） | - |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 头信息 | 替代方案 |\n| `AUTH_TOKEN` | HTTP 传输认证令牌 | CLI 参数优先 |\n\n资料来源：[README.md:55-80]()\n\n### 传输模式\n\n| 模式 | 说明 | 默认端口 |\n|------|------|---------|\n| `stdio` | 标准输入输出传输（默认） | - |\n| `http` | Streamable HTTP 传输 | 3000 |\n\n**命令行参数：**\n\n```bash\n--transport # 传输类型：'stdio' 或 'http'\n--port # HTTP 服务器端口（默认：3000）\n--auth-token # HTTP 传输认证令牌\n--disable-auth # 禁用认证\n--help, -h # 显示帮助信息\n```\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n---\n\n## 参数反序列化机制\n\nMCPProxy 中的 `deserializeParams` 函数处理参数反序列化：\n\n```mermaid\nflowchart TD\n A[接收参数对象] --> B{参数类型判断}\n B -->|string| C{是否 JSON 字符串}\n B -->|array| D{遍历数组成员}\n B -->|其他| G[直接传递]\n \n C -->|是| E[JSON.parse 解析]\n C -->|否| G\n \n E --> F{解析结果是否为对象}\n F -->|是| H[递归反序列化]\n F -->|否| G\n \n D --> D1{成员是否为字符串}\n D1 -->|是| E\n D1 -->|否| D2[保持原值]\n \n H --> I[返回反序列化结果]\n G --> I\n D2 --> I\n```\n\n该机制确保嵌套的 JSON 字符串参数能够正确反序列化，防止参数传递错误。\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-60]()\n\n---\n\n## 快速开始\n\n### 安装与配置\n\n```bash\n# 方式一：使用 npm\nnpx -y @notionhq/notion-mcp-server\n\n# 方式二：本地开发\nnpm install\nnpm run build\nnpm link # 创建全局符号链接\n```\n\n### MCP 客户端配置示例\n\n**Cursor/Claude 配置文件**（`~/.cursor/mcp.json`）：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:100-130]()\n\n### 构建与测试\n\n| 命令 | 说明 |\n|------|------|\n| `npm run build` | TypeScript 编译 + CLI 打包 |\n| `npm test` | 运行 vitest 测试 |\n| `npm run dev` | 启动开发服务器（热重载） |\n\n资料来源：[CLAUDE.md:20-25]()\n\n---\n\n## 相关链接\n\n- 官方文档：https://developers.notion.com/reference/intro\n- MCP 协议规范：https://spec.modelcontextprotocol.io/\n- 问题反馈：https://github.com/makenotion/notion-mcp-server/issues\n\n---\n\n\n\n## 系统架构与模块设计\n\n### 相关页面\n\n相关主题：[项目介绍与版本说明](#page-1), [HTTP 客户端与网络请求处理](#page-5), [认证机制与安全配置](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/openapi-mcp-server/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/index.ts)\n- [src/openapi-mcp-server/auth/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts)\n- [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)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n
\n\n# 系统架构与模块设计\n\n## 概述\n\nNotion MCP Server 是一个实现 MCP（Model Context Protocol）协议的服务器，用于将 Notion API 暴露为 MCP 工具供 AI 代理使用。该项目采用自动生成架构，通过 OpenAPI 规范定义所有工具，无需为每个 API 端点编写独立代码。\n\n### 核心设计理念\n\n| 设计原则 | 说明 |\n|---------|------|\n| 规范驱动 | 所有工具从 `notion-openapi.json` 自动生成 |\n| 零手动维护 | 新增 API 端点只需修改 OpenAPI 规范 |\n| 多协议兼容 | 支持 STDIO 和 HTTP 两种传输协议 |\n| 标准化转换 | OpenAPI → MCP / OpenAI / Anthropic 工具格式 |\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph \"数据源层\"\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 规范\"]\n end\n \n subgraph \"核心处理层\"\n B[\"init-server.ts
服务器初始化\"]\n C[\"parser.ts
OpenAPI → MCP 转换器\"]\n D[\"proxy.ts
MCP 工具代理\"]\n end\n \n subgraph \"传输层\"\n E[\"STDIO 传输\"]\n F[\"HTTP/Streamable 传输\"]\n end\n \n subgraph \"外部调用\"\n G[\"AI 客户端
Cursor/Claude/Copilot\"]\n end\n \n A --> B\n B --> C\n C --> D\n D --> E\n D --> F\n E --> G\n F --> G\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e9\n```\n\n## 模块详解\n\n### 1. 入口模块 (scripts/start-server.ts)\n\n服务器启动入口，负责命令行参数解析和传输协议选择。\n\n#### 支持的参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--transport` | string | `stdio` | 传输类型：`stdio` 或 `http` |\n| `--port` | number | `3000` | HTTP 服务器端口 |\n| `--auth-token` | string | 自动生成 | HTTP 传输的认证令牌 |\n| `--disable-auth` | boolean | `false` | 禁用认证 |\n| `--help` | - | - | 显示帮助信息 |\n\n#### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `NOTION_TOKEN` | Notion 集成令牌（推荐） |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 请求头 |\n| `AUTH_TOKEN` | HTTP 传输认证令牌（备选） |\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n### 2. 服务器初始化 (src/init-server.ts)\n\n负责加载 OpenAPI 规范、验证配置并创建 MCP 服务器实例。\n\n#### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant 启动脚本\n participant init-server\n participant MCPProxy\n participant OpenAPI规范\n \n 启动脚本->>init-server: 加载 OpenAPI 规范\n init-server->>MCPProxy: 创建代理实例\n MCPProxy->>OpenAPI规范: 解析端点\n MCPProxy->>MCPProxy: 注册工具处理器\n init-server->>启动脚本: 返回服务器实例\n```\n\n资料来源：[src/init-server.ts](), [src/openapi-mcp-server/mcp/proxy.ts:1-50]()\n\n### 3. OpenAPI 解析器 (src/openapi-mcp-server/openapi/parser.ts)\n\n核心转换模块，将 OpenAPI 3.1.0 规范转换为 MCP 工具定义。\n\n#### 主要功能\n\n- 解析 OpenAPI 路径和操作\n- 转换 JSON Schema 参数定义\n- 生成 MCP 工具的 `inputSchema` 和 `returnSchema`\n- 支持多种输出格式：MCP、OpenAI ChatCompletion、Anthropic Tool\n\n#### 转换方法\n\n| 方法 | 输出格式 | 用途 |\n|------|----------|------|\n| `convertToMCPTools()` | MCP Tool[] | MCP 协议标准格式 |\n| `convertToOpenAITools()` | ChatCompletionTool[] | OpenAI 函数调用 |\n| `convertToAnthropicTools()` | Tool[] | Anthropic Claude 工具 |\n\n#### Schema 转换处理\n\n```typescript\n// 处理类型映射关系\n- OpenAPI binary → JSON Schema uri-reference\n- object 类型 → 保留 properties 和 additionalProperties\n- array 类型 → 递归转换 items\n- oneOf/anyOf/allOf → 递归处理联合类型\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-100]()\n\n### 4. MCP 代理模块 (src/openapi-mcp-server/mcp/proxy.ts)\n\n负责 MCP 工具的注册、路由和执行。\n\n#### 核心组件\n\n| 组件 | 职责 |\n|------|------|\n| `HttpClient` | 发送 HTTP 请求到 Notion API |\n| `OpenAPIToMCPConverter` | 工具定义转换 |\n| `MCPProxy` | 工具注册与调用处理 |\n\n#### 工具命名规则\n\n- 工具名称来源：`operationId` 字段\n- 长度限制：截断至 64 字符\n- 显示格式：Title Case（如 `RetrieveADatabase`）\n\n#### 请求处理流程\n\n```mermaid\ngraph LR\n A[\"MCP 调用请求\"] --> B[\"解析工具名称\"]\n B --> C[\"查找 OpenAPI 操作\"]\n C --> D[\"提取参数\"]\n D --> E[\"构造 HTTP 请求\"]\n E --> F[\"发送请求到 Notion API\"]\n F --> G[\"返回响应结果\"]\n```\n\n#### 工具注解\n\n| HTTP 方法 | 注解 | 说明 |\n|-----------|------|------|\n| GET | `readOnlyHint: true` | 只读操作 |\n| POST/PATCH/DELETE | `destructiveHint: true` | 可能修改数据的操作 |\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:50-150]()\n\n### 5. HTTP 客户端 (src/openapi-mcp-server/client/http-client.ts)\n\n负责执行实际的 API 调用。\n\n#### 请求构造\n\n```typescript\n// 参数分类处理\n1. 路径参数 (path) → URL 路径占位符\n2. 查询参数 (query) → URL 查询字符串\n3. 请求体 (body) → JSON 请求体\n4. 表单数据 (formData) → multipart/form-data\n```\n\n#### 认证头处理\n\n默认从环境变量读取认证信息：\n- `OPENAPI_MCP_HEADERS`：JSON 格式的完整请求头\n- 自动注入 `Authorization` 和 `Notion-Version`\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-100]()\n\n### 6. 认证模块 (src/openapi-mcp-server/auth/index.ts)\n\n处理 HTTP 传输的 Bearer Token 认证。\n\n#### 认证选项\n\n| 方式 | 优先级 | 说明 |\n|------|--------|------|\n| 命令行 `--auth-token` | 最高 | 显式指定令牌 |\n| 环境变量 `AUTH_TOKEN` | 中 | 环境配置 |\n| 自动生成 | 最低 | 开发模式自动创建 |\n\n#### 认证流程\n\n```mermaid\ngraph TD\n A[\"HTTP 请求到达\"] --> B{\"检查 --disable-auth\"}\n B -->|是| C[\"跳过认证\"]\n B -->|否| D[\"提取 Authorization 头\"]\n D --> E{\"验证 Bearer Token\"}\n E -->|通过| F[\"处理请求\"]\n E -->|失败| G[\"返回 401 错误\"]\n```\n\n资料来源：[src/openapi-mcp-server/auth/index.ts]()\n\n## 数据流架构\n\n```mermaid\nflowchart LR\n subgraph 用户层\n A[\"AI 客户端\"]\n B[\"Notion Token\"]\n end\n \n subgraph MCP服务器\n C[\"STDIO/HTTP 接收\"]\n D[\"工具列表请求\"]\n E[\"工具调用请求\"]\n F[\"工具解析\"]\n G[\"HTTP 执行器\"]\n end\n \n subgraph Notion API\n H[\"Notion API v2025-09-03\"]\n end\n \n A -->|MCP 协议| C\n B -->|认证| G\n C --> D\n C --> E\n E --> F\n F --> G\n G -->|HTTP/REST| H\n H -->|JSON 响应| G\n G -->|MCP 响应| A\n```\n\n## 传输协议\n\n### STDIO 模式\n\n默认传输方式，适用于本地集成。\n\n```bash\nnpx @notionhq/notion-mcp-server\n```\n\n### HTTP/Streamable 模式\n\n适用于远程部署和分布式架构。\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --port 3000\n```\n\n| 特性 | STDIO | HTTP |\n|------|-------|------|\n| 连接方式 | 标准输入/输出 | HTTP 长连接 |\n| 认证 | 无 | Bearer Token |\n| 适用场景 | 本地 IDE | 远程服务 |\n| 状态管理 | 无状态 | Session 支持 |\n\n## 扩展机制\n\n### 添加新 API 端点\n\n仅需修改 `scripts/notion-openapi.json`，工具将自动生成：\n\n```mermaid\ngraph LR\n A[\"修改 notion-openapi.json\"] --> B[\"添加/修改路径\"]\n B --> C[\"定义 operationId\"]\n C --> D[\"npm run build\"]\n D --> E[\"工具自动可用\"]\n```\n\n### 支持的工具格式\n\n| 格式 | 生成方法 | 使用场景 |\n|------|----------|----------|\n| MCP Tool | `convertToMCPTools()` | MCP SDK 原生支持 |\n| OpenAI Function | `convertToOpenAITools()` | GPT 函数调用 |\n| Anthropic Tool | `convertToAnthropicTools()` | Claude 工具使用 |\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n package.json --> express\n package.json --> @modelcontextprotocol-sdk\n package.json --> openapi-types\n \n express --> src/init-server.ts\n @modelcontextprotocol-sdk --> src/openapi-mcp-server/mcp/proxy.ts\n \n src/init-server.ts --> src/openapi-mcp-server/mcp/proxy.ts\n src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/openapi/parser.ts\n src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/client/http-client.ts\n src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/auth/index.ts\n \n src/openapi-mcp-server/openapi/parser.ts --> openapi-types\n scripts/start-server.ts --> src/init-server.ts\n```\n\n## 关键设计决策\n\n### 1. 规范即代码\n\n通过将 OpenAPI 规范作为唯一的工具定义来源，实现了：\n- 单点维护\n- 文档与实现同步\n- 多格式工具自动导出\n\n### 2. 分层架构\n\n| 层级 | 职责 | 隔离性 |\n|------|------|--------|\n| 传输层 | 协议适配 (STDIO/HTTP) | 可替换 |\n| 协议层 | MCP SDK 封装 | 核心依赖 |\n| 转换层 | OpenAPI → MCP 转换 | 可复用 |\n| 执行层 | HTTP 请求执行 | 可测试 |\n\n### 3. 认证安全\n\nHTTP 传输强制使用 Bearer Token 认证，支持：\n- 自动生成（开发模式）\n- 环境变量配置（生产推荐）\n- 命令行显式指定（最高优先级）\n\n## 总结\n\nNotion MCP Server 采用现代化的分层架构设计，通过 OpenAPI 规范驱动实现零手动维护的工具生成机制。核心模块各司其职：解析器负责格式转换、代理负责工具注册、HTTP 客户端负责实际请求执行、认证模块负责安全控制。这种设计既保证了代码的可维护性，又为未来扩展提供了良好的基础。\n\n---\n\n\n\n## MCP 工具集详解\n\n### 相关页面\n\n相关主题：[项目介绍与版本说明](#page-1), [系统架构与模块设计](#page-2), [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json) - OpenAPI 3.1.0 规范定义所有 Notion API 端点\n- [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 工具转换器\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts) - MCP 工具注册与执行代理\n- [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 客户端实现\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts) - 服务器初始化逻辑\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts) - 服务器入口点\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json) - 项目依赖与构建配置\n
\n\n# MCP 工具集详解\n\n## 概述\n\nMCP 工具集是 Notion MCP Server 的核心功能模块，它将 Notion OpenAPI 规范自动转换为 Model Context Protocol (MCP) 工具，使 AI 助手能够直接调用 Notion API 进行操作。\n\n该系统的设计理念是**仅需修改 OpenAPI 规范文件**，即可自动生成对应的 MCP 工具，无需手动编写代码。工具的命名、参数定义、响应模式等全部从 OpenAPI 规范派生。\n\n资料来源：[CLAUDE.md]()\n\n## 架构总览\n\n### 核心数据流\n\n```mermaid\ngraph TD\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 规范\"] --> B[\"src/init-server.ts
加载与验证规范\"]\n B --> C[\"OpenAPIToMCPConverter
openapi/parser.ts\"]\n C --> D[\"MCPProxy
mcp/proxy.ts\"]\n D --> E[\"HTTP Client
client/http-client.ts\"]\n E --> F[\"Notion API
api.notion.com\"]\n \n C -.->|convertToMCPTools| G[\"MCP 工具定义\"]\n C -.->|convertToOpenAITools| H[\"OpenAI 工具格式\"]\n C -.->|convertToAnthropicTools| I[\"Anthropic 工具格式\"]\n```\n\n### 关键组件\n\n| 组件 | 文件路径 | 职责 |\n|------|---------|------|\n| OpenAPI 规范 | `scripts/notion-openapi.json` | 定义所有 API 端点的规范来源 |\n| 工具转换器 | `src/openapi-mcp-server/openapi/parser.ts` | 将 OpenAPI 转换为 MCP 工具格式 |\n| 工具代理 | `src/openapi-mcp-server/mcp/proxy.ts` | 注册工具句柄并执行调用 |\n| HTTP 客户端 | `src/openapi-mcp-server/client/http-client.ts` | 执行实际的 API 请求 |\n| 服务器初始化 | `src/init-server.ts` | 加载规范并创建 MCPProxy 实例 |\n\n资料来源：[CLAUDE.md]()\n\n## OpenAPI 到 MCP 工具转换机制\n\n### 转换流程\n\n```mermaid\nsequenceDiagram\n participant OpenAPI as OpenAPI 规范\n participant Parser as OpenAPIToMCPConverter\n participant MCP as MCPProxy\n \n OpenAPI->>Parser: 加载规范文件\n Parser->>Parser: 解析 paths 和 operations\n Parser->>Parser: convertOperationToJsonSchema()\n Parser->>Parser: extractResponseType()\n Parser->>Parser: convertToMCPTools()\n Parser-->>MCP: { tools, openApiLookup, zip }\n```\n\n### 核心转换方法\n\n`OpenAPIToMCPConverter` 类提供三种工具格式转换方法：\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:120-180]()\n\n#### 1. `convertToMCPTools()`\n\n生成原生 MCP 工具定义，返回包含三个属性的对象：\n\n```typescript\n{\n tools: Record, // 按 API 名称分组的工具\n openApiLookup: Record, // 操作查找表\n zip: Record // 配对的 OpenAPI 与 MCP 工具\n}\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:85-140]()\n\n#### 2. `convertToOpenAITools()`\n\n转换为 OpenAI ChatCompletion 工具格式：\n\n```typescript\n{\n type: 'function',\n function: {\n name: operation.operationId,\n description: 描述文本,\n parameters: JSON Schema\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:143-165]()\n\n#### 3. `convertToAnthropicTools()`\n\n转换为 Anthropic Claude 工具格式：\n\n```typescript\n{\n name: operation.operationId,\n description: 描述文本,\n input_schema: JSON Schema\n}\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:168-190]()\n\n### Schema 转换细节\n\n#### 类型映射规则\n\n| OpenAPI 类型 | JSON Schema 类型 | 特殊处理 |\n|-------------|-----------------|---------|\n| `string` | `string` | - |\n| `integer` | `integer` | - |\n| `number` | `number` | - |\n| `boolean` | `boolean` | - |\n| `array` | `array` | 包含 items 转换 |\n| `object` | `object` | 包含 properties 和 additionalProperties |\n| `binary` | `uri-reference` | 添加\"本地文件绝对路径\"描述 |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:30-90]()\n\n#### 复合类型处理\n\n对于包含 `oneOf`、`anyOf`、`allOf` 的复杂 Schema，系统采用以下策略：\n\n```typescript\n// 如果 schema 包含 oneOf/anyOf/allOf 或是数组\nif ('anyOf' in schema || 'oneOf' in schema || 'allOf' in schema) {\n return { anyOf: [schema, { type: 'string' }] }\n}\n```\n\n这确保了参数可以接受原始值或 JSON 字符串形式。\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:260-280]()\n\n#### 响应 Schema 提取\n\n```mermaid\ngraph LR\n A[\"responses 对象\"] --> B{\"查找成功响应\"}\n B -->|\"200/201/202/204\"| C[\"解析 content\"]\n B -->|\"无匹配\"| D[\"返回 null\"]\n C --> E{\"application/json?\"}\n E -->|是| F[\"转换 schema
添加 $defs\"]\n E -->|否| G[\"处理二进制格式\"]\n```\n\n系统按优先级 `200 → 201 → 202 → 204` 查找成功响应，并从 `application/json` content 中提取响应 schema。\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:290-320]()\n\n## 工具命名规范\n\n### 命名来源\n\n工具名称直接取自 OpenAPI 规范的 `operationId` 字段：\n\n```json\n{\n \"operationId\": \"retrieve-a-database\"\n}\n```\n\n转换后生成工具名：`Retrieve-A-Database`\n\n资料来源：[CLAUDE.md]()\n\n### 名称处理规则\n\n| 处理步骤 | 说明 |\n|---------|------|\n| 1. 截断 | 名称被截断至 64 字符以内 |\n| 2. 标题化 | 转换为 Title Case 格式 |\n| 3. 分组 | 按 API 名称分组到不同的方法集合 |\n\n## 工具注册与执行\n\n### MCPProxy 架构\n\n```mermaid\nclassDiagram\n class MCPProxy {\n +mcpServer: Server\n +openApiSpec: OpenAPIV3.Document\n +openApiLookup: Record\n +setupHandlers() void\n +executeTool(name, args) Promise\n }\n \n class HTTPClient {\n +executeOperation(operationId, params) Promise\n }\n \n MCPProxy --> HTTPClient : 使用\n```\n\n### 参数反序列化机制\n\nMCP 协议在传输过程中会将复杂参数序列化为字符串。`deserializeParams()` 函数负责反序列化：\n\n```typescript\nfunction deserializeParams(params: Record): Record\n```\n\n**处理逻辑：**\n\n1. 检测字符串值是否以 `{`/`[` 开头并以 `}`/`]` 结尾\n2. 尝试使用 `JSON.parse()` 解析\n3. 对嵌套对象递归反序列化\n4. 对数组中的 JSON 字符串项逐个处理\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:10-60]()\n\n### 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Proxy as MCPProxy\n participant Deserializer as deserializeParams\n participant HTTP as HTTPClient\n participant API as Notion API\n \n Client->>Proxy: 调用工具 \"retrieve-a-database\"\n Proxy->>Deserializer: 反序列化参数\n Deserializer-->>Proxy: 处理后的参数对象\n Proxy->>HTTP: operationId + 参数\n HTTP->>API: GET /v1/databases/{database_id}\n API-->>HTTP: 200 OK + 数据库数据\n HTTP-->>Proxy: API 响应\n Proxy-->>Client: MCP 响应结果\n```\n\n## HTTP 客户端实现\n\n### 请求构建流程\n\n`HTTPClient` 负责将工具调用转换为实际的 HTTP 请求：\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50]()\n\n| 处理步骤 | 操作 |\n|---------|------|\n| 1 | 从 `operation.parameters` 提取 path 和 query 参数 |\n| 2 | 识别 `application/json` 或 `multipart/form-data` 请求体 |\n| 3 | 设置相应的 `Content-Type` header |\n| 4 | 调用 OpenAPI 客户端生成的操作函数 |\n| 5 | 转换响应 headers 为标准 Headers 对象 |\n\n### 请求体处理\n\n```typescript\n// 根据是否有请求体设置 headers\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n\n// 调用格式：第一个参数为 URL 参数，第二个为 body 参数\nconst response = await operationFn(urlParameters, hasBody ? bodyParams : undefined, requestConfig)\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:50-80]()\n\n## 服务器传输模式\n\n### 支持的传输类型\n\n| 传输模式 | 说明 | 默认端口 |\n|---------|------|---------|\n| `stdio` | 标准输入/输出流 | N/A |\n| `http` | Streamable HTTP 传输 | 3000 |\n\n资料来源：[scripts/start-server.ts:20-40]()\n\n### 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--transport ` | 指定传输类型 (`stdio` 或 `http`) |\n| `--port ` | HTTP 服务器端口 (默认: 3000) |\n| `--auth-token ` | HTTP 传输认证的 Bearer token |\n| `--disable-auth` | 禁用 HTTP 传输的 Bearer token 认证 |\n| `--help`, `-h` | 显示帮助信息 |\n\n### 环境变量配置\n\n| 变量 | 说明 | 优先级 |\n|------|------|-------|\n| `NOTION_TOKEN` | Notion 集成密钥 (推荐) | 高 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API headers | 低 |\n\n`--auth-token` 参数优先于 `AUTH_TOKEN` 环境变量。\n\n资料来源：[scripts/start-server.ts:60-100]()\n\n## API 版本支持\n\n服务器使用 Notion API 版本 **`2025-09-03`** (Data Source Edition)。\n\n规范文件同时包含两类端点：\n\n| 端点类型 | 示例路径 |\n|---------|---------|\n| 传统数据库端点 | `/v1/databases/{database_id}` |\n| 数据源端点 | `/v1/data_sources/{data_source_id}` |\n\n资料来源：[CLAUDE.md]()\n\n## 使用示例\n\n### 工具调用示例\n\n当用户发出以下指令时：\n\n```\nAdd a page titled \"Notion MCP\" to page \"Development\"\n```\n\nAI 助手会自动规划并调用以下 API 操作：\n\n1. `v1/search` - 查找名为 \"Development\" 的页面\n2. `v1/pages` - 创建新页面\n\n### 工具引用方式\n\n工具支持以下引用方式：\n\n| 方式 | 示例 |\n|------|------|\n| 页面标题 | `Comment \"Hello MCP\" on page \"Getting started\"` |\n| 页面 ID | `Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2` |\n\n## 测试框架\n\n### 测试配置\n\n测试文件位于源文件同级的 `__tests__` 目录中，使用 Vitest 测试框架：\n\n```bash\nnpm test # 运行所有测试\nnpm run test:watch # 监视模式\nnpm run test:coverage # 生成覆盖率报告\n```\n\n### 依赖包\n\n| 包名 | 用途 |\n|------|------|\n| `@modelcontextprotocol/sdk` | MCP 协议实现 |\n| `axios` | HTTP 请求处理 |\n| `openapi-client-axios` | OpenAPI 客户端生成 |\n| `zod` | Schema 验证 |\n\n资料来源：[package.json]()\n\n## 扩展机制\n\n### 添加新端点\n\n要添加新的 API 端点，只需修改 `scripts/notion-openapi.json` 文件，无需修改其他代码：\n\n1. 在 `paths` 对象中添加新的端点定义\n2. 设置唯一的 `operationId`\n3. 定义 parameters 和 requestBody\n4. 定义 response schema\n\n系统会自动：\n- 生成新的 MCP 工具定义\n- 更新工具注册表\n- 处理参数序列化和反序列化\n\n资料来源：[CLAUDE.md]()\n\n### 自定义 Header 配置\n\n对于需要自定义 headers 的高级用例，可通过 `OPENAPI_MCP_HEADERS` 环境变量传入：\n\n```json\n{\n \"Authorization\": \"Bearer ntn_****\",\n \"Notion-Version\": \"2025-09-03\"\n}\n\n---\n\n\n\n## 安装与客户端配置\n\n### 相关页面\n\n相关主题：[传输层配置详解](#page-7), [本地开发与测试指南](#page-8)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [docker-compose.yml](https://github.com/makenotion/notion-mcp-server/blob/main/docker-compose.yml)\n- [Dockerfile](https://github.com/makenotion/notion-mcp-server/blob/main/Dockerfile)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [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)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n
\n\n# 安装与客户端配置\n\n本文档详细说明 Notion MCP Server 的安装方式、Docker 部署方案以及各主流 AI 客户端的配置方法。\n\n## 概述\n\nNotion MCP Server 是官方提供的 Model Context Protocol (MCP) 服务器，用于将 Notion API 以 MCP 工具的形式暴露给 AI 客户端。项目采用 TypeScript 开发，支持两种传输模式（STDIO 和 Streamable HTTP）和多种认证方式。\n\n核心依赖包括：\n- `@modelcontextprotocol/sdk` (^1.25.1) - MCP 协议实现\n- `axios` (^1.8.4) - HTTP 请求处理\n- `express` (^4.21.2) - HTTP 传输层支持\n- `zod` (3.24.1) - 参数验证\n\n资料来源：[package.json:1-50]()\n\n## 环境准备\n\n### 前置条件\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 18+ | 支持原生 Headers 类 |\n| npm | 9+ | 包管理 |\n| Docker | 20+ | Docker 部署方式 |\n\n> **注意**：Headers 类在 Node.js 18+ 才原生支持，较低版本使用 polyfill 实现。\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-10]()\n\n### Notion 集成配置\n\n1. 访问 [Notion 开发者平台](https://www.notion.so/profile/integrations) 创建内部集成或选择已有集成\n2. 复制集成的 Secret Token（格式：`ntn_****`）\n3. 访问目标页面，点击右上角「...」→「连接」→「连接到集成」\n\n## 安装方式\n\n### NPM 安装（推荐）\n\nNPM 安装是使用 Notion MCP Server 最便捷的方式，适用于 Cursor、Claude Desktop、Zed 等主流 AI 客户端。\n\n```bash\n# 使用 NOTION_TOKEN（推荐）\nnpx -y @notionhq/notion-mcp-server\n\n# 或使用 OPENAPI_MCP_HEADERS（高级场景）\nnpx -y @notionhq/notion-mcp-server --transport http\n```\n\n资料来源：[README.md:80-95]()\n\n### Docker 安装\n\n#### 选项一：使用官方 Docker Hub 镜像\n\n官方镜像 `mcp/notion` 托管在 Docker Hub，无需本地构建即可快速部署。\n\n```bash\n# 拉取官方镜像\ndocker pull mcp/notion\n\n# 使用 NOTION_TOKEN 运行\ndocker run --rm -i -e NOTION_TOKEN=\"ntn_****\" mcp/notion\n```\n\n资料来源：[README.md:140-155]()\n\n#### 选项二：本地构建 Docker 镜像\n\n如果需要自定义配置或使用最新代码，可选择本地构建：\n\n```bash\n# 构建镜像\ndocker compose build\n\n# 或使用 docker build\ndocker build -t notion-mcp-server .\n```\n\n构建配置如下：\n\n```dockerfile\nFROM node:20-slim\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --production\nCOPY . .\nCMD [\"node\", \"bin/cli.mjs\"]\n```\n\n资料来源：[Dockerfile:1-10]()\n\n```yaml\nservices:\n notion-mcp-server:\n build: .\n container_name: notion-mcp-server\n environment:\n - NOTION_TOKEN=${NOTION_TOKEN}\n stdin_open: true\n tty: true\n```\n\n资料来源：[docker-compose.yml:1-15]()\n\n## 客户端配置\n\n### 配置架构图\n\n```mermaid\ngraph TD\n A[AI 客户端] --> B[MCP 配置文件]\n B --> C{传输模式}\n C -->|STDIO| D[notion-mcp-server 进程]\n C -->|HTTP| E[notion-mcp-server HTTP 服务]\n D --> F[Notion API]\n E --> F\n```\n\n### Cursor / Claude Desktop\n\n#### 配置路径\n\n- **Cursor**: `~/.cursor/mcp.json`\n- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n#### 使用 NOTION_TOKEN（推荐）\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n#### 使用 OPENAPI_MCP_HEADERS（高级场景）\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:95-125]()\n\n### Zed 编辑器\n\nZed 通过 `settings.json` 的 `context_servers` 配置项支持 MCP 服务器。\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n资料来源：[README.md:75-88]()\n\n### GitHub Copilot CLI\n\n#### 交互式配置\n\n```bash\n/mcp add\n```\n\n#### 手动配置\n\n编辑 `~/.copilot/mcp-config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:88-103]()\n\n### Docker 环境下的客户端配置\n\n#### 使用 Docker Hub 镜像\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n#### 本地构建镜像\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md:155-185]()\n\n## 传输模式与认证\n\n### STDIO 传输模式（默认）\n\nSTDIO 是默认传输模式，通过标准输入输出与客户端通信：\n\n```bash\nnpx -y @notionhq/notion-mcp-server\n```\n\n### HTTP 传输模式\n\nHTTP 传输模式启动一个 HTTP 服务器，适合远程部署和需要认证的场景：\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --port 3000\n```\n\n服务器默认监听 `http://0.0.0.0:3000/mcp`。\n\n资料来源：[scripts/start-server.ts:20-35]()\n\n### 认证机制\n\nHTTP 传输模式支持 bearer token 认证：\n\n| 认证方式 | 配置方法 | 优先级 |\n|----------|----------|--------|\n| 命令行参数 | `--auth-token \"token\"` | 最高 |\n| 环境变量 | `AUTH_TOKEN=\"token\"` | 中 |\n| 自动生成 | 不指定则自动生成 | 仅开发环境 |\n\n#### 自动生成 token（仅开发环境）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http\n```\n\n输出示例：\n\n```\nGenerated auth token: a1b2c3d4e5f6789...\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789...\n```\n\n#### 自定义 token（生产环境推荐）\n\n```bash\n# 通过命令行\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# 或通过环境变量\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n#### 禁用认证（不推荐）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --disable-auth\n```\n\n#### HTTP 请求示例\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n## 命令行参数\n\n```bash\nnotion-mcp-server [options]\n\nOptions:\n --transport 传输类型: 'stdio' 或 'http'（默认: stdio）\n --port HTTP 服务器端口（默认: 3000）\n --auth-token Bearer token 认证\n --disable-auth 禁用认证\n --help, -h 显示帮助信息\n\nEnvironment Variables:\n NOTION_TOKEN Notion 集成 token（推荐）\n OPENAPI_MCP_HEADERS JSON 格式的 Notion API 请求头\n AUTH_TOKEN HTTP 传输认证 token\n```\n\n资料来源：[scripts/start-server.ts:10-30]()\n\n## 开发环境配置\n\n### 本地开发设置\n\n1. **链接本地包**：\n\n```bash\nnpm link\n```\n\n2. **配置 MCP 客户端**：\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. **清理**：\n\n```bash\nnpm unlink\n```\n\n### 构建与测试\n\n```bash\n# 构建项目\nnpm run build\n\n# 运行测试\nnpm test\n\n# 监听模式开发\nnpm run dev\n```\n\n### 本地执行\n\n```bash\nnpx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server\n```\n\n资料来源：[README.md:200-230]()\n\n## 环境变量详解\n\n| 变量名 | 用途 | 示例值 |\n|--------|------|--------|\n| `NOTION_TOKEN` | Notion 集成 Secret Token | `ntn_1a2b3c4d5e...` |\n| `OPENAPI_MCP_HEADERS` | 自定义 API 请求头（JSON） | `{\"Authorization\": \"Bearer ...\", \"Notion-Version\": \"2025-09-03\"}` |\n| `AUTH_TOKEN` | HTTP 传输认证 token | `my-secret-token` |\n\n> **注意**：`OPENAPI_MCP_HEADERS` 中的 JSON 必须正确转义。在 shell 中使用时，建议使用单引号包裹整个 JSON 字符串。\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-30]()\n\n## 参数反序列化\n\nMCP 工具调用时，参数以字符串形式传递。服务器会自动反序列化 JSON 格式的参数字符串：\n\n```mermaid\ngraph LR\n A[MCP 客户端
参数值: '{\"filter\": {...}}'] --> B[字符串传递]\n B --> C[反序列化检查]\n C -->|JSON 对象/数组| D[解析为对象]\n C -->|其他| E[保持原值]\n```\n\n支持的类型：\n- JSON 对象字符串：`'{\"key\": \"value\"}'`\n- JSON 数组字符串：`'[\"item1\", \"item2\"]'`\n- 嵌套对象的递归反序列化\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-40]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 认证失败 401 | 检查 `NOTION_TOKEN` 是否正确，或确认 Bearer token 与 `--auth-token` 匹配 |\n| 页面访问被拒绝 | 确认已在目标页面「连接」到对应集成 |\n| Docker 容器启动失败 | 检查 `NOTION_TOKEN` 环境变量是否正确传递 |\n| Node 版本过低 | 升级到 Node.js 18+ |\n\n### 验证配置\n\n1. 启动服务器并检查输出日志\n2. 确认客户端成功连接（查看客户端日志）\n3. 尝试执行简单命令如搜索页面\n\n## 发布包\n\n```bash\nnpm login\nnpm publish --access public\n```\n\n资料来源：[README.md:230-235]()\n\n## 相关文档\n\n- [官方 README](https://github.com/makenotion/notion-mcp-server#readme)\n- [Notion API 文档](https://developers.notion.com/reference/intro)\n- [MCP 协议规范](https://spec.modelcontextprotocol.io/)\n\n---\n\n\n\n## HTTP 客户端与网络请求处理\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#page-2), [认证机制与安全配置](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# HTTP 客户端与网络请求处理\n\n## 概述\n\nNotion MCP Server 的 HTTP 客户端模块负责执行所有与 Notion API 的网络通信。该模块封装了底层的 HTTP 请求逻辑，将 OpenAPI 规范定义的 API 操作转换为可执行的 HTTP 调用。\n\n核心职责包括：\n\n- 构建符合 Notion API 规范的 HTTP 请求\n- 处理请求参数（路径参数、查询参数、请求体）\n- 管理请求头和认证信息\n- 处理表单数据和二进制内容\n- 转换响应格式\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-198]()\n\n## 架构设计\n\n### 模块结构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCPProxy │\n│ (工具注册与请求路由) │\n└─────────────────────┬───────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ HttpClient │\n│ (HTTP 请求执行层) │\n│ ┌─────────────────────────────────────────────────────┐ │\n│ │ 参数处理 │ 请求构建 │ 响应转换 │ 错误处理 │ │\n│ └─────────────────────────────────────────────────────┘ │\n└─────────────────────┬───────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Notion API │\n│ (https://api.notion.com) │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### HTTP 客户端类\n\n`HttpClient` 类是网络请求的核心执行器，在初始化时接收基础配置：\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `baseUrl` | `string` | API 基础地址（默认 Notion API） |\n| `headers` | `Record` | 全局请求头 |\n| `openApiSpec` | `OpenAPIV3.Document` | OpenAPI 规范文档 |\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:18-23]()\n\n## HttpClient 实现详解\n\n### 类初始化\n\n```typescript\nexport class HttpClient {\n constructor(\n private config: HttpClientConfig,\n private openApiSpec: OpenAPIV3.Document\n ) {\n this.api = this.createApiClient()\n }\n}\n```\n\n构造函数完成以下初始化：\n\n1. 存储配置参数\n2. 创建 axios API 客户端实例\n3. 准备处理 OpenAPI 规范中定义的请求\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:15-26]()\n\n### 请求参数处理\n\n`HttpClient` 根据 OpenAPI 规范中的参数定义，智能分配参数到不同的请求位置：\n\n```mermaid\ngraph TD\n A[接收参数对象] --> B{存在 requestBody?}\n B -->|是| C{参数类型为 FormData?}\n B -->|否| D[将参数转为 URL 查询参数]\n C -->|是| E[设置 FormData Headers]\n C -->|否| F[设置 JSON Content-Type]\n D --> G[执行 HTTP 请求]\n E --> G\n F --> G\n```\n\n参数分配逻辑：\n\n| 参数位置 | 处理方式 | 来源 |\n|----------|----------|------|\n| `path` | 直接替换 URL 路径占位符 | `operation.parameters` |\n| `query` | 添加到 URL 查询字符串 | `operation.parameters` |\n| `body` | 作为请求体发送 | `operation.requestBody` |\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:55-77]()\n\n### 请求体处理\n\n当没有定义 `requestBody` 且没有 FormData 时，所有剩余参数自动转为 URL 参数：\n\n```typescript\n// Add all parameters as url parameters if there is no requestBody defined\nif (!operation.requestBody && !formData) {\n for (const key in bodyParams) {\n if (bodyParams[key] !== undefined) {\n urlParameters[key] = bodyParams[key]\n delete bodyParams[key]\n }\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:66-74]()\n\n### Content-Type 处理\n\n`HttpClient` 根据请求内容类型动态设置请求头：\n\n| 场景 | Content-Type |\n|------|--------------|\n| 有请求体 | `application/json` |\n| FormData | 使用 FormData 的自动检测 |\n| 无请求体 | `null`（移除 Content-Type） |\n\n```typescript\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:79-88]()\n\n## 请求头管理\n\n### Headers Polyfill\n\n由于 Node.js 18 之前版本不支持原生的 `Headers` 类，项目实现了兼容性 polyfill：\n\n```typescript\nclass PolyfillHeaders {\n private headers: Map = new Map();\n\n public append(name: string, value: string): void {\n const key = name.toLowerCase();\n if (!this.headers.has(key)) {\n this.headers.set(key, []);\n }\n this.headers.get(key)!.push(value);\n }\n\n public get(name: string): string | null {\n const key = name.toLowerCase();\n if (!this.headers.has(key)) {\n return null;\n }\n return this.headers.get(key)!.join(', ');\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-45]()\n\n### Polyfill 特性\n\n| 特性 | 实现说明 |\n|------|----------|\n| 大小写不敏感 | 所有 key 自动转为小写存储 |\n| 多值支持 | `append()` 方法支持添加多个同名值 |\n| 兼容性 | 优先使用原生 `Headers`，回退到 polyfill |\n\n### 响应头转换\n\naxios 响应的 headers 对象会被转换为标准 `Headers` 实例：\n\n```typescript\nconst responseHeaders = new Headers()\nObject.entries(response.headers).forEach(([key, value]) => {\n if (typeof value === 'string') {\n responseHeaders.append(key, value)\n }\n})\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:103-108]()\n\n## 请求执行流程\n\n### 完整请求流程\n\n```mermaid\nsequenceDiagram\n participant 调用方\n participant MCPProxy\n participant HttpClient\n participant NotionAPI\n\n 调用方->>MCPProxy: 调用工具\n MCPProxy->>HttpClient: executeOperation(operationId, params)\n HttpClient->>HttpClient: 解析 OpenAPI 操作定义\n HttpClient->>HttpClient: 分离 path/query/body 参数\n HttpClient->>HttpClient: 构建请求配置\n HttpClient->>NotionAPI: HTTP 请求\n NotionAPI-->>HttpClient: 响应数据\n HttpClient->>HttpClient: 转换响应头\n HttpClient-->>MCPProxy: 格式化响应\n MCPProxy-->>调用方: 返回结果\n```\n\n### 操作查找\n\n每个 API 操作通过 `operationId` 查找对应的 HTTP 方法：\n\n```typescript\nconst operationFn = (api as any)[operationId]\nif (!operationFn) {\n throw new Error(`Operation ${operationId} not found`)\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:75-78]()\n\n## 配置与初始化\n\n### MCPProxy 中的 HTTP 客户端\n\n`MCPProxy` 在初始化时创建 `HttpClient` 实例：\n\n```typescript\nthis.httpClient = new HttpClient(\n {\n baseUrl,\n headers: this.parseHeadersFromEnv(),\n },\n openApiSpec,\n)\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:29-35]()\n\n### 从环境变量解析请求头\n\n项目支持通过 `OPENAPI_MCP_HEADERS` 环境变量配置请求头：\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headersEnv = process.env.OPENAPI_MCP_HEADERS\n if (headersEnv) {\n try {\n return JSON.parse(headersEnv)\n } catch {\n return {}\n }\n }\n return {}\n}\n```\n\n常用配置示例：\n\n```json\n{\n \"Authorization\": \"Bearer ntn_xxxx\",\n \"Notion-Version\": \"2025-09-03\"\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:15-26]()\n\n### 服务端初始化\n\n`init-server.ts` 负责加载 OpenAPI 规范并创建代理：\n\n```typescript\nexport async function initProxy(specPath: string, baseUrl: string | undefined) {\n const openApiSpec = await loadOpenApiSpec(specPath, baseUrl)\n const proxy = new MCPProxy('Notion API', openApiSpec)\n return proxy\n}\n```\n\n资料来源：[src/init-server.ts:44-50]()\n\n## 错误处理\n\n### 操作未找到\n\n当 `operationId` 不存在于 API 客户端中时：\n\n```typescript\nconst operationFn = (api as any)[operationId]\nif (!operationFn) {\n throw new Error(`Operation ${operationId} not found`)\n}\n```\n\n### 文件读取错误\n\n规范文件加载失败时的处理：\n\n```typescript\ntry {\n rawSpec = fs.readFileSync(path.resolve(process.cwd(), specPath), 'utf-8')\n} catch (error) {\n console.error('Failed to read OpenAPI specification file:', (error as Error).message)\n process.exit(1)\n}\n```\n\n资料来源：[src/init-server.ts:22-27]()\n\n## 传输层支持\n\n### STDIO 传输（默认）\n\n默认情况下，MCP 服务器使用 STDIO 传输，适用于本地集成：\n\n```bash\nnotion-mcp-server\n```\n\n### HTTP 传输\n\n支持 HTTP 传输模式，用于远程访问：\n\n```bash\nnotion-mcp-server --transport http --port 3000\n```\n\nHTTP 传输需要认证令牌：\n\n```bash\n# 自动生成令牌\nnotion-mcp-server --transport http\n\n# 自定义令牌\nnotion-mcp-server --transport http --auth-token \"your-token\"\n```\n\n资料来源：[scripts/start-server.ts:1-40]()\n\n## 最佳实践\n\n### 请求头配置\n\n推荐使用 `NOTION_TOKEN` 环境变量进行配置：\n\n```bash\nNOTION_TOKEN=ntn_xxxx notion-mcp-server\n```\n\n高级场景可使用 `OPENAPI_MCP_HEADERS`：\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_xxxx\", \"Notion-Version\": \"2025-09-03\"}' notion-mcp-server\n```\n\n### 本地开发测试\n\n使用 `npm link` 创建全局符号链接进行本地测试：\n\n```bash\nnpm link\n```\n\n配置客户端使用本地包：\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n## 总结\n\nHTTP 客户端模块是 Notion MCP Server 与 Notion API 通信的桥梁。通过封装底层的 HTTP 请求逻辑，提供了：\n\n- **参数自动路由**：智能区分 path、query、body 参数\n- **格式自动适配**：根据内容类型设置正确的 Content-Type\n- **跨版本兼容**：Headers polyfill 确保 Node.js 18 以下版本兼容\n- **配置灵活**：支持环境变量和命令行参数配置\n\n该设计遵循了单一职责原则，使网络请求处理与业务逻辑解耦，便于维护和测试。\n\n---\n\n\n\n## 认证机制与安全配置\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#page-2), [传输层配置详解](#page-7)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# 认证机制与安全配置\n\nNotion MCP Server 提供多层认证机制，支持通过环境变量、命令行参数和 HTTP 传输层认证来保护对 Notion API 的访问。本页面详细说明服务器启动、API 认证和 HTTP 传输安全的完整配置流程。\n\n## 认证体系概述\n\nNotion MCP Server 采用双层认证架构：\n\n| 层级 | 认证对象 | 认证方式 | 配置方式 |\n|------|----------|----------|----------|\n| **API 认证层** | Notion API 请求 | Bearer Token / Header | `NOTION_TOKEN` 或 `OPENAPI_MCP_HEADERS` |\n| **传输认证层** | HTTP 传输通道 | Bearer Token | `--auth-token` 或 `AUTH_TOKEN` |\n\n资料来源：[scripts/start-server.ts:1-100]()\n\n```mermaid\ngraph TD\n A[客户端请求] --> B{传输类型}\n B -->|stdio| C[直接通信]\n B -->|http| D[传输层认证]\n \n D --> E{验证 Bearer Token}\n E -->|通过| F[解析请求]\n E -->|失败| G[401 未授权]\n \n F --> H{API 认证}\n H -->|NOTION_TOKEN| I[使用环境变量 Token]\n H -->|OPENAPI_MCP_HEADERS| J[使用自定义 Header]\n \n I --> K[调用 Notion API]\n J --> K\n```\n\n## 环境变量配置\n\n### NOTION_TOKEN（推荐方式）\n\nNotion 集成令牌是访问 Notion API 的主要认证凭证。\n\n```bash\nNOTION_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxx npx -y @notionhq/notion-mcp-server\n```\n\n**配置位置**：[scripts/start-server.ts:26-27]() 在启动时读取环境变量\n\n```typescript\nconst notionToken = process.env.NOTION_TOKEN\n```\n\n> **注意**：集成令牌需在 Notion 开发者门户中创建，并为目标页面授予访问权限。\n\n### OPENAPI_MCP_HEADERS（高级配置）\n\n当需要自定义请求头时使用，如指定 Notion API 版本：\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_xxxx\", \"Notion-Version\": \"2025-09-03\"}' \\\nnpx -y @notionhq/notion-mcp-server\n```\n\n**Header 解析逻辑**：[src/init-server.ts:39-52]() 通过 `parseHeadersFromEnv()` 方法处理\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headersEnv = process.env.OPENAPI_MCP_HEADERS\n if (!headersEnv) return {}\n \n try {\n return JSON.parse(headersEnv)\n } catch {\n throw new Error('OPENAPI_MCP_HEADERS must be valid JSON')\n }\n}\n```\n\n## HTTP 传输层认证\n\n当使用 `--transport http` 模式时，服务器启用额外的 Bearer Token 认证层。\n\n### 命令行参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--transport ` | 传输类型：`stdio` 或 `http` | `stdio` |\n| `--port ` | HTTP 服务器端口 | `3000` |\n| `--auth-token ` | 传输层认证令牌 | 自动生成 |\n| `--disable-auth` | 禁用传输层认证 | `false`（默认启用） |\n| `--help`, `-h` | 显示帮助信息 | - |\n\n资料来源：[scripts/start-server.ts:1-35]()\n\n### 认证模式\n\n#### 自动生成令牌（仅限开发环境）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http\n```\n\n服务器启动时会输出自动生成的令牌：\n\n```\nGenerated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789...\n```\n\n#### 自定义令牌（推荐用于生产环境）\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n#### 环境变量配置\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n**优先级**：`--auth-token` > `AUTH_TOKEN` 环境变量\n\n资料来源：[scripts/start-server.ts:17-24]()\n\n### 令牌验证流程\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant S as MCP Server\n \n C->>S: HTTP POST /mcp (无 Authorization)\n S-->>C: 401 Unauthorized\n \n C->>S: HTTP POST /mcp (Bearer invalid-token)\n S-->>C: 401 Unauthorized\n \n C->>S: HTTP POST /mcp (Bearer valid-token)\n S->>S: 验证令牌\n S->>S: 解析 JSON-RPC 请求\n S->>C: JSON-RPC 响应\n```\n\n## 认证头传递机制\n\nHTTP 客户端负责将认证信息传递给 Notion API：\n\n```mermaid\ngraph LR\n A[环境变量] -->|OPENAPI_MCP_HEADERS| B[HttpClient]\n C[NOTION_TOKEN] -->|Bearer Token| B\n B --> D[Authorization: Bearer ntn_xxx]\n B --> E[Notion-Version: 2025-09-03]\n D --> F[Notion API]\n E --> F\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50]()\n\n### 客户端初始化\n\n```typescript\nthis.httpClient = new HttpClient(\n {\n baseUrl,\n headers: this.parseHeadersFromEnv(),\n },\n openApiSpec,\n)\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:35-42]()\n\n## 安全配置最佳实践\n\n### 生产环境配置\n\n| 配置项 | 建议值 | 理由 |\n|--------|--------|------|\n| `NOTION_TOKEN` | 必需设置 | API 访问凭证 |\n| `AUTH_TOKEN` | 使用强随机字符串 | 保护 HTTP 传输通道 |\n| `--disable-auth` | **勿使用** | 关闭认证存在安全风险 |\n| `--port` | 非标准端口 | 减少暴露面 |\n\n### Docker 环境配置\n\n#### 方式一：使用 NOTION_TOKEN\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"mcp/notion\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_xxxx\"\n }\n }\n }\n}\n```\n\n#### 方式二：使用 OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"OPENAPI_MCP_HEADERS\", \"mcp/notion\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_xxxx\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n### Cursor/Claude Desktop 配置\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_xxxx\"\n }\n }\n }\n}\n```\n\n## 错误处理\n\n| 错误场景 | HTTP 状态码 | 响应 |\n|----------|-------------|------|\n| 未提供传输层令牌 | 401 | `Unauthorized` |\n| 令牌验证失败 | 401 | `Unauthorized` |\n| JSON 解析失败 | 400 | `Bad Request` |\n| Notion API 错误 | 相应状态码 | API 响应内容 |\n\n```typescript\n// 错误处理示例\n} catch (error) {\n if (error instanceof ValidationError) {\n console.error('Invalid OpenAPI 3.1 specification:')\n error.errors.forEach(err => console.error(err))\n } else {\n console.error('Error:', error)\n }\n process.exit(1)\n}\n```\n\n资料来源：[scripts/start-server.ts:85-93]()\n\n## 命令行帮助信息\n\n```bash\nUsage: notion-mcp-server [options]\n\nOptions:\n --transport Transport type: 'stdio' or 'http' (default: stdio)\n --port Port for HTTP server when using Streamable HTTP transport (default: 3000)\n --auth-token Bearer token for HTTP transport authentication (auto-generated if not provided)\n --disable-auth Disable bearer token authentication for HTTP transport\n --help, -h Show this help message\n\nEnvironment Variables:\n NOTION_TOKEN Notion integration token (recommended)\n OPENAPI_MCP_HEADERS JSON string with Notion API headers (alternative)\n AUTH_TOKEN Bearer token for HTTP transport authentication (alternative to --auth-token)\n```\n\n## 快速参考\n\n| 场景 | 推荐配置 |\n|------|----------|\n| 本地开发 (stdio) | `NOTION_TOKEN=ntn_xxx notion-mcp-server` |\n| 本地开发 (HTTP) | `NOTION_TOKEN=ntn_xxx notion-mcp-server --transport http` |\n| 生产环境 | 使用 `--auth-token` 指定强密码，启用 HTTPS 反向代理 |\n| Docker 运行 | 使用环境变量挂载或配置文件 |\n\n---\n\n\n\n## 传输层配置详解\n\n### 相关页面\n\n相关主题：[安装与客户端配置](#page-4), [认证机制与安全配置](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# 传输层配置详解\n\n## 概述\n\nNotion MCP Server 支持两种传输层协议，用于与 MCP 客户端进行通信。传输层是 MCP 服务器与客户端之间数据传输的核心抽象，负责处理请求的序列化和反序列化、会话管理以及认证机制。资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## 传输类型\n\n| 传输类型 | 说明 | 默认端口 | 适用场景 |\n|---------|------|---------|---------|\n| `stdio` | 标准输入输出流 | - | 本地开发、直接进程调用 |\n| `http` | Streamable HTTP | 3000 | 远程访问、微服务架构 |\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n## stdio 传输模式\n\nstdio（Standard Input/Output）是 MCP 协议的默认传输方式，适用于本地进程通信场景。在这种模式下，服务器通过标准输入读取来自客户端的 JSON-RPC 请求，并通过标准输出返回响应。\n\n### 工作原理\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|stdin| B[notion-mcp-server]\n B -->|stdout| A\n```\n\nstdio 传输模式的优势在于：\n- 配置简单，无需额外的网络配置\n- 适合自动化测试和本地开发\n- 进程生命周期由客户端管理\n\n### 使用方式\n\n```bash\n# 默认使用 stdio 传输\nnpx -y @notionhq/notion-mcp-server\n\n# 显式指定 stdio 传输\nnpx @notionhq/notion-mcp-server --transport stdio\n```\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n## HTTP 传输模式\n\nHTTP 传输模式基于 Model Context Protocol 的 Streamable HTTP 规范实现，提供了更灵活的远程访问能力。资料来源：[scripts/start-server.ts:1-80]()\n\n### 架构设计\n\n```mermaid\ngraph TD\n A[MCP 客户端] -->|HTTP 请求| B[Express 服务器]\n B -->|路由| C[Streamable HTTP Handler]\n C -->|认证检查| D{认证状态}\n D -->|有效| E[MCP 代理]\n D -->|无效| F[401 Unauthorized]\n E -->|处理请求| G[Notion API]\n G -->|响应| E\n E -->|JSON-RPC 响应| B\n```\n\n### 启动参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--transport` | string | `stdio` | 传输类型 |\n| `--port` | number | `3000` | HTTP 服务端口 |\n| `--auth-token` | string | 自动生成 | 认证令牌 |\n| `--disable-auth` | boolean | `false` | 禁用认证 |\n\n资料来源：[scripts/start-server.ts:15-40]()\n\n### 命令行示例\n\n```bash\n# 基础 HTTP 模式（自动生成认证令牌）\nnpx @notionhq/notion-mcp-server --transport http\n\n# 指定端口\nnpx @notionhq/notion-mcp-server --transport http --port 8080\n\n# 自定义认证令牌（推荐用于生产环境）\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# 禁用认证（仅用于开发环境）\nnpx @notionhq/notion-mcp-server --transport http --disable-auth\n```\n\n资料来源：[scripts/start-server.ts:10-45]()\n\n## 认证机制\n\nHTTP 传输模式强制使用 Bearer Token 认证，以防止未授权访问。\n\n### 认证方式优先级\n\n1. **命令行参数** `--auth-token`（最高优先级）\n2. **环境变量** `AUTH_TOKEN`\n3. **自动生成**（仅开发模式）\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant C as MCP 客户端\n participant S as MCP 服务器\n participant N as Notion API\n \n C->>S: HTTP 请求 + Authorization Header\n Note over S: 验证 Bearer Token\n alt 认证失败\n S-->>C: 401 Unauthorized\n else 认证成功\n S->>N: API 请求\n N-->>S: API 响应\n S-->>C: JSON-RPC 响应\n end\n```\n\n### 请求示例\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n## 环境变量配置\n\nNotion MCP Server 支持多种环境变量配置方式，用于设置 API 凭证和自定义请求头。\n\n### 配置参数\n\n| 环境变量 | 说明 | 推荐用途 |\n|---------|------|---------|\n| `NOTION_TOKEN` | Notion 集成令牌 | 推荐用于标准配置 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的自定义请求头 | 高级配置场景 |\n| `AUTH_TOKEN` | HTTP 传输认证令牌 | 生产环境部署 |\n\n### 配置示例\n\n```bash\n# 方式一：使用 NOTION_TOKEN（推荐）\nexport NOTION_TOKEN=\"ntn_****\"\nnpx @notionhq/notion-mcp-server --transport http\n\n# 方式二：使用 OPENAPI_MCP_HEADERS\nexport OPENAPI_MCP_HEADERS='{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}'\nnpx @notionhq/notion-mcp-server --transport http\n\n# 方式三：使用 AUTH_TOKEN\nexport AUTH_TOKEN=\"secure-auth-token\"\nnpx @notionhq/notion-mcp-server --transport http\n```\n\n## 客户端配置\n\n### Cursor / Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Zed Editor\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n## Docker 部署\n\n### 方式一：使用官方镜像\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"mcp/notion\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### 方式二：本地构建\n\n```bash\ndocker compose build\n```\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n## 核心组件架构\n\n```mermaid\ngraph TD\n subgraph 传输层\n A[stdio 传输]\n B[HTTP 传输]\n end\n \n subgraph 核心服务\n C[MCPProxy]\n D[HttpClient]\n E[OpenAPIToMCPConverter]\n end\n \n subgraph 工具系统\n F[工具注册]\n G[参数反序列化]\n H[API 执行]\n end\n \n A --> C\n B --> C\n C --> D\n C --> E\n E --> F\n F --> G\n G --> H\n```\n\n### MCPProxy 类\n\n`MCPProxy` 是传输层与工具系统之间的桥梁，负责：\n\n- 初始化 MCP 服务器实例\n- 注册 OpenAPI 转换后的工具\n- 处理请求参数的反序列化\n- 执行 API 调用并返回响应\n\n```typescript\nexport class MCPProxy {\n private server: Server\n private httpClient: HttpClient\n private tools: Record\n private openApiLookup: Record\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:50-100]()\n\n### 参数反序列化\n\nMCP 协议在传输过程中会将嵌套对象序列化为字符串，服务器端需要反序列化这些参数：\n\n```typescript\nfunction deserializeParams(params: Record): Record {\n // 处理 JSON 字符串形式的嵌套对象\n // 处理数组中的 JSON 字符串元素\n // 递归反序列化\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:10-50]()\n\n## 配置决策矩阵\n\n| 使用场景 | 传输模式 | 认证方式 | 推荐配置 |\n|---------|---------|---------|---------|\n| 本地开发调试 | stdio | 无 | `npm run dev` |\n| 生产环境（远程） | http | `--auth-token` | 环境变量 + 令牌 |\n| Docker 部署 | http | 环境变量 | `NOTION_TOKEN` |\n| 团队共享 | http | 统一令牌 | 配置文件管理 |\n\n## 故障排除\n\n### 常见问题\n\n1. **连接被拒绝**\n - 检查端口是否被占用：`lsof -i :3000`\n - 确认防火墙规则允许访问\n\n2. **认证失败**\n - 验证 Bearer Token 与服务器配置一致\n - 检查 `Authorization` 头部格式是否正确\n\n3. **工具调用失败**\n - 确认 `NOTION_TOKEN` 有效且已配置到目标页面\n - 检查 OpenAPI 请求头配置\n\n### 调试模式\n\n使用 `tsx watch` 启动开发服务器以获取详细日志：\n\n```bash\nnpm run dev\n```\n\n资料来源：[package.json:10-20]()\n\n## 总结\n\nNotion MCP Server 的传输层设计遵循 Model Context Protocol 规范，提供了 stdio 和 HTTP 两种传输模式以适应不同的部署场景。stdio 模式适合本地开发和测试，而 HTTP 模式则支持远程访问和微服务架构。通过命令行参数和环境变量的灵活组合，用户可以根据实际需求选择合适的认证和配置方案。\n\n---\n\n\n\n## 本地开发与测试指南\n\n### 相关页面\n\n相关主题：[安装与客户端配置](#page-4), [从 v1.x 到 v2.0.0 迁移指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n
\n\n# 本地开发与测试指南\n\n本指南详细介绍如何搭建本地开发环境、运行测试、调试代码以及发布 `notion-mcp-server` 包。该服务器是基于 MCP (Model Context Protocol) 的 Notion API 实现，通过 OpenAPI 规范自动生成 MCP 工具。\n\n## 环境准备\n\n### 系统要求\n\n| 要求项 | 最低版本 | 推荐版本 |\n|--------|----------|----------|\n| Node.js | Node.js 20+ | Node.js 22 LTS |\n| npm | npm 10+ | npm 10+ |\n| Docker | Docker 24+ | Docker 最新版 |\n\n### 安装依赖\n\n项目使用 ES Modules (ESM) 模块系统，TypeScript 版本为 5.8.2。安装依赖前请确保 Node.js 版本符合要求：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/makenotion/notion-mcp-server.git\ncd notion-mcp-server\n\n# 安装依赖\nnpm install\n```\n\n资料来源：[package.json:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### 环境变量配置\n\n开发环境需要配置 Notion API 认证信息。可通过以下方式配置：\n\n| 环境变量 | 说明 | 必需 |\n|----------|------|------|\n| `NOTION_TOKEN` | Notion 集成密钥（推荐） | 是 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 请求头 | 否 |\n| `AUTH_TOKEN` | HTTP 传输层认证令牌 | 仅 HTTP 模式 |\n| `NODE_ENV` | 运行环境 (`test` 用于测试) | 测试时必需 |\n\n资料来源：[README.md:100-120](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## 项目架构\n\n### 核心模块结构\n\n```\nnotion-mcp-server/\n├── scripts/\n│ ├── notion-openapi.json # OpenAPI 3.1.0 规范（所有工具的来源）\n│ └── start-server.ts # 服务器启动入口\n├── src/\n│ └── openapi-mcp-server/\n│ ├── openapi/\n│ │ └── parser.ts # OpenAPI → MCP 工具转换\n│ ├── mcp/\n│ │ └── proxy.ts # MCP 工具注册与执行\n│ └── client/\n│ └── http-client.ts # HTTP 请求执行\n└── __tests__/ # 测试文件目录\n```\n\n### 工具生成流程\n\nMCP 工具通过 OpenAPI 规范自动生成，无需手动编写代码：\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[每个 operation 生成一个 MCP 工具]\n C --> D[参数 → inputSchema]\n C --> E[响应 → returnSchema]\n D --> F[MCPProxy.setupHandlers]\n E --> F\n F --> G[MCP SDK 注册工具]\n```\n\n资料来源：[CLAUDE.md:20-35](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## 开发命令\n\n### 常用命令\n\n| 命令 | 说明 | 用途 |\n|------|------|------|\n| `npm run build` | TypeScript 编译 + CLI 打包 | 生产构建 |\n| `npm run dev` | 热重载开发服务器 | 实时调试 |\n| `npm test` | 运行 vitest 测试 | 单元测试 |\n| `npm run test:watch` | 监听模式运行测试 | TDD 开发 |\n| `npm run test:coverage` | 生成测试覆盖率报告 | 代码覆盖率 |\n\n资料来源：[package.json:8-13](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### 构建流程\n\n`npm run build` 命令执行两个步骤：\n\n1. **TypeScript 编译**：`tsc -build` 编译 TypeScript 源代码\n2. **CLI 打包**：`node scripts/build-cli.js` 将代码打包为 CLI 可执行文件\n\n构建产物：\n- `index.js`：主入口\n- `bin/cli.mjs`：CLI 可执行文件\n\n```bash\n# 完整构建\nnpm run build\n\n# 仅编译 TypeScript（不打包 CLI）\ntsc -build\n\n# 热重载开发\nnpm run dev\n```\n\n资料来源：[package.json:8](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## 测试框架\n\n### Vitest 配置\n\n项目使用 Vitest 4.0.18 作为测试框架，与 Vite 集成提供快速的单元测试能力。\n\n测试文件位置遵循约定：与源文件同目录的 `__tests__` 子目录：\n\n```\nsrc/openapi-mcp-server/openapi/\n├── parser.ts\n└── __tests__/\n └── parser.test.ts\n```\n\n运行测试时需要设置 `NODE_ENV=test` 环境变量：\n\n```bash\n# 运行所有测试\nnpm test\n\n# 监听模式（文件变化时自动重新运行）\nnpm run test:watch\n\n# 生成覆盖率报告\nnpm run test:coverage\n```\n\n资料来源：[package.json:11-13](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### 参数反序列化测试\n\n`proxy.ts` 中的 `deserializeParams` 函数负责将 JSON 字符串参数反序列化为对象。测试覆盖以下场景：\n\n- JSON 对象字符串 → 对象\n- JSON 数组字符串 → 数组\n- 嵌套对象的递归反序列化\n- 无效 JSON 字符串保留原值\n\n```typescript\n// 测试示例\nconst input = { filter: '[{\"property\":\"Name\",\"checkbox\":{\"equals\":true}}]' }\nconst result = deserializeParams(input)\n// result.filter 变为数组而非字符串\n```\n\n资料来源：[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)\n\n## 本地测试配置\n\n### Cursor 客户端测试\n\n在 Cursor 中测试本地修改的步骤：\n\n```mermaid\ngraph LR\n A[npm link] --> B[创建全局符号链接]\n B --> C[修改 mcp.json 配置]\n C --> D[Cursor 连接本地包]\n D --> E[测试 MCP 工具]\n E --> F{npm unlink 清理}\n```\n\n**步骤 1**：在仓库根目录创建符号链接\n\n```bash\nnpm link\n```\n\n**步骤 2**：修改 Cursor 的 `mcp.json` 配置\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n**步骤 3**：测试完成后清理\n\n```bash\nnpm unlink\n```\n\n资料来源：[README.md:85-105](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### 命令行直接执行\n\n本地构建后可使用 `npx` 直接执行：\n\n```bash\n# 使用本地路径执行\nnpx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server\n```\n\n## HTTP 传输模式调试\n\n### 启动带认证的 HTTP 服务器\n\n```bash\n# 自动生成认证令牌（仅用于开发）\nnpx @notionhq/notion-mcp-server --transport http\n\n# 指定自定义令牌\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# 使用环境变量指定令牌\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n### 启动参数说明\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--transport` | 传输类型：`stdio` 或 `http` | `stdio` |\n| `--port` | HTTP 服务器端口 | `3000` |\n| `--auth-token` | 认证令牌 | 自动生成 |\n| `--disable-auth` | 禁用认证 | - |\n| `--help`, `-h` | 显示帮助信息 | - |\n\n资料来源：[scripts/start-server.ts:15-30](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### HTTP 请求示例\n\n使用认证令牌发起请求：\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n## Docker 开发\n\n### 本地构建 Docker 镜像\n\n```bash\n# 构建镜像\ndocker compose build\n\n# 运行容器\ndocker compose up\n```\n\n### Docker 配置示例\n\n使用环境变量传递 Notion 令牌（推荐）：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"notion-mcp-server\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n使用 OPENAPI_MCP_HEADERS（高级场景）：\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"OPENAPI_MCP_HEADERS\",\n \"notion-mcp-server\"\n ],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_****\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:55-90](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## 发布流程\n\n### npm 发布\n\n```bash\n# 登录 npm\nnpm login\n\n# 发布包（需要 public 访问权限）\nnpm publish --access public\n```\n\n### 版本管理\n\n当前版本：`2.3.0`\n\n包名称：`@notionhq/notion-mcp-server`\n\n发布前请确保：\n1. 所有测试通过：`npm test`\n2. 构建成功：`npm run build`\n3. 更新版本号（在 `package.json` 中）\n\n资料来源：[package.json:4-7](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## OpenAPI 解析器开发\n\n### 模式转换逻辑\n\n`parser.ts` 实现了 OpenAPI Schema 到 JSON Schema 的转换：\n\n```mermaid\ngraph TD\n A[OpenAPI Schema] --> B{类型判断}\n B -->|binary format| C[转换为 uri-reference]\n B -->|object| D[处理 properties]\n B -->|array| E[递归处理 items]\n B -->|enum| F[保留 enum 值]\n B -->|oneOf/anyOf| G[递归转换子模式]\n C --> H[JSON Schema]\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n### 关键转换规则\n\n| OpenAPI 特性 | 转换处理 |\n|--------------|----------|\n| `format: binary` | 转为 `format: uri-reference` |\n| `type: object` | 保留 `properties` 和 `required` |\n| `type: array` | 递归处理 `items` |\n| `additionalProperties` | 布尔值或递归处理对象 |\n| `oneOf/anyOf/allOf` | 递归转换子模式 |\n| `const` | 保留用于 discriminator |\n\n资料来源：[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)\n\n## 常见问题排查\n\n### 问题：模块导入错误\n\n确保使用 ES Modules 运行，检查 `package.json` 中 `\"type\": \"module\"` 配置。\n\n### 问题：测试找不到文件\n\n检查测试文件是否位于源文件同级的 `__tests__` 目录中，文件名应匹配 `*.test.ts` 模式。\n\n### 问题：HTTP 认证失败\n\n确认请求头中包含正确的 `Authorization: Bearer `，且令牌与服务器配置一致。\n\n### 问题：TypeScript 编译错误\n\n运行 `npm run build` 前确保已安装所有依赖，必要时删除 `node_modules` 后重新安装。\n\n---\n\n\n\n## 从 v1.x 到 v2.0.0 迁移指南\n\n### 相关页面\n\n相关主题：[项目介绍与版本说明](#page-1), [MCP 工具集详解](#page-3)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# 从 v1.x 到 v2.0.0 迁移指南\n\n## 概述\n\nNotion MCP Server v2.0.0 是该项目的重大版本更新，主要迁移到 **Notion API 2025-09-03** 版本（即 Data Source Edition）。此次更新引入了 **data sources（数据源）** 作为数据库的主要抽象概念，取代了传统的 `database` 概念。\n\n> **重要提示**：v2.0.0 **不需要代码更改**。MCP 工具在服务器启动时自动被发现。当你升级到 v2.0.0 时，AI 客户端将自动看到新的工具名称和参数，旧版数据库工具将不再可用。\n\n资料来源：[README.md:100-105]()\n\n## 版本变化总览\n\n### 工具变化统计\n\n| 变更类型 | 数量 | 说明 |\n|---------|------|------|\n| 移除工具 | 3 个 | 被新数据源工具替代 |\n| 新增工具 | 7 个 | 完整的数据源操作能力 |\n| 工具总数 | 22 个 | v1.x 为 19 个 |\n\n资料来源：[README.md:106-108]()\n\n### 架构变化图示\n\n```mermaid\ngraph TD\n subgraph v1.x 架构\n A1[数据库操作] -->|database_id| B1[post-database-query]\n A1 -->|database_id| B2[update-a-database]\n A1 -->|database_id| B3[create-a-database]\n end\n \n subgraph v2.0.0 架构\n A2[数据源操作] -->|data_source_id| C1[query-data-source]\n A2 -->|data_source_id| C2[update-a-data-source]\n A2 -->|data_source_id| C3[create-a-data-source]\n A2 -->|data_source_id| C4[retrieve-a-data-source]\n A2 -->|data_source_id| C5[list-data-source-templates]\n end\n \n A2 -.->|page_id / database_id| C6[move-page]\n A2 -.->|向后兼容| C7[retrieve-a-database]\n \n style A1 fill:#ffcccc\n style A2 fill:#ccffcc\n style B1 fill:#ffcccc\n style B2 fill:#ffcccc\n style B3 fill:#ffcccc\n style C1 fill:#ccffcc\n style C2 fill:#ccffcc\n style C3 fill:#ccffcc\n style C4 fill:#ccffcc\n style C5 fill:#ccffcc\n```\n\n## 移除的工具\n\n以下三个工具已被新工具替代，不再可用：\n\n| 旧工具名称 (v1.x) | 替代工具 (v2.0) | 用途 |\n|-----------------|---------------|------|\n| `post-database-query` | `query-data-source` | 查询数据源 |\n| `update-a-database` | `update-a-data-source` | 更新数据源 |\n| `create-a-database` | `create-a-data-source` | 创建数据源 |\n\n资料来源：[README.md:72-74]()\n\n## 新增的工具\n\n### 数据源操作工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `query-data-source` | 使用过滤器和排序查询数据源 |\n| `retrieve-a-data-source` | 获取数据源的元数据和架构 |\n| `update-a-data-source` | 更新数据源属性 |\n| `create-a-data-source` | 创建新的数据源 |\n| `list-data-source-templates` | 列出数据源中的可用模板 |\n\n### 页面操作工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `move-page` | 将页面移动到不同的父级位置 |\n| `retrieve-a-database` | 获取数据库元数据（包括数据源 ID 列表） |\n\n资料来源：[README.md:75-83]()\n\n## 参数变更说明\n\n### 核心参数变化\n\n| 变更项 | v1.x | v2.0.0 | 说明 |\n|-------|------|--------|------|\n| 数据库标识符 | `database_id` | `data_source_id` | 所有数据源操作使用新参数名 |\n| 搜索过滤器值 | `[\"page\", \"database\"]` | `[\"page\", \"data_source\"]` | 搜索 API 的过滤器值变更 |\n| 页面创建父级 | 仅 `page_id` | `page_id` 或 `database_id` | 现在支持数据源作为父级 |\n\n资料来源：[README.md:84-87]()\n\n### 参数转换示例\n\n```mermaid\ngraph LR\n subgraph v1.x 参数传递\n A1[\"database_id: 'xxx'\"] --> B1[数据库操作]\n end\n \n subgraph v2.0.0 参数传递\n A2[\"data_source_id: 'xxx'\"] --> B2[数据源操作]\n end\n \n style A1 fill:#ffcccc\n style A2 fill:#ccffcc\n```\n\n## API 版本与端点\n\n### 使用的 API 版本\n\nv2.0.0 使用 **Notion API 版本 `2025-09-03`**（Data Source Edition）。\n\n> 此版本引入了数据源作为数据库的主要抽象，是 Notion API 的重大更新。\n\n资料来源：[CLAUDE.md:38]()\n\n### 新增的 API 端点\n\n| 端点类型 | 端点路径 | 说明 |\n|---------|---------|------|\n| 传统端点 | `/v1/databases/{database_id}` | 保留传统数据库端点 |\n| 新端点 | `/v1/data_sources/{data_source_id}` | 新增数据源端点 |\n\n资料来源：[CLAUDE.md:39-40]()\n\n## 迁移操作指南\n\n### 步骤一：识别硬编码的工具引用\n\n如果你的代码或提示词中硬编码了旧版工具名称，需要进行以下更新：\n\n| 旧工具 (v1.x) | 新工具 (v2.0) | 参数变更 |\n|--------------|---------------|---------|\n| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |\n| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |\n| `create-a-database` | `create-a-data-source` | 参数不变（使用 `parent.page_id`） |\n\n资料来源：[README.md:117-121]()\n\n### 步骤二：更新参数名称\n\n```diff\n# 数据库查询操作\n- tool: \"post-database-query\"\n- params: { \"database_id\": \"xxx\" }\n+ tool: \"query-data-source\"\n+ params: { \"data_source_id\": \"xxx\" }\n\n# 数据库更新操作\n- tool: \"update-a-database\"\n- params: { \"database_id\": \"xxx\", ... }\n+ tool: \"update-a-data-source\"\n+ params: { \"data_source_id\": \"xxx\", ... }\n```\n\n### 步骤三：理解保留的工具\n\n`retrieve-a-database` 工具仍然可用，用于获取数据库元数据。该工具现在会返回数据源 ID 列表。使用 `retrieve-a-data-source` 获取特定数据源的架构和属性。\n\n```mermaid\ngraph TD\n A[retrieve-a-database] -->|获取数据库元数据| B[data_source_ids 列表]\n B --> C[retrieve-a-data-source]\n C -->|获取数据源架构| D[schema 和 properties]\n```\n\n资料来源：[README.md:123-125]()\n\n## MCP 服务器工具自动发现机制\n\nNotion MCP Server 的一个关键特性是**工具自动生成**机制。工具从 OpenAPI 规范自动派生，无需手动代码更改。\n\n### 工具生成流程\n\n```mermaid\ngraph TD\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 规范\"] --> B[\"src/init-server.ts
加载并验证规范\"]\n B --> C[\"openapi/parser.ts
OpenAPIToMCPConverter\"]\n C --> D[\"convertToMCPTools() 方法\"]\n D --> E[\"mcp/proxy.ts
MCPProxy.setupHandlers()\"]\n E --> F[\"MCP SDK 注册工具\"]\n \n subgraph 关键转换逻辑\n C -.->|1. operationId → 工具名| G[\"retrieve-a-data-source\"]\n C -.->|2. parameters + requestBody → inputSchema| H[\"输入参数模式\"]\n C -.->|3. Response schema → returnSchema| I[\"返回模式\"]\n end\n```\n\n资料来源：[CLAUDE.md:18-30]()\n\n### 文件结构说明\n\n| 文件路径 | 职责 |\n|---------|------|\n| `scripts/notion-openapi.json` | OpenAPI 3.1.0 规范（所有工具的来源） |\n| `src/init-server.ts` | 服务器初始化 |\n| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI → MCP 工具转换 |\n| `src/openapi-mcp-server/mcp/proxy.ts` | MCP 工具注册和执行 |\n| `src/openapi-mcp-server/client/http-client.ts` | HTTP 请求执行 |\n\n资料来源：[CLAUDE.md:33-36]()\n\n## 搜索功能变更\n\n### 搜索过滤器值变化\n\nv2.0.0 中，搜索 API 的过滤器值发生了以下变化：\n\n| 对象类型 | v1.x 值 | v2.0.0 值 |\n|---------|---------|----------|\n| 页面 | `\"page\"` | `\"page\"` |\n| 数据库/数据源 | `\"database\"` | `\"data_source\"` |\n\n```mermaid\ngraph LR\n A[搜索过滤器] -->|v1.x| B[\"value: 'database'\"]\n A -->|v2.0.0| C[\"value: 'data_source'\"]\n \n style B fill:#ffcccc\n style C fill:#ccffcc\n```\n\n资料来源：[README.md:85-86]()\n\n## 页面创建增强\n\n### 新增的父级类型支持\n\nv2.0.0 增强了页面创建功能，现在支持两种父级类型：\n\n| 父级类型 | 参数名 | 说明 |\n|---------|--------|------|\n| 页面 | `page_id` | 在现有页面下创建 |\n| 数据源（数据库） | `database_id` | 在数据源下创建页面 |\n\n这使得在数据源中创建条目更加直接，无需先获取数据源对应的页面 ID。\n\n资料来源：[README.md:87-88]()\n\n## 常见问题\n\n### Q1：是否需要修改代码？\n\n**否**。MCP 工具在服务器启动时自动被发现。升级到 v2.0.0 后，AI 客户端会自动看到新的工具名称和参数。\n\n> **唯一例外**：如果你在代码或提示词中**硬编码**了旧版工具名称，则需要手动更新为新工具名称和参数。\n\n资料来源：[README.md:109-113]()\n\n### Q2：如何区分数据库和数据源？\n\n- **数据库（Database）**：传统概念，保留用于向后兼容\n- **数据源（Data Source）**：API 2025-09-03 引入的新概念，是当前的主要抽象\n\n使用 `retrieve-a-database` 获取数据库元数据，其中包含关联的 `data_source_ids` 列表。\n\n资料来源：[README.md:123-125]()\n\n### Q3：如何获取数据源的详细信息？\n\n使用 `retrieve-a-data-source` 工具获取特定数据源的架构和属性：\n\n```typescript\n// 获取数据源详情\ntool: \"retrieve-a-data-source\"\nparams: {\n \"data_source_id\": \"\"\n}\n```\n\n资料来源：[README.md:77]()\n\n## 环境变量配置\n\n### Notion 认证\n\n| 环境变量 | 说明 | 推荐度 |\n|---------|------|--------|\n| `NOTION_TOKEN` | Notion 集成令牌 | ⭐ 推荐 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的 API 头信息 | 高级用法 |\n\n### HTTP 传输认证\n\n| 环境变量 | 说明 |\n|---------|------|\n| `AUTH_TOKEN` | HTTP 传输的 Bearer 令牌（可通过 `--auth-token` 命令行参数覆盖） |\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n## 构建和测试命令\n\n### 常用命令\n\n| 命令 | 功能 |\n|-----|------|\n| `npm run build` | TypeScript 编译 + CLI 打包 |\n| `npm test` | 运行 Vitest 测试 |\n| `npm run dev` | 启动热重载的开发服务器 |\n\n资料来源：[CLAUDE.md:32]()\n\n### 本地测试配置\n\n1. 在仓库根目录运行 `npm link` 创建全局符号链接\n2. 在 Cursor 的 `mcp.json` 中添加配置：\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. 测试完成后，运行 `npm unlink` 清理\n\n资料来源：[README.md:26-40]()\n\n## 总结\n\n### 迁移检查清单\n\n- [ ] 识别代码中硬编码的旧版工具名称\n- [ ] 将 `database_id` 参数更新为 `data_source_id`\n- [ ] 将搜索过滤器值从 `\"database\"` 更新为 `\"data_source\"`\n- [ ] 验证 AI 客户端能自动发现新工具\n- [ ] 测试数据源相关操作（查询、更新、创建）\n\n### 关键变更一览\n\n| 变更类别 | 变更内容 |\n|---------|---------|\n| API 版本 | `2022-06-28` → `2025-09-03` |\n| 移除工具 | 3 个数据库工具 |\n| 新增工具 | 7 个数据源和页面工具 |\n| 工具总数 | 19 → 22 |\n| 核心参数 | `database_id` → `data_source_id` |\n| 搜索过滤器 | `database` → `data_source` |\n| 页面创建 | 支持 `database_id` 作为父级 |\n\n> **记住**：最关键的迁移点是参数名称的变更（`database_id` → `data_source_id`）和搜索过滤器值的变化。只要更新这两处，你的应用就能平滑迁移到 v2.0.0。\n\n---\n\n\n\n## OpenAPI 规范与文件上传\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#page-2), [MCP 工具集详解](#page-3)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)\n- [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)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [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)\n
\n\n# OpenAPI 规范与文件上传\n\n## 概述\n\nNotion MCP Server 的核心设计理念是通过 OpenAPI 3.1.0 规范文件自动生成 MCP 工具。文件上传功能是该架构中的重要组成部分，允许用户通过 MCP 协议上传本地文件到 Notion 服务端。\n\n本文档详细说明 OpenAPI 规范解析机制与二进制文件上传处理的实现原理。\n\n## 架构总览\n\n```\nscripts/notion-openapi.json\n ↓\n OpenAPI 3.1.0 规范\n ↓\nsrc/openapi-mcp-server/openapi/parser.ts\n ↓\n OpenAPI → MCP 工具转换\n ↓\nsrc/openapi-mcp-server/mcp/proxy.ts\n ↓\n MCP 工具注册与调用\n ↓\nsrc/openapi-mcp-server/client/http-client.ts\n ↓\n Notion API HTTP 请求执行\n```\n\n资料来源：[CLAUDE.md:1-30]()\n\n## OpenAPI 规范解析机制\n\n### 规范文件结构\n\n`scripts/notion-openapi.json` 是整个项目的核心数据源，采用 OpenAPI 3.1.0 标准定义所有 Notion API 端点：\n\n| 组件 | 说明 |\n|------|------|\n| `paths` | API 路径与方法定义 |\n| `components.schemas` | 数据模型与类型定义 |\n| `components.parameters` | 可复用参数定义 |\n| `operationId` | 工具名称来源 |\n\n资料来源：[CLAUDE.md:21-22]()\n\n### Schema 转换流程\n\n`OpenAPIToMCPConverter` 类负责将 OpenAPI Schema 转换为 MCP 可用的 JSON Schema：\n\n```typescript\nconvertOpenApiSchemaToJsonSchema(\n schema: OpenAPIV3.SchemaObject,\n resolvedRefs: Set,\n resolveRefs: boolean\n): IJsonSchema\n```\n\n转换过程中包含以下关键处理：\n\n| 特性 | 处理方式 |\n|------|----------|\n| 二进制格式 | 转换为 `uri-reference` |\n| 对象属性 | 递归转换 `properties` |\n| 数组类型 | 递归转换 `items` |\n| 组合类型 | 处理 `oneOf`、`anyOf`、`allOf` |\n| 常量值 | 保留 `const` 字段 |\n| 默认值 | 保留 `default` 字段 |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-100]()\n\n## 二进制文件与上传处理\n\n### Binary 格式转换\n\n当 OpenAPI Schema 中的 `format` 字段为 `binary` 时，解析器会自动进行以下转换：\n\n```typescript\nif (schema.format === 'binary') {\n result.format = 'uri-reference'\n const binaryDesc = 'absolute paths to local files'\n result.description = schema.description \n ? `${schema.description} (${binaryDesc})` \n : binaryDesc\n}\n```\n\n此转换使得 MCP 客户端可以传入本地文件的绝对路径，系统会自动处理文件上传逻辑。\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:50-60]()\n\n### 文件上传流程图\n\n```mermaid\ngraph TD\n A[MCP 客户端调用工具] --> B[解析参数中的 binary 字段]\n B --> C{文件是否存在?}\n C -->|不存在| D[抛出参数错误]\n C -->|存在| E[读取本地文件内容]\n E --> F[构造 multipart/form-data 请求]\n F --> G[HTTP 客户端执行上传]\n G --> H{响应状态}\n H -->|2xx| I[返回成功结果]\n H -->|4xx/5xx| J[抛出 HttpClientError]\n```\n\n## 参数反序列化机制\n\n### 参数处理策略\n\n`deserializeParams` 函数解决了 MCP 协议传输过程中的双重序列化问题：\n\n| 问题场景 | 处理方式 |\n|----------|----------|\n| JSON 字符串对象 | 自动解析为对象 |\n| JSON 字符串数组 | 自动解析为数组 |\n| 嵌套 JSON 字符串 | 递归反序列化 |\n| 普通字符串 | 保持原样 |\n\n```typescript\nfunction deserializeParams(params: Record): Record {\n const result: Record = {}\n \n for (const [key, value] of Object.entries(params)) {\n if (typeof value === 'string') {\n const trimmed = value.trim()\n if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||\n (trimmed.startsWith('[') && trimmed.endsWith(']'))) {\n // JSON.parse and validate...\n }\n }\n // ... more handling\n }\n return result\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:176-210]()\n\n### 数组元素反序列化\n\n数组内的 JSON 字符串元素也会被递归处理：\n\n```typescript\n} else if (Array.isArray(value)) {\n result[key] = value.map((item) => {\n if (typeof item !== 'string') return item\n // ... check and parse JSON strings in array\n })\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:195-208]()\n\n## HTTP 客户端与请求执行\n\n### 请求参数分类\n\nHTTP 客户端将参数分为三类处理：\n\n| 参数类型 | 来源 | 用途 |\n|----------|------|------|\n| `urlParameters` | `path` 和 `query` 参数 | URL 路径与查询字符串 |\n| `bodyParams` | `requestBody` 内容 | JSON 请求体 |\n| `formData` | multipart/form-data | 文件上传表单 |\n\n```typescript\n// 提取 path 和 query 参数\nif (operation.parameters) {\n for (const param of operation.parameters) {\n if (param.in === 'path' || param.in === 'query') {\n if (params[param.name] !== undefined) {\n urlParameters[param.name] = params[param.name]\n }\n }\n }\n}\n\n// 无 requestBody 时，将 bodyParams 转为 URL 参数\nif (!operation.requestBody && !formData) {\n for (const key in bodyParams) {\n if (bodyParams[key] !== undefined) {\n urlParameters[key] = bodyParams[key]\n delete bodyParams[key]\n }\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:80-100]()\n\n### 表单数据处理\n\n当存在 `formData` 时，HTTP 客户端自动设置正确的 `Content-Type` 头：\n\n```typescript\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:110-115]()\n\n## 工具注册与执行\n\n### MCP 工具生成\n\n`MCPProxy.setupHandlers()` 方法负责将 OpenAPI 操作转换为 MCP 工具：\n\n```typescript\nsetupHandlers(tools: Record) {\n this.server.setRequestHandler(ListToolsRequestSchema, async () => {\n const toolDefs = []\n for (const method of methods) {\n toolDefs.push({\n name: method.name,\n description: method.description,\n inputSchema: method.inputSchema,\n annotations: {\n title: this.operationIdToTitle(method.name),\n ...(isReadOnly ? { readOnlyHint: true } : { destructiveHint: true }),\n },\n })\n }\n return { tools: toolDefs }\n })\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:150-170]()\n\n### 工具调用处理\n\n当 MCP 客户端调用工具时，系统执行以下步骤：\n\n```mermaid\nsequenceDiagram\n 客户端->>MCP服务器: CallToolRequest(name, arguments)\n MCP服务器->>代理: findOperation(name)\n 代理-->>MCP服务器: OperationObject\n MCP服务器->>参数反序列化: deserializeParams(arguments)\n 参数反序列化-->>MCP服务器: deserializedParams\n MCP服务器->>HTTP客户端: executeOperation(operation, deserializedParams)\n HTTP客户端->>Notion API: HTTP Request\n Notion API-->>HTTP客户端: Response\n HTTP客户端-->>MCP服务器: response.data\n MCP服务器-->>客户端: { content: [{ type: 'text', text: JSON.stringify(data) }] }\n```\n\n## 错误处理\n\n### HTTP 客户端错误\n\n`HttpClientError` 异常包含状态码和响应数据：\n\n```typescript\nreturn {\n content: [\n {\n type: 'text',\n text: JSON.stringify(error.data?.response?.data ?? error.data ?? {}),\n },\n ],\n isError: true,\n}\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:200-210]()\n\n## 配置与运行环境\n\n### 环境变量\n\n| 变量名 | 说明 | 优先级 |\n|--------|------|--------|\n| `NOTION_TOKEN` | Notion 集成令牌（推荐） | 高 |\n| `OPENAPI_MCP_HEADERS` | JSON 格式的自定义请求头 | 中 |\n\n### 命令行参数\n\n```bash\nnotion-mcp-server [选项]\n\n选项:\n --transport 传输类型: 'stdio' 或 'http'\n --port HTTP 服务端口 (默认: 3000)\n --auth-token HTTP 传输认证令牌\n --disable-auth 禁用 HTTP 认证\n --help, -h 显示帮助信息\n```\n\n资料来源：[scripts/start-server.ts:60-80]()\n\n## 开发指南\n\n### 本地测试文件上传\n\n1. **构建项目**：\n ```bash\n npm run build\n ```\n\n2. **链接本地包**：\n ```bash\n npm link\n ```\n\n3. **配置 MCP 客户端**：\n ```json\n {\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n }\n ```\n\n4. **测试文件上传**：\n ```\n Upload file \"/path/to/document.pdf\" to page \"My Page\"\n ```\n\n5. **清理**：\n ```bash\n npm unlink\n ```\n\n资料来源：[README.md:Development]()\n\n## 相关资源\n\n- **OpenAPI 规范文件**：[scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)\n- **Notion API 版本**：`2025-09-03` (Data Source Edition)\n- **API 端点类型**：\n - `/v1/databases/{database_id}` - 传统数据库端点\n - `/v1/data_sources/{data_source_id}` - 新数据源端点\n\n资料来源：[CLAUDE.md:40-45]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：makenotion/notion-mcp-server\n\n摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。\n\n## 1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：makenotion/notion-mcp-server\n\n摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。\n\n## 1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# notion-mcp-server - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 notion-mcp-server 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Official Notion MCP Server 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目介绍与版本说明。围绕“项目介绍与版本说明”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构与模块设计。围绕“系统架构与模块设计”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：MCP 工具集详解。围绕“MCP 工具集详解”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：安装与客户端配置。围绕“安装与客户端配置”模拟一次用户任务，不展示安装或运行结果。\n5. page-6：认证机制与安全配置。围绕“认证机制与安全配置”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目介绍与版本说明”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构与模块设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“MCP 工具集详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“安装与客户端配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-6\n输入：用户提供的“认证机制与安全配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目介绍与版本说明”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构与模块设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“MCP 工具集详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“安装与客户端配置”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-6：Step 5 必须围绕“认证机制与安全配置”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/makenotion/notion-mcp-server\n- https://github.com/makenotion/notion-mcp-server#readme\n- README.md\n- package.json\n- src/openapi-mcp-server/index.ts\n- src/openapi-mcp-server/auth/index.ts\n- src/openapi-mcp-server/client/http-client.ts\n- src/openapi-mcp-server/mcp/proxy.ts\n- scripts/notion-openapi.json\n- src/openapi-mcp-server/openapi/parser.ts\n- docker-compose.yml\n- Dockerfile\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 notion-mcp-server 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：makenotion/notion-mcp-server\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx @notionhq/notion-mcp-server\n```\n\n来源：https://github.com/makenotion/notion-mcp-server#readme\n\n## 来源\n\n- repo: https://github.com/makenotion/notion-mcp-server\n- docs: https://github.com/makenotion/notion-mcp-server#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_8ca90274aa7b4b399787d5d55144dc3a" }