金大哥 - mcp MCP 详情

article

README

🚀 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 中：

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

配置完成后重启 Claude Desktop。

Cursor

添加到 .cursor/mcp.json：

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

VS Code

添加到 .vscode/mcp.json：

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

其他 IDE

不同的 IDE 配置格式有所不同，需添加以下参数：

命令：uvx
参数：["hopx-mcp"]
环境变量：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

🔧 技术细节

该项目基于以下技术构建：

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

HOPX 服务条款：hopx.ai/terms

网站 | 文档 | GitHub

mcp