dsh-mcp-worker
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| DSH_HOME | No | DSH state directory. Also passed through to child DSH processes. | ~/.dsh |
| DSH_MCP_BACKEND | No | Execution backend: sdk for a long-lived process or headless for one process per task. | sdk |
| DSH_MCP_DSH_CLI | No | Absolute path to @deepseek-ai/dsh/lib/bin.js. Started with node and is the most reliable way to locate DSH. | |
| DSH_MCP_DSH_DIR | No | DSH installation directory. The worker will append node_modules/@deepseek-ai/dsh/lib/bin.js. | |
| DSH_MCP_PROFILE | No | Profile used by the headless backend. | headless |
| DSH_MCP_TASK_MAX | No | Maximum number of tasks. When exceeded, the oldest finished tasks are evicted first. | 500 |
| DSH_MCP_AUDIT_DIR | No | Directory for the append-only audit.jsonl log. | $DSH_HOME/mcp-audit |
| DSH_MCP_BATCH_DIR | No | Directory for batch task metadata. | $DSH_HOME/mcp-batches |
| DSH_MCP_BATCH_MAX | No | Maximum number of tasks in a single batch submission. Valid range is 1-32. | 8 |
| DSH_MCP_DSH_PATCH | No | DSH compatibility patch mode: apply, notify, or off. | apply |
| DSH_MCP_HTTP_HOST | No | HTTP listen address. If set to 0.0.0.0, DSH_MCP_HTTP_TOKEN must be set. | 127.0.0.1 |
| DSH_MCP_HTTP_PORT | No | HTTP port. Use 0 for a random port. | 7391 |
| DSH_MCP_SDK_MODEL | No | Model used by the sdk backend. Fixed per backend process. | deepseek-flash |
| DSH_MCP_TASKS_DIR | No | Root directory for persisted task data. | $DSH_HOME/mcp-tasks |
| DSH_MCP_TIMEOUT_S | No | Default timeout in seconds for a single task. | 900 |
| DSH_MCP_TRANSPORT | No | MCP transport: stdio for local leaders or http for Streamable HTTP remote leaders. | stdio |
| DSH_MCP_HTTP_TOKEN | No | HTTP Bearer token. Required when using HTTP transport on a non-loopback address. | |
| DSH_MCP_NOTIFY_CMD | No | Command to run when a task finishes. The event is passed via the DSH_MCP_NOTIFY_JSON environment variable. | |
| DSH_MCP_DEFAULT_CWD | No | Default working directory used when cwd is omitted. If unset, the worker process cwd is used. | |
| DSH_MCP_DSH_COMMAND | No | Full DSH command, such as dsh, launched through a shell. Lower priority than DSH_MCP_DSH_CLI. | |
| DSH_MCP_SDK_PROFILE | No | DSH profile used by the long-lived sdk backend. | sdk |
| DSH_MCP_ACL_FALLBACK | No | Fallback when workspace-write sandbox ACL authorization fails: danger-full-access, read-only, or off. | danger-full-access |
| DSH_MCP_ALLOWED_CWDS | No | Semicolon-separated whitelist of allowed working directories. If set, tasks may only run in these directories. | |
| DSH_MCP_OTEL_SERVICE | No | OTel service.name value. | dsh-mcp-worker |
| DSH_MCP_SDK_IDLE_MIN | No | Minutes of backend idle time before the sdk backend process is reclaimed. Valid range is 1-240. | 10 |
| DSH_MCP_SDK_PROVIDER | No | Provider used by the sdk backend. | deepseek-official |
| DSH_MCP_TASK_TTL_MIN | No | Minutes to retain finished tasks before automatic cleanup. | 1440 |
| DSH_MCP_AUTO_WORKTREE | No | Automatically create a writable worktree for ACL-restricted clean git repositories. | 1 |
| DSH_MCP_OTEL_ENDPOINT | No | OTLP/HTTP traces endpoint, such as http://127.0.0.1:4318/v1/traces. Empty disables export. | |
| DSH_MCP_WORKTREE_ROOT | No | Root directory for automatically created worktrees. | ~/dsh-worktrees |
| DSH_MCP_MAX_CONCURRENT | No | Global maximum number of concurrent tasks. Valid range is 1-8; same-session tasks are also serialized. | 2 |
| DSH_MCP_NOTIFY_WEBHOOK | No | Webhook URL to POST a JSON notification when a task finishes. | |
| DSH_MCP_SDK_MAX_TOKENS | No | Optional maximum output tokens per sdk backend call. | |
| DSH_MCP_MAX_TASK_TOKENS | No | Per-task DSH token budget. Default 0 means disabled. | 0 |
| DSH_MCP_PERMISSION_MODE | No | Default permission mode: auto, read-only, workspace-write, or danger-full-access. | auto |
| DSH_MCP_RETRY_TRANSIENT | No | Automatically retry once on transient backend crash or initialization failure. | 1 |
| DSH_MCP_CAPABILITY_CACHE | No | Enable cwd capability cache used by auto permission mode across worker processes. | 1 |
| DSH_MCP_CAPABILITY_TTL_H | No | cwd capability cache TTL in hours. | 24 |
| DSH_MCP_MAX_RESULT_CHARS | No | Result length threshold for spilling full output to disk. | 40000 |
| DSH_MCP_MAX_STATUS_EVENTS | No | Maximum number of events returned by a single dsh_status call. | 100 |
| DSH_MCP_STATUS_WAIT_MAX_S | No | Maximum long-poll wait time in seconds for dsh_status. Valid range is 5-600. | 120 |
| DSH_MCP_SDK_INIT_TIMEOUT_S | No | Timeout in seconds for sdk backend initialization. On failure the worker retries once and can fall back to headless. | 300 |
| DSH_MCP_CLEANUP_INTERVAL_MIN | No | Automatic cleanup interval in minutes. | 10 |
| DSH_MCP_SDK_REASONING_EFFORT | No | Optional reasoning effort for the sdk backend, for example max. | |
| DSH_MCP_MAX_CONCURRENT_PER_CWD | No | Maximum number of concurrent tasks for the same cwd. | 1 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
DSH（DeepSeek Harness）worker：把可验收的完整工作单元交给本机 DSH 执行，并返回结果。 粒度原则（最重要）：一个 dsh_run = 一个可独立验收的工作单元，默认包含「定位 → 实现/修改 → 自测 → 证据汇总」。典型粒度：一个功能点、一个 bug、一个测试修复批次、一次跨文件重构。禁止把同一工作拆成逐文件/逐命令/逐步骤的微任务——那会让 leader 付出更多思考与往返 token，反而更慢。 分工原则：leader 负责决策与验收，DSH 负责执行与迭代；执行密集（读代码/改文件/跑测试/机械重构/批量核对）交给 DSH，需要业务语义/方案权衡/根因判断时 leader 先决策再外包。任务建议写 [已定决策] 与 [待你判断]，DSH 遇到需决策的分支应停下汇报，不要猜。 任务文本四要素：目标（做什么、为什么）、范围（可改/不可改、入口文件）、验收（要跑的命令与期望结果，失败附输出）、证据（变更文件清单 + 测试结果 + 风险点）。给目标与约束，不要让 DSH 逐步等你确认；DSH 会自己规划多步工具调用。 使用顺序：1) dsh_run 提交（可带 wait_s=60–120 在本次调用里直接等结果）；2) dsh_status(task_id, wait_s=长轮询，建议 60–120s) 等到终态；3) dsh_result 取结果；中断用 dsh_cancel。不要 5–25 秒高频轮询，也不要在 DSH 执行期间重复做同一件事。 cwd 必须是具体项目目录绝对路径（不要用用户主目录；Windows 沙箱下 shell 可能不可用）。 permission_mode：默认 auto（worker 按 cwd 能力自动选 workspace-write / worktree / read-only / danger-full-access，调用方不需要手选）；也可显式传 read-only / workspace-write / danger-full-access。 并行：彼此独立的工作流用一次 dsh_batch_run 派发（每个任务仍各自包含完整验收），不要拆成串行小任务。 续聊：同一工作单元后续修正把首次返回的 session_id 传回 dsh_run，不要新建多个孤立任务。 验收：leader 只审阅 diff/测试证据/风险点并决定是否返工，不要逐步重做 DSH 已完成的工作；DSH 失败时把 error 原样反馈用户。 历史任务用 dsh_tasks 回顾；审计事件用 dsh_audit；dsh_result 输出过长落盘时用 dsh_read_result 分页读取；运行指标用 dsh_metrics。 长任务依赖异步任务模型：不要在一次工具调用里反复短轮询等待。
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| dsh_runA | 把一个可验收的完整工作单元（功能点/bug/测试修复批次/跨文件重构）交给本机 DSH 异步执行，立即返回 task_id。DSH 自己规划并执行多步工具调用（读代码、改文件、跑测试），一次任务应覆盖「实现 + 自测 + 证据」；不要提交单步/逐文件微任务。之后用 dsh_status 长轮询（wait_s 60–120）到终态，dsh_result 取结果；中断用 dsh_cancel。cwd 传当前项目绝对路径。 |
| dsh_statusA | 查询任务状态与增量事件。status 为 succeeded/failed/cancelled 表示结束。用 wait_s 长轮询（建议 60–120s）一次等更久，减少 leader 往返；不要用 5–25s 高频轮询。 |
| dsh_resultA | 任务结束后获取最终结果（含完整输出、退出码、耗时）。输出过大时会自动落盘并返回文件路径。任务未结束时返回错误。 |
| dsh_cancelA | 取消排队中或运行中的任务：运行中的任务会杀掉整个进程树。 |
| dsh_describeA | 返回 worker 版本、DSH 入口、默认参数与限制，便于 leader 自适应调用方式。 |
| dsh_tasksB | 列出最近的任务摘要（task_id / 状态 / 任务预览 / cwd / 时间 / 错误），用于回顾历史与继续轮询。 |
| dsh_auditA | 读取最近的审计事件（任务创建/开始/结束/取消、审批决定等），用于追溯与排障。 |
| dsh_read_resultA | 当 dsh_result 因输出过长落盘（返回 artifacts）时，用本工具分页读取完整结果或事件日志；仅限任务目录内。 |
| dsh_batch_runA | 一次并行派发多个彼此独立、各自可验收的工作单元（每个任务仍应覆盖「实现+自测+证据」），立即返回 batch_id；用 dsh_batch_status / dsh_batch_result 聚合查询。不要用它串行拆解同一工作流。 |
| dsh_batch_statusA | 返回批量任务的整体状态、各子任务状态与计数；wait_s>0 时轮询到批量结束或超时。 |
| dsh_batch_resultA | 返回批量中每个任务的最终输出/错误/耗时；单条输出超过 max_output_chars 会截断（完整内容用 dsh_read_result）。 |
| dsh_searchA | 在已记录任务的最终输出与工具结果里做子串检索，返回匹配任务与上下文片段。 |
| dsh_metricsA | 返回任务计数、耗时分位（avg/p50/p95/max）、DSH 侧 token 汇总、并发限制、排队情况、后端与 OTel 状态；用于 leader 自适应与「省 token/提速」核对。 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
The lifecycle tools (run/status/result/cancel) and their batch counterparts (batch_run/batch_status/batch_result) are clearly separated by purpose. Minor overlap exists between dsh_result and dsh_read_result, and between dsh_tasks and dsh_search, but descriptions make the boundaries clear.
All tools use a consistent dsh_ prefix with snake_case verb_noun patterns (dsh_run, dsh_status, dsh_batch_run, dsh_read_result). The batch family mirrors the single-task family predictably.
13 tools is well within the ideal 3-15 range and each earns its place: core lifecycle, batch orchestration, result reading, search, audit, metrics, and introspection.
The surface covers the full async task lifecycle: submit, poll, fetch result, cancel, batch dispatch/status/result, large-output pagination, search, audit trail, metrics, and worker introspection. No obvious dead ends.