notion-mcp 0.2.0__tar.gz

notion_mcp-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug report
+description: Report a reproducible problem in notion-mcp.
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Do not include real Notion tokens, private workspace data, local config
+        files, or unredacted logs. Sensitive security reports should follow
+        SECURITY.md instead of a public issue.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction steps
+      description: Provide the smallest command sequence or MCP client flow that reproduces the issue.
+      placeholder: |
+        1. Run `notion-mcp ...`
+        2. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include sanitized output only.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      placeholder: "notion-mcp 0.2.0 or commit SHA"
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, install method, MCP client if applicable.
+      placeholder: |
+        OS:
+        Python:
+        Install method:
+        MCP client:

notion_mcp-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Sensitive security report
+    url: https://github.com/bluewhitep/notion_mcp/security/advisories/new
+    about: Use GitHub private vulnerability reporting for sensitive security reports.

notion_mcp-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Suggest an improvement or new capability.
+title: "[Feature]: "
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: What workflow should this improve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Describe the CLI, MCP tool, configuration, or documentation change you want.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Optional. Mention current workarounds or other designs.
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: Compatibility notes
+      description: Optional. Mention any impact on existing CLI commands, MCP tools, or config files.

notion_mcp-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+- 
+
+## Validation
+
+- [ ] `uv run pytest -q -p no:cacheprovider`
+- [ ] `uv run ruff check .`
+- [ ] `uv run mypy src`
+- [ ] Documentation updated, or not applicable
+
+## Safety
+
+- [ ] No real Notion tokens, private workspace data, local config files, or unredacted logs are included.
+- [ ] Live Notion tests were not run, or their credential/data scope is documented.

