mcp-dev-server MCP Server

mcp-shell-yeah

**Model Context Protocol（MCP）**サーバーです。サーバー、ビルドウォッチャー、テストランナーなど、長時間実行されるローカル開発タスクをAIエージェントが確実に管理するのが難しいという、よくある課題を解決するために設計されています。こうしたバックグラウンドシェルは、複数の会話にまたがって保持する必要があることが多く、状態やログの確認には、壊れやすいカスタムスクリプトや手動での操作が必要です。mcp-shell-yeahは標準化されたMCPインターフェースを提供し、AIエージェントがこうした重要なシェルプロセスを確実に起動、監視、ログの取得、停止できるようにして、AIを活用した開発ワークフローを効率化します。

---

クイックスタート：Cursor に追加

"mcp-shell-yeah": {
  "command": "npx",
  "args": ["mcp-shell-yeah@latest"]
}

---

🚀 Cursor Proになりませんか？ 🏆

Cursorで高度なワークフロー、ヒント、実践的なAI開発戦略を習得しましょう。
木曜日にライブワークショップを週1〜2回開催しています。

👉 egghead.io/workshop/cursor

---

主な機能

• 長時間実行されるシェルの起動と管理： 開発サーバー、テストランナー、ビルドスクリプトなどを起動、管理します。
• 会話をまたいでシェルの状態を保持： シェルは保持され、今後のチャットでも確認や制御ができます。
• リアルタイムの状態確認： プロセスが実行中、クラッシュ、停止のいずれかをすぐに確認できます。
• シェル出力ログへの確実なアクセス： 管理対象のシェルの最新ログまたは全ログを取得します。
• 特定のシェルまたは管理対象のすべてのシェルを停止： 必要に応じてプロセスを正常終了または強制終了します。
• 対話型シェルへの入力送信： プロンプトやコマンドラインツールを操作します。

---

よくある使用例

• 開発サーバーを起動する： npm run devを起動し、新しいチャットでも後からAIにログや状態を確認させます。
• テストランナーを監視する： npm run test:watchを実行し、セッションをまたいでAIにテストの失敗を監視させます。
• 長時間のビルドを追跡する： 時間のかかるbuildコマンドを開始し、休憩後に完了状態を確認します。
• 応答しなくなったプロセスを再起動する： 開発サーバーが応答しなくなった場合、AIに特定のサーバーの再起動を依頼します。

---

API リファレンス

ツールとAPIの詳細なドキュメント（パラメーター、JSON構造など）については、API.mdを参照してください。

---

開発環境のセットアップ

前提条件：

• Node.js（v20.x以降を推奨）
• pnpm（推奨）またはnpm

手順：

1. リポジトリをクローンします：

   git clone https://github.com/johnlindquist/mcp-shell-yeah.git # Replace with actual repo URL
   cd mcp-shell-yeah
   

2. 依存関係をインストールします：

   pnpm install
   # or
   # npm install
   

3. プロジェクトをビルドします：

   pnpm run build
   # or
   # npm run build
   

4. ビルドしたサーバーをローカルで実行します：

   node build/index.js
   

---

既知の制限事項

• 対話型プロンプトの取得： 一部の対話型プロンプト（特に bash や python スクリプトからのもの）は、既知の回避策をすべて適用しても、PTY ログに記録されない場合があります。Node.js ベースのプロンプトは確実に記録されます。詳細については、API ドキュメントを参照してください。
• Node.js Readline プロンプト： PTY の制限により、Node.js readline のプロンプトがログに表示されない場合があります。これは既知の Node.js／PTY の問題です。
• macOS での OSC 133 プロンプト検出： macOS（bash 3.2）では、OSC 133 のプロンプトシーケンスが確実に検出されない場合があります。フォールバックとして、ヒューリスティックによるプロンプト検出が使用されます。

---

技術スタック

• Node.js / TypeScript
• @modelcontextprotocol/sdk：MCP サーバーのコアフレームワーク
• node-pty：堅牢な疑似端末プロセス管理
• zod：実行時検証
• biomejs：フォーマットとリンティング
• semantic-release：バージョン管理と公開の自動化

---

MCP への準拠

このプロジェクトは、ツールのレスポンスと型の使用に関して、公式の Model Context Protocol（MCP）標準に厳密に準拠しています。すべての結果／コンテンツ型は、@modelcontextprotocol/sdk/types.js（ESM との互換性のため .js を付加）から直接インポートしています。ツールの結果やコンテンツに対するカスタム型定義は許可されていません。すべてのツール実装とヘルパーは、MCP の仕様で定められた { content: [...], isError?: boolean } 構造を返します。

