Name: 远程执行工具
Author: G-karthick0501

使用说明

智能Colab MCP桥（实验）

此存储库包含一个实验设置，该设置使用通过ngrok公开的轻量级Flask服务器将Claude Desktop连接到Google Colab运行时。目标是在Colab（CPU/GPU）上实现受控、资源感知的Python代码远程执行，同时通过Claude Desktop在本地编排任务。

这个存储库反映了最初构建的系统，没有后来的强化或重构。

📊 系统架构

      ┌────────────────┐          ┌───────────────────┐
      │ Claude Desktop │          │   Google Colab    │
      │   (Reasoning)  │          │    (Compute)      │
      └───────┬────────┘          └─────────┬─────────┘
              │                             │
       JSON-RPC (Stdio)                Flask Server
              │                             │
      ┌───────▼────────┐          ┌─────────▼─────────┐
      │ Local MCP Agent│◄────────►│    ngrok Tunnel   │
      │ (State/Config) │   HTTP   │  (Public URL)     │
      └────────────────┘          └───────────────────┘

它是如何工作的：

本地MCP代理： 轻量级Python脚本通过Claude Desktop在您的PC上运行。处理超时、检查点和文件管理。
远程执行器： Colab笔记本通过ngrok隧道暴露Flask API。
桥：克劳德发送代码→ 本地代理→ Colab执行→ 结果返回给克劳德。

重要提示： Claude Desktop会自动启动MCP服务器。必须手动启动Colab笔记本以提供ngrok端点。

✨ 特性

远程执行： 在Colab GPU/CPU上运行Pandas、PyTorch、Scikit学习
智能超时：
- 快速模式（2分钟）：可变检查，轻度计算
- 长模式（10分钟）：模型训练，数据集下载
分块操作： 将大量循环分解为安全批次，以避免超时
本地持久性：
- 长时间运行任务的检查点可恢复性
- 从Colab自动下载文件 /content 到本地机器
环境探测： 执行前查询RAM、GPU和已安装的软件包
内存管理： 清理终结点以释放RAM，而无需重新启动运行时

📂 存储库结构

smart-colab-mcp/
├── agent/
│   └── mcp_smart_colab_v2.py       # Local MCP bridge (reads from env vars)
├── colab/
│   └── smart_colab_executor.ipynb  # Colab backend (Flask + ngrok)
├── config/
│   └── claude_desktop_config.example.json
├── requirements.txt
└── README.md

🚀 安装说明

第一阶段：Colab设置

打开 colab/smart_colab_executor.ipynb 在谷歌Colab
设置您的ngrok身份验证令牌：
```
!ngrok authtoken YOUR_TOKEN_HERE
```
获取免费代币 ngrok.com/dashboard
运行笔记本中的所有单元格
复制公共HTTPS URL 打印（例如。， https://xxxx-xx-xx.ngrok-free.app)
保持笔记本运行 -关闭它会杀死服务器

第二阶段：本地设置

git clone https://github.com/G-karthick0501/Smart-colab-MCP.git
cd Smart-colab-MCP
pip install -r requirements.txt

所需软件包：

mcp -模型上下文协议
requests -HTTP客户端
flask -Web框架（Colab端）
pyngrok -ngrok Python包装器（Colab侧）

第3阶段：配置Claude桌面

地点： %APPDATA%\Claude\claude_desktop_config.json （Windows）

配置示例：

{
  "mcpServers": {
    "smart-colab": {
      "command": "C:\\Path\\To\\Python.exe",
      "args": ["C:\\Path\\To\\agent\\mcp_smart_colab_v2.py"],
      "env": {
        "COLAB_URL": "https://your-ngrok-url.ngrok-free.app",
        "LOCAL_SAVE_DIR": "C:\\Path\\To\\results",
        "CHECKPOINT_DIR": "C:\\Path\\To\\checkpoints"
      }
    }
  }
}

重要提示：

使用 双睫毛 (\\)在Windows路径中
替换 COLAB_URL 使用第一阶段的实际ngrok URL
创建 LOCAL_SAVE_DIR 和 CHECKPOINT_DIR 预先文件夹
编辑配置后重新启动Claude Desktop

🛠️ 可用工具

工具	描述	超时
`check_colab_connection`	验证ngrok隧道是否处于活动状态	10s
`probe_colab_environment`	获取GPU/RAM/软件包信息	30s
`run_code_quick`	执行简短的Python代码片段	2分钟
`run_code_long`	执行繁重任务（培训/下载）	10分钟
`run_chunked_operation`	支持恢复的批量处理循环	5分钟/批
`list_colab_files`	在Colab中列出文件 `/content` 目录	30s
`download_from_colab`	将文件下载到 `LOCAL_SAVE_DIR`	5分钟
`cleanup_colab`	可用RAM/GPU内存	30s
`list_colab_variables`	显示运行时变量和形状	15秒
`get_checkpoint`	检索已保存的检查点数据	即时

🔍 验证和故障排除

检查正在运行的进程

窗户：

tasklist /fi "imagename eq python.exe"

预期产量：

Image Name           PID   Session    Mem Usage
Claude.exe          1234   Console    450,000 K
python.exe          5678   Console     80,000 K  ← Memory MCP (if configured)
python.exe          9012   Console     60,000 K  ← Colab MCP

检测Colab健康终点

curl https://your-ngrok-url/health

预期响应：

{
  "status": "ok",
  "uptime_minutes": 15,
  "memory_available_gb": 10.5,
  "memory_used_pct": 15.2
}

常见问题

