phonectl-mcp 0.1.0__tar.gz

phonectl_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+# Publish to PyPI when a version tag (v0.1.0, ...) is pushed. Uses PyPI trusted publishing:
+# no token is stored; PyPI trusts this workflow in this repo, in the "pypi" environment.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: macos-latest  # the package imports macOS-only frameworks (Vision via pyobjc)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Check the tag matches the version in pyproject.toml
+        run: |
+          version=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != v$version"; exit 1; }
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

phonectl_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,15 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run pytest -q

phonectl_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+.DS_Store
+.pytest_cache/
+# personal notes for Claude Code, not part of the project
+CLAUDE.local.md

phonectl_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiefeng-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phonectl_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: phonectl-mcp
+Version: 0.1.0
+Summary: MCP server that lets AI agents see and drive a real iPhone over USB: screenshots, on-screen text, taps, swipes, typing, apps.
+Project-URL: Homepage, https://github.com/jiefeng-ai/phonectl-mcp
+Project-URL: Issues, https://github.com/jiefeng-ai/phonectl-mcp/issues
+Author: jiefeng-ai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,automation,ios,iphone,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.13
+Requires-Dist: mcp<3,>=2.3.0
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: pymobiledevice3==11.50.0
+Requires-Dist: pyobjc-framework-vision>=13.0
+Description-Content-Type: text/markdown
+
+# phonectl-mcp
+
+[中文](https://github.com/jiefeng-ai/phonectl-mcp/blob/main/README.zh-CN.md)
+
+An MCP server that lets AI agents see and drive a real iPhone over a USB cable: screenshots, the text on screen, taps, swipes, typing, hardware buttons, apps and the clipboard. **macOS only.**
+
+<p align="center"><img src="https://raw.githubusercontent.com/jiefeng-ai/phonectl-mcp/main/docs/demo.gif" width="358" alt="A script applies to one job in the BOSS Zhipin app through phonectl-mcp, reading the screen with read_text and tapping"></p>
+<p align="center"><sub>A script applying to one job in a recruiting app through phonectl-mcp: <code>read_text</code> finds the buttons, <code>tap</code> presses them. Personal details are pixelated; 2× speed.</sub></p>
+
+Nothing is installed on the phone and nothing is jailbroken. It uses the developer services iOS already exposes to a trusted Mac (the same ones Xcode uses), and the touch and keyboard input path that iOS 27 opened over USB.
+
+## Requirements
+
+- A Mac. The USB tunnel and the on-screen text recognition (Apple Vision) are macOS-only.
+- An iPhone on **iOS 27 or later**. Taps, swipes and typing need iOS 27. Screenshots and app control may also work on iOS 17–26, but this is untested.
+- A USB data cable (a charge-only cable won't work).
+- On the phone: **Developer Mode** turned on, and this Mac trusted. `phonectl doctor` walks you through both.
+- [uv](https://docs.astral.sh/uv/).
+
+Tested on an iPhone 17 Pro with iOS 27.2 and macOS 27.
+
+## Install
+
+```sh
+uv tool install phonectl-mcp
+phonectl install-service
+phonectl doctor
+```
+
+- `install-service` runs the server at login as a launchd job. It listens on `http://127.0.0.1:47321/mcp` and creates an access token in `~/.config/phonectl/token`. It also prints the client setup below.
+- `doctor` checks every link from the cable to the server and says what to do about anything that fails. `phonectl doctor --fix` mounts the developer disk image if it is missing.
+
+### Connect a client
+
+Claude Code:
+
+```sh
+claude mcp add --scope user --transport http phone http://127.0.0.1:47321/mcp \
+  --header "Authorization: Bearer $(cat ~/.config/phonectl/token)"
+```
+
+Any other client that speaks streamable HTTP needs two things: the URL above, and the header `Authorization: Bearer <token>`.
+
+### Why one server for every client
+
+The phone keeps a single control connection to the Mac. If two programs each open their own, they keep knocking each other off. So one resident server owns the phone, and every agent and script connects to that server. Your own scripts can call the same tools with any MCP client library.
+
+This only makes the connection safe to share. The server does not stop two agents from tapping the screen at the same time, so let one drive at a time.
+
+## Tools
+
+Coordinates are iOS points, which match the pixels of the screenshot the server returns (402×874 on an iPhone 17 Pro).
+
+| Tool | What it does |
+| --- | --- |
+| `screenshot(native=False)` | Captures the screen. `native=True` returns the full-resolution PNG, for scripts. |
+| `read_text()` | Returns the text on screen with positions in points, as JSON. Much cheaper than an image when an agent or script only needs to find a button. |
+| `tap(x, y)`, `long_press(x, y, duration_ms)` | Touch. |
+| `swipe(x1, y1, x2, y2, duration_ms)` | Drag. To scroll down, swipe upward. |
+| `type_text(text)` | Types into the focused field. ASCII is typed key by key. Other text (Chinese, emoji) is pasted through the clipboard, which replaces what was on it. |
+| `press_key(key)` | Presses a key or chord, such as `enter`, `backspace` or `cmd+a`. |
+| `press_button(name)` | Presses a hardware button: `home`, `lock`, `volume-up`, `volume-down`, `mute` or `siri`. |
+| `launch_app(bundle_id, restart=False)`, `list_apps(query)` | Opens apps and finds their bundle ids. |
+| `get_clipboard()`, `set_clipboard(text)` | Reads and writes the phone's clipboard. |
+| `status()` | Reports the server and the phone link. |
+
+The tools that act on the phone (`tap`, `long_press`, `swipe`, `type_text`, `press_key`, `press_button`, `launch_app`) return a screenshot taken afterwards; pass `screenshot=False` to skip it. Taps are not confirmed by the phone, so use that screenshot to see whether a tap landed.
+
+## Settings
+
+Set these environment variables before running `phonectl install-service`; it copies them into the service.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PHONECTL_UDID` | first USB iPhone | Which phone to use when more than one is connected. |
+| `PHONECTL_PORT` | `47321` | HTTP port. The server only listens on 127.0.0.1. |
+| `PHONECTL_TOKEN_FILE` | `~/.config/phonectl/token` | Where the access token is kept. |
+| `PHONECTL_SCALE` | `3` | Pixels per point. Use 2 on an iPhone SE, XR or 11. It only sets the screenshot size; taps stay correct either way. |
+| `PHONECTL_OCR_LANGS` | `zh-Hans,en-US` | Languages for `read_text`, in priority order. |
+| `PHONECTL_SETTLE` | `0.6` | Seconds to wait before the screenshot that follows an action. |
+| `PHONECTL_TOUCH_IDLE` | `30` | Seconds without input after which the input stream to the phone is closed. The next input reopens it, which takes about 0.6 s. |
+| `PHONECTL_CALL_TIMEOUT` | `15` | Seconds to wait for the phone before a call fails, on top of the time a gesture takes. |
+| `PHONECTL_LOG` | `WARNING` | Log level (`INFO` for the installed service). Logs are in `~/Library/Logs/phonectl*.log`. |
+
+Other commands: `phonectl restart` restarts the server (for example after upgrading with `uv tool upgrade phonectl-mcp`), and `phonectl uninstall-service` removes it. Running `phonectl-mcp` with no arguments speaks stdio for a single client; this is meant for debugging.
+
+## Troubleshooting
+
+Run `phonectl doctor` first. It tells you which link is broken.
+
+| Symptom | Fix |
+| --- | --- |
+| No iPhone found | Use a data cable, unlock the phone, then replug. |
+| "Mac is not trusted" | Unlock the phone, replug, and tap **Trust**. |
+| Developer Mode switch is missing | Open Xcode once with the phone connected. The switch then appears under Settings › Privacy & Security. |
+| Screenshots fail | Run `phonectl doctor --fix` to mount the developer disk image. |
+| Taps do nothing | Taps need iOS 27 or later. Also make sure the screen is on and unlocked. |
+| Clients cannot connect | Run `phonectl restart` and check `~/Library/Logs/phonectl.error.log`. |
+
+## Security
+
+- The server listens only on `127.0.0.1` and rejects any request without the token.
+- An agent connected to it can do anything you could do with your finger: send messages, buy things, delete data. Give it the narrowest instructions you can, and watch the screen while it works.
+- You use it at your own risk. Automating third-party apps may break their terms of service.
+
+## Development
+
+```sh
+git clone https://github.com/jiefeng-ai/phonectl-mcp
+cd phonectl-mcp
+uv sync
+uv run pytest
+```
+
+To run your working copy as the service, run `uv run phonectl install-service` from the clone.
+
+## License
+
+MIT

phonectl_mcp-0.1.0/README.md

@@ -0,0 +1,119 @@
+# phonectl-mcp
+
+[中文](https://github.com/jiefeng-ai/phonectl-mcp/blob/main/README.zh-CN.md)
+
+An MCP server that lets AI agents see and drive a real iPhone over a USB cable: screenshots, the text on screen, taps, swipes, typing, hardware buttons, apps and the clipboard. **macOS only.**
+
+<p align="center"><img src="https://raw.githubusercontent.com/jiefeng-ai/phonectl-mcp/main/docs/demo.gif" width="358" alt="A script applies to one job in the BOSS Zhipin app through phonectl-mcp, reading the screen with read_text and tapping"></p>
+<p align="center"><sub>A script applying to one job in a recruiting app through phonectl-mcp: <code>read_text</code> finds the buttons, <code>tap</code> presses them. Personal details are pixelated; 2× speed.</sub></p>
+
+Nothing is installed on the phone and nothing is jailbroken. It uses the developer services iOS already exposes to a trusted Mac (the same ones Xcode uses), and the touch and keyboard input path that iOS 27 opened over USB.
+
+## Requirements
+
+- A Mac. The USB tunnel and the on-screen text recognition (Apple Vision) are macOS-only.
+- An iPhone on **iOS 27 or later**. Taps, swipes and typing need iOS 27. Screenshots and app control may also work on iOS 17–26, but this is untested.
+- A USB data cable (a charge-only cable won't work).
+- On the phone: **Developer Mode** turned on, and this Mac trusted. `phonectl doctor` walks you through both.
+- [uv](https://docs.astral.sh/uv/).
+
+Tested on an iPhone 17 Pro with iOS 27.2 and macOS 27.
+
+## Install
+
+```sh
+uv tool install phonectl-mcp
+phonectl install-service
+phonectl doctor
+```
+
+- `install-service` runs the server at login as a launchd job. It listens on `http://127.0.0.1:47321/mcp` and creates an access token in `~/.config/phonectl/token`. It also prints the client setup below.
+- `doctor` checks every link from the cable to the server and says what to do about anything that fails. `phonectl doctor --fix` mounts the developer disk image if it is missing.
+
+### Connect a client
+
+Claude Code:
+
+```sh
+claude mcp add --scope user --transport http phone http://127.0.0.1:47321/mcp \
+  --header "Authorization: Bearer $(cat ~/.config/phonectl/token)"
+```
+
+Any other client that speaks streamable HTTP needs two things: the URL above, and the header `Authorization: Bearer <token>`.
+
+### Why one server for every client
+
+The phone keeps a single control connection to the Mac. If two programs each open their own, they keep knocking each other off. So one resident server owns the phone, and every agent and script connects to that server. Your own scripts can call the same tools with any MCP client library.
+
+This only makes the connection safe to share. The server does not stop two agents from tapping the screen at the same time, so let one drive at a time.
+
+## Tools
+
+Coordinates are iOS points, which match the pixels of the screenshot the server returns (402×874 on an iPhone 17 Pro).
+
+| Tool | What it does |
+| --- | --- |
+| `screenshot(native=False)` | Captures the screen. `native=True` returns the full-resolution PNG, for scripts. |
+| `read_text()` | Returns the text on screen with positions in points, as JSON. Much cheaper than an image when an agent or script only needs to find a button. |
+| `tap(x, y)`, `long_press(x, y, duration_ms)` | Touch. |
+| `swipe(x1, y1, x2, y2, duration_ms)` | Drag. To scroll down, swipe upward. |
+| `type_text(text)` | Types into the focused field. ASCII is typed key by key. Other text (Chinese, emoji) is pasted through the clipboard, which replaces what was on it. |
+| `press_key(key)` | Presses a key or chord, such as `enter`, `backspace` or `cmd+a`. |
+| `press_button(name)` | Presses a hardware button: `home`, `lock`, `volume-up`, `volume-down`, `mute` or `siri`. |
+| `launch_app(bundle_id, restart=False)`, `list_apps(query)` | Opens apps and finds their bundle ids. |
+| `get_clipboard()`, `set_clipboard(text)` | Reads and writes the phone's clipboard. |
+| `status()` | Reports the server and the phone link. |
+
+The tools that act on the phone (`tap`, `long_press`, `swipe`, `type_text`, `press_key`, `press_button`, `launch_app`) return a screenshot taken afterwards; pass `screenshot=False` to skip it. Taps are not confirmed by the phone, so use that screenshot to see whether a tap landed.
+
+## Settings
+
+Set these environment variables before running `phonectl install-service`; it copies them into the service.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PHONECTL_UDID` | first USB iPhone | Which phone to use when more than one is connected. |
+| `PHONECTL_PORT` | `47321` | HTTP port. The server only listens on 127.0.0.1. |
+| `PHONECTL_TOKEN_FILE` | `~/.config/phonectl/token` | Where the access token is kept. |
+| `PHONECTL_SCALE` | `3` | Pixels per point. Use 2 on an iPhone SE, XR or 11. It only sets the screenshot size; taps stay correct either way. |
+| `PHONECTL_OCR_LANGS` | `zh-Hans,en-US` | Languages for `read_text`, in priority order. |
+| `PHONECTL_SETTLE` | `0.6` | Seconds to wait before the screenshot that follows an action. |
+| `PHONECTL_TOUCH_IDLE` | `30` | Seconds without input after which the input stream to the phone is closed. The next input reopens it, which takes about 0.6 s. |
+| `PHONECTL_CALL_TIMEOUT` | `15` | Seconds to wait for the phone before a call fails, on top of the time a gesture takes. |
+| `PHONECTL_LOG` | `WARNING` | Log level (`INFO` for the installed service). Logs are in `~/Library/Logs/phonectl*.log`. |
+
+Other commands: `phonectl restart` restarts the server (for example after upgrading with `uv tool upgrade phonectl-mcp`), and `phonectl uninstall-service` removes it. Running `phonectl-mcp` with no arguments speaks stdio for a single client; this is meant for debugging.
+
+## Troubleshooting
+
+Run `phonectl doctor` first. It tells you which link is broken.
+
+| Symptom | Fix |
+| --- | --- |
+| No iPhone found | Use a data cable, unlock the phone, then replug. |
+| "Mac is not trusted" | Unlock the phone, replug, and tap **Trust**. |
+| Developer Mode switch is missing | Open Xcode once with the phone connected. The switch then appears under Settings › Privacy & Security. |
+| Screenshots fail | Run `phonectl doctor --fix` to mount the developer disk image. |
+| Taps do nothing | Taps need iOS 27 or later. Also make sure the screen is on and unlocked. |
+| Clients cannot connect | Run `phonectl restart` and check `~/Library/Logs/phonectl.error.log`. |
+
+## Security
+
+- The server listens only on `127.0.0.1` and rejects any request without the token.
+- An agent connected to it can do anything you could do with your finger: send messages, buy things, delete data. Give it the narrowest instructions you can, and watch the screen while it works.
+- You use it at your own risk. Automating third-party apps may break their terms of service.
+
+## Development
+
+```sh
+git clone https://github.com/jiefeng-ai/phonectl-mcp
+cd phonectl-mcp
+uv sync
+uv run pytest
+```
+
+To run your working copy as the service, run `uv run phonectl install-service` from the clone.
+
+## License
+
+MIT

phonectl_mcp-0.1.0/README.zh-CN.md

@@ -0,0 +1,122 @@
+# phonectl-mcp
+
+[English](https://github.com/jiefeng-ai/phonectl-mcp/blob/main/README.md)
+
+一个 MCP 服务：让 AI agent 通过 USB 线看见并操作一台真实的 iPhone，能截图、读屏幕文字、点按、滑动、打字、按硬件按钮、启动 App、读写剪贴板。**仅支持 macOS。**
+
+<p align="center"><img src="https://raw.githubusercontent.com/jiefeng-ai/phonectl-mcp/main/docs/demo.gif" width="358" alt="脚本通过 phonectl-mcp 在 BOSS 直聘里投递一个岗位：用 read_text 读屏、用 tap 点按"></p>
+<p align="center"><sub>脚本通过 phonectl-mcp 在招聘 App 里投递一个岗位：<code>read_text</code> 找按钮，<code>tap</code> 点下去。个人信息已打码，2 倍速。</sub></p>
+
+手机上不用装任何东西，也不用越狱。它用的是 iOS 对已信任 Mac 开放的开发者服务（Xcode 用的就是这套），点按和打字走 iOS 27 开放的 USB 输入通道。
+
+## 需要什么
+
+- **一台 Mac**：USB 隧道和读屏文字识别（Apple Vision）都只有 macOS 上有。
+- **iOS 27 或以上的 iPhone**：点按、滑动、打字需要 iOS 27。iOS 17–26 上截图和启动 App 可能能用，但没有测试过。
+- **一根能传数据的 USB 线**：只能充电的线不行。
+- **手机打开「开发者模式」，并信任这台 Mac**：这两步 `phonectl doctor` 会一步步告诉你怎么做。
+- **[uv](https://docs.astral.sh/uv/)**。
+
+已在 iPhone 17 Pro（iOS 27.2）+ macOS 27 上测试。
+
+## 安装
+
+```sh
+uv tool install phonectl-mcp
+phonectl install-service
+phonectl doctor
+```
+
+- `install-service`：把服务注册为开机自启（launchd），监听 `http://127.0.0.1:47321/mcp`；在 `~/.config/phonectl/token` 生成访问令牌，并打印下面的客户端配置。
+- `doctor`：从数据线到服务，逐段检查连接，哪一步不通就告诉你怎么修。缺开发者磁盘镜像时，加 `--fix` 会自动装上。
+
+### 接入客户端
+
+Claude Code：
+
+```sh
+claude mcp add --scope user --transport http phone http://127.0.0.1:47321/mcp \
+  --header "Authorization: Bearer $(cat ~/.config/phonectl/token)"
+```
+
+其他支持 streamable HTTP 的客户端，填上面的地址，再加请求头 `Authorization: Bearer <令牌>` 即可。
+
+### 为什么全机只跑一份服务
+
+手机和 Mac 之间同一时间只保留一条控制连接，两个程序各连各的会互相踢掉对方。所以由一份常驻服务独占手机，所有 agent 和脚本都连这份服务。你自己写的脚本，也可以用任意 MCP 客户端库调用同样的工具。
+
+注意，这只解决连接共用的问题，服务管不了两个 agent 同时点屏幕。同一时间请只让一方操作。
+
+## 工具
+
+坐标单位是 iOS 的 point，和服务返回的截图像素一一对应（iPhone 17 Pro 是 402×874）。
+
+| 工具 | 作用 |
+| --- | --- |
+| `screenshot(native=False)` | 截图。`native=True` 返回原分辨率 PNG，给脚本用 |
+| `read_text()` | 以 JSON 返回屏幕上的文字和位置（单位 point）。只需要找按钮时，比看图省得多 |
+| `tap(x, y)`、`long_press(x, y, duration_ms)` | 点按、长按 |
+| `swipe(x1, y1, x2, y2, duration_ms)` | 滑动。要往下翻，就向上滑 |
+| `type_text(text)` | 往当前输入框打字。ASCII 字符逐键输入；中文和 emoji 经剪贴板粘贴，会覆盖剪贴板原有内容 |
+| `press_key(key)` | 按键或组合键，如 `enter`、`backspace`、`cmd+a` |
+| `press_button(name)` | 按硬件按钮：`home`、`lock`、`volume-up`、`volume-down`、`mute`、`siri` |
+| `launch_app(bundle_id, restart=False)`、`list_apps(query)` | 启动 App，查 App 的 bundle id |
+| `get_clipboard()`、`set_clipboard(text)` | 读写手机剪贴板 |
+| `status()` | 报告服务状态和手机连接 |
+
+操作手机的工具（`tap`、`long_press`、`swipe`、`type_text`、`press_key`、`press_button`、`launch_app`）操作完会返回一张截图，传 `screenshot=False` 可以不要。手机不会确认点按是否生效，请看这张截图判断点没点中。
+
+## 配置
+
+在运行 `phonectl install-service` 之前设好下面的环境变量，安装时会写进服务配置。
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `PHONECTL_UDID` | 第一台 USB 连接的 iPhone | 连了多台手机时，指定用哪一台 |
+| `PHONECTL_PORT` | `47321` | HTTP 端口，只监听 127.0.0.1 |
+| `PHONECTL_TOKEN_FILE` | `~/.config/phonectl/token` | 令牌文件的位置 |
+| `PHONECTL_SCALE` | `3` | 每个 point 对应几个像素。iPhone SE、XR、11 填 2。它只影响截图大小，设错了也不会点错位置 |
+| `PHONECTL_OCR_LANGS` | `zh-Hans,en-US` | `read_text` 的识别语言，按优先级排列 |
+| `PHONECTL_SETTLE` | `0.6` | 操作后等多少秒再截图 |
+| `PHONECTL_TOUCH_IDLE` | `30` | 多少秒没有输入后关闭到手机的输入通道。下次输入会重新打开，约 0.6 秒 |
+| `PHONECTL_CALL_TIMEOUT` | `15` | 等手机响应多少秒算失败（不含手势本身的耗时） |
+| `PHONECTL_LOG` | `WARNING` | 日志级别（安装成服务时是 `INFO`）。日志在 `~/Library/Logs/phonectl*.log` |
+
+其他命令：
+- `phonectl restart`：重启服务，比如用 `uv tool upgrade phonectl-mcp` 升级之后；
+- `phonectl uninstall-service`：卸载服务；
+- 直接运行 `phonectl-mcp`（不带参数）：以 stdio 方式服务单个客户端，用于调试。
+
+## 排查问题
+
+先跑 `phonectl doctor`，它会告诉你断在哪一段。
+
+| 现象 | 处理 |
+| --- | --- |
+| 找不到 iPhone | 换一根能传数据的线，解锁手机后重插 |
+| 提示 Mac 未被信任 | 解锁手机，重插线，在手机上点「信任」 |
+| 设置里找不到「开发者模式」 | 手机连着 Mac 时打开一次 Xcode，之后「设置 › 隐私与安全性」里会出现这个开关 |
+| 截图失败 | 运行 `phonectl doctor --fix`，装上开发者磁盘镜像 |
+| 点了没反应 | 点按需要 iOS 27 及以上；另外确认屏幕亮着、没锁屏 |
+| 客户端连不上 | 运行 `phonectl restart`，再看 `~/Library/Logs/phonectl.error.log` |
+
+## 安全
+
+- 服务只监听 `127.0.0.1`，不带令牌的请求一律拒绝。
+- 接入的 agent 能做你用手指能做的任何事：发消息、付款、删数据。请给它尽量明确、范围小的指令，并在它操作时看着屏幕。
+- 使用风险自负。用它自动操作第三方 App，可能违反这些 App 的用户协议。
+
+## 开发
+
+```sh
+git clone https://github.com/jiefeng-ai/phonectl-mcp
+cd phonectl-mcp
+uv sync
+uv run pytest
+```
+
+想让服务直接运行你本地的代码，在仓库目录里执行 `uv run phonectl install-service`。
+
+## 协议
+
+MIT

phonectl_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "phonectl-mcp"
+version = "0.1.0"
+description = "MCP server that lets AI agents see and drive a real iPhone over USB: screenshots, on-screen text, taps, swipes, typing, apps."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "jiefeng-ai" }]
+requires-python = ">=3.13"
+keywords = ["mcp", "iphone", "ios", "automation", "agent", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "mcp>=2.3.0,<3",
+    "pillow>=13.0.0",
+    "pymobiledevice3==11.50.0",
+    "pyobjc-framework-vision>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jiefeng-ai/phonectl-mcp"
+Issues = "https://github.com/jiefeng-ai/phonectl-mcp/issues"
+
+[project.scripts]
+phonectl-mcp = "phonectl.server:main"
+phonectl = "phonectl.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/phonectl"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["docs/"]

phonectl_mcp-0.1.0/src/phonectl/__init__.py

@@ -0,0 +1,8 @@
+"""phonectl: an MCP server that drives a real iPhone over USB."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("phonectl-mcp")
+except PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0+unknown"