Skip to main content
Glama

dsh-mcp-gateway

把本机正在运行的 DeepSeek Harness(DSH) 以 Streamable HTTP MCP Server 暴露给其它 Agent。

其它 Agent 可以通过 MCP 工具读取已有会话、发送消息、一次性提问并取回答复;在用户授权后还可以新建会话、指定模型、切换权限、取消/派生会话,甚至调整 DSH 设置、管理插件与凭据。

默认权限(下限)

安装并启用后默认:

  • 审批模式:审批(仅勾选项)

  • 勾选能力:基础 5 项

    • list_sessions 列出会话

    • read_session 读取记录

    • send_message 发送内容

    • wait_for_completion 等待完成

    • ask_dsh 一次调用完成“发送并返回回答”

  • 其它所有能力默认关闭,且每次调用基础工具都会通过 Windows MessageBox 请求审批,用户允许后才执行。

  • 所有 numeric limits 默认 -1:负数表示不限制读取条数/字符数、单条消息长度、等待时间和审批超时;只有正数才启用原有限制。

⚠️ 默认允许向所有已有根会话发送消息。这些会话中的模型会按该会话当前的权限预设执行工具;如果会话是“完全权限”,外部 Agent 可能借此执行任意命令或文件操作。请用会话 allowlist、关闭发送能力或收紧会话权限来降低风险。

Related MCP server: dsh-mcp-bridge

鉴权模型

四个审批档位

档位

行为

审批(仅勾选项)

只有勾选的能力可用;每次调用都需要审批

审批(勾选项除外)

勾选的能力直接放行;未勾选的能力每次调用需要审批

均需审批

所有能力都可用;每次调用都需要审批

完全开放(无视名单)

所有能力直接放行,不再询问;勾选名单仅作展示

能力勾选在四种模式下含义不同:only-checked 会隐藏未勾选工具;except-checked 中未勾选工具仍可见,但每次调用必须审批(不是硬拒绝);all 全部可见且每次审批;open 全部可见且直接放行。若要硬性禁止管理类工具,请使用 only-checked 或保持对应能力未勾选并选择 only-checked。

审批请求只通过 Windows MessageBox 显示:能力、工具、会话、参数摘要、超时时间;可以允许或拒绝。DSH 窗口内不再显示审批卡片,即使 DSH 窗口最小化也能看到系统弹窗。 审批等待默认不限时(limits.approvalTimeoutMs=-1);配置正数时超时失败关闭,不会自动放行。

设置文件受 Windows 文件 ACL 保护:默认把 $DSH_HOME/dsh-mcp-gateway 目录和 settings.json 设为管理员/SYSTEM 可写、当前用户只读。非管理员保存设置时,插件会先尝试直接写;被 ACL 拒绝后自动触发 Windows UAC,用户批准后由提权 helper 写回同一份文件;取消授权才返回 403 settings-write-denied。插件层没有管理员判断或 admin-required 门禁。

三级能力

级别

能力

基础

列出会话、读取会话、发送消息、等待完成、问答接口 ask_dsh

常规

列出模型、新建会话、选择模型、切换权限、取消轮次、派生会话、重命名会话

进阶

调整 DSH 设置、管理插件(列/启停/安装/卸载)、管理凭据(状态/设置/移除,不读取明文)

设置页每个级别有“全选/取消全选”勾选行,可以逐项调整。

范围(Scope)

  • 会话范围:全部 / 仅勾选 / 除勾选外 / 禁用。勾选模式提供可视化会话列表(标题、cwd、模型、运行状态),也保留字段式配置。

  • 模型范围:全部 / 仅勾选 / 除勾选外 / 禁用。勾选模式按 provider 分组提供可视化列表,也保留 provider/model 字段。

  • 子会话:默认拒绝。

  • cwd 范围:非完全开放模式下,MCP 新建会话的 cwd 必须位于 allowedRoots 或 defaultCwd 内;完全开放模式允许任意绝对路径。

  • 权限预设:MCP 新建会话默认使用 workspace-write;danger-full-access 仅在完全开放模式下可用。

使用方式

1. 安装并启用插件

正常发行方式:在 DSH 的 Plugins 页面安装并启用 dsh-mcp-gateway。 当前机器因为 pnpm store 不一致,采用本地 link 方式安装(见下文“安装”)。

2. 确认首次配置

插件首次生效后客户端会弹出欢迎/风险提示;确认后写入 onboarding 状态。 设置页入口:DSH 0.2.2 为 设置 → 插件 → DSH MCP Gateway;DSH 0.2.1 为 设置 → DSH MCP 网关。

3. 直接连接 MCP(推荐)

端点:http://127.0.0.1:<port>/dsh-mcp/mcp(端口跟随当前 DSH Web 服务;设置页会显示实际地址) Token:设置页复制,或读取 $DSH_HOME/dsh-mcp-gateway/settings.json 的 server.token。

复制 MCP 客户端配置是推荐步骤(不是多余操作),配置会随当前端口生成:

  1. 在设置页复制 MCP 客户端配置(含当前地址/端口和 Token);

  2. 把设置页“使用方法”里的标准提示词发给 Agent,并同时提供配置或 Token;

  3. 提示词中的地址、端口、设置文件路径来自当前网关状态,会动态变化;提示词不含真实 Token,Agent 需要认证时会向用户询问 Token。DSH 设置变化后请重新复制提示词。

{
  "mcpServers": {
    "dsh": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/dsh-mcp/mcp",
      "headers": {
        "Authorization": "Bearer dshmcp_xxx"
      }
    }
  }
}

如果 Agent 只支持 URL + Token、不需要配置文件,也可以省略 JSON;DSH 必须保持运行,v1 不提供 stdio 适配。

4. 调用

推荐的最小工作流:

  1. list_sessions 找到目标会话;

  2. ask_dsh 发送问题并直接拿到回答;

  3. 长任务用 send_message(wait=false) + wait_for_completion 轮询;

  4. 新任务用 create_session + ask_dsh 或直接 run_task。

ask_dsh 示例:

{
  "sessionId": "session-...",
  "message": "解释这个仓库的构建流程",
  "timeoutMs": 60000
}

返回:

{
  "sessionId": "session-...",
  "requestId": "...",
  "reply": "……",
  "status": "idle",
  "cursor": { "lastSeq": 123 },
  "messages": [ ... ]
}

如果 reply 为空或 status 为 timeout/running/queued,用返回的 cursor.lastSeq 调 wait_for_completion 继续取回。 ask_dsh 会阻塞到本轮结束;未传 timeoutMs 时使用 maxWaitMs(默认 -1,表示不限时)。调用期间不要自己启动轮询循环。

设置页的“使用方法”Tab 还提供可直接复制的标准提示词,可整段发给其它 Agent 使用。

工具列表

工具

能力

说明

list_sessions

listSessions

列出已有根会话

read_session

readSessions

transcript / 受限事件记录

send_message

sendMessages

向已有会话发送,可等待

wait_for_completion

waitForCompletion

等待/轮询轮次

ask_dsh

askDsh + sendMessages + waitForCompletion

一次调用阻塞等待并返回最终回答(未传 timeoutMs 时使用 maxWaitMs;默认 -1 表示不限时)

list_models

listModels

已配置模型

create_session

createSessions

新建会话

run_task

createSessions + sendMessages + waitForCompletion

新建 + 发送 + 等待

set_model

selectModel

切换会话模型

set_permission

setPermission

切换权限预设

cancel_turn

cancelTurns

取消运行轮次

fork_session

forkSessions

派生会话

rename_session

renameSessions

重命名

settings_describe

manageSettings

读取 DSH 设置(脱敏)

settings_update

manageSettings

修改 DSH 设置

plugins_list

managePlugins

列出插件/包

plugin_set_enabled

managePlugins

启停插件行

bundle_set_enabled

managePlugins

启用/停用 bundle

plugin_install

managePlugins

安装插件(可能执行包构建脚本)

plugin_remove

managePlugins

卸载插件

credentials_describe

manageCredentials

凭据状态(不返回明文)

credential_set

manageCredentials

设置凭据

credential_unset

manageCredentials

移除凭据

说明:

  • wait_for_completion 返回 transcript 页(messages / completedTurns / turnEndReason / cursor),没有顶层 reply;需要单条回答用 ask_dsh。

  • 参数名按资源类型保留:plugin_set_enabled 用 entryId(Loader 行),bundle_set_enabled / plugin_remove 用 name(包名),credentials 用 ref。

  • set_permission 切换到 danger-full-access 仍要求网关审批模式为 open;read-only / workspace-write 不受此限制。

  • cancel_turn 等价于 GUI 停止当前运行轮次,保留已排队 follow-up;对已完成轮次是 no-op。

安全模型

  • Bearer Token,常量时间比较;轮换即时失效;日志不记录 Token。

  • 仅回环客户端;Host/Origin 校验;无 CORS。

  • 每次需要审批的 MCP 调用通过 Windows MessageBox 确认;超时失败关闭。

  • 设置文件写入走操作系统文件路径鉴权:非管理员写入被 ACL 拒绝后自动请求 UAC,批准则写入成功,取消则返回 403 settings-write-denied;插件层没有管理员门禁。

  • 审批摘要会截断并遮蔽 token/secret/password/value 等字段。

  • open 模式会放开全部能力,只建议完全信任的客户端使用。

  • 本机同用户进程属于信任边界;能读 $DSH_HOME 的进程可以取得 Token。

  • 不自动批准、不自动回答 ask_user_question;模型在 DSH 中等待用户时,MCP 调用会一直等待(默认限制已关闭)或受客户端自身超时限制。

安装

版本:DSH 0.2.2-rc.1(兼容范围 >=0.2.1-rc.5 <0.3.0),desktop profile。

方式 A:插件管理器(推荐)

在 DSH 侧边栏 Plugins 页面搜索 dsh-mcp-gateway 并安装,或执行:

dsh plugin --profile <profile> add dsh-mcp-gateway

插件激活后创建 $DSH_HOME/dsh-mcp-gateway/settings.json。

# 1. 安装插件自身依赖(在仓库目录)
pnpm install

# 2. 让 profile 解析本地包
dsh plugin --profile <profile> add link:<本仓库绝对路径>

# 3. 在 profile 的 cordis.patch.yml 末尾加入:
#    - insert:
#        - id: dsh-mcp-gateway
#          name: dsh-mcp-gateway

保存后 DSH 会重载配置;若客户端未出现,刷新页面。

测试