问题	原因	解决方案
`Connection refused`	Colab笔记本电脑未运行	重新运行笔记本电脑单元
`COLAB_URL not set`	缺少环境变量	检查Claude Desktop配置
ngrok URL已更改	笔记本已重新启动	使用新URL更新配置
`404 Not Found`	端点路径错误	验证URL是否包含 `/health`
执行超时	代码耗时>10分钟	使用 `run_chunked_operation`
内存错误	Colab RAM已满	调用 `cleanup_colab()`
找不到文件	Colab路径错误	检查 `/content/` 目录

🔒 安全考虑

已知风险（未硬化）

任意代码执行： 这 /execute endpoint无需验证即可运行任何Python代码
无身份验证： 笔记本运行时，ngrok URL可公开访问
无沙盒： 代码以完整的Colab运行时权限执行
单线程： 无执行锁定；并发请求可能会发生冲突
公众曝光： 如果URL泄漏，可以发现ngrok隧道

📋 已知限制

这些是 故意记录 并跟踪未来的工作：

执行模式： 同步，阻塞Flask工作线程
无并发控制： 并行请求可能会导致竞争条件
输出大小限制： 非常大的输出可能超过运输限制
分块执行： 假设简单的循环体；复杂的压痕可能会破裂
没有坚持： Colab运行时断开连接时会话状态丢失
会话生存期： 取决于Colab的空闲超时（约90分钟）
ngrok旋转： 每次会话URL都会更改（付费计划除外）
Flask主机绑定： 应使用 host="0.0.0.0" 可靠性

🔮 未来工作

计划改进（跟踪为GitHub问题）：

安全与认证：

[]添加请求签名/API密钥身份验证
[]实施IP白名单
[]限制危险的Python操作(os.system, subprocess等等）
[]添加带有执行ID的结构化日志记录

可靠性：

[]添加执行锁定机制(threading.Lock)
[]实现并发请求的作业排队
[]提高分块执行的鲁棒性（处理复杂的缩进）
[]添加 /shutdown 用于干净服务器终止的端点

特征：

[]在外部保持远程状态（Google Drive同步）
[]将ngrok替换为自托管隧道（Tailscale、Cloudflare）
[]支持多种运行时环境（Kaggle、VM、本地Docker）
[]为长时间操作添加流式stdout
[]在Colab断开连接时实现自动重新连接

🔄 MCP通信的工作原理

┌─────────────────┐
│ Claude Desktop  │  Reads config.json
│                 │  Spawns MCP servers as subprocesses
└────────┬────────┘
         │
         │ JSON-RPC via stdin/stdout
         │
┌────────▼────────┐
│ MCP Server      │  Python process on your PC
│ (mcp_smart_     │  Reads COLAB_URL from environment
│  colab_v2.py)   │
└────────┬────────┘
         │
         │ HTTP POST/GET
         │
┌────────▼────────┐
│ ngrok Tunnel    │  Public HTTPS → Colab VM
└────────┬────────┘
         │
┌────────▼────────┐
│ Flask Server    │  Running in Colab notebook
│ (Colab Runtime) │  Executes Python via exec()
└─────────────────┘

JSON-RPC消息示例：

// Request from Claude
{
  "jsonrpc": "2.0",
  "method": "run_code_quick",
  "params": {"code": "print(2 + 2)"},
  "id": 1
}

// Response from MCP
{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "stdout": "4\n",
    "execution_time_sec": 0.12
  },
  "id": 1
}

要点：

MCP服务器启动 自动地 当Claude Desktop启动时
Claude和MCP之间的通信是本地（标准输入/标准输出）
MCP和Colab之间的通信是 超文本传输协议 （通过ngrok）
Colab笔记本必须 手动启动 并继续奔跑

📋 推荐.gitignore

# Python
venv/
__pycache__/
*.pyc
*.pyo

# Local storage
results/
checkpoints/
memory_db/
memory_backups/

# IDE
.vscode/
.idea/
*.swp
*.swo

# Secrets
*.token
.env

🎯 状态和动机

当前状态：

✅ 概念的实验证明
✅ 单用户，仅限本地使用
❌ 未加固以确保安全
❌ 可生产的

为什么存在： 该项目旨在探索：

实用的MCP编排模式
无需SSH复杂性的远程执行
管理Colab的瞬态运行时约束
具有检查点的长时间运行的机器学习工作流
关注点分离：推理（Claude）与计算（Colab）

是什么让它与众不同：

执行分类： 显式快速/长/分块模式
本地检查点： 崩溃或断开连接后恢复
探究第一纪律： 执行前检查资源
故障控制： 适当的超时处理和错误表面

📚 额外资源

🤝 贡献

欢迎通过Issues和Pull Requests投稿！

提交前：

删除个人路径和令牌
用新鲜的Colab疗程进行测试
记录任何新的端点或工具
如果架构发生变化，请更新此README

好的第一个问题：

添加执行锁以防止并发运行
实现基本请求身份验证
改进错误消息和日志记录
为MCP工具添加单元测试

⚠️ 免责声明

此代码远程执行任意Python。它是 不安全 用于多用户或公共部署。仅在具有可信代码的可信环境中使用。

用户负责：

执行前检查所有代码
管理ngrok URL隐私
了解执行权限
监控Colab的使用和成本

作者提供：

教育示例代码
已知风险文件
无任何保证或担保

使用风险自负。 不建议用于生产。

🙏 致谢

受...启发 doobidoo/mcp内存服务模式
内置于 FastMCP, 烧瓶，以及吸烟
感谢Anthropic团队制定MCP协议

📝 许可证

MIT许可证-可免费使用并注明出处

维护单位： G-karthick0501
存储库： github/G-karthick0501/Smart-colab-MCP
最后更新时间： 2026年1月