Xcode MCP Server

Сервер Model Context Protocol для экосистемы Apple

Подключайте OpenCode, Codex и Claude Code к Xcode — 43 профессиональных инструмента в одном index.js

🌐 Язык: English | Español

Установка • Инструменты • OpenCode • Codex • Claude Code • Документация

Что это такое?

Xcode MCP Server — это серьёзный, готовый к продакшену мост между вашей AI IDE (OpenCode / Codex / Claude Code) и Xcode + Apple Dev Tools.

LLM больше не просто пишет на Swift: она собирает, тестирует, профилирует, управляет симуляторами, физическими устройствами, подписью и даже открывает Xcode на нужной строке — всё через MCP stdio без HTTP-сервера.

Стек: ES Modules · @modelcontextprotocol/sdk@1.30 · StdioServerTransport · promisify(exec) · Yarn 4 Berry · Make

• ✅ Один файл index.js (2250 строк) — без шага сборки, без компиляции, всё можно проверить в одном файле. Shebang #!/usr/bin/env node, готов к запуску через node, yarn start или npx.

• ✅ 43 инструмента со строгой JSON Schema (additionalProperties:false) + глобальный try/catch. Каждый инструмент возвращает content: [{type:"text"}] и isError:true при сбое — без // TODO.

• ✅ Полное покрытие Apple: xcodebuild, simctl (9), devicectl (2), xctrace (5 шаблонов), agvtool, security, osascript/xed.

• ✅ Современный DX: вендоренный Yarn 4 (.yarn/releases), самодокументируемый Makefile с help, модульные docs/, macOS CI + смоук-тест make test.

• ✅ Мультиклиент: один и тот же index.js работает с OpenCode, Codex и Claude Code без изменений.

Related MCP server: Xcode MCP Server

✨ Возможности

📋 Содержание

1. Требования

2. Пошаговая установка

3. Проверка

4. Использование с OpenCode / Codex / Claude Code

5. Инструменты (43)

6. Команды Make

7. Документация

8. Архитектура

9. Вклад в проект

📦 Требования

Linux/Windows: работает только make lint (без Xcode). Для этого CI запускает задачу syntax-linux.

🚀 Пошаговая установка

Следуйте точно в этом порядке. Копируйте и вставляйте блок за блоком.

Шаг 0 — Проверьте Xcode и Node

xcodebuild -version
# Xcode 15.4  Build version 15F31d

node --version
# v20.11.0 (or newer)

yarn --version
# 4.18.0 — if "command not found", run:
corepack enable
corepack prepare yarn@stable --activate
yarn --version

Шаг 1 — Клонируйте репозиторий

git clone https://github.com/YanxReal/Xcode-MPC.git
cd Xcode-MPC

Шаг 2 — Установите зависимости

Вариант A — через Make (рекомендуемый, современный):

make install

Что делает make install:

1. Обнаруживает yarn, при отсутствии устанавливает через corepack

2. Выполняет yarn install (читает yarn.lock, устанавливает @modelcontextprotocol/sdk)

3. Выполняет chmod +x index.js

Ожидаемый вывод:

➤ YN0000: · Yarn 4.18.0
➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed
➤ YN0000: · Done with warnings in 3s
✓ dependencies installed

Вариант B — напрямую через Yarn:

yarn install
chmod +x index.js

Если вы переходите с npm:

rm -f package-lock.json
yarn install

Шаг 3 — Проверьте окружение

make doctor

Должен показать:

Node: v20.x
Yarn: 4.18.0
Xcode: Xcode 15.x
xcrun: xcrun version 70
...
✓ doctor complete

Если вы видите xcodebuild: command not found:

sudo xcode-select -s /Applications/Xcode.app

Шаг 4 — Проверьте MCP-сервер

make lint
# ➜ node --check index.js
# ✓ lint ok

make test
# ➜ smoke test MCP...
# ✓ tools/list: 43 tools
# ✓ xcode_sync_strings OK
# ✓ xcode_certificates_check OK
# ✓ smoke test PASSED

Или вручную:

python3 scripts/smoke_test.py
# or
node scripts/smoke_test.mjs

Шаг 5 — Настройте ваш AI-клиент

Выберите один (или все три — один и тот же index.js работает везде):

Полные пошаговые инструкции с готовыми JSON/TOML для копирования:

• 📘 OpenCode → docs/opencode.md

• 📗 Codex → docs/codex.md

• 📙 Claude Code → docs/claude-code.md

Шаг 6 — Перезапустите и проверьте

Перезапустите OpenCode / Codex / Claude Code и введите:

list the xcode tools

Вы должны увидеть 43 инструмента и в логе:

✅ Xcode MCP Server started (stdio) — 43 tools registered

Готово! Теперь вы можете сказать:

Build MyApp with xcode_build scheme MyApp destination "platform=iOS Simulator,name=iPhone 15"

✅ Проверка

# 1. Syntax
make lint

# 2. Smoke MCP (no Xcode needed, just Node)
make test

# 3. Apple environment
make doctor
# Checks: node, yarn, xcodebuild, xcrun, simctl, swiftlint, security, osascript

# 4. Visual inspector (optional)
make inspect
# or
yarn inspect
# Open http://localhost:6274 → tools/list → tools/call

🔧 Использование с OpenCode / Codex / Claude Code

OpenCode

~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"],
      "env": {}
    }
  }
}

