Appcircle MCP Server

oficial

Servidor MCP oficial de Appcircle

GitHub

¿Qué puedes hacer con Appcircle MCP?

  • Supervisar el estado y los registros de compilación — Usa get_build_status y get_build_logs para revisar ejecuciones de pipelines y depurar fallos.
  • Activar o cancelar compilaciones — Usa trigger_build y cancel_build para iniciar o detener ejecuciones de compilación reales.
  • Generar información de salud de CI/CD — Usa get_build_insights_report para obtener un resumen de salud agregado, tendencias y análisis de causa raíz.
  • Gestionar la distribución de pruebas — Usa get_distribution_profiles y send_app_version_to_testers para enviar compilaciones a los evaluadores.
  • Inspeccionar identidades de firma — Usa get_certificates, get_keystores y get_provisioning_profiles para revisar la configuración de firma.
  • Seguimiento de publicación en la tienda — Usa get_publish_profiles y get_publish_details para monitorear las ejecuciones del flujo de publicación.

Documentación

Appcircle MCP Server

Servidor MCP para Appcircle: expone herramientas de Build, Signing Identities, Testing Distribution, Enterprise App Store, Publish to Stores y Reporting a cualquier cliente compatible con MCP (Claude Desktop, Cursor, VS Code, etc.). El Appcircle MCP Server actúa como puente entre las herramientas de IA y Appcircle; de este modo, los agentes, asistentes y chatbots de IA pueden acceder e interactuar de forma segura con los recursos de Appcircle mediante herramientas estructuradas, gobernadas y a nivel de tarea.

Casos de uso

  • Inteligencia de CI/CD y flujos de trabajo: supervisa ejecuciones de pipelines, sigue el estado de los lanzamientos y obtén información sobre tus flujos de trabajo de CI/CD móvil.
  • Información de configuración y entorno: consulta configuraciones de build y configuración de firmado para entender cómo está configurado un proyecto y dónde pueden originarse los problemas.
  • Información de reportes y operaciones: genera resúmenes de estabilidad de CI, problemas recurrentes, rendimiento de pipelines y salud general de CI/CD.

Modos de ejecución

Puedes usar el servidor MCP de cuatro maneras:

ModoResumen
1. Host remotoConéctate a https://mcp.appcircle.io. Sin instalación local; tu cliente envía tu token de Appcircle (p. ej. Authorization: Bearer <token>) en cada solicitud.
2. Local (stdio)Ejecuta el servidor desde el código fuente: clona el repositorio, opcionalmente usa un venv, y luego ejecuta appcircle-mcp (el transporte predeterminado es stdio). Requiere Python y pip. Establece APPCIRCLE_ACCESS_TOKEN en el entorno. Tu cliente MCP ejecuta el servidor como subproceso.
3. Local (streamable-http)Ejecuta el servidor localmente sobre HTTP: usa --transport streamable-http y opcionalmente --host / --port (p. ej. appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000). Los clientes se conectan a esa URL y envían su token en la solicitud.
4. Local (Docker)Ejecuta la imagen oficial de Docker en tu máquina. Requiere Docker. Usa el puerto predeterminado de la imagen o sobrescríbelo con --port; consulta la documentación de la imagen para el uso exacto.

La configuración detallada del cliente (Cursor, Claude, etc.) se encuentra en las guías de instalación dedicadas; esta sección es solo un resumen de alto nivel.

Instalación

Guías de configuración específicas por cliente:

Configuración (Variables de entorno)

