# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build Commands
```bash
npm run build # Compile TypeScript to dist/
npm run dev # Run with tsx (development)
npm test # Run tests with vitest
```
## Testing the MCP Server
Test tools by piping JSON-RPC requests to the built server:
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"xcodebuild_list","arguments":{"directory":"/path/to/ios/project"}}}' | node dist/index.js
```
## Architecture
This is an MCP (Model Context Protocol) server that exposes Xcode developer tools as MCP tools.
### Tool Categories
- **simctl tools** (`simctl_*`): Wrap `xcrun simctl` for iOS Simulator control
- **xcodebuild tools** (`xcodebuild_*`): Wrap `xcodebuild` for building/testing Xcode projects
- **wda tools** (`wda_*`): WebDriverAgent integration for UI automation (tap, swipe, type, find elements)
### Code Structure
**Executors** (`src/executor/`): Low-level command execution wrappers
- `index.ts` - Base `execute()` function for running shell commands
- `simctl.ts` - `simctl()` and `simctlJson()` for simulator commands
- `xcodebuild.ts` - `xcodebuild*()` functions with result bundle parsing
- `wda.ts` - Async HTTP client for WebDriverAgent REST API with retry logic
**Tools** (`src/tools/`): MCP tool definitions with Zod schemas
- Each tool exports: `{toolName}Schema` (Zod schema) and `{toolName}Tool` (name, description, handler)
- Tools are registered in `src/server.ts`
**Utilities** (`src/utils/`):
- `device-resolver.ts` - Resolve device names/UDIDs, `buildSimulatorDestination()`
- `project-resolver.ts` - Auto-detect .xcworkspace/.xcodeproj
- `result-bundle-parser.ts` - Parse .xcresult bundles via `xcresulttool`
- `wda-session.ts` - WDA session management with lazy creation and auto-recovery
### Adding a New Tool
1. Create `src/tools/{tool-name}.ts` with Zod schema and tool definition
2. Import and register in `src/server.ts` using `server.tool()`
3. Follow existing tool patterns:
- `src/tools/boot.ts` for simctl tools (sync shell commands)
- `src/tools/xcodebuild-build.ts` for xcodebuild tools
- `src/tools/wda-tap.ts` for WDA tools (async HTTP)
### Key Patterns
- Device identifiers accept: UDID, device name (e.g., "iPhone 16 Pro"), or "booted"
- xcodebuild tools auto-detect workspace/project from cwd if not specified
- Result bundles are auto-generated in temp dir and cleaned up after parsing
- Tool handlers return `{ content: [{ type: 'text', text: string }] }`
- WDA tools use async HTTP (unlike sync simctl); sessions are auto-managed
- WDA coordinates are in **points** (logical pixels), not physical pixels
## Git Workflow
For non-trivial changes:
1. Create a feature branch: `git checkout -b feature/description`
2. Make changes and commit
3. Push and create a PR: `gh pr create`
4. Request a subagent code review before merging (use Task tool with Plan agent)
5. Address review feedback, then merge
