@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 +21 -21
- package/README.md +152 -139
- package/docs/API.md +37 -35
- package/docs/MCP.md +120 -48
- package/docs/NPM.md +21 -21
- package/docs/openapi.yaml +185 -171
- package/package.json +50 -50
- package/scripts/postinstall.mjs +266 -266
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
|
-
**
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/@bitefoundry/notion)
|
|
8
|
-
[](docs/NPM.md)
|
|
9
|
-
[](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
|
|
10
|
-
[](
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
| **
|
|
27
|
-
| **
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
#
|
|
42
|
-
notion login --
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
notion
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
notion
|
|
88
|
-
notion
|
|
89
|
-
notion
|
|
90
|
-
notion
|
|
91
|
-
notion
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
notion
|
|
97
|
-
notion
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
---
|
|
138
|
-
|
|
139
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/@bitefoundry/notion)
|
|
8
|
+
[](docs/NPM.md)
|
|
9
|
+
[](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
|
|
12
|
+
[BiteFoundry](https://bitefoundry.dev/#app-notion) · [Latest release notes](https://github.com/BiteFoundry/notion/releases/latest)
|
|
13
|
+
|
|
14
|
+
<br />
|
|
15
|
+
|
|
16
|
+

|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
|
18
|
-
|
|
19
|
-
| `GET` | `/
|
|
20
|
-
| `GET` | `/api/v1/
|
|
21
|
-
| `GET` | `/api/v1/
|
|
22
|
-
| `
|
|
23
|
-
| `GET` | `/api/v1/pages
|
|
24
|
-
| `
|
|
25
|
-
| `GET` | `/api/v1/pages/{id}
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
| `
|
|
30
|
-
| `
|
|
31
|
-
| `
|
|
32
|
-
| `POST` | `/api/v1/
|
|
33
|
-
| `
|
|
34
|
-
|
|
35
|
-
|
|
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 (
|
|
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 (
|
|
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 | `
|
|
29
|
-
| 4 | `
|
|
30
|
-
| 5 | `
|
|
31
|
-
| 6 | `
|
|
32
|
-
| 7 | `
|
|
33
|
-
| 8 | `
|
|
34
|
-
| 9 | `
|
|
35
|
-
| 10 | `
|
|
36
|
-
| 11 | `
|
|
37
|
-
| 12 | `
|
|
38
|
-
| 13 | `
|
|
39
|
-
| 14 | `
|
|
40
|
-
| 15 | `
|
|
41
|
-
| 16 | `
|
|
42
|
-
| 17 | `
|
|
43
|
-
| 18 | `
|
|
44
|
-
| 19 | `
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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.
|