Ssh Liaison MCP

🚀 SSH Liaison MCP Server

Model Context Protocol (MCP) を介したステートフルな SSH 接続とコマンド実行を行います。

🚀 クイックスタート

このサーバーの主な機能は、ステートフルな SSH セッションを提供することです。各 SSH 接続は永続的なシェルセッションを維持し、MCP ツールの呼び出し間で状態（現在のディレクトリ、環境変数など）が保持されます。これにより、コマンドが相互に依存する自然な多段階ワークフローが可能になります。

✨ 主な機能

📦 インストール

事前ビルド済みバイナリ

リリースページ から、お使いのプラットフォーム用の最新リリースをダウンロードしてください。

対応プラットフォーム:

• macOS (Intel x86_64、Apple Silicon aarch64)
• Linux (x86_64、aarch64)
• Windows (x86_64)

# macOS (Apple Silicon)
curl -LO https://github.com/Citizen4our/ssh-liaison-mcp/releases/latest/download/ssh-liaison-mcp-aarch64-apple-darwin.tar.gz
tar -xzf ssh-liaison-mcp-aarch64-apple-darwin.tar.gz

# macOS (Intel)
curl -LO https://github.com/Citizen4our/ssh-liaison-mcp/releases/latest/download/ssh-liaison-mcp-x86_64-apple-darwin.tar.gz
tar -xzf ssh-liaison-mcp-x86_64-apple-darwin.tar.gz

# Linux (x86_64)
curl -LO https://github.com/Citizen4our/ssh-liaison-mcp/releases/latest/download/ssh-liaison-mcp-x86_64-unknown-linux-gnu.tar.gz
tar -xzf ssh-liaison-mcp-x86_64-unknown-linux-gnu.tar.gz

ソースからビルド

git clone https://github.com/Citizen4our/ssh-liaison-mcp.git
cd ssh-liaison-mcp
cargo build --release

バイナリは target/release/ssh-liaison-mcp に配置されます。

💻 使用例

MCP サーバーモード（主な使用ケース）

ステートフルセッションの仕組み

ssh_connect を使用してホストに接続すると、永続的なシェルセッションが確立されます。そのホストに対するすべての後続の ssh_run_command 呼び出しは、同じシェルセッション で実行されます。つまり、以下のことが保証されます。

• 現在のディレクトリが保持される：あるコマンドで cd /var/log を実行した場合、次のコマンドは /var/log から開始されます。
• 環境変数が持続する：export で設定した変数は、後続のコマンドでも使用可能です。
• シェルの状態が維持される：履歴、エイリアス、その他のシェル状態は、呼び出し間で保持されます。
• 効率的：各コマンドごとに再接続したり、コンテキストを再確立する必要はありません。

ワークフロー例:

1. ssh_connect("production") → 永続的なシェルを確立
2. ssh_run_command("production", "cd /var/log") → ディレクトリを変更
3. ssh_run_command("production", "pwd") → 「/var/log」を返す（状態が保持されている！）
4. ssh_run_command("production", "ls -la") → /var/log のファイルを一覧表示

Cursor IDE の場合

1. バイナリをビルドする：

cargo build --release

2. Cursor の設定に追加する (~/.cursor/mcp.json または Cursor の設定 UI)：

{
  "mcpServers": {
    "ssh-liaison": {
      "command": "/absolute/path/to/ssh-liaison-mcp",
      "args": ["serve"]
    }
  }
}

3. Cursor を再起動する

Claude Desktop の場合

1. バイナリをビルドする：

cargo build --release

2. Claude Desktop の設定に追加する (~/Library/Application Support/Claude/claude_desktop_config.json on macOS)：

{
  "mcpServers": {
    "ssh-liaison": {
      "command": "/absolute/path/to/ssh-liaison-mcp",
      "args": ["serve"]
    }
  }
}

3. Claude Desktop を再起動する

旧型式の直接接続モード

下位互換性のために、以下のコマンドを使用できます。

cargo run -- connect <user> <host> [--port <port>]

スタンドアロン CLI モード（デバッグ用）

テストやデバッグ用の対話型ターミナルモードです。接続問題のトラブルシューティングやコマンドの手動テストに役立ちます。

接続方法

1. SSH 設定のエイリアスを使用する

# ~/.ssh/config のエイリアスを使用してすぐに接続
cargo run -- cli --host rpi
# または
./target/release/ssh-liaison-mcp cli --host rpi

2. コマンドラインで直接接続する

# SSH キーで直接接続（デフォルトポート 22）
cargo run -- cli --user pi --hostname 192.168.1.100

# カスタムポートで直接接続
cargo run -- cli --user pi --hostname 192.168.1.100 --port 2222

# パスワード認証で直接接続
cargo run -- cli --user pi --hostname 192.168.1.100 --password mypassword

# パスワードとカスタムポートで直接接続
cargo run -- cli --user pi --hostname 192.168.1.100 --password mypassword --port 2222

接続例

# 例 1: SSH 設定を介して接続
cargo run -- cli --host production

# 例 2: Raspberry Pi に直接接続
cargo run -- cli --user pi --hostname 192.168.1.100

# 例 3: パスワードでカスタムポートに直接接続
cargo run -- cli --user admin --hostname server.example.com --password secret --port 2222

# 例 4: 対話型モード - 後で接続
cargo run -- cli
ssh> connect dev-server
[dev-server]> uname -a
[dev-server]> exit

🔧 技術詳細

SSH 設定

サーバーは ~/.ssh/config からホストのエイリアスを読み取ります。これは接続設定を一元管理するため、推奨される接続方法です。

SSH 設定例

# シンプルなホストエイリアス
Host rpi
    HostName 192.168.1.100
    User pi
    Port 22
    IdentityFile ~/.ssh/id_ed25519

# カスタムポートの本番サーバー
Host production
    HostName prod.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/deploy_key

# 開発サーバー
Host dev
    HostName dev.example.com
    User developer
    IdentityFile ~/.ssh/id_rsa

MCP ツール

MCP サーバーとして実行する場合、以下のツールが利用可能です。

重要な注意事項:

• ステートフル：同じホストに対するすべてのコマンドは、同じ永続的なシェルセッションで実行されます。
• 接続方法：
  • ssh_connect を使用して SSH 設定ベースの接続を行います（~/.ssh/config が必要）。
  • ssh_connect_direct を使用して、SSH 設定を必要としない直接接続を行います。
• 認証順序 (ssh_connect_direct の場合)：
  1. SSH キー（SSH エージェント、次に一般的なキーファイル）
  2. パスワード（提供され、SSH キーが失敗した場合）
• セッションの持続性：接続されると、セッションは MCP サーバーが再起動されるか、明示的に切断されるまでアクティブなままです。
• セキュリティ：ssh_connect_direct のパスワードは、SSH プロトコルを介して安全に送信されます（暗号化されています）。可能な場合は、SSH キー認証を使用することをお勧めします。

MCP モードのプロンプト例

MCP サーバーを設定すると、AI アシスタントに SSH 操作を依頼することができます。 例 1:

User: Connect to rpi and show me the current directory and disk usage

AI の応答:

I'll connect to rpi and check the current directory and disk usage for you.

[Connecting to rpi...]

Current directory: /home/pi
Disk usage:
Filesystem      Size  Used Avail Use% Mounted on
/dev/root        15G  5.2G  8.8G  38% /
/dev/mmcblk0p1  253M   49M  204M  20% /boot

例 2:

User: Connect to production and read the last 50 lines from /var/log/nginx/error.log

AI の応答:

I'll connect to production and read the last 50 lines from the nginx error log.

[Connecting to production...]

Last 50 lines from /var/log/nginx/error.log:
2024-01-15 10:23:45 [error] 12345#0: *123 connect() failed (111: Connection refused)
2024-01-15 10:24:12 [error] 12345#0: *124 upstream timed out
...

例 3:

User: Connect directly to 192.168.88.63 as user pi and show disk usage

AI の応答:

I'll connect directly to 192.168.88.63 as user pi and check the disk usage.

[Connecting to 192.168.88.63 using SSH keys...]

Disk usage:
Filesystem      Size  Used Avail Use% Mounted on
/dev/root        15G  5.2G  8.8G  38% /
/dev/mmcblk0p1  253M   49M  204M  20% /boot

例 3b (パスワード付き):

User: Connect to 192.168.88.63 as user admin with password mypass123 and check uptime

AI の応答:

I'll connect to 192.168.88.63 as user admin and check the system uptime.

[Connecting to 192.168.88.63...]
[SSH key authentication failed, trying password...]

System uptime: 5 days, 12 hours, 30 minutes

例 4:

User: Check system uptime and memory usage on the dev server

AI の応答:

I'll check the system uptime and memory usage on the dev server.

[Connecting to dev...]

System uptime: 15 days, 3 hours, 22 minutes
Memory usage:
              total        used        free      shared  buff/cache   available
Mem:           7.8G        2.1G        3.2G        128M        2.5G        5.4G
Swap:          2.0G          0B        2.0G

例 5:

User: Show me running processes and check if nginx service is running on production

AI の応答:

I'll check the running processes and verify if nginx is running on production.

[Connecting to production...]

Nginx service status: active (running)
Top processes by CPU:
  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
 1234 nginx     20   0  123456   4567   1234 S   2.3   0.1   0:05:23 nginx
 5678 app       20   0  234567   8901   2345 S   1.8   0.2   0:12:45 app
...

ステートフルセッションの例

この例は、コマンド間で状態が保持されることを示しています。

User: Connect to rpi, navigate to /var/log, and show me the last 10 lines of syslog

AI の応答:

I'll connect to rpi, navigate to /var/log, and show you the last 10 lines of syslog.

[Connecting to rpi...]
[Changing directory to /var/log...]

Last 10 lines of syslog:
Jan 15 10:23:45 rpi systemd[1]: Started Network Manager.
Jan 15 10:24:12 rpi sshd[1234]: Accepted publickey for pi from 192.168.1.50
...

内部で行われた処理:

1. ssh_connect("rpi") - 永続的なシェルセッションを確立
2. ssh_run_command("rpi", "cd /var/log") - ディレクトリを変更（状態を保存）
3. ssh_run_command("rpi", "tail -n 10 syslog") - /var/log から実行（状態が保持されている！）

2 番目のコマンドは、前のコマンドからシェルの状態が保持されているため、自動的に /var/log から開始されました。

🔐 認証

ssh_connect（SSH 設定）の場合

サーバーは、以下の順序で認証を試みます。

1. SSH エージェント（利用可能な場合）
2. SSH 設定からの Identity ファイル
3. 一般的な SSH キー（順序）：

• ~/.ssh/id_ed25519
• ~/.ssh/id_rsa
• ~/.ssh/id_ecdsa
• ~/.ssh/id_dsa

ssh_connect_direct（直接接続）の場合

1. SSH キー（上記と同じ順序）
2. パスワード（提供され、SSH キーが失敗した場合または利用できない場合）

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

• 読み取り専用操作を推奨：ツールには破壊的な操作に関する警告が含まれています。
• パスワードの取り扱い：sudo パスワードの入力サポートは計画されていますが、まだ完全に実装されていません。
• パスワードのログ記録なし：パスワードは決してログに記録されたり、公開されたりすることはありません。

🧪 開発

# 開発モードで実行
cargo run -- cli --host <your-host>

# リリース用にビルド
cargo build --release

# テストを実行
cargo test

# リントを実行
cargo clippy --all-targets -- -D warnings

# コードをフォーマット
cargo fmt

📊 ロギング

サーバーは tracing クレートを介して構造化ロギングを使用しています。ログの詳細度は、以下の方法で制御できます。

コマンドラインフラグ

# デフォルト（警告のみ）
ssh-liaison-mcp serve

# 情報レベル (-v)
ssh-liaison-mcp -v serve

# デバッグレベル (-vv)
ssh-liaison-mcp -vv serve

# トレースレベル (-vvv)
ssh-liaison-mcp -vvv serve

環境変数

# RUST_LOG を介してログレベルを設定
RUST_LOG=debug ssh-liaison-mcp serve

# 特定のモジュールを対象にする
RUST_LOG=ssh_liaison_mcp=debug ssh-liaison-mcp serve

# 複数の対象
RUST_LOG=ssh_liaison_mcp::ssh=trace,ssh_liaison_mcp::mcp=debug ssh-liaison-mcp serve

📋 今後の予定 / 改善点

インフラストラクチャと配布

• [x] CI/CD パイプライン (GitHub Actions)
  • [x] プッシュ/PR 時の自動テスト
  • [x] リントとフォーマットチェック (clippy、rustfmt)
  • [x] 複数のプラットフォーム向けのビルド (Linux、macOS、Windows)
  • [x] 自動リリースワークフロー
• [x] リリース自動化
  • [x] リリース作成用の GitHub Actions ワークフロー
  • [x] 主要なプラットフォーム向けの自動バイナリビルド
  • [x] 事前ビルド済みバイナリを含む GitHub リリース
  • [ ] バージョンの自動更新
• [ ] Crates.io への公開
  • [x] クレートのメタデータを準備（説明、キーワード、カテゴリ）
  • [ ] クレートのドキュメントを追加
  • [ ] Crates.io に公開

機能

• [ ] Sudo パスワードの入力
  • [ ] sudo コマンドのパスワードプロンプトの処理を実装
  • [ ] MCP プロンプトを介した安全なパスワード入力
  • [ ] セッション中のパスワードキャッシュ
• [ ] セッション管理
  • [ ] ssh_disconnect ツールでセッションを明示的に閉じる
  • [ ] ssh_list_sessions ツールでアクティブな接続を表示
  • [ ] タイムアウト時の自動セッションクリーンアップ
  • [ ] セッションのヘルスチェックと再接続
• [ ] エラーハンドリングの強化
  • [ ] コンテキスト付きのより良いエラーメッセージ
  • [ ] 接続リトライロジック
  • [ ] ネットワーク中断の適切な処理
  • [ ] セッションの回復メカニズム
• [ ] ファイル操作
  • [ ] リモートファイルを読み取る ssh_read_file ツール
  • [ ] （安全チェック付きの）ssh_write_file ツール
  • [ ] ディレクトリの一覧を表示する ssh_list_directory ツール
  • [ ] バイナリファイル転送のサポート
• [ ] 監視と可観測性
  • [ ] 接続状態の監視
  • [ ] オプションの詳細ログモード

コード品質

• [ ] テスト
  • [x] SSH 設定のパース用の単体テスト
  • [ ] MCP ツールの統合テスト
  • [ ] テスト用のモック SSH サーバー
  • [ ] CLI モードのテスト
• [ ] ドキュメント
  • [ ] API ドキュメント (rustdoc)
  • [ ] アーキテクチャドキュメント
  • [ ] コントリビュートガイドライン
  • [ ] セキュリティのベストプラクティスガイド
• [x] コードの改善
  • [x] エラーハンドリングパターンのリファクタリング
  • [x] 包括的なロギングの追加 (tracing)
  • [ ] パフォーマンスの最適化
  • [ ] コードカバレッジの改善

プラットフォームサポート

• [x] クロスプラットフォームのバイナリリリース
  • [x] Linux (x86_64、ARM64)
  • [x] macOS (Intel、Apple Silicon)
  • [x] Windows (x86_64)
• [ ] パッケージマネージャー
  • [ ] macOS 用の Homebrew フォーミュラ
  • [ ] Arch Linux 用の AUR パッケージ
  • [ ] Cargo install の手順

セキュリティの強化

• [ ] セキュリティ監査
  • [ ] 依存関係のセキュリティスキャン
  • [ ] コードのセキュリティレビュー
  • [ ] ペネトレーションテストの検討
• [ ] アクセス制御
  • [ ] オプションのホスト許可リスト/拒否リスト
  • [ ] コマンドのホワイトリスト/ブラックリスト
  • [ ] 接続のレート制限

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。