UI-dbugbridge-mcp
An MCP server for inspecting, automating, and validating a DebugBridge-enabled iOS app on a connected physical device through Mac-side orchestration.
Discover/check a physical device and ensure the in-app DebugBridge port is forwarded (
ping,ensure_ports).Read semantic pages, registered actionable element IDs, full UIView/UIWindow trees, and live runtime nodes by accessibility anchor.
Interact with UI elements by stable DebugBridge IDs: tap, set switches, replace or append text, and run multi-step UI flows with waits.
Query the current app run's in-memory logs or wait for new matching log entries with level, category, query, and limit filters.
Compare a Figma raw frame with the current DebugBridge page using
audit_runtimeand produce semantic audit artifacts.Capture a screenshot when an external screenshot command is configured.
Use deprecated compatibility aliases (
get_page,get_ui_hierarchy).It does not build/install/launch the app; it targets physical iOS devices only, and logs are temporary per app process.
Allows auditing runtime UI against a Figma design by comparing a Figma raw JSON export with the current DebugBridge page, generating a semantic alignment report.
Provides tools for inspecting and interacting with iOS apps running on physical devices, including reading the UI hierarchy, tapping elements, setting text or switches, running multi-step UI flows, reading in-app logs, and capturing screenshots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@UI-dbugbridge-mcp Inspect the current UI hierarchy on the device."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
UI-dbugbridge-mcp
UI-dbugbridge-mcp 是 Mac 侧的 MCP Server。它通过 stdio 接收 MCP 请求,再通过 iproxy 访问运行在 iOS App 内的 LookDebugBridge HTTP 服务。
本仓库只负责 MCP 编排,不负责编译、安装或启动 App。真机编译安装由 XcodeBuildMCP 的 build_run_device 完成。
两个仓库的职责
仓库 | 职责 |
| Mac 侧 MCP Server:真机预检、端口转发、UI 操作、UI 树读取、日志读取、运行态校验 |
| iOS Debug Pod:在 App 进程内启动 HTTP Bridge,提供 UI、UI 树和临时内存日志能力 |
Related MCP server: astrolabe
当前运行约束
只发现物理设备上的 DebugBridge,不扫描 iOS Simulator,也不回退到 localhost。
ensure_ports/ping默认探测真机目标的 App 端口37777(与 Pod 默认值对齐),并在结果里返回discovered列表。通过
bundleID/sessionID/deviceUDID(或deviceID)/mode=device选择当前激活目标;设备选择器支持物理 UDID 和 CoreDevice ID。未指定选择器时,优先有线真机上的活桥,其次任意真机。
App 编译安装由 XcodeBuildMCP 负责;本仓库不激活 Xcode scheme,不发送
Command+R。不读取 Xcode Console,不调用 Lookin CLI。
真机优先走 CoreDevice tunnel;旧设备回退
iproxy。
端口与会话语义
维度 | 默认行为 | 说明 |
远端 App 端口 |
| 与 Pod 默认值对齐,同一真机/同一 App 只暴露一个端口;连续会话直接复用,不靠多端口隔离 |
CoreDevice 直连 |
| iOS 17+ 默认走 CoreDevice tunnel,MCP 直接访问 tunnelIP:37777, |
iproxy 回退 |
| 旧设备无 tunnelIP 时回退 iproxy; |
| 上下文标记,非并发隔离 | 默认(未传 |
连续会话 release | 下个会话可重连 | App 侧 |
若两个 MCP 会话并发控制同一 App,当前没有 ownership/lease 机制保护,仍可能互相覆盖 sessionID。仅适合"连续会话"(同一时刻只有一个活跃会话)场景。
App 侧接入
CocoaPods
正式接入使用独立 Pod 仓库:
target 'YourApp' do
use_frameworks!
pod 'LookDebugBridge',
:git => 'git@github.com:Immmmmmortal1/LookDebugBridgeService.git',
:tag => '0.1.18',
:configurations => ['Debug']
end不要再添加 LookinServer。执行:
pod install启动 Bridge
在 App 启动阶段,仅 Debug 构建启动服务:
#if DEBUG
import LookDebugBridge
Task { @MainActor in
LookDebugBridge.shared.startIfNeeded()
}
#endifBridge 启动后提供:
HTTP 接口 | 用途 |
| 检查 Bridge 是否可用 |
| 只读 bundleID / sessionID / port;Mac 侧 preflight 据此校验目标 App |
| 运行时注入 sessionID(上下文标记,非并发隔离);覆盖式写入,幂等可重入 |
| 读取当前语义页面和注册元素 |
| 读取当前 UIWindow/UIView 树 |
| 按 accessibility anchor 读取运行态节点 |
| 点击注册元素 |
| 设置 UISwitch |
| 替换 UITextField/UITextView 文本 |
| 追加 UITextField/UITextView 文本 |
| 查询或等待当前 App 进程的日志 |
/debug/identity与/debug/session中的sessionID是上下文标记(用于日志、identity 匹配),不代表真正并发隔离。两个 MCP 会话并发控制同一 App 仍需后续 ownership/lease 机制。
日志接入
业务 Debug 日志必须进入 LookDebugBridge.log,或由 App 的 Debug 日志入口统一转发:
#if DEBUG
LovOnDebugLog.error("request failed", category: "api")
#endif日志级别和分类是自由字符串,不限于固定枚举。level 和 category 查询为不区分大小写的精确匹配,query 为不区分大小写的消息子串匹配。
日志生命周期和查询规则
日志是 App 进程内的临时内存池:
不写本地文件;
不跨 App 进程保留;
App 重启后创建新的日志池;
不使用 cursor、offset 或读取位置;
read_app_logs直接检索当前进程已经产生的完整日志池,默认返回最近 500 条,最多 5000 条;wait_app_logs只等待本次请求开始后产生的、符合条件的新日志,最多等待 120 秒;sessionID是 App 本次进程生成的调试会话标识(上下文标记,不是文件目录,也不是日志游标,不作为并发隔离依据);DEV_FLOW_SESSION_ID是 DevFlow/MCP 上下文标识,作为上下文标记通过POST /debug/session注入 App(用于日志/identity),两者用途不同但语义都是上下文标记。
日志返回结构:
{
"success": true,
"sessionID": "app-process-session-id",
"status": "matched",
"lines": [
{
"timestamp": "2026-07-31T06:00:00Z",
"level": "error",
"category": "api",
"message": "request failed"
}
],
"error": null
}status 的含义:
status | 含义 |
| 找到符合条件的日志 |
| 当前池没有符合条件的日志(立即查询) |
| 等待超时,期间没有符合条件的新日志 |
查询示例:
{
"name": "read_app_logs",
"arguments": {
"query": "upload",
"category": "oss",
"limit": 50
}
}等待示例:
{
"name": "wait_app_logs",
"arguments": {
"query": "completed",
"level": "info",
"waitMs": 30000
}
}Mac 侧安装与配置
要求:
macOS;
Node.js 18+;
Xcode command line tools;
iproxy;已连接并信任的物理 iOS 设备。
Codex 配置示例:
[mcp_servers.ui_dbugbridge_mcp]
command = "/opt/homebrew/bin/node"
args = ["/absolute/path/UI-dbugbridge-mcp/src/server.js"]
startup_timeout_sec = 30.0
[mcp_servers.ui_dbugbridge_mcp.env]
# 默认不设置 BRIDGE_BASE_URL / BRIDGE_LOCAL_PORT:iproxy 模式下 localPort 动态分配,
# CoreDevice 隧道模式下 ensureBridgeReachable 用 tunnelIP 覆盖;二者均不需要固定本地端口
LOOKDEBUG_DEVICE_ID = "<core-device-id-or-physical-udid>"
IPROXY_PATH = "iproxy"
# 远端 App 端口默认 37777(与 Pod 对齐);1-65535,否则回退到 37777
# BRIDGE_REMOTE_PORT = "37777"
DEV_FLOW_SESSION_ID = "<devflow-session-id>"
DEV_FLOW_SESSION_ID只作为上下文标记写入 App(通过POST /debug/session),用于日志/identity 匹配,不作为并发隔离依据。同一时刻多个 MCP 会话并发控制同一 App 仍需后续 ownership/lease。
隧道模式 vs iproxy 模式(端口说明)
默认省略 BRIDGE_BASE_URL / BRIDGE_LOCAL_PORT:iproxy 模式下 localPort 动态分配,CoreDevice 隧道模式下用 tunnelIP 覆盖,二者均不需要固定本地端口:
模式 | 触发条件 | BRIDGE_BASE_URL / BRIDGE_LOCAL_PORT | 实际访问地址 |
CoreDevice 隧道(iOS 17+ 默认) | 设备暴露 | 忽略, |
|
iproxy(旧设备回退) | 无 tunnelIP,走 | 默认省略;如显式设置则在 iproxy 模式生效,否则动态分配本地端口转回设备 37777 |
|
门禁类探针不要直接探测 127.0.0.1:37777:隧道模式下该端口无监听,会误报桥不可用。请通过 MCP 工具(ping / ensure_ports)走 preflight 流程判断桥可达性。
配置项:
配置项 | 必须 | 说明 |
| 否 | 默认省略;省略时 iproxy 模式下动态生成实际本机转发地址,CoreDevice 隧道模式用 tunnelIP 覆盖。如显式设置:host 仅允许回环(127.0.0.1/localhost/::1),非回环需显式开启 |
| 否 | 指定优先使用的 XcodeBuildMCP/CoreDevice ID;也接受物理设备 UDID |
| 否 |
|
| 否 | 默认 |
| 否 | 默认省略,由 iproxy 模式动态分配本机端口;显式设置后固定使用指定端口(1-65535),若被其他转发占用则失败。仅 iproxy 模式生效,CoreDevice 隧道模式忽略 |
| 否 | 默认 |
| 否 | DevFlow 上下文标识,作为上下文标记通过 |
| 否 | 外部截图命令;使用 |
| 否 | artifact 根目录,设置后 |
| 否 | 危险开关,默认关闭。开启后允许 |
| 否 | 危险开关,默认关闭。开启后允许 |
截图不是 UI 树或日志的依赖能力。未配置 LOOKDEBUG_SCREENSHOT_COMMAND 时,get_screenshot 返回 screenshot_command_not_configured。配置后执行返回结果会带 warning: screenshot_command_executed_as_configured 提示。
标准真机调试流程
1. session_show_defaults
2. 未指定设备时,默认选中有线连接的第一台可用物理设备,再 build_run_device
3. 启动并确认 App 内 LookDebugBridge
4. MCP tools/call: ping 或任意业务工具(自动执行预检)
5. get_debug_page / inspect_ui
6. tap_element / set_switch / set_text / type_text / run_flow
7. read_app_logs 或 wait_app_logs 验证业务结果
8. get_runtime_node / audit_runtime 做运行态校验build_run_device、session_show_defaults 属于 XcodeBuildMCP,不是本仓库提供的 MCP 工具。本仓库不主动切换 Xcode scheme,也不模拟 Command+R。设备选择遵循上方「有线第一台」规则;LOOKDEBUG_DEVICE_ID(或旧版 LOOKDEBUG_DEVICE_UDID)仅用于显式覆盖。
iOS 26 System TabBar 访问规则
iOS 26+ 的 UITabBarController 使用 mode = .tabBar + tabs: [UITab] 新 API,viewControllers 返回 nil,旧路径(遍历 viewControllers / UITabBar.subviews)无法注册 tab 按钮。LookDebugBridge 0.1.15+ 已适配,通过 UITab API 注册 tab 按钮。
Tab 按钮注册
Tab 按钮注册为以下 id(按 index 顺序):
id | 说明 |
| index-based,从 0 开始 |
| title-based,title 转小写去空格 |
| identifier-based,UITab.identifier |
点击时执行 tabBarController.selectedTab = tab + delegate 回调(shouldSelectTab / didSelectTab),与 App 端切换方式一致。
嵌套容器结构
iOS 26 system TabBar 模式下,tab 的 root VC 可能是嵌套容器。例如 Chat tab 的结构:
SystemMainTabBarController (selectedTab = search tab)
└─ UINavigationController
└─ NativeMainChatViewController ← 系统搜索输入器宿主
└─ ChatViewController ← 实际聊天页(带消息列表、send 按钮)
└─ chat.messages.collectionView
└─ inputBar / chat.send / chat.emoji / chat.inputget_debug_page 返回的扁平元素列表会包含各层级的注册元素(如 chatviewcontroller.view、chat.messages.collectionView、chat.send 等),但不反映嵌套层级。
找不到目标元素时的排查顺序
get_debug_page 的扁平列表拿不到目标元素时,禁止直接下结论"入口不可达"或"元素不存在",按以下顺序排查:
用
inspect_ui深度遍历:get_debug_page只返回注册元素,inspect_ui返回完整 UI 树。用depth: 20, maxNodes: 5000深度遍历,确认目标元素是否在嵌套层里。检查元素是否隐藏:
inspect_ui默认不返回 hidden/alpha<0.01 的节点,传includeHidden: true确认。检查
usesSystemTabBarChrome分支:App 代码里可能用usesSystemTabBarChrome == false门控了某些浮动按钮的创建(如首页/地图的浮动 chat 按钮),iOS 26 system tab bar 模式下这些按钮不创建——这不是 DebugBridge 的问题,是 App 代码的产品设计。get_runtime_node按 anchor 查:如果知道元素的accessibilityIdentifier,用get_runtime_node直接查运行态节点,确认它是否在窗口里、是否 hidden。查 App 日志:
read_app_logs看是否有相关错误日志。
常见误区
误区 | 正确做法 |
| 用 |
点 tab 后页面没变 = tab 按钮不可点 | 确认 |
iOS 26 上某个浮动按钮找不到 = DebugBridge 没适配 | 先查 App 代码是否在 |
MCP 工具契约
所有业务工具都通过 stdio 的 MCP tools/list 和 tools/call 暴露。工具结果统一包含:
{
"source": "debug_bridge",
"success": true,
"payload": {},
"error": null
}环境与连接
工具 | 参数 | 说明 |
|
| 扫描全部目标上的活桥并激活一个 |
|
| 释放本 MCP 实例的 iproxy;默认随后退出 server 进程 |
| 同上 | 同上;结果包含 |
UI 页面和节点
工具 | 主要参数 | 说明 |
|
| 读取当前语义页面、页面标题和注册元素 |
|
| 读取当前 UIWindow/UIView 节点树 |
|
| 按 |
| 同 | 兼容别名,已弃用 |
| 无 |
|
inspect_ui 示例:
{
"name": "inspect_ui",
"arguments": {
"depth": 8,
"includeHidden": false,
"maxNodes": 2000
}
}UI 操作
工具 | 必填参数 | 说明 |
|
| 点击注册元素 |
|
| 设置开关状态 |
|
| 替换输入控件文本 |
|
| 追加输入控件文本 |
|
| 按顺序执行多步 UI 流程 |
操作工具使用 DebugBridge 注册的稳定 id,不使用坐标。单步可附加 waitForPageID、waitForElement、timeoutMs、intervalMs 等等待条件。
run_flow.steps 支持:
tap
tap_if_present
set_switch
set_text
type_text
wait_for_page
wait_for_element
sleep流程示例:
{
"name": "run_flow",
"arguments": {
"steps": [
{"action": "set_text", "id": "login.email", "text": "user@example.com"},
{"action": "tap", "id": "login.submit", "waitForPageID": "home"},
{"action": "wait_for_element", "id": "home.content"}
]
}
}日志、截图和运行态审查
工具 | 必填参数 | 说明 |
| 无 | 查询当前 App 进程日志池 |
| 无 | 等待当前请求开始后的新匹配日志 |
| 无 | 调用配置的外部截图命令 |
|
| 将 Figma raw JSON 与当前 DebugBridge 页面做语义校对并生成报告 |
audit_runtime 可选 figmaNodeID、expectedPageID、labelAliases、artifactDir、outJsonPath、outMarkdownPath、timeoutMs、intervalMs。
页面、流程和审查工具的 artifact 默认写入 .devflow-ui/runtime;截图默认写入当前工作目录下的 .tmp/lookdebug-mcp。日志不写入这些目录。
常见错误
错误 | 处理 |
| 连接物理设备,开启开发者模式并确认 Developer Disk Image 服务可用 |
| 检查 |
| 设置 |
| 检查 |
| 确认 App 已启动 DebugBridge 且 |
| dev-flow commit 完成后调用,释放本 MCP 实例的 iproxy 并退出进程 |
| 当前页面没有可用的页面描述或 App 仍在切换页面 |
| 重新调用 |
| 当前元素不支持请求的操作 |
| 确认日志入口确实调用了 |
本地开发和验证
npm run build
npm test运行 MCP Server:
node src/server.js该进程使用 newline-delimited JSON 的 stdio MCP transport,支持 initialize、notifications/initialized、tools/list 和 tools/call。
发布与群通知
MCP 更新后的 Bridge 版本门禁
每次更新 MCP 代码或准备发布前,必须主动检查以下版本是否同步:
package.json的 MCP 版本LookDebugBridge.podspec的 Pod 版本独立
LookDebugBridgeService仓库的最新稳定 tagREADME 中示例 Pod 的 tag
执行联网校验:
npm run check:bridge-version校验无法访问远端或任一版本不一致时会以非零状态退出,禁止继续发布。仅检查本地文件一致性时可使用 npm run check:bridge-version:offline。
打 tag 发布新版本并 push 时,.githooks/pre-push 会自动推送飞书群机器人通知(仅发版触发,普通提交不通知)。
新 clone 后启用 hook(一次性):
git config core.hooksPath .githooks发布流程:
# 1. bump 版本(package.json 的 version)
# 2. npm run release:check
# 3. commit 改动
# 4. git tag -a <版本> -m "Release <版本>"
# 5. git push origin main && git push origin <版本> # 触发飞书通知默认 webhook 地址内置于 .githooks/pre-push,可用环境变量 LOOKDEBUG_LARK_WEBHOOK 覆盖。
Available Tools
16 toolsaudit_runtimeB
Compare a Figma raw frame with the current DebugBridge page and write semantic audit artifacts.
Inputs: figmaRawPath (required), timeoutMs, intervalMs, artifactDir, +6 more.
ensure_portsB
Require a connected physical device and ensure the DebugBridge port is forwarded.
Inputs: no named parameters.
get_debug_pageB
Get semantic page and registered actionable element IDs from the in-app DebugBridge, optionally saving an artifact.
Inputs: timeoutMs, intervalMs, artifactDir, saveArtifact, +2 more.
get_pageA
Deprecated alias of get_debug_page.
Inputs: no named parameters.
get_runtime_nodeA
Read a live UIKit node by runtime anchor/accessibilityIdentifier via the in-app DebugBridge, optionally saving a runtime detail artifact.
Inputs: anchor (required), artifactDir, saveArtifact, artifactPrefix.
get_screenshotA
Capture a screenshot using the configured screenshot command.
Inputs: no named parameters.
get_ui_hierarchyA
Deprecated alias of inspect_ui using the current App UIWindow/UIView tree.
Inputs: no named parameters.
inspect_uiB
Read the current App UIWindow/UIView tree directly from DebugBridge.
Inputs: color, depth, maxNodes, includeHidden.
pingA
Require a connected physical iOS device, then check the in-app DebugBridge.
Inputs: no named parameters.
read_app_logsA
Search the current app run's in-memory DebugBridge log pool. Logs are temporary and are not written to disk or addressed by cursor.
Inputs: level, limit, query, category.
run_flowC
Run a UI operation flow against the current app page using DebugBridge IDs or labels.
Inputs: steps (required), artifactDir, saveArtifacts, artifactPrefix.
set_switchB
Set a UISwitch by stable DebugBridge ID.
Inputs: id (required), isOn (required), timeoutMs, intervalMs, +7 more.
set_textB
Replace text in a UITextField or UITextView by stable DebugBridge ID, focusing the control and firing editing-change events.
Inputs: id (required), text (required), timeoutMs, intervalMs, +7 more.
tap_elementC
Tap an element by stable DebugBridge ID.
Inputs: id (required), timeoutMs, intervalMs, waitAfterMs, +6 more.
type_textA
Append text to a UITextField or UITextView by stable DebugBridge ID, focusing the control and firing editing-change events.
Inputs: id (required), text (required), timeoutMs, intervalMs, +7 more.
wait_app_logsA
Wait for a new matching entry in the current app run's in-memory DebugBridge log pool; no cursor is required or returned.
Inputs: level, limit, query, waitMs, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool serves a clear, distinct purpose, such as connection setup, UI inspection, element interaction, log retrieval, or runtime auditing. The two deprecated aliases are explicitly labeled as such, minimizing confusion despite their overlap with get_debug_page and inspect_ui.
All tool names follow a consistent snake_case verb_noun pattern (e.g., get_debug_page, tap_element, run_flow). Deprecated aliases also adhere to this pattern, so the naming style is uniform throughout.
With 16 tools, the count is slightly above the typical 3-15 range, primarily due to two deprecated aliases. Excluding those, the 14 unique tools cover the domain comprehensively, making the count reasonable but marginally padded.
The tool set covers the full lifecycle of UI debugging: connection verification, port forwarding, UI tree inspection, runtime node retrieval, element interaction (tap, switches, text), log searching/waiting, screenshots, and Figma-based auditing. No significant gaps are evident for the stated purpose.
Related MCP Connectors
remote debug iOS/Android/Unity/Godot/Flutter/RN/Web on real-device.ui-tree/screenshots/taps,tests.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Open a React Native app in a simulated phone: read the screen, tap, type, set device state.
Build, run, and inspect iOS apps in disposable hosted Simulators from cloud coding agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceBridges React Native DevTools, enabling AI assistants to debug, profile, and inspect React Native applications through a standardized protocol.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to inspect and verify mobile UI hierarchies, nodes, styles, screenshots, and runtime attributes of iOS apps in simulators or on USB devices.2Apache 2.0
- AlicenseBqualityBmaintenanceEnables inspecting, debugging, and safely automating a running Typora instance over local STDIO through an opt-in, reversible renderer bridge that exposes status and capability discovery, structured snapshots, DOM and style queries, short-lived element refs, keyboard and click actions, console/network evidence, and instance lifecycle control. Fixture runs execute read-only in isolated profiles and cannot alter Markdown source, while the bridge listens only on localhost with token authentication.28MIT
- AlicenseBqualityBmaintenanceEnables controlling a real iPhone or iPad over USB for app development testing, including building and installing apps, launching with console logs, inspecting the accessibility tree, tapping, swiping, typing, taking screenshots, managing app files, and recording audio.291MIT