VariableRequeridaDescripción
APPCIRCLE_ACCESS_TOKENSí (solo stdio)Token de acceso a la API de Appcircle. Requerido al usar transporte stdio. Para streamable-http, cada cliente envía su propio token. Consulta Obtención de un token para saber cómo obtenerlo.
APPCIRCLE_API_URLNoURL base de la API (predeterminado: https://api.appcircle.io puede diferir para usuarios de self-hosted).
APPCIRCLE_MCP_ALLOWED_HOSTNo (solo streamable-http)Nombre de host público para el servidor MCP (p. ej. mcp.appcircle.io). Establécelo al implementar detrás de un proxy inverso para que el servidor acepte el encabezado Host de los clientes. Omítelo para localhost.
APPCIRCLE_MCP_PORTNo (solo streamable-http)Puerto de enlace para el servidor HTTP (predeterminado: 8000). Sobrescrito por --port si se proporciona. Útil para on-prem o Docker cuando se requiere un puerto específico.
LOG_LEVELNoNivel de registro, p. ej. DEBUG, INFO (predeterminado: INFO).
APPCIRCLE_EXCLUDED_TOOLSETSNoConjuntos de herramientas separados por comas para excluir (p. ej. build_module,report). Consulta Toolsets a continuación.
AC_MCP_ENABLE_WRITE_TOOLSNoLas herramientas de escritura/acción (p. ej. trigger_build, cancel_build) se registran de forma predeterminada. Establece false/0/no/off para optar por no participar y no registrarlas en absoluto (no solo deshabilitarlas en el momento de la llamada).

Establece estas variables en tu shell o en la configuración de tu cliente MCP.

Toolsets

Toolsets disponibles

Los siguientes conjuntos de herramientas están disponibles:

ToolsetDescripción
build_modulePerfiles de build, configuraciones, flujos de trabajo, commits y operaciones de pipeline
signing_identitiesIdentidades de firmado e identificadores de bundle
testing_distributionPerfiles de distribución de pruebas y detalles de distribución
publish_to_storesPerfiles de publicación y operaciones de publicación en tiendas
enterprise_app_storePerfiles de tienda de aplicaciones empresarial y detalles de tienda
reportReportes: historial de builds, distribución, firmado, estado de publicación y reportes relacionados

Puedes excluir uno o más toolsets para que sus herramientas no se registren. Las exclusiones se pueden configurar mediante argumentos de CLI o la variable de entorno APPCIRCLE_EXCLUDED_TOOLSETS; ambos se combinan (unión).

  • CLI: --exclude toolset1 toolset2 o --exclude-toolsets toolset1,toolset2
  • Env: APPCIRCLE_EXCLUDED_TOOLSETS=build_module,report

Ejemplo de configuración MCP (Cursor / Claude Desktop) con exclusiones:

{
  "mcpServers": {
    "appcircle": {
      "command": "appcircle-mcp",
      "args": ["--exclude", "report"]
    }
  }
}

Herramientas

Las herramientas se exponen mediante MCP tools/list. La referencia a continuación enumera todas las herramientas por toolset; para la forma de respuesta y ejemplos, consulta docs/tool_contract.md.

Build

  • get_build_profiles - Obtiene los perfiles de build de la organización actual (paginado). Opcionalmente filtra por nombre de perfil, plataforma, último estado de build y fuente del repositorio. Opcionalmente ordena.

    • Nivel de acceso: lectura
    • page: Número de página (basado en 1). Predeterminado: 1. (número, opcional)
    • size: Tamaño de página (1-100). Predeterminado: 25. Los valores superiores a 100 se limitan a 100. (número, opcional)
    • search: Término de búsqueda opcional para filtrar perfiles (coincidencia parcial sin distinción de mayúsculas en el nombre del perfil; la búsqueda de la API también puede coincidir con otros campos del perfil). (cadena, opcional)
    • platform: Lista opcional de códigos de plataforma para filtrar. Valores permitidos: 1=iOS, 2=Android. (lista de números, opcional)
    • last_build_status: Lista opcional de códigos de último estado de build para filtrar. Valores permitidos: 0=Éxito, 1=Fallido, 2=Cancelado, 3=Tiempo agotado, 90=En espera, 91=En ejecución. (lista de números, opcional)
    • repository_source: Lista opcional de códigos de fuente del repositorio para filtrar. Valores permitidos: 1=GitHub, 2=Bitbucket, 3=GitLab, 4=Azure DevOps, 6=Repositorio público, 7=Repositorio privado, 8=SSH. (lista de números, opcional)
    • sort: Código de campo de ordenación opcional. Valores permitidos: 1=Nombre del perfil, 2=Fecha de creación, 3=Fecha del último build. (número, opcional)
    • sort_direction: Código de dirección de ordenación opcional. Valores permitidos: 1=ASC, 2=DESC. (número, opcional)

  • get_build_profile_details - Obtiene un único perfil de build por ID, opcionalmente incluyendo sus configuraciones de build.

    • Nivel de acceso: lectura
    • profile_id: El ID del perfil de build (p. ej. UUID). (cadena, requerido)
    • configurations: Si es true, también obtiene las configuraciones de build del perfil. Predeterminado: false. (booleano, opcional)

  • get_build_configuration_details - Obtiene una única configuración de build por ID de perfil e ID de configuración.

    • Nivel de acceso: lectura
    • profile_id: El ID del perfil de build (p. ej. UUID). (cadena, requerido)
    • configuration_id: El ID de la configuración de build (p. ej. UUID). (cadena, requerido)

  • get_build_profile_workflows - Obtiene los flujos de trabajo de un perfil de build por ID de perfil.

    • Nivel de acceso: lectura
    • profile_id: El ID del perfil de build (p. ej. UUID). (cadena, requerido)

  • get_workflow_detail - Obtiene un único flujo de trabajo por ID de perfil de build e ID de flujo de trabajo.

    • Nivel de acceso: lectura
    • profile_id: El ID del perfil de build (p. ej. UUID). (cadena, requerido)
    • workflow_id: El ID del flujo de trabajo (p. ej. UUID). (cadena, requerido)

  • get_commits_by_branch - Obtiene los commits de una rama de build (paginado).

    • Nivel de acceso: lectura
    • branch_id: El ID de la rama (p. ej. UUID). (cadena, requerido)
    • page: Número de página (basado en 1). Si se proporciona con size, habilita la paginación. Predeterminado: 1. (número, opcional)
    • size: Tamaño de página. Si se proporciona con page, habilita la paginación. Predeterminado: 25, máximo 100. (número, opcional)

  • get_commit_details - Obtiene un único commit por ID de commit (UUID) o por hash de commit (git SHA). Proporciona commit_id o commit_hash, no ambos.

    • Nivel de acceso: lectura
    • commit_id: El ID del commit (UUID). (cadena, opcional)
    • commit_hash: El hash del commit (git SHA). (cadena, opcional)

  • get_last_commit - Obtiene el commit más reciente en una rama de build.

    • Nivel de acceso: lectura
    • branch_id: El ID de la rama (p. ej. UUID). (cadena, requerido)

  • get_build_status - Obtiene el estado de un build (p. ej. 0=Éxito, 1=Fallido, 2=Cancelado, 3=Tiempo agotado, 90=En espera, 91=En ejecución, 92=Completando, 99=Desconocido).

    • Nivel de acceso: lectura
    • commit_id: El ID del commit (UUID). (cadena, requerido)
    • build_id: El ID del build (UUID). (cadena, requerido)

  • get_build_logs - Obtiene los registros de un build, opcionalmente limitados a un solo paso. De forma predeterminada, muestra una vista truncada al final para evitar saturar el contexto del modelo.

    • Nivel de acceso: lectura
    • commit_id: El ID del commit (UUID). (cadena, requerido)
    • build_id: El ID del build (UUID). (cadena, requerido)
    • step: Nombre de paso exacto opcional (sin distinción de mayúsculas) para limitar la salida al bloque de registro de un solo paso. (cadena, opcional)
    • full_log: Si es true, devuelve el registro completo en lugar del final predeterminado. Aún limitado a 256 KB. Predeterminado: false. (booleano, opcional)
    • tail_lines: Número de líneas a conservar desde el final cuando no se usa full_log. Predeterminado: 200, máximo 1000. (número, opcional)
    • grep: Filtro de subcadena sin distinción de mayúsculas aplicado a las líneas antes del truncamiento. (cadena, opcional)

  • get_variable_groups - Obtiene todos los grupos de variables de entorno de build de la organización, incluyendo las variables de cada grupo (clave, valor, isSecret, isFile). Los valores secretos ya están redactados por la API.

    • Nivel de acceso: lectura
    • No toma parámetros.

  • trigger_build - EFECTO SECUNDARIO: inicia una nueva ejecución de build real (pone en cola un build real, consumiendo minutos/créditos de build) ya sea en una rama (último commit sincronizado) o para un commit específico. Registrado de forma predeterminada; establece AC_MCP_ENABLE_WRITE_TOOLS=false para optar por no participar.

    • Nivel de acceso: escritura
    • profile_id: El ID del perfil de build (p. ej. UUID). Requerido en modo rama (commit_id no proporcionado); no se usa en modo commit. (cadena, opcional)
    • workflow_id: El ID del flujo de trabajo (p. ej. UUID). Requerido en modo rama. Opcional en modo commit (usa el último flujo de trabajo usado/predeterminado si se omite). (cadena, opcional)
    • branch_name: Nombre de rama opcional (p. ej. "main"). Solo modo rama; se usa la rama predeterminada del perfil si se omite. No debe proporcionarse junto con commit_id. (cadena, opcional)
    • commit_id: El ID propio del commit (no su hash git) para activar un build para un commit específico en lugar del último en una rama. No debe proporcionarse junto con branch_name. (cadena, opcional)
    • configuration_id: ID de configuración de build opcional (p. ej. UUID) para usar en lugar de la predeterminada. (cadena, opcional)

  • cancel_build - EFECTO SECUNDARIO: cancela un build en cola o en ejecución (el trabajo real en curso se detiene; no se puede reanudar). Registrado de forma predeterminada; establece AC_MCP_ENABLE_WRITE_TOOLS=false para optar por no participar.

    • Nivel de acceso: escritura
    • task_id: El ID de tarea del build (el campo "taskId" devuelto por trigger_build). (cadena, requerido)
Signing Identities

  • get_bundle_identifiers - Obtiene todos los identificadores de bundle de la organización (IDs de bundle de aplicaciones iOS/macOS).

    • Nivel de acceso: lectura
    • Sin parámetros.

  • get_certificates - Obtener todos los certificados de firma de la organización. Los campos sensibles (p12Password, p12Binary, metaData, thumbprint) se omiten.

    • Nivel de acceso: lectura
    • Sin parámetros.

  • get_keystores - Obtener todos los almacenes de claves (keystores) de la organización (p. ej. keystores de firma de Android). Los campos sensibles (password, aliasPassword, binary, checkSum, sha256FingerPrint) se omiten.

    • Nivel de acceso: lectura
    • Sin parámetros.

  • get_provisioning_profiles - Obtener perfiles de aprovisionamiento de la organización (p. ej. iOS/macOS). Los campos sensibles/grandes (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) se omiten. Opcionalmente, filtrar por ID de aplicación (bundle).

    • Nivel de acceso: lectura
    • app_id: ID de aplicación (bundle) opcional para filtrar perfiles de aprovisionamiento (p. ej. com.example.app). (string, opcional)
Distribución de pruebas

  • get_distribution_profiles - Obtener perfiles de distribución de pruebas de la organización actual (paginados). Opcionalmente, filtrar por nombre de perfil, plataforma y tipo de autenticación. Opcionalmente, ordenar.

    • Nivel de acceso: lectura
    • page: Número de página (base 1). Predeterminado: 1. (number, opcional)
    • size: Tamaño de página (1-100). Predeterminado: 25, máximo 100. (number, opcional)
    • search: Término de búsqueda opcional para filtrar perfiles (coincidencia parcial sin distinción de mayúsculas/minúsculas en el nombre del perfil; la búsqueda de la API también puede coincidir con otros campos del perfil). (string, opcional)
    • platform: Lista opcional de códigos de plataforma para filtrar. Valores permitidos: 1=iOS, 2=Android. (list of numbers, opcional)
    • authentication_type: Lista opcional de códigos de tipo de autenticación para filtrar. Valores permitidos: 1=None, 3=Static Login, 4=LDAP, 5=SSO. (list of numbers, opcional)
    • sort: Código de campo de ordenación opcional. Valores permitidos: 1=Profile Name, 2=Create Date, 3=Last Upload Date. (number, opcional)
    • sort_direction: Código de dirección de ordenación opcional. Valores permitidos: 1=ASC, 2=DESC. (number, opcional)

  • get_distribution_profile_details - Obtener un único perfil de distribución de pruebas por ID (con paginación opcional de versiones de aplicación).

    • Nivel de acceso: lectura
    • profile_id: El ID del perfil de distribución (p. ej. UUID). (string, obligatorio)
    • page: Número de página para versiones de aplicación (base 1). Predeterminado: 1. (number, opcional)
    • size: Tamaño de página para versiones de aplicación (1-100). Predeterminado: 25, máximo 100. (number, opcional)

  • get_testing_groups - Obtener todos los grupos de distribución de pruebas de la organización, incluidos los correos electrónicos de los evaluadores miembros de cada grupo y el tipo de grupo.

    • Nivel de acceso: lectura
    • No acepta parámetros.

  • update_app_version_release_notes - EFECTO SECUNDARIO: sobrescribe las notas de versión ("message") mostradas a los evaluadores de una versión de aplicación de distribución. Devuelve el objeto de versión de aplicación actualizado (excluye certThumbPrints). Registrado por defecto; establezca AC_MCP_ENABLE_WRITE_TOOLS=false para optar por no participar.

    • Nivel de acceso: escritura
    • profile_id: El ID del perfil de distribución (p. ej. UUID). (string, obligatorio)
    • app_version_id: El ID de la versión de aplicación (p. ej. UUID). (string, obligatorio)
    • message: El nuevo texto de notas de versión. (string, obligatorio)

  • send_app_version_to_testers - EFECTO SECUNDARIO: envía una notificación real a los evaluadores/a un grupo de pruebas, despachando una tarea de distribución para una versión de aplicación específica. Registrado por defecto; establezca AC_MCP_ENABLE_WRITE_TOOLS=false para optar por no participar.

    • Nivel de acceso: escritura
    • profile_id: El ID del perfil de distribución (p. ej. UUID). (string, obligatorio)
    • app_version_id: El ID de la versión de aplicación (p. ej. UUID). (string, obligatorio)
    • message: El mensaje de notificación mostrado a los evaluadores. (string, obligatorio)
    • testers: Lista de evaluadores a los que enviar. Cada entrada es la dirección de correo electrónico de un evaluador o un ID de grupo de pruebas (el campo "id" de get_testing_groups). (list of strings, obligatorio)
Publicar en tiendas

  • get_publish_profiles - Obtener perfiles de publicación de la organización actual para un tipo de plataforma determinado (paginados). Opcionalmente, filtrar por estado de flujo, marketplace de destino, presencia de binario candidato a versión final y estado de tienda. Opcionalmente, ordenar.

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma de los perfiles de publicación ("ios" o "android"). (string, obligatorio)
    • page: Número de página (base 1). Predeterminado: 1. (number, opcional)
    • size: Tamaño de página (1-100). Predeterminado: 25, máximo 100. (number, opcional)
    • flow_status: Código de estado de flujo opcional para filtrar (p. ej. 0=Success, 1=Failed, 91=Running). (number, opcional)
    • market_place_type: Lista opcional de códigos de marketplace de destino para filtrar. Los valores permitidos dependen de platform_type -- ios: 0=Not Available, 1=App Store Connect, 4=Intune; android: 0=Not Available, 2=Google Play, 3=AppGallery, 4=Intune. (list of numbers, opcional)
    • has_rc_binary: Filtro opcional para si el perfil tiene un binario candidato a versión final. (boolean, opcional)
    • store_status: Lista opcional de códigos de estado de tienda para filtrar. Los valores permitidos dependen de platform_type (muchos más códigos para ios que para android, p. ej. ios: "IN_REVIEW", "READY_FOR_SALE", "REJECTED"; android: "NOT_AVAILABLE", "DRAFT", "IN_PROGRESS", "HALTED", "COMPLETED"). (list of strings, opcional)
    • sort: Código de campo de ordenación opcional. Valores permitidos: 1=Profile Name, 2=Create Date. (number, opcional)
    • sort_direction: Código de dirección de ordenación opcional. Valores permitidos: 1=ASC, 2=DESC. (number, opcional)

  • get_publish_profile_details - Obtener un único perfil de publicación por tipo de plataforma e ID (con paginación opcional de versiones de aplicación).

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • page: Número de página para versiones de aplicación (base 1). Predeterminado: 1. (number, opcional)
    • size: Tamaño de página para versiones de aplicación (1-100). Predeterminado: 25, máximo 100. (number, opcional)

  • get_app_version_metadata - Obtener metadatos de listado de tienda para una única versión de aplicación (información de revisión de la aplicación, localizaciones, información de versión, información de versión de aplicación). appReviewInformation.demoPassword se excluye.

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • app_version_id: El ID de la versión de aplicación (p. ej. UUID). (string, obligatorio)

  • get_metadata_locales - Obtener las configuraciones regionales de metadatos de tienda disponibles para una única versión de aplicación (name, code, localized, isPrimary).

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • app_version_id: El ID de la versión de aplicación (p. ej. UUID). (string, obligatorio)

  • get_intune_metadata - Obtener metadatos de aplicación de Microsoft Intune para una única versión de aplicación (display name, publisher, bundle ID, version, publishing state, applicable device types, categories, etc.).

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • app_version_id: El ID de la versión de aplicación (p. ej. UUID). (string, obligatorio)

  • get_publish_metadata_lock_status - Obtener si los metadatos de tienda de un perfil de publicación están bloqueados para edición.

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)

  • get_publish_details - Obtener los detalles de ejecución del flujo de publicación para una única versión de aplicación (status, timing, ordered steps with run history/artifacts/log resource IDs).

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • app_version_id: El ID de la versión de aplicación (p. ej. UUID). (string, obligatorio)

  • get_publish_step_logs - Obtener los registros de una ejecución de flujo de publicación, opcionalmente limitados a un solo paso. De forma predeterminada, se muestra una vista truncada al final para evitar saturar el contexto del modelo.

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • publish_id: El ID de ejecución del flujo de publicación (el campo "id" de get_publish_details). (string, obligatorio)
    • step_id: El ID del paso (el campo "id" de un paso de la lista de pasos de get_publish_details). (string, obligatorio)
    • step: Nombre de paso exacto opcional (sin distinción de mayúsculas/minúsculas) para limitar la salida al bloque de registro de un solo paso. (string, opcional)
    • full_log: Si es true, devuelve el registro completo en lugar del final predeterminado. Aún limitado a 256 KB. Predeterminado: false. (boolean, opcional)
    • tail_lines: Número de líneas a conservar desde el final cuando no se usa full_log. Predeterminado: 200, máximo 1000. (number, opcional)
    • grep: Filtro de subcadena sin distinción de mayúsculas/minúsculas aplicado a las líneas antes del truncamiento. (string, opcional)

  • get_publish_flows - Obtener los flujos de publicación configurados para un perfil de publicación (name, ID, full flow document YAML).

    • Nivel de acceso: lectura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)

  • start_publish - EFECTO SECUNDARIO: inicia una ejecución de flujo de publicación (o la reinicia desde un paso específico) -- trabajo de publicación real (p. ej. subir a App Store/Play Store/Intune). Registrado por defecto; establezca AC_MCP_ENABLE_WRITE_TOOLS=false para optar por no participar.

    • Nivel de acceso: escritura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • publish_id: El ID de ejecución del flujo de publicación (el campo "id" de get_publish_details). (string, obligatorio)
    • step_id: ID de paso opcional para iniciar desde ese paso en lugar del comienzo del flujo. (string, opcional)
    • organization_pool_id: ID de pool de organización opcional (p. ej. UUID) en el que ejecutar. (string, opcional)

  • stop_publish - EFECTO SECUNDARIO: cancela una ejecución de flujo de publicación en curso (el trabajo real en progreso se detiene; no se puede reanudar). Registrado por defecto; establezca AC_MCP_ENABLE_WRITE_TOOLS=false para optar por no participar.

    • Nivel de acceso: escritura
    • platform_type: Tipo de plataforma ("ios" o "android"). (string, obligatorio)
    • profile_id: El ID del perfil de publicación (p. ej. UUID). (string, obligatorio)
    • publish_id: El ID de ejecución del flujo de publicación (el campo "id" de get_publish_details). (string, obligatorio)
    • step_id: ID de paso opcional. (string, opcional)
    • organization_pool_id: ID de pool de organización opcional (p. ej. UUID). (string, opcional)
