@deepseek-ai/dsh-notion 0.0.0-stage → 0.2.3-alpha.1

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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DeepSeek
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.
@@ -0,0 +1,73 @@
1
+ # Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
2
+ # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
3
+ # After editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/connector/notion/README.md
5
+ /:
6
+ en: 0aa30500a6748dff
7
+ zh: ecfb242e80df586f
8
+ /deepseek-ai-dsh-notion:
9
+ en: ebcdb43f309b330c
10
+ zh: 364385eb8bbf6171
11
+ /deepseek-ai-dsh-notion/summary:
12
+ en: 05703b12e01e8b04
13
+ zh: 9dff7eb9cfbeae68
14
+ /deepseek-ai-dsh-notion/table-of-contents:
15
+ en: d152484eb41ac6b4
16
+ zh: 09388d293f9be9cb
17
+ /deepseek-ai-dsh-notion/use-this-package:
18
+ en: bbff250eba0f1b89
19
+ zh: 0a618f05cc88ee2b
20
+ /deepseek-ai-dsh-notion/use-this-package/install-into-a-profile:
21
+ en: 917f72b8c57fa68a
22
+ zh: d2e5a6d4337c6048
23
+ /deepseek-ai-dsh-notion/use-this-package/authorize-and-sign-out:
24
+ en: 2b77a82c90e41194
25
+ zh: ab7d72148ead15d3
26
+ /deepseek-ai-dsh-notion/use-this-package/turn-off-and-uninstall:
27
+ en: 8fb8e3a36288a635
28
+ zh: 3ba01fe30e802d1f
29
+ /deepseek-ai-dsh-notion/use-this-package/configure:
30
+ en: 74b045a61a3fec72
31
+ zh: 69d64b33e8d1812e
32
+ /deepseek-ai-dsh-notion/understand-the-implementation:
33
+ en: 5a12bb3e000c4cc9
34
+ zh: 6431dcb502c1d7af
35
+ /deepseek-ai-dsh-notion/further-exploration:
36
+ en: ed7d1edadf2feef5
37
+ zh: 6746823e51e4f4f3
38
+ /deepseek-ai-dsh-notion/model-experience:
39
+ en: 215e7ba838619b7b
40
+ zh: a311da3843709f90
41
+ /deepseek-ai-dsh-notion/model-experience/naming-and-connection-guidance:
42
+ en: 01b6ec6d681e457b
43
+ zh: 7fe0d1c9d1037bd4
44
+ /deepseek-ai-dsh-notion/model-experience/naming-and-connection-guidance/what-the-model-sees:
45
+ en: a62a8dbe1f7b7944
46
+ zh: 32a94fa68d8b30c2
47
+ /deepseek-ai-dsh-notion/model-experience/naming-and-connection-guidance/what-the-model-sees/guidance-text:
48
+ en: 8f57292f6821da96
49
+ zh: b2d3bc7e5c9cbc05
50
+ /deepseek-ai-dsh-notion/model-experience/naming-and-connection-guidance/token-effect:
51
+ en: 263969c79903e387
52
+ zh: d45f9e49d9a252c3
53
+ /deepseek-ai-dsh-notion/model-experience/naming-and-connection-guidance/kv-cache-effect:
54
+ en: e9668826c9355444
55
+ zh: 66f609e3779fd510
56
+ /deepseek-ai-dsh-notion/model-experience/notion-server-tools-and-instructions:
57
+ en: ae0fe892d237cd8d
58
+ zh: bfd6c55b83ff9f8c
59
+ /deepseek-ai-dsh-notion/model-experience/notion-server-tools-and-instructions/what-the-model-sees:
60
+ en: 1acff8ce3a0dbdc4
61
+ zh: f392c0dfc07c8b2c
62
+ /deepseek-ai-dsh-notion/model-experience/notion-server-tools-and-instructions/token-effect:
63
+ en: ea047c321d077856
64
+ zh: d50bd0a0579c0a6c
65
+ /deepseek-ai-dsh-notion/model-experience/notion-server-tools-and-instructions/kv-cache-effect:
66
+ en: 5bed63237f352122
67
+ zh: a82a734d98bf1ba7
68
+ /deepseek-ai-dsh-notion/known-limitations-and-deferred-work:
69
+ en: 9f145e50fb31de42
70
+ zh: fdc6da981ae79456
71
+ /deepseek-ai-dsh-notion/known-limitations-and-deferred-work/dev-note:
72
+ en: be76e387a7ea3a71
73
+ zh: d53904834ac3525c
package/README.md CHANGED
@@ -1,3 +1,155 @@
1
- # Temporary Holding Version
1
+ ---
2
+ description: "Connect Notion's hosted MCP server through the shared MCP manager, authorize it with OAuth, and use its tools in conversations."
3
+ kind: "package-bundle"
4
+ ---
2
5
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
6
+ # @deepseek-ai/dsh-notion
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ The Notion plugin registers Notion's hosted MCP server, `https://mcp.notion.com/mcp`, with the Host's shared [MCP manager](../../mcp/mcp-manager/README.md) for as long as the plugin is loaded. The user connects a Notion account from the plugin's page on the Web sidebar's **Plugins** page; afterwards every conversation on that Host can use the server's tools, and the model is told to call the integration the Notion plugin. The manager owns the connection, OAuth authorization, the saved grant, and sign-out, which the shared [MCP account service](../../mcp/mcp-account/README.md) shows on the Plugins page. It runs in the Web and Desktop compositions.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
27
+
28
+ ### Install into a profile
29
+
30
+ Install the package as a bundle, for example from the Web sidebar's **Plugins** page or with the CLI:
31
+
32
+ ```sh
33
+ dsh plugin --profile web add @deepseek-ai/dsh-notion
34
+ ```
35
+
36
+ The bundle patch inserts the `notion` row after the profile's other layers. The plugin requires the `mcpManager` and `systemPrompt` services, which the Web and Desktop compositions provide through [`dsh-web-app`](../../bundle/web-app/README.md). In a profile without the MCP manager, such as `headless`, the plugin does not activate, and startup prints a warning that names the missing `mcpManager` service.
37
+
38
+ ### Authorize and sign out
39
+
40
+ The plugin registers the server `notion` with the fixed OAuth credential key `mcp-client/notion`. Without a saved grant the server waits for authorization and exposes no Notion tools. With a saved grant the manager connects at startup and refreshes tokens as needed. Notion's tools load [on demand](../../mcp/mcp-client/README.md#on-demand-tool-loading) by default: the system prompt lists them, and each agent loads the ones it needs with `mcp__notion__load_tools`.
41
+
42
+ While the plugin is on, its page on the **Plugins** page shows a **Notion account** section, and a tag beside the title reads Not connected, Connecting, Connected, Reconnect, or Unavailable. Switching the plugin on from the list while no account is connected offers **Connect Notion**, which opens the plugin's page and starts authorization.
43
+
44
+ | Section state | Action |
45
+ |---|---|
46
+ | Not connected, or the grant expired, no longer matches the settings, was rejected, or lacks permissions | **Connect Notion** or **Connect again** starts an authorization attempt |
47
+ | Waiting for you to confirm in the browser | The browser that started the attempt opens Notion's authorization page once; **Open authorization page** opens it again, and **Cancel** ends the attempt |
48
+ | Connected | **Sign out** asks for confirmation, then deletes the local grant |
49
+ | Cannot connect right now | **Retry** restarts the server and keeps the existing grant |
50
+
51
+ Authorization must be completed in a browser on the Host machine. After the user approves access in Notion, the callback page says DSH received the authorization; the section then shows the result. Leaving the page does not cancel an attempt, which the Host owns. A failed attempt shows **Authorization was not completed. Try again.**; a failed page action shows a toast. Sign-out keeps the client registration and does not revoke the connection on Notion's side.
52
+
53
+ The page follows the account through the [`connectorAccounts` Remote](../../client/ui-connector-account/README.md) under the key `mcp:notion`, and its buttons start `connect`, `sign-out`, or `retry` or cancel the attempt there. On the Host, [`dsh-mcp-account`](../../mcp/mcp-account/README.md) runs them through the manager's [OAuth operations](../../mcp/mcp-manager/README.md#oauth-authorization): `startAuthorization('notion')` returns an attempt whose `authorizationUrl` the stream reports, `cancelAuthorization('notion', id)` cancels it, `signOut('notion')` deletes the grant, and `restart('notion')` retries. Other Remote clients can use the same operations.
54
+
55
+ ### Turn off and uninstall
56
+
57
+ Turning the row off in Plugin Manager, or uninstalling the package, ends the registration: the Notion tools leave the model's tool set, and the saved grant stays in the credentials store, so reinstalling reuses it. To remove the grant, sign out while the plugin is loaded, or delete the `mcp-client/notion` record from `$DSH_HOME/.credentials.yaml` as the [local credentials provider](../../credentials/credentials-local/README.md) documents.
58
+
59
+ ### Configure
60
+
61
+ | Field | Default | Meaning |
62
+ |---|---|---|
63
+ | `url` | `https://mcp.notion.com/mcp` | Streamable HTTP MCP endpoint of the Notion server |
64
+ | `toolLoading` | `on-demand` | `on-demand` keeps Notion's tools hidden from each agent until it loads them; `eager` sends every tool definition with every request |
65
+
66
+ The generated [config catalog](../../../docs/config-catalog.md#deepseek-aidsh-notion) is the exhaustive source of supported fields. Connection and authorization budgets use the manager and mcp-client defaults. The saved grant is bound to `url`; changing it requires connecting the account again.
67
+
68
+ -----
69
+
70
+ <a id="understand-the-implementation"></a>
71
+ ## Understand the implementation
72
+
73
+ <details>
74
+ <summary>Implementation internals — click to expand</summary>
75
+
76
+ [`cordis.patch.yml`](cordis.patch.yml) inserts one row with id `notion` naming this package, so the package is both the bundle and its only row; `config` overrides target that id. The Host half, [`src/index.ts`](src/index.ts), makes two registrations, both effects of the plugin's fiber: `ctx.mcpManager.register('notion', …)` adds a Streamable HTTP entry with the configured `url` and OAuth credential key, and `ctx.systemPrompt.section()` adds the naming guidance at the `MCP_SERVERS` order. The server name fixes the `mcp__notion__` tool namespace, and the credential key fixes the grant address, so a reloaded or reinstalled plugin reaches the same tools and grant. The manager validates the entry when it is registered; a configured or registered server that already uses the name or key makes the plugin fail to load before the guidance is added.
77
+
78
+ While the account registry runs, the plugin also calls `ctx.mcpAccounts.register({ server: 'notion', packageName: '@deepseek-ai/dsh-notion', copy })`, where [`src/locales.ts`](src/locales.ts) holds the text that names Notion in every shipped language; [`dsh-mcp-account`](../../mcp/mcp-account/README.md) then registers the account with the connector account registry, which renders the section, guidance, tag, and toast described above. A composition without the registry, such as a headless profile, loads the plugin without the account section.
79
+
80
+ </details>
81
+
82
+ -----
83
+
84
+ <a id="further-exploration"></a>
85
+ ## Further Exploration
86
+
87
+ - [Connector packages](../README.md) — the group this application plugin belongs to.
88
+ - [MCP manager](../../mcp/mcp-manager/README.md) — registration lifetime, status, OAuth authorization, and sign-out.
89
+ - [MCP client](../../mcp/mcp-client/README.md) — connection, tool naming, OAuth grant refresh, and redaction.
90
+ - [MCP subsystem](../../../docs/subsystems/mcp.md) — how the MCP packages fit together.
91
+ - [Plugin Manager](../../boot/plugin-manager/README.md) — installation and enablement.
92
+ - [MCP account service](../../mcp/mcp-account/README.md) — how the manager's status and authorization map to the account section.
93
+ - [Connector account surfaces](../../client/ui-connector-account/README.md) — the section, tag, guidance, and notices the account registration shows.
94
+ - [Plugins page](../../client/ui-plugin-manager/README.md#use-this-package) — the bundle page those surfaces occupy.
95
+
96
+ -----
97
+
98
+ <a id="model-experience"></a>
99
+ ## Model Experience
100
+
101
+ ### Naming and connection guidance
102
+
103
+ #### What the model sees
104
+
105
+ While the plugin is loaded, the system prompt contains the text below after the MCP server sections, whether or not Notion is authorized.
106
+
107
+ ##### Guidance text
108
+
109
+ ```markdown
110
+ Tools named `mcp__notion__*` come from the Notion plugin. In user-facing replies, call it the Notion plugin (Notion 插件 in Chinese), not MCP. If no `mcp__notion__*` tool appears in your tool list, Notion is not connected yet; ask the user to connect it on the Notion plugin page in Plugins.
111
+ ```
112
+
113
+ #### Token effect
114
+
115
+ The two fixed sentences add about 70 tokens to every request while the plugin is loaded.
116
+
117
+ #### KV Cache effect
118
+
119
+ The sentence is prefix-stable: it changes only when the plugin loads or unloads, not when authorization or the connection changes.
120
+
121
+ ### Notion server tools and instructions
122
+
123
+ #### What the model sees
124
+
125
+ After authorization, the model sees Notion's server instructions under `### MCP server: notion` and, with the default `toolLoading: on-demand`, the loader `mcp__notion__load_tools` and a [catalog of Notion's tools](../../mcp/mcp-client/README.md#model-experience) in the system prompt; each tool it loads then appears as `mcp__notion__<tool>` with Notion's description and input schema. With `eager`, every tool appears from the start, as the [MCP client](../../mcp/mcp-client/README.md#model-experience) documents. With `on-demand`, the loader and the catalog appear only once Notion is connected. While the plugin is loaded, including before authorization, the [shared resource tools](../../mcp/mcp-resources/README.md#model-experience) and their server-name prompt list `notion`.
126
+
127
+ #### Token effect
128
+
129
+ Notion's server defines the tool set and instructions, and their size can change without a DSH update. With `on-demand`, a connected Notion costs its instructions, the loader, and a catalog of about 6,400 characters for its 46 tools, plus the definitions an agent has loaded; with `eager`, all definitions, about 214,500 characters, repeat on every request.
130
+
131
+ #### KV Cache effect
132
+
133
+ Notion's instructions (or, with `eager`, its tools) appear when the connection succeeds and disappear when authorization is withdrawn or the plugin unloads; each change can invalidate reuse from the first changed token. With `on-demand`, the catalog changes only when Notion's tool list does, and each load changes the agent's next tool list, as the [MCP client](../../mcp/mcp-client/README.md#model-experience) documents. The shared resource tools stay unchanged across connection changes.
134
+
135
+ ## Known Limitations and Deferred Work
136
+
137
+ <a id="known-limitations-and-deferred-work"></a>
138
+
139
+ - The Notion account section exists only while the plugin is on. To sign out after turning the plugin off, turn it on again or delete the grant record.
140
+ - Only the Web and Desktop compositions mount the MCP manager; other profiles leave the plugin inactive.
141
+ - The authorization callback is `http://127.0.0.1:<port>` on the Host, so the browser that completes authorization must run on the Host machine. A Web Host reached from another machine cannot finish authorization.
142
+ - Desktop listens on an OS-assigned port for each launch. Authorizing again after a restart registers a new OAuth client and keeps the earlier registration record; saved grants refresh normally across restarts.
143
+ - Before the account is connected, the shared resource prompt still lists `notion` as a server name, and resource calls to it fail until the user connects.
144
+ - One Notion authorization serves the whole Host; there is no account or workspace picker.
145
+ - Turning the plugin off or uninstalling it keeps the local grant. Signing out deletes the local grant but leaves the connection authorized on Notion's side until the user removes it there.
146
+
147
+ <a id="dev-note"></a>
148
+ ### Dev Note
149
+
150
+ <details>
151
+ <summary>Working context for maintainers — click to expand</summary>
152
+
153
+ Host specs run the plugin against the MCP manager and the mcp-client loopback OAuth server fixture; another checks that the account registry serves the Notion account with its text and withdraws it with the plugin. The `notion-plugin` session snapshot replays the Notion row without a saved grant, so it pins the naming guidance and verifies that no request reaches the server.
154
+
155
+ </details>
package/README.zh.md ADDED
@@ -0,0 +1,155 @@
1
+ ---
2
+ description: "通过共用的 MCP 管理器接入 Notion 托管的 MCP 服务器,经 OAuth 授权后在对话中使用其工具。"
3
+ kind: "package-bundle"
4
+ ---
5
+
6
+ # @deepseek-ai/dsh-notion
7
+
8
+ [English](README.md) | 中文
9
+
10
+ ## 概述
11
+
12
+ Notion 插件在加载期间把 Notion 托管的 MCP 服务器 `https://mcp.notion.com/mcp` 注册到 Host 共用的 [MCP 管理器](../../mcp/mcp-manager/README.zh.md)。用户在 Web 侧栏**插件**页面的插件详情页中连接 Notion 账号,之后该 Host 上的所有对话都能使用这个服务器的工具,模型也会被告知把这项集成称为 Notion 插件。连接、OAuth 授权、已保存的 grant 和退出登录都由管理器负责,并由共用的 [MCP 账号服务](../../mcp/mcp-account/README.zh.md)显示在插件页面上。插件运行在 Web 与 Desktop 组合中。
13
+
14
+ ## 目录
15
+
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
27
+
28
+ ### 安装到 profile
29
+
30
+ 将本包作为 bundle 安装,例如在 Web 侧栏的**插件**页面安装,或使用 CLI:
31
+
32
+ ```sh
33
+ dsh plugin --profile web add @deepseek-ai/dsh-notion
34
+ ```
35
+
36
+ bundle patch 在 profile 其他层之后插入 `notion` 行。插件需要 `mcpManager` 与 `systemPrompt` 服务,Web 与 Desktop 组合通过 [`dsh-web-app`](../../bundle/web-app/README.zh.md) 提供它们。在没有 MCP 管理器的 profile(例如 `headless`)中,插件不会激活,启动时会打印一条警告,指出缺少 `mcpManager` 服务。
37
+
38
+ ### 授权与退出登录
39
+
40
+ 插件以固定的 OAuth 凭据 key `mcp-client/notion` 注册服务器 `notion`。没有已保存的 grant 时,服务器等待授权,不提供 Notion 工具。有已保存的 grant 时,管理器在启动时连接,并按需刷新 token。Notion 的工具默认[按需加载](../../mcp/mcp-client/README.zh.md#on-demand-tool-loading):系统提示词列出这些工具,每个 agent 用 `mcp__notion__load_tools` 加载需要的工具。
41
+
42
+ 插件开启期间,它在**插件**页面的详情页显示 **Notion 账号**区块,标题旁的标签显示未连接、连接中、已连接、需要重新连接或暂时无法连接。在列表中开启插件而尚未连接账号时,页面提示**连接 Notion**,点击后打开插件详情页并发起授权。
43
+
44
+ | 区块状态 | 操作 |
45
+ |---|---|
46
+ | 未连接,或授权已过期、与当前设置不再匹配、被拒绝、缺少权限 | **连接 Notion** 或**重新连接**发起一次授权尝试 |
47
+ | 等待你在浏览器中确认 | 发起尝试的浏览器打开一次 Notion 授权页面;**打开授权页面**再次打开,**取消**结束这次尝试 |
48
+ | 已连接 | **退出登录**确认后删除本地 grant |
49
+ | 暂时无法连接 | **重试**重启服务器并保留现有授权 |
50
+
51
+ 授权必须在 Host 所在机器的浏览器中完成。用户在 Notion 中同意授权后,回调页面说明 DSH 已收到授权,区块随后显示结果。离开页面不会取消授权尝试,尝试由 Host 持有。授权失败时显示**授权未完成,请重试**;页面操作失败时显示 toast。退出登录保留客户端注册,不会在 Notion 一侧撤销连接。
52
+
53
+ 页面通过 [`connectorAccounts` Remote](../../client/ui-connector-account/README.zh.md) 以 key `mcp:notion` 跟随账号,其按钮在该 Remote 上发起 `connect`、`sign-out` 或 `retry`,或取消授权尝试。在 Host 上,[`dsh-mcp-account`](../../mcp/mcp-account/README.zh.md) 通过管理器的 [OAuth 操作](../../mcp/mcp-manager/README.zh.md#oauth-authorization)执行它们:`startAuthorization('notion')` 返回一次授权尝试,其 `authorizationUrl` 由流报告,`cancelAuthorization('notion', id)` 取消它,`signOut('notion')` 删除 grant,`restart('notion')` 重试。其他 Remote 客户端可以使用同样的操作。
54
+
55
+ ### 停用与卸载
56
+
57
+ 在 Plugin Manager 中关闭该行或卸载本包都会结束注册:Notion 工具从模型的工具集中撤下,已保存的 grant 留在凭据存储中,因此重新安装会复用它。要删除 grant,请在插件加载期间退出登录,或按[本地凭据提供方](../../credentials/credentials-local/README.zh.md)的说明,从 `$DSH_HOME/.credentials.yaml` 中删除 `mcp-client/notion` 记录。
58
+
59
+ ### 配置
60
+
61
+ | 字段 | 默认值 | 含义 |
62
+ |---|---|---|
63
+ | `url` | `https://mcp.notion.com/mcp` | Notion 服务器的 Streamable HTTP MCP 端点 |
64
+ | `toolLoading` | `on-demand` | `on-demand` 让 Notion 的工具在 agent 加载前对其隐藏;`eager` 在每次请求中发送全部工具定义 |
65
+
66
+ 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-notion)是受支持字段的完整来源。连接与授权的预算使用管理器和 mcp-client 的默认值。已保存的 grant 与 `url` 绑定,修改后需要重新连接账号。
67
+
68
+ -----
69
+
70
+ <a id="understand-the-implementation"></a>
71
+ ## 理解实现
72
+
73
+ <details>
74
+ <summary>实现内部机制——点击展开</summary>
75
+
76
+ [`cordis.patch.yml`](cordis.patch.yml) 插入一行 id 为 `notion` 的条目,指向本包,因此本包既是 bundle,也是其唯一的一行;`config` 覆盖以该 id 为目标。Host 侧的 [`src/index.ts`](src/index.ts) 进行两项注册,二者都是插件 fiber 的 effect:`ctx.mcpManager.register('notion', …)` 以配置的 `url` 和 OAuth 凭据 key 添加一个 Streamable HTTP 条目,`ctx.systemPrompt.section()` 在 `MCP_SERVERS` 排序位置添加称呼指引。服务器名固定了 `mcp__notion__` 工具命名空间,凭据 key 固定了 grant 地址,因此重新加载或重新安装的插件会得到同样的工具和 grant。管理器在注册时校验条目;如果已配置或已注册的服务器占用了该名称或 key,插件会在添加指引之前加载失败。
77
+
78
+ 账号注册表运行时,插件还调用 `ctx.mcpAccounts.register({ server: 'notion', packageName: '@deepseek-ai/dsh-notion', copy })`,其中 [`src/locales.ts`](src/locales.ts) 以每种已发布语言保存指明 Notion 的文案;随后由 [`dsh-mcp-account`](../../mcp/mcp-account/README.zh.md) 把账号登记到连接器账号注册表,由注册表渲染上文所述的区块、引导、标签与 toast。没有注册表的组合(如 headless profile)加载插件时不带账号区块。
79
+
80
+ </details>
81
+
82
+ -----
83
+
84
+ <a id="further-exploration"></a>
85
+ ## 进一步探索
86
+
87
+ - [Connector 包](../README.zh.md)——这个应用插件所属的分组。
88
+ - [MCP 管理器](../../mcp/mcp-manager/README.zh.md)——注册生命周期、状态、OAuth 授权与退出登录。
89
+ - [MCP 客户端](../../mcp/mcp-client/README.zh.md)——连接、工具命名、OAuth grant 刷新与脱敏。
90
+ - [MCP 子系统](../../../docs/subsystems/mcp.zh.md)——各 MCP 包如何协同。
91
+ - [Plugin Manager](../../boot/plugin-manager/README.zh.md)——安装与启用。
92
+ - [MCP 账号服务](../../mcp/mcp-account/README.zh.md)——管理器的状态与授权如何映射到账号区块。
93
+ - [连接器账号界面](../../client/ui-connector-account/README.zh.md)——账号注册后显示的区块、标签、引导与提示。
94
+ - [插件页面](../../client/ui-plugin-manager/README.zh.md#use-this-package)——这些界面所在的 bundle 详情页。
95
+
96
+ -----
97
+
98
+ <a id="model-experience"></a>
99
+ ## 模型体验
100
+
101
+ ### 称呼与连接指引
102
+
103
+ #### 模型看到什么
104
+
105
+ 插件加载期间,无论 Notion 是否已授权,系统提示词都会在 MCP 服务器各节之后包含下面这段文字。
106
+
107
+ ##### 指引文本
108
+
109
+ ```markdown
110
+ Tools named `mcp__notion__*` come from the Notion plugin. In user-facing replies, call it the Notion plugin (Notion 插件 in Chinese), not MCP. If no `mcp__notion__*` tool appears in your tool list, Notion is not connected yet; ask the user to connect it on the Notion plugin page in Plugins.
111
+ ```
112
+
113
+ #### Token 影响
114
+
115
+ 插件加载期间,这两句固定文字为每次请求增加约 70 个 token。
116
+
117
+ #### KV Cache 影响
118
+
119
+ 这句话保持前缀稳定:只在插件加载或卸载时变化,授权或连接状态变化不会改变它。
120
+
121
+ ### Notion 服务器工具与说明
122
+
123
+ #### 模型看到什么
124
+
125
+ 授权之后,模型会在 `### MCP server: notion` 之下看到 Notion 的服务器说明;在默认的 `toolLoading: on-demand` 下,还会看到加载器 `mcp__notion__load_tools`,以及系统提示词中的 [Notion 工具目录](../../mcp/mcp-client/README.zh.md#model-experience),加载的每个工具随后以 `mcp__notion__<tool>` 命名,带有 Notion 提供的描述和输入 schema。设为 `eager` 时,所有工具从一开始就出现,详见 [MCP 客户端](../../mcp/mcp-client/README.zh.md#model-experience)。设为 `on-demand` 时,加载器和目录只在 Notion 连接后出现。插件加载期间(包括授权之前),[共用的资源工具](../../mcp/mcp-resources/README.zh.md#model-experience)及其服务器名提示词都会列出 `notion`。
126
+
127
+ #### Token 影响
128
+
129
+ 工具集与服务器说明由 Notion 服务器定义,其大小可能在 DSH 不更新的情况下变化。设为 `on-demand` 时,已连接的 Notion 的开销是服务器说明、加载工具、46 个工具约 6,400 字符的目录,以及 agent 已加载的定义;设为 `eager` 时,全部定义(约 214,500 字符)在每次请求中重复出现。
130
+
131
+ #### KV Cache 影响
132
+
133
+ Notion 的服务器说明(设为 `eager` 时则是其工具)在连接成功时出现,在授权被撤回或插件卸载时消失;每次变化都可能使从第一个变化 token 起的复用失效。设为 `on-demand` 时,目录只在 Notion 的工具列表变化时变化,每次加载都会改变该 agent 下一次请求的工具列表,详见 [MCP 客户端](../../mcp/mcp-client/README.zh.md#model-experience)。共用的资源工具在连接变化前后保持不变。
134
+
135
+ ## 已知限制与延期工作
136
+
137
+ <a id="known-limitations-and-deferred-work"></a>
138
+
139
+ - Notion 账号区块只在插件开启时存在。关闭插件后如需退出登录,请先重新开启插件,或删除 grant 记录。
140
+ - 只有 Web 与 Desktop 组合挂载 MCP 管理器;在其他 profile 中插件保持未激活。
141
+ - 授权回调地址是 Host 上的 `http://127.0.0.1:<port>`,因此完成授权的浏览器必须运行在 Host 所在机器上。从另一台机器访问的 Web Host 无法完成授权。
142
+ - Desktop 每次启动都监听操作系统分配的端口。重启后再次授权会注册一个新的 OAuth 客户端,并保留之前的注册记录;已保存的 grant 在重启前后正常刷新。
143
+ - 账号连接之前,共享资源的提示词仍把 `notion` 列为服务器名,对它的资源调用会失败,直到用户完成连接。
144
+ - 一次 Notion 授权供整个 Host 使用;没有账号或工作区选择器。
145
+ - 停用或卸载插件会保留本地 grant。退出登录会删除本地 grant,但在用户于 Notion 一侧移除之前,该连接在 Notion 中仍处于已授权状态。
146
+
147
+ <a id="dev-note"></a>
148
+ ### 开发备注
149
+
150
+ <details>
151
+ <summary>维护者工作上下文——点击展开</summary>
152
+
153
+ Host 侧单测让插件运行在 MCP 管理器和 mcp-client 的回环 OAuth 服务器夹具之上;另一项单测检查账号注册表提供带文案的 Notion 账号,并随插件一起撤下。`notion-plugin` 会话快照在没有已保存 grant 的情况下回放 Notion 行,因此它固定称呼指引,并验证没有请求到达服务器。
154
+
155
+ </details>
@@ -0,0 +1,3 @@
1
+ - insert:
2
+ - id: notion
3
+ name: '@deepseek-ai/dsh-notion'
package/docs/DETAIL.md ADDED
@@ -0,0 +1 @@
1
+ ![The connected Notion account on the plugin page and a conversation that searches Notion pages](preview.svg)
@@ -0,0 +1 @@
1
+ ![插件页上已连接的 Notion 账号,以及在对话中搜索 Notion 页面](preview.zh.svg)