@bitefoundry/notion 0.2.2 → 0.3.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/README.md +3 -1
- package/docs/API.md +4 -4
- package/docs/MCP.md +72 -7
- package/docs/openapi.yaml +15 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -76,7 +76,8 @@ notion
|
|
|
76
76
|
notion search "Q4 Roadmap" --json
|
|
77
77
|
notion pages list --json
|
|
78
78
|
notion pages get "Q4 Launch Plan"
|
|
79
|
-
notion pages get "Q4 Launch Plan" --json
|
|
79
|
+
notion pages get "Q4 Launch Plan" --json
|
|
80
|
+
notion pages get "Q4 Launch Plan" --json --full
|
|
80
81
|
notion pages edit "Q4 Launch Plan" --editor
|
|
81
82
|
notion pages append "Q4 Launch Plan" "/todo Tag v1.0 release"
|
|
82
83
|
notion pages export "Q4 Launch Plan" --out launch-plan.md
|
|
@@ -87,6 +88,7 @@ notion blocks toggle <block-id>
|
|
|
87
88
|
notion db list --json
|
|
88
89
|
notion db query "Q4 Roadmap" --json
|
|
89
90
|
notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
|
|
91
|
+
notion comments list "Q4 Launch Plan" --json --limit 50 --cursor <next_cursor>
|
|
90
92
|
notion comments add "Q4 Launch Plan" "Green light for launch!"
|
|
91
93
|
notion download <url-or-block-id> --json
|
|
92
94
|
|
package/docs/API.md
CHANGED
|
@@ -20,16 +20,16 @@ When `--api-key` is configured, pass `x-api-key: <key>` or `Authorization: Beare
|
|
|
20
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
21
|
| `GET` | `/api/v1/pages?archived=false&refresh=false&offline=false` | List pages in active workspace |
|
|
22
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) |
|
|
23
|
+
| `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. |
|
|
24
24
|
| `PATCH` | `/api/v1/pages/{id}` | Update page title, icon, properties, or archive/unarchive (`{ title?, icon?, archived?, properties? }`) |
|
|
25
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
26
|
| `POST` | `/api/v1/pages/{id}/blocks` | Append Markdown or slash-style blocks (`{ markdown }`) |
|
|
27
27
|
| `PATCH` | `/api/v1/blocks/{id}` | Update block text or toggle `to_do.checked` (`{ block_type?, text?, checked? }`) |
|
|
28
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? }`) |
|
|
29
|
+
| `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`. |
|
|
30
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 |
|
|
31
|
+
| `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. |
|
|
32
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 |
|
|
33
|
+
| `POST` | `/api/v1/sync` | Synchronize workspace pages & databases into SQLite WAL + FTS5 immediately (`{ ok, workspace_id, pages_count, databases_count, fetched_count, complete }`) |
|
|
34
34
|
|
|
35
35
|
See [`docs/openapi.yaml`](openapi.yaml) for full schemas.
|
package/docs/MCP.md
CHANGED
|
@@ -26,23 +26,88 @@ notion mcp
|
|
|
26
26
|
| 1 | `whoami` | — | Return the currently authenticated Notion user/bot and active workspace metadata. |
|
|
27
27
|
| 2 | `list_workspaces` | — | List all configured Notion workspace profiles and the currently active workspace. |
|
|
28
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
|
|
30
|
-
| 5 | `get_page_blocks` | `page` | List the recursive block tree for a Notion page or block ID
|
|
29
|
+
| 4 | `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. |
|
|
30
|
+
| 5 | `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`. |
|
|
31
31
|
| 6 | `create_page` | `parent_id`, `title` | Create a new Notion page under a parent page or database from Markdown content. |
|
|
32
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
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
34
|
| 9 | `toggle_todo` | `block_id` | Toggle or explicitly set a Notion `to_do` block's checkbox state. |
|
|
35
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
|
|
36
|
+
| 11 | `list_databases` | — | List accessible Notion databases with schemas (`limit` default 50, `cursor`). |
|
|
37
|
+
| 12 | `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`. |
|
|
38
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
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. |
|
|
40
|
+
| 15 | `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. |
|
|
41
41
|
| 16 | `add_comment` | `page`, `text` | Add a comment to a Notion page or reply to an existing discussion thread. |
|
|
42
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. |
|
|
43
|
+
| 18 | `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`. |
|
|
44
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
45
|
|
|
46
|
-
|
|
46
|
+
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: []`.
|
|
47
|
+
|
|
48
|
+
Tool text replies (`content[0].text`) carry minified JSON matching `structuredContent`.
|
|
49
|
+
|
|
50
|
+
### Compact `get_page` Fields
|
|
51
|
+
|
|
52
|
+
| Key | Type | Meaning |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| `id` | string | Page ID |
|
|
55
|
+
| `title` | string | Page title |
|
|
56
|
+
| `last_edited_time` | string \| null | Last edit timestamp |
|
|
57
|
+
| `markdown` | string | Full rendered Markdown body |
|
|
58
|
+
| `incomplete_blocks` | string[] | Block IDs whose children were not loaded (document order); empty when complete |
|
|
59
|
+
| `comments_state` | string | `"cached"`, `"partial"`, `"failed"`, or `"not_fetched"` |
|
|
60
|
+
| `comments_error` | string (optional) | Present only when `comments_state` is `"failed"` |
|
|
61
|
+
| `omitted.blocks` | integer | Top-level block count omitted from the compact view |
|
|
62
|
+
| `omitted.comments` | integer \| null | Cached comment count when `comments_state` is `"cached"`; `null` otherwise |
|
|
63
|
+
| `omitted.media` | integer | Omitted media reference count |
|
|
64
|
+
| `omitted.fields` | string[] | Omitted `page.*` fields |
|
|
65
|
+
| `hint` | string | Follow-up call to request the full page detail |
|
|
66
|
+
|
|
67
|
+
### Paginated List Envelope (`get_page_blocks`, `list_comments`, `list_databases`, `query_database`)
|
|
68
|
+
|
|
69
|
+
| Key | Type | Meaning |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| `ok` | boolean | Always `true` on success |
|
|
72
|
+
| `count` | integer | Number of items in this response |
|
|
73
|
+
| `returned` | integer | Same value as `count` |
|
|
74
|
+
| `blocks` / `comments` / `databases` / `rows` | array | Page of items |
|
|
75
|
+
| `has_more` | boolean | Whether additional items exist |
|
|
76
|
+
| `next_cursor` | string \| null | Cursor for the next call (`null` when no further cursor can be used) |
|
|
77
|
+
| `hint` | string (optional) | Present on offline partial comment cache exhaustion |
|
|
78
|
+
|
|
79
|
+
### Examples
|
|
80
|
+
|
|
81
|
+
Compact `get_page` (default):
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_page","arguments":{"page":"page-roadmap"}}}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Full `get_page`:
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_page","arguments":{"page":"page-roadmap","compact":false}}}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Paginated `list_comments`:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_comments","arguments":{"page":"page-manycmt","limit":2,"cursor":"cur-2"}}}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Offline `query_database` rejecting `filter`:
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"query_database","arguments":{"database":"db-tasks","offline":true,"filter":{"property":"Status","status":{"equals":"Done"}}}}}
|
|
103
|
+
```
|
|
47
104
|
|
|
48
105
|
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)
|
|
106
|
+
|
|
107
|
+
## Known limits
|
|
108
|
+
|
|
109
|
+
- **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`.
|
|
110
|
+
- **`relation` and `people` properties**: Notion's page endpoint returns at most 25 entries per property; cached values reflect those entries.
|
|
111
|
+
- **`blocks list` / `get_page_blocks` `count`**: counts top-level blocks in the returned slice, not nested descendants.
|
|
112
|
+
- **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.
|
|
113
|
+
- **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.
|
package/docs/openapi.yaml
CHANGED
|
@@ -57,15 +57,21 @@ paths:
|
|
|
57
57
|
description: Created page
|
|
58
58
|
/api/v1/pages/{id}:
|
|
59
59
|
get:
|
|
60
|
-
summary: Get full Notion page detail (metadata, blocks, comments, markdown, media)
|
|
60
|
+
summary: Get full Notion page detail (metadata, blocks, comments, markdown, media, incomplete_blocks, comments_has_more)
|
|
61
61
|
parameters:
|
|
62
62
|
- name: id
|
|
63
63
|
in: path
|
|
64
64
|
required: true
|
|
65
65
|
schema: { type: string }
|
|
66
|
+
- name: offline
|
|
67
|
+
in: query
|
|
68
|
+
schema: { type: boolean, default: false }
|
|
69
|
+
description: Read only from the local offline cache.
|
|
66
70
|
responses:
|
|
67
71
|
"200":
|
|
68
72
|
description: Page detail
|
|
73
|
+
"404":
|
|
74
|
+
description: Page not found or page body unavailable in the offline cache
|
|
69
75
|
patch:
|
|
70
76
|
summary: Update page metadata, properties, or archive state
|
|
71
77
|
parameters:
|
|
@@ -131,6 +137,8 @@ paths:
|
|
|
131
137
|
responses:
|
|
132
138
|
"200":
|
|
133
139
|
description: Database rows
|
|
140
|
+
"400":
|
|
141
|
+
description: Invalid offline query (filter or sorts combined with offline=true) or invalid limit
|
|
134
142
|
/api/v1/databases/{id}/items:
|
|
135
143
|
post:
|
|
136
144
|
summary: Create a new database item row
|
|
@@ -150,9 +158,15 @@ paths:
|
|
|
150
158
|
in: path
|
|
151
159
|
required: true
|
|
152
160
|
schema: { type: string }
|
|
161
|
+
- name: offline
|
|
162
|
+
in: query
|
|
163
|
+
schema: { type: boolean, default: false }
|
|
164
|
+
description: Read only from the local offline cache.
|
|
153
165
|
responses:
|
|
154
166
|
"200":
|
|
155
167
|
description: Comments list
|
|
168
|
+
"404":
|
|
169
|
+
description: Page not found or comments unavailable in the offline cache
|
|
156
170
|
post:
|
|
157
171
|
summary: Add a comment or discussion reply
|
|
158
172
|
parameters:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bitefoundry/notion",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Notion terminal client & AI agent toolkit — Pages, Blocks, Databases (Table/Board/List), Comments & Multi-Workspace (CLI, TUI, HTTP API, MCP)",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -40,11 +40,11 @@
|
|
|
40
40
|
"build:npm": "node scripts/build-npm.mjs"
|
|
41
41
|
},
|
|
42
42
|
"optionalDependencies": {
|
|
43
|
-
"@bitefoundry/notion-win32-x64": "0.
|
|
44
|
-
"@bitefoundry/notion-win32-arm64": "0.
|
|
45
|
-
"@bitefoundry/notion-darwin-x64": "0.
|
|
46
|
-
"@bitefoundry/notion-darwin-arm64": "0.
|
|
47
|
-
"@bitefoundry/notion-linux-x64": "0.
|
|
48
|
-
"@bitefoundry/notion-linux-arm64": "0.
|
|
43
|
+
"@bitefoundry/notion-win32-x64": "0.3.0",
|
|
44
|
+
"@bitefoundry/notion-win32-arm64": "0.3.0",
|
|
45
|
+
"@bitefoundry/notion-darwin-x64": "0.3.0",
|
|
46
|
+
"@bitefoundry/notion-darwin-arm64": "0.3.0",
|
|
47
|
+
"@bitefoundry/notion-linux-x64": "0.3.0",
|
|
48
|
+
"@bitefoundry/notion-linux-arm64": "0.3.0"
|
|
49
49
|
}
|
|
50
50
|
}
|