使用说明

🐚 MCP外壳管理器

AI助手的持久终端会话+文件传输

SSH到服务器、运行命令、传输文件——所有这些都是通过你的人工智能助手完成的。不再有无国籍限制。

🎯 问题

像Cursor这样的AI助手执行命令 无政府 --每个命令都在新的环境中运行：

❌ ssh user@server                          # Hangs forever - no output until exit
❌ Can't run commands after SSH
❌ Each command starts from scratch
❌ No way to transfer files to/from servers
❌ Must re-authenticate for every operation

✨ 解决方案

ShellCeeper将AI助手转化为 有状态运算符 具有持久会话和文件传输功能。

🚀 核心功能

🔄 正式执行

传统人工智能（无状态）

You: "SSH to server"
AI: ❌ Command hangs forever

You: "List files"
AI: ❌ Runs on local, not server

贝壳守护者（有状态）

You: "Connect to my server"
AI: ✅ Establishes SSH session

You: "What files are there?"
AI: ✅ Lists files on server

You: "Go to the logs folder"
AI: ✅ Changes to /var/log

You: "Show me recent errors"
AI: ✅ Displays log content

AI在您的问题之间保持完整的上下文！

🎯 持续会话

自然对话流

You: "SSH to production server"
AI: ✅ Connected to prod-01
    Session: prod-01

You: "How much disk space left?"
AI: ✅ 45GB available
    (same session, no re-auth)

You: "Show me today's logs"
AI: ✅ Displaying logs...
    (same session continues)

You: "Restart the API service"
AI: ✅ Service restarted
    (still same session!)

AI会记住一切：

✅ 您的SSH连接
✅ 当前目录
✅ 环境变量
✅ 所有先前上下文

📁 无缝文件传输

用自然语言提问

You: "Upload my config to the server"

AI: ✅ Uploaded config.json
    /app/config/config.json

---

You: "Download the error logs"

AI: ✅ Downloaded app.log
    Saved to ./logs/app.log

---

You: "Get database backup"

AI: ✅ Downloaded backup.sql
    (even through SSH jumps!)

它只是起作用：

✅ 通过任何SSH会话
✅ 多个跳转主机
✅ 高达10MB的文件
✅ 二进制和文本文件

🎬 真实世界示例

观看自然对话如何变成自动化操作：

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

👤 YOU ASK:
   "Debug the slow API on prod-server-01"

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

🤖 AI EXECUTES:

   [Connecting...]
   → ssh user@prod-server-01
   ✅ Connected to prod-server-01

   [Investigating processes...]
   → ps aux | grep api
   📊 API process found: PID 1234, using 98% CPU

   [Checking logs...]
   → cd /var/log/api && tail -n 100 error.log
   🔍 ERROR: Memory leak in /api/v1/users endpoint

   [Downloading for analysis...]
   → Download: /var/log/api/error.log → ./local-debug/
   ✅ Downloaded 2.4MB (analyzed: 500+ memory errors)

   [Applying fix...]
   → Upload: ./fixed-config.yml → /app/config/
   ✅ Uploaded new rate-limiting config

   [Restarting service...]
   → systemctl restart api-service
   → systemctl status api-service
   ✅ Service restarted, CPU now at 12%

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

🤖 AI RESPONDS:
   "Fixed! The API had a memory leak in the users endpoint.

   • Downloaded logs and found 500+ memory allocation errors
   • Applied rate-limiting configuration
   • Restarted service - CPU dropped from 98% to 12%
   • All operations completed in one persistent session"

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

✨ All in ONE session, NO re-authentication needed! ✨

📦 安装

npm install -g mcp-shellkeeper

配置

光标

设置JSON：

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

(Cmd+Shift+P → 首选项：打开设置）

克劳德代码

配置文件：

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

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

VS代码（临床）

设置JSON：

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

重启你的AI助手 你准备好了！ 🎉

💡 用例

场景	你问什么	人工智能做什么
🔍 调试生产	“为什么prod-api很慢？”	SSH→ 检查CPU/内存→ 下载日志→ 分析→ 上传修复→ 重新启动
🚀 部署更新	“将v2.0部署到登台”	SSH→ 备份→ 上传文件→ 迁移数据库→ 重启→ 验证
🔧 更新配置	“更新web服务器上的SSL证书”	SSH→ 下载旧证书→ 上传新→ Test → 重新加载nginx
🗄️ 备份数据库	“将prod数据库备份到本地”	SSH穿越堡垒→ 转储数据库→ 压缩→ 下载→ 验证
📊 分析日志	“今天查找所有500个错误”	SSH→ 解析日志→ 下载→ 本地分析→ 报告模式
🔄 批量操作	“更新所有服务器上的配置”	平行会议→ 上传→ 重启→ 下载结果

通过与您的AI进行自然对话！ 没有脚本，没有手动SSH杂耍。

📖 可用工具

AI会自动使用这些工具，但您可以参考它们进行高级使用：

工具	目的	主要功能
`terminal_execute`	在持久会话中运行命令	超时配置，退出代码捕获，清理输出
`terminal_upload_file`	上传本地→ remote（最大10MB）	自动检测目录，处理重复项，通过SSH工作
`terminal_download_file`	下载远程→ 本地（最大10MB）	自动创建目录、保留权限、验证完整性
`terminal_new_session`	创建隔离会话	并行操作，独立环境
`terminal_list_sessions`	查看所有活动会话	状态、正常运行时间、最后一个命令
`terminal_close_session`	清理会话	完成后释放资源
`terminal_get_buffer`	调试原始输出	有助于故障排除

💡 提示： AI会根据您的自然语言请求自动处理这些请求！

🔒 安全最佳实践

✅ 做：

使用SSH密钥身份验证（不是密码）： ssh-keygen -t ed25519
跳过堡垒主机进行生产： ssh -J bastion.com user@prod
限制文件上传目的地（避免 /etc, /root, .ssh/)
使用只读帐户进行调查
任务结束后的清理会议
审核所有AI操作

❌ 不要：

将密码存储在命令或配置中
将不受信任的文件上传到生产环境
下载不加密的敏感数据
运行破坏性命令而不进行验证
授予不必要的权限

🛠️ 运作原理

持续会话：

使用PTY（伪终端）进行具有状态持久性的完整TTY仿真
智能标记自动检测命令完成情况
捕获退出代码以进行错误检测
输出解析干净（无ANSI代码）

文件传输：

通过现有SSH会话进行Base64编码（无单独的SCP/SFTP）
通过跳转主机工作，无需重新身份验证
最大10MB，5分钟超时（如果更快，则提前完成）

🐛 故障排除

Commands timeout or hang

// Increase timeout for long-running commands
terminal_execute({
  command: "npm install",
  timeout: 120000  // 2 minutes
})

// Check if SSH keys are set up correctly
ssh -v user@server

SSH asks for password

# Set up passwordless authentication
ssh-keygen -t ed25519
ssh-copy-id user@server

# Verify
ssh user@server "echo Success"

File upload fails

// Check if in SSH session first
terminal_execute({ command: "pwd" })  // Verify you're on remote server

// Ensure remote directory exists
terminal_execute({ command: "mkdir -p /app/uploads" })

// Then upload
terminal_upload({ local_path: "file.txt", remote_path: "/app/uploads/file.txt" })

File download fails

// Verify remote file exists
terminal_execute({ command: "ls -lh /path/to/file" })

// Check permissions
terminal_execute({ command: "cat /path/to/file | wc -l" })

// Try download with absolute path
terminal_download({ remote_path: "/full/path/to/file", local_path: "./" })

Session becomes unresponsive

// List all sessions
terminal_list_sessions()

// Close problematic session
terminal_close_session({ session_id: "stuck-session" })

// Create fresh session
terminal_new_session({ session_id: "new-session" })

🧪 发展

# Clone repository
git clone https://github.com/tranhuucanh/mcp-shellkeeper.git
cd mcp-shellkeeper

# Install dependencies
npm install

# Build
npm run build

# Test locally with stdio transport
node dist/index.js

# Test with MCP Inspector
npm run inspector

🤝 贡献

欢迎投稿！帮助更好地进行人工智能辅助服务器管理。

分叉存储库
创建特征分支(git checkout -b feature/amazing-feature)
提交更改(git commit -m 'Add amazing feature')
推送到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

你可以：

✅ 商业用途
✅ 修改
✅ 分发
✅ 私人使用

🙏 致谢

内置于模型上下文协议SDK
用途节点pty 用于终端仿真
受AI工作流中有状态命令执行需求的启发

📞 支持

内置于❤️ 面向AI开发者社区

有状态执行+文件传输=无限可能

⬆ 返回页首