使用说明
进行中
vphone mcp
vphone-mcp 是专业人士 模型上下文协议（MCP） 为控制而设计的服务器 vPhone虚拟iOS设备它为LLM提供了一套全面的工具，用于与虚拟iOS环境交互，包括硬件控制、位置模拟、文件系统管理和应用程序安装。
🏗️ 建筑
该项目实施了一个稳健的 Python Swift桥 架构：
- MCP层：内置 fastmcp 在Python 3.13+中，向MCP客户端公开高级工具。
- 沟通：使用高性能 Unix域套接字（UDS） 用于低延迟通信的网桥。
- Bridge客户端：Python客户端(
src/vphone_mcp/bridge/client.py)与通信vphone-cli（Swift）守护进程。 - 协议：自定义二进制框架JSON协议(
src/vphone_mcp/bridge/protocol.py)确保可靠的消息传递和状态管理。
🛡️ 安全特性
安全是 vphone-mcp，实施多层保护：
- API令牌身份验证：所有连接都需要有效的
VPHONE_API_TOKEN令牌用于敏感操作的HMAC-SHA256签名。 - 严格路径验证：文件系统操作仅限于允许的目录的白名单（例如。，
/var/mobile/Documents,/var/tmp)并防止路径遍历和符号链接逃逸攻击。 - 两步确认：破坏性或敏感操作（删除、重命名、IPA安装）遵循 预览确认 图案。预览步骤返回一个短暂（5分钟）的一次性HMAC签名令牌，必须提供该令牌才能执行最终操作。
🚀 安装指南
先决条件
- Python 3.13或更高版本
- 紫外线 包管理器
vphone-cli（Swift）守护进程在主机上运行
设置
-
克隆存储库:
git clone https://github.com/Lumysia/vphone-mcp.git cd vphone-mcp -
配置环境变量: 在shell或
.env文件：export VPHONE_API_TOKEN="your-secure-api-token" export VPHONE_BRIDGE_SOCKET="/tmp/vphone_bridge.sock" # Default path export VPHONE_LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR -
运行服务器:
uv run vphone-mcp
🛠️ MCP工具参考
服务器暴露 26工具 根据高效设备管理进行分类：
连接和状态
| 工具 | 说明 |
|---|---|
vphone_connect |
连接到vphone网桥并执行握手。 |
vphone_disconnect |
断开与网桥的连接并清理资源。 |
vphone_status |
获取当前连接状态（连接、断开等）。 |
vphone_ping |
测量到网桥的往返延迟。 |
vphone_version |
检索协议版本和支持的功能。 |
硬件和HID控制
| 工具 | 说明 |
|---|---|
vphone_hid_press |
模拟一次完整的按钮按下（向下然后向上）。 |
vphone_hid_down |
按住HID按钮。 |
vphone_hid_up |
松开之前按住的HID按钮。 |
vphone_home |
模拟按下主页按钮。 |
vphone_power |
模拟按下电源按钮（睡眠/唤醒/电源对话框）。 |
vphone_volume_up |
模拟按下音量增大按钮。 |
vphone_volume_down |
模拟按下音量降低按钮。 |
位置模拟
| 工具 | 说明 |
|---|---|
vphone_set_location |
设置模拟GPS坐标（纬度、经度、高度、速度、航向）。 |
vphone_stop_location |
停止位置模拟并恢复到真实的GPS。 |
文件系统管理
| 工具 | 说明 |
|---|---|
vphone_file_list |
列出包含元数据的目录内容。 |
vphone_file_download |
下载文件内容（base64/hex）或元数据。 |
vphone_file_upload |
将文件内容上传到设备（不覆盖）。 |
vphone_file_mkdir |
创建一个目录（可选带父目录）。 |
vphone_file_delete_preview |
（安全） 预览删除并获取确认令牌。 |
vphone_file_delete_confirm |
（安全） 使用有效的预览令牌执行删除。 |
vphone_file_rename_preview |
（安全） 预览重命名/移动并获取确认令牌。 |
vphone_file_rename_confirm |
（安全） 使用有效的预览标记执行重命名/移动。 |
开发者模式和应用程序
| 工具 | 说明 |
|---|---|
vphone_devmode_status |
查询来宾当前的开发人员模式状态。 |
vphone_devmode_enable |
Arm开发人员模式（需要重新启动设备）。 |
vphone_ipa_install_preview |
（安全） 验证IPA并获取安装令牌。 |
vphone_ipa_install_confirm |
（安全） 使用有效令牌执行IPA安装。 |
🖥️ 客户端配置
整合 vphone-mcp 随着 克劳德桌面版，将以下内容添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"vphone": {
"command": "uv",
"args": [
"--directory",
"/path/to/vphone-mcp",
"run",
"vphone-mcp"
],
"env": {
"VPHONE_API_TOKEN": "your-secure-api-token",
"VPHONE_BRIDGE_SOCKET": "/tmp/vphone_bridge.sock",
"VPHONE_LOG_LEVEL": "INFO"
}
}
}
}
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
