dsh-mcp-server

DeepSeek Harness의 Agent(dsh, 전체 도구 세트 포함: 파일, 터미널, 웹 검색, 하위 에이전트, 워크플로우 코딩 Agent)를 Model Context Protocol을 통해 로컬에서 사용 가능한 모델 백엔드로 노출하고, 동시에 "나를 읽기 / 나를 개조하기" 인터페이스를 노출합니다.

┌────────────────────────────┐        stdio / HTTP         ┌──────────────────────────────┐
│  其他 Agent / MCP 客户端     │  ────────────────────────▶  │        dsh-mcp-server         │
│  (Claude Desktop, Cursor,  │                            │  方向A：驱动我（消耗我的额度）  │
│   Claude Code, 自定义程序)   │                            │  方向B：读懂我/改造我（便宜）   │
└────────────────────────────┘                            └──────────────┬───────────────┘
                                                                         │ spawn
                                                              ┌──────────▼───────────────┐
                                                              │  dsh Agent（完整工具链）    │
                                                              │  DeepSeek 模型（默认）      │
                                                              └──────────────────────────┘

두 가지 방향

방향 A: 나를 구동하기 — DeepSeek Harness 크레딧 소모, 사용자 확인 필수

dsh_ask / dsh_converse / dsh_tool 호출 시마다 완전한 dsh Agent 프로세스가 실행되며, 해당 프로세스가 (DeepSeek 모델로) 실제 작업을 수행합니다: 파일 읽기/쓰기, 명령 실행, 웹 검색, 하위 에이전트 파견. 이는 DeepSeek Harness의 토큰 크레딧을 소모합니다, 따라서:

1. 호출은 먼저 confirmation_required를 반환하며(이 시점에는 크레딧이 소모되지 않음), "DeepSeek Harness 크레딧이 소모됩니다"라고 명확히 안내합니다;

2. 호출자는 이 요청을 사용자에게 표시해야 합니다(MCP 클라이언트는 일반적으로 도구 호출을 자동으로 표시합니다);

3. 사용자가 승인한 후 dsh_confirm(requestId, approve=true)를 호출해야 실제로 실행됩니다; 또는 dsh_deny(requestId)로 취소합니다.

각 대기 중인 요청은 서버 stderr에도 눈에 띄는 경고 한 줄을 출력합니다. 확인되지 않은 요청은 10분 후 만료됩니다.

⚠️ 위험 스위치: DSH_MCP_AUTO_APPROVE=1은 확인 게이트를 건너뜁니다(무인/완전 신뢰 환경에 적합). 단일 호출에서도 confirm: false를 전달하여 건너뛸 수 있습니다.

방향 B: 나를 읽기 / 나를 개조하기 — 상대방의 토큰 소모, 서버 측은 매우 저렴

다른 Agent가 "내가 무엇인지, 어떻게 설계되었는지, 나를 위한 플러그인/설정 변경을 어떻게 만드는지"를 이해하려 할 때 이 인터페이스를 사용합니다(서버는 로컬 읽기/검증만 수행하며, dsh 모델 크레딧을 소모하지 않습니다; 상대방 모델이 결과를 자신의 컨텍스트로 읽어들이므로, 소모되는 것은 상대방 자신의 토큰입니다):

일반적인 사용법: 외부 Agent가 먼저 dsh://self/* 리소스를 읽어 설계를 이해하고(자신의 토큰 소모), 그 다음 dsh_patch_config를 호출하여 설정 변경을 제안하거나(예: 모델 교체, 새 스킬 마운트, 특정 플러그인 비활성화), dsh_plugin_contract에 따라 로컬에 dsh 플러그인을 작성합니다.

Related MCP server: dsh-orchestrator

빠른 시작

cd E:\DeepSeek Harness\dsh-mcp
npm install          # 安装 @modelcontextprotocol/sdk

# 冒烟测试：不经过 MCP，直接验证 dsh Agent 后端可用
node scripts/smoke.mjs

# 以 stdio 传输启动服务器（MCP 客户端的标准方式）
node src/index.js