---

コントリビューター向けガイドライン、内部メモ、高度な統合の詳細については、CONTRIBUTING.md と API.md を参照してください。

機能

• プロセスの開始： 指定した作業ディレクトリ内で、シェルコマンドを使って新しいバックグラウンドプロセスを起動します。
• 状態の監視： プロセスが起動中、実行中、検証中、停止中、再起動中、クラッシュ状態、またはエラー状態かどうかを確認します。
• ログの表示： 管理対象プロセスの最近の出力（stdout／stderr）を取得します。
• プロセスの停止： 特定のプロセスを正常に終了（SIGTERM）するか、強制終了（SIGKILL）します。
• すべて停止： サーバーインスタンスが管理するすべてのプロセスを終了します。
• プロセスの再起動： 特定のプロセスを停止してから再起動します。
• 状態を待機： プロセスが目的の状態（例：'running'）になるまで実行を一時停止します。
• 任意のラベル： プロセスにカスタムラベルを付けるか、コマンドと作業ディレクトリに基づいてサーバーにラベルを生成させます。
• 自動クリーンアップ： 基本的なゾンビプロセスの検出機能を備え、シャットダウン時に管理対象プロセスの終了を試みます。
• Cursor-tail の強化された指示： バックグラウンドプロセスの開始時に、Cursor IDE ユーザー向けの指示を強化します。
• 自動削除： 停止したプロセスはプロセスリストから自動的に削除されます。削除済みのプロセスを問い合わせると、停止状態と空のログが返されます。

利用可能なツール

このサーバーは、MCP クライアントに次のツールを公開します。

• start_shell：新しいバックグラウンドプロセスを起動します。（ラベルは省略可能です）ログに URL が含まれている場合、AI はそれらを抽出し、Markdown リンクとして返します。

• start_shell_with_verification：検証、タイムアウト、再試行オプションを指定して、新しいバックグラウンドプロセスを起動します。（ラベルは省略可能です）

• check_shell：特定のプロセスのステータスとログを確認します。（ラベルが必要です）ログに URL が含まれている場合、AI はそれらを抽出し、Markdown リンクとして返します。

• stop_shell：特定のプロセスを停止します。（ラベルが必要です）

• list_shells：現在管理されているすべてのプロセスと、その基本的なステータスを一覧表示します。

• stop_all_shells：管理対象のすべてのプロセスの停止を試みます。

• restart_shell：特定のプロセスを再起動します。（ラベルが必要です）

• wait_for_shell：特定のプロセスが目標のステータスになるまで待機します。（ラベルが必要です）

• get_all_loglines：特定の管理対象プロセスについて、保存されているログ履歴全体を取得します。（ラベルが必要です）

• send_input：実行中のプロセスの stdin にテキスト入力を送信します。（ラベルが必要です）

  新しい動作： 入力を送信すると、このツールは 1 秒待機してから、更新されたログとプロセスのステータスを含む check_shell の呼び出し結果を返します。これにより、入力がプロセスに及ぼした即時の影響を確認できます。

  例：

  // Integration test snippet
  const sendInputRequest = {
    jsonrpc: "2.0",
    method: "tools/call",
    params: {
      name: "send_input",
      arguments: { label, input: 'echo "hello from send_input"' },
    },
    id: `req-sendinput-${label}`,
  };
  const sendInputResponse = (await sendRequest(serverProcess, sendInputRequest));
  const sendInputResult = JSON.parse(sendInputResponse.result.content[0].text);
  // sendInputResult.logs will include "hello from send_input"
  // sendInputResult.status will reflect the updated process state
  

• health_check：プロセスマネージャー自体のステータス概要を提供します。

クイックスタート：サーバーの実行

MCP Process Manager を実行する最も簡単な方法は npx を使用することです。手動でインストールしなくても、公開されている最新バージョンを確実に使用できます。

1. ターミナルを開きます。
2. サーバーを実行します：

   npx mcp-shell-yeah
   

3. サーバーが起動します： このコマンドは、必要に応じて mcp-shell-yeah サーバーをダウンロードし、実行します。初期化ログを stderr に出力した後、標準入力（stdin）で MCP メッセージを待ち受け、標準出力（stdout）に応答を送信します。

MCP クライアントまたはオーケストレーターを設定すると、このプロセスの stdio ストリームを介して通信できるようになります。

開発環境のセットアップ

サーバーを変更したり、開発に貢献したりする場合：

前提条件：

• Node.js（v20.x 以降を推奨）
• npm（通常は Node.js に含まれています）または pnpm

手順：