Codex (OpenAI)

~/.codex/config.toml:

[mcp_servers.xcode]
command = "node"
args = ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"]

Claude Code (Anthropic)

claude mcp add xcode -- node /Users/YanxReal/Dev/Tools/Xcode-MPC/index.js
# verify
claude mcp list
# xcode: connected — 43 tools

Или для конкретного проекта с .mcp.json:

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"]
    }
  }
}

Примеры промптов для каждого клиента → docs/opencode.md · docs/codex.md · docs/claude-code.md · Шаблоны: .mcp.json.example · .codex-config.toml.example

🛠️ Инструменты (43)

1. Сборка, диагностика и очистка

2. Тесты и покрытие

3. Симуляторы xcrun simctl (9)

simctl_list (фильтр booted), simctl_lifecycle (boot|shutdown|erase), simctl_install_launch, simctl_media_capture (screenshot|record), simctl_push_notification, simctl_location_mock, simctl_privacy_control, simctl_ui_appearance (light|dark), simctl_open_url

4. Физические устройства xcrun devicectl (2)

devicectl_list (--json), devicectl_logs (deviceUdid*, durationSeconds)

5. Профилирование xcrun xctrace (1)

xctrace_profile (template: Time Profiler|Allocations|Leaks|System Trace, timeLimitSeconds, outputFilePath*)

6. Версии и безопасность (2)

agvtool_version_bump (bump_build|set_version|set_build), xcode_certificates_check (security find-identity)

7. GUI-редактор Xcode (2)

xcode_get_active_file (AppleScript osascript), xcode_open_at_line (filePath*, line*, column — xed → xcode://)

8. Локализация (1)

xcode_sync_strings (.xcstrings → missing / pendingTranslation / emptyValues)

9. Ассеты Assets.xcassets + actool (6)

asset_list_contents (перечисляет *.colorset/*.imageset), asset_manage_color (#RRGGBB Light + Dark), asset_manage_image (scales/vector + preserves-vector-representation), asset_read_info (Contents.json), asset_delete (безопасно), asset_validate_actool (xcrun actool --compile)

10. AppIcon для всех ОС Apple (1)

asset_generate_appicon (iOS, macOS, watchOS, tvOS, visionOS — 42 слота, sips -z, если указан baseImagePath)

11. Пакеты SPM / CocoaPods / Carthage (11)

package_resolve/update/list/read_resolved/reset_cache/compute_checksum, spm_add/remove_dependency, cocoapods_manage, carthage_manage, cocoapods_to_spm_migrate (Podfile→Package.swift)

Полный справочник с JSON Schema и примерами для копирования → docs/tools.md

📖 Команды Make

make help          # Show this pretty help (colors)
make install       # yarn install + chmod +x
make reinstall     # clean + install (from scratch)
make lint          # node --check index.js
make doctor        # Check Node/Yarn/Xcode/simctl/swiftlint/osascript
make test          # Smoke test MCP (43 tools + 2 calls)
make start         # yarn start (stdio)
make dev           # yarn dev (--watch)
make inspect       # MCP Inspector at http://localhost:6274
make clean         # Remove node_modules/.yarn/cache/build
make fmt           # prettier if available
make release VERSION=1.0.1  # bump + tag + push

Подробности → docs/development.md

📚 Документация

🧪 Ручной смоук-тест

# Without Make:
python3 scripts/smoke_test.py
# STDERR: ✅ Xcode MCP Server started — 43 tools
# ✓ tools/list: 43 tools
# ✓ xcode_sync_strings OK
# ✓ smoke test PASSED

# With Make:
make test

🏗️ Архитектура

index.js (2250 lines, 1 file)
├── Shebang + Imports (MCP SDK, promisify(exec), fs, path, os)
├── Helpers: shellEscape, expandTilde, runCommand (try/catch + 10MB buffer), formatResult
├── TOOLS[43]: Strict JSON Schema (additionalProperties:false)
├── Handlers[43]: async handle_* with validation + fallbacks (xed→xcode://, swift-format→swiftlint)
├── Dispatcher: HANDLERS map + ListTools/CallTool (try/catch → isError:true)
└── Server: StdioServerTransport (stdin JSON-RPC, stdout JSON-RPC, stderr logs)

Решение об одном файле и поток OpenCode → stdin → handler → xcrun → stdout описаны в docs/architecture.md.

🤝 Участие

# 1. Fork and branch
git checkout -b feat/my-tool

# 2. Develop: add to TOOLS + Handler + HANDLERS in index.js
make install && make lint && make test

# 3. Document in docs/tools.md + README.md

# 4. PR

Issues: Сообщение об ошибке · Запрос функции · Шаблон PR

CI запускается на macos-14 и ubuntu-latest — ваш PR тестируется автоматически.

📄 Лицензия

MIT © YanxReal — см. LICENSE.

🔗 Ссылки

• Репозиторий: https://github.com/YanxReal/Xcode-MPC

• Спецификация MCP: https://modelcontextprotocol.io

• SDK: https://github.com/modelcontextprotocol/typescript-sdk

• Yarn Berry: https://yarnpkg.com/getting-started

• Xcode: https://developer.apple.com/xcode/

Сделано с ❤️ для экосистемы Apple · Yarn 4 + Make + CI + Docs

Если проект вам помог, поставьте ⭐ на GitHub