xcode-cloud-mcp

Servidor MCP mínimo para descubrir productos de Xcode Cloud, inspeccionar y editar flujos de trabajo, supervisar ejecuciones de compilación y recuperar problemas de compilación, registros, resúmenes de pruebas y artefactos de pruebas de interfaz de usuario a través de la API de App Store Connect.

Características

La búsqueda de compilaciones está limitada al flujo de trabajo. Las herramientas de recuperación aceptan un buildRunId directo, o un workflowId más buildNumber, o un workflowId más buildSelector: "latest" | "latestFailing".

list_products y list_workflows pagan automáticamente por todos los resultados.

list_build_runs admite status: "all" | "failed" | "succeeded" | "running" | "pending" y un limit opcional, que por defecto es 20, para que los agentes puedan consultar flujos de trabajo activos sin tener que procesar cada ejecución localmente ni aumentar el tamaño de la respuesta de MCP.

Related MCP server: appstore-release-mcp

Requisitos

• Node.js 20+

• Credenciales de la API de App Store Connect con acceso a Xcode Cloud

Variables de Entorno

Nombres principales:

• APPSTORE_CONNECT_API_KEY_ID

• APPSTORE_CONNECT_API_ISSUER_ID

• APPSTORE_CONNECT_API_KEY_CONTENT

Alias de compatibilidad:

• APP_STORE_KEY_ID

• APP_STORE_ISSUER_ID

• APP_STORE_PRIVATE_KEY

La clave privada se puede pasar como contenido PEM literal de varias líneas o como una cadena con \n escapado.

Configuración de 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

Configuración de 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

Herramientas Disponibles

• 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?)

Comportamiento de Recuperación de Registros

get_build_logs mantiene la respuesta de MCP compacta a propósito:

• descarga y extrae los artefactos de registro de compilación de tipo texto a un directorio temporal local

• devuelve savedLogsDirectory y savedLogs para que los agentes locales puedan inspeccionar los archivos extraídos con rg, grep o cat

• devuelve un resumen compacto de failedTests, highlights y un excerpt limitado

• incluso si el llamador pasa un maxCharacters muy grande, el extracto en línea se limita para evitar respuestas de MCP demasiado grandes

Flujo de trabajo recomendado para el agente:

1. Llama a get_failed_tests o get_build_logs.

2. Lee savedLogsDirectory.

3. Usa rg en ese directorio para inspeccionar la prueba o aserción exacta que falla.

4. Si es necesario, llama a cleanup_saved_logs cuando termines la investigación.

Los registros temporales se escriben en el directorio temporal del sistema en una ruta como:

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

En macOS, normalmente se resuelve a una ruta en /var/folders/.../T/.

Política de limpieza:

• cada nueva llamada para el mismo buildRunId elimina y vuelve a crear primero ese directorio temporal específico de la compilación

• los directorios de compilación antiguos se eliminan automáticamente cuando tienen más de 24 horas

• también puedes llamar a cleanup_saved_logs directamente para un buildRunId o para todos los directorios más antiguos que el período de retención elegido

Ejemplos de Prompts

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.

Comportamiento de Detalles del Flujo de Trabajo

get_workflow_details devuelve la configuración en vivo del flujo de trabajo expuesta por App Store Connect, agrupada en:

• general

• environment

• startConditions

• actions

• postActions

Notas:

• environment incluye el repositorio, xcodeVersion y macOsVersion cuando App Store Connect los devuelve.

• actions incluye el tipo de acción, esquema, plataforma, destino, estado de requerido para pasar y detalles del plan de pruebas cuando estén presentes.

• postActions actualmente se devuelve como una matriz vacía con una nota porque la carga útil del flujo de trabajo de App Store Connect no expone acciones posteriores separadas en la respuesta de API observada.

Comportamiento de Actualización del Flujo de Trabajo

Las herramientas de actualización del flujo de trabajo son intencionadamente explícitas:

• set_workflow_enabled solo alterna isEnabled

• update_workflow_general solo cambia name, description y clean

• update_workflow_start_conditions solo cambia los objetos de condición de inicio que pases

• update_workflow_actions reemplaza la matriz completa de actions, por lo que los llamadores deben obtener primero el flujo de trabajo actual y luego enviar la lista de acciones final deseada

Restricción importante:

• si el flujo de trabajo tiene Restrict Editing habilitado en Xcode Cloud, las ediciones pueden fallar incluso si la clave de API de App Store Connect tiene acceso de App Manager

• para que las ediciones de MCP funcionen de forma fiable, desmarca la casilla Restrict Editing de ese flujo de trabajo antes de usar las herramientas de escritura

• si Apple sigue rechazando la solicitud después de eso, usa un rol de clave de API más potente, como Admin

Desarrollo Local

Instala las dependencias:

npm install

Ejecuta las pruebas:

npm test

Compila el paquete:

npm run build