1. リポジトリをクローンします：

   git clone https://github.com/johnlindquist/mcp-shell-yeah.git # Replace with actual repo URL
   cd mcp-shell-yeah
   

2. 依存関係をインストールします：

   npm install
   # or if using pnpm:
   # pnpm install
   

3. プロジェクトをビルドします： これにより、TypeScript コードが build/ ディレクトリ内の JavaScript にコンパイルされます。

   npm run build
   

4. ビルドしたサーバーをローカルで実行します： コンパイル済みコードを Node で直接実行します。

   node build/index.js
   

   サーバーは npx 版と同様に起動し、stdio で待ち受けます。

5. （任意）変更を監視します： 積極的に開発する場合は、監視スクリプトを実行できます。ソースファイル（src/**/*.ts）を保存すると、プロジェクトが自動的に再ビルドされます。

   npm run watch
   

   更新したコードを実行するには、再ビルドのたびに node build/index.js プロセスを手動で再起動する必要があります。

開発に関する注意事項：

• コードベースは、明確さと保守性を高めるためにモジュール化されています。
• 型と定数は一元管理されています。
• 明確さと速度を高めるため、統合テストと単体テストを分けています。
• すべてのテストとヘルパーは、MCP の結果形式（result.content[]）を想定しています。
• コードベース全体で、型安全性と MCP への準拠が厳格に適用されています。

技術スタック

• Node.js / TypeScript
• @modelcontextprotocol/sdk：MCP サーバーのコアフレームワークです。
• node-pty：堅牢な疑似端末プロセス管理に使用します。
• zod：ツールパラメーターの実行時検証に使用します。
• biomejs：フォーマットとリンティングに使用します。
• semantic-release：バージョン管理と公開の自動化に使用します。

MCP への準拠

このプロジェクトは、ツールの応答と型の使用について、公式の Model Context Protocol（MCP）標準に厳格に準拠しています。

• すべてのツール結果／コンテンツの型は、@modelcontextprotocol/sdk/types.js から直接インポートします（ESM との互換性のため、.js を付けます）。
• ツールの結果やコンテンツに関する独自の型定義は許可されていません。
• すべてのツール実装とヘルパーは、MCP 仕様で定められた { content: [...], isError?: boolean } の構造を返す必要があります。
• テストとヘルパーは、新しい形式（例：従来の形式ではなく result.content[0].text）を想定する必要があります。
• テストヘルパーと型アサーションは、新しい形式に一致している必要があります。

例については、[src/mcpUtils.ts]、[src/toolImplementations.ts]、および [tests/integration/test-helpers.ts] を参照してください。

重要な概念（2024）

• 命令形式の AI 指示： 応答内の ai_instructions フィールドは、AI が次に行うべきことを示す唯一の信頼できる情報源になりました。このフィールドは常に存在し、強く明確な表現が使われます（例：「必須：このシェルの出力を監視するため、バックグラウンドターミナルで run_terminal_cmd ツールを使って tail_command を直ちに実行してください（このコマンドはブロックする可能性があります）。また、検出された detected_urls の各エントリを、クリック可能な Markdown リンクとして必ずユーザーに表示してください。これらの手順を省略しないでください。」）。
• バックグラウンドターミナルの使用が必須： tail_command はブロックする可能性があるため、AI は必ずバックグラウンドターミナルで実行する必要があります。フォアグラウンドでは実行しないでください。
• URL の抽出： ログで見つかった URL はすべて detected_urls 配列に返されます。AI はこれらを必ずクリック可能な Markdown リンクとしてユーザーに表示する必要があります。

ツール一覧

このセクションでは、mcp-shell-yeah が提供するツールについて説明します。

start_shell

バックグラウンドプロセス（開発サーバーやスクリプトなど）を起動して管理します。

パラメーター：

• command（文字列、必須）：実行するコマンド。
• workingDirectory（文字列、必須）：コマンドを実行する絶対パスの作業ディレクトリ。この設定は必須です。'.' や '../' などの相対パスは使用しないでください。完全なパスを指定してください（例：/Users/me/myproject）。
• label（文字列、任意）：任意の人が読みやすい識別子（例：'dev-server'）。空欄にすると、サーバーが CWD とコマンドに基づいて生成します。
• args（文字列の配列、任意、デフォルト：[]）：コマンドに渡す任意の引数。
• host（文字列、任意、列挙型："cursor"、"claude"、"chatgpt"、"vscode"、"windsurf"、"unknown"、デフォルト："unknown"）：プロセスを開始するクライアントの識別子。応答や手順を適切に調整するために使用します。

戻り値：（JSON）

