notion-nilo 0.3.0__tar.gz

notion_nilo-0.3.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_nilo-0.3.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_nilo-0.3.0/Docs/Developer/API.md

@@ -0,0 +1,32 @@
+# 开发者接口索引
+
+本文档面向开发者，说明当前仓库的接口文档入口。当前项目已经从 REST 原型补全为本地 Notion MCP 服务器。
+
+## 当前接口状态
+
+- `src/nilo/core/`：唯一业务逻辑层，供 CLI、MCP Tool 和兼容代码复用。
+- `src/nilo/server.py` 与 `src/nilo/routes/`：内部 REST 原型兼容代码，不是公开 server CLI 入口，也不是最终 MCP Tool 接口。
+- `src/nilo/cli/`：git-like CLI，人类入口，调用 Core。
+- `src/nilo/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_nilo-0.3.0/Docs/Developer/api/cli.md

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

notion_nilo-0.3.0/Docs/Developer/api/core.md

@@ -0,0 +1,95 @@
+# Core API
+
+本文档面向开发者，记录 `src/nilo/core/` 当前已经实现的 Core 能力。Core 是唯一业务逻辑层，CLI 和 MCP Tool 都应调用 Core，而不是直接调用 Notion SDK。
+
+## 配置
+
+模块：`src/nilo/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/nilo/core/errors.py`
+
+- `CoreError`
+  - 所有 Core 错误的基类。
+  - `to_dict()` 返回 `type`、`code`、`message`、`details`。
+- `ConfigNotFoundError`
+- `ConfigValidationError`
+- `NotionAuthError`
+- `NotionOperationError`
+
+CLI JSON 输出和 MCP tool 响应应复用这些错误结构。
+
+## Notion SDK Client
+
+模块：`src/nilo/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/nilo/core/auth.py`
+
+- `AuthService.validate(...)`
+  - 调用 `client.users.me()` 校验 token。
+  - 可传入 `expected_user_id`，用于校验配置中的 Notion 用户 UUID 是否匹配当前 token。
+  - 返回 `AuthValidationResult`。
+
+## 审计
+
+模块：`src/nilo/core/audit.py`
+
+- `AuditRecorder.record(...)`
+  - 写入 JSONL 审计记录。
+  - 字段包含 `timestamp`、`configured_user_id`、`operation`、`target`、`dry_run` 和 `metadata`。
+  - 会移除 `notion_token`、`token`、`auth`、`authorization`、`bearer` 等敏感字段。
+
+## Notion 对象域服务
+
+目录：`src/nilo/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/nilo/core/services/raw_api.py`
+
+- `registered_operations()`
+  - 返回允许 pass-through 的 Notion SDK 操作名。
+- `RawNotionService.invoke(operation, arguments)`
+  - 只允许调用登记表内的操作。
+  - 禁止未登记操作和私有属性。
+  - 用于补足 “支持 Notion SDK/API 公开能力” 的扩展入口。

notion_nilo-0.3.0/Docs/Developer/architecture/overview.md

@@ -0,0 +1,101 @@
+# Architecture Overview
+
+本文档面向开发者，说明当前仓库的架构边界。
+
+## 当前目标
+
+本仓库提供本地运行的 Notion MCP server。当前实现围绕以下三层展开：
+
+- Core：唯一业务逻辑层。
+- CLI：面向人类的 git-like 本地命令入口。
+- MCP Tool：面向 Agent/LLM 的结构化工具入口。
+
+使用者安装、Notion connection 配置和命令用法放在 `Docs/User/`；本目录只记录开发者需要维护的实现边界。
+
+## 目标结构
+
+```text
+Human -> CLI -> Core
+Agent / LLM -> MCP Tool -> Core
+```
+
+必须保持：
+
+```text
+CLI -> Core
+MCP Tool -> Core
+```
+
+禁止：
+
+```text
+MCP Tool 通过 CLI 字符串绕行
+CLI -> Notion SDK
+MCP Tool -> Notion SDK
+```
+
+## Core
+
+Core 是唯一业务逻辑层，负责：
+
+- 全局配置读写、项目级上下文解析和 token 脱敏。
+- 集中管理 Notion API version、timeout 和 retry。
+- 统一创建 Notion SDK-compatible client。
+- auth validate 和 user/bot 信息读取。
+- 按对象域封装 Notion 服务：
+  - pages
+  - blocks
+  - databases
+  - data sources
+  - users
+  - comments
+  - views
+  - file uploads
+  - search
+  - custom emojis
+- raw API 登记表和高级兜底调用。
+- 本地审计和统一错误模型。
+
+## CLI
+
+CLI 是人类入口，负责：
+
+- git-like 命令结构。
+- 普通文本输出。
+- `--json` 输出。
+- `--dry-run`。
+- 启动和管理 MCP server。
+
+公开 server 命令包括：
+
+```text
+nilo server run
+nilo server status
+nilo server stop
+nilo server logs
+nilo server remove
+nilo server stdio
+```
+
+CLI resource command 通过 Core service 调用 Notion 能力。
+
+项目级 `.notion_mcp/` 目录只保存项目上下文和 attach state，不保存 token。全局配置继续保存 token、用户显示名和 Notion API version。
+
+## MCP Tool
+
+MCP Tool 是 Agent/LLM 入口，负责：
+
+- tool inventory。
+- input schema。
+- tool annotations。
+- 结构化错误。
+- 危险操作确认。
+
+MCP Tool 直接调用 Core service，不拼 CLI 字符串。
+
+## 非功能边界
+
+- token 默认不得在普通输出或 MCP config status 中明文泄露。
+- CLI 和 MCP 写操作应支持 dry-run 或危险操作确认。
+- live 测试默认跳过，只能在明确的测试 page/workspace 中运行。
+- Notion-Version 由 Core 配置集中管理，不在 CLI、MCP tool 或单个服务里散落硬编码。

notion_nilo-0.3.0/Docs/Developer/mcp_tools/README.md

@@ -0,0 +1,86 @@
+# MCP Tools 开发者文档
+
+本文档是 MCP tool 文档入口。当前仓库已实现 `src/nilo/mcp_server/`，使用 MCP Python SDK 的 `FastMCP` 暴露本地工具。
+
+## Server
+
+- server factory：`src/nilo/mcp_server/server.py`
+- package entry：`nilo.mcp_server:create_mcp_server`
+- CLI stdio entry：`nilo server stdio`
+- CLI background HTTP entry：`nilo server run --host 127.0.0.1 --port 8000`
+- 支持 transport：`stdio`、`streamable-http`
+
+## 工具域文档
+
+- `config.md`
+- `auth.md`
+- `pages.md`
+- `blocks.md`
+- `databases.md`
+- `data_sources.md`
+- `users.md`
+- `comments.md`
+- `views.md`
+- `file_uploads.md`
+- `search.md`
+- `custom_emojis.md`
+- `raw_api.md`
+
+## Tool Inventory
+
+当前 server 可枚举 46 个 tools：
+
+- `auth_validate`
+- `auth_whoami`
+- `block_append`
+- `block_children_list`
+- `block_trash`
+- `block_update`
+- `comment_create`
+- `comment_list`
+- `comment_reply`
+- `config_get`
+- `config_status`
+- `custom_emoji_list`
+- `custom_emoji_retrieve`
+- `data_source_create`
+- `data_source_property_rename`
+- `data_source_query`
+- `data_source_retrieve`
+- `data_source_templates`
+- `data_source_update`
+- `database_create`
+- `database_query`
+- `database_rename`
+- `database_retrieve`
+- `database_sources`
+- `database_update`
+- `file_upload_complete`
+- `file_upload_create`
+- `file_upload_list`
+- `file_upload_retrieve`
+- `file_upload_send`
+- `page_create`
+- `page_property_retrieve`
+- `page_retrieve`
+- `page_trash`
+- `page_update`
+- `raw_api_invoke`
+- `raw_api_registered_operations`
+- `search`
+- `user_list`
+- `user_me`
+- `user_retrieve`
+- `view_create`
+- `view_list`
+- `view_query`
+- `view_retrieve`
+- `view_update`
+
+## 公共规则
+
+- MCP Tool 只能调用 Core，不能调用 CLI。
+- 工具错误应返回结构化 `{"ok": false, "error": ...}`。
+- token 默认必须脱敏。
+- 删除、归档、trash 类危险工具必须带 `destructiveHint`，并要求 `confirm=true`。
+- live Notion 权限、付费计划或真实 workspace 才能验证的能力，必须在测试和进度文档中标记。

notion_nilo-0.3.0/Docs/Developer/mcp_tools/auth.md

@@ -0,0 +1,11 @@
+# Auth Tools
+
+- `auth_validate`
+  - 说明：通过 Core auth service 调用 `users.me()` 校验当前 token。
+  - 必选参数：无。
+  - 返回：`valid`、`user_id`、`name`、`raw`。
+  - live 限制：需要真实 Notion token。
+- `auth_whoami`
+  - 说明：返回当前 token 对应的 Notion 用户信息。
+  - 必选参数：无。
+  - live 限制：需要真实 Notion token。

notion_nilo-0.3.0/Docs/Developer/mcp_tools/blocks.md

@@ -0,0 +1,18 @@
+# Block Tools
+
+- `block_children_list`
+  - 说明：列出区块子元素。
+  - 必选参数：`block_id`。
+- `block_append`
+  - 说明：追加子区块，使用 Notion 2026 `position` 合约。
+  - 必选参数：`block_id`、`children`。
+  - 可选参数：`position`、`dry_run`。
+- `block_update`
+  - 说明：更新区块。
+  - 必选参数：`block_id`、`payload`。
+  - 可选参数：`dry_run`。
+- `block_trash`
+  - 说明：删除或 trash 区块。
+  - 必选参数：`block_id`、`confirm`。
+  - 可选参数：`dry_run`。
+  - 危险性：`destructiveHint=true`，缺少 `confirm=true` 会返回 `confirmation_required`。

notion_nilo-0.3.0/Docs/Developer/mcp_tools/comments.md

@@ -0,0 +1,13 @@
+# Comment Tools
+
+- `comment_list`
+  - 说明：按 raw Notion comment query 参数列出 comments。
+  - 必选参数：`params`。
+- `comment_create`
+  - 说明：创建 comment。
+  - 必选参数：`payload`。
+  - 可选参数：`dry_run`。
+- `comment_reply`
+  - 说明：回复 discussion。
+  - 必选参数：`discussion_id`、`rich_text`。
+  - 可选参数：`dry_run`。

notion_nilo-0.3.0/Docs/Developer/mcp_tools/config.md

@@ -0,0 +1,11 @@
+# Config Tools
+
+- `config_status`
+  - 说明：返回本地配置状态、脱敏配置和能力标记。
+  - 必选参数：无。
+  - 返回：`configured`、`config`、`capabilities`。
+- `config_get`
+  - 说明：读取一个配置字段。
+  - 必选参数：`key`。
+  - 可选参数：`show_secret`，默认 `false`。
+  - 安全：`notion_token` 默认返回 `********`。

notion_nilo-0.3.0/Docs/Developer/mcp_tools/custom_emojis.md

@@ -0,0 +1,9 @@
+# Custom Emoji Tools
+
+- `custom_emoji_list`
+  - 说明：列出 integration 可访问的 custom emojis。
+  - 可选参数：`page_size`、`start_cursor`。
+- `custom_emoji_retrieve`
+  - 说明：读取指定 custom emoji。
+  - 必选参数：`custom_emoji_id`。
+  - live 限制：取决于 workspace 是否有 custom emojis 和 API 权限。