Synapse - AI-Powered iOS Automation Framework

Synapse 是一个基于 MCP (Model Context Protocol) 的 iOS 自动化框架，让 AI 模型能够像神经突触一样连接并控制 iOS 设备，实现智能化的 UI 自动化测试。

功能特性

• 🔍 自动设备发现 - 通过 Bonjour/mDNS 自动发现局域网内的 iOS 设备
• 📱 多设备支持 - 同时连接和控制多个 iOS 设备
• 🎯 基础操作 - 点击、滑动、长按、输入文本等
• 📸 屏幕截图 - 实时捕获设备屏幕
• 🤖 AI 增强 - 支持集成视觉 AI 进行智能元素定位（可选）
• 🔌 Claude Desktop 集成 - 可直接在 Claude Desktop 中使用

安装

Synapse 服务器端

cd synapse
npm install
npm run build

iOS 应用端

1. 在 ThirdLibraries/Swift/Package.swift 中已添加依赖
2. 在 DEBUG 构建中包含 SynapseKit 框架
3. 在 AppDelegate 中注册服务（已通过 SynapseAssembly 自动完成）

使用方法

1. 启动 Synapse 服务器

npm start

2. iOS 应用自动启动服务

在 DEBUG 模式下，iOS 应用会自动在端口 9222 启动 WebSocket 服务器并广播 Bonjour 服务。

3. 在 Claude Desktop 中使用

配置 Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "synapse": {
      "command": "node",
      "args": ["/path/to/synapse/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

MCP 工具列表

设备管理

• ios_list_devices - 列出所有可用的 iOS 设备
• ios_connect_device - 连接到指定设备
• ios_disconnect_device - 断开设备连接
• ios_device_info - 获取设备详细信息

基础操作

• ios_tap - 点击指定坐标
• ios_swipe - 滑动操作
• ios_long_press - 长按
• ios_type - 输入文本
• ios_screenshot - 截取屏幕

使用示例

在 Claude 中:

1. 列出可用设备:
   调用 ios_list_devices

2. 连接设备:
   调用 ios_connect_device，device_name 为 "iPhone 15 Pro"

3. 点击屏幕:
   调用 ios_tap，x 为 100，y 为 200

4. 截图:
   调用 ios_screenshot

架构说明

MCP 服务器 (TypeScript)

synapse/
├── src/
│   ├── core/           # MCP 核心服务
│   ├── device/         # 设备管理
│   ├── transport/      # WebSocket 通信
│   └── automation/     # 自动化控制

iOS 应用端 (Swift)

AutomationService/
├── Protocol/           # 服务接口定义
├── Service/            # 服务实现
│   ├── AutomationService.swift
│   ├── TouchSimulator.swift     # Hammer 封装
│   ├── WebSocketServer.swift    # WebSocket 服务
│   └── ServiceBroadcaster.swift # Bonjour 广播
└── Assembly/           # MicroKernel 集成

安全说明

⚠️ 仅限开发环境使用

• 自动化服务仅在 DEBUG 构建中包含
• 使用条件编译标志 #if DEBUG 隔离代码
• 生产版本会完全移除相关代码
• WebSocket 服务器默认只监听本地连接

故障排查

设备无法发现

1. 确保 iOS 设备和 MCP 服务器在同一局域网
2. 检查防火墙设置，确保端口 9222 未被阻止
3. 确认 iOS 应用在 DEBUG 模式运行

连接失败

1. 检查 iOS 应用是否成功启动 WebSocket 服务器
2. 查看 Xcode 控制台输出的服务器地址
3. 尝试使用 IP 地址直接连接

操作无响应

1. 确保 iOS 应用在前台运行
2. 检查坐标是否在屏幕范围内
3. 查看 iOS 端日志获取错误信息

开发计划

• [ ] 添加视觉 AI 元素定位
• [ ] 支持更多手势操作
• [ ] 添加操作录制和回放
• [ ] 支持横竖屏切换
• [ ] 添加性能监控

许可证

内部使用，遵循项目整体许可证。