MCP

🚀 HOPX MCP Server

HOPX MCP Server 是 HOPX 的模型上下文協議（MCP）服務器，它能夠讓 AI 助手在隔離的雲容器中執行代碼。

MCP 名稱：io.github.hopx-ai/hopx-mcp

🚀 快速開始

安裝

uvx hopx-mcp

你可以在 hopx.ai 獲取 API 密鑰。

✨ 主要特性

• 可在隔離容器中執行 Python、JavaScript、Bash 和 Go 代碼。
• 支持使用預安裝的 pandas、numpy、matplotlib 進行數據分析。
• 支持文件操作和系統命令。
• 支持後臺進程和長時間運行的任務。

容器使用後會自動銷燬。

📦 安裝指南

獲取 API 密鑰

在 hopx.ai 註冊賬號以獲取 API 密鑰。

配置 IDE

將 MCP 服務器配置添加到你的 IDE 中：

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 使用示例

基礎用法

execute_code_isolated(
    code='print("Hello, World!")',
    language='python',
    timeout=30
)

返回結果：

{
    'stdout': 'Hello, World!\n',
    'exit_code': 0,
    'execution_time': 0.123,
    'sandbox_id': '1762778786mxaco6r2'
}

高級用法

在同一環境中進行多次操作：

# 創建沙箱
sandbox = create_sandbox(
    template_id='code-interpreter',
    timeout_seconds=3600
)

sandbox_id = sandbox['id']

# 運行操作
execute_code(sandbox_id, 'import pandas as pd')
execute_code(sandbox_id, 'df = pd.read_csv("data.csv")')
file_write(sandbox_id, '/workspace/output.txt', 'results')
content = file_read(sandbox_id, '/workspace/output.txt')

# 清理沙箱
delete_sandbox(sandbox_id)

📚 詳細文檔

可用工具

沙箱管理：

• create_sandbox() - 創建沙箱
• list_sandboxes() - 列出沙箱
• delete_sandbox() - 終止沙箱

代碼執行：

• execute_code_isolated() - 一次性執行（推薦）
• execute_code() - 在現有沙箱中執行
• execute_code_background() - 長時間運行的任務
• execute_code_async() - 針對 30 分鐘以上任務的 Webhook 回調

文件操作：

• file_read()、file_write()、file_list()
• file_exists()、file_remove()、file_mkdir()

命令執行：

• run_command() - 執行 shell 命令
• run_command_background() - 後臺進程

環境變量：

• env_get()、env_set()、env_clear()

支持的語言

• Python 3.11+ - pandas、numpy、matplotlib、scipy、scikit-learn、requests
• JavaScript/Node.js 20 - 標準庫
• Bash - Unix 實用工具、git、curl、wget
• Go - 支持編譯

特性

• 沙箱創建時間：約 200ms
• 容器啟動時間：約 0.1s
• 自動清理時間：600s（可配置）
• 網絡訪問：默認開啟
• 隔離性：每次執行完全隔離
• 認證方式：基於 JWT

環境變量

必需的環境變量：

HOPX_API_KEY=your-api-key

可選的環境變量：

HOPX_BASE_URL=https://api.hopx.dev  # 默認值

故障排除

"401 Unauthorized"

API 密鑰未設置或無效。 解決方案：

echo $HOPX_API_KEY  # 驗證密鑰是否設置

"Template not found"

模板名稱無效。 解決方案：

templates = list_templates(limit=20)  # 瀏覽可用模板

首次執行緩慢

容器創建後約 3 秒完成初始化。 原因：VM 認證設置 解決方案：後續操作將立即執行

限制

• 同步執行最大時長：300 秒
• 沙箱生命週期：默認 10 分鐘（可配置）
• 特定模板的語言支持

安全性

保護機制：

• 本地系統與容器執行隔離。
• 容器之間相互隔離。
• 自動清理防止資源洩漏。
• 每個沙箱採用 JWT 認證。

注意事項：

• 容器默認具有網絡訪問權限。
• 代碼在 HOPX 雲端執行。
• 處理敏感數據時請遵循你的安全策略。

支持

• 文檔：docs.hopx.ai
• 問題反饋：GitHub
• 郵箱：support@hopx.ai

🔧 技術細節

該項目基於以下技術構建：

• hopx-ai SDK v0.2.7
• FastMCP 框架
• 模型上下文協議

📄 許可證

本項目採用 MIT 許可證，詳情請見 LICENSE。

HOPX 服務條款：hopx.ai/terms

網站 | 文檔 | GitHub