diff --git a/external_plugins/notion-mcp/.zcode-plugin/plugin.json b/external_plugins/notion-mcp/.zcode-plugin/plugin.json new file mode 100644 index 00000000..7f78a1de --- /dev/null +++ b/external_plugins/notion-mcp/.zcode-plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "name": "notion-mcp", + "version": "0.1.0", + "description": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.", + "author": { + "name": "Jommmain", + "url": "https://github.com/Jommmain" + }, + "keywords": [ + "notion", + "mcp", + "notes", + "documents", + "databases", + "oauth" + ], + "mcpServers": { + "notion": { + "type": "http", + "url": "https://mcp.notion.com/mcp" + } + }, + "skills": "./skills", + "description_i18n": { + "en": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.", + "zh-CN": "Notion MCP 集成:通过官方 mcp.notion.com 服务器访问页面、数据库、评论、页面版本历史与 Notion 聊天会话记录,并提供首次 OAuth 授权指引。" + } +} diff --git a/external_plugins/notion-mcp/README.md b/external_plugins/notion-mcp/README.md new file mode 100644 index 00000000..2e3aeace --- /dev/null +++ b/external_plugins/notion-mcp/README.md @@ -0,0 +1,67 @@ +# notion-mcp + +Connect ZCode to your Notion workspace through the official **Notion MCP +server** (`https://mcp.notion.com/mcp`): read, create and update pages and +databases, work with comments and discussions, browse page version history, +and search/read Notion chat session history. + +## What's included + +- **MCP server declaration** for the official remote Notion MCP server. After + authorization it exposes ~70 tools, grouped as: + - Pages & documents: `notion-search`, `notion-fetch`, `notion-create-pages`, + `notion-update-page`, `notion-move-pages`, `notion-duplicate-page` + - Databases: `notion-create-database`, `notion-query-data-sources` + - Comments & discussions: `notion-get-comments`, `notion-create-comment`, + `notion-set-discussion-resolved` + - Chat session history: `notion-search-sessions`, `notion-query-sessions`, + `notion-read-session-event`, `notion-send-message-to-session` + - Page version history: `notion-get-version-changes`, `notion-view-version`, + `notion-restore-version` + - Calendar & meetings, files & attachments +- **Setup skill** that guides first-time OAuth authorization and 401 + troubleshooting. + +## First-time setup (one time) + +The Notion MCP server only whitelists a fixed list of OAuth client names, and +ZCode is not on it, so the out-of-the-box flow fails at client registration. +Authorize once with the helper script: + +```bash +git clone https://github.com/Jommmain/zcode-notion-mcp +cd zcode-notion-mcp && npm install +node notion-mcp-auth.mjs +``` + +The script opens a browser: log in to Notion, pick the pages to share, click +Allow. It injects the tokens into ZCode's encrypted credential store +(`~/.zcode/v2/credentials.json`, backup is written alongside). Restart ZCode +(or reconnect the `notion` server) afterwards. + +When access tokens expire (ZCode starts receiving 401s), re-run the script. + +## Dependencies, network access and side effects + +- Network: connections to `https://mcp.notion.com` (MCP + OAuth), initiated + by ZCode after installation. The helper script additionally runs a local + callback server on `localhost:3000` during authorization. +- Service dependency: a Notion account with pages the user shares with the + connection. The connection only sees pages explicitly shared during + authorization. +- File writes: none by the plugin itself. The optional helper script writes + only to `~/.zcode/v2/credentials.json` (plus a `.backup` copy). +- Command execution: the setup skill instructs running the helper script from + https://github.com/Jommmain/zcode-notion-mcp when authorization is needed. + +## Third-party code and services + +- **Notion MCP server** — remote service operated by Notion Labs; subject to + Notion's terms of service. +- **zcode-notion-mcp helper** (optional, MIT) — + https://github.com/Jommmain/zcode-notion-mcp — MIT-licensed, depends on the + `@modelcontextprotocol/sdk` (MIT) for the OAuth flow. + +## Category + +`productivity` diff --git a/external_plugins/notion-mcp/README_CN.md b/external_plugins/notion-mcp/README_CN.md new file mode 100644 index 00000000..b2d12aaf --- /dev/null +++ b/external_plugins/notion-mcp/README_CN.md @@ -0,0 +1,59 @@ +# notion-mcp + +通过 Notion **官方 MCP 服务器**(`https://mcp.notion.com/mcp`)将 ZCode 接入 +Notion 工作区:读取、创建和更新页面与数据库,处理评论与讨论,查看页面版本 +历史,以及搜索/读取 Notion 聊天会话记录。 + +## 包含内容 + +- **MCP 服务器声明**:官方远程 Notion MCP 服务器。授权后提供约 70 个工具: + - 页面与文档:`notion-search`、`notion-fetch`、`notion-create-pages`、 + `notion-update-page`、`notion-move-pages`、`notion-duplicate-page` + - 数据库:`notion-create-database`、`notion-query-data-sources` + - 评论与讨论:`notion-get-comments`、`notion-create-comment`、 + `notion-set-discussion-resolved` + - 聊天会话记录:`notion-search-sessions`、`notion-query-sessions`、 + `notion-read-session-event`、`notion-send-message-to-session` + - 页面版本历史:`notion-get-version-changes`、`notion-view-version`、 + `notion-restore-version` + - 日历与会议记录、文件与附件 +- **配置技能**:指引首次 OAuth 授权与 401 排障。 + +## 首次配置(一次性) + +Notion MCP 服务器只允许固定名单内的 OAuth 客户端名称,ZCode 不在其中, +开箱即用的连接会在客户端注册一步失败。请先运行辅助脚本完成授权: + +```bash +git clone https://github.com/Jommmain/zcode-notion-mcp +cd zcode-notion-mcp && npm install +node notion-mcp-auth.mjs +``` + +脚本会打开浏览器:登录 Notion、选择要共享的页面并点击允许。随后脚本将令牌 +写入 ZCode 的加密凭据库(`~/.zcode/v2/credentials.json`,同时生成 `.backup` +备份)。完成后重启 ZCode(或重连 `notion` 服务器)。 + +访问令牌过期(ZCode 收到 401)时,重新运行该脚本即可。 + +## 依赖、网络访问与副作用 + +- 网络:安装后由 ZCode 连接 `https://mcp.notion.com`(MCP 与 OAuth)。辅助 + 脚本在授权期间额外在本机 `localhost:3000` 运行回调服务器。 +- 服务依赖:需要 Notion 账号;连接只能访问用户在授权时明确共享的页面。 +- 文件写入:插件本身不写文件。可选的辅助脚本仅写入 + `~/.zcode/v2/credentials.json`(并生成 `.backup` 备份)。 +- 命令执行:配置技能在需要授权时指示运行来自 + https://github.com/Jommmain/zcode-notion-mcp 的辅助脚本。 + +## 第三方代码与服务 + +- **Notion MCP 服务器** — Notion Labs 运营的远程服务,受 Notion 服务条款 + 约束。 +- **zcode-notion-mcp 辅助脚本**(可选,MIT 许可证)— + https://github.com/Jommmain/zcode-notion-mcp ,OAuth 流程依赖 + `@modelcontextprotocol/sdk`(MIT)。 + +## 分类 + +`productivity` diff --git a/external_plugins/notion-mcp/skills/notion-mcp/SKILL.md b/external_plugins/notion-mcp/skills/notion-mcp/SKILL.md new file mode 100644 index 00000000..67244458 --- /dev/null +++ b/external_plugins/notion-mcp/skills/notion-mcp/SKILL.md @@ -0,0 +1,49 @@ +--- +name: notion-mcp +description: Use when the user asks to read, create or update Notion pages and databases, work with page comments and discussions, browse page version history, or search/read Notion chat session history. Also covers first-time OAuth setup and 401 troubleshooting for the Notion MCP server. +--- + +# Notion MCP + +The `notion` MCP server (official `https://mcp.notion.com/mcp`) exposes ~70 tools: +pages and databases (`notion-search`, `notion-fetch`, `notion-create-pages`, +`notion-update-page`, `notion-move-pages`, `notion-query-data-sources`), comments +and discussions (`notion-get-comments`, `notion-create-comment`, +`notion-set-discussion-resolved`), page version history +(`notion-get-version-changes`, `notion-view-version`, `notion-restore-version`), +chat sessions (`notion-search-sessions`, `notion-query-sessions`, +`notion-read-session-event`, `notion-send-message-to-session`), calendar and +meeting notes, and file uploads/downloads. + +## First-time setup (OAuth) + +The Notion MCP server only whitelists a fixed list of OAuth client names, and +ZCode is not on it — a plain connect fails at client registration. The +one-time workaround is an authorization helper script: + +```bash +git clone https://github.com/Jommmain/zcode-notion-mcp +cd zcode-notion-mcp && npm install +node notion-mcp-auth.mjs +``` + +The script opens a browser: the user logs in to Notion, selects the pages to +share, and clicks Allow. It then injects the tokens into ZCode's encrypted +credential store. Afterwards restart ZCode (or reconnect the `notion` server). +Full details: https://github.com/Jommmain/zcode-notion-mcp + +## Troubleshooting + +- **401 from `notion` tools**: the access token expired. Re-run + `node notion-mcp-auth.mjs` from the helper repository, then restart ZCode. +- **A page is not found / not visible**: the connection only sees pages the + user shared during authorization. Tell the user to open the page in Notion → + `···` → Connections → grant access, then retry. + +## Working rules + +- Prefer `notion-search` first; never invent page or database ids. +- Chat session history: `notion-search-sessions` / `notion-query-sessions`, + then `notion-read-session-event` for details. +- Deleting pages (`notion-delete-pages`) moves them to trash — confirm with + the user before destructive calls. diff --git a/marketplace.json b/marketplace.json index c7f09a06..a7b8462c 100644 --- a/marketplace.json +++ b/marketplace.json @@ -10,7 +10,10 @@ "url": "https://z.ai" }, "unlistedPlugins": [ - { "name": "openpencil", "source": "./external_plugins/openpencil" } + { + "name": "openpencil", + "source": "./external_plugins/openpencil" + } ], "plugins": [ { @@ -827,7 +830,9 @@ }, { "name": "excalidraw", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "Excalidraw", "displayName_i18n": { "en": "Excalidraw", @@ -850,7 +855,9 @@ "name": "photocraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/photocraft/icon.png", "source": "./external_plugins/photocraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "PhotoCraft", "displayName_i18n": { "en": "PhotoCraft", @@ -877,7 +884,9 @@ "name": "vectorcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/vectorcraft/icon.png", "source": "./external_plugins/vectorcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "VectorCraft", "displayName_i18n": { "en": "VectorCraft", @@ -904,7 +913,9 @@ "name": "pdfcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/pdfcraft/icon.png", "source": "./external_plugins/pdfcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "PdfCraft", "displayName_i18n": { "en": "PdfCraft", @@ -931,7 +942,9 @@ "name": "designcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/designcraft/icon.png", "source": "./external_plugins/designcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "DesignCraft", "displayName_i18n": { "en": "DesignCraft", @@ -958,7 +971,9 @@ "name": "wordcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/wordcraft/icon.png", "source": "./external_plugins/wordcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "WordCraft", "displayName_i18n": { "en": "WordCraft", @@ -985,7 +1000,9 @@ "name": "gridcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/gridcraft/icon.png", "source": "./external_plugins/gridcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "GridCraft", "displayName_i18n": { "en": "GridCraft", @@ -1012,7 +1029,9 @@ "name": "deckcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/deckcraft/icon.png", "source": "./external_plugins/deckcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "DeckCraft", "displayName_i18n": { "en": "DeckCraft", @@ -1039,7 +1058,9 @@ "name": "cadcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/cadcraft/icon.png", "source": "./external_plugins/cadcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "CADCraft", "displayName_i18n": { "en": "CADCraft", @@ -1066,7 +1087,9 @@ "name": "soundcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/soundcraft/icon.png", "source": "./external_plugins/soundcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "SoundCraft", "displayName_i18n": { "en": "SoundCraft", @@ -1149,7 +1172,9 @@ }, "category": "developer-tools", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/kicad/icon.png", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "KiCad", "displayName_i18n": { "en": "KiCad", @@ -1443,6 +1468,27 @@ "mcp", "verification" ] + }, + { + "name": "notion-mcp", + "source": "./external_plugins/notion-mcp", + "description": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.", + "description_i18n": { + "en": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.", + "zh-CN": "Notion MCP 集成:通过官方 mcp.notion.com 服务器访问页面、数据库、评论、页面版本历史与 Notion 聊天会话记录,并提供首次 OAuth 授权指引。" + }, + "version": "0.1.0", + "author": { + "name": "Jommmain" + }, + "category": "productivity", + "keywords": [ + "notion", + "mcp", + "notes", + "documents", + "oauth" + ] } ] -} \ No newline at end of file +}