director-shell-mcp

director-shell-mcp は、director モードのエージェント向けの小さな MCP サーバーです。MCP stdio トランスポートを使用して、ファイルの書き込み、Python データ探索コードの実行、シェルコマンドの実行、バックグラウンドジョブの監視を行うための制御された脱出ハッチを提供します。コマンドはエージェントがツールを明示的に呼び出した場合にのみ起動され、サーバー自体がシェルを実行することはありません。

インストール

Node.js 18 以降が必要です。このディレクトリから:

npm install

サーバーを直接実行するには:

node C:/path/to/director-shell-mcp/index.js

Related MCP server: shell-0

OMP 登録（プライマリ）

主要なクライアントは Oh My Pi (OMP) ハーネスです。ユーザーレベルの ~/.omp/agent/mcp.json（またはプロジェクトレベルの .omp/mcp.json）に、この正確な設定を追加してください:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

stdio サーバーの場合、type は省略できます。設定を編集した後、OMP で /mcp reload を実行し、次に /mcp test director-shell を実行してください。

汎用 MCP クライアント登録

他の MCP クライアントは通常、同等の stdio 登録を受け入れます:

{
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

ツールリファレンス

すべてのツールは MCP テキストコンテンツ内で JSON オブジェクトを返します。エラーは、文形式の error フィールドを持つ MCP ツールエラーとして返されます。

shell_run

コマンドを完了まで実行します。パラメータ:

• command (文字列、必須): コマンドテキスト。

• cwd (文字列、任意): 作業ディレクトリ。

• timeout_ms (整数、任意): デフォルトは 60,000、最大 600,000。

• shell (powershell、cmd、または bash、任意): デフォルトは Windows では PowerShell、それ以外では Bash。

結果には exit_code、duration_ms、stdout/stderr オブジェクトが含まれます。各ストリームには最大約 50 KiB のプレビューテキストが含まれます。ストリームがその上限を超える場合、そのオブジェクトには truncated: true と、完全なストリームを含む一時ファイルを指す full_output_path も含まれます。タイムアウトは、明確なメッセージと部分的な結果を含む MCP ツールエラーを返します。

write_file

UTF-8 テキストを絶対ファイルパスに書き込みます。パラメータ:

• path (文字列、必須): 絶対ファイルパス。

• content (文字列、必須): 書き込むテキスト。

• append (ブール値、任意): 置き換えではなく追記します。デフォルトは false。

• create_dirs (ブール値、任意): 存在しない親ディレクトリを作成します。デフォルトは true。

結果には path、bytes_written、created (呼び出し前にファイルが存在しなかったかどうか)、appended が含まれます。

edit_file

絶対パスの UTF-8 ファイル内のテキストを置き換えます。パラメータ:

• path (文字列、必須): 絶対ファイルパス。

• old_text (文字列、必須): 検索する空でないテキスト。

• new_text (文字列、必須): 置換テキスト。

• replace_all (ブール値、任意): すべての出現箇所を置き換えます。デフォルトは false。

replace_all がない場合、old_text は正確に 1 回出現する必要があります。0 回または複数回の一致は MCP ツールエラーを返し、ファイルは変更されません。結果には path と replacements が含まれます。

run_python

Python ソースコードを、出力とタイムアウトを制限して完了まで実行します。Windows では、サーバーは最初に py ランチャーを、次に python をプローブします。他のシステムでは、最初に python3、次に python をプローブし、最初に使用可能な実行可能ファイルをキャッシュします。パラメータ:

• code (文字列、必須): Python ソースコード。

• cwd (文字列、任意): Python プロセスの作業ディレクトリ。

• timeout_ms (整数、任意): デフォルトは 60,000、最大 600,000。

• args (文字列の配列、任意): sys.argv[1:] として渡される値。

結果には exit_code、duration_ms、stdout/stderr オブジェクト、python_executable が含まれます。出力ストリームは上限に達すると、shell_run と同じ動作で一時ファイルにスピルされます。タイムアウトは、明確なメッセージと部分的な結果を含む MCP ツールエラーを返します。

job_start

ツール呼び出しが返った後も継続するデタッチされたコマンドを開始します。パラメータ:

• command (文字列、必須)

• cwd (文字列、任意)

• shell (powershell、cmd、または bash、任意)

• name (文字列、任意、人間が読めるラベル)

結果には job_id、pid、log_paths (stdout、stderr、combined)、exit_marker パスが含まれます。メタデータは %LOCALAPPDATA%/director-shell-mcp/jobs/<jobId>/ の下に JSON として永続化されるため、サーバー再起動後もジョブは検出可能です。

job_status

ジョブの永続化された状態を読み取ります。パラメータ:

• job_id (文字列、必須): job_start によって返された ID。

• tail_lines (整数、任意): デフォルトは 40、最大 1,000。

結果には running、exit_code (利用可能な場合)、runtime_ms、started_at、結合ログからの output_tail が含まれます。デタッチされたラッパーは、コマンドが終了したときに exit_code.txt を書き込み、サーバー再起動後も終了コードを保持します。

job_kill

このサーバーによって開始されたジョブを終了します。job_id を受け入れます。Windows では taskkill /T /F を使用してラッパーのプロセスツリーを終了します。すでに完了したジョブは変更されません。

job_list

有効な永続化されたすべてのジョブを、job_id、任意の name、pid、running 状態、終了コード、開始時刻とともに一覧表示します。

grep_files

ripgrep を必要とせず、JavaScript 正規表現を使用して絶対ファイルまたはディレクトリを再帰的に検索します。検索は node_modules、.git、bin、obj、dist、target をスキップし、5 MiB を超えるファイルとバイナリファイルを無視し、結果制限で停止します。パラメータ:

• pattern (文字列、必須): JavaScript 正規表現ソース。

• path (文字列、必須): 絶対ファイルまたはディレクトリパス。

• glob (文字列、任意): * と ? を使用した単純なファイル名フィルター。

• case_sensitive (ブール値、任意): デフォルトは false。

• max_results (整数、任意): デフォルトは 200、最大 1,000。

• context_lines (整数、任意): 各一致の前後の行数。デフォルトは 0、最大 5。

結果には matches が file、line_number、line、before、after とともに含まれ、さらに files_scanned と truncated が含まれます。無効な正規表現は MCP ツールエラーを返します。

job_wait

既存のデタッチされたジョブが終了するのを待ち、永続化された終了マーカーを 500 ミリ秒ごとにポーリングします。パラメータ:

• job_id (文字列、必須): job_start によって返された ID。

• timeout_ms (整数、任意): デフォルトは 60,000、最大 600,000。

• tail_lines (整数、任意): デフォルトは 40、最大 1,000。

結果は job_status と同じフィールドを持ち、timed_out が追加されます。ジョブがまだ実行中に期限が切れた場合は、MCP エラーではなく、timed_out: true の通常の結果です。

lock_acquire と lock_release

%LOCALAPPDATA%/director-shell-mcp/locks/ の下に永続化された、エージェント間の名前付きミューテックスを提供します。名前には文字、数字、_、.、- のみを含めることができ、最大 64 文字です。lock_acquire は name (必須)、wait_ms (任意、デフォルトは 0、最大 600,000)、任意の note を受け入れます。name、UUID token、acquired_at を返します。取得はアトミックなディレクトリ作成を使用し、記録された所有者プロセスがもう存在しないロックを回復します。保持されたロックエラーは、その pid、存在する場合は note、期間を識別します。lock_release は name と所有者の token を受け入れます。間違ったトークンと空きロックはエラーであり、ロックは変更されません。

screenshot

Windows で System.Drawing と Windows API を使用して、仮想画面全体、または表示されているトップレベルウィンドウを PNG にキャプチャします。パラメータ:

• target (screen または window、任意): デフォルトは screen。

• window_title (文字列、window の場合は必須): 大文字と小文字を区別しない表示ウィンドウのタイトル部分文字列。

• output_path (絶対 .png、任意): デフォルトは一時出力ディレクトリ内のタイムスタンプ付きファイル。

結果には path、width、height、target、ウィンドウキャプチャの場合は一致した window_title が含まれます。非 Windows システムでは明確なサポートされていないエラーを返し、要求されたウィンドウが見つからない場合は明確な一致なしエラーを返します。

process_list

Windows で読み取り専用のプロセス一覧を返します。パラメータ:

• name_filter (文字列、任意): プロセス名または実行可能ファイルパスの大文字と小文字を区別しない部分文字列。

• max_results (整数、任意): デフォルトは 100、最大 1,000。

各プロセスには pid と name が含まれ、利用可能な場合は path、started_at、working_set_bytes も含まれます。結果には truncated も含まれます。

file_lockers

Restart Manager API を介して、Windows で既存のファイルを開いているプロセスを報告します。path (必須) を受け入れます。これは既存のファイルへの絶対パスである必要があり、{ path, lockers } を返します。各ロッカーには pid、app_name、app_type が含まれます。ロックされていないファイルは、空の lockers 配列を持つ成功した結果です。非 Windows システムでは明確なサポートされていないエラーを返します。

検証

軽量なエンドツーエンドのスモークテストを実行します (echo と PowerShell の sleep のみを使用):

npm run smoke

スモークテストは、stdio 上で新しい MCP サーバーを起動し、初期化を実行し、15 個すべてのツールを一覧表示し、ファイル書き込み、正確なテキスト編集、Python 実行と引数渡し、コマンド完了と出力キャプチャを実行し、実行中および終了後のデタッチされたジョブを検証し、grep、wait、ロック、スクリーンショット、プロセス一覧、Restart Manager ファイルロッカー検出を実行し、job_list による永続化をチェックし、コマンドタイムアウト処理を検証します。

ライセンス

MIT