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. 安装与启动

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：

- 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）：

{
  "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）：

{
  "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. 验证

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 组合：

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 和运行时构建。