@bitefoundry/notion 0.3.0 → 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 -141
- package/docs/API.md +37 -35
- package/docs/MCP.md +120 -113
- package/docs/NPM.md +21 -21
- package/docs/openapi.yaml +185 -185
- package/package.json +50 -50
- package/scripts/postinstall.mjs +266 -266
package/docs/MCP.md
CHANGED
|
@@ -1,113 +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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `omitted.
|
|
63
|
-
| `omitted.
|
|
64
|
-
| `omitted.
|
|
65
|
-
| `
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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.
|
package/docs/NPM.md
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
# `@bitefoundry/notion` 6-Platform npm Distribution
|
|
2
|
-
|
|
3
|
-
`@bitefoundry/notion` distributes prebuilt native Rust binaries via npm `optionalDependencies`, installing the `notion` command with zero Node.js runtime overhead after `postinstall` hardlinking.
|
|
4
|
-
|
|
5
|
-
## Platform Packages
|
|
6
|
-
|
|
7
|
-
| Platform Package | Rust Target | Binary |
|
|
8
|
-
|---|---|---|
|
|
9
|
-
| `@bitefoundry/notion-win32-x64` | `x86_64-pc-windows-msvc` | `bin/notion.exe` |
|
|
10
|
-
| `@bitefoundry/notion-win32-arm64` | `aarch64-pc-windows-msvc` | `bin/notion.exe` |
|
|
11
|
-
| `@bitefoundry/notion-darwin-x64` | `x86_64-apple-darwin` | `bin/notion` |
|
|
12
|
-
| `@bitefoundry/notion-darwin-arm64` | `aarch64-apple-darwin` | `bin/notion` |
|
|
13
|
-
| `@bitefoundry/notion-linux-x64` | `x86_64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
14
|
-
| `@bitefoundry/notion-linux-arm64` | `aarch64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
15
|
-
|
|
16
|
-
## Packaging Scripts
|
|
17
|
-
|
|
18
|
-
- `node scripts/sync-version.mjs --check`: verifies `Cargo.toml`, root `package.json`, and all 6 `npm/notion-*/package.json` manifests match version `0.1.0`.
|
|
19
|
-
- `node scripts/verify-glibc.mjs --self-test`: verifies the GLIBC <= 2.28 ELF symbol checker used in GitHub Actions Linux releases.
|
|
20
|
-
- `node scripts/build-npm.mjs [--target <triple>] [--all]`: stages Cargo release binaries into `npm/notion-*/bin/`.
|
|
21
|
-
- `scripts/postinstall.mjs`: links `notion` directly to the native binary on Unix/Windows while guarding against mutating a git development checkout.
|
|
1
|
+
# `@bitefoundry/notion` 6-Platform npm Distribution
|
|
2
|
+
|
|
3
|
+
`@bitefoundry/notion` distributes prebuilt native Rust binaries via npm `optionalDependencies`, installing the `notion` command with zero Node.js runtime overhead after `postinstall` hardlinking.
|
|
4
|
+
|
|
5
|
+
## Platform Packages
|
|
6
|
+
|
|
7
|
+
| Platform Package | Rust Target | Binary |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `@bitefoundry/notion-win32-x64` | `x86_64-pc-windows-msvc` | `bin/notion.exe` |
|
|
10
|
+
| `@bitefoundry/notion-win32-arm64` | `aarch64-pc-windows-msvc` | `bin/notion.exe` |
|
|
11
|
+
| `@bitefoundry/notion-darwin-x64` | `x86_64-apple-darwin` | `bin/notion` |
|
|
12
|
+
| `@bitefoundry/notion-darwin-arm64` | `aarch64-apple-darwin` | `bin/notion` |
|
|
13
|
+
| `@bitefoundry/notion-linux-x64` | `x86_64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
14
|
+
| `@bitefoundry/notion-linux-arm64` | `aarch64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
15
|
+
|
|
16
|
+
## Packaging Scripts
|
|
17
|
+
|
|
18
|
+
- `node scripts/sync-version.mjs --check`: verifies `Cargo.toml`, root `package.json`, and all 6 `npm/notion-*/package.json` manifests match version `0.1.0`.
|
|
19
|
+
- `node scripts/verify-glibc.mjs --self-test`: verifies the GLIBC <= 2.28 ELF symbol checker used in GitHub Actions Linux releases.
|
|
20
|
+
- `node scripts/build-npm.mjs [--target <triple>] [--all]`: stages Cargo release binaries into `npm/notion-*/bin/`.
|
|
21
|
+
- `scripts/postinstall.mjs`: links `notion` directly to the native binary on Unix/Windows while guarding against mutating a git development checkout.
|