Skip to content

troubleshooting.md

Latest commit

 

History

History
162 lines (103 loc) · 3.48 KB

troubleshooting.md

File metadata and controls

162 lines (103 loc) · 3.48 KB

Troubleshooting

setup fails to locate mcpbridge

Run:

xcode-mcli setup

If it fails with Failed to locate xcrun mcpbridge.:

  • confirm Xcode is installed
  • confirm Xcode Tools is enabled in Settings > Intelligence
  • confirm xcrun resolves from your shell

If it fails with Failed to call xcrun mcpbridge --help.:

  • enable Xcode Tools in Settings > Intelligence
  • run xcode-mcli setup again

windows list returns no useful workspace

Make sure Xcode is open with a workspace or project window.

Then run:

xcode-mcli windows list

A tab-aware command fails because no active window is selected

Use one of these paths:

xcode-mcli windows list
xcode-mcli windows use --tab-identifier windowtab1

Or pass the tab directly on the command:

xcode-mcli files read --tab-identifier windowtab1 --file-path Path/To/File.swift

Multiple Xcode windows are open

Pick one explicitly:

xcode-mcli windows list
xcode-mcli windows use --tab-identifier windowtab1

Xcode permission prompts appear

The first tool-backed command may trigger an Xcode permission prompt for the CLI process.

If you change terminals, shells, or Node installations, macOS may ask again because the calling process identity changed.

The daemon looks stale

Restart it:

xcode-mcli daemon restart

Or stop and start it:

xcode-mcli daemon stop
xcode-mcli daemon start

Inspect status:

xcode-mcli daemon status

If the state root still points at a stale daemon process or socket, the next daemon-backed command replaces that stale state and reconnects through one live daemon for the state root.

JSON output is mixed with diagnostic text

--json writes the stable envelope to stdout.

For tool-backed commands, --verbose writes the tool name to stderr.

This keeps stdout parseable:

xcode-mcli windows list --json --verbose

Mutating commands fail with a confirmation error

These commands require --yes:

  • files rm
  • files update
  • files write
  • files mv --overwrite-existing

Example:

xcode-mcli files write --tab-identifier windowtab1 --file-path Path/To/File.swift --content 'let x = 1' --yes

files mkdir or other mutating commands fail with an Xcode tool error

Some Xcode mutating tools depend on project structure resolution inside the active workspace.

If files mkdir reports a message telling you to run XcodeLS first, warm the structure with:

xcode-mcli files ls --path .

Then retry the mutating command against a path inside an existing project-recognized subtree.

If Xcode returns a group-resolution failure for a path that is not already represented in the project structure, use a disposable path under an existing group such as a known source folder.

Inspecting daemon state

The default state root is:

~/Library/Application Support/xcode-mcli

Important files:

  • daemon.sock
  • daemon.pid
  • daemon.log
  • state.json

surface verify reports a mismatch

Run:

npm run compat:xcode-mcp:verify

If it fails, inspect the categorized diff with:

xcode-mcli surface verify --baseline-file skill/references/apple-xcode-26.3.surface.json --json

Review whether the live Xcode release changed:

  • protocol version
  • tool definitions
  • prompt definitions
  • resource definitions

If the live contract is the one you want to support, re-pin the baseline snapshot after updating the wrapper behavior that depends on it.