xcode-cli 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter
+
+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,151 @@
+# xcode-cli-skill
+
+[中文文档](./README_CN.md)
+
+CLI + Skill wrapper for the [official Xcode 26.3+ MCP tools](https://developer.apple.com/xcode/mcp/): a persistent local bridge service so the "Allow access to Xcode?" popup stops showing up on every call, plus a Claude Code / Codex Skill that keeps the full Xcode MCP tool surface out of every conversation by default.
+
+| Problem | What this repo gives you |
+|---------|--------------------------|
+| AI agents get a "Allow access to Xcode?" popup over and over when talking to Xcode MCP | A long-lived local bridge service managed by `xcode-cli-ctl`, so the agent talks to one stable endpoint instead of spawning a fresh bridge every time |
+| Xcode MCP tools are powerful, but you usually do not want all of them loaded into every conversation | A packaged `xcode-cli` Skill, so agents can load the workflow on demand instead of treating raw MCP as the default path |
+
+## Details
+
+### Problem 1: Permission Popup Spam
+
+<img src="alert.jpg" width="360" alt="macOS permission dialog: Allow Codex to access Xcode?">
+
+When AI agents (Claude Code, Codex, Cursor) call Xcode 26.3 MCP tools, macOS can keep popping up "Allow access to Xcode?" every few seconds. If the bridge process keeps changing, macOS does not treat it as the same long-lived integration.
+
+### Root Cause
+
+The Xcode MCP bridge is process-bound. If every call goes through a fresh short-lived process, you get repeated permission prompts and a worse day-to-day workflow.
+
+### The Fix
+
+This repo runs a persistent local bridge service in front of `xcrun mcpbridge`. The agent or terminal CLI talks to that stable HTTP endpoint, while `xcode-cli-ctl` manages the background service for you.
+
+```text
+Agent / CLI ──HTTP──▶ local bridge service ──▶ xcrun mcpbridge ──▶ Xcode
+                           ▲
+                  managed by xcode-cli-ctl
+```
+
+### Problem 2: Keep MCP Out of Every Conversation by Default
+
+Raw MCP server integration is available, but it is not the recommended default. For Claude Code and Codex, this repo is primarily about the packaged `xcode-cli` Skill: let the agent load the workflow when it actually needs Xcode, instead of wiring raw MCP tools into every session.
+
+## Prerequisites
+
+- **macOS** with **Xcode 26.3+**
+- **Node.js** 18+
+- Xcode open with the target project/workspace when you want to build, test, preview, or inspect issues
+
+## Quick Start
+
+```bash
+# 1. Install from npm
+npm install -g xcode-cli
+
+# 2. Install and start the local bridge service
+xcode-cli-ctl install
+
+# 3. Check service health
+xcode-cli-ctl status
+
+# 4. Install the packaged skill
+xcode-cli-ctl skill install
+```
+
+Click "Allow" when macOS asks for Xcode permission.
+
+### Verify
+
+```bash
+# Make sure Xcode is open with a project
+xcode-cli windows
+xcode-cli build
+```
+
+## AI Agent Integration
+
+### Claude Code (Skill)
+
+Install the packaged skill so Claude Code can use `xcode-cli` as an on-demand workflow:
+
+```bash
+xcode-cli-ctl skill install --claude
+```
+
+If you omit `--claude` / `--codex`, the skill installs to both by default.
+
+### Codex (Skill)
+
+Install the packaged skill for Codex:
+
+```bash
+xcode-cli-ctl skill install --codex
+```
+
+Or install to both agents at once:
+
+```bash
+xcode-cli-ctl skill install
+```
+
+### MCP Server (not recommended)
+
+If you really want raw MCP wiring instead of the skill-first workflow, add the local bridge manually:
+
+```bash
+# Claude Code
+claude mcp add --transport http xcode http://localhost:48321/mcp
+
+# Codex
+codex mcp add xcode --url http://localhost:48321/mcp
+```
+
+> **Note:** This is available as a manual fallback, but the main point of this repo is the skill-based workflow, not raw MCP as the default integration path.
+
+### Common `xcode-cli` Commands
+
+```bash
+xcode-cli windows
+xcode-cli status
+xcode-cli build
+xcode-cli build-log --severity error
+xcode-cli test list
+xcode-cli test all
+xcode-cli test some --target MyTests "FeatureTests#testExample"
+xcode-cli file-issues "Sources/App.swift"
+xcode-cli preview "Sources/MyView.swift" --out ./preview-out
+xcode-cli doc "SwiftUI NavigationStack" --frameworks SwiftUI
+```
+
+### Available Tools (20) provided by Xcode 26.3+
+
+| Category | Tools |
+|----------|-------|
+| **Build & Diagnostics** | `BuildProject`, `GetBuildLog`, `XcodeRefreshCodeIssuesInFile`, `XcodeListNavigatorIssues` |
+| **File Operations** | `XcodeRead`, `XcodeWrite`, `XcodeUpdate`, `XcodeRM`, `XcodeMV`, `XcodeMakeDir`, `XcodeLS` |
+| **Search** | `XcodeGrep`, `XcodeGlob`, `DocumentationSearch` |
+| **Testing** | `GetTestList`, `RunAllTests`, `RunSomeTests` |
+| **Preview & Execution** | `RenderPreview`, `ExecuteSnippet` |
+| **Workspace** | `XcodeListWindows` |
+
+## How It Works
+
+```text
+AI Agent ──skill / bash──▶ xcode-cli ──HTTP──▶ local bridge service ──▶ xcrun mcpbridge ──▶ Xcode IDE
+```
+
+| Component | Role |
+|-----------|------|
+| `xcrun mcpbridge` | Xcode's built-in MCP bridge |
+| local bridge service | Persistent HTTP bridge managed via `xcode-cli-ctl` on port `48321` |
+| `xcode-cli` | Friendly CLI surface for Xcode MCP workflows |
+| `xcode-cli` Skill | The recommended integration path for Claude Code / Codex |
+
+## License
+
+MIT

package/bin/xcode-cli

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  if [[ "$SOURCE" != /* ]]; then
+    SOURCE="$DIR/$SOURCE"
+  fi
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ROOT_DIR="$(cd -P "$DIR/.." && pwd)"
+TSX_LOADER="$(node -e 'try { console.log(require.resolve("tsx", { paths: [process.argv[1]] })); } catch { process.exit(1); }' "$ROOT_DIR")"
+if [[ -z "$TSX_LOADER" || ! -f "$TSX_LOADER" ]]; then
+  echo "xcode-cli: missing runtime dependency 'tsx'" >&2
+  echo "Reinstall package dependencies (npm install) or reinstall xcode-cli." >&2
+  exit 1
+fi
+
+exec node --import "$TSX_LOADER" "$ROOT_DIR/src/xcode.ts" "$@"

package/bin/xcode-cli-ctl

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  if [[ "$SOURCE" != /* ]]; then
+    SOURCE="$DIR/$SOURCE"
+  fi
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ROOT_DIR="$(cd -P "$DIR/.." && pwd)"
+TSX_LOADER="$(node -e 'try { console.log(require.resolve("tsx", { paths: [process.argv[1]] })); } catch { process.exit(1); }' "$ROOT_DIR")"
+if [[ -z "$TSX_LOADER" || ! -f "$TSX_LOADER" ]]; then
+  echo "xcode-cli-ctl: missing runtime dependency 'tsx'" >&2
+  echo "Reinstall package dependencies (npm install) or reinstall xcode-cli." >&2
+  exit 1
+fi
+
+exec node --import "$TSX_LOADER" "$ROOT_DIR/src/xcode-ctl.ts" "$@"

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "xcode-cli",
+  "version": "1.0.5",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --import tsx --test \"tests/**/*.test.ts\"",
+    "generate": "mcporter generate-cli --command \"xcrun mcpbridge\" --name mcpbridge --description \"xcode-tools\" --output ./src/mcpbridge.ts"
+  },
+  "keywords": [
+    "xcode",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "ios",
+    "swift"
+  ],
+  "author": "Peter Gammelgaard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dazuiba/xcode-cli-skill.git"
+  },
+  "license": "MIT",
+  "description": "CLI for interacting with Xcode MCP tools from the terminal.",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "commander": "^14.0.3",
+    "mcporter": "^0.7.3",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {},
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    "skills/"
+  ],
+  "bin": {
+    "xcode-cli": "./bin/xcode-cli",
+    "xcode-cli-ctl": "./bin/xcode-cli-ctl"
+  }
+}

package/skills/xcode-cli/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: xcode-cli
+version: 1.0.0
+description: >-
+  Xcode IDE interaction skill. Uses the xcode-cli CLI to build, diagnose,
+  test, preview, and edit Xcode projects via MCP. Use when the user asks to
+  build an Xcode project, view build errors, run diagnostics, run tests,
+  render SwiftUI previews, search Apple documentation, or manage project files.
+---
+
+# xcode-cli Skill
+
+Interact with Xcode through the `xcode-cli` CLI backed by the Xcode MCP bridge.
+
+## Prerequisites
+
+- Xcode 26.3 or later is installed and open with the target project
+- `xcode-cli` is installed: `npm install -g xcode-cli`
+- The bridge is running via one of:
+  - Background service: `xcode-cli-ctl install`
+  - Foreground (in a separate terminal): `xcode-cli-ctl run`
+- The bridge listens on `http://127.0.0.1:48321/mcp`
+
+## Workflow
+
+### 1. Discover tab identifier
+```bash
+xcode-cli windows
+```
+Returns the `tabIdentifier` (e.g. `windowtab1`) and corresponding workspace path.
+If exactly one Xcode tab is open, `--tab` is auto-detected for all commands.
+
+### 2. Build
+```bash
+xcode-cli build
+```
+
+### 3. View build errors
+```bash
+xcode-cli build-log --severity error
+```
+
+### 4. Single-file diagnostics (no full build required)
+```bash
+xcode-cli file-issues "MyApp/Sources/Controllers/MyFile.swift"
+```
+
+### 5. View all Navigator issues
+```bash
+xcode-cli issues --severity error
+```
+
+### 6. Quick project status (windows + issues)
+```bash
+xcode-cli status
+```
+
+### 7. SwiftUI preview (requires #Preview macro)
+```bash
+xcode-cli preview "MyApp/Sources/Views/MyView.swift" --out ./preview-out
+```
+
+### 8. Execute code snippet
+```bash
+xcode-cli snippet "MyApp/Sources/SomeFile.swift" "print(someExpression)"
+```
+
+### 9. Testing
+```bash
+xcode-cli test all
+xcode-cli test list --json
+xcode-cli test some "TargetName::ClassName/testMethod()"
+xcode-cli test some --target TargetName "ClassName#testMethod"
+xcode-cli test list
+```
+For exact MCP parity, use `targetName` + `identifier` from `test list --json`:
+- `targetName` maps to `RunSomeTests.tests[].targetName`
+- `identifier` maps to `RunSomeTests.tests[].testIdentifier`
+
+`RunSomeTests` only runs tests from the active scheme's active test plan in Xcode.
+If a target is missing (for example you need `DashProxyMac` while `DashProxy` is active), switch scheme in Xcode first, then run `xcode-cli test list --json` again.
+
+### 10. Search Apple documentation
+```bash
+xcode-cli doc "SwiftUI NavigationStack" --frameworks SwiftUI
+```
+
+### 11. File operations (within Xcode project structure)
+```bash
+xcode-cli read "path/to/file"
+xcode-cli ls /
+xcode-cli ls -r /
+xcode-cli grep "TODO|FIXME"
+xcode-cli glob "**/*.swift"
+xcode-cli write "path/to/file" "content"
+xcode-cli update "path/to/file" "oldText" "newText" --replace-all
+xcode-cli mv "Old.swift" "New.swift"
+xcode-cli mkdir "MyApp/Sources/Feature"
+xcode-cli rm "MyApp/Sources/Unused.swift"
+```
+
+### 12. Service management
+```bash
+xcode-cli-ctl install         # Install and start as background service (launchd)
+xcode-cli-ctl status          # Check if bridge is running
+xcode-cli-ctl logs -f         # Follow bridge logs
+xcode-cli-ctl uninstall       # Stop and remove service
+```
+
+## Notes
+- File paths are relative to the Xcode project structure, not absolute filesystem paths.
+- Use `--tab <tabIdentifier>` if multiple Xcode tabs are open.
+- If the bridge is not responding: `xcode-cli-ctl status` then `xcode-cli-ctl uninstall && xcode-cli-ctl install`.
+- For JSON output, add `--json` to any command.
+- Use `xcode-cli run <toolName> --args '{"key":"value"}'` to invoke any MCP tool directly.
+
+## CLI to MCP Mapping
+- `status` -> `XcodeListWindows` + `XcodeListNavigatorIssues`
+- `build` -> `BuildProject`
+- `build-log` -> `GetBuildLog`
+- `test all` -> `RunAllTests`
+- `test list` -> `GetTestList`
+- `test some` -> `RunSomeTests`
+- `issues` -> `XcodeListNavigatorIssues`
+- `file-issues` -> `XcodeRefreshCodeIssuesInFile`
+- `windows` -> `XcodeListWindows`
+- `read` -> `XcodeRead`
+- `grep` -> `XcodeGrep`
+- `ls` -> `XcodeLS`
+- `glob` -> `XcodeGlob`
+- `write` -> `XcodeWrite`
+- `update` -> `XcodeUpdate`
+- `mv` -> `XcodeMV`
+- `mkdir` -> `XcodeMakeDir`
+- `rm` -> `XcodeRM`
+- `preview` -> `RenderPreview`
+- `snippet` -> `ExecuteSnippet`
+- `doc` -> `DocumentationSearch`