Skip to main content
Glama
deenesjakoruzh
hqzqaq

dsh-tools-mcp

by hqzqaq
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

dsh-tools-mcp

Extract and wrap the tools from minimal mode and standard mode in deepseek-harness (DeepSeek AI's open-source agent harness) as an MCP (Model Context Protocol) server, with the --mode parameter controlling which tool set is exposed.

The tool schemas, description texts, and output envelopes (such as the <path>/<type>/<content> format of read, the view/create/str_replace/insert semantics of str_replace_editor, and the [exit code: N] marker) are all faithfully reproduced from the original repository's apps/cli/config/agent-presets/{minimal,standard}/agent.cordis.yml and its corresponding packages/*/tool-* implementations.

Mode and Tool Mapping

Mode

Parameter

Tools

Minimal mode

--mode minimal

Persistent shell (bash on POSIX, pwsh on win32, state maintained across calls) + str_replace_editor

Standard mode

--mode standard

bash/pwsh (single execution), 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

Standard mode also supports --with-web-fetch to additionally expose web_fetch (the original standard preset defaults to fetch: false).

Related MCP server: deepseek-agent-mcp

Quick Start

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 Client Configuration

// 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"]
    }
  }
}

Both entry points can be registered simultaneously, and you can choose the minimal or standard tool set as needed.

All Parameters

--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 Override

--tools accepts tool names or suite names to expose a subset as needed:

# 只要文件相关
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

Suite names: shell (persistent shell), one-shot, fs, search, jobs, todo, web, ask-user, goal, plan, skill.

Design Notes

  • Persistent shell: No node-pty dependency; uses stdio pipes to drive a long-running bash/powershell child process; commands are wrapped with random UUID markers to reliably capture completion status and exit codes; state such as cd/export is maintained across calls; automatically resets on timeout or shell exit (consistent with the original tool-bash-persistent semantics).

  • Path safety: By default, file tools only allow access to paths within the --cwd workspace; out-of-bounds access raises an error prompting the use of --allow-outside-root.

  • web_search defaults to DuckDuckGo (no API key required); for users in mainland China, it is recommended to use --proxy http://127.0.0.1:7897, or switch to --search-provider tavily --search-api-key <key>.

  • All state is in-process (session-level): todo/goal/plan/background job state lives with the server process lifecycle and is cleared on restart—equivalent to the original "session-level state."

Differences from the Original dsh

Item

Original dsh

This MCP wrapper

Persistent shell

node-pty PTY terminal

stdio pipe long-running process (no interactive prompt, state maintained equivalently)

ask_user_question

dsh UI question bridge

Synchronous interaction is not possible under MCP stdio; returns the question text and instructs the model to relay it to the user

plan_mode/exit_plan_mode

UI approval flow

Server-side flag + plan text callback

subagent_*/workflow/ralph

Depends on the dsh runtime (LLM sub-agents, workflow engine)

Not wrapped—requires the full dsh runtime, see below

grep engine

Built-in ripgrep binary

node regex implementation (common syntax is equivalent; some ripgrep features are not supported)

Unwrapped tools (runtime-coupled tools in the original standard preset, requiring the full dsh runtime): subagent_control, list_agents, subagent, subagent_fork, workflow, ralph. For these capabilities, please use the deepseek-harness itself.

Testing

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

Source Code Reference

Extracted from deepseek-ai/deepseek-harness (MIT License, master branch):

  • Mode definitions: apps/cli/config/agent-presets/minimal/agent.cordis.yml, .../standard/agent.cordis.yml

  • Tool implementations: 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, etc.

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
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.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

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches