xcode-cli 1.0.5 → 1.0.6

package/README.md

@@ -2,12 +2,12 @@
 
 [中文文档](./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.
+CLI + Skill wrapper for the [official Xcode 26.3+ MCP tools](https://developer.apple.com/xcode/mcp/):  a long-lived `xcode-cli-service` so the "Allow access to Xcode?" popup stops showing up on every call, plus a Claude Code Skill that saves **~5 K tokens** of context per conversation.
 
-| 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 |
+| Pain point | Solution |
+|------------|----------|
+| AI agents get a "Allow access to Xcode?" popup on every Xcode MCP call, and it never remembers | A persistent `mcp-proxy` process — macOS only asks once |
+| MCP tool definitions (20 tools, ~5K tokens) load into every conversation | Wrapped as a Claude Code Skill — loads on-demand |
 
 ## Details
 
@@ -46,6 +46,8 @@ Raw MCP server integration is available, but it is not the recommended default.
 ```bash
 # 1. Install from npm
 npm install -g xcode-cli
+# To update to the latest version:
+# npm install -g xcode-cli@latest
 
 # 2. Install and start the local bridge service
 xcode-cli-ctl install
@@ -69,33 +71,22 @@ xcode-cli build
 
 ## AI Agent Integration
 
-### Claude Code (Skill)
+use skill, you can saves **~5 K tokens** of context per conversation.
 
-Install the packaged skill so Claude Code can use `xcode-cli` as an on-demand workflow:
+### Skill Installation (better)
 
-```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 --claude
 xcode-cli-ctl skill install --codex
-```
-
-Or install to both agents at once:
-
-```bash
+# Install to both Claude Code and Codex
 xcode-cli-ctl skill install
-```
 
-### MCP Server (not recommended)
+# Or copy manually
+cp skills/xcode-cli/SKILL.md ~/.claude/skills/xcode-cli/SKILL.md
+```
 
-If you really want raw MCP wiring instead of the skill-first workflow, add the local bridge manually:
+### MCP Server
 
 ```bash
 # Claude Code
@@ -104,24 +95,6 @@ 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 |
@@ -133,18 +106,16 @@ xcode-cli doc "SwiftUI NavigationStack" --frameworks SwiftUI
 | **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 List
+ 
 
-| Component | Role |
+|  | 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 |
+| `xcode-cli-service` | Persistent HTTP bridge on port `48321`, managed by `xcode-cli-ctl` — solves the repeated permission popup |
+| `xcode-cli` | CLI for Xcode MCP workflows, used by the Skill and directly from the terminal |
+| [`SKILL.md`](skills/xcode-cli/SKILL.md) | Recommended integration for Claude Code / Codex, installed via `xcode-cli-ctl skill install` |
+| `xcode-cli-ctl` | Manages service lifecycle and Skill installation |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xcode-cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "main": "index.js",
   "scripts": {
     "test": "node --import tsx --test \"tests/**/*.test.ts\"",

package/skills/xcode-cli/SKILL.md

@@ -1,6 +1,5 @@
 ---
 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
@@ -16,123 +15,40 @@ Interact with Xcode through the `xcode-cli` CLI backed by the Xcode MCP bridge.
 
 - 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
-```
+- Bridge running: `xcode-cli-ctl install` (background) or `xcode-cli-ctl run` (foreground)
+
+## Commands
+
+All commands: `xcode-cli <cmd> [args]`. **Always use `--tab <tabIdentifier>`** — run `xcode-cli windows` first to get the tabIdentifier, then pass it to every subsequent command. Add `--json` for JSON output.
+
+| Command | Usage | Notes |
+|---------|-------|-------|
+| `windows` | `windows` | List tabs/workspaces; get `tabIdentifier` |
+| `status` | `status` | Quick project status (windows + issues) |
+| `build` | `build` | Build project |
+| `build-log` | `build-log --severity error` | View build errors |
+| `run` | `run` | Build and run active scheme (like Cmd+R) |
+| `run-without-build` | `run-without-build` | Run without building (like Ctrl+Cmd+R) |
+| `issues` | `issues --severity error` | Navigator issues |
+| `file-issues` | `file-issues "MyApp/Sources/MyFile.swift"` | Single-file diagnostics, no full build |
+| `test` | `test all` / `test list [--json]` / `test some "Target::Class/method()"` | Run/list tests |
+| `preview` | `preview "MyApp/Sources/MyView.swift" --out ./out` | SwiftUI preview (requires `#Preview` macro) |
+| `snippet` | `snippet "MyApp/Sources/File.swift" "print(expr)"` | Execute code snippet |
+| `doc` | `doc "SwiftUI NavigationStack" --frameworks SwiftUI` | Search Apple documentation |
+| `read` | `read "path/to/file"` | Read file |
+| `ls` | `ls [-r] /` | List directory |
+| `grep` | `grep "TODO\|FIXME"` | Search files |
+| `glob` | `glob "**/*.swift"` | Find files by pattern |
+| `write` | `write "path/to/file" "content"` | Write file |
+| `update` | `update "path/to/file" "old" "new" [--replace-all]` | Edit file |
+| `mv` | `mv "Old.swift" "New.swift"` | Move/rename file |
+| `mkdir` | `mkdir "MyApp/Sources/Feature"` | Create directory |
+| `rm` | `rm "MyApp/Sources/Unused.swift"` | Delete file |
 
 ## 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`
+- Use `xcode-cli call <toolName> --args '{"key":"value"}'` to invoke any MCP tool directly.
+- `run` and `run-without-build` use AppleScript to send keyboard shortcuts to Xcode; ensure Accessibility access is granted to Terminal/iTerm in System Settings → Privacy & Security → Accessibility.
+- Testing: use `targetName` + `identifier` from `test list --json` for exact test targeting. `test some` only runs tests from the active scheme's active test plan — switch scheme in Xcode if a target is missing.