mirroir mcp

](https://www.npmjs.com/package/mirroir-mcp) ![Build](https://github.com/jfarcand/mirroir-mcp/actions/workflows/build.yml) ![Install](https://github.com/jfarcand/mirroir-mcp/actions/workflows/install.yml) ![Installers](https://github.com/jfarcand/mirroir-mcp/actions/workflows/installers.yml) ![MCP Compliance](https://github.com/jfarcand/mirroir-mcp/actions/workflows/mcp-compliance.yml) ![License](LICENSE) ![macOS 15+](https://support.apple.com/en-us/105071) ![Discord](https://discord.gg/jVDBbMjPMf)

给你的AI眼睛、手和一部真正的iPhone。一个MCP服务器，允许任何AI代理查看屏幕，点击它需要的内容，并通过macOS iPhone镜像解决其余问题。对macOS窗口的实验支持。 32工具，任何MCP客户端。

需求

macOS 15+
通过连接iPhone iPhone镜像

安装

/bin/bash -c "$(curl -fsSL https://mirroir.dev/get-mirroir.sh)"

或通过 npx:

npx -y mirroir-mcp install

或通过家酿:

brew tap jfarcand/tap && brew install mirroir-mcp

第一次截图时，macOS会提示 屏幕录制 和 无障碍 权限。两者都给。

Per-client setup

克劳德代码

claude mcp add --transport stdio mirroir -- npx -y mirroir-mcp

GitHub副本（VS代码）

从MCP服务器库安装：搜索 @mcp mirroir 在“扩展”视图中，或添加到 .vscode/mcp.json:

{
  "servers": {
    "mirroir": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mirroir-mcp"]
    }
  }
}

光标

添加 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "mirroir": {
      "command": "npx",
      "args": ["-y", "mirroir-mcp"]
    }
  }
}

OpenAI 代码专家

codex mcp add mirroir -- npx -y mirroir-mcp

或添加到 ~/.codex/config.toml:

[mcp_servers.mirroir]
command = "npx"
args = ["-y", "mirroir-mcp"]

Install from source

git clone https://github.com/jfarcand/mirroir-mcp.git
cd mirroir-mcp
./mirroir.sh

使用二进制文件的完整路径 .mcp.json: /.build/release/mirroir-mcp.

运作原理

每次交互都遵循相同的循环： 观察、推理、行动. describe_screen 为AI提供每个文本元素的点击坐标（眼睛）。LLM决定下一步做什么（大脑）。 tap, type_text, swipe 执行动作（手）——然后循环回来观察。没有脚本，没有坐标，只有意图。

描述你的应用程序

mirroir可以盲目地探索任何iOS应用程序，但当你告诉它会发生什么时，它的效果会更好。写一个 APP.md 文件，mirroir在探索开始前读取它：

---
app: Santé
archetype: dashboard
obstacle_mode: auto
---

## Structure
Dashboard with 4 tabs: Résumé, Partage, Parcourir, Profil.

## Résumé Tab
- Summary cards for health metrics that drill down to charts
- Cards often show "Aucune donnée" on test devices

## Obstacles
- Health Access permission → tap "Autoriser"
- Notification permission → tap "Ne pas autoriser"

## Skip
- Supprimer les données de Santé
- Réinitialiser

代码目前实际使用的内容： archetype 覆盖配方自动检测； obstacles 在以下情况下自动解除 obstacle_mode: auto; skip 与合并 permissions.json.skipElements; tabs （内联或作为一个部分）作为高优先级目标注入；结构+标签正文+提示成为生成技能的AI上下文。

看 APP.md规格对于完整的字段列表、加载器解析规则和权限系统桥。三个层次的模式协同工作——元素（行看起来像什么）、屏幕（页面布局意味着什么）和应用程序（开发人员知道什么）。模式与技能覆盖整个系统。

示例

将其中任何一个粘贴到Claude Code、Claude Desktop、ChatGPT、Cursor或任何MCP客户端中：

Open Messages, find my conversation with Alice, and send "running 10 min late".

Open Calendar, create a new event called "Dentist" next Tuesday at 2pm.

