Terminal Control

🚀 MCP ターミナルプロジェクトドキュメント

MCP ターミナルは、MCP プロトコルを通じて大規模言語モデルと統合し、ターミナルコマンドの実行と管理を実現するターミナル制御サーバーです。

🚀 クイックスタート

サーバーの起動

以下のコマンドを実行して、MCP ターミナルサーバーを起動します。

python -m src.mcp_terminal.stdiostream_server

✨ 主な機能

• 複数のターミナルコントローラーをサポート：子プロセス、AppleScript、iTerm2 API ベースのコントローラーを含みます。
• 標準的な MCP インターフェースを提供：他のシステムやサービスとの相互作用を容易にします。
• 拡張可能なアーキテクチャ：新しいターミナルコントローラーや機能モジュールの追加をサポートします。
• セキュリティ設計：権限制御とコマンドフィルタリングメカニズムを備え、実行環境の安全性を確保します。

📦 インストール

前提条件

1. オペレーティングシステム：Linux または macOS
2. Python バージョン：3.6 以上
3. 依存関係管理ツール：パッケージ管理に pip の使用をおすすめします。

uv を使用したインストール

uv mcp-terminal@latest

Makefile を使用したインストール

make install

💻 使用例

基本的な使用法

# 基本的な使用
mcp-terminal execute_command --command "ls"

# タイムアウト設定付きのコマンド実行
mcp-terminal execute_command --command "sleep 10" --timeout 5

📚 ドキュメント

Claude Desktop の設定

Claude Desktop で MCP ターミナルツールを追加します。

{
  "tools": {
    "mcp-terminal": {
      "type": "execute_command",
      "config": {
        "host": "localhost",
        "port": "1234"
      }
    }
  }
}

トラブルシューティング

一般的な問題と解決策

• 問題：MCP ターミナルサーバーに接続できない
  • 解決策：サーバーが実行中であることを確認し、ネットワーク設定が正しいことを確認します。
• 問題：コマンドの実行がタイムアウトする
  • 解決策：コマンドの待機タイムアウト時間を増やすか、呼び出されるコマンドのパフォーマンスを最適化します。

API 仕様

コマンドの実行

execute_command(
    command: str,
    wait_for_output: bool = True,
    timeout: int = 10
) -> dict

パラメータの説明：

• command：実行するターミナルコマンド。
• wait_for_output：コマンドの出力を待つかどうか。デフォルトは True。
• timeout：待機するタイムアウト時間（秒）。デフォルトは 10。

戻り値：

{
  "success": bool,
  "output": str,
  "error": str,
  "return_code": int,
  "warning": str
}

ターミナル情報の取得

get_terminal_info() -> dict

戻り値：

{
  "terminal_type": str,
  "platform": str
}

セキュリティに関する注意事項

• 権限制御：信頼できるソースのみが MCP ターミナルサーバーに接続できるようにします。
• コマンドフィルタリング：未承認の操作を防ぐため、コマンドのホワイトリストまたはブラックリストメカニズムを実装することをおすすめします。
• 監査ログ：実行されたコマンドの履歴を定期的にレビューします。

開発ガイド

ディレクトリ構成

プロジェクトルートディレクトリ/
├── mcp_terminal.py          # エントリースクリプト
├── pyproject.toml           # プロジェクト設定と依存関係管理
├── README.md                # ユーザードキュメント
├── Makefile                 # ビルドと実行スクリプト
└── src/
    ├── __init__.py
    └── mcp_terminal/
        ├── stdio_server.py   # 標準入出力サーバーの実装
        ├── controllers/      # ターミナルコントローラーモジュール
        │   ├── base.py       # 基本インターフェースの定義
        │   ├── subprocess.py  # 子プロセスコントローラーの実装
        │   ├── applescript.py # AppleScript コントローラーの実装
        │   └── iterm.py      # iTerm2 API コントローラーの実装
        └── tools/            # ツールモジュール
            └── terminal_tools.py  # ターミナル操作ツール関数

貢献ガイド

1. コード規約：PEP8 コーディング規約に従います。
2. テスト要件：新機能には単体テストと統合テストを追加します。
3. コミット手順：
   • コミット前にコードフォーマットをチェックします。
   • コミットメッセージには関連する変更の説明を含めます。

連絡先

• メール：support@mcp-terminal.com
• GitHub：https://github.com/mcpteam/mcp-terminal