xcode-cloud-mcp

Минималистичный MCP-сервер для обнаружения продуктов Xcode Cloud, просмотра и редактирования workflows, отслеживания запусков сборок, а также получения проблем сборки, журналов, сводок тестов и артефактов UI-тестов через App Store Connect API.

Возможности

Поиск сборок ограничен рамками workflow. Инструменты получения данных принимают либо прямой buildRunId, либо workflowId в сочетании с buildNumber, либо workflowId в сочетании с buildSelector: "latest" | "latestFailing".

list_products и list_workflows автоматически перебирают все результаты с помощью пагинации.

list_build_runs поддерживает status: "all" | "failed" | "succeeded" | "running" | "pending" и необязательный параметр limit, который по умолчанию равен 20, чтобы агенты могли опрашивать активные workflows без локальной постобработки каждого запуска и без раздувания размера ответа MCP.

Related MCP server: appstore-release-mcp

Требования

• Node.js 20+

• Учётные данные App Store Connect API с доступом к Xcode Cloud

Переменные окружения

Основные имена:

• APPSTORE_CONNECT_API_KEY_ID

• APPSTORE_CONNECT_API_ISSUER_ID

• APPSTORE_CONNECT_API_KEY_CONTENT

Псевдонимы для совместимости:

• APP_STORE_KEY_ID

• APP_STORE_ISSUER_ID

• APP_STORE_PRIVATE_KEY

Приватный ключ можно передать как буквальное многострочное содержимое PEM или как строку с экранированными \n.

Настройка Claude

claude mcp add xcode-cloud \
  --env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
  --env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
  --env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
  -- npx -y @thatfactory/xcode-cloud-mcp

Настройка Codex

codex mcp add xcode-cloud \
  --env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
  --env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
  --env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
  -- npx -y @thatfactory/xcode-cloud-mcp

Доступные инструменты

• list_products()

• list_workflows(productId)

• get_workflow_details(workflowId)

• list_build_runs(workflowId, limit?, status?)

• set_workflow_enabled(workflowId, enabled)

• update_workflow_general(workflowId, name?, description?, clean?)

• update_workflow_start_conditions(workflowId, branchStartCondition?, manualBranchStartCondition?, pullRequestStartCondition?, manualPullRequestStartCondition?, scheduledStartCondition?, tagStartCondition?, manualTagStartCondition?)

• update_workflow_actions(workflowId, actions)

• get_build_issues(buildRunId? workflowId? buildNumber? buildSelector?)

• get_build_logs(buildRunId? workflowId? buildNumber? buildSelector?, maxCharacters?)

• materialize_build_logs(buildRunId? workflowId? buildNumber? buildSelector?)

• get_test_results(buildRunId? workflowId? buildNumber? buildSelector?)

• get_failed_tests(buildRunId? workflowId? buildNumber? buildSelector?)

• get_test_artifacts(buildRunId? workflowId? buildNumber? buildSelector?)

• cleanup_saved_logs(buildRunId?, maxAgeHours?)

Поведение при получении журналов

get_build_logs намеренно сохраняет компактность ответа MCP:

• она скачивает и извлекает текстовые артефакты журналов сборки во временную локальную директорию

• она возвращает savedLogsDirectory и savedLogs, чтобы локальные агенты могли просматривать извлечённые файлы с помощью rg, grep или cat

• она возвращает компактную сводку failedTests, highlights и ограниченный excerpt

• даже если вызывающая сторона передаст очень большое значение maxCharacters, встроенный excerpt ограничивается, чтобы избежать слишком больших ответов MCP

Рекомендуемый порядок действий агента:

1. Вызовите get_failed_tests или get_build_logs.

2. Прочитайте savedLogsDirectory.

3. Используйте rg внутри этой директории, чтобы изучить конкретный упавший тест или проверку.

4. При необходимости после завершения разбора вызовите cleanup_saved_logs.

Временные журналы записываются в системную временную директорию по пути вида:

/tmp/xcode-cloud-mcp/build-logs/<buildRunId>

В macOS это обычно соответствует пути внутри /var/folders/.../T/.

Политика очистки:

• каждый новый вызов для одного и того же buildRunId сначала удаляет и заново создаёт временную директорию, относящуюся к этой сборке

• более старые директории сборок автоматически удаляются, когда они становятся старше 24 часов

• вы также можете вызвать cleanup_saved_logs напрямую для одного buildRunId или для всех директорий старше выбранного периода хранения

Примеры запросов

Retrieve logs of the latest failing build for workflow abc123.

Retrieve logs of build 81, then inspect the returned savedLogsDirectory and grep for Expectation failed.

Get the failed tests for build 81, then open the saved logs directory and inspect the failing test in context.

Retrieve logs of build number 42 for workflow abc123.

Show me the latest failing UI test artifacts for workflow abc123.

List the workflows for product def456 and then summarize the latest build.

Show me the full workflow details for workflow abc123, including environment, start conditions, actions, and whether it is enabled.

Disable workflow abc123, remove the archive action, then restore the original action list after the experiment.

Поведение при получении деталей workflow

get_workflow_details возвращает актуальную конфигурацию workflow, предоставляемую App Store Connect, сгруппированную по разделам:

• general

• environment

• startConditions

• actions

• postActions

Примечания:

• environment включает repository, xcodeVersion и macOsVersion, когда App Store Connect возвращает их.

• actions включает тип действия, схему, платформу, назначение, статус required-to-pass и детали тест-плана, когда они присутствуют.

• postActions в настоящее время возвращается как пустой массив с примечанием, поскольку полезная нагрузка workflow в App Store Connect не раскрывает отдельные post-actions в наблюдаемом ответе API.

Поведение при обновлении workflow

Инструменты обновления workflow намеренно явные:

• set_workflow_enabled только переключает isEnabled

• update_workflow_general изменяет только name, description и clean

• update_workflow_start_conditions изменяет только те объекты условий запуска, которые вы передаёте

• update_workflow_actions заменяет весь массив actions, поэтому вызывающей стороне следует сначала получить текущий workflow, а затем отправить итоговый желаемый список действий

Важное ограничение:

• если в Xcode Cloud для workflow включён параметр Restrict Editing, изменения могут завершаться ошибкой, даже если ключ App Store Connect API имеет доступ App Manager

• чтобы изменения через MCP работали надёжно, отключите флажок Restrict Editing для этого workflow перед использованием инструментов записи

• если Apple по-прежнему отклоняет запрос после этого, используйте более сильную роль ключа API, например Admin

Локальная разработка

Установка зависимостей:

npm install

Запуск тестов:

npm test

Сборка пакета:

npm run build