Tienda de aplicaciones empresarial
  • get_store_profiles - Obtener perfiles de tienda de aplicaciones empresarial de la organización actual (paginados). No admite búsqueda, pero puede filtrar por plataforma, tipo de publicación y visibilidad. Opcionalmente, ordenar.
    • Nivel de acceso: lectura
    • page: Número de página (base 1). Predeterminado: 1. (number, opcional)
    • size: Tamaño de página (1-100). Predeterminado: 25, máximo 100. (number, opcional)
    • platform_type: Lista opcional de códigos de plataforma para filtrar. Valores permitidos: 1=iOS, 2=Android. (list of numbers, opcional)
    • publish_type: Lista opcional de códigos de tipo de publicación para filtrar. Valores permitidos: 1=Published to Beta, 2=Published to Live. (list of numbers, opcional)
    • visibility: Filtro opcional para si el perfil está listado públicamente (true=Listed, false=Unlisted). (boolean, opcional)
    • sort: Código de campo de ordenación opcional. Valores permitidos: 1=App Name, 2=Create Date, 3=Download Count, 4=Binary Receive Date. (number, opcional)
    • sort_direction: Código de dirección de ordenación opcional. Valores permitidos: 1=ASC, 2=DESC. (number, opcional)
  • get_store_profile_details - Obtiene un perfil de tienda de aplicaciones empresarial por ID (con paginación opcional de versiones de aplicaciones).
    • Nivel de acceso: read
    • profile_id: El ID del perfil de tienda de aplicaciones empresarial (por ejemplo, UUID). (string, requerido)
    • page: Número de página para versiones de aplicaciones (basado en 1). Por defecto: 1. (number, opcional)
    • size: Tamaño de página para versiones de aplicaciones (1-100). Por defecto: 25, máx 100. (number, opcional)
    • El campo publishType de cada versión de la aplicación es un int: 0=None, 1=Beta, 2=Live.
