# deepseek-agent-mcp

把 DeepSeek 智能体打包成 **MCP Server**，让别的 Agent（Claude Desktop、Cursor、DSH 自身、或任何 MCP 客户端）把它当工具调用。提供两个工具：

| 工具 | 能力 | 适用场景 |
|---|---|---|
| `delegate_task` | 裸模型 `deepseek-v4-pro`（无工具、无工作区） | 快速问答、分析、写作 |
| `run_agent_task` | **完整 DSH agent**：shell + 文件读写/编辑 + subagent + workflow + todo + 持久化，能真实改工作区 | 写代码、改文件、跑测试等真实任务 |

传输：`stdio`。运行时依赖：`@modelcontextprotocol/sdk` + `zod`（Node ≥ 20）。

## 1. 安装与启动

```bash
cd deepseek-agent-mcp
npm install        # 会顺便执行 prepare -> 编译出 dist/
npm run build      # 手动编译
npm start          # 运行 stdio MCP server（node dist/index.js）
```

### 凭据（API Key）

按顺序读取，命中即用：

1. 环境变量 `DEEPSEEK_API_KEY`
2. DSH 自己的凭据文件 `~/.dsh/.credentials.yaml`

> 第 2 条对 DSH 特别有用：DSH 的 stdio MCP 启动器会清除环境里看起来像凭据的变量，但凭据文件不受影响。

### 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `DEEPSEEK_API_KEY` | 从 `~/.dsh/.credentials.yaml` 回退 | DeepSeek API Key |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 端点 |
| `DEEPSEEK_MCP_MODEL` | `deepseek-v4-pro` | `delegate_task` 默认模型 |
| `DEEPSEEK_HARNESS_ROOT` | — | `run_agent_task` 用的 deepseek-harness checkout 路径（`run_agent_task` 的 `harness_root` 参数优先） |

## 2. 工具说明

### 2.1 `delegate_task` —— 裸模型

把任务交给 DeepSeek 模型，返回回答。无状态、无工具、不碰文件。

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `task` | string | ✅ | — | 任务/问题 |
| `system` | string | — | — | 可选系统提示 |
| `model` | enum | — | `deepseek-v4-pro` | `deepseek-v4-pro` / `deepseek-v4-flash` |
| `reasoning_effort` | enum | — | `high` | `off` / `high` / `max` |
| `max_tokens` | int | — | `8192` | 输出上限（≤256000） |

### 2.2 `run_agent_task` —— 完整 agent

启动一次 `dsh --profile headless "<task>"`，跑完整 DSH 编码 agent（shell、文件读写/编辑、subagent、workflow、todo、JSONL 持久化），在指定工作区里真实执行并修改文件，返回最终回答。

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `task` | string | ✅ | — | 任务（目标、涉及文件、验收标准） |
| `workspace` | string | — | server 进程 cwd | agent 操作的工作区目录 |
| `harness_root` | string | — | `$DEEPSEEK_HARNESS_ROOT` | deepseek-harness checkout 路径 |
| `profile` | enum | — | `headless` | 目前只支持 `headless` |
| `timeout_ms` | int | — | `600000` | 超时杀掉（默认 10 分钟） |

**前置条件**：本机要有一个已构建（`pnpm install` 过）的 deepseek-harness checkout，其 `apps/cli/lib/bin.js` 存在。首次运行 `dsh --profile headless` 会在 `~/.dsh/profiles/headless/` 自动初始化 profile（写几个小文件），属正常行为。

返回内容块：最终回答 → `[agent] ok=... exit=...` 状态 → 出错时带 `[stderr]` 诊断。退出码非 0 时 `isError=true`。

## 3. 接入不同的 Agent

### 3.1 接入 DSH（本机）

插到 `cordis.yml`（或作为 `--config` overlay），DSH 里的工具名会是 `mcp__deepseek__delegate_task` 和 `mcp__deepseek__run_agent_task`：

