Skip to main content
Glama
deenesjakoruzh
hqzqaq

dsh-tools-mcp

by hqzqaq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

dsh-tools-mcp

将 deepseek-harness（DeepSeek AI 开源的 agent harness）中 极简模式（minimal） 与 标准模式（standard） 的 tools 提取并包装为 MCP（Model Context Protocol） 服务器，通过 --mode 参数控制暴露哪套工具集。

工具 schema、描述文案、输出信封（如 read 的 <path>/<type>/<content> 格式、str_replace_editor 的 view/create/str_replace/insert 语义、[exit code: N] 标记）均忠实还原自原仓库 apps/cli/config/agent-presets/{minimal,standard}/agent.cordis.yml 及其对应 packages/*/tool-* 实现。

模式与工具对照

模式

参数

工具

极简模式

--mode minimal

持久 shell（POSIX 为 bash，win32 为 pwsh，状态跨调用保持）+ str_replace_editor

标准模式

--mode standard

bash/pwsh（单次执行）、read、write、edit、read_image、glob、grep、job_output/job_list/job_kill、todo_write、ask_user_question、web_search、get_goal/create_goal/update_goal、plan_mode/exit_plan_mode、skill

标准模式还支持 --with-web-fetch 额外暴露 web_fetch（原版 standard 预设默认 fetch: false）。

Related MCP server: deepseek-agent-mcp

快速开始

cd dsh-tools-mcp
npm install
npm run build          # 输出到 dist/

# 极简模式
node dist/index.js --mode minimal --cwd D:/develop/project/dsh-tools-mcp

# 标准模式
node dist/index.js --mode standard --cwd D:/develop/project/dsh-tools-mcp

MCP 客户端配置

// mcp.json / WorkBuddy 自定义连接器
{
  "mcpServers": {
    "dsh-minimal": {
      "command": "node",
      "args": ["D:/develop/project/dsh-tools-mcp/dist/index.js", "--mode", "minimal", "--cwd", "D:/develop/project/dsh-tools-mcp"]
    },
    "dsh-standard": {
      "command": "node",
      "args": ["D:/develop/project/dsh-tools-mcp/dist/index.js", "--mode", "standard", "--cwd", "D:/develop/project/dsh-tools-mcp"]
    }
  }
}

两个入口可以同时注册，按需选择极简/标准工具集。

全部参数

--mode <minimal|standard>    Agent 预设模式（默认 minimal）
--cwd <path>                 工作区根目录，文件工具基于它解析相对路径（默认 process.cwd()）
--shell <auto|bash|pwsh>     shell 后端；auto = win32 用 pwsh，其余用 bash
--shell-timeout-ms <n>       持久 shell 单条命令超时（默认 300000）
--max-output-chars <n>       输出截断上限（默认 16000）
--skills-dir <path>          启用 skill 工具，扫描该目录下的 SKILL.md 子目录
--search-provider <duckduckgo|tavily|bing>   web 搜索后端（默认 duckduckgo）
--search-api-key <key>       tavily/bing 的 API key
--proxy <url>                web 工具的 HTTP(S) 代理，如 http://127.0.0.1:7897
--with-web-fetch             额外暴露 web_fetch
--allow-outside-root         允许文件工具访问 --cwd 之外的路径（默认禁止）
--tools <a,b,c>              显式指定工具/套件清单覆盖模式（见下）
--help / --version

--tools 覆写

--tools 接受工具名或套件名，按需暴露子集：

# 只要文件相关
node dist/index.js --mode standard --tools read,write,edit,glob,grep

# 只要极简模式的编辑器 + 后台任务
node dist/index.js --mode minimal --tools str_replace_editor,job_output,job_list,job_kill

套件名：shell（持久 shell）、one-shot、fs、search、jobs、todo、web、ask-user、goal、plan、skill。

设计说明

  • 持久 shell：无 node-pty 依赖，用 stdio 管道驱动长驻 bash/powershell 子进程；命令以随机 UUID 标记包裹以可靠捕获完成状态与退出码；cd/export 等状态跨调用保持；超时或 shell 退出时自动重置（与原始 tool-bash-persistent 语义一致）。

  • 路径安全：默认文件工具仅允许访问 --cwd 工作区内的路径，越界报错提示加 --allow-outside-root。

  • web_search 默认 DuckDuckGo（免 key）；国内网络建议 --proxy http://127.0.0.1:7897，或换 --search-provider tavily --search-api-key <key>。

  • 状态均为进程内（session 级）：todo/goal/plan/后台任务状态随服务器进程生命周期，重启即清空——与原版"会话级状态"等价。

与原版 dsh 的差异（明确说明）

项

原版 dsh

本 MCP 包装

持久 shell

node-pty PTY 终端

stdio 管道长驻进程（无交互提示符，状态保持等价）

ask_user_question

dsh UI 提问桥

MCP stdio 下无法同步交互，返回问题文本并指示模型转述给用户

plan_mode/exit_plan_mode

UI 审批流

服务端标志位 + 计划文本回传

subagent_*/workflow/ralph

