@bitefoundry/notion 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 BiteFoundry
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BiteFoundry
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,139 +1,152 @@
1
- <div align="center">
2
-
3
- # `@bitefoundry/notion`
4
-
5
- **Notion-native terminal workspace & AI agent toolkit — Editorial Pages, Interactive Blocks, Databases (Table/Board/List), CLI · TUI · HTTP API · MCP.**
6
-
7
- [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fnotion?style=flat-square&color=191919)](https://www.npmjs.com/package/@bitefoundry/notion)
8
- [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
- [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
10
- [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](package.json)
11
-
12
- <br />
13
-
14
- ![Notion TUI Demo](https://raw.githubusercontent.com/BiteFoundry/notion/master/assets/demo.gif)
15
-
16
- </div>
17
-
18
- ---
19
-
20
- ## Highlights
21
-
22
- | Pillar | Capabilities |
23
- | :--- | :--- |
24
- | **Minimal-Chrome TUI** | Authentic Notion editorial aesthetic (`notion`): 1-line **Breadcrumb Bar**, collapsible **Workspace Sidebar (`[`)** with Favorites & nested tree, **Centered (~88 col) / Full Width (`w`) Page Canvas**, 10 canonical Notion pill colors, live interactive **`to_do` checkboxes (`Space`/`x`)** & **`toggle` blocks**, **Database Table (`1`) / Board Kanban (`2`) / List (`3`) views**, **Comments Peek Drawer (`C`)**, **Quick Find (`Ctrl+K`)**, **Multi-Workspace Switcher (`Ctrl+S`)**, and **5 curated palettes** (`Clean Dark`, `Warm Paper`, `Tokyo Night`, `Catppuccin`, `Nord`). |
25
- | **High-Res Terminal Images** | Native inline image previews for Notion-hosted & external media via **Kitty Graphics**, **iTerm2**, **Sixel**, and **24-bit Truecolor Half-Block (`▀`)** fallback (`v` HD modal & `notion download`). |
26
- | **Local SQLite FTS5 + IPC Daemon** | Workspace-scoped SQLite WAL + FTS5 cache (`pages`, `databases`, `blocks`, `comments`, `pages_fts`) with automatic `<3`-char Korean/CJK `LIKE` fallback, plus single-instance background sync IPC daemon (`notion daemon start`). |
27
- | **4-in-1 Agent Interface** | Same binary powers the **Interactive TUI**, scriptable **`--json` CLI**, local **HTTP JSON API** (`notion serve`, `:8791`), and **stdio MCP server** (`notion mcp`, **19 typed tools** with `confirm: true` archive guard). |
28
-
29
- ---
30
-
31
- ## Quick Start
32
-
33
- Upgrading from 0.1.x? Change `nt` to `notion` in shell scripts and set the MCP server’s `command` to `notion`.
34
-
35
- ```bash
36
- # 1. Install globally (installs the native `notion` command)
37
- npm i -g @bitefoundry/notion
38
-
39
- # 2. Authenticate — Internal Integration Token (30-second setup) or Public OAuth 2.0
40
- notion login --token ntn_...
41
- # Or Public OAuth 2.0 loopback:
42
- notion login --oauth --client-id "$NOTION_CLIENT_ID" --client-secret "$NOTION_CLIENT_SECRET"
43
-
44
- # 3. Sync your workspace & launch the Notion-native TUI
45
- notion sync
46
- notion
47
- ```
48
-
49
- ---
50
-
51
- ## Keybindings Cheat Sheet
52
-
53
- | Key | Action | Context |
54
- | :--- | :--- | :--- |
55
- | `[` / `Ctrl+B` | Toggle collapsible Workspace Sidebar | Global |
56
- | `Tab` / `Shift+Tab` | Cycle focus across Sidebar, Canvas, and Comments Drawer | Global |
57
- | `j` `k` / `↑` `↓` | Move across sidebar tree, page blocks, or database rows | Global |
58
- | `Space` / `x` | Check/uncheck live `to_do` block or expand/collapse `toggle` block | Page Canvas |
59
- | `w` / `f` / `y` | Toggle Centered vs Full Width / Favorite star / Copy code block | Page Canvas |
60
- | `a` / `n` / `e` | Slash Quick Append (`/h1`, `/todo`, `/callout`) / New Page / `$EDITOR` | Page / Database |
61
- | `C` | Toggle right-split Comments Peek Drawer & reply inline | Page Canvas |
62
- | `1` / `2` / `3` | Switch Database views: **Table** / **Board (Kanban)** / **List** | Database |
63
- | `f` / `s` / `m` | Filter rows / Cycle sort / Move Kanban card to another Status column | Database |
64
- | `Ctrl+K` / `Ctrl+P` | Quick Find & Command Palette (FTS5 search + workspace commands) | Global |
65
- | `u` / `Ctrl+F` / `v` | Link Extractor / File Picker (`z` zoxide) / HD Image Preview | Global |
66
- | `Ctrl+S` / `Ctrl+,` / `?` | Switch Workspace / Settings & Palettes / Keyboard Shortcuts Help | Global |
67
-
68
- ---
69
-
70
- ## CLI, HTTP API & MCP
71
-
72
- ### CLI (`--json` ready)
73
-
74
- ```bash
75
- # Search, read, append & export Notion pages
76
- notion search "Q4 Roadmap" --json
77
- notion pages list --json
78
- notion pages get "Q4 Launch Plan"
79
- notion pages get "Q4 Launch Plan" --json --compact
80
- notion pages edit "Q4 Launch Plan" --editor
81
- notion pages append "Q4 Launch Plan" "/todo Tag v1.0 release"
82
- notion pages export "Q4 Launch Plan" --out launch-plan.md
83
- notion blocks edit <block-id> --text "Release **verified**" --json
84
- notion blocks toggle <block-id>
85
-
86
- # Query & create Notion database items
87
- notion db list --json
88
- notion db query "Q4 Roadmap" --json
89
- notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
90
- notion comments add "Q4 Launch Plan" "Green light for launch!"
91
- notion download <url-or-block-id> --json
92
-
93
- # Multi-workspace profiles & background sync daemon
94
- notion workspaces list
95
- notion workspaces add work --token ntn_...
96
- notion workspaces use work
97
- notion daemon start
98
- ```
99
-
100
- ### Local HTTP JSON API (`notion serve`)
101
-
102
- ```bash
103
- notion serve --host 127.0.0.1 --port 8791 --api-key "$API_TOKEN"
104
- curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8791/api/v1/search?q=Roadmap"
105
- ```
106
-
107
- Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
108
-
109
- ### MCP Server (`notion mcp` — 19 Tools)
110
-
111
- ```json
112
- {
113
- "mcpServers": {
114
- "notion": {
115
- "command": "notion",
116
- "args": ["mcp"]
117
- }
118
- }
119
- }
120
- ```
121
-
122
- Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
123
-
124
- ---
125
-
126
- ## `@bitefoundry` Enterprise Terminal Suite
127
-
128
- | Package | Commands | Workspace | Interfaces |
129
- | :--- | :--- | :--- | :--- |
130
- | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
131
- | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
132
- | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
133
- | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `bitefoundry-onedrive` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
134
- | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
135
- | **`@bitefoundry/notion`** | `notion` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
136
-
137
- ---
138
-
139
- > **Disclaimer:** Unofficial terminal client for Notion. Not affiliated with, endorsed by, or sponsored by Notion Labs, Inc.
1
+ <div align="center">
2
+
3
+ # `@bitefoundry/notion`
4
+
5
+ **Read and edit Notion pages, work with database records, and search a synced workspace from the terminal.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fnotion?style=flat-square&color=191919)](https://www.npmjs.com/package/@bitefoundry/notion)
8
+ [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
+ [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](LICENSE)
11
+
12
+ [BiteFoundry](https://bitefoundry.dev/#app-notion) · [Latest release notes](https://github.com/BiteFoundry/notion/releases/latest)
13
+
14
+ <br />
15
+
16
+ ![Notion TUI Demo](https://raw.githubusercontent.com/BiteFoundry/notion/master/assets/demo.gif)
17
+
18
+ </div>
19
+
20
+ ---
21
+
22
+ ## Highlights
23
+
24
+ | Pillar | Capabilities |
25
+ | :--- | :--- |
26
+ | **Minimal-Chrome TUI** | Authentic Notion editorial aesthetic (`notion`): 1-line **Breadcrumb Bar**, collapsible **Workspace Sidebar (`[`)** with Favorites & nested tree, **Centered (~88 col) / Full Width (`w`) Page Canvas**, 10 canonical Notion pill colors, live interactive **`to_do` checkboxes (`Space`/`x`)** & **`toggle` blocks**, **Database Table (`1`) / Board Kanban (`2`) / List (`3`) views**, **Comments Peek Drawer (`C`)**, **Quick Find (`Ctrl+K`)**, **Multi-Workspace Switcher (`Ctrl+S`)**, and **5 curated palettes** (`Clean Dark`, `Warm Paper`, `Tokyo Night`, `Catppuccin`, `Nord`). |
27
+ | **High-Res Terminal Images** | Native inline image previews for Notion-hosted & external media via **Kitty Graphics**, **iTerm2**, **Sixel**, and **24-bit Truecolor Half-Block (`▀`)** fallback (`v` HD modal & `notion download`). |
28
+ | **Local SQLite FTS5 + IPC Daemon** | Workspace-scoped SQLite WAL + FTS5 cache (`pages`, `databases`, `blocks`, `comments`, `pages_fts`) with automatic `<3`-char Korean/CJK `LIKE` fallback, plus single-instance background sync IPC daemon (`notion daemon start`). |
29
+ | **4-in-1 Agent Interface** | Same binary powers the **Interactive TUI**, scriptable **`--json` CLI**, local **HTTP JSON API** (`notion serve`, `:8791`), and **stdio MCP server** (`notion mcp`, **20 typed tools** with `confirm: true` archive guard). |
30
+
31
+ ---
32
+
33
+ ## Quick Start
34
+
35
+ Upgrading from 0.1.x? Change `nt` to `notion` in shell scripts and set the MCP server’s `command` to `notion`.
36
+
37
+ ```bash
38
+ # 1. Install globally (installs the native `notion` command)
39
+ npm i -g @bitefoundry/notion
40
+
41
+ # 2. Authenticate — Internal Integration Token (30-second setup) or Public OAuth 2.0
42
+ notion login --token ntn_...
43
+ # Or Public OAuth 2.0 loopback:
44
+ notion login --oauth --client-id "$NOTION_CLIENT_ID" --client-secret "$NOTION_CLIENT_SECRET"
45
+
46
+ # 3. Sync your workspace & launch the Notion-native TUI
47
+ notion sync
48
+ notion
49
+ ```
50
+
51
+ ```sh
52
+ notion pages get PAGE_ID --json
53
+ ```
54
+
55
+ Read page Markdown and see which blocks or comments were loaded. A compact read skips the comments request. Use `notion comments list PAGE_ID --json` to fetch comments separately. For full detail, add `--full` in the CLI or pass `compact: false` to `get_page` in MCP.
56
+
57
+ ---
58
+
59
+ ## Keybindings Cheat Sheet
60
+
61
+ | Key | Action | Context |
62
+ | :--- | :--- | :--- |
63
+ | `[` / `Ctrl+B` | Toggle collapsible Workspace Sidebar | Global |
64
+ | `Tab` / `Shift+Tab` | Cycle focus across Sidebar, Canvas, and Comments Drawer | Global |
65
+ | `j` `k` / `↑` `↓` | Move across sidebar tree, page blocks, or database rows | Global |
66
+ | `Space` / `x` | Check/uncheck live `to_do` block or expand/collapse `toggle` block | Page Canvas |
67
+ | `w` / `f` / `y` | Toggle Centered vs Full Width / Favorite star / Copy code block | Page Canvas |
68
+ | `a` / `n` / `e` | Slash Quick Append (`/h1`, `/todo`, `/callout`) / New Page / `$EDITOR` | Page / Database |
69
+ | `C` | Toggle right-split Comments Peek Drawer & reply inline | Page Canvas |
70
+ | `1` / `2` / `3` | Switch Database views: **Table** / **Board (Kanban)** / **List** | Database |
71
+ | `f` / `s` / `m` | Filter rows / Cycle sort / Move Kanban card to another Status column | Database |
72
+ | `Ctrl+K` / `Ctrl+P` | Quick Find & Command Palette (FTS5 search + workspace commands) | Global |
73
+ | `u` / `Ctrl+F` / `v` | Link Extractor / File Picker (`z` zoxide) / HD Image Preview | Global |
74
+ | `Ctrl+S` / `Ctrl+,` / `?` | Switch Workspace / Settings & Palettes / Keyboard Shortcuts Help | Global |
75
+
76
+ ---
77
+
78
+ ## CLI, HTTP API & MCP
79
+
80
+ ### CLI (`--json` ready)
81
+
82
+ ```bash
83
+ # Search, read, append & export Notion pages
84
+ notion search "Q4 Roadmap" --json
85
+ notion pages list --json
86
+ notion pages get "Q4 Launch Plan"
87
+ notion pages get "Q4 Launch Plan" --json
88
+ notion pages get "Q4 Launch Plan" --json --full
89
+ notion pages edit "Q4 Launch Plan" --editor
90
+ notion pages append "Q4 Launch Plan" "/todo Tag v1.0 release"
91
+ notion pages export "Q4 Launch Plan" --out launch-plan.md
92
+ notion blocks edit <block-id> --text "Release **verified**" --json
93
+ notion blocks toggle <block-id>
94
+
95
+ # Query & create Notion database items, list workspace users
96
+ notion db list --json
97
+ notion db query "Q4 Roadmap" --json
98
+ notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
99
+ notion users list --json
100
+ notion comments list "Q4 Launch Plan" --json --limit 50 --cursor <next_cursor>
101
+ notion comments add "Q4 Launch Plan" "Green light for launch!"
102
+ notion download <url-or-block-id> --json
103
+
104
+ # Multi-workspace profiles & background sync daemon
105
+ notion workspaces list
106
+ notion workspaces add work --token ntn_...
107
+ notion workspaces use work
108
+ notion daemon start
109
+ ```
110
+
111
+ **Identifier resolution & `--json` exit contract:** UUIDs and Notion URLs pass through directly with zero extra lookups. Read commands accept exact or partial titles (preferring active pages), while write commands require a single exact title match among active pages (use `--unarchive` with a page ID or URL if an archived page is not in the local cache; pass a page ID or URL whenever duplicate or newly-created external titles may exist). Runtime failures under `--json` exit `1` and print `{"ok":false,"error":{"code":"...","message":"..."}}` to stdout (with `details.candidates` for ambiguous/missing titles); argument usage errors exit `2` with stderr usage text and empty stdout. On `--json`, treat exit `0` (and not `ok: false`) as success—some commands omit a top-level `ok` field, and `doctor --online --json` reports probe failures inside `online_probe.ok`.
112
+
113
+ ### Local HTTP JSON API (`notion serve`)
114
+
115
+ ```bash
116
+ notion serve --host 127.0.0.1 --port 8791 --api-key "$API_TOKEN"
117
+ curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8791/api/v1/search?q=Roadmap"
118
+ ```
119
+
120
+ Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
121
+
122
+ ### MCP Server (`notion mcp` — 20 Tools)
123
+
124
+ ```json
125
+ {
126
+ "mcpServers": {
127
+ "notion": {
128
+ "command": "notion",
129
+ "args": ["mcp"]
130
+ }
131
+ }
132
+ }
133
+ ```
134
+
135
+ Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
136
+
137
+ ---
138
+
139
+ ## `@bitefoundry` Enterprise Terminal Suite
140
+
141
+ | Package | Commands | Workspace | Interfaces |
142
+ | :--- | :--- | :--- | :--- |
143
+ | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
144
+ | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
145
+ | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
146
+ | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `bitefoundry-onedrive` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
147
+ | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
148
+ | **`@bitefoundry/notion`** | `notion` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
149
+
150
+ ---
151
+
152
+ > **Disclaimer:** Unofficial terminal client for Notion. Not affiliated with, endorsed by, or sponsored by Notion Labs, Inc.
package/docs/API.md CHANGED
@@ -1,35 +1,37 @@
1
- # `@bitefoundry/notion` Local HTTP API Reference
2
-
3
- Start the local HTTP JSON API server (default `127.0.0.1:8791`):
4
-
5
- ```bash
6
- notion serve --port 8791
7
- # Optional API key protection (required when binding non-loopback hosts):
8
- notion serve --host 0.0.0.0 --port 8791 --api-key "$NOTION_LOCAL_API_KEY"
9
- ```
10
-
11
- When `--api-key` is configured, pass `x-api-key: <key>` or `Authorization: Bearer <key>` on all `/api/v1/*` routes.
12
-
13
- ## Endpoints
14
-
15
- | Method | Path | Description |
16
- |---|---|---|
17
- | `GET` | `/health` | Service health & version (`{ ok, service: "notion-cli", version }`) |
18
- | `GET` | `/api/v1/whoami` | Authenticated Notion bot/user and active workspace metadata |
19
- | `GET` | `/api/v1/workspaces` | List configured Notion workspace profiles |
20
- | `GET` | `/api/v1/search?q=<query>&remote=false&offline=false&limit=30` | Local SQLite FTS5 + Korean `<3` char LIKE search (or remote Notion search) |
21
- | `GET` | `/api/v1/pages?archived=false&refresh=false&offline=false` | List pages in active workspace |
22
- | `POST` | `/api/v1/pages` | Create a new page (`{ parent_id, title, icon?, markdown?, parent_is_database?, properties? }`) |
23
- | `GET` | `/api/v1/pages/{id}?offline=false` | Get full page detail (metadata, properties, block tree, comments, markdown, media refs) |
24
- | `PATCH` | `/api/v1/pages/{id}` | Update page title, icon, properties, or archive/unarchive (`{ title?, icon?, archived?, properties? }`) |
25
- | `GET` | `/api/v1/pages/{id}/blocks?offline=false` | Get a page or block's recursive children. Offline reads return HTTP 404 for an uncached list and HTTP 200 for a verified empty list. |
26
- | `POST` | `/api/v1/pages/{id}/blocks` | Append Markdown or slash-style blocks (`{ markdown }`) |
27
- | `PATCH` | `/api/v1/blocks/{id}` | Update block text or toggle `to_do.checked` (`{ block_type?, text?, checked? }`) |
28
- | `GET` | `/api/v1/databases?refresh=false&offline=false` | List databases & schemas |
29
- | `POST` | `/api/v1/databases/{id}/query` | Query database rows (`{ filter?, sorts?, limit?, offline? }`) |
30
- | `POST` | `/api/v1/databases/{id}/items` | Create a new database item (`{ title, status?, properties?, body? }`) |
31
- | `GET` | `/api/v1/pages/{id}/comments?offline=false` | List page comments |
32
- | `POST` | `/api/v1/pages/{id}/comments` | Add a comment or discussion reply (`{ text, discussion_id? }`) |
33
- | `POST` | `/api/v1/sync` | Synchronize workspace pages & databases into SQLite WAL + FTS5 immediately |
34
-
35
- See [`docs/openapi.yaml`](openapi.yaml) for full schemas.
1
+ # `@bitefoundry/notion` Local HTTP API Reference
2
+
3
+ Start the local HTTP JSON API server (default `127.0.0.1:8791`):
4
+
5
+ ```bash
6
+ notion serve --port 8791
7
+ # Optional API key protection (required when binding non-loopback hosts):
8
+ notion serve --host 0.0.0.0 --port 8791 --api-key "$NOTION_LOCAL_API_KEY"
9
+ ```
10
+
11
+ When `--api-key` is configured, pass `x-api-key: <key>` or `Authorization: Bearer <key>` on all `/api/v1/*` routes.
12
+
13
+ Errors return `{ "ok": false, "error": "..." }` and preserve the upstream Notion API HTTP status code (such as `401`, `403`, `404`, `409`, or `429`) when a request fails upstream.
14
+
15
+ ## Endpoints
16
+
17
+ | Method | Path | Description |
18
+ |---|---|---|
19
+ | `GET` | `/health` | Service health & version (`{ ok, service: "notion-cli", version }`) |
20
+ | `GET` | `/api/v1/whoami` | Authenticated Notion bot/user and active workspace metadata |
21
+ | `GET` | `/api/v1/workspaces` | List configured Notion workspace profiles |
22
+ | `GET` | `/api/v1/search?q=<query>&remote=false&offline=false&limit=30` | Local SQLite FTS5 + Korean `<3` char LIKE search (or remote Notion search) |
23
+ | `GET` | `/api/v1/pages?archived=false&refresh=false&offline=false` | List pages in active workspace |
24
+ | `POST` | `/api/v1/pages` | Create a new page (`{ parent_id, title, icon?, markdown?, parent_is_database?, properties? }`) |
25
+ | `GET` | `/api/v1/pages/{id}?offline=false` | Get full page detail (`detail` includes metadata, properties, block tree, comments, markdown, media refs, `incomplete_blocks`, and `comments_has_more`). Offline reads return HTTP 404 when the page body has not been fetched. |
26
+ | `PATCH` | `/api/v1/pages/{id}` | Update page title, icon, properties, or archive/unarchive (`{ title?, icon?, archived?, properties? }`) |
27
+ | `GET` | `/api/v1/pages/{id}/blocks?offline=false` | Get a page or block's recursive children. Offline reads return HTTP 404 for an uncached list and HTTP 200 for a verified empty list. |
28
+ | `POST` | `/api/v1/pages/{id}/blocks` | Append Markdown or slash-style blocks (`{ markdown }`) |
29
+ | `PATCH` | `/api/v1/blocks/{id}` | Update block text or toggle `to_do.checked` (`{ block_type?, text?, checked? }`) |
30
+ | `GET` | `/api/v1/databases?refresh=false&offline=false` | List databases & schemas |
31
+ | `POST` | `/api/v1/databases/{id}/query` | Query database rows (`{ filter?, sorts?, limit?, offline? }`). Returns HTTP 400 when `offline: true` is combined with `filter` or `sorts`. |
32
+ | `POST` | `/api/v1/databases/{id}/items` | Create a new database item (`{ title, status?, properties?, body? }`) |
33
+ | `GET` | `/api/v1/pages/{id}/comments?offline=false` | List page comments. Offline reads return HTTP 404 when comments have not been fetched or the last fetch failed. |
34
+ | `POST` | `/api/v1/pages/{id}/comments` | Add a comment or discussion reply (`{ text, discussion_id? }`) |
35
+ | `POST` | `/api/v1/sync` | Synchronize workspace pages & databases into SQLite WAL + FTS5 immediately (`{ ok, workspace_id, pages_count, databases_count, fetched_count, complete }`) |
36
+
37
+ See [`docs/openapi.yaml`](openapi.yaml) for full schemas.
package/docs/MCP.md CHANGED
@@ -1,48 +1,120 @@
1
- # `@bitefoundry/notion` MCP Server Reference (19 Tools)
2
-
3
- Run the standalone stdio JSON-RPC 2.0 Model Context Protocol server:
4
-
5
- ```bash
6
- notion mcp
7
- ```
8
-
9
- ### Example MCP Client Configuration
10
-
11
- ```json
12
- {
13
- "mcpServers": {
14
- "notion": {
15
- "command": "notion",
16
- "args": ["mcp"]
17
- }
18
- }
19
- }
20
- ```
21
-
22
- ## Available Tools (19)
23
-
24
- | # | Tool | Required Args | Description |
25
- |---|---|---|---|
26
- | 1 | `whoami` | — | Return the currently authenticated Notion user/bot and active workspace metadata. |
27
- | 2 | `list_workspaces` | — | List all configured Notion workspace profiles and the currently active workspace. |
28
- | 3 | `search_pages` | `query` | Search Notion pages and databases using local SQLite FTS5 (with Korean `<3` char LIKE fallback) or remote Notion Search API. |
29
- | 4 | `get_page` | `page` | Fetch a page with its properties, recursive block tree, Markdown, comments, and media. Pass `compact: true` for just `id`, `title`, `last_edited_time`, and `markdown`. |
30
- | 5 | `get_page_blocks` | `page` | List the recursive block tree for a Notion page or block ID. With `offline: true`, a cache miss is a tool error. A verified empty list returns `{"ok":true,"count":0,"blocks":[]}`. |
31
- | 6 | `create_page` | `parent_id`, `title` | Create a new Notion page under a parent page or database from Markdown content. |
32
- | 7 | `append_blocks` | `page`, `markdown` | Append Markdown or slash-style blocks (`/h1`, `/todo`, `/callout`, `/code`, `/quote`, `/toggle`) to a Notion page or block. |
33
- | 8 | `update_block` | `block_id`, `text` | Edit one block's text using inline Markdown. Include the complete inline text so unchanged spans retain their formatting and mentions. Use `toggle_todo` for checkbox-only changes. |
34
- | 9 | `toggle_todo` | `block_id` | Toggle or explicitly set a Notion `to_do` block's checkbox state. |
35
- | 10 | `archive_page` | `page`, `confirm` | Archive (or unarchive) a Notion page. Destructive archive requires `confirm: true`. |
36
- | 11 | `list_databases` | — | List accessible Notion databases with schemas. |
37
- | 12 | `query_database` | `database` | Query rows of a Notion database with optional Notion API JSON filter and sorts. |
38
- | 13 | `create_database_item` | `database`, `title` | Create a new row page inside a Notion database with title, optional status, custom properties, and Markdown body. |
39
- | 14 | `update_database_item` | `page_id` | Update title, status, or arbitrary properties on a database row. `title` and `status` use the row's property names and types (`status` targets a `status` column and falls back to `select` only when no `status` column exists; pass an explicit column in `properties` to disambiguate multiple columns of the same type without conflicting values). |
40
- | 15 | `list_comments` | `page` | List comments on a Notion page. |
41
- | 16 | `add_comment` | `page`, `text` | Add a comment to a Notion page or reply to an existing discussion thread. |
42
- | 17 | `download_media` | `target` | Download a Notion-hosted or external media URL or image/file/pdf block ID to local disk. |
43
- | 18 | `sync_now` | — | Synchronize Notion workspace pages and databases into the local SQLite WAL + FTS5 cache immediately. |
44
- | 19 | `update_page` | `page`, plus `title` or `icon` | Set a title or emoji icon. Fields you omit keep their current values. Send `null` to clear either field. |
45
-
46
- Full `get_page` replies include `comments_error` when comment retrieval fails. An offline reply may include previously cached comments alongside that error. A successful empty comment list has `comments: []`.
47
-
48
- For `update_page`, `{"page":"Q4 Launch Plan","title":"Q4 Launch Checklist"}` changes the title. `{"page":"Q4 Launch Checklist","icon":null}` removes its icon. A title update reads the page's title property first, including custom title names on database rows. The Notion connection needs read access for that lookup and update access for the patch. [Notion Update page API](https://developers.notion.com/reference/patch-page)
1
+ # `@bitefoundry/notion` MCP Server Reference (20 Tools)
2
+
3
+ Run the standalone stdio JSON-RPC 2.0 Model Context Protocol server:
4
+
5
+ ```bash
6
+ notion mcp
7
+ ```
8
+
9
+ ### Example MCP Client Configuration
10
+
11
+ ```json
12
+ {
13
+ "mcpServers": {
14
+ "notion": {
15
+ "command": "notion",
16
+ "args": ["mcp"]
17
+ }
18
+ }
19
+ }
20
+ ```
21
+
22
+ ## Available Tools (20)
23
+
24
+ | # | Tool | Required Args | Description |
25
+ |---|---|---|---|
26
+ | 1 | `whoami` | — | Return the currently authenticated Notion user/bot and active workspace metadata. |
27
+ | 2 | `list_workspaces` | — | List all configured Notion workspace profiles and the currently active workspace. |
28
+ | 3 | `list_users` | — | List Notion workspace users (`limit` default 50, `cursor`) with `id`, `name`, `user_type`, and `email`. |
29
+ | 4 | `search_pages` | `query` | Search Notion pages and databases using local SQLite FTS5 (with Korean `<3` char LIKE fallback) or remote Notion Search API. |
30
+ | 5 | `get_page` | `page` | Fetch a Notion page. Compact by default (`compact: true`): returns `id`, `title`, `last_edited_time`, `markdown`, `incomplete_blocks`, `comments_state`, `omitted` counts, and a `hint` without requesting `/v1/comments`. Pass `compact: false` for properties, block tree, comments (up to 2,000 + `comments_has_more`), and media. |
31
+ | 6 | `get_page_blocks` | `page` | List the recursive block tree for a Notion page or block ID (`limit` default 50, `cursor`). Offline reads report a cache miss when no children have been fetched. Returns `has_more`, `next_cursor`, and `incomplete_blocks`. |
32
+ | 7 | `create_page` | `parent_id`, `title` | Create a new Notion page under a parent page or database from Markdown content. Automatically chunks bodies over 100 blocks. |
33
+ | 8 | `append_blocks` | `page`, `markdown` | Append Markdown or slash-style blocks (`/h1`, `/todo`, `/callout`, `/code`, `/quote`, `/toggle`) to a Notion page or block. Compact by default (`compact: true`): returns `{ ok, appended, block_ids }`. Pass `compact: false` for full block objects. |
34
+ | 9 | `update_block` | `block_id`, `text` | Edit one block's text using inline Markdown. Include the complete inline text so unchanged spans retain their formatting and mentions. Use `toggle_todo` for checkbox-only changes. |
35
+ | 10 | `toggle_todo` | `block_id` | Toggle or explicitly set a Notion `to_do` block's checkbox state. |
36
+ | 11 | `archive_page` | `page`, `confirm` | Archive (or unarchive) a Notion page. Destructive archive requires `confirm: true`. |
37
+ | 12 | `list_databases` | — | List accessible Notion databases with schemas (`limit` default 50, `cursor`). |
38
+ | 13 | `query_database` | `database` | Query rows of a Notion database with optional Notion API JSON `filter`, `sorts`, `limit` (default 50), and `cursor`. `filter` and `sorts` are rejected when `offline: true`. |
39
+ | 14 | `create_database_item` | `database`, `title` | Create a new row page inside a Notion database with title, optional status, custom properties, and Markdown body. |
40
+ | 15 | `update_database_item` | `page_id` | Update title, status, or arbitrary properties on a database row. `page_id` accepts a row UUID, Notion URL, or exact row title. `title` and `status` use the row's property names and types (`status` targets a `status` column and falls back to `select` only when no `status` column exists; pass an explicit column in `properties` to disambiguate multiple columns of the same type without conflicting values). |
41
+ | 16 | `list_comments` | `page` | List comments on a Notion page (`limit` default 50, `cursor`). With `offline: true`, comments that were never fetched or failed to fetch are a tool error. |
42
+ | 17 | `add_comment` | `page`, `text` | Add a comment to a Notion page or reply to an existing discussion thread. |
43
+ | 18 | `download_media` | `target` | Download a Notion-hosted or external media URL or image/file/pdf block ID to local disk. |
44
+ | 19 | `sync_now` | — | Synchronize Notion workspace pages and databases into the local SQLite WAL + FTS5 cache immediately. Streams every search batch into the cache; returns `fetched_count` and `complete`. |
45
+ | 20 | `update_page` | `page`, plus `title` or `icon` | Set a title or emoji icon. Fields you omit keep their current values. Send `null` to clear either field. |
46
+
47
+ Both compact and full `get_page` replies include `comments_error` when comment retrieval fails. Compact reads never call `/v1/comments`; they report the comment state already known to the local cache (`"cached"`, `"partial"`, `"failed"`, or `"not_fetched"`) without overwriting cached comments or prior errors. Full replies (`compact: false`) fetch comments (up to 2,000 + `comments_has_more`) and may include previously cached comments alongside `comments_error` on an offline read. A successful empty comment list has `comments: []`.
48
+
49
+ Tool text replies (`content[0].text`) carry minified JSON matching `structuredContent`.
50
+
51
+ ### Compact `get_page` Fields
52
+
53
+ | Key | Type | Meaning |
54
+ |---|---|---|
55
+ | `id` | string | Page ID |
56
+ | `title` | string | Page title |
57
+ | `last_edited_time` | string \| null | Last edit timestamp |
58
+ | `markdown` | string | Full rendered Markdown body |
59
+ | `incomplete_blocks` | string[] | Block IDs whose children were not loaded (document order); empty when complete |
60
+ | `comments_state` | string | `"cached"`, `"partial"`, `"failed"`, or `"not_fetched"` |
61
+ | `comments_error` | string (optional) | Present only when `comments_state` is `"failed"` |
62
+ | `omitted.blocks` | integer | Top-level block count omitted from the compact view |
63
+ | `omitted.comments` | integer \| null | Cached comment count when `comments_state` is `"cached"`; `null` otherwise |
64
+ | `omitted.media` | integer | Omitted media reference count |
65
+ | `omitted.fields` | string[] | Omitted `page.*` fields |
66
+ | `hint` | string | Follow-up call to request the full page detail |
67
+
68
+ ### Paginated List Envelope (`get_page_blocks`, `list_comments`, `list_databases`, `query_database`, `list_users`)
69
+
70
+ | Key | Type | Meaning |
71
+ |---|---|---|
72
+ | `ok` | boolean | Always `true` on success |
73
+ | `count` | integer | Number of items in this response |
74
+ | `returned` | integer | Same value as `count` |
75
+ | `blocks` / `comments` / `databases` / `rows` / `users` | array | Page of items |
76
+ | `has_more` | boolean | Whether additional items exist |
77
+ | `next_cursor` | string \| null | Cursor for the next call (`null` when no further cursor can be used) |
78
+ | `hint` | string (optional) | Present on offline partial comment cache exhaustion |
79
+
80
+ ### Examples
81
+
82
+ Compact `get_page` (default):
83
+
84
+ ```json
85
+ {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_page","arguments":{"page":"page-roadmap"}}}
86
+ ```
87
+
88
+ Full `get_page`:
89
+
90
+ ```json
91
+ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_page","arguments":{"page":"page-roadmap","compact":false}}}
92
+ ```
93
+
94
+ Paginated `list_comments`:
95
+
96
+ ```json
97
+ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_comments","arguments":{"page":"page-manycmt","limit":2,"cursor":"cur-2"}}}
98
+ ```
99
+
100
+ Offline `query_database` rejecting `filter`:
101
+
102
+ ```json
103
+ {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"query_database","arguments":{"database":"db-tasks","offline":true,"filter":{"property":"Status","status":{"equals":"Done"}}}}}
104
+ ```
105
+
106
+ For `update_page`, `{"page":"Q4 Launch Plan","title":"Q4 Launch Checklist"}` changes the title. `{"page":"Q4 Launch Checklist","icon":null}` removes its icon. A title update reads the page's title property first, including custom title names on database rows. The Notion connection needs read access for that lookup and update access for the patch. [Notion Update page API](https://developers.notion.com/reference/patch-page)
107
+
108
+ Write tools (`create_page`, `update_page`, `append_blocks`, `archive_page`, `create_database_item`, `update_database_item`, `add_comment`) require a single exact title match among active pages/databases when given a title instead of a UUID or Notion URL. When multiple pages share a title, the tool fails without writing and lists the candidate IDs:
109
+
110
+ ```text
111
+ Error: Title 'Weekly Sync' matches 2 pages. Pass a page ID or URL: 22222222-2222-2222-2222-222222222221 (edited 2026-11-22T12:00:00.000Z), 22222222-2222-2222-2222-222222222222 (edited 2026-11-22T12:05:00.000Z)
112
+ ```
113
+
114
+ ## Known limits
115
+
116
+ - **Block tree depth**: recursive block reads load up to 13 levels (depth cap 12 below the root). Any deeper blocks with unloaded children are reported in `incomplete_blocks` (JSON) and a stderr warning (text), and can be fetched directly with `notion blocks list <block-id>` / `get_page_blocks`.
117
+ - **`relation` and `people` properties**: Notion's page endpoint returns at most 25 entries per property; cached values reflect those entries.
118
+ - **`blocks list` / `get_page_blocks` `count`**: counts top-level blocks in the returned slice, not nested descendants.
119
+ - **Page detail comments**: full page detail JSON serializes at most 2,000 comments (a 2,001st entry is fetched only as lookahead and kept in the local cache) and reports `comments_has_more: true` when more exist. Use `notion comments list <page> --json --cursor ...` or `list_comments` with `cursor` to read the remainder.
120
+ - **Offline database queries**: `--offline` / `offline: true` cannot evaluate Notion `filter` or `sorts` against the local SQLite cache and returns an error instead of silently ignoring them.