yuque-mcp-plus 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.2 - 2026-03-04
+
+Changed:
+
+- added switchable `node` and `npx` setup examples for Codex, Claude Code, Qoder, OpenCode, and Trae
+
+## 0.2.1 - 2026-03-04
+
+Changed:
+
+- simplified the Chinese README title copy to "语雀 MCP 服务"
+- added `npx yuque-mcp-plus` usage to Chinese and English docs
+- updated package metadata description for npm usage
+
 ## 0.2.0 - 2026-03-04
 
 Added:

package/README.en.md

@@ -58,6 +58,18 @@ Resolution order:
 
 ## Run
 
+Run directly from npm:
+
+```bash
+npx yuque-mcp-plus
+```
+
+With environment variables:
+
+```bash
+YUQUE_TOKEN="your-token" npx yuque-mcp-plus
+```
+
 ```bash
 node ./src/index.js
 ```
@@ -84,6 +96,10 @@ Release workflow:
 
 ## Codex MCP Config Example
 
+If you want to switch between the local source tree and the published npm package, only `command + args` need to change.
+
+Source mode:
+
 ```toml
 [mcp_servers.yuque]
 command = "node"
@@ -93,6 +109,17 @@ args = [ "/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js" ]
 YUQUE_TOKEN = "your-token"
 ```
 
+npm mode:
+
+```toml
+[mcp_servers.yuque]
+command = "npx"
+args = [ "-y", "yuque-mcp-plus" ]
+
+[mcp_servers.yuque.env]
+YUQUE_TOKEN = "your-token"
+```
+
 ## Other Client Integrations
 
 The examples below are based on the client docs available on 2026-03-04. UI labels and config file locations may change, but the local `stdio` startup model is the same.
@@ -101,14 +128,23 @@ The examples below are based on the client docs available on 2026-03-04. UI labe
 
 The current official docs recommend registering a local `stdio` MCP server with a command like this:
 
+Source mode:
+
 ```bash
 claude mcp add --transport stdio yuque -- node /Users/program/code/code_mcp/yuque-mcp-plus/src/index.js
 ```
 
+npm mode:
+
+```bash
+claude mcp add --transport stdio yuque -- npx -y yuque-mcp-plus
+```
+
 With environment variables:
 
 ```bash
 claude mcp add --transport stdio --env YUQUE_TOKEN=your-token yuque -- node /Users/program/code/code_mcp/yuque-mcp-plus/src/index.js
+claude mcp add --transport stdio --env YUQUE_TOKEN=your-token yuque -- npx -y yuque-mcp-plus
 ```
 
 Useful management commands:
@@ -120,6 +156,8 @@ claude mcp get yuque
 
 If you prefer project-shared config, you can also place this in your project root `.mcp.json`:
 
+Source mode:
+
 ```json
 {
   "mcpServers": {
@@ -136,6 +174,25 @@ If you prefer project-shared config, you can also place this in your project roo
 }
 ```
 
+npm mode:
+
+```json
+{
+  "mcpServers": {
+    "yuque": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "yuque-mcp-plus"
+      ],
+      "env": {
+        "YUQUE_TOKEN": "${YUQUE_TOKEN}"
+      }
+    }
+  }
+}
+```
+
 ### Qoder
 
 Qoder currently supports adding MCP servers directly from the settings UI.
@@ -149,6 +206,8 @@ Path:
 
 Use this project with:
 
+Source mode:
+
 ```json
 {
   "mcpServers": {
@@ -165,6 +224,25 @@ Use this project with:
 }
 ```
 
+npm mode:
+
+```json
+{
+  "mcpServers": {
+    "yuque": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "yuque-mcp-plus"
+      ],
+      "env": {
+        "YUQUE_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
 After saving, a successful connection icon should appear. Use Qoder in `Agent mode` so it can invoke MCP tools.
 
 ### OpenCode
@@ -173,6 +251,8 @@ OpenCode currently configures MCP in `opencode.jsonc`. Local MCP servers belong
 
 Example:
 
+Source mode:
+
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
@@ -192,6 +272,28 @@ Example:
 }
 ```
 
+npm mode:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "yuque": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "yuque-mcp-plus"
+      ],
+      "enabled": true,
+      "environment": {
+        "YUQUE_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
 In prompts, you can refer to it explicitly, for example:
 
 ```text
@@ -211,11 +313,20 @@ Typical flow:
 
 Recommended values:
 
+Source mode:
+
 - Name: `yuque`
 - Command: `node`
 - Args: `/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js`
 - Env: `YUQUE_TOKEN=your-token`
 
+npm mode:
+
+- Name: `yuque`
+- Command: `npx`
+- Args: `-y yuque-mcp-plus`
+- Env: `YUQUE_TOKEN=your-token`
+
 Notes:
 
 - The exact entry point and field names may vary by Trae version

package/README.md

@@ -1,6 +1,6 @@
 # yuque-mcp-plus
 
-增强版语雀 MCP 服务，默认中文文档。
+语雀 MCP 服务。
 
 它在现有 `yuque-mcp-server` 的基础上补了几类关键能力：
 
@@ -67,6 +67,18 @@
 
 ## 运行方式
 
+通过 npm 直接运行：
+
+```bash
+npx yuque-mcp-plus
+```
+
+如果要带环境变量：
+
+```bash
+YUQUE_TOKEN="your-token" npx yuque-mcp-plus
+```
+
 直接启动：
 
 ```bash
@@ -95,6 +107,10 @@ npm test
 
 ## Codex MCP 配置示例
 
+如果你想在本地源码和 npm 已发布包之间切换，可以直接替换 `command + args`。
+
+源码模式：
+
 ```toml
 [mcp_servers.yuque]
 command = "node"
@@ -104,6 +120,17 @@ args = [ "/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js" ]
 YUQUE_TOKEN = "your-token"
 ```
 
+npm 模式：
+
+```toml
+[mcp_servers.yuque]
+command = "npx"
+args = [ "-y", "yuque-mcp-plus" ]
+
+[mcp_servers.yuque.env]
+YUQUE_TOKEN = "your-token"
+```
+
 ## 其他客户端接入
 
 下面这些示例基于 2026-03-04 当天可查到的客户端文档整理。不同版本的 UI 或配置文件位置可能会变，但本地 `stdio` 启动方式基本一致。
@@ -112,14 +139,23 @@ YUQUE_TOKEN = "your-token"
 
 官方文档当前推荐直接用命令注册本地 `stdio` MCP：
 
+源码模式：
+
 ```bash
 claude mcp add --transport stdio yuque -- node /Users/program/code/code_mcp/yuque-mcp-plus/src/index.js
 ```
 
+npm 模式：
+
+```bash
+claude mcp add --transport stdio yuque -- npx -y yuque-mcp-plus
+```
+
 如果要带环境变量：
 
 ```bash
 claude mcp add --transport stdio --env YUQUE_TOKEN=your-token yuque -- node /Users/program/code/code_mcp/yuque-mcp-plus/src/index.js
+claude mcp add --transport stdio --env YUQUE_TOKEN=your-token yuque -- npx -y yuque-mcp-plus
 ```
 
 常用管理命令：
@@ -131,6 +167,8 @@ claude mcp get yuque
 
 如果你使用项目共享配置，也可以把它写进项目根目录的 `.mcp.json`：
 
+源码模式：
+
 ```json
 {
   "mcpServers": {
@@ -147,6 +185,25 @@ claude mcp get yuque
 }
 ```
 
+npm 模式：
+
+```json
+{
+  "mcpServers": {
+    "yuque": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "yuque-mcp-plus"
+      ],
+      "env": {
+        "YUQUE_TOKEN": "${YUQUE_TOKEN}"
+      }
+    }
+  }
+}
+```
+
 ### Qoder
 
 Qoder 当前支持在设置页里直接添加 MCP。
@@ -160,6 +217,8 @@ Qoder 当前支持在设置页里直接添加 MCP。
 
 本项目可直接使用：
 
+源码模式：
+
 ```json
 {
   "mcpServers": {
@@ -176,6 +235,25 @@ Qoder 当前支持在设置页里直接添加 MCP。
 }
 ```
 
+npm 模式：
+
+```json
+{
+  "mcpServers": {
+    "yuque": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "yuque-mcp-plus"
+      ],
+      "env": {
+        "YUQUE_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
 保存后如果能看到连接图标，说明服务已成功连上。使用时要切到 `Agent mode`，这样 Qoder 才会调用 MCP 工具。
 
 ### OpenCode
@@ -184,6 +262,8 @@ OpenCode 当前在 `opencode.jsonc` 里配置 MCP。本地 MCP 要放在 `mcp`
 
 示例：
 
+源码模式：
+
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
@@ -203,6 +283,28 @@ OpenCode 当前在 `opencode.jsonc` 里配置 MCP。本地 MCP 要放在 `mcp`
 }
 ```
 
+npm 模式：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "yuque": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "yuque-mcp-plus"
+      ],
+      "enabled": true,
+      "environment": {
+        "YUQUE_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
 使用时可以在提示词里直接点名，例如：
 
 ```text
@@ -222,11 +324,20 @@ Trae 已经支持 MCP，但我当前没查到和 Qoder/OpenCode 一样完整公
 
 建议填写：
 
+源码模式：
+
 - Name: `yuque`
 - Command: `node`
 - Args: `/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js`
 - Env: `YUQUE_TOKEN=your-token`
 
+npm 模式：
+
+- Name: `yuque`
+- Command: `npx`
+- Args: `-y yuque-mcp-plus`
+- Env: `YUQUE_TOKEN=your-token`
+
 说明：
 
 - Trae 的具体入口位置和字段名可能会随版本变化

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yuque-mcp-plus",
-  "version": "0.2.0",
-  "description": "Enhanced Yuque MCP server with default repo, TOC tree, parentUuid, and move support.",
+  "version": "0.2.2",
+  "description": "Yuque MCP server with TOC, parentUuid, move, and multipart support.",
   "author": "michaeljou <864738795@qq.com>",
   "license": "MIT",
   "type": "module",

package/src/server.js

@@ -21,7 +21,7 @@ export function createServer() {
   const server = new Server(
     {
       name: "yuque-mcp-plus",
-      version: "0.2.0"
+      version: "0.2.2"
     },
     {
       capabilities: {