@magentaesolutions/device-screenshot-mcp 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,106 @@
+# Device Screenshot MCP
+
+MCP server for taking screenshots from a physical iOS device connected via USB. Works with Claude Code across all projects.
+
+## Prerequisites
+
+- **pymobiledevice3** — Python tool for communicating with iOS devices
+- **pymobiledevice3 tunneld** — must be running as root for iOS 17+
+
+### Install pymobiledevice3
+
+```bash
+pip3 install pymobiledevice3
+```
+
+### Start tunneld
+
+The tunnel daemon must run as root. You can either start it manually:
+
+```bash
+sudo pymobiledevice3 remote tunneld
+```
+
+Or install it as a LaunchDaemon for auto-start on boot. Create `/Library/LaunchDaemons/com.pymobiledevice3.tunneld.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.pymobiledevice3.tunneld</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/path/to/pymobiledevice3</string>
+        <string>remote</string>
+        <string>tunneld</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PYTHONPATH</key>
+        <string>/path/to/python/site-packages</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/pymobiledevice3-tunneld.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/pymobiledevice3-tunneld.log</string>
+</dict>
+</plist>
+```
+
+Then load it:
+
+```bash
+sudo cp com.pymobiledevice3.tunneld.plist /Library/LaunchDaemons/
+sudo launchctl load /Library/LaunchDaemons/com.pymobiledevice3.tunneld.plist
+```
+
+### iOS device requirements
+
+- Developer Mode enabled (Settings > Privacy & Security > Developer Mode)
+- Connected via USB and trusted
+
+## Setup
+
+Add to `~/.claude/.mcp.json` for global access, or to a project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "device": {
+      "command": "npx",
+      "args": ["-y", "@magentaesolutions/device-screenshot-mcp@latest"],
+      "env": {
+        "PYMOBILEDEVICE3_PATH": "/path/to/pymobiledevice3",
+        "SCREENSHOT_DIR": "/path/to/project/screenshots"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `PYMOBILEDEVICE3_PATH` | No | `pymobiledevice3` | Path to the pymobiledevice3 binary |
+| `SCREENSHOT_DIR` | No | cwd | Default directory for saved screenshots. `save_to` paths are resolved relative to this. |
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `take_screenshot` | Capture a PNG screenshot from the connected iOS device |
+
+### take_screenshot
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `save_to` | string | No | Filename or path for saving a copy (e.g. `screenshot.png`). Resolved relative to `SCREENSHOT_DIR` if set, otherwise relative to cwd. Creates directories if needed. |
+
+Returns the screenshot as an inline image. If `save_to` is provided, also saves a copy to that path.

package/dist/index.js

@@ -2,10 +2,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { execFile } from 'node:child_process';
-import { readFile, unlink } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
 const PMD3 = process.env.PYMOBILEDEVICE3_PATH || 'pymobiledevice3';
+const SCREENSHOT_DIR = process.env.SCREENSHOT_DIR;
 const server = new McpServer({
     name: 'device-screenshot',
     version: '1.0.0',
@@ -20,21 +22,28 @@ function exec(cmd, args, timeout = 15000) {
         });
     });
 }
-server.tool('take_screenshot', 'Take a screenshot from a connected physical iOS device via USB. Returns the image as a PNG. Requires pymobiledevice3 tunneld to be running (sudo pymobiledevice3 remote tunneld).', {}, async () => {
+server.tool('take_screenshot', 'Take a screenshot from a connected physical iOS device via USB. Returns the image as a PNG. Optionally saves a copy to disk. Requires pymobiledevice3 tunneld to be running (sudo pymobiledevice3 remote tunneld).', {
+    save_to: z.string().optional().describe('Optional filename or path to save the screenshot (e.g. "screenshot.png"). Resolved relative to SCREENSHOT_DIR if set, otherwise relative to cwd. Creates directories if needed.'),
+}, async ({ save_to }) => {
     const outPath = join(tmpdir(), `device-screenshot-${Date.now()}.png`);
     try {
         await exec(PMD3, ['developer', 'dvt', 'screenshot', outPath, '--tunnel', '']);
         const data = await readFile(outPath);
+        const content = [
+            {
+                type: 'image',
+                data: data.toString('base64'),
+                mimeType: 'image/png',
+            },
+        ];
+        if (save_to) {
+            const savePath = SCREENSHOT_DIR ? resolve(SCREENSHOT_DIR, save_to) : resolve(save_to);
+            await mkdir(dirname(savePath), { recursive: true });
+            await copyFile(outPath, savePath);
+            content.push({ type: 'text', text: `Saved to ${savePath}` });
+        }
         await unlink(outPath).catch(() => { });
-        return {
-            content: [
-                {
-                    type: 'image',
-                    data: data.toString('base64'),
-                    mimeType: 'image/png',
-                },
-            ],
-        };
+        return { content };
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magentaesolutions/device-screenshot-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP server for taking screenshots from physical iOS devices via USB",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "publish:npm": "npm publish --access public",
     "prepublishOnly": "npm run build"
   },
   "keywords": [