start_shell の呼び出しが成功した場合のレスポンスペイロードです。label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、message、logs、monitoring_hint、info_message、および（ログ内で URL が見つかった場合は）detected_urls などのフィールドが含まれます。AI は URL を抽出し、Markdown リンクとして返す必要があります。

• ai_instructions（文字列、必須）：AI はこのフィールドの指示に必ず従う必要があります。このフィールドには、tail_command を必ずバックグラウンドターミナルで実行し（ブロックする可能性があるため、フォアグラウンドでは実行しない）、すべての detected_urls をクリック可能な Markdown リンクとして表示するよう、常に AI に指示します。AI はこれらの手順を省略したり、先延ばしにしたりしてはなりません。
• user_hint（文字列、任意）：次に何をすべきかを示す、ユーザー向けのヒント。

失敗した場合は、error、status、cwd、error_type などを含む可能性のあるエラーオブジェクトを返します。

使用例：

{
  "command": "npm",
  "args": ["run", "dev"],
  "workingDirectory": "/path/to/my-web-app",
  "label": "webapp-dev-server",
  "host": "cursor"
}

start_shell_with_verification

検証（パターン、タイムアウト、再試行）を行いながら、バックグラウンドプロセスを起動します。

パラメーター：

• command（文字列、必須）：実行するコマンド。
• workingDirectory（文字列、必須）：コマンドを実行する絶対パスの作業ディレクトリ。この設定は必須です。'.' や '../' などの相対パスは使用しないでください。完全なパスを指定してください（例：/Users/me/myproject）。
• label（文字列、任意）：任意の人が読みやすい識別子（例：'dev-server'）。空欄にすると、サーバーが CWD とコマンドに基づいて生成します。
• args（文字列の配列、任意、デフォルト：[]）：コマンドに渡す任意の引数。
• host（文字列、任意、列挙型："cursor"、"claude"、"chatgpt"、"vscode"、"windsurf"、"unknown"、デフォルト："unknown"）：プロセスを開始するクライアントの識別子。応答や手順を適切に調整するために使用します。
• verification_pattern（文字列、任意）：起動の成功を確認するために、標準出力／標準エラー出力で照合する任意の正規表現パターン。例：'running on port 3000' または 'localhost'。
• verification_timeout_ms（整数、任意、デフォルト：-1）：検証パターンを待つ時間（ミリ秒）。-1 にするとタイマーは無効になります（デフォルト）。
• retry_delay_ms（整数、任意）：クラッシュしたプロセスを再起動するまでの任意の待機時間（ミリ秒、デフォルト：1000ms）。
• max_retries（整数、任意）：クラッシュしたプロセスの再起動を試みる最大回数（デフォルト：3）。0 にすると再起動は無効になります。

戻り値：（JSON）

start_shell_with_verification の呼び出しが成功した場合のレスポンスペイロードです。label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、message、logs、monitoring_hint、info_message などのフィールドが含まれます。

• instructions（文字列、任意）：host に "cursor" が指定され、ファイルへのログ記録が有効な場合、このフィールドには Cursor IDE 向けの推奨手順が含まれます。たとえば、tail_command を実行するためのバックグラウンドターミナルの起動方法などです。 失敗した場合は、error、status、cwd、error_type などを含む可能性のあるエラーオブジェクトを返します。

使用例：

{
  "command": "npm",
  "args": ["run", "dev"],
  "workingDirectory": "/path/to/my-web-app",
  "label": "webapp-dev-server",
  "host": "cursor",
  "verification_pattern": "ready - started server on",
  "verification_timeout_ms": 30000,
  "retry_delay_ms": 1000,
  "max_retries": 3
}

check_shell

最近のログを含め、管理対象プロセスの現在の状態を確認します。

パラメーター：

• label（string、必須）：確認するプロセスのラベルです。
• log_lines（integer、省略可能、デフォルト：20）：取得する最近のログ行数です。デフォルトは20です。保存される最大行数は1000です。保存済みの履歴全体（最大1000行）を取得するには、'getAllLoglines' を使用してください。

戻り値：（JSON）

check_shell のレスポンスペイロードです。label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、logs、hint、および detected_urls（ログ内でURLが見つかった場合）が含まれます。AI は見つかったURLを抽出し、Markdownリンクとして返してください。

• ai_instructions（string、必須）：AI はこのフィールドの指示に必ず従ってください。これには、バックグラウンドターミナルで tail_command を実行し、すべての detected_urls をMarkdownリンクとして表示することも含まれます。

使用例：

{
  "label": "webapp-dev-server",
  "log_lines": 50
}

list_shells

現在管理されているすべてのプロセスとその状態を一覧表示します。

パラメーター：

• log_lines（integer、省略可能、デフォルト：0）：各プロセスに含める最近のログ行数です（デフォルトは0で、ログ行は含まれません）。

戻り値：（JSON）

list_shells のレスポンスペイロードで、プロセスの詳細を含む配列が格納されています。各詳細オブジェクトには、label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、logs、log_hint などのフィールドが含まれます。

使用例：

{
  "log_lines": 10
}

stop_shell

指定した管理対象プロセスを停止します。

パラメーター：

• label（string、必須）：停止するプロセスのラベルです。
• force（boolean、省略可能、デフォルト：false）：正常終了させるためのSIGTERMの代わりにSIGKILLを使用して、プロセスを強制終了します。デフォルトはfalseです。

戻り値：（JSON）

stop_shell のレスポンスペイロードです。label、status、message、pid などのフィールドが含まれます。

使用例：

{
  "label": "webapp-dev-server",
  "force": true
}

stop_all_shells

管理対象のすべてのプロセスを正常に停止しようとします。

パラメーター： なし

戻り値：（JSON）

stop_all_shells のレスポンスペイロードです。summary 文字列と details 配列が含まれます。各詳細オブジェクトには、label、result（例：SignalSent、Skipped、Failed）、status、pid が含まれます。

使用例：

{}

restart_shell

指定した管理対象プロセスを再起動します（実行中の場合は停止してから、元の設定で再度起動します）。

パラメーター：

• label（string、必須）：再起動するプロセスのラベルです。

戻り値：（JSON）

restart_shell の呼び出しが成功した場合のレスポンスペイロードです（構造は start_shell の成功時と同じです）。失敗した場合は、`

既知の制限事項：対話型プロンプトのキャプチャ

一部の対話型プロンプト（特に bash および python スクリプトによるもの）は、既知のすべての回避策（例：stdbuf、script、バッファーなしの環境変数）を使用しても、PTYログにキャプチャされない場合があります。これは、OSレベルおよび言語レベルの出力バッファリングが原因であり、常に外部から回避できるとは限りません。

• Node.jsベースのプロンプトは確実にキャプチャされます。
• すべての言語のエコー／出力は確実にキャプチャされます。
• プロセスマネージャーにプロンプトを確実に表示させる必要がある場合は、Node.jsベースのCLIを使用するか、ツールが出力を明示的にフラッシュするようにしてください。
• これはPTYおよびバッファリングの動作に起因する根本的な制限であり、プロセスマネージャーのバグではありません。

既知の制限事項：Node.js の Readline プロンプトと PTY キャプチャ

Node.js の readline プロンプトは、ログに表示されなかったり、入力待ちのプロンプトとして検出されなかったりする場合があります。

• Node.js の readline ライブラリは、プロンプトをプロセスの stdout ストリーム経由ではなく、ターミナルデバイスに直接書き込むことがあります。
• PTY ベースのプロセスマネージャーでは、このためプロンプトがログに表示されなかったり、プロンプト検出のヒューリスティックが起動しなかったりすることがあります。
• これは、Node.js の readline と PTY の相互作用に関する、よく知られた制限事項です（Node.js の issue #29589 を参照）。
• その他すべての種類のプロンプト（bash、python、node のカスタム CLI など）は、正しくキャプチャおよび検出されます。
• ログにプロンプトが表示されない場合、ほとんどの場合、プログラムが実際にはプロンプトを出力していないか、パーサーが無視するエスケープシーケンスを使用しています。

テストカバレッジ：

• Node.js の readline プロンプト検出に関する統合テストは含まれていますが、この制限事項を記録し、PTY または Node.js の動作が将来改善された場合に検知できるよう、スキップされています。

既知の制限事項：macOS での OSC 133 プロンプト検出

• macOS（bash 3.2）では、シェルから OSC 133 のプロンプトシーケンス（例：\x1b]133;B\x07）を出力しても、安定して動作しません。
• printf を直接使ったり、シェルのプロンプトを設定したりしても、期待されるエスケープシーケンスが PTY バッファーに現れません。
• これは検出ロジックではなく、シェル／環境の制限事項です。
• そのため、OSC 133 によるプロンプト検出テストはスキップされており、テストファイルに詳細なコメントが記載されています。
• フォールバックとして、ヒューリスティックによるプロンプト検出（例：行末が :、? などで終わる場合）が使用されており、ほとんどの対話型 CLI のユースケースでは十分です。
• OSC 133 の堅牢な検出が必要な場合は、新しいバージョンの bash または zsh シェルが使える Linux 環境でテストを実行することを検討してください。