charleswiltgen/axiom-xcode-mcp-ref

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