Open my Expo Go app, tap "LoginDemo", test the login screen with
test@example.com / password123. Screenshot after each step.

Start recording, open Settings, scroll to General > About, stop recording.

屏幕智能

describe_screen 是AI的眼睛。三个后端协同工作，为代理提供屏幕上内容的完整画面——文本、图标和语义UI结构。

Apple Vision OCR（默认）

默认后端使用苹果的Vision框架来检测屏幕上的每个文本元素，并返回精确的点击坐标。这是快速的、本地的，并且不需要API密钥或外部服务。

图标检测（YOLO CoreML）

纯文本OCR忽略了非文本UI元素——按钮、开关、标签栏图标、活动环。删除YOLO CoreML模型(.mlmodelc)in ~/.mirroir-mcp/models/ 服务器在启动时自动检测到它，将图标检测结果与OCR文本合并。AI为仅文本OCR无法看到的元素获取点击目标。

模式	`ocrBackend` 设置	行为
自动检测（默认）	`"auto"`	如果安装了型号，则使用Vision+YOLO，否则仅使用Vision
仅限视觉	`"vision"`	仅限Apple Vision OCR文本
仅限YOLO	`"yolo"`	仅用于CoreML元素检测
两者皆有	`"both"`	始终合并两个后端（如果没有模型，则回退到Vision）

AI视觉模式（embacle）

代替本地OCR， describe_screen 可以将屏幕截图发送到AI视觉模型，该模型在语义上识别UI元素——卡片、标签、按钮、图标、导航结构——而不仅仅是原始文本。这为代理提供了更丰富的上下文，特别是在布局复杂的屏幕上。

这河中之碎冰堆运行时通过Rust FFI直接嵌入到mirroir mcp二进制文件中。 describe_screen 在进程内调用嵌入式运行时——没有单独的服务器，没有网络往返，也没有额外的设置。FFI层(EmbacleFFI.swift → libembacle.a)处理跨Swift/Rust边界的初始化、聊天完成请求和内存管理。

embracle通过已验证的CLI工具（GitHub Copilot、Claude Code）路由视觉请求，因此没有单独的API密钥需要管理。如果您有Copilot或Claude Code订阅，则您已经可以访问。

安装

brew tap dravr-ai/tap
brew install embacle          # CLI tools (embacle-server, embacle-mcp)
brew install embacle-ffi      # Rust FFI static library (libembacle.a)

然后从源代码重建mirroir mcp（或通过Homebrew重新安装），以便二进制链接 libembacle.a:

# From source
swift build -c release

# Or via Homebrew (rebuilds automatically)
brew reinstall mirroir-mcp

零配置激活

当立方体FFI被链接到二进制文件中时， screenDescriberMode 默认为 "auto" 其自动解析为视觉模式。无需更改设置--安装embacle ffi、重建和 describe_screen 开始使用AI视觉。

要强制本地OCR，即使在有壁龛可用的情况下，也要明确设置 "ocr":

// .mirroir-mcp/settings.json
{
  "screenDescriberMode": "ocr"
}

看配置对于所有可用设置。

技能

当你发现自己重复同样的代理工作流程时，把它当作一种技能来掌握。技能是SKILL.md文件——AI遵循的编号步骤，适应布局变化和意外对话框。步骤如下 Tap "Email" 使用OCR——没有硬编码的坐标。

将文件放入 ~/.mirroir-mcp/skills/ （全球）或 /.mirroir-mcp/skills/ （本地项目）。

APP.md

---
version: 1
name: Commute ETA Notification
app: Waze, Messages
tags: ["workflow", "cross-app"]
---

## Steps

1. Launch **Waze**
2. Wait for "Où va-t-on ?" to appear
3. Tap "Où va-t-on ?"
4. Wait for "${DESTINATION:-Travail}" to appear
5. Tap "${DESTINATION:-Travail}"
6. Wait for "Y aller" to appear
7. Tap "Y aller"
8. Wait for "min" to appear
9. Remember: Read the commute time and ETA.
10. Press Home
11. Launch **Messages**
12. Tap "New Message"
13. Type "${RECIPIENT}" and select the contact
14. Type "On my way! ETA {eta}"
15. Press **Return**
16. Screenshot: "message_sent"