```yaml
- insert:
    - id: deepseek-agent-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: deepseek
        transport: stdio
        command: node
        args: ['D:/dsh/deepseek-agent-mcp/dist/index.js']
        cwd: D:/dsh/deepseek-agent-mcp
        env:
          DEEPSEEK_HARNESS_ROOT: 'D:/deepseek-harness'
        # 完整 agent + 思考型任务可能很久，放宽超时
        toolCallTimeoutMs: 900000
```

> DSH 的 stdio 启动器会清掉 `DSH_*` 和凭据类环境变量，但 `config.env` 里显式写的变量会在清洗**之后**合并进去，所以上面显式写 `DEEPSEEK_HARNESS_ROOT` 是安全的；`DEEPSEEK_API_KEY` 不必写，server 会从 `~/.dsh/.credentials.yaml` 读。

### 3.2 接入 Claude Desktop

`claude_desktop_config.json`（macOS `~/Library/Application Support/Claude/claude_desktop_config.json`，Windows `%APPDATA%\Claude\claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "deepseek": {
      "command": "node",
      "args": ["D:/dsh/deepseek-agent-mcp/dist/index.js"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DEEPSEEK_HARNESS_ROOT": "D:/deepseek-harness"
      }
    }
  }
}
```

### 3.3 接入 Cursor / 其它 `mcp.json` 客户端

`.cursor/mcp.json`（或通用 `.mcp.json`）：

```json
{
  "mcpServers": {
    "deepseek": {
      "command": "node",
      "args": ["D:/dsh/deepseek-agent-mcp/dist/index.js"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DEEPSEEK_HARNESS_ROOT": "D:/deepseek-harness"
      }
    }
  }
}
```

## 4. 验证

```bash
npm run build      # 编译
npm run test:api   # 直接打 DeepSeek API，验证 key/端点/模型/思考参数
npm run test:mcp   # 进程内 MCP 往返：listTools + delegate_task 真实调用 + run_agent_task 冒烟
npm run smoke      # （真实环境）通过 MCP stdio 起子进程，listTools + 一次真实 delegate_task
```

> `test:mcp` 用 SDK 的 `InMemoryTransport` 做完整 MCP 握手，不依赖子进程管道，因此也能在禁止 named-pipe 的沙箱里跑；`run_agent_task` 的完整 agent 冒烟需要真实环境（见下）。

## 5. 安全与边界（重要）

- **`run_agent_task` 会真实执行**：调用方等于把任务交给一个能跑 shell、能改文件的编码 agent。谁调用它，就等于授权它在 `workspace` 里做这些事——务必限制调用来源和工作区范围。
- **API Key 不回传**：key 只在 server 进程内存里、且只作为 HTTPS 请求头发给 `DEEPSEEK_BASE_URL`（默认官方端点）。工具返回、schema、日志都不含 key。详见上一轮说明。
- `delegate_task` 是**无状态**的裸模型，不带会话、工具、工作区。
- `run_agent_task` 每次调用是**独立的一次性会话**（新 session），不跨调用共享上下文。
- 模型/思考参数由 `~/.dsh/settings.yaml`（`agent-default-model`）决定，`run_agent_task` 走 DSH 的默认模型选择。

## 6. 可移植替代方案（Python SDK）

如果不想依赖一个本机 checkout，官方更「可携带」的入口是 **Python SDK** `deepseek-harness-sdk`，它捆绑运行时并复用同一套完整 agent 组合：

```python
from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-pro",
    cwd="/path/to/workspace",          # agent 可修改的工作区
    session_root="/path/to/.dsh-sessions",
) as harness:
    result = harness.run("fix the failing test")
    print(result.final_response, result.finish_reason)
```

它返回结构化 `RunResult`（`final_response`、`finish_reason`、`session_id`），且运行时子进程可跨调用复用。参考 `examples/jsonrpc-agent/minimal.py` 与 `python/sdk/README.md`。把这段包进一个 Python MCP server（`mcp` 包）即可得到同样效果、且自带运行时的版本；本仓库当前用 CLI 方案是因为它无需额外 `pip install` 和运行时构建。