stackdex_neu/.claude/skills/axiom-xcode-mcp-ref/SKILL.md

---
name: axiom-xcode-mcp-ref
description: Reference — all 20 Xcode MCP tools with parameters, return schemas, and examples
license: MIT
---

# Xcode MCP Tool Reference

Complete reference for all 20 tools exposed by Xcode's MCP server (`xcrun mcpbridge`).

**Source**: Xcode 26.3 `tools/list` response. Validated against Keith Smiley's gist (2025-07-15).

**Critical**: `tabIdentifier` is required by 18 of 20 tools. Always call `XcodeListWindows` first.

## Discovery

### XcodeListWindows

Returns open Xcode windows. **Call this first** to get `tabIdentifier` values.

- **Parameters**: None
- **Returns**: `{ message: string }` — description of open windows
- **Notes**: Only tool that does not require `tabIdentifier`.

---

## File Operations

### XcodeRead

Read file contents (cat -n format, 600 lines default).

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `filePath` (string, required) — project-relative or absolute
  - `limit` (integer, optional) — max lines to return
  - `offset` (integer, optional) — starting line number
- **Returns**: `{ content, filePath, fileSize, linesRead, startLine, totalLines }`

### XcodeWrite

Create or overwrite a file. Automatically adds new files to the project structure.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `filePath` (string, required)
  - `content` (string, required)
- **Returns**: `{ success, filePath, absolutePath, bytesWritten, linesWritten, wasExistingFile, message }`

### XcodeUpdate

Edit an existing file with text replacement.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `filePath` (string, required)
  - `oldString` (string, required) — text to find
  - `newString` (string, required) — replacement text
  - `replaceAll` (boolean, optional, default false) — replace all occurrences
- **Returns**: `{ filePath, editsApplied, success, originalContentLength, modifiedContentLength, message }`
- **Notes**: Single replacement by default. Each `oldString` must be unique unless `replaceAll` is true. Prefer over XcodeWrite for editing existing files.

### XcodeGlob

Find files matching a wildcard pattern.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `pattern` (string, optional, default `**/*`) — glob pattern
  - `path` (string, optional) — directory to search within
- **Returns**: `{ matches[], pattern, searchPath, truncated, totalFound, message }`

### XcodeGrep

Search file contents with regex.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `pattern` (string, required) — regex pattern
  - `glob` (string, optional) — file pattern filter
  - `path` (string, optional) — directory scope
  - `type` (string, optional) — file type filter
  - `ignoreCase` (boolean, optional)
  - `multiline` (boolean, optional)
  - `outputMode` (enum, optional) — `content`, `filesWithMatches`, `count`
  - `linesContext` (integer, optional) — context lines
  - `linesBefore` (integer, optional)
  - `linesAfter` (integer, optional)
  - `headLimit` (integer, optional) — max results
  - `showLineNumbers` (boolean, optional)
- **Returns**: `{ results[], pattern, searchPath, matchCount, truncated, message }`
- **Notes**: Mirrors ripgrep's interface. Use `outputMode` to control result format.

### XcodeLS

List directory contents.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `path` (string, required)
  - `recursive` (boolean, optional, default true)
  - `ignore` (array of strings, optional) — patterns to skip
- **Returns**: `{ items[], path }`

### XcodeMakeDir

Create a directory in the project.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `directoryPath` (string, required)
- **Returns**: `{ success, message, createdPath }`

### XcodeRM

Remove files or directories from project. Uses Trash by default.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `path` (string, required)
  - `deleteFiles` (boolean, optional, default true) — move to Trash
  - `recursive` (boolean, optional)
- **Returns**: `{ removedPath, success, message }`

### XcodeMV

Move or copy files.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `sourcePath` (string, required)
  - `destinationPath` (string, required)
  - `operation` (enum, optional) — `move` or `copy`
  - `overwriteExisting` (boolean, optional)
- **Returns**: `{ success, operation, message, sourceOriginalPath, destinationFinalPath }`
- **Notes**: Can copy, not just move. May break imports — confirm with user.

---

## Build & Test

### BuildProject

Build the project and wait for completion.

- **Parameters**:
  - `tabIdentifier` (string, required)
- **Returns**: `{ buildResult, elapsedTime, errors[] }`
- **Notes**: Each error has `classification`, `filePath`, `lineNumber`, `message`.

### GetBuildLog

Retrieve build log with optional filtering.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `severity` (enum, optional) — `remark`, `warning`, `error`
  - `pattern` (string, optional) — regex filter
  - `glob` (string, optional) — file pattern filter
- **Returns**: `{ buildIsRunning, buildLogEntries[], buildResult, fullLogPath, truncated, totalFound }`
- **Notes**: Returns structured entries, not raw text. Each entry has `buildTask` and `emittedIssues[]`.

### RunAllTests

Run the full test suite from the active scheme's test plan.

- **Parameters**:
  - `tabIdentifier` (string, required)
- **Returns**: `{ summary, counts, results[], schemeName, activeTestPlanName }`
- **Notes**: `counts` has `total`, `passed`, `failed`, `skipped`, `expectedFailures`, `notRun`. Each result has `targetName`, `identifier`, `displayName`, `state`.

### RunSomeTests

Run specific tests by identifier.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `tests` (array, required) — each element: `{ targetName: string, testIdentifier: string }`
- **Returns**: Same shape as RunAllTests
- **Notes**: Use `GetTestList` to discover valid test identifiers.

### GetTestList

List available tests from the active test plan.

- **Parameters**:
  - `tabIdentifier` (string, required)
- **Returns**: `{ tests[], schemeName, activeTestPlanName }`
- **Notes**: Each test has `targetName`, `identifier`, `displayName`, `isEnabled`, `filePath`, `lineNumber`, `tags[]`.

---

## Diagnostics

### XcodeListNavigatorIssues

Get issues from Xcode's Issue Navigator.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `severity` (enum, optional) — `remark`, `warning`, `error`
  - `pattern` (string, optional) — regex filter
  - `glob` (string, optional) — file pattern filter
- **Returns**: `{ issues[], truncated, totalFound, message }`
- **Notes**: Each issue has `message`, `severity`, `path`, `line`, `category`, `vitality` (fresh/stale). Structured and deduplicated.

### XcodeRefreshCodeIssuesInFile

Refresh diagnostics for a specific file.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `filePath` (string, required)
- **Returns**: `{ filePath, diagnosticsCount, content, success }`
- **Notes**: Triggers Xcode to re-analyze the file.

---

## Execution & Rendering

### ExecuteSnippet

Build and run a code snippet in the context of a source file.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `codeSnippet` (string, required) — code to execute
  - `sourceFilePath` (string, required) — Swift file whose context the snippet runs in (has access to its `fileprivate` declarations)
  - `timeout` (integer, optional, default 120) — seconds
- **Returns**: `{ executionResults }` — console output from print statements
- **Notes**: Not a generic REPL. Runs in the context of a specific file. No `language` parameter — Swift only.

### RenderPreview

Render a SwiftUI preview snapshot.

- **Parameters**:
  - `tabIdentifier` (string, required)
  - `sourceFilePath` (string, required) — Swift file with `#Preview`
  - `previewDefinitionIndexInFile` (integer, optional, default 0) — zero-based index of which `#Preview` to render
  - `timeout` (integer, optional, default 120)
- **Returns**: `{ previewSnapshotPath }` — path to rendered image
- **Notes**: Index-based, not name-based. First `#Preview` in the file is index 0.

---

## Search

### DocumentationSearch

Search Apple Developer Documentation semantically.

- **Parameters**:
  - `query` (string, required)
  - `frameworks` (array of strings, optional) — scope to specific frameworks
- **Returns**: `{ documents[] }` — each with `title`, `uri`, `contents`, `score`
- **Notes**: Local semantic search (MLX-accelerated), not web search.

---

## Quick Reference

| Category | Tools |
|----------|-------|
| **Discovery** | `XcodeListWindows` |
| **File Read** | `XcodeRead`, `XcodeGlob`, `XcodeGrep`, `XcodeLS` |
| **File Write** | `XcodeWrite`, `XcodeUpdate`, `XcodeMakeDir` |
| **File Destructive** | `XcodeRM`, `XcodeMV` |
| **Build** | `BuildProject`, `GetBuildLog` |
| **Test** | `RunAllTests`, `RunSomeTests`, `GetTestList` |
| **Diagnostics** | `XcodeListNavigatorIssues`, `XcodeRefreshCodeIssuesInFile` |
| **Execution** | `ExecuteSnippet` |
| **Preview** | `RenderPreview` |
| **Search** | `DocumentationSearch` |

## Common Parameter Patterns

- **`tabIdentifier`** — Required by 18/20 tools. Always call `XcodeListWindows` first.
- **`filePath`** — Used by XcodeRead, XcodeWrite, XcodeUpdate, XcodeRefreshCodeIssuesInFile. Project-relative or absolute.
- **`path`** — Used by XcodeLS, XcodeRM, XcodeGlob. Directory path.
- **`directoryPath`** — Used by XcodeMakeDir.
- **`sourceFilePath`** — Used by ExecuteSnippet, RenderPreview. Must be a Swift source file.

## Resources

**Skills**: axiom-xcode-mcp-setup, axiom-xcode-mcp-tools