${VAR} 占位符从环境变量中解析出来。 ${VAR:-default} 以防倒退。

技能市场

从安装即用型技能 jfarcand/mirroir技能:

git clone https://github.com/jfarcand/mirroir-skills ~/.mirroir-mcp/skills

从探索到CI

这 generate_skill 该工具允许AI代理探索应用程序并生成SKILL.md文件。它使用广度优先搜索（BFS）以导航图的形式遍历应用程序——屏幕是节点，可点击的元素是边。资源管理器描述每个屏幕，将元素与组件定义要决定点击什么，请访问子屏幕，并通过后V形按钮回溯。通过结构指纹识别跳过重复屏幕。看成分检测下面介绍资源管理器如何将原始元素解释为结构化UI组件。

资源管理器逐个视口工作：校准页面长度后，它从当前视口构建一个计划，从上到下点击元素，向下滚动以显示更多内容，并为每个新视口重建计划。这种方法适用于OCR和AI视觉描述器。通过 seed 用于跨运行的确定性排序。

探索是有限的——它不会发现大型应用程序中的每个可访问的屏幕。深度、屏幕数量和时间限制使运行保持实用。对于目标流量，提供 goal 以集中遍历。

graph TD
    A["Launch App"] --> B["Describe Screen"]
    B --> C{"Calibrated?"}
    C -- No --> D["Scroll Full Page"]
    D --> E{"skip_calibration?"}
    E -- No --> F["Component Detect +\nClassify + Validate"]
    E -- Yes --> G["Classify Elements\nDirectly"]
    F --> H["Build Plan"]
    G --> H
    C -- Yes --> H

    H --> I{"Untried\nElements?"}
    I -- Yes --> J["Tap Element"]
    I -- No --> K["Return to Root"]

    J --> M["Describe +\nClassify Edge"]
    M --> N{"Transition"}
    N -- new screen --> O["Add to Frontier"]
    O --> P["Backtrack"]
    N -- revisited/dead --> P

    P -- push: tap back --> H
    P -- modal: tap close --> H
    P -- tab: tap prev --> H

    K --> Q{"Frontier\nEmpty?"}
    Q -- No --> R["Next Frontier\nScreen"]
    R --> B
    Q -- Yes --> S["Generate SKILL.md"]

生成

两种模式： 自主探索 （BFS）和 引导式会议 （手动分步）。

自主BFS探索 --代理自行探索：

Explore the Settings app and generate a skill that checks the iOS version.

这叫 generate_skill(action: "explore", app_name: "Settings", goal: "check iOS version") 引擎盖下。浏览器启动应用程序，从根屏幕运行BFS，并为发现的路径输出SKILL.md。

参数	默认值	说明
`app_name`	必需	要探索的应用程序
`goal`	无	将探索重点放在特定流程上（例如“检查软件版本”）
`goals`	none	目标数组——每个目标一个SKILL.md
`max_depth`	6	最大BFS深度
`max_screens`	30	可访问的最大屏幕数
`max_time`	300	停止前的最长秒数
`strategy`	汽车	`"mobile"` （默认）， `"social"` （Reddit、Instagram），或 `"desktop"` （macOS窗口）
`skip_calibration`	false	校准期间跳过组件检测。滚动仍在运行。适用于产生清晰语义元素的AI视觉描述器
`seed`	随机	用于确定性探索排序的整数种子。相同的种子产生相同的抽头序列
`fresh`	true	丢弃持久的导航图，从头开始探索。集 `false` 用于增量勘探

引导式会议 --AI手动导航，捕捉每个屏幕：

generate_skill(action: "start", app_name: "MyApp") --启动应用程序，OCR第一个屏幕
使用 tap/swipe/type_text 导航，然后 generate_skill(action: "capture") 记录每个屏幕
generate_skill(action: "finish") --将捕获的屏幕组装成SKILL.md

测试

从CLI中确定性地运行技能——循环中没有AI：

