@mmerterden/dev-toolkit-mcp 2.24.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert Erden
+
+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.

package/README.md

@@ -0,0 +1,387 @@
+# @mmerterden/dev-toolkit-mcp
+
+[![npm version](https://img.shields.io/npm/v/@mmerterden/dev-toolkit-mcp)](https://www.npmjs.com/package/@mmerterden/dev-toolkit-mcp)
+[![npm downloads](https://img.shields.io/npm/dw/@mmerterden/dev-toolkit-mcp)](https://www.npmjs.com/package/@mmerterden/dev-toolkit-mcp)
+[![GitHub stars](https://img.shields.io/github/stars/mmerterden/dev-toolkit-mcp)](https://github.com/mmerterden/dev-toolkit-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**80 tools** for iOS Simulator, Android Emulator, and headless web control. MCP server that lets your AI coding assistant see, interact with, and audit your mobile apps - plus drive browsers, run an 18-rule App Store compliance audit, and orchestrate multi-step batch flows.
+
+Distributed via **GitHub Packages** (private).
+
+**Verified on Claude Code, Copilot CLI and Codex CLI** - the three hosts the release gates actually exercise. Being a standard stdio MCP server it also runs in Cursor, Antigravity, VS Code Copilot Chat, Claude Desktop and any other MCP client; config snippets for those are below, but nothing here checks them.
+
+That distinction is worth keeping straight. This line once called five hosts "the multi-agent-pipeline's full-orchestration targets", which stopped being true in pipeline v10.7.0 when the Cursor / Antigravity / Codex / Copilot Chat adapters were deleted. Codex CLI returned as a first-class target in pipeline v13.0.0 on capability - it now has skills, parallel sub-agents, hooks and MCP - and it is on the verified list only because a gate exercises it, not because it is supported elsewhere. Claiming hosts nobody exercises is not free either: 2.20.0 and 2.21.0 shipped an illegal `outputSchema` on the first tool, so Claude Code rejected the whole `tools/list` and served zero of the 78 - in the primary host, for two releases, with every gate in this repo green.
+
+**6 categories:**
+- **Device Control** (58 tools) - screenshot, tap, swipe, type, navigate, dark mode, locale, location, permissions, push notifications
+- **Accessibility Audit** (2 tools) - auto-detect missing labels, small tap targets, missing identifiers (scope filtering supported)
+- **Store Compliance** (5 tools) - App Store / Play Store readiness; **18-rule deep `ios_app_store_audit`** cross-references Apple ITMS error codes + App Store Review Guidelines (privacy manifest, required-reason API, Info.plist, code signing, entitlements, embedded SDK, IPv6, debug-tool leak, ...)
+- **Web Automation** (8 tools) - Playwright-powered: goto, click (CSS selectors), type, eval JS, wait for selector, extract text, screenshot. Chromium / WebKit / Firefox engines. **Requires `playwright` peer dependency.**
+- **Design Audit** (6 tools) - mock-mode vs Figma conformance: scenario inventory, mock detection, mock launch, live UI geometry, pixel/geometry/typography compare, and the HTML/PDF report with its coverage gate
+- **Autonomous Agent DSL** (1 tool) - `agent_run_steps` executes a batch array of {tool, args, continue_on_error?, wait_ms?} steps in one MCP round trip. Ideal for scripted login flows, form fills, multi-step QA paths.
+
+## Prerequisites
+
+This is a **private package** hosted on GitHub Packages. You need:
+
+1. **Collaborator access** to `mmerterden/dev-toolkit-mcp` (granted by the repo owner).
+2. A **Classic** Personal Access Token (fine-grained PATs are not fully supported for GitHub Packages on private repos).
+
+### 1. Create a Classic PAT
+
+Go to https://github.com/settings/tokens/new?scopes=read:packages,repo and create a token with:
+
+- ✅ `read:packages`
+- ✅ `repo` (required for private package access)
+
+If your GitHub account belongs to an SSO-enforced organization, after creating the token click **"Configure SSO" → Authorize** on the token row.
+
+### 2. Configure `~/.npmrc`
+
+```bash
+# Replace ghp_xxx with the token from step 1
+echo "@mmerterden:registry=https://npm.pkg.github.com" >> ~/.npmrc
+echo "//npm.pkg.github.com/:_authToken=ghp_xxx"        >> ~/.npmrc
+```
+
+### 3. Verify access
+
+```bash
+npm view @mmerterden/dev-toolkit-mcp version
+# → prints the latest published version when everything is wired up
+```
+
+If this fails, see [Troubleshooting](#troubleshooting) below.
+
+## Quick Start
+
+### Option A - Install from source (recommended, no registry auth)
+
+The simplest path. Works even if you haven't configured `~/.npmrc` yet.
+
+```bash
+git clone git@github.com:mmerterden/dev-toolkit-mcp.git
+cd dev-toolkit-mcp
+npm install
+
+# Optional: web tools require Playwright
+npm i -g playwright && npx playwright install chromium
+
+# Make it globally available as 'dev-toolkit-mcp'
+npm link
+```
+
+Update later with `git pull && npm install` inside the clone. Pin to a specific version by checking out the corresponding tag (`git tag -l` to list).
+
+### Option B - npx (requires Prerequisites above)
+
+```bash
+npx @mmerterden/dev-toolkit-mcp
+```
+
+### Setup (after either Option A or B)
+
+#### Claude Code / Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "dev-toolkit": {
+      "command": "npx",
+      "args": ["-y", "@mmerterden/dev-toolkit-mcp"]
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "dev-toolkit": {
+      "command": "npx",
+      "args": ["-y", "@mmerterden/dev-toolkit-mcp"]
+    }
+  }
+}
+```
+
+#### Antigravity
+
+Add to `.agent/mcp_config.json` (or the global `~/.gemini/antigravity/mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "dev-toolkit": {
+      "command": "npx",
+      "args": ["-y", "@mmerterden/dev-toolkit-mcp"]
+    }
+  }
+}
+```
+
+#### Copilot CLI
+
+Add to `~/.copilot/settings.json`:
+```json
+{
+  "mcpServers": {
+    "dev-toolkit": {
+      "command": "npx",
+      "args": ["-y", "@mmerterden/dev-toolkit-mcp"]
+    }
+  }
+}
+```
+
+#### Codex CLI
+
+Let Codex write its own config  -  it owns `~/.codex/config.toml` (marketplace and
+plugin state live there too), and the command is idempotent:
+
+```bash
+codex mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp
+codex mcp list                 # confirm
+codex doctor --json            # checks["mcp.config"] should read ok
+```
+
+For reference, that produces:
+```toml
+[mcp_servers.dev-toolkit]
+command = "npx"
+args = ["-y", "@mmerterden/dev-toolkit-mcp"]
+```
+
+The multi-agent pipeline's `install --codex` runs the `codex mcp add` step for you.
+
+## Troubleshooting
+
+### `npm error code E401` - "User cannot be authenticated with the token provided"
+
+Your token is being rejected by GitHub Packages. Usually one of:
+
+- PAT is fine-grained instead of **Classic**. Recreate as Classic.
+- PAT is missing `repo` scope. Private packages require both `read:packages` **and** `repo`.
+- SSO not authorized. On the token row, click **"Configure SSO" → Authorize** for the relevant org.
+- Token expired or revoked.
+
+### `npm error code E404` on `registry.npmjs.org`
+
+Your `~/.npmrc` does not have the `@mmerterden:registry=...` line. npm defaulted to public npm, which doesn't host this package. Redo the Prerequisites section.
+
+#### VS Code Copilot Chat
+
+Add to `.vscode/mcp.json`:
+```json
+{
+  "servers": {
+    "dev-toolkit": {
+      "command": "npx",
+      "args": ["-y", "@mmerterden/dev-toolkit-mcp"]
+    }
+  }
+}
+```
+
+### Requirements
+
+- **Node.js 18+**
+- **iOS tools**: macOS + Xcode (provides `xcrun simctl`)
+- **Android tools**: Android SDK Platform-Tools (provides `adb`)
+- **Web tools** (optional): `playwright` - install once:
+  ```bash
+  npm i -g playwright && npx playwright install chromium
+  ```
+  (or `webkit` / `firefox` - choose engine per `web_goto` call.)
+
+> If Xcode is not installed, iOS tools return a friendly message instead of crashing. Same for Android and Web tools - use what you have.
+
+### Agent DSL Example
+
+Run a scripted login flow in one MCP call:
+
+```json
+{
+  "tool": "agent_run_steps",
+  "args": {
+    "steps": [
+      { "tool": "web_goto", "args": { "url": "https://example.com/login" } },
+      { "tool": "web_type", "args": { "selector": "#email", "text": "user@example.com" } },
+      { "tool": "web_type", "args": { "selector": "#password", "text": "s3cret" } },
+      { "tool": "web_click", "args": { "selector": "button[type=submit]" }, "wait_ms": 1000 },
+      { "tool": "web_wait_for", "args": { "selector": ".dashboard" } },
+      { "tool": "web_screenshot", "args": { "full_page": true } }
+    ]
+  }
+}
+```
+
+Returns per-step status so the agent can self-correct on failure.
+
+### iOS Tools (37)
+
+| Tool | Description |
+|------|-------------|
+| `ios_list_devices` | List all available simulators |
+| `ios_boot_device` | Boot a simulator |
+| `ios_screenshot` | Capture screenshot (base64 PNG) |
+| `ios_tap` | Tap at coordinates |
+| `ios_swipe` | Swipe gesture |
+| `ios_type_text` | Type text into focused field |
+| `ios_launch_app` | Launch app by bundle ID |
+| `ios_terminate_app` | Terminate app |
+| `ios_list_apps` | List installed apps |
+| `ios_go_home` | Press home button |
+| `ios_set_appearance` | Set light/dark mode |
+| `ios_set_content_size` | Set Dynamic Type size |
+| `ios_set_locale` | Change app language |
+| `ios_open_url` | Open URL or deep link |
+| `ios_status_bar` | Override status bar - supports presets (`clean` 9:41/100% for App Store screenshots, `testing`, `low-battery`, `airplane`) plus manual time/battery |
+| `ios_push_notification` | Send simulated push |
+| `ios_grant_permission` | Grant privacy permission |
+| `ios_revoke_permission` | Revoke permission |
+| `ios_reset_permissions` | Reset all permissions |
+| `ios_set_location` | Set simulated GPS |
+| `ios_clear_location` | Clear location |
+| `ios_set_increase_contrast` | Toggle Increase Contrast |
+| `ios_record_video` | Screen recording |
+| `ios_add_media` | Add to photo library |
+| `ios_keychain_reset` | Reset keychain |
+| `ios_get_app_container` | Get app file path |
+| `ios_erase_device` | Factory reset simulator |
+| `ios_get_ui_tree` | Accessibility UI tree |
+| `ios_accessibility_audit` | Auto-audit: missing labels, small tap targets, missing identifiers |
+| `ios_biometric` | Simulate Face ID / Touch ID (match or fail) |
+| `ios_archive_audit` | Audit .xcarchive for App Store compliance (lighter, deprecated - use `ios_app_store_audit`) |
+| `ios_app_store_audit` | Deep 18-rule App Store compliance audit on .xcarchive - covers privacy manifest, required-reason API, Info.plist, code signing, entitlements, embedded SDK, IPv6, debug-tool leak, binary size, dead refs, duplicate resources, team ID, provisioning profile, Swift ABI, extension signing, asset validation, production hygiene, SDK floor (ITMS-90725). Cross-references Apple ITMS error codes + App Store Review Guidelines |
+| `ios_export_ipa` | Export a .xcarchive to a signed .ipa via `xcodebuild -exportArchive`. Generates the exportOptions.plist from arguments (method defaults to `app-store-connect`). A run that exits 0 without producing an .ipa is reported as a failure |
+| `ios_testflight_validate` | Apple's own pre-submission validation via `xcrun altool --validate-app`, with returned ITMS codes mapped onto the App Store rule each implies. Catches what static analysis structurally cannot: unregistered bundle ID, profile/app-record mismatch, an already-used version+build, entitlements not provisioned for the App ID. 3-tier auth (ASC API key → Apple ID + app-specific password by keychain/env reference → `SKIPPED` with a reason). **`SKIPPED` is not a pass** |
+| `ios_xcodebuild` | Build / test / clean / archive an Xcode project. Returns one-line summary + xcresult ID; full log stays out of context |
+| `ios_xcresult` | Drill into a previous build by ID - modes: `summary`, `errors`, `warnings`, `log`, `tests`. Token-efficient progressive disclosure |
+| `ios_visual_diff` | Compare two PNG screenshots (pixelmatch). Returns diff_pct, pass/fail vs threshold, optional diff PNG. Useful for snapshot regressions across light/dark, locale, dynamic type |
+
+### Android Tools (28)
+
+| Tool | Description |
+|------|-------------|
+| `android_list_devices` | List connected devices |
+| `android_screenshot` | Capture screenshot (base64 PNG) |
+| `android_tap` | Tap at coordinates |
+| `android_swipe` | Swipe gesture |
+| `android_type_text` | Type text |
+| `android_key_event` | Send key event (HOME, BACK, ENTER) |
+| `android_launch_app` | Launch app by package |
+| `android_stop_app` | Force-stop app |
+| `android_list_packages` | List installed packages |
+| `android_go_home` | Press home |
+| `android_go_back` | Press back |
+| `android_get_ui_tree` | UI hierarchy (uiautomator XML) |
+| `android_set_dark_mode` | Toggle dark mode |
+| `android_set_font_scale` | Set font scale |
+| `android_set_locale` | Change locale |
+| `android_set_location` | Mock GPS location |
+| `android_grant_permission` | Grant runtime permission |
+| `android_revoke_permission` | Revoke permission |
+| `android_record_screen` | Screen recording |
+| `android_install_apk` | Install APK |
+| `android_uninstall_app` | Uninstall app |
+| `android_logcat` | View logs |
+| `android_get_screen_size` | Get screen resolution |
+| `android_open_url` | Open URL or deep link |
+| `android_clear_app_data` | Clear app data |
+| `android_accessibility_audit` | Auto-audit: missing contentDescription, small touch targets, missing resource-id |
+| `android_launch_time` | Measure cold start launch time (ms) |
+| `android_apk_audit` | Audit APK for Play Store compliance |
+
+### Design Tools (6)
+
+Mock-mode vs Figma design audit. Generic and platform-agnostic - the heavy orchestration (Figma fetch, variant matching, screen navigation, report assembly) is expected to live in the caller; these expose the mechanical primitives.
+
+| Tool | Description |
+|------|-------------|
+| `design_mock_detect` | Detect whether a project supports a mock/stub mode (`true` / `false` / `debug-only`) via naming conventions, `#if DEBUG` DI, MockData fixtures, and well-known runtime switch keys (extendable). Returns activation + variant hints + evidence. |
+| `design_scenario_inventory` | Enumerate every state driver the mock build exposes - relaunch flags, `*Scenario` / `*Outcome` enum cases, reference-prefix variants (`hasPrefix("F6DI")` branches inside per-screen mock repositories, typically the largest group), flow-wide scenario codes, MockData fixtures, custom-scheme deep links - each with file+line evidence. Prices every target (`relaunch` vs `in-app`) and batches them into a run `plan`, so one relaunch serves every in-app state on that screen. Gives an audit a countable target set instead of "walk the UI until it feels done". |
+| `design_mock_launch` | Launch an installed app in mock mode (iOS UserDefaults launch arg / Android intent extra). |
+| `design_ui_geometry` | Flat element bounding boxes of the current screen + screen size, for px-level spacing measurement. |
+| `design_visual_compare` | Compare a Figma render vs a live screenshot without failing on size mismatch: normalizes scale, crops chrome, reports perceptual diff %, spacing/size/position (px), color (ΔE), and typography. Writes figma/live/diff/overlay/side-by-side PNGs. |
+| `design_report` | Render a design-audit report object to self-contained HTML (base64 images, CSS-positioned annotations) + optional PDF. Enforces a coverage gate: every target must be audited or skipped with an explicit reason, so a partial audit cannot render as a clean report. Wording comes from a label pack (English default, Turkish built in). |
+
+### Use Cases
+
+- **Visual bug hunting** - Screenshot every screen, AI analyzes for layout issues
+- **Dark mode testing** - Toggle appearance, screenshot, compare
+- **Accessibility audit** - Auto-detect missing labels, small tap targets (<44pt iOS / <48dp Android)
+- **Store compliance** - Audit .xcarchive or .apk before submission (signing, debug tools, privacy manifest)
+- **Biometric testing** - Simulate Face ID / Touch ID success and failure flows
+- **Performance** - Measure Android cold start time (ms)
+- **Localization testing** - Switch locale, screenshot all screens
+- **App Store screenshots** - Clean status bar + automated navigation
+- **Regression testing** - Tap through flows, verify behavior
+
+### How It Works
+
+```mermaid
+graph LR
+    subgraph "You"
+        PROMPT["Prompt"]
+    end
+
+    subgraph "AI Assistant"
+        AI["Claude Code / Copilot CLI (verified)\nany other MCP client"]
+    end
+
+    subgraph "dev-toolkit-mcp"
+        MCP["MCP Server"]
+        IOS["iOS Tools (37)\nxcrun simctl"]
+        AND["Android Tools (28)\nadb"]
+        WEB["Web Tools (8)\nPlaywright"]
+        DSL["Agent DSL (1)\nBatch runner"]
+    end
+
+    subgraph "Devices"
+        SIM["📱 iOS Simulator"]
+        EMU["🤖 Android Emulator"]
+        BROWSER["🌐 Browser"]
+    end
+
+    PROMPT --> AI
+    AI -- "MCP Protocol" --> MCP
+    MCP --> IOS --> SIM
+    MCP --> AND --> EMU
+    MCP --> WEB --> BROWSER
+    MCP --> DSL
+    SIM -- "screenshot / UI tree" --> AI
+    EMU -- "screenshot / UI tree" --> AI
+    BROWSER -- "screenshot / text" --> AI
+
+    style MCP fill:#8b5cf6,color:#fff
+    style IOS fill:#3b82f6,color:#fff
+    style AND fill:#10b981,color:#fff
+    style WEB fill:#f59e0b,color:#fff
+```
+
+1. Your AI assistant decides it needs to interact with a device
+2. It calls a tool like `ios_screenshot` or `android_tap` via MCP protocol
+3. This server receives the call and runs the native command (`xcrun simctl` or `adb`)
+4. The result (screenshot, UI tree, action confirmation) is returned to the AI
+5. The AI analyzes the result and decides the next action
+
+**What it wraps:**
+- **iOS**: `xcrun simctl` (part of Xcode Command Line Tools)
+- **Android**: `adb` (part of Android SDK Platform-Tools)
+- **Web**: Playwright (Chromium / WebKit / Firefox)
+
+**What it does NOT do:**
+- Does not access your source code
+- Does not send data to any server
+- Does not require an account or API key
+- Does not modify your project files
+
+Everything runs locally on your machine.
+
+## License
+
+MIT