依赖 dsh 运行时（LLM 子代理、工作流引擎）

未包装——需完整 dsh 运行时，详见下方

grep 引擎

内置 ripgrep 二进制

node 正则实现（常见语法等价，部分 ripgrep 特性不支持）

未包装的工具（原版 standard preset 中的运行时耦合工具，需完整 dsh runtime）：subagent_control、list_agents、subagent、subagent_fork、workflow、ralph。如需这些能力，请直接使用 deepseek-harness 本体。

测试

npm run build
npm test          # 冒烟测试：两种模式工具暴露 + 核心工具行为 + --tools 覆写
node scripts/state-test.mjs   # 持久 shell 状态保持 / 退出码 / 优雅重置（PROXY=... 可测 web_search）
node scripts/bash-test.mjs    # bash 后端验证

源码参考

提取自 deepseek-ai/deepseek-harness（MIT License，master 分支）：

  • 模式定义：apps/cli/config/agent-presets/minimal/agent.cordis.yml、.../standard/agent.cordis.yml

  • 工具实现：packages/shell/tool-bash-persistent、packages/fs/tool-str-replace-editor、packages/fs/tool-fs、packages/fs/tool-fs-search、packages/jobs/tool-jobs、packages/todo/tool-todo、packages/web/tool-web、packages/interaction/tool-ask-user、packages/goal/tool-goal、packages/plan/plan-mode、packages/skill/tool-skill 等

Available Tools

2 tools
bashA

Run commands in a persistent shell. State, including the current directory and exported environment variables, persists across calls for this agent.

  • You don't have access to the internet via this tool.

  • State is persistent across command calls and discussions with the user.

  • To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.

  • Please avoid commands that may produce a very large amount of output.

  • Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe bash command to run. Relative path is preferred in the command.

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that state persists across calls (including directory and env vars), that there is no internet access, and that state persists across discussions. It also discloses constraints and recommendations (avoid large output, run background commands) and suggests a specific technique (sed). This is rich, transparent behavior description beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, starting with the core purpose and then presenting bullet-pointed usage tips. It has a slight redundancy: 'State is persistent across command calls and discussions with the user' repeats the initial statement about persistence. However, the overall structure is clear and front-loads the most important information without wasting words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's flexibility and only one parameter, the description covers key operational aspects: persistence, network capabilities, output handling, and background execution. It does not mention exit codes or the format of command output, which could be useful, but for a general shell tool the guidance is sufficient for an agent to use it effectively. The absence of an output schema is partially mitigated by the description's behavioral notes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the single 'command' parameter fully, providing its type and a note about relative paths. The description adds value by offering practical guidance on how to construct commands: using sed for line inspection, avoiding excessive output, and handling long-running processes. This enriches the parameter's usage semantics beyond the schema, earning a score above the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Run commands in a persistent shell,' specifying the verb (run), resource (commands in a shell), and a key behavioral trait (persistence). It distinguishes itself from the sibling tool str_replace_editor, which is for file editing, making it a precise and unambiguous purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for usage: it mentions the shell is persistent, warns about no internet access, advises avoiding large output, and recommends running long-lived commands in the background. Though it doesn't explicitly compare with alternatives, the context and tips implicitly guide appropriate use. It doesn't state when not to use this tool, but the guidance is practical and specific.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

str_replace_editorA

Custom editing tool for viewing, creating and editing files

  • State is persistent across command calls and discussions with the user

  • If path is a file, view displays the result of applying cat -n. If path is a directory, view lists non-hidden files and directories up to 2 levels deep

  • The create command cannot be used if the specified path already exists as a file

  • If a command generates a long output, it will be truncated and marked with <response clipped>

Notes for using the str_replace command:

  • The old_str parameter should match EXACTLY one or more consecutive lines from the original file. Be mindful of whitespaces!

  • If the old_str parameter is not unique in the file, the replacement will not be performed. Make sure to include enough context in old_str to make it unique

  • The new_str parameter should contain the edited lines that should replace the old_str

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path to file or directory, e.g. `/repo/file.py` or `/repo`.
commandYesThe commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`.
new_strNoOptional parameter of `str_replace` command containing the new string (if not given, no string will be added). Required parameter of `insert` command containing the string to insert.
old_strNoRequired parameter of `str_replace` command containing the string in `path` to replace.
file_textNoRequired parameter of `create` command, with the content of the file to be created.
view_rangeNoOptional parameter of `view` command when `path` points to a file. If none is given, the full file is shown. If provided, the file will be shown in the indicated line number range, e.g. [11, 12] will show lines 11 and 12. Indexing at 1 to start. Setting `[start_line, -1]` shows all lines from `start_line` to the end of the file.
insert_lineNoRequired parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Transparency is high: no annotations are present, so the description takes the full burden. Detailed behavioral information is abundant, exposing persistence, the behavior of view when file vs. directory, the inability to create an existing file, truncation of long outputs with the marker, and the exact conditions of str_replace.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is long, but structured with sections and command-scoped notes. It is organized by command, then by operational notes (view, insert, str_replace) with clear field labels. The amount of detail useful is given by the complexity of the tool, and is not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output scheme, but the description provides a complete operational picture even without a return description: command list, state persistence, file vs directory behavior in view, truncation of long output, create and insert restrictions, and the str_replace disambiguation rules are all present. Well covered for a tool that accepts many parameters and custom states.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema already covers 100% of the parameters, the descriptions go further with practical semantics: for str_replace, old_str refers to exact/consecutive line matching and uniqueness; new_str is optional semantics; file_text is used in create; view_range explains mixed ranges with 1-based indexing and -1 sentinel; insert_line includes his post-insertion rule.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with specific verb and resource ('custom editing tool for viewing, creating and editing files'), then lists the four commands (view, create, str_replace, insert) with their exact semantics. Its 'custom editing tool' framing distinguishes it from a generic bash/shell tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly defines what the tool does and explains each command's role. The directives include operational caveats (persistent state, directory vs. file output of view, no overwrite on create, output truncation marker) and dedicated notes on how to use str_replace (exact line match, uniqueness requirement, whitespace sensitivity). These rules are stated directly in the tool description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observedbash
    • First observedstr_replace_editor
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation1/5

Both tools are generic and overlap heavily in purpose: bash executes commands, while str_replace_editor edits files—but an agent could easily misuse bash for file edits (it can) or misuse str_replace_editor for shell commands (it cannot). The boundary is unclear, and each tool's descriptions do not clearly delineate when to use one over the other.

Naming Consistency2/5

The names 'bash' and 'str_replace_editor' follow no consistent convention; one is a single-word executable name, the other is a multi-underscore compound. There is no verb_noun pattern, and the names are descriptive but not aligned. However, they are not chaotic, so a score of 2 is appropriate.

Tool Count2/5

With only two tools, the server feels under-scoped for a general-purpose 'dsh-tools' server. Two tools can be sufficient if they cover the domain, but here the domain is broad (shell + file editing), and the count is too low to be considered well-scoped for the apparent purpose.

Completeness2/5

The tool surface lacks any file reading dedicated tool, any process management tool, or any other common operations. While bash can compensate, there are no explicit tools for listing files, searching, or managing processes. The set is far from covering typical developer tasks, though it covers the basics of shell and file editing.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches