MCP Shellkeeper

🚀 🐚 MCP ShellKeeper

MCP ShellKeeperは、AIアシスタントに永続的なターミナルセッションとファイル転送機能を提供します。AIアシスタントを通じてサーバーにSSH接続し、コマンドを実行し、ファイルを転送することができ、ステートレスの制限を克服します。

🚀 クイックスタート

AIアシスタントを通じてサーバーへのSSH接続やコマンド実行、ファイル転送を行うために、MCP ShellKeeperを使用することができます。以下のセクションで、その機能や使い方を詳しく説明します。

✨ 主な機能

🔄 ステートフル実行

従来のAIはステートレスでコマンドを実行するため、コマンドがハングしたり、期待した結果が得られないことがあります。一方、ShellKeeperはステートフルな実行をサポートしており、AIがユーザーの質問間でコンテキストを維持することができます。

従来のAI (ステートレス)

あなた: "サーバーにSSH接続"
AI: ❌ コマンドが永久にハングする

あなた: "ファイルを一覧表示"
AI: ❌ ローカルで実行され、サーバー上のファイルは表示されない

ShellKeeper (ステートフル)

あなた: "私のサーバーに接続"
AI: ✅ SSHセッションを確立

あなた: "何のファイルがありますか？"
AI: ✅ サーバー上のファイルを一覧表示

あなた: "logsフォルダに移動"
AI: ✅ /var/logに移動

あなた: "最近のエラーを表示"
AI: ✅ ログ内容を表示

🎯 永続的なセッション

ShellKeeperは、自然な会話の流れの中で永続的なセッションを維持することができます。AIはユーザーのSSH接続、現在のディレクトリ、環境変数、以前のコンテキストをすべて記憶します。

自然な会話の流れ

あなた: "本番サーバーにSSH接続"
AI: ✅ prod-01に接続
    セッション: prod-01

あなた: "ディスク空き容量はいくらですか？"
AI: ✅ 45GB利用可能
    (同じセッション、再認証不要)

あなた: "今日のログを表示"
AI: ✅ ログを表示...
    (同じセッションが続く)

あなた: "APIサービスを再起動"
AI: ✅ サービスを再起動
    (依然として同じセッション!)

📁 シームレスなファイル転送

自然言語での要求に基づいて、ShellKeeperはSSHセッションを通じてファイルのアップロードとダウンロードをシームレスに行うことができます。最大10MBのバイナリやテキストファイルを転送することができ、複数のジャンプホストを通しても問題なく動作します。

自然言語での要求例

あなた: "サーバーに私の設定ファイルをアップロード"

AI: ✅ config.jsonをアップロード
    /app/config/config.json

---

あなた: "エラーログをダウンロード"

AI: ✅ app.logをダウンロード
    ./logs/app.logに保存

---

あなた: "データベースのバックアップを取得"

AI: ✅ backup.sqlをダウンロード
    (SSHジャンプを通しても可能!)

🎬 実際の使用例

以下は、自然な会話が自動化された操作に変わる実際の例です。すべての操作は1つの永続的なセッションで行われ、再認証は必要ありません。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 あなたの質問:
   "prod-server-01の遅いAPIをデバッグ"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 AIの実行:

   [接続中...]
   → ssh user@prod-server-01
   ✅ prod-server-01に接続

   [プロセスを調査中...]
   → ps aux | grep api
   📊 APIプロセスが見つかりました: PID 1234, CPU使用率98%

   [ログを確認中...]
   → cd /var/log/api && tail -n 100 error.log
   🔍 エラー: /api/v1/usersエンドポイントでメモリリークが発生しています

   [分析のためにダウンロード中...]
   → ダウンロード: /var/log/api/error.log → ./local-debug/
   ✅ 2.4MBをダウンロード (分析結果: 500以上のメモリエラー)

   [修正を適用中...]
   → アップロード: ./fixed-config.yml → /app/config/
   ✅ 新しいレート制限設定をアップロード

   [サービスを再起動中...]
   → systemctl restart api-service
   → systemctl status api-service
   ✅ サービスを再起動、CPU使用率が12%に低下

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 AIの応答:
   "修正完了！APIのusersエンドポイントでメモリリークが発生していました。

   • ログをダウンロードし、500以上のメモリ割り当てエラーを発見
   • レート制限設定を適用
   • サービスを再起動 - CPU使用率が98%から12%に低下
   • すべての操作は1つの永続的なセッションで完了"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ すべて1つのセッションで、再認証不要！ ✨

📦 インストール

インストールコマンド

npm install -g mcp-shellkeeper

設定

異なるAIアシスタントでの設定方法は以下の通りです。設定後、AIアシスタントを再起動すると使用可能です。

Cursor

Settings JSON:

{
  "mcpServers": {
    "shellkeeper": {
      "command": "npx",
      "args": ["-y", "mcp-shellkeeper"]
    }
  }
}

(Cmd+Shift+P → Preferences: Open Settings)

Claude Code

Config file:

{
  "mcpServers": {
    "shellkeeper": {
      "command": "npx",
      "args": ["-y", "mcp-shellkeeper"]
    }
  }
}

(~/.config/claude/config.json)

VS Code (Cline)

Settings JSON:

{
  "cline.mcpServers": {
    "shellkeeper": {
      "command": "npx",
      "args": ["-y", "mcp-shellkeeper"]
    }
  }
}

💡 使用例

すべての操作は、AIとの自然な会話を通じて行うことができます。スクリプトや手動でのSSH操作は必要ありません。

📖 利用可能なツール

AIはこれらのツールを自動的に使用しますが、高度な使用方法については以下の表を参考にすることができます。

💡 ヒント: AIは自然言語の要求に基づいてこれらのツールを自動的に処理します！

🔧 技術詳細

永続的なセッション

• PTY (Pseudo-Terminal) を使用して、状態を保持した完全なTTYエミュレーションを実現します。
• スマートマーカーが自動的にコマンドの完了を検出します。
• 終了コードをキャプチャしてエラーを検出します。
• 出力をクリーンに解析します (ANSIコードなし)。

ファイル転送

• 既存のSSHセッションを通じてBase64エンコーディングを使用します (別のSCP/SFTPは不要)。
• ジャンプホストを通しても再認証なしで動作します。
• 最大10MB、5分のタイムアウト (より速く完了する場合は早期に終了)。

🐛 トラブルシューティング

コマンドがタイムアウトまたはハングする場合

// 長時間実行されるコマンドのタイムアウトを増やす
terminal_execute({
  command: "npm install",
  timeout: 120000  // 2分
})

// SSHキーが正しく設定されているか確認する
ssh -v user@server

SSHがパスワードを要求する場合

# パスワードレス認証を設定する
ssh-keygen -t ed25519
ssh-copy-id user@server

# 検証
ssh user@server "echo Success"

ファイルのアップロードが失敗する場合

// まずSSHセッションに入っているか確認する
terminal_execute({ command: "pwd" })  // リモートサーバーにいることを確認

// リモートディレクトリが存在することを確認する
terminal_execute({ command: "mkdir -p /app/uploads" })

// その後、ファイルをアップロードする
terminal_upload({ local_path: "file.txt", remote_path: "/app/uploads/file.txt" })

ファイルのダウンロードが失敗する場合

// リモートファイルが存在することを確認する
terminal_execute({ command: "ls -lh /path/to/file" })

// パーミッションを確認する
terminal_execute({ command: "cat /path/to/file | wc -l" })

// 絶対パスでダウンロードを試す
terminal_download({ remote_path: "/full/path/to/file", local_path: "./" })

セッションが応答しなくなる場合

// すべてのセッションを表示する
terminal_list_sessions()

// 問題のあるセッションを閉じる
terminal_close_session({ session_id: "stuck-session" })

// 新しいセッションを作成する
terminal_new_session({ session_id: "new-session" })

🧪 開発

# リポジトリをクローンする
git clone https://github.com/tranhuucanh/mcp-shellkeeper.git
cd mcp-shellkeeper

# 依存関係をインストールする
npm install

# ビルドする
npm run build

# 標準入出力トランスポートでローカルでテストする
node dist/index.js

# MCPインスペクターでテストする
npm run inspector

🤝 コントリビューション

コントリビューションを歓迎します！AIによるサーバー管理をさらに良くするためにご協力ください。

1. リポジトリをフォークする
2. 機能ブランチを作成する (git checkout -b feature/amazing-feature)
3. 変更をコミットする (git commit -m 'Add amazing feature')
4. ブランチにプッシュする (git push origin feature/amazing-feature)
5. プルリクエストを作成する

📄 ライセンス

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

あなたは以下のことができます:

• ✅ 商用利用
• ✅ 修正
• ✅ 配布
• ✅ 個人利用

🙏 謝辞

• Model Context Protocol SDK を使用して構築されています。
• ターミナルエミュレーションに node-pty を使用しています。
• AIワークフローにおけるステートフルなコマンド実行の必要性に触発されて開発されました。

📞 サポート

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions
• MCPコミュニティ: Discord