前言¶

DeepSeek Harness（dsh）可以通过 MCP 把外部能力挂进智能体。Undermind 是面向研究场景的 AI 文献检索服务：用自然语言描述研究目标，返回按相关性排序的论文，并支持 PDF 阅读与工作区整理。其远程 MCP 端点为 https://mcp.undermind.ai/mcp，但只接受 OAuth 授权码 + PKCE 签发的 Authorization: Bearer；访问令牌约一小时过期，刷新令牌每次使用都会轮换。dsh 内置的 @deepseek-ai/dsh-mcp-client 只能转发静态请求头，没有续期逻辑，无法长期维持这条连接。

dsh-plugin-undermind（维护者 VANuVANuu，GitHub 仓库 VANuVANuu/dsh-plugin-undermind，社区目录 SkillHub 条目）在 dsh 进程内自行完成 OAuth/PKCE 登录、令牌存储与刷新，并把 Undermind MCP 工具注册为 mcp__undermind__*。分类为联网工具；当前 package 版本为 0.1.0，许可证 MIT，要求 dsh >=0.2.1-rc.3 <0.3.0-0。

这是什么¶

插件把 Undermind 的远程 MCP 服务接入 dsh，使智能体可以检索文献、读 PDF、整理论文。每个用户用自己的 Undermind 账号授权，没有 API Key 或服务账号模式。插件以 ESM 形式发布，无构建步骤，通过 Cordis patch 与宿主共享 @deepseek-ai/cordis、@deepseek-ai/schemastery 等 peer 依赖。

为什么需要插件而不是只配 MCP¶

Undermind 端点的认证模型与静态 MCP 客户端不匹配。插件负责：

1. OAuth/PKCE 登录 — 一次性 loopback 回调服务 + 系统浏览器完成授权。
2. 令牌存储与刷新 — 默认写入 $DSH_HOME/storages/undermind-mcp-auth.json，权限 0600、原子替换；到期前 90 秒刷新；遇 401 强制刷新并重试一次；轮换后的 refresh token 立即落盘。
3. MCP 会话 — initialize → notifications/initialized，每次调用携带 mcp-session-id，支持 JSON 或 text/event-stream；服务端返回 404 时重建会话。
4. 工具注册 — tools/list 返回的工具以 mcp__undermind__<name> 注册；未授权时不注册任何 Undermind 工具；换账号或改 clientId 会丢弃上一代工具。
5. undermind_auth 工具 — 始终可用，动作为 status、login、logout、refresh、retry，便于在对话里修复会话。
6. 宿主 HTTP 路由 — /dsh-undermind/api/ 下提供浏览器侧授权与诊断接口。

请勿同时为该服务再添加 @deepseek-ai/dsh-mcp-client：它不能刷新令牌，且工具名会与插件冲突。

前置条件：账号与 client id¶

1. 需要 Undermind 账号。
2. 需要 client id。Undermind 不支持动态客户端注册，可选：
   - CIMD：在你控制的 HTTPS URL 上托管 Client ID Metadata Document（JSON），把该 URL 填入插件 clientId；
   - 预注册 client id：向 support@undermind.ai 申请。

CIMD 自助路径示例（client_id 必须与 URL 字节级一致，redirect_uris 须包含插件的 redirectUri）：

{
  "client_id": "https://example.com/undermind-client-metadata.json",
  "client_name": "DeepSeek Harness",
  "redirect_uris": ["http://127.0.0.1:8799/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp"
}

文档须以 application/json 提供。GitHub raw.githubusercontent.com 常为 text/plain，Gist 可用 gist.githack.com 镜像；GitHub Pages 可直接使用。修改 redirectUri 时须同步更新 CIMD。本地可访问 GET /dsh-undermind/api/client-metadata 获取带当前 redirectUri 的模板。

安装¶

CLI 安装（将 web 换成你的 profile 名）：

dsh plugin --profile web add github:VANuVANuu/dsh-plugin-undermind

Electron 桌面客户端保留 desktop profile，dsh plugin CLI 不能向其安装；可从插件市场安装，或将包放到 profiles/desktop/node_modules 并在 dsh.profile.bundles 中加入 dsh-plugin-undermind。

DSH 社区插件目录在 SkillHub 等独立站点维护，与 DeepSeek / 幻方无官方从属关系；安装前宜自行查看仓库源码与 MIT 许可证。插件以当前 dsh 进程权限运行，令牌仅写在本地机器。

配置¶

字段在插件设置中保存后，下一次调用生效，无需重启进程。

典型用法¶

首次登录¶

在对话中让智能体连接 Undermind，或调用：

undermind_auth action="login"

插件在 redirectUri 端口启动一次性服务，用 PKCE 构造授权 URL 并打开默认浏览器。批准后浏览器回到 127.0.0.1:8799/callback，插件换码、写令牌并注册工具。mcp__undermind__* 随即对模型可见；undermind_auth action="status" 可查看 toolCount 与已注册名称。

日常使用¶

• 描述研究问题并指定时间范围 → 可调用 mcp__undermind__launch_deep_search 启动异步深度检索（可能数分钟），用 inspect_deep_searches 轮询。
• 按摘要找相似论文 → mcp__undermind__search_papers。
• 批量读 PDF 并归纳方法 → mcp__undermind__read_pdfs（每篇论文单独子智能体，含图表）。
• 整理到文件夹 → create_folder、add_papers_to_folder 等（注册名均带 mcp__undermind__ 前缀）。

display_deep_search_results、display_references、suggest_pdf_uploads 在支持 MCP Apps 的智能体里是交互卡片；在 dsh 中仅返回文本与链接。

排错¶

Loopback HTTP 路由（仅 localhost / 127.0.0.1 / [::1]，sec-fetch-site: cross-site 会被拒绝）包括 GET /dsh-undermind/api/status、POST /dsh-undermind/api/login 等；响应包络为 {"ok":true,"data":…} 或 {"ok":false,"error":{…}}。

适用场景与注意¶

适合需要在 dsh 智能体工作流里做文献检索、读 PDF、管理论文集合的研究与开发场景。不适合期望「只填一个静态 MCP URL 就能用」的部署方式——认证必须由本插件或等价的 OAuth 续期逻辑承担。

安装与启用前请阅读仓库 README 与源码；令牌不离开本机，但仍依赖你对 Undermind 账号与 OAuth 客户端文档的安全托管。

结尾¶

dsh-plugin-undermind 把 Undermind 的 OAuth MCP 连接做成 dsh 一等插件：登录、续期、会话与 mcp__undermind__* 工具注册一体化，避免与内置静态 MCP 客户端硬配。更多信息见 GitHub 仓库 与 SkillHub 目录页。