MCP Shellkeeper

🚀 🐚 MCP ShellKeeper

MCP ShellKeeper 能夠讓 AI 助手擁有持久的終端會話和文件傳輸能力。藉助它，AI 助手可以通過 SSH 連接服務器、執行命令以及傳輸文件，打破了無狀態操作的限制。

🚀 快速開始

要使用 MCP ShellKeeper，你可以按照以下步驟進行安裝和配置：

npm install -g mcp-shellkeeper

配置

不同的 AI 助手有不同的配置方式：

• Cursor： 打開設置 JSON 文件（通過 Cmd+Shift+P → Preferences: Open Settings），添加以下內容：

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

• Claude Code： 在配置文件 ~/.config/claude/config.json 中添加以下內容：

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

• VS Code (Cline)： 打開設置 JSON 文件，添加以下內容：

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

重新啟動你的 AI 助手，即可開始使用！🎉

✨ 主要特性

🔄 有狀態執行

傳統的 AI 執行命令是無狀態的，例如：

你: "SSH 連接到服務器"
AI: ❌ 命令一直掛起

你: "列出文件"
AI: ❌ 在本地執行，而不是服務器上

而使用 ShellKeeper 後，AI 可以實現有狀態執行：

你: "連接到我的服務器"
AI: ✅ 建立 SSH 會話

你: "有哪些文件？"
AI: ✅ 列出服務器上的文件

你: "進入日誌文件夾"
AI: ✅ 切換到 /var/log

你: "顯示最近的錯誤"
AI: ✅ 顯示日誌內容

AI 可以在你的問題之間保持完整的上下文！

🎯 持久會話

使用 ShellKeeper 可以實現自然的對話流程：

你: "SSH 連接到生產服務器"
AI: ✅ 連接到 prod-01
    會話: prod-01

你: "還剩多少磁盤空間？"
AI: ✅ 可用空間 45GB
    (同一個會話，無需重新認證)

你: "顯示今天的日誌"
AI: ✅ 顯示日誌...
    (同一個會話繼續)

你: "重啟 API 服務"
AI: ✅ 服務已重啟
    (仍然是同一個會話！)

AI 可以記住所有信息，包括：

• ✅ 你的 SSH 連接
• ✅ 當前目錄
• ✅ 環境變量
• ✅ 所有先前的上下文

📁 無縫文件傳輸

你可以用自然語言要求 AI 進行文件傳輸：

你: "將我的配置文件上傳到服務器"
AI: ✅ 已上傳 config.json
    /app/config/config.json

---

你: "下載錯誤日誌"
AI: ✅ 已下載 app.log
    保存到 ./logs/app.log

---

你: "獲取數據庫備份"
AI: ✅ 已下載 backup.sql
    (即使通過 SSH 跳轉！)

文件傳輸功能具有以下特點：

• ✅ 可通過任何 SSH 會話進行
• ✅ 支持多個跳轉主機
• ✅ 最大支持 10MB 的文件
• ✅ 支持二進制和文本文件

💻 使用示例

基礎用法

以下是一個通過 AI 助手使用 ShellKeeper 進行服務器調試的真實示例：

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

👤 你詢問:
   "調試生產服務器 prod-server-01 上的緩慢 API"

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

🤖 AI 執行:

   [正在連接...]
   → ssh user@prod-server-01
   ✅ 已連接到 prod-server-01

   [正在調查進程...]
   → ps aux | grep api
   📊 找到 API 進程: PID 1234，佔用 98% CPU

   [正在檢查日誌...]
   → 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 在用戶端點存在內存洩漏。

   • 下載日誌並發現 500 多個內存分配錯誤
   • 應用了速率限制配置
   • 重啟服務 - CPU 從 98% 降至 12%
   • 所有操作都在一個持久會話中完成"

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

✨ 所有操作都在一個會話中完成，無需重新認證！✨

高級用法

AI 會自動使用以下工具，但你也可以參考這些工具進行高級使用：

💡 提示：AI 會根據你的自然語言請求自動處理這些工具！

📚 詳細文檔

💡 使用場景

所有操作都可以通過與 AI 的自然對話完成！無需編寫腳本，也無需手動進行 SSH 操作。

🔧 技術細節

持久會話

• 使用 PTY（偽終端）進行完整的 TTY 模擬，實現狀態持久化。
• 智能標記可自動檢測命令完成情況。
• 捕獲退出代碼以進行錯誤檢測。
• 輸出經過解析，無 ANSI 代碼。

文件傳輸

• 通過現有的 SSH 會話使用 Base64 編碼進行文件傳輸（無需單獨的 SCP/SFTP）。
• 支持通過跳轉主機進行傳輸，無需重新認證。
• 最大支持 10MB 的文件，超時時間為 5 分鐘（如果傳輸速度快，會提前完成）。

🔒 安全最佳實踐

✅ 建議操作：

• 使用 SSH 密鑰認證（而非密碼）：ssh-keygen -t ed25519
• 通過堡壘機跳轉連接到生產環境：ssh -J bastion.com user@prod
• 限制文件上傳目標（避免 /etc、/root、.ssh/）
• 使用只讀賬戶進行調查
• 任務完成後清理會話
• 審計所有 AI 操作

❌ 避免操作：

• 在命令或配置中存儲密碼
• 將不可信的文件上傳到生產環境
• 在未加密的情況下下載敏感數據
• 在未驗證的情況下運行破壞性命令
• 授予不必要的權限

🐛 故障排除

// 增加長時間運行命令的超時時間
terminal_execute({
  command: "npm install",
  timeout: 120000  // 2 分鐘
})

// 檢查 SSH 密鑰是否正確設置
ssh -v user@server

# 設置無密碼認證
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

# 在本地使用 stdio 傳輸進行測試
node dist/index.js

# 使用 MCP Inspector 進行測試
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