dsh-yuque-mcp

把 语雀（Yuque） 知识库接进 DeepSeek Harness：Agent 直接读写你的文档 / 知识库 / 目录 / 小记。 内置上游 yuque-mcp-server 服务端，并在首次运行或令牌失效时弹窗向用户索取 YUQUE_TOKEN。

DSH Agent ──MCP(stdio)──> 内置 yuque-mcp 服务端 ──HTTPS──> 语雀开放 API (api/v2)
                                 ▲
                    YUQUE_TOKEN / YUQUE_HOST（由本插件注入）

它比「手写 mcpServers 配置」多做了什么

上游服务端在缺 YUQUE_TOKEN 时直接 exit 1（src/cli.ts），MCP 客户端只会看到「服务端起不来」。 本插件把「令牌从哪来、坏了怎么办」做成了闭环：

Related MCP server: Yuque MCP Server

环境要求

安装

# 1) 安装到 profile（Agent 受 DSH 文件沙箱限制写不了 ~/.dsh，请在终端执行）
sh dsh-yuque-mcp/scripts/install-into-profile.sh              # 装进 desktop
sh dsh-yuque-mcp/scripts/install-into-profile.sh desktop web  # 装进 desktop 与 web

脚本内部执行的就是桌面端自带 CLI 的官方命令：

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
  plugin --profile desktop add "file:/绝对路径/dsh-yuque-mcp"

GUI 方式：桌面端侧边栏 插件 页 → 安装组合包 → 填本目录的绝对路径。 卸载：dsh plugin --profile desktop remove dsh-yuque-mcp。 本插件零运行时依赖（服务端已打成单文件），安装不联网、不执行任何第三方构建脚本。

重启 Harness 后，Agent 会看到本地工具 yuque_status 与 19 个 mcp__yuque__* 工具。

第一次运行：令牌弹窗

1. 让 Agent 调一次 yuque_status（或直接让它读你的语雀文档）；

2. 插件发现没有可用令牌 → 弹出问答卡片，标题「语雀 YUQUE_TOKEN」；

3. 把令牌粘贴到卡片下方的输入框并提交（卡片上还有一个「暂时不用语雀」的选项，选它只是跳过本次）；

4. 插件立刻打一次 GET /api/v2/user 校验：通过就写进 $DSH_HOME/yuque-mcp/token.json（0600）并热替换服务端， 同一次工具调用继续执行，不需要重试。

建议先调 yuque_status 再调语雀工具：yuque_status 的调用预算给了 10 分钟，用户慢慢找令牌也不会超时； 直接调 mcp__yuque__* 触发弹窗时，可用时间受该 MCP 工具的 toolCallTimeoutMs 限制（默认 60 秒）。

令牌三级来源（优先级从高到低）：

1. profile 配置里的 token（适合 CI / 多账号；会写进配置文件，注意别提交）；

2. 环境变量 YUQUE_TOKEN 或 YUQUE_PERSONAL_TOKEN（后者是上游 v1.0.0 的旧名字，两个都认）；

3. 令牌文件 $DSH_HOME/yuque-mcp/token.json（弹窗自动写入）。

删除令牌文件 = 清除令牌；下次调用会重新弹窗。

配置

在 profile 的 cordis.patch.yml 里按 id 覆盖（不要改插件自带的 cordis.patch.yml）：

- id: yuque-mcp
  config:
    serverName: yuque                  # 工具命名空间 mcp__<serverName>__*
    host: https://your-space.yuque.com # 团队版/独立站点；留空用 https://www.yuque.com
    tokenFile: /Users/me/.dsh/yuque-mcp/token.json
    interactive: true                  # false = 不弹窗（headless / CI 用环境变量喂令牌）
    toolCallTimeoutMs: 60000           # 单次 MCP 调用超时
    verifyTimeoutMs: 8000              # 令牌在线校验超时
    verifyCacheMs: 60000              # 校验结果缓存时长，0 = 每次都校验
    maxPromptAttempts: 3               # 连续贴错几次后放弃
    env:
      YUQUE_HOST: https://your-space.yuque.com

非法值（例如 toolCallTimeoutMs: 0）会在插件加载期被 schema 直接拒绝。

工具

• yuque_status（本地工具，无 mcp__ 前缀）：令牌来源 / 在线校验结果（含当前用户）/ 站点 / 内置服务端版本 / 工具清单 / 可执行建议。

  • 不传参数：令牌缺失或失效时弹窗；

  • prompt: true：无论当前令牌是否可用都弹窗重填（换令牌走这里）；

  • prompt: false：只诊断，不弹窗；

  • verify: false：跳过在线校验（不发网络请求）。

• mcp__yuque__*（19 个，来自上游）：

  • 用户：yuque_get_user

  • 知识库：yuque_list_books、yuque_get_book、yuque_create_book、yuque_update_book

  • 文档：yuque_list_docs、yuque_get_doc、yuque_create_doc、yuque_update_doc

  • 目录：yuque_get_toc、yuque_update_toc

  • 搜索：yuque_search

  • 小记：yuque_list_notes、yuque_get_note、yuque_create_note、yuque_update_note

  • 资源（附件/画板）：yuque_get_resource、yuque_create_resource、yuque_update_resource

故障排查

开发

node scripts/vendor-server.mjs        # 按 PROVENANCE.json 的 ref 重新拉取上游并打包（需要 git / npm）
node scripts/vendor-server.mjs main   # 升级到新的 tag / 分支 / commit
node scripts/smoke.mjs                # 离线自检：94 项断言（vendor 完整性 / 真 stdio 握手 / 单测 / 插件接线）
node scripts/smoke.mjs --online       # 额外探测一次真实 api.yuque.com（失败只算跳过）

目录结构：

dsh-yuque-mcp/
├── lib/index.js              # 插件入口：Config、挂载 mcp-client、yuque_status、tools/execute 闸门
├── lib/token-store.js        # 令牌解析（三级优先级）/ 落盘（0600）/ 打码
├── lib/token-gate.js         # 令牌策略状态机：弹窗 → 校验 → 落盘 → 重挂（依赖注入，可离线单测）
├── lib/yuque-api.js          # GET /api/v2/user 在线校验 + baseURL 规范化
├── vendor/yuque-mcp-server/  # 内置上游服务端（esbuild 单文件 + PROVENANCE.json + LICENSE）
├── scripts/vendor-server.mjs # 拉上游 → npm ci --omit=dev → esbuild 单文件
├── scripts/smoke.mjs         # 自检（含本地语雀桩，不依赖外网）
├── scripts/install-into-profile.sh
└── cordis.patch.yml          # bundle 层：按 id: yuque-mcp 插入

为什么内置服务端是「零依赖单文件」

pnpm 会拦截第三方依赖的构建脚本，一旦上游依赖树里有未获批准的 postinstall，dsh plugin add 会直接失败。 scripts/vendor-server.mjs 用 esbuild 把服务端打成单个 ESM 文件（并用 createRequire banner 兼容 axios 这些 CJS 依赖的动态 require），因此本插件 dependencies 为空，安装不联网、不跑第三方脚本。

上游版本

内置的是上游 main 的 commit（见 vendor/yuque-mcp-server/PROVENANCE.json），而不是 npm 上的 1.0.0 tag： tag v1.0.0 只认 YUQUE_PERSONAL_TOKEN，YUQUE_TOKEN / YUQUE_HOST 是之后才进 main 的（上游尚未再发版）。 插件把两个环境变量都传给子进程，因此两代上游都能跑。

开发时 node scripts/smoke.mjs 会在插件目录下建一个 node_modules/@deepseek-ai 软链（指向 profile 的 peer 依赖）， 仅供本机跑测试用，已在 .gitignore 中忽略。

许可

本插件以 BSD 2-Clause 分发（仓库根目录的 LICENSE 即该许可证）。 内置的 yuque-mcp 服务端来自 yuque/yuque-mcp-server（MIT）， 其许可证随产物保留在 vendor/yuque-mcp-server/LICENSE，来源与构建信息见 vendor/yuque-mcp-server/PROVENANCE.json。