mirroir test apps/settings/check-about
mirroir test --junit results.xml --verbose        # JUnit output
mirroir test --dry-run apps/settings/check-about    # validate without executing

选项	描述
`--junit
`	编写JUnitXML报告
`--screenshot-dir`	保存故障截图（默认： `./mirroir-test-results/`)
`--timeout`	`wait_for` 超时（默认值：15）
`--verbose`	详细步骤
`--dry-run`	解析和验证而不执行
`--no-compiled`	跳过编译技能，强制完全OCR

退出码 0 =全部通过， 1 =任何故障。

编译技能

编译一次技能来捕捉坐标和时间。零OCR回放——10步技能从OCR的5+秒下降到不到一秒。

mirroir compile apps/settings/check-about        # compile
mirroir test apps/settings/check-about            # auto-detects .compiled.json
mirroir test --no-compiled check-about            # force full OCR

AI代理自动编译技能是第一次MCP运行的副作用。看编译技能了解详情。

人工智能辅助诊断

当测试步骤失败时，通过 --agent 对问题所在进行人工智能诊断，并提出修复建议：

mirroir test --agent gpt-5.3 apps/settings/check-about
mirroir test --agent claude-sonnet-4-6 apps/settings/check-about
mirroir test --agent ollama:llama3 apps/settings/check-about
mirroir test --agent embacle apps/settings/check-about

内置代理：

代理	提供商	API密钥
`gpt-5.3`	OpenAI	`OPENAI_API_KEY`
`claude-sonnet-4-6`, `claude-haiku-4-5`	人类学	`ANTHROPIC_API_KEY`
`ollama:`	奥拉玛（本地）	无
`embacle`, `embacle:claude`	embacle服务器	CLI代理密钥

自定义代理可以在中定义为YAML配置文件 ~/.mirroir-mcp/agents/.

No API key? Use embacle

河中之碎冰堆通过已验证的CLI工具（GitHub Copilot、Claude Code等）路由请求-不需要单独的API密钥：

brew tap dravr-ai/tap && brew install embacle
mirroir test --agent embacle my-skill

模式系统

explorer使用三层模式系统来理解iOS应用程序——在不同尺度上使用相同的声明性概念：

元素模式 (patterns/elements/)--34个与行级UI组件（表行、选项卡栏、开关、摘要卡）匹配的定义。每个都指定了匹配规则、交互行为和分组逻辑。
屏幕图案 (patterns/screens/)——7个原型配方，从元素组合中识别屏幕级导航模型。校准过程中自动检测，或通过声明 archetype 在APP.md中。
应用程序模式 (patterns/apps/)--APP.md文件，包含结构、障碍、跳过列表和原型声明。开发者的真相来源。

内置原型： settings-list, dashboard, social-feed, content-grid, conversation-list, utility-display, detail-form.

在中放置自定义图案 ~/.mirroir-mcp/components/ （元素）， ~/.mirroir-mcp/recipes/ （屏幕），或 mirroir技能回购。

视觉指示器

AI视觉描述者在语义上描述UI元素（“Activitéchevron”），而不是逐个字符（“Activisté”+“>”）。A. vision-indicators.md 文件将这些描述映射到OCR兼容字符，因此组件管道与两个后端的工作方式相同：

## Indicators
- chevron: >
- dismiss: ×
- back: ”。地方 `vision-indicators.md` 以及您的组件定义。

看 [成分检测](docs/components.md) 对于完整的定义格式、匹配规则参考和检测管道。

## 安全

让AI访问你的手机需要深度防御。mirroir mcp是 **故障关闭** 在每一层。

- **工具权限** --没有配置文件，只有只读工具(`screenshot`, `describe_screen`)暴露。修改工具对MCP客户端完全隐藏——它永远看不到它们。
- **应用程序屏蔽** — `blockedApps` 在 `permissions.json` 即使允许使用变异工具，也会阻止人工智能与钱包或银行等敏感应用程序进行交互。
- **不需要root** -使用macOS CGEvent API作为常规用户进程运行。没有守护进程，没有内核扩展，没有root权限——只有可访问权限。
- **紧急停止开关** --关闭iPhone镜像以立即终止所有输入。

// ~/.mirroir-mcp/permissions.json { "allow": ["tap", "swipe", "type_text", "press_key", "launch_app"], "deny": [], "blockedApps": ["Wallet", "Banking"] }


看 [权限](docs/permissions.md) 和 [安全](docs/security.md) 对于完整的威胁模型。

## CLI工具

### 录音机

将互动记录为技能档案：

mirroir record -o login-flow.yaml -n "Login Flow" --app "MyApp"


### 医生

验证您的设置：

mirroir doctor mirroir doctor --json # machine-readable output


### 配置

为非美国键盘设置键盘布局：

mirroir configure


## 更新

curl installer

/bin/bash -c "$(curl -fsSL https://mirroir.dev/get-mirroir.sh)"

npx

npx -y mirroir-mcp install

Homebrew

brew upgrade mirroir-mcp

From source

git pull && swift build -c release


## 卸载

Homebrew

brew uninstall mirroir-mcp

From source

./uninstall-mirroir.sh


## 配置

所有设置均已生效 `settings.json` --项目本地(`.mirroir-mcp/settings.json`)或全球(`~/.mirroir-mcp/settings.json`).项目本地设置会覆盖全局设置。每个设置也有一个相应的环境变量（例如。 `MIRROIR_SCREEN_DESCRIBER_MODE`).

{ "screenDescriberMode": "auto", "agent": "embacle", "ocrBackend": "auto", "keystrokeDelayUs": 15000, "explorationMaxScreens": 30 }


看 [配置参考](docs/configuration.md) 适用于40多种设置，包括屏幕智能、输入时间、滚动行为、探索预算、人工智能提供商和键盘布局。

## 文档

| | |
|---|---|
| [工具参考](docs/tools.md) |所有32个工具、参数和输入工作流|
| [配置](docs/configuration.md) |所有设置：屏幕智能、输入计时、探索、人工智能提供商|
| [常见问题](docs/faq.md) |安全、焦点窃取、键盘布局、防护墙/视觉模式|
| [安全](docs/security.md) |威胁模型、终止开关和建议|
| [权限](docs/permissions.md) |关闭权限模型和配置文件失败|
| [已知限制](docs/limitations.md) |焦点窃取、键盘布局间隙、自动更正|
| [模式与技能](docs/components.md) |元素模式、屏幕配方、APP.md应用程序描述和检测管道|
| [探索新应用](docs/exploring-a-new-app.md) |引导新应用程序的分步手册——app.md、权限、组件、探索目标|
| [YOLO图标检测](docs/yolo-models.md) |推荐的YOLO型号、CoreML设置和配置|
| [编译技能](docs/compiled-skills.md) |零OCR技能回放|
| [测试](docs/testing.md) |伪造镜像、集成测试和CI策略|
| [故障排除](docs/troubleshooting.md) |调试模式和常见问题|
| [贡献](CONTRIBUTING.md) |如何添加工具、命令和测试|
| [技能市场](docs/skills-marketplace.md) |技能格式、插件发现和创作|

## 社区

加入 [Discord服务器](https://discord.gg/jVDBbMjPMf) 提问、分享技能和讨论想法。

## 贡献

欢迎捐款。提交补丁即表示您同意 [贡献者许可协议](CLA.md) --Git提交元数据充当您的电子签名。

______________________________________________________________________

> **为什么是“mirroir”？** --这是古老的法语拼写 *镜子* （镜子）。这是对作者根源的致敬，而不是拼写错误。

Iphone Mirroir MCP

快速接入

详细介绍

mirroir mcp

需求

安装

克劳德代码

GitHub副本（VS代码）

光标

OpenAI 代码专家

运作原理

描述你的应用程序

示例

屏幕智能

Apple Vision OCR（默认）

图标检测（YOLO CoreML）

AI视觉模式（embacle）

安装

零配置激活

技能

APP.md

技能市场

从探索到CI

生成

测试

编译技能

人工智能辅助诊断

模式系统

视觉指示器

curl installer

npx

Homebrew

From source

Homebrew

From source

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP