deepseek-subagent-mcp

Claude Code、Codex、またはその他のMCPクライアントに、自身のサブエージェントにタスクを委任するのと同じように、DeepSeek Harnessエージェントを委任できる機能を提供します。

MCP（Model Context Protocol）は、コーディングエージェントが外部ツールを読み込むための標準です。DeepSeek Harnessは、DeepSeekがMITライセンスで2026年8月にリリースしたオープンソースのエージェントランタイムです。ファイル操作やシェルツールを備えたループ内のモデルです。このサーバーはその中間に位置します。別プロセスでHarnessエージェントを実行し、開始、監視、継続、停止のための6つのツールを公開します。

子エージェントは独自のコンテキストウィンドウを持ちます。それがポイントです。自己完結型のタスクを渡すと、子エージェントは自身のトークンを使ってファイルを処理し、トランスクリプトではなく結果を返します。

必要条件

• Python 3.11以降

• platform.deepseek.com からのDeepSeek APIキー

• Apple Silicon搭載のmacOS 14以降、またはx86-64もしくはarm64のLinux

Node.jsのインストールは不要です。Harnessランタイムは、deepseek-harness-sdk ホイール内に自己完結型の実行可能ファイルとして同梱されています。このホイールがプラットフォームの制限でもあります。macosx_14_0_arm64、manylinux_2_28_x86_64、manylinux_2_28_aarch64 のみを公開しており、それ以外のプラットフォーム（Windows、Intel Mac、macOS 13）ではインストールできません。

インストール

uvx --from git+https://github.com/gaztrabisme/deepseek-subagent-mcp deepseek-subagent-mcp

Claude Code

プロジェクト内の .mcp.json に追加するか、すべてのプロジェクトで ~/.claude.json に追加します。

{
  "mcpServers": {
    "deepseek-subagent": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp",
        "deepseek-subagent-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DSA_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Codex

~/.codex/config.toml に追加します。

[mcp_servers.deepseek-subagent]
command = "uvx"
args = ["--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp", "deepseek-subagent-mcp"]
env = { DEEPSEEK_API_KEY = "sk-...", DSA_WORKSPACE = "/path/to/your/project" }

ツール

実行はデフォルトで非同期です。コーディングタスクには数分かかることがあり、MCPクライアントは個々のツール呼び出しをタイムアウトさせるためです。dsh_delegate は作業がキューに入れられるとすぐに戻ります。dsh_await が待機を行い、その間に進捗を報告します。短いタスクの場合は、dsh_delegate に wait_seconds を渡して2回目の呼び出しをスキップします。

各 dsh_delegate は1つのエージェントを作成し、1つのランタイムプロセスと1つの永続化されたセッションを保持します。dsh_continue はそのセッションに再入するため、子エージェントは以前のターンをコンテキストに保持したままになります。

すべての委任は、どのように確認されるかを指定します

dsh_delegate には verification 引数が必要です。これはタスクが完了したことを証明するコマンドです。

dsh_delegate(task="Fix the failing date parser", verification="pytest -q tests/test_dates.py")

サーバーは、子エージェントが終了した後、エージェントのワークスペース内でそのコマンド自体を実行します。子エージェントが自身のテスト結果を報告することは主張であり、終了コードは事実です。エージェントが時期尚早に勝利を宣言することは、よく文書化された障害モードです。

コマンドは、子エージェント自身の呼び出しを実行前に制限するのと同じポリシーによって分類されます。呼び出し元は別のエージェントであり、プロンプトインジェクションの可能性があるため、「呼び出し元が要求した」という理由だけでは承認されません。本当に確認するものがない場合は verification="true" を渡します。明示的な嘘は、暗黙のデフォルトよりも優れています。

返されるもの

完全なトランスクリプトを返すサブエージェントは、その目的を無効にします。子エージェントの回答が DSA_SUMMARY_TOKENS より大きい場合、同じセッション内で、さらに1ターンとして、7つのセクション（目標、制約と優先事項、進捗、重要な決定、次のステップ、関連ファイル、重要なコンテキスト）からなるハンドオフサマリーに置き換えるよう求められます。これがMCP境界を越えるものです。

すでに上限以下の回答はそのまま返され、追加のターンは消費されません。生の応答は常に保持されます。dsh_transcript(run_id, raw=True)。

監視付き実行

子エージェントのツール呼び出しは、実行前にゲートされます。ランタイム内の PreToolUse フックが、提案された各呼び出しをこのサーバーに渡し、サーバーは許可または拒否を返します。拒否された呼び出しは、理由を含むブロックされたツール結果としてモデルに返され、モデルは適応します。

決定論的分類器が最初に判断し、ほとんどの呼び出しを決定します。ファイルの読み取り、ls、grep、バージョン管理の読み取り、ワークスペース自身のコードやテストの実行は、モデルを介さずに許可されます。特権コマンド、ワークスペース外の削除、シェルへのパイプ接続されたフェッチ、SSHキーや .env に触れるものは、無害に見える動詞であっても（cat ~/.ssh/id_rsa はシークレットに適用された読み取り専用ツールであるため）完全に拒否されます。分類器が分類できないものだけがエスカレーションされます。

エスカレーションは、クライアントがサポートする最良の階層で実行されます。起動時に解決され、dsh_list によって報告されます。

すべての階層はフェイルクローズです。到達不能なスーパーバイザー、タイムアウト、不正なリクエスト、またはどちらの機能もサポートしないクライアントは、すべて拒否を生成し、承認は決して行われません。

階層は一度選択されるのではなく、順に試行されます。エラー を起こした階層は次の階層にフォールスルーします。そのため、サンプリングを廃止したクライアント（2026-07-28仕様改訂で非推奨、現在も動作中）は、すべてを拒否する代わりに、あなたに問い合わせるようにダウングレードされます。タイムアウト した階層はフォールスルーしません。未回答の質問は「いいえ」であり、別のチャネルで再度問い合わせても待ち時間が2倍になるだけです。

ゲートを完全に無効にするには、DSA_SUPERVISOR=off を設定します。

スーパーバイザーに表示されるのは構造化された事実であり、子エージェントの散文ではありません。ツール、各パイプラインセグメントのプログラム、およびコマンドが名前を付ける各パスにワークスペース内か外かのフラグが付けられます。子エージェントはコマンドとその正当性の両方を記述します。自分のケースを主張できる子エージェントはそうするでしょう。静的に解決できないパス（$TMPDIR/out.txt など）は推測ではなく未解決として報告され、外部としてカウントされます。

examples/claude_supervisor.py は、実際のClaudeに対してパターン全体を実行します。これは、sampling 自体を提供しないクライアント向けです。

DEEPSEEK_API_KEY=sk-... uv run python examples/claude_supervisor.py

上限とコスト

委任されたエージェントはループ内で資金を消費するため、4つの独立した上限がそれを制限し、各実行は使用量を報告します。

ワイヤー上でターン途中のキャンセルはないため、すべての停止はプロセスの強制終了です。上限による強制終了は、実行自体が報告したものよりも常に優先されます。強制終了されたプロセスの出力は、成功として読み取られることはありません。

dsh_delegate、dsh_await、dsh_list はすべて、プロバイダーから報告されたトークン使用量（入力、出力、キャッシュの読み取りと書き込み、ステップ数）を合計して報告します。ステップごとの入力は意図的に合計されます。各リクエストは再送信されたプレフィックス全体に対して課金されるため、合計が委任の実際のコストになります。

設定

すべての設定はサーバープロセスの環境変数です。

これに依存する前に知っておくべき制限事項

これらは Harness SDK ワイヤプロトコルに由来するものであり、ここでの選択によるものではありません。

• ファイルシステムサンドボックスは bash をカバーしません。 dsh-fs-sandbox はモデルの write/edit ツールをワークスペースに制限しますが、dsh-bash-sandbox はバンドルされたランタイム実行可能ファイルに含まれていないため、bash 自体は制限されません。スーパーバイザーがこれをカバーします。スーパーバイザーは、bash を含むすべてのツールに対して、実行の上流でゲートをかけます。DSA_SUPERVISOR=off の場合、bash にはまったく境界がありません。ブランチやスクラッチディレクトリを指すようにしてください。

• サンドボックスはファイルへの影響のみを制限します — ネットワーク、プロセス、システムコールは制限しません。また、workspace-write はワークスペースルートだけでなく /tmp も許可します。

• キャンセルはプロセスを強制終了します。 ワイヤ上にターン途中のキャンセルはないため、dsh_cancel はランタイムを終了します。すでに書き込まれた編集はディスクに残り、その後セッションを再開することはできません。

• 回収されたエージェントのセッションは失われますが、その結果は失われません。 DSA_IDLE_TIMEOUT の後、プロセスは解放されます。dsh_await と dsh_transcript は完了した実行に対して引き続き機能しますが、dsh_continue は機能しません。

• セッションはプロセスが存続する限り存続します。 セッションごとのクローズはないため、エージェントの履歴とともにメモリが増加します。使い終わったエージェントはキャンセルしてください。

• 上流は開発者プレビューです。 deepseek-harness-sdk は ==0.1.0rc7 に固定されています。1週間のうちに2つのリリース候補が出荷されました。ワイヤが変更される可能性があります。

開発

uv sync
uv run pytest                  # 127 tests, no API key, no network
uv run ruff check .
uv run deepseek-subagent-mcp   # starts on stdio; a client drives it

ライブテストには実際のキーが必要でありトークンを消費するため、pytest では収集されません:

DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_task.py        # the product works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_result.py      # distillation and the archive
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_supervisor.py  # the gate works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_escalation.py  # both escalation tiers
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_limits.py      # reaper and deadline
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_mcp.py         # all six tools

CLAUDE.md にはアーキテクチャと上流の制約が記載されています。wiki/ には決定記録と測定された内容が含まれています。

ライセンス

MIT。