# dsh-minimal-mcp

将 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 的**极简模式（minimal agent preset）**的面向模型工具包装成一个 MCP server，供任意外部 agent（Claude Desktop、Trae、Cursor、LangChain 等）通过标准 MCP 协议接入调用。

极简模式（`apps/cli/config/agent-presets/minimal/agent.cordis.yml`）是 deepseek-harness 官方提供的最小双工具编码智能体，仅暴露两个工具：

- **`bash`** — 持久 bash（PTY 会话，跨调用共享 cwd / 环境变量 / 函数 / 后台任务）
- **`str_replace_editor`** — `view` / `create` / `str_replace` / `insert` 文件编辑

本实现**自研复刻并对齐原版语义**（`@deepseek-ai/dsh-tool-bash-persistent` 与 `@deepseek-ai/dsh-tool-str-replace-editor`），不依赖完整 harness 运行时，跨平台、轻量、可独立运行。

## 工具语义（与原版对齐）

### `bash`
- 真实 PTY 持久 shell，命令间状态持久。
- 非零退出码追加注释：`[exit code: N]`。
- 输出超过上限截断并标记 `<response clipped>`。
- 超时返回部分输出并重置 shell。

### `str_replace_editor`
- `view`：文件按 `cat -n` 风格加行号；目录列出非隐藏项、向下两级。
- `create`：仅当路径不存在时创建，否则报错。
- `str_replace`：`old_str` 必须唯一逐字匹配，多匹配 / 零匹配报错。
- `insert`：`insert_line` 0-based，插入不额外加尾换行。

## 安装与构建

```bash
pnpm install
pnpm run build
```

> 首次安装会执行 `postinstall` 脚本，修复 `node-pty` 预编译二进制在 macOS 上的执行权限（缺失会导致 `posix_spawnp failed`）。

## 运行

```bash
node dist/index.js
```

### 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `DSH_CWD` | `process.cwd()` | bash 与文件系统工具的工作目录 |
| `DSH_BASH_TIMEOUT_MS` | `60000` | 单条命令超时（毫秒），超时自动重置 shell 防卡死 |
| `DSH_MAX_OUTPUT_CHARS` | `16000` | 命令 / 文件输出保留字符上限 |
| `DSH_SHELL` | `/bin/bash` | 用于 spawn 的 shell 路径 |

## 接入配置

以 Claude / 通用 MCP 客户端为例，在你的 MCP 配置中加入：

```json
{
  "mcpServers": {
    "dsh-minimal": {
      "command": "node",
      "args": ["/absolute/path/to/dsh-mcp-tools/dist/index.js"],
      "env": {
        "DSH_CWD": "/your/workspace"
      }
    }
  }
}
```

一次服务调用暴露两个工具：`bash` 与 `str_replace_editor`，即为 deepseek-harness 极简模式的编码能力全集。

## 目录结构

```
src/
  index.ts   # MCP server 入口，注册两个工具（stdio 传输）
  config.ts  # 环境变量解析与描述文本
  bash.ts    # 持久 bash（node-pty）
  editor.ts  # str_replace_editor
scripts/
  fix-node-pty-perms.mjs  # 安装后修复 node-pty 二进制权限
```

## 说明
- 传输方式为 **stdio**（MCP 标准，面向本地 agent）。如需 streamable-HTTP 可扩展。
- 原版 bash 描述中提到"可通过镜像访问 apt/pip 包"等环境信息，本实现保留该描述文本但实际网络能力取决于运行环境。