notion_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    env:
+      PYTHONDONTWRITEBYTECODE: "1"
+      UV_PROJECT_ENVIRONMENT: /tmp/notion-mcp-ci-${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.12"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Run tests
+        run: uv run pytest -q -p no:cacheprovider
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Run mypy
+        run: uv run mypy src
+
+      - name: Build package
+        run: uv build --out-dir /tmp/notion-mcp-dist

notion_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish Python package
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/notion-mcp
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

notion_mcp-0.2.0/.gitignore

@@ -0,0 +1,44 @@
+__pycache__/
+# BEGIN git-guard managed ignore rules
+.*
+!.gitignore
+!.gitmodules
+!.github/
+.github/**
+!.github/workflows/
+!.github/workflows/*.yml
+!.github/workflows/*.yaml
+!.github/actions/
+!.github/actions/**
+!.github/ISSUE_TEMPLATE/
+!.github/ISSUE_TEMPLATE/**
+!.github/PULL_REQUEST_TEMPLATE.md
+!.github/pull_request_template.md
+!.github/PULL_REQUEST_TEMPLATE/
+!.github/PULL_REQUEST_TEMPLATE/**
+!.github/DISCUSSION_TEMPLATE/
+!.github/DISCUSSION_TEMPLATE/**
+!.github/dependabot.yml
+!.github/CODEOWNERS
+!.github/FUNDING.yml
+!.github/SECURITY.md
+!.github/CODE_OF_CONDUCT.md
+!.github/CONTRIBUTING.md
+!.github/SUPPORT.md
+AGENTS.md
+# END git-guard managed ignore rules
+*.py[cod]
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+uv.lock
+build/
+dist/
+*.egg-info/
+.DS_Store
+.dev_docs/
+.private_docs/
+tests/v5/
+Docs/skills/test_copies/

notion_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Pull requests are welcome.
+
+## Before Opening a Pull Request
+
+Use a small, focused change. Keep unrelated refactors, formatting churn, and
+generated files out of the PR.
+
+Run the local checks when they apply:
+
+```bash
+uv run pytest -q -p no:cacheprovider
+uv run ruff check .
+uv run mypy src
+```
+
+Live Notion tests require explicit opt-in and real credentials. Do not run or
+document live results unless the test command, required environment variables,
+and data-safety scope are clear.
+
+## Documentation
+
+Update user or developer documentation when a change affects CLI commands,
+MCP tools, configuration, installation, security behavior, or public package
+metadata.
+
+## Security
+
+Do not include real Notion tokens, private workspace content, local config files,
+or unredacted logs in issues, pull requests, tests, or documentation.
+
+Report sensitive security issues through the process in [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing to this repository, you agree that your contribution is licensed
+under the Apache License 2.0.

notion_mcp-0.2.0/Docs/Developer/API.md

@@ -0,0 +1,32 @@
+# 开发者接口索引
+
+本文档面向开发者，说明当前仓库的接口文档入口。当前项目已经从 REST 原型补全为本地 Notion MCP 服务器。
+
+## 当前接口状态
+
+- `src/notion_mcp/core/`：唯一业务逻辑层，供 CLI、MCP Tool 和兼容代码复用。
+- `src/notion_mcp/server.py` 与 `src/notion_mcp/routes/`：内部 REST 原型兼容代码，不是公开 server CLI 入口，也不是最终 MCP Tool 接口。
+- `src/notion_mcp/cli/`：git-like CLI，人类入口，调用 Core。
+- `src/notion_mcp/mcp_server/`：MCP server 和 MCP tools，Agent/LLM 结构化入口，调用 Core。
+
+## 文档入口
+
+- Core API：`Docs/Developer/api/core.md`
+- CLI API：`Docs/Developer/api/cli.md`
+- Core 测试：`Docs/Developer/testing/core.md`
+- CLI 测试：`Docs/Developer/testing/cli.md`
+- MCP 测试：`Docs/Developer/testing/mcp.md`
+- Live 测试：`Docs/Developer/testing/live.md`
+- 场景测试：`Docs/Developer/testing/scenarios.md`
+- MCP Tool contract：`Docs/Developer/mcp_tools/README.md`
+
+## 调用边界
+
+目标调用关系必须保持为：
+
+```text
+Human -> CLI -> Core
+Agent / LLM -> MCP Tool -> Core
+```
+
+禁止 MCP Tool 通过 CLI 字符串调用，也禁止 CLI 和 MCP Tool 各自复制业务逻辑。

notion_mcp-0.2.0/Docs/Developer/api/cli.md

@@ -0,0 +1,204 @@
+# CLI API
+
+本文档面向开发者，记录当前 `notion-mcp` CLI 的公开命令面、隐藏兼容入口和 Core 调用边界。CLI 负责终端使用体验，业务能力必须来自 Core service。
+
+## 入口
+
+- package：`notion_mcp.cli`
+- console script：`notion-mcp = notion_mcp.cli:app`
+- root app：`src/notion_mcp/cli/app.py`
+- help options：`--help` and `-h`
+
+## 核心边界
+
+```text
+CLI -> Core -> Notion SDK/API
+MCP Tool -> Core -> Notion SDK/API
+```
+
+CLI 不应直接调用 Notion SDK。新增命令时，应先确认对应 Core service 能力；如果 Core 缺失，应先补 Core，再接 CLI。
+
+## 公开 Root 命令
+
+- `notion-mcp init`
+  - 初始化当前目录的项目级 `.notion_mcp/`。
+  - 不写入 token，不要求 user id。
+- `notion-mcp pwd`
+  - 从当前目录向上解析项目根目录。
+- `notion-mcp version`
+  - 输出 MCP package version 和配置的 Notion API version。
+- `notion-mcp config --global --show`
+  - 输出全局配置摘要，不暴露 token。
+- `notion-mcp config --global user.token <token>`
+  - 更新全局 token。
+- `notion-mcp config --global user.name <name>`
+  - 更新全局用户显示名称。
+- `notion-mcp config --local --show`
+  - 输出当前项目级配置摘要。
+
+`project`、`local`、root `status`、`config global/local` 和 `config set/get/unset/list` 只保留为隐藏兼容入口，不属于公开命令面。
+
+## Project Context
+
+项目上下文由 Core 提供：
+
+```text
+ProjectResolver
+ProjectConfigStore
+AttachmentStore
+ContextResolver
+```
+
+解析规则：
+
+```text
+explicit id > attached state > error
+```
+
+项目级配置：
+
+```text
+.notion_mcp/config.json
+```
+
+Attach state：
+
+```text
+.notion_mcp/state/page.attach.json
+.notion_mcp/state/database.attach.json
+```
+
+项目级配置和 attach state 不得保存 token。
+
+## Page CLI
+
+公开命令：
+
+Page id inputs are normalized through `src/notion_mcp/core/identifiers.py`. Public `<page_id>` arguments accept raw page ids, copied Notion URLs, and Markdown links that contain Notion URLs.
+
+- `notion-mcp page attach <page_id>`
+  - 绑定当前项目默认 page。
+  - `attach` 语义是 project context binding，不是 file attachment。
+- `notion-mcp page status`
+  - 显示当前绑定 page。
+- `notion-mcp page refresh`
+  - 重新读取绑定 page 的标题、URL 和状态，只刷新本地 state，不修改 Notion 远端。
+- `notion-mcp page detach`
+  - 删除本地 page attach state，不修改 Notion 远端。
+- `notion-mcp page retrieve [page_id]`
+  - 读取 page 元信息。
+  - 无参数时使用 attached page。
+- `notion-mcp page blocks [page_id]`
+  - 读取 page 内容块摘要。
+  - 无参数时使用 attached page。
+- `notion-mcp page create`
+  - 创建 page。
+  - payload 没有 parent 且存在 attached page 时，默认使用 attached page 作为 parent。
+- `notion-mcp page create --parent-page <page_id>`
+  - 在指定 parent page 下创建 child page。
+- `notion-mcp page update <page_id>`
+  - 更新普通 page 或 data source entry page properties。
+- `notion-mcp page trash <page_id>`
+  - 将 page 移入 trash。
+
+隐藏兼容入口保留给旧的 page content/current/deattach aliases、旧 page-scoped block group 和旧 page insert group。它们不得作为公开用户命令记录。
+
+## Block CLI
+
+公开命令：
+
+- `notion-mcp block children <block_id>`
+  - 列出 child blocks。
+- `notion-mcp block append <block_id>`
+  - 追加 child blocks。
+- `notion-mcp block insert-after <block_id>`
+  - 在目标 block 后插入 sibling blocks。
+- `notion-mcp block update <block_id>`
+  - 更新 block。
+- `notion-mcp block trash <block_id>`
+  - 将 block 移入 trash。
+
+`insert-before` 不作为稳定公开命令。`block remove` 只作为隐藏兼容别名，行为等同 trash。
+
+## Database 和 DataSource
+
+语义边界：
+
+```text
+database = container
+data_source = table under database
+page = page or data source entry
+block = page content node
+```
+
+容器级能力使用 `database`。表级 schema/query/templates/page-entry 能力使用 `data-source`。只有使用当前绑定 database 的 active data source 时，才允许 `database` 快捷命令。
+
+### Database 容器命令
+
+- `notion-mcp database attach <database_id>`
+- `notion-mcp database attach <database_id> --data-source <id_or_name>`
+- `notion-mcp database status`
+- `notion-mcp database refresh`
+- `notion-mcp database detach`
+- `notion-mcp database retrieve [database_id]`
+- `notion-mcp database sources [database_id]`
+- `notion-mcp database create`
+- `notion-mcp database create --parent-page <page_id>`
+- `notion-mcp database update <database_id>`
+- `notion-mcp database rename <database_id> <new_name>`
+
+`database create` 创建 database 容器，并创建 initial data source。`database update` 只允许容器级更新，不用于修改 data source schema。
+
+### Database 快捷命令
+
+这些命令只作用于 attached database 的 active data source：
+
+- `notion-mcp database query --payload <json>`
+- `notion-mcp database page create --properties <json>`
+- `notion-mcp database property rename <property> <new_name>`
+
+公开 CLI 不提供 `database query --data-source`、`database page create <data_source_id>`、`database page update <page_id>` 或三参数 `database property rename`。显式 data source 操作必须使用 `data-source`；page property 更新使用 `page update`。
+
+### DataSource 命令
+
+- `notion-mcp data-source retrieve <data_source_id>`
+- `notion-mcp data-source query <data_source_id>`
+- `notion-mcp data-source create`
+- `notion-mcp data-source create <database_id>`
+- `notion-mcp data-source update <data_source_id>`
+- `notion-mcp data-source templates <data_source_id>`
+- `notion-mcp data-source property rename <data_source_id> <property> <new_name>`
+- `notion-mcp data-source page create <data_source_id>`
+
+## 其他对象域
+
+- `notion-mcp auth validate`
+- `notion-mcp auth whoami`
+- `notion-mcp user me/list/retrieve`
+- `notion-mcp comment list/create/reply`
+- `notion-mcp view retrieve/list/query/create/update`
+- `notion-mcp file-upload retrieve/list/create/send/complete`
+- `notion-mcp search query`
+- `notion-mcp custom-emoji list/retrieve`
+- `notion-mcp raw-api operations`
+- `notion-mcp raw-api invoke <operation>`
+- `notion-mcp server run`
+- `notion-mcp server status`
+- `notion-mcp server stop`
+- `notion-mcp server logs`
+- `notion-mcp server remove`
+- `notion-mcp server stdio`
+
+Raw API 是高级兜底入口，不应作为普通 page/database 编辑路径。
+
+## 移除的旧入口
+
+以下旧 root 命令不再作为公开 CLI 入口：
+
+- `notion-mcp set-token`
+- `notion-mcp set-user`
+- `notion-mcp show`
+- `notion-mcp run`
+- `notion-mcp mcp serve`
+
+配置使用 `notion-mcp config --global ...`；MCP server 使用 `notion-mcp server ...`。

notion_mcp-0.2.0/Docs/Developer/api/core.md

@@ -0,0 +1,95 @@
+# Core API
+
+本文档面向开发者，记录 `src/notion_mcp/core/` 当前已经实现的 Core 能力。Core 是唯一业务逻辑层，CLI 和 MCP Tool 都应调用 Core，而不是直接调用 Notion SDK。
+
+## 配置
+
+模块：`src/notion_mcp/core/config.py`
+
+- `CoreConfig`
+  - 保存 `notion_token`、`user_name`、`user_id`、`notion_version`、`timeout_ms`、`retry`、`default_transport` 和 `audit_enabled`。
+  - `user_id` 必须是 UUID。
+  - 默认 `notion_version` 为 `2026-03-11`。
+- `init_core_config(...)`
+  - 初始化配置并写入本地配置文件。
+  - 配置文件权限写为 `0600`。
+- `load_core_config(...)`
+  - 读取配置文件并返回严格校验后的 `CoreConfig`。
+- `update_core_config(...)`
+  - 只更新传入字段，不清空未传入字段。
+- `redacted_config(...)`
+  - 返回状态输出使用的脱敏配置，不泄露 token。
+
+## 错误模型
+
+模块：`src/notion_mcp/core/errors.py`
+
+- `CoreError`
+  - 所有 Core 错误的基类。
+  - `to_dict()` 返回 `type`、`code`、`message`、`details`。
+- `ConfigNotFoundError`
+- `ConfigValidationError`
+- `NotionAuthError`
+- `NotionOperationError`
+
+CLI JSON 输出和 MCP tool 响应应复用这些错误结构。
+
+## Notion SDK Client
+
+模块：`src/notion_mcp/core/client.py`
+
+- `NotionClientFactory`
+  - 从 `CoreConfig` 创建 Notion SDK client。
+  - 注入 `auth`、`notion_version`、`timeout_ms` 和 `retry`。
+  - 支持 `client_cls` 和 `fake_client`，用于测试和后续 MCP 场景测试。
+- `create_notion_client(...)`
+  - 默认 client factory 入口。
+
+## 认证
+
+模块：`src/notion_mcp/core/auth.py`
+
+- `AuthService.validate(...)`
+  - 调用 `client.users.me()` 校验 token。
+  - 可传入 `expected_user_id`，用于校验配置中的 Notion 用户 UUID 是否匹配当前 token。
+  - 返回 `AuthValidationResult`。
+
+## 审计
+
+模块：`src/notion_mcp/core/audit.py`
+
+- `AuditRecorder.record(...)`
+  - 写入 JSONL 审计记录。
+  - 字段包含 `timestamp`、`configured_user_id`、`operation`、`target`、`dry_run` 和 `metadata`。
+  - 会移除 `notion_token`、`token`、`auth`、`authorization`、`bearer` 等敏感字段。
+
+## Notion 对象域服务
+
+目录：`src/notion_mcp/core/services/`
+
+当前已按对象域建立服务模块：
+
+- `blocks.py`
+- `pages.py`
+- `databases.py`
+- `data_sources.py`
+- `users.py`
+- `comments.py`
+- `views.py`
+- `file_uploads.py`
+- `search.py`
+- `custom_emojis.py`
+- `raw_api.py`
+
+这些服务只依赖 Core 和 Notion SDK-compatible client，不导入 CLI 或 MCP 层。
+
+## Raw API
+
+模块：`src/notion_mcp/core/services/raw_api.py`
+
+- `registered_operations()`
+  - 返回允许 pass-through 的 Notion SDK 操作名。
+- `RawNotionService.invoke(operation, arguments)`
+  - 只允许调用登记表内的操作。
+  - 禁止未登记操作和私有属性。
+  - 用于补足 “支持 Notion SDK/API 公开能力” 的扩展入口。