# 单元/协议测试
node --test test/*.test.js

# 只读烟测(临时切 open,结束后恢复)
node scripts/smoke-live.mjs

# 写入烟测:新建 + ask_dsh + wait
node scripts/smoke-live.mjs --write --root <工作区>

# 完全开放 + danger-full-access + run_task
node scripts/smoke-live.mjs --full --root <工作区>

# 审批流:only-checked 下出现审批 → allow / deny
node scripts/smoke-live.mjs --approval

# 进阶只读工具:settings_describe / plugins_list / credentials_describe
node scripts/smoke-live.mjs --advanced

# 范围四档:except 排除会话 / none 禁用会话(结束自动恢复)
node scripts/scope-smoke.mjs

# Windows 系统审批弹窗自测(弹窗约 1.2 秒后按超时自动关闭)
node scripts/system-popup-smoke.mjs

# 当前 only-checked 模式下的审批 allow/deny(不修改设置)
node scripts/approval-current-smoke.mjs

smoke-live / scope-smoke 会临时切换审批模式或范围并写入设置文件;如果设置目录已加固 ACL,普通权限运行会弹出 UAC 并等待授权,不适合无人值守烟测。可在管理员身份启动的 DSH 下执行,或改用不写设置的 approval-current-smoke / system-popup-smoke。

烟测会创建留在 DSH 会话列表中的测试会话,可自行删除;--write/--full 结束会恢复原设置。

数据与日志

  • 设置/Token:$DSH_HOME/dsh-mcp-gateway/settings.json(schemaVersion 2)。

  • 旧版 v1 设置会自动迁移:权限布尔 → capabilities,fullAccess:true → open,Token/范围/引导状态保留。

  • 激活诊断:$DSH_HOME/dsh-mcp-gateway/activation.log(设置目录加 ACL 后,普通权限进程无法再追加,属预期)。

  • 损坏设置会备份为 settings.json.corrupt-<timestamp> 后重建默认配置。

设置文件权限加固(可选)

scripts/protect-settings.ps1 可以把设置目录和文件设为:

  • BUILTIN\Administrators / SYSTEM:完全控制

  • 当前用户:目录 ReadAndExecute、settings.json Read

因此保存设置时,普通进程会触发 UAC;批准后由提权 helper 写入,取消或超时才返回 403 settings-write-denied,且不会修改文件或 revision。

UAC helper 是 lib/settings-elevate.exe(GUI 子系统,无控制台窗口):

  • 先弹出 Windows 信任对话框(WinForms,盾牌图标,类似“是否信任此应用”);显示目标 文件路径、修改摘要(审批模式、能力、范围、限制、服务字段等 diff),默认按钮为“拒绝”;

  • 点“信任并请求管理员权限”后,才通过 ShellExecuteEx("runas") 请求 UAC;

  • 提权后的副本只接受目标名为 settings.json、父目录名为 dsh-mcp-gateway、源文件为合法 JSON 的写请求,不执行任意命令;

  • 不再启动 PowerShell,因此不会闪过 PowerShell 窗口。

测试方式:刷新 DSH 页面 → 修改任一设置 → 保存。若当前用户没有文件写权限,会先出现 Windows 信任对话框,列出目标文件和修改摘要;点“信任并请求管理员权限”后,Windows 再 按 UAC 策略弹授权框或静默提权;点“拒绝”则不写入,页面显示 settings-write-denied。

# 重新加固(当前用户即可执行,因为仍是文件所有者)
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\protect-settings.ps1 `
  -SettingsPath "$env:DSH_HOME\dsh-mcp-gateway\settings.json"

# 撤销 ACL(需要能修改 ACL 的身份;用于恢复默认继承权限)
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\protect-settings.ps1 `
  -SettingsPath "$env:DSH_HOME\dsh-mcp-gateway\settings.json" -Unprotect

注意:Windows 文件所有者仍可能主动改回 ACL;这是操作系统所有权模型,不是插件能覆盖的边界。

已知限制

  • 只支持 Streamable HTTP;无 stdio proxy。

  • Windows 系统审批弹窗依赖 powershell.exe 与 System.Windows.Forms;非 Windows 没有审批 UI,需要审批的调用会超时失败。

  • 审批只依赖 Windows MessageBox;DSH 页面关闭/最小化不影响审批,非 Windows 无审批入口。

  • 设置文件写入受 Windows ACL 控制;普通用户保存时触发 UAC,批准后写入,取消则失败。

  • UAC fallback 需要交互式桌面;无桌面/服务会话或 UAC 被策略禁用时,保存直接返回 settings-write-denied。

  • 管理员边界在操作系统文件层;插件只在文件写入被拒绝时请求 UAC,没有 admin-required 插件门禁。

  • 不支持 MCP resources / prompts / sampling / elicitation。

  • 不自动批准,不自动回答用户提问。

  • 插件安装/设置修改依赖 DSH 会话服务;兼容 DSH 0.2.1-rc.5 和 0.2.2-rc.1,升级 DSH 后仍需复核。DSH 0.2.2 的入口在 设置 → 插件 → DSH MCP Gateway(旧版为设置分区)。

  • open 模式与 except-checked 下勾选高级能力都可能让外部 Agent 执行用户级操作,请谨慎。

排障

现象

处理

MCP 401

Token 错误/已轮换;从设置页复制新 Token

MCP 403

非回环地址、Host/Origin 不匹配;改用 http://127.0.0.1:<port>

MCP 503

设置中 server.enabled 为 false

工具缺失

当前审批模式/能力未勾选;或 only-checked 下未勾选

调用一直等待

需要 Windows MessageBox 审批但无人处理;默认审批不限时,检查弹窗是否被其它窗口遮挡

设置页/弹窗不出现

刷新页面;在 设置 → 插件 → DSH MCP Gateway 打开;检查 __DSH_BOOT__ 中是否有 dsh-mcp-gateway;查看 activation.log

保存冲突 409

别处已修改设置;刷新后重试

读不到设置

检查 $DSH_HOME;插件启动时会创建目录/文件

卸载 / 回滚

  1. 从 profile cordis.patch.yml 删除 dsh-mcp-gateway insert 行;

  2. 从 profile package.json 删除依赖;

  3. 删除 profiles\desktop\node_modules\dsh-mcp-gateway junction;

  4. 可选删除 $DSH_HOME/dsh-mcp-gateway;

  5. 刷新/重载 DSH。

已有备份:cordis.patch.yml.bak-mcp-gateway、package.json.bak-mcp-gateway。

实现文件

文件

职责

lib/index.js

Cordis 入口、路由生命周期、审批队列

lib/settings.js

v2 设置、v1 迁移、Token、revision、原子写

lib/capabilities.js

三级能力、四级审批模式、工具可见/调用策略

lib/approvals.js

审批队列、摘要脱敏

lib/bridge.js

DSH 服务适配、会话/模型/设置/插件/凭据操作

lib/format.js

transcript / events 投影与脱敏

lib/mcp.js

MCP Server、23 个工具、审批门禁

lib/http.js

认证、管理 API、审批 API

lib/client.js

浏览器 UI(原生勾选、Tab、使用说明;审批仅在系统 MessageBox)

lib/settings-elevation.js

写文件被 ACL 拒绝时触发 UAC 提权 fallback

lib/settings-elevate.exe

GUI 信任对话框 + 提权写入 helper(无 console;WinForms 盾牌窗口)

scripts/settings-elevate-gui.cs

UAC/信任对话框 helper 源码

scripts/build-elevate.ps1

用 .NET Framework csc 重新编译 helper

scripts/protect-settings.ps1

给设置目录/文件加管理员可写、用户只读的 Windows ACL

docs/CLIENT-CONTRACT-V2.md

客户端 v2 契约

docs/SETTINGS.md

设置字段与 API

docs/STANDARD-PROMPT.md

可直接复制给其它 Agent 的标准提示词

docs/VERIFICATION.md

验证记录

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      In-process DeepSeek Harness plugin that exposes a local Streamable HTTP MCP server, allowing MCP clients like Codex to submit tasks executed by DSH child agents using DSH's existing tools.
      681 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes DeepSeek Harness tools to any MCP-compatible client over streamable HTTP, allowing allowlisted operations such as file read, glob, grep, and web search while preserving the harness's sandbox and approval pipeline.
      681 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes a running DeepSeek Harness as an MCP endpoint so any other agent or script can create workspaces and sessions, hand coding tasks to the DSH agent, read and write files, run shell commands, and invoke permitted harness tools under the same sandbox, transcript, and permission policy as the DSH UI.
      1,888 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes a DeepSeek Harness instance — either the whole runtime or one session chosen in the UI — as an MCP Streamable HTTP endpoint on the Harness Web server's origin. Lets other MCP-speaking agents such as Codex or Claude Code delegate tasks, list and read session transcripts, and cancel or inspect running turns using the Harness's own model, tools, workspace and sandbox policy.
      MIT