서버는 로컬에 설치된 dsh를 자동으로 발견합니다(npx 캐시 / npm 캐시 / 현재 디렉터리 스캔), 별도 설정 불필요. 찾지 못한 경우 환경 변수로 지정: DSH_MCP_DSH_BIN=C:\...\@deepseek-ai\dsh\lib\bin.js.

Claude Desktop 연동

%APPDATA%\Claude\claude_desktop_config.json 편집:

{
  "mcpServers": {
    "dsh": {
      "command": "node",
      "args": ["E:\\DeepSeek Harness\\dsh-mcp\\src\\index.js"]
    }
  }
}

Claude Code / Cursor / VS Code 연동

각각 examples/claude-code.json, examples/cursor-mcp.json, examples/vscode.json 사용.

자체 Agent 연동(HTTP 방식)

node src/index.js --transport http --port 3005
# 端点：http://127.0.0.1:3005/mcp  （Streamable HTTP）

도구 목록

환경 변수

권한 및 보안

• dsh Agent는 dsh 권한 체계를 상속: 기본 workspace-write(작업 디렉터리만 쓰기 가능), read-only / danger-full-access로 조정 가능.

• 방향 A의 모든 실행은 확인 게이트를 거치며, 크레딧 소모가 명확히 공개됩니다.

• 방향 B의 읽기 전용 경로는 어떤 비밀 키 값도 마스킹하지 않습니다; 쓰기 경로(dsh_patch_config)는 기본 dry-run, 디스크 쓰기 전 자동 백업, 확인 필요, home 레이어 변경 시 모든 profile(실행 중인 Web UI 포함)에 영향을 준다는 경고가 표시됩니다.

• 세션은 ~/.dsh/sessions에 영속화되고, 자격 증명은 ~/.dsh/.credentials.yaml을 공유합니다.

• 서버는 로컬에서만 수신합니다(stdio 파이프 / 127.0.0.1).

모델 교체(방향 B의 일반적인 사용법)

기본 모델은 dsh의 agent-default-model(로컬 deepseek-official / deepseek-v4-flash)에서 가져옵니다. 변경 방법:

1. dsh_patch_config 사용(권장): home 레이어에 patch 제출, dry-run 검증 통과 후 사용자 확인 후 쓰기(자동 백업). 예시 patch:

   - id: agent-default-model
     config:
       provider: deepseek-official
       model: deepseek-chat

2. 전역 설정 변경: ~/.dsh/settings.yaml의 agent-default-model 섹션 편집.

3. 전체 profile 교체: DSH_MCP_PROFILE로 다른 profile 지정(다른 도구 세트/페르소나).

알려진 제한 사항

• 방향 A는 호출마다 새 프로세스(약 2~3초 콜드 스타트 + 모델 응답), 스트리밍 없음, 작업 텍스트 ≤ ~30k 문자.

• 확인 게이트는 호출자가 confirmation_required를 사용자에게 표시하는 것에 의존합니다; 호출자가 무인 프로그램이고 DSH_MCP_AUTO_APPROVE를 설정하지 않은 경우, 요청은 만료될 때까지 계속 대기합니다.

• 리소스/도구 수: 리소스 6개 + 도구 11개.

개발 및 테스트

node scripts/smoke.mjs              # 仅测 dsh 后端（无 MCP）
node scripts/demo.mjs               # 演示：确认闸门 + 读懂我 + 改配置提议
node scripts/mcp-client-test.mjs    # stdio 端到端：闸门/拒绝/多轮/自省/patch/资源
node scripts/http-client-test.mjs   # HTTP 端到端（自动批准模式）

디렉터리 구조

dsh-mcp/
├── src/
│   ├── index.js     # CLI 入口（stdio / HTTP 传输）
│   ├── server.js    # MCP 工具与资源注册
│   ├── dsh.js       # dsh 子进程运行器（spawn/超时/输出捕获/并发闸门）
│   ├── approvals.js # 确认闸门（额度披露、待确认队列、过期）
│   ├── self.js      # 自省：设计快照、技能发现、配置路径、插件契约
│   └── sessions.js  # 会话记忆与多轮提示组装
├── scripts/         # 冒烟 + 演示 + 端到端测试
└── examples/        # 各客户端接入配置