MCP Terminal Server

MCP Terminal Server

Windows サービスとして実行でき、シェルコマンドの実行とその出力のストリーミングを行うエンドポイントを公開する、軽量な FastAPI サーバーです。

特長

• Windows サービスまたはデバッグモードで実行できます
• シェルコマンドを実行し、出力をリアルタイムでストリーミングします
• API キー認証に対応しています
• レート制限に対応しています
• 環境変数または設定ファイルで設定できます
• 堅牢なエラー処理とロギングを備えています
• 障害発生時にプロセスを自動的に再起動します

インストール

前提条件

• Windows オペレーティングシステム
• Python 3.7 以降
• 管理者権限（サービスのインストール時）

インストール手順

1. このリポジトリをクローンするか、ソースコードをダウンロードします
2. PowerShell を管理者として開きます
3. プロジェクトディレクトリに移動します
4. インストールスクリプトを実行します：

.\install_service.ps1

これにより、以下が実行されます：

• 必要な Python 依存関係をインストールします
• ランダムな API キーを生成します（または指定したキーを使用します）
• 設定ファイルを作成します
• Windows サービスをインストールして起動します

インストールオプション

以下のパラメーターを使って、インストールをカスタマイズできます：

.\install_service.ps1 -ApiKey "your-api-key" -Port 8080 -Host "127.0.0.1" -LogLevel "debug"

使用可能なパラメーター：

• -ApiKey：認証用のカスタム API キー
• -Port：サーバーのポート番号（デフォルト：8000）
• -Host：バインドするホストアドレス（デフォルト：0.0.0.0）
• -LogLevel：ログレベル（debug、info、warning、error、critical）
• -ConfigFile：カスタム設定ファイルのパス

設定

サーバーは以下を使って設定できます：

1. 環境変数
2. 設定ファイル（config.json）
3. インストール時のコマンドライン引数

設定ファイル

サンプル設定ファイル（config.json.sample）が用意されています。これを config.json にコピーして編集できます：

{
    "host": "0.0.0.0",
    "port": 8000,
    "log_level": "info",
    "log_file": "mcp_terminal_server.log",
    "max_log_size_mb": 10,
    "log_backup_count": 5,
    "restart_on_failure": true,
    "max_restart_attempts": 5,
    "restart_delay_seconds": 10,
    "shutdown_timeout_seconds": 30,
    "working_directory": null
}

環境変数

環境変数を使ってサーバーを設定することもできます：

• MCP_TERMINAL_API_KEY：認証用の API キー
• MCP_HOST：バインドするホストアドレス
• MCP_PORT：サーバーのポート番号
• MCP_LOG_LEVEL：ログレベル
• MCP_LOG_FILE：ログファイルのパス
• MCP_MAX_LOG_SIZE_MB：ログファイルの最大サイズ（MB）
• MCP_LOG_BACKUP_COUNT：保持するログのバックアップファイル数
• MCP_RESTART_ON_FAILURE：障害発生時にサーバーを再起動するかどうか
• MCP_MAX_RESTART_ATTEMPTS：再起動の最大試行回数
• MCP_RESTART_DELAY_SECONDS：再起動試行間の遅延時間
• MCP_SHUTDOWN_TIMEOUT_SECONDS：正常なシャットダウンのタイムアウト時間
• MCP_WORKING_DIRECTORY：サーバーの作業ディレクトリ

サービス管理

サービスコマンド

以下のコマンドを使ってサービスを管理できます：

# Install the service
python service.py install

# Start the service
python service.py start

# Stop the service
python service.py stop

# Restart the service
python service.py restart

# Remove the service
python service.py remove

# Update the service configuration
python service.py update

# Run in debug mode (not as a service)
python service.py debug

ログ

ログは設定されたログファイル（デフォルト：mcp_terminal_server.log）に保存されます。ログには以下が含まれます：

• サービスの起動／停止イベント
• コマンドの実行
• エラーと警告
• ヘルスチェックの結果

API の使用方法

テストクライアント

以下の特長を備えた堅牢なテストクライアントが用意されており、サーバーとのやり取りに使用できます：

• 使いやすさを高めるコマンドライン引数
• API キー認証への対応
• 読みやすさを高める色付きの出力
• 出力のファイルへの保存に対応
• 堅牢なエラー処理とロギング
• コマンド履歴に対応した対話モード
• サーバーのヘルスチェック機能

基本的な使い方

# Run a command
python test_client.py -c "dir" -k "your-api-key"

# Check server health
python test_client.py --health

# Interactive mode
python test_client.py -k "your-api-key"

# Save output to a file
python test_client.py -c "systeminfo" --save-output output.txt

# Specify server URL
python test_client.py -s "http://example.com:8000" -c "dir"

# Enable verbose output
python test_client.py -v -c "dir"

# Show version
python test_client.py --version

設定ファイル

テストクライアントは JSON 設定ファイルを使って設定できます。用意されているサンプルを基に client_config.json ファイルを作成します：

{
    "server_url": "http://localhost:8000",
    "api_key": "your-api-key-here",
    "timeout": 60,
    "verbose": false
}

次に、以下のように使用します：

python test_client.py --config client_config.json

環境変数

テストクライアントは、環境変数による設定にも対応しています：

• MCP_TERMINAL_API_KEY：認証用の API キー
• MCP_TERMINAL_SERVER_URL：サーバーの URL

API エンドポイント

• POST /run：コマンドを実行します

  • X-API-Key ヘッダーに API キーが必要です
  • リクエスト本文：{"command": "your command"}
  • コマンドの出力を含むストリーミングレスポンスを返します

• GET /health：サーバーの状態を確認します

  • {"status": "healthy", "active_sessions": 0} を返します

セキュリティに関する考慮事項

• 本番環境では、必ずデフォルトの API キーを変更してください
• サーバーへのアクセスをローカルのみに制限する場合は、ホストを 127.0.0.1 に設定してください
• 本番環境では、HTTPS の使用を検討してください
• サーバーは潜在的に危険なコマンドをブロックしますが、追加のセキュリティ対策が必要な場合があります

トラブルシューティング

• ログファイルでエラーを確認してください
• デバッグモードで実行して、コンソール出力を確認してください：python service.py debug
• サービスが実行中であることを確認してください：Get-Service -Name "MCP_Terminal_Server"
• Windows イベント ビューアーで、サービス関連のエラーを確認してください

ライセンス

MIT