Report

  • get_build_history_report - Obtiene el informe del historial de compilaciones, opcionalmente filtrado por rango de fechas, perfil de compilación y organización. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • build_profile_name: Filtrar por nombre de perfil de compilación. (string, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)

  • get_build_queue_waiting_report - Obtiene el informe de espera en cola de compilaciones, opcionalmente filtrado por rango de fechas. Paginado. Nota: en este endpoint, buildDuration significa tiempo de espera en cola en minutos, no tiempo de ejecución (a diferencia de get_build_history_report).

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). Debe ser <= fecha_fin si se proporcionan ambas. (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)

  • get_build_activity_log - Obtiene el registro de actividad de compilación (cambios de flujo de trabajo/perfil, lanzamientos de CodePush, etc.), opcionalmente filtrado por rango de fechas y otros parámetros. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). Debe ser <= fecha_fin si se proporcionan ambas. (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)
    • platform: Filtrar por tipo de plataforma (código entero, por ejemplo, 0=Android, 1=iOS). (number, opcional)
    • email: Filtrar por correo electrónico del usuario que actúa. (string, opcional)
    • profile_name: Filtrar por nombre de perfil de compilación. (string, opcional)
    • action: Filtrar por código de acción de actividad (entero; consulte BUILD_ACTIVITY_ACTIONS en el código fuente de la herramienta para el mapeo completo). (number, opcional)

  • get_build_insights_report - Obtiene un Informe de Insights de Compilación calculado (Snapshot de Salud + Tendencias, Causa Raíz, Salud de Artefactos, Calidad de Flujo de Trabajo, Tiempo de Cola y análisis de Evaluación de Madurez) sobre el historial de compilaciones, agregado en el servidor. A diferencia de get_build_history_report, esto obtiene cada página internamente y devuelve pequeños resultados pre-agregados en lugar de registros crudos.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD) para el período actual. Por defecto: últimos 30 días. (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD) para el período actual. (string, opcional)
    • sections: Lista opcional de secciones a calcular: health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. Por defecto: las seis. (array de strings, opcional)
    • include_sub_orgs: Si es true, mantener registros de compilación entre organizaciones en métricas derivadas del historial en lugar de filtrarlos a la organización del token. Por defecto: false. (boolean, opcional)

  • get_distribution_app_version_report - Obtiene informe de uso diario para versiones de aplicaciones distribuidas. Paginado; admite filtros por perfil, SO, organización.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • profile_name: Filtrar por nombre de perfil de distribución. (string, opcional)
    • os: Filtrar por SO ("ios" o "android"). (string, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)

  • get_distribution_sent_report - Obtiene informe de uso diario para compartir aplicaciones distribuidas. Paginado; admite filtros por perfil, SO, organización.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • profile_name: Filtrar por nombre de perfil de distribución. (string, opcional)
    • os: Filtrar por SO ("ios" o "android"). (string, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)

  • get_enterprise_app_store_app_usage_report - Obtiene informe de uso de aplicaciones para la tienda de aplicaciones empresarial. start_date y end_date son obligatorios. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio (AAAA-MM-DD). (string, requerido)
    • end_date: Fecha de fin (AAAA-MM-DD). (string, requerido)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • organization_id: Filtro opcional por UUID de organización. (string, opcional)

  • get_publish_resign_report - Obtiene informe de re-firma de publicación, opcionalmente filtrado por rango de fechas, nombre de aplicación, organización y estado. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • app_name: Filtrar por nombre de aplicación. (string, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)
    • status: Filtrar por estado de re-firma (0=en espera, 1=procesando, 2=exitoso, 3=fallido, 4=cancelado, 5=tiempo agotado). (number, opcional)

  • get_publish_status_report - Obtiene informe de estado de publicación, opcionalmente filtrado por rango de fechas, nombre de aplicación, organización y estado. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • app_name: Filtrar por nombre de aplicación. (string, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)
    • status: Filtrar por estado de publicación (por ejemplo, 0=Éxito, 1=Fallido, 91=En ejecución). (number, opcional)

  • get_signing_report - Obtiene informe de firma, opcionalmente filtrado por rango de fechas, organización, SO y estado de compilación. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)
    • os: Filtrar por SO ("ios" o "android"). (string, opcional)
    • build_status: Filtrar por estado de compilación (por ejemplo, 0=Éxito, 1=Fallido, 91=En ejecución). (number, opcional)

  • get_signing_activity_log - Obtiene el registro de actividad de firma (por ejemplo, avisos de caducidad de certificado/perfil de aprovisionamiento/keystore), opcionalmente filtrado por rango de fechas y otros parámetros. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). Debe ser <= fecha_fin si se proporcionan ambas. (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)
    • platform: Filtrar por plataforma (por ejemplo, "iOS", "Android"). (string, opcional)
    • email: Filtrar por correo electrónico del usuario que actúa. (string, opcional)
    • action: Filtrar por código de acción de actividad (entero; consulte SIGNING_ACTIVITY_ACTIONS en el código fuente de la herramienta para el mapeo completo). (number, opcional)

  • get_publish_activity_log - Obtiene el registro de actividad de publicación (re-firma, eventos de flujo de publicación, etc.), opcionalmente filtrado por rango de fechas y otros parámetros. Paginado.

    • Nivel de acceso: read
    • start_date: Fecha de inicio opcional (AAAA-MM-DD). Debe ser <= fecha_fin si se proporcionan ambas. (string, opcional)
    • end_date: Fecha de fin opcional (AAAA-MM-DD). (string, opcional)
    • page: Número de página (por defecto: 1). (number, opcional)
    • size: Elementos por página (1-100, por defecto: 50). (number, opcional)
    • organization_id: Filtrar por UUID de organización. (string, opcional)
    • platform: Filtrar por plataforma (por ejemplo, "iOS", "Android"). (string, opcional)
    • email: Filtrar por correo electrónico del usuario que actúa. (string, opcional)
    • profile_name: Filtrar por nombre de perfil de publicación. (string, opcional)
    • action: Filtrar por código de acción de actividad (entero; consulte PUBLISH_ACTIVITY_ACTIONS en el código fuente de la herramienta para el mapeo completo). (number, opcional)

Ejecutar el servidor

Desde la raíz del repositorio:

python -m src.server

O después de pip install -e .:

appcircle-mcp

El servidor se ejecuta sobre stdio (o SSE/HTTP según cómo lo inicie su cliente).

Formato de respuesta

Cada herramienta devuelve un envoltorio estándar:

  • Éxito: { "success": true, "data": <payload>, "meta": { ... } }
    data es el resultado de la herramienta; meta es opcional (por ejemplo, count, page, filters).
  • Error: { "success": false, "error": { "tool", "type", "message", "details" } }
    La misma forma para todas las herramientas para que los clientes puedan analizar errores de manera consistente.

Especificación completa: docs/tool_contract.md.

Pruebas

Instalar con dependencias de desarrollo:

pip install -e ".[dev]"

Pruebas unitarias (predeterminado)

Use una API simulada; no se necesita APPCIRCLE_ACCESS_TOKEN. El pytest predeterminado solo ejecuta estas (consulte testpaths en pyproject.toml):

pytest test/unit/ -v
  • Archivo único: pytest test/unit/tools/build_module/test_get_build_profiles.py -v
  • Con cobertura: pytest test/unit/ --cov=src --cov-report=term-missing

Pruebas de integración

Llame a la API real de Appcircle. Establezca APPCIRCLE_ACCESS_TOKEN en el entorno y luego ejecute:

pytest test/integration/ -v
  • Todas las pruebas de integración: pytest test/integration/ -v
  • Por herramienta: pytest test/integration/build_module/ -v, pytest test/integration/report/ -v, etc.
  • Por marcador: pytest -m integration -v (cuando se ejecuta desde la raíz del repositorio; incluye solo pruebas de integración si se recopilan tanto unitarias como de integración)

Si APPCIRCLE_ACCESS_TOKEN no está configurado, las pruebas de integración se omiten (sin fallo).

Variables de entorno opcionales para pruebas de integración (cuando falla la detección o las pruebas necesitan IDs reales; omítalas para omitir esas pruebas):

VariableDescripción
APPCIRCLE_TEST_ORGANIZATION_IDUUID de organización. Utilizado por test_with_organization_id (informe de uso de aplicaciones de la tienda de aplicaciones empresarial).
APPCIRCLE_TEST_BRANCH_IDUUID de rama. Utilizado por get_commits_by_branch y pruebas relacionadas cuando no se puede descubrir una rama desde la API.
APPCIRCLE_TEST_COMMIT_IDUUID de commit. Utilizado por pruebas de get_commit_details cuando no se puede descubrir un commit desde la API.
Pruebas de integración de escritura/acción (trigger_build, cancel_build, etc.) están marcadas como integration_write y son opt-in además de APPCIRCLE_ACCESS_TOKEN — mutan datos reales (disparan builds reales, etc.), por lo que nunca se ejecutan solo desde pytest test/integration/ -v. Establece APPCIRCLE_RUN_WRITE_INTEGRATION_TESTS=true (apuntando APPCIRCLE_ACCESS_TOKEN a una organización de prueba dedicada, no producción) para habilitarlas.

Seguridad

Este proyecto depende de paquetes de código abierto de terceros listados en pyproject.toml. Aunque fijamos rangos de versiones de dependencias y incluimos un archivo de bloqueo (uv.lock) con hashes criptográficos, estos paquetes se mantienen de forma independiente y se proporcionan "tal cual". Appcircle no ofrece garantías sobre la seguridad o confiabilidad de las dependencias de terceros.

Recomendamos auditar los paquetes instalados antes de usarlos:

uv run pip-audit