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