mcp-console-automation

コンソール自動化 MCP サーバー

ローカルのコンソールアプリケーションやリモート SSH セッションを制御して操作するための Model Context Protocol（MCP）サーバーです。出力の監視、エラー検出、長時間実行ワークフローに対応しています。

セキュリティ状況

このサーバーは任意のコマンドを実行し、リモート SSH セッションを開くことができます。リスクの低いドキュメント接続ツールではなく、特権ターミナルとして扱ってください。

• コマンドやセッションの変更操作では、MCP ツールの承認を有効にしておいてください。
• インラインのシークレットよりも、SSH キーまたは環境変数による認証情報の参照を優先してください。
• 制限付きのデプロイ用アカウントを使用し、本番環境では別途承認手順を設けてください。
• 診断が明示的に必要な場合を除き、MCP_DEBUG_LOG と MCP_LOG_DIR は未設定のままにしてください。
• 復旧用メタデータが明示的に必要な場合を除き、セッションの永続化は無効のままにしてください。
• クラウド、コンテナー、シリアルの統合機能は、必要な場合にのみインストールしてください。

機能

🚀 主な機能

• ターミナルの完全制御：最大50個のコンソールセッションを作成・管理できます。
• マルチプロトコル対応：ローカルシェル（cmd、PowerShell、pwsh、bash、zsh、sh）とリモート SSH 接続に対応しています。
• インタラクティブ入力：テキスト入力や特殊キーシーケンス（Enter、Tab、Ctrl+C など）を送信できます。
• リアルタイム出力監視：高度な検索機能を使って、コンソール出力を取得、フィルタリング、分析できます。
• ストリーミング対応：パターンマッチングを用いて、長時間実行プロセスを効率的にストリーミングできます。
• 自動エラー検出：複数の言語にわたって、エラー、例外、スタックトレースを検出する組み込みパターンを備えています。
• クロスプラットフォーム：ネイティブ依存関係なしで Windows、macOS、Linux で動作します。

🔐 SSH とリモート接続

• SSH の完全サポート：パスフレーズに対応した、パスワード認証と鍵ベース認証を利用できます。
• SSH オプション：カスタムポート、接続タイムアウト、キープアライブ設定に対応しています。
• 接続プロファイル：再利用可能な SSH メタデータと、環境変数による認証情報の参照を保存できます。
• クラウドプラットフォーム対応：保存済みプロファイルを使って、Azure、AWS、GCP、Kubernetes に接続できます。
• コンテナー対応：コンテナー化されたワークフロー向けに Docker と WSL を統合できます。

✅ テスト自動化フレームワーク

• 自動テストケース：コンソール出力を検証するための組み込みアサーションツールを備えています。
• 出力アサーション：出力に特定の内容が含まれるか、正規表現に一致するか、期待値と等しいかを検証できます。
• 終了コードの検証：コマンドの終了コードをアサートして、成功または失敗を検出できます。
• エラーなしの検証：コマンド出力にエラーがないか自動的に確認します。
• 状態スナップショット：操作の前後にセッション状態を保存して比較できます。
• テストワークフロー：アサーションを連結して、包括的なテストシナリオを構成できます。

🔄 バックグラウンドジョブの実行

• 非同期コマンド実行：長時間実行コマンドをバックグラウンドで実行し、出力をすべて取得できます。
• 優先度キューシステム：ジョブに優先度（1～10）を設定して、リソースを最適に活用できます。
• ジョブ監視：バックグラウンドジョブのステータス、進行状況、完了を追跡できます。
• ジョブ制御：バックグラウンド処理をキャンセル、一時停止、再開できます。
• 結果の取得：完了したジョブの出力全体と終了コードを取得できます。
• リソース管理：保持期間を設定して、完了したジョブを自動的にクリーンアップします。

📊 エンタープライズ監視とアラート

• システム全体のメトリクス：CPU、メモリ、ディスク、ネットワークの使用状況を追跡します。
• セッションメトリクス：セッションごとのパフォーマンス監視とリソース消費量の追跡を行います。
• リアルタイムダッシュボード：カスタマイズ可能なビューで、監視データをリアルタイムに表示します。
• アラートシステム：重大度レベル付きのパフォーマンス、エラー、セキュリティ、異常アラートを提供します。
• カスタム監視：セッションごとに監視間隔、メトリクス、しきい値を設定できます。
• 診断：エラー分析とセッションの健全性検証機能を組み込んでいます。

📁 プロファイル管理

• 接続プロファイル：SSH、Docker、WSL、クラウドプラットフォームへの接続を保存します
• アプリケーションプロファイル：よく使うコマンド設定を保存します（Node.js、Python、.NET、Java、Go、Rust）
• クイック接続：保存したプロファイルを使って、設定を上書きしながらすぐに接続できます
• 環境変数：プロファイルごとに環境設定を保存します
• 作業ディレクトリ管理：各プロファイルのデフォルトディレクトリを設定します

🔍 高度な出力処理

• 正規表現フィルタリング：正規表現を使って出力を検索します（大文字と小文字を区別／区別しない）
• 複数パターン検索：複数のパターンを AND／OR ロジックで組み合わせます
• ページネーション：出力の指定した行範囲、先頭、または末尾を取得します
• 時間ベースのフィルタリング：タイムスタンプ（絶対時間、または相対時間：'5m'、'1h'、'2d'）で出力をフィルタリングします
• 出力ストリーミング：長時間実行されるプロセスの出力をリアルタイムで取得します
• バッファー管理：出力バッファーを消去してメモリー使用量を削減します

クイックインストール

Windows

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
.\install.ps1 -Target codex

macOS/Linux

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
chmod +x install.sh
./install.sh --target codex

手動インストール

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
npm ci
npm run build
codex mcp add console-automation --env LOG_LEVEL=warn -- node "$PWD/dist/mcp/server.js"

設定

Codex は MCP 設定を ~/.codex/config.toml に保存します。インストーラーは codex mcp add を使用し、既存の console-automation 登録を安全に置き換えます。インストール後に Codex を再起動し、/mcp を使って接続を確認してください。

別の MCP クライアントを使用する場合は、既存のファイルを上書きせずに新しい JSON 設定を生成します。

.\install.ps1 -Target custom -CustomPath C:\path\to\new-mcp-config.json

npm パッケージは公開されていないため、npx console-automation-mcp と @mcp/console-automation は有効なインストール方法ではありません。

保存済み SSH 認証情報

console_save_profile は、パスワード、秘密鍵の内容、パスフレーズの直接入力を拒否します。passwordEnvVar、privateKeyEnvVar または privateKeyPath、passphraseEnvVar を使用してください。プロファイル一覧の応答に認証情報の値が含まれることはありません。また、OS が POSIX モードをサポートしている場合、設定ファイルは所有者のみがアクセスできる権限で作成されます。

セッションの永続化

セッションの永続化はデフォルトで無効になっています。セッションの復元データにはコマンド、パス、環境変数の値が含まれる場合があるためです。有効にするには、MCP_SESSION_PERSISTENCE=true を設定してください。デフォルトのファイルは ~/.console-automation-mcp/sessions.json です。MCP_SESSION_PERSISTENCE_PATH で変更できます。永続化されたコマンド／環境の復元データは、プログラムから SessionManager 設定で有効にしない限り無効のままです。

本番用インストーラーでは、開発用およびオプションのプロトコルパッケージが削除されます。ローカルコンソールと SSH は引き続き利用できます。Docker、クラウド、Kubernetes、シリアルなどのオプションアダプターに必要なピアパッケージのみをインストールしてください。

利用可能なツール（合計40）

この MCP サーバーは、6つのカテゴリに分類された40個の包括的なツールを提供します。

📚 完全なドキュメント

• ツールリファレンス全文 - 40個すべてのツールに関する詳細なドキュメント
• 実践的な例 - 実際の使用例とパターン
• 公開ガイド - このサーバーをレジストリに登録する方法

ツールのカテゴリ

🖥️ セッション管理（9個のツール）

• console_create_session - ローカルまたは SSH のコンソールセッションを作成します
• console_send_input - セッションにテキスト入力を送信します
• console_send_key - 特殊キー（Enter、Ctrl+C など）を送信します
• console_get_output - 高度な検索機能でフィルタリング／ページネーションされた出力を取得します
• console_get_stream - 長時間実行されるプロセスの出力をストリーミングします
• console_wait_for_output - 指定したパターンが現れるまで待機します
• console_stop_session - セッションを停止します
• console_list_sessions - アクティブなセッションをすべて一覧表示します
• console_cleanup_sessions - 非アクティブなセッションをクリーンアップします

⚡ コマンド実行（6個のツール）

• console_execute_command - 出力を取得しながらコマンドを実行します
• console_detect_errors - 出力を分析してエラーを検出します
• console_get_resource_usage - システムリソースの統計情報を取得します
• console_clear_output - 出力バッファーを消去します
• console_get_session_state - セッションの実行状態を取得します
• console_get_command_history - コマンド履歴を表示します

📊 監視とアラート（6 ツール）

• console_get_system_metrics - システムの包括的なメトリクス
• console_get_session_metrics - セッション固有のメトリクス
• console_get_alerts - アクティブな監視アラート
• console_get_monitoring_dashboard - リアルタイムのダッシュボードデータ
• console_start_monitoring - カスタム監視を開始
• console_stop_monitoring - 監視を停止

📁 プロファイル管理（4 ツール）

• console_save_profile - SSH／アプリ接続プロファイルを保存
• console_list_profiles - 保存済みプロファイルを一覧表示
• console_remove_profile - プロファイルを削除
• console_use_profile - 保存済みプロファイルを使ってすばやく接続

🔄 バックグラウンドジョブ（9 ツール）

• console_execute_async - コマンドを非同期で実行
• console_get_job_status - ジョブのステータスを確認
• console_get_job_output - ジョブの出力を取得
• console_cancel_job - 実行中のジョブをキャンセル
• console_list_jobs - すべてのバックグラウンドジョブを一覧表示
• console_get_job_progress - ジョブの進行状況を監視
• console_get_job_result - ジョブの結果全体を取得
• console_get_job_metrics - ジョブ実行の統計情報
• console_cleanup_jobs - 完了したジョブをクリーンアップ

✅ テスト自動化（6 ツール）

• console_assert_output - 出力が条件を満たすことを検証
• console_assert_exit_code - 終了コードを検証
• console_assert_no_errors - エラーが発生していないことを検証
• console_save_snapshot - セッション状態のスナップショットを保存
• console_compare_snapshots - 状態の差分を比較
• console_assert_state - セッション状態を検証

クイックスタートの例

ローカルセッションを作成

const session = await console_create_session({
  command: "npm",
  args: ["run", "dev"],
  detectErrors: true
});

SSH で接続

const session = await console_create_session({
  command: "bash",
  consoleType: "ssh",
  sshOptions: {
    host: "example.com",
    username: "user",
    privateKeyPath: "~/.ssh/id_rsa"
  }
});

アサーションを使ってテストを実行

const session = await console_create_session({
  command: "npm",
  args: ["test"]
});

await console_assert_output({
  sessionId: session.sessionId,
  assertionType: "contains",
  expected: "All tests passed"
});

バックグラウンドジョブを実行

const job = await console_execute_async({
  sessionId: session.sessionId,
  command: "npm run build",
  priority: 8
});

const status = await console_get_job_status({
  jobId: job.jobId
});

その他の例については、docs/EXAMPLES.md を参照してください。

ユースケース

1. 開発サーバーの実行と監視

// Create a session for the dev server
const session = await console_create_session({
  command: "npm",
  args: ["run", "dev"],
  detectErrors: true
});

// Wait for server to start
await console_wait_for_output({
  sessionId: session.sessionId,
  pattern: "Server running on",
  timeout: 10000
});

// Monitor for errors
const errors = await console_detect_errors({
  sessionId: session.sessionId
});

2. 対話型デバッグセッション

// Start a Python debugging session
const session = await console_create_session({
  command: "python",
  args: ["-m", "pdb", "script.py"]
});

// Set a breakpoint
await console_send_input({
  sessionId: session.sessionId,
  input: "b main\n"
});

// Continue execution
await console_send_input({
  sessionId: session.sessionId,
  input: "c\n"
});

// Step through code
await console_send_key({
  sessionId: session.sessionId,
  key: "n"
});

3. エラー検出を伴う自動テスト

// Run tests
const result = await console_execute_command({
  command: "pytest",
  args: ["tests/"],
  timeout: 30000
});

// Check for test failures
const errors = await console_detect_errors({
  text: result.output
});

if (errors.hasErrors) {
  console.log("Test failures detected:", errors);
}

4. 対話型 CLI ツールの自動化

// Start an interactive CLI tool
const session = await console_create_session({
  command: "mysql",
  args: ["-u", "root", "-p"]
});

// Enter password
await console_wait_for_output({
  sessionId: session.sessionId,
  pattern: "Enter password:"
});

await console_send_input({
  sessionId: session.sessionId,
  input: "mypassword\n"
});

// Run SQL commands
await console_send_input({
  sessionId: session.sessionId,
  input: "SHOW DATABASES;\n"
});

エラー検出パターン

サーバーには、一般的なエラーの種類を検出するためのパターンが組み込まれています。

• 一般的なエラー（error:、ERROR:、Error:）
• 例外（Exception:、exception）
• 警告（Warning:、WARNING:）
• 致命的エラー
• 失敗した操作
• 権限／アクセス拒否
• タイムアウト
• スタックトレース（Python、Java、Node.js）
• コンパイルエラー
• 構文エラー
• メモリエラー
• 接続エラー

開発

ソースからビルド

npm install
npm run build

開発モードで実行

npm run dev

テストを実行

npm test

型チェック

npm run typecheck

リンティング

npm run lint

アーキテクチャ

サーバーは以下を使用して構築されています。

• Node の子プロセスと ssh2：ローカルでのコマンド実行と SSH セッションに使用
• @modelcontextprotocol/sdk：MCP プロトコルの実装
• TypeScript：型安全性と開発者エクスペリエンスの向上
• Winston：構造化ログに使用

コアコンポーネント

1. ConsoleManager：ターミナルセッション、入出力、ライフサイクルを管理
2. ErrorDetector：出力を分析してエラーと例外を検出
3. MCP Server：MCP ツールを通じてコンソール機能を公開
4. Session Management：複数のコンソールセッションを同時に管理

要件

• Node.js >= 18.0.0
• Windows、macOS、または Linux のオペレーティングシステム
• シリアルポート連携を有効にする場合、任意のプラットフォームビルドツールが必要になることがあります。

テスト

静的検証、ビルド、MCP のスモークテスト、テストスイートを実行します。

npm run lint
npm run typecheck
npm run build
npm run test:mcp
npm run test:logger
npm run test:installer
npm run test:package
npm test

トラブルシューティング

よくある問題

1. 権限拒否エラー：サーバーにプロセスを起動する権限があることを確認してください
2. 任意のネイティブ依存関係に関するエラー：シリアルポート連携を有効にする場合に限り、プラットフォームビルドツールをインストールしてください
3. セッションが応答しない：コマンドで TTY 操作が必要かどうか確認してください
4. 出力が取得されない：アプリケーションによっては、stdout を経由せずにターミナルへ直接書き込む場合があります

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/AmazingFeature）
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュします（git push origin feature/AmazingFeature）
5. プルリクエストを作成します

ライセンス

MIT License — 詳細は LICENSE ファイルをご覧ください

サポート

問題や質問、提案がある場合は、GitHub で issue を作成してください： https://github.com/ooples/mcp-console-automation/issues

ロードマップ

• ターミナルの記録と再生のサポートを追加
• セッションの永続化と復元を実装
• 特定の言語向けのエラー検出パターンを追加
• ターミナルのマルチプレクシングをサポート（tmux/screen との統合）
• Web ベースのターミナルビューアー
• セッション共有とコラボレーション機能
• パフォーマンスプロファイリングツール
• 人気の CI/CD システムとの統合