Appcircle MCP Server

oficial

Servidor MCP oficial de Appcircle

GitHub

¿Qué puedes hacer con Appcircle MCP?

Listar y buscar perfiles de compilación — Recupera perfiles de compilación paginados y filtra por nombre con get_build_profiles.
Inspeccionar configuraciones de compilación y flujos de trabajo — Obtén detalles de un perfil de compilación específico, sus configuraciones y flujos de trabajo usando get_build_profile_details, get_build_configuration_details y get_workflow_detail.
Revisar identidades de firma — Lista certificados, almacenes de claves, perfiles de aprovisionamiento e identificadores de paquete mediante get_certificates, get_keystores, get_provisioning_profiles y get_bundle_identifiers.
Verificar el estado de distribución empresarial y de pruebas — Obtén perfiles de distribución y sus versiones de aplicación con get_distribution_profiles y get_distribution_profile_details, o inspecciona perfiles de tienda empresarial mediante get_store_profiles.
Generar informes de salud de CI/CD e historial de compilaciones — Usa get_build_insights_report para tendencias agregadas y análisis de causa raíz, o get_build_history_report para registros de compilación sin procesar.

Documentación

Servidor MCP de Appcircle

Servidor MCP para Appcircle: expone herramientas de Compilación, Identidades de Firma, Distribución de Pruebas, Tienda de Aplicaciones Empresarial, Publicación en Tiendas y Reportes a cualquier cliente compatible con MCP (Claude Desktop, Cursor, VS Code, etc.). El Servidor MCP de Appcircle actúa como el puente entre las herramientas de IA y Appcircle; de esta manera, los agentes de IA, asistentes y chatbots pueden acceder e interactuar de forma segura con los recursos de Appcircle a través de herramientas estructuradas, gobernadas y a nivel de tarea.

Casos de Uso

Inteligencia de CI/CD y Flujos de Trabajo: Monitorear ejecuciones de pipelines, rastrear el estado de lanzamientos y obtener información sobre tus flujos de trabajo de CI/CD móviles.
Información de Configuración y Entorno: Consultar configuraciones de compilación y configuración de firma para entender cómo está configurado un proyecto y dónde pueden originarse los problemas.
Reportes e Información Operativa: Generar 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:

Modo	Resumen
1. Host remoto	Conéctate a https://mcp.appcircle.io. Sin instalación local; tu cliente envía tu token de Appcircle (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, 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 un subproceso.
3. Local (streamable-http)	Ejecuta el servidor localmente sobre HTTP: usa `--transport streamable-http` y opcionalmente `--host` / `--port` (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 para cada cliente:

Aplicaciones Claude - Guía de instalación para Claude Desktop y Claude Code CLI.
Cursor IDE - Guía de instalación para Cursor IDE.
Codex - Guía de instalación para la aplicación Codex y Codex CLI.
Antigravity IDE - Guía de instalación para Antigravity IDE.
VS Code (GitHub Copilot) - Guía de instalación para VS Code con GitHub Copilot.
Windsurf IDE - Guía de instalación para Windsurf IDE.
Gemini CLI - Guía de instalación para Gemini CLI.
GitHub Copilot CLI - Guía de instalación para GitHub Copilot CLI.

Configuración (Variables de Entorno)

Variable	Requerida	Descripción
`APPCIRCLE_ACCESS_TOKEN`	Sí (solo stdio)	Token de acceso a la API de Appcircle. Requerido al usar el transporte stdio. Para streamable-http, cada cliente envía su propio token. Consulta Obtención de un token para saber cómo obtener uno.
`APPCIRCLE_API_URL`	No	URL base de la API (predeterminado: `https://api.appcircle.io` puede diferir para usuarios autoalojados).
`APPCIRCLE_MCP_ALLOWED_HOST`	No (solo streamable-http)	Nombre de host público para el servidor MCP (ej. `mcp.appcircle.io`). Establece esto al desplegar detrás de un proxy inverso para que el servidor acepte el encabezado `Host` de los clientes. Omite para localhost.
`APPCIRCLE_MCP_PORT`	No (solo streamable-http)	Puerto de enlace para el servidor HTTP (predeterminado: `8000`). Sobrescrito por `--port` si se proporciona. Útil para instalaciones locales o Docker cuando se requiere un puerto específico.
`LOG_LEVEL`	No	Nivel de registro, ej. `DEBUG`, `INFO` (predeterminado: `INFO`).
`APPCIRCLE_EXCLUDED_TOOLSETS`	No	Conjuntos de herramientas a excluir separados por comas (ej. `build_module,report`). Consulta Conjuntos de herramientas a continuación.

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

Conjuntos de Herramientas

Conjuntos de Herramientas Disponibles

Los siguientes conjuntos de herramientas están disponibles:

Conjunto de herramientas	Descripción
`build_module`	Perfiles de compilación, configuraciones, flujos de trabajo, commits y operaciones de pipeline
`signing_identities`	Identidades de firma e identificadores de bundle
`testing_distribution`	Perfiles de distribución de pruebas y detalles de distribución
`publish_to_stores`	Perfiles de publicación y operaciones de publicación en tiendas
`enterprise_app_store`	Perfiles de tienda de aplicaciones empresarial y detalles de la tienda
`report`	Reportes: historial de compilación, distribución, firma, estado de publicación y reportes relacionados

Puedes excluir uno o más conjuntos de herramientas para que sus herramientas no se registren. Las exclusiones se pueden establecer mediante argumentos de CLI o la variable de entorno APPCIRCLE_EXCLUDED_TOOLSETS; ambas 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 a través de MCP tools/list. La referencia a continuación enumera todas las herramientas por conjunto de herramientas; para la forma de la respuesta y ejemplos, consulta docs/tool_contract.md.

Compilación

get_build_profiles - Obtiene perfiles de compilación para la organización actual (paginado). Opcionalmente filtra por nombre de perfil.
- 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. Valores superiores a 100 se limitan a 100. (número, opcional)
- search: Término de búsqueda opcional para filtrar perfiles por nombre (coincidencia parcial sin distinción de mayúsculas/minúsculas). (cadena, opcional)
get_build_profile_details - Obtiene un solo perfil de compilación por ID, incluyendo opcionalmente sus configuraciones de compilación.
- Nivel de acceso: lectura
- profile_id: El ID del perfil de compilación (ej. UUID). (cadena, requerido)
- configurations: Si es true, también obtiene las configuraciones de compilación del perfil. Predeterminado: false. (booleano, opcional)
get_build_configuration_details - Obtiene una sola configuración de compilación por ID de perfil e ID de configuración.
- Nivel de acceso: lectura
- profile_id: El ID del perfil de compilación (ej. UUID). (cadena, requerido)
- configuration_id: El ID de la configuración de compilación (ej. UUID). (cadena, requerido)
get_build_profile_workflows - Obtiene flujos de trabajo para un perfil de compilación por ID de perfil.
- Nivel de acceso: lectura
- profile_id: El ID del perfil de compilación (ej. UUID). (cadena, requerido)
get_workflow_detail - Obtiene un solo flujo de trabajo por ID de perfil de compilación e ID de flujo de trabajo.
- Nivel de acceso: lectura
- profile_id: El ID del perfil de compilación (ej. UUID). (cadena, requerido)
- workflow_id: El ID del flujo de trabajo (ej. UUID). (cadena, requerido)
get_commits_by_branch - Obtiene commits para una rama de compilación (paginado).
- Nivel de acceso: lectura
- branch_id: El ID de la rama (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áx. 100. (número, opcional)
get_commit_details - Obtiene un solo 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)

Identidades de Firma

get_bundle_identifiers - Obtiene todos los identificadores de bundle para la organización (IDs de bundle de aplicaciones iOS/macOS).
- Nivel de acceso: lectura
- Sin parámetros.
get_certificates - Obtiene todos los certificados de firma para la organización. Los campos sensibles (p12Password, p12Binary, metaData, thumbprint) se omiten.
- Nivel de acceso: lectura
- Sin parámetros.
get_keystores - Obtiene todos los almacenes de claves para la organización (ej. almacenes de claves de firma de Android). Los campos sensibles (password, aliasPassword, binary, checkSum, sha256FingerPrint) se omiten.
- Nivel de acceso: lectura
- Sin parámetros.
get_provisioning_profiles - Obtiene perfiles de aprovisionamiento para la organización (ej. iOS/macOS). Los campos sensibles/grandes (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) se omiten. Opcionalmente filtra por ID de app (bundle).
- Nivel de acceso: lectura
- app_id: ID de app (bundle) opcional para filtrar perfiles de aprovisionamiento (ej. com.example.app). (cadena, opcional)

Distribución de Pruebas

get_distribution_profiles - Obtiene perfiles de distribución de pruebas para la organización actual (paginado). Opcionalmente filtra por nombre de perfil.
- 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, máx. 100. (número, opcional)
- search: Término de búsqueda opcional para filtrar perfiles por nombre. (cadena, opcional)
get_distribution_profile_details - Obtiene un solo perfil de distribución de pruebas por ID (con paginación opcional de versiones de la app).
- Nivel de acceso: lectura
- profile_id: El ID del perfil de distribución (ej. UUID). (cadena, requerido)
- page: Número de página para versiones de la app (basado en 1). Predeterminado: 1. (número, opcional)
- size: Tamaño de página para versiones de la app (1-100). Predeterminado: 25, máx. 100. (número, opcional)

Publicación en Tiendas

get_publish_profiles - Obtiene perfiles de publicación para la organización actual para un tipo de plataforma dado (paginado). Opcionalmente filtra por estado de flujo.
- Nivel de acceso: lectura
- platform_type: Tipo de plataforma de los perfiles de publicación ("ios" o "android"). (cadena, requerido)
- page: Número de página (basado en 1). Predeterminado: 1. (número, opcional)
- size: Tamaño de página (1-100). Predeterminado: 25, máx. 100. (número, opcional)
- flow_status: Código de estado de flujo opcional para filtrar (ej. 0=Éxito, 1=Fallido, 91=Ejecutándose). (número, opcional)
get_publish_profile_details - Obtiene un solo perfil de publicación por tipo de plataforma e ID (con paginación opcional de versiones de la app).
- Nivel de acceso: lectura
- platform_type: Tipo de plataforma ("ios" o "android"). (cadena, requerido)
- profile_id: El ID del perfil de publicación (ej. UUID). (cadena, requerido)
- page: Número de página para versiones de la app (basado en 1). Predeterminado: 1. (número, opcional)
- size: Tamaño de página para versiones de la app (1-100). Predeterminado: 25, máx. 100. (número, opcional)

Tienda de Aplicaciones Empresarial

get_store_profiles - Obtiene perfiles de tienda de aplicaciones empresarial para la organización actual (paginado).
- 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, máx. 100. (número, opcional)
get_store_profile_details - Obtiene un solo perfil de tienda de aplicaciones empresarial por ID (con paginación opcional de versiones de la app).
- Nivel de acceso: lectura
- profile_id: El ID del perfil de tienda de aplicaciones empresarial (ej. UUID). (cadena, requerido)
- page: Número de página para versiones de la app (basado en 1). Predeterminado: 1. (número, opcional)
- size: Tamaño de página para versiones de la app (1-100). Predeterminado: 25, máx. 100. (número, opcional)

Reporte

- **get_build_history_report** - Obtiene el informe del historial de compilaciones, filtrado opcionalmente por rango de fechas, perfil de compilación y organización. Paginado. - **Nivel de acceso:** lectura - `start_date`: Fecha de inicio opcional (AAAA-MM-DD). (cadena, opcional) - `end_date`: Fecha de fin opcional (AAAA-MM-DD). (cadena, opcional) - `page`: Número de página (predeterminado: 1). (número, opcional) - `size`: Elementos por página (1-100, predeterminado: 50). (número, opcional) - `build_profile_name`: Filtrar por nombre del perfil de compilación. (cadena, opcional) - `organization_id`: Filtrar por UUID de la organización. (cadena, opcional)

get_build_insights_report - Obtiene un Informe de Perspectivas de Compilación calculado (Instantánea de Salud + Tendencias, Causa Raíz, Salud de Artefactos, Calidad del Flujo de Trabajo, Tiempo en Cola y análisis de Evaluación de Madurez) sobre el historial de compilaciones, agregado del lado del servidor. A diferencia de get_build_history_report, este obtiene cada página internamente y devuelve pequeños resultados pre-agregados en lugar de registros sin procesar.
- Nivel de acceso: lectura
- start_date: Fecha de inicio opcional (AAAA-MM-DD) para el período actual. Predeterminado: últimos 30 días. (cadena, opcional)
- end_date: Fecha de fin opcional (AAAA-MM-DD) para el período actual. (cadena, opcional)
- sections: Lista opcional de secciones a calcular: health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. Predeterminado: las seis. (arreglo de cadenas, opcional)
- include_sub_orgs: Si es verdadero, mantiene registros de compilación entre organizaciones en las métricas derivadas del historial en lugar de filtrar por la propia organización del token. Predeterminado: falso. (booleano, opcional)
get_distribution_app_version_report - Obtiene el informe de uso diario para las versiones de aplicaciones distribuidas. Paginado; admite filtros por perfil, SO, organización.
- Nivel de acceso: lectura
- start_date: Fecha de inicio opcional (AAAA-MM-DD). (cadena, opcional)
- end_date: Fecha de fin opcional (AAAA-MM-DD). (cadena, opcional)
- page: Número de página (predeterminado: 1). (número, opcional)
- size: Elementos por página (1-100, predeterminado: 50). (número, opcional)
- profile_name: Filtrar por nombre del perfil de distribución. (cadena, opcional)
- os: Filtrar por SO ("ios" o "android"). (cadena, opcional)
- organization_id: Filtrar por UUID de la organización. (cadena, opcional)
get_distribution_sent_report - Obtiene el informe de uso diario para el uso compartido de aplicaciones distribuidas. Paginado; admite filtros por perfil, SO, organización.
- Nivel de acceso: lectura
- start_date: Fecha de inicio opcional (AAAA-MM-DD). (cadena, opcional)
- end_date: Fecha de fin opcional (AAAA-MM-DD). (cadena, opcional)
- page: Número de página (predeterminado: 1). (número, opcional)
- size: Elementos por página (1-100, predeterminado: 50). (número, opcional)
- profile_name: Filtrar por nombre del perfil de distribución. (cadena, opcional)
- os: Filtrar por SO ("ios" o "android"). (cadena, opcional)
- organization_id: Filtrar por UUID de la organización. (cadena, opcional)
get_enterprise_app_store_app_usage_report - Obtiene el informe de uso de aplicaciones para la tienda de aplicaciones empresarial. start_date y end_date son obligatorios. Paginado.
- Nivel de acceso: lectura
- start_date: Fecha de inicio (AAAA-MM-DD). (cadena, obligatorio)
- end_date: Fecha de fin (AAAA-MM-DD). (cadena, obligatorio)
- page: Número de página (predeterminado: 1). (número, opcional)
- size: Elementos por página (1-100, predeterminado: 50). (número, opcional)
- organization_id: Filtro opcional por UUID de la organización. (cadena, opcional)
get_publish_resign_report - Obtiene el informe de resignación de publicación, filtrado opcionalmente por rango de fechas, nombre de la aplicación, organización y estado. Paginado.
- Nivel de acceso: lectura
- start_date: Fecha de inicio opcional (AAAA-MM-DD). (cadena, opcional)
- end_date: Fecha de fin opcional (AAAA-MM-DD). (cadena, opcional)
- page: Número de página (predeterminado: 1). (número, opcional)
- size: Elementos por página (1-100, predeterminado: 50). (número, opcional)
- app_name: Filtrar por nombre de la aplicación. (cadena, opcional)
- organization_id: Filtrar por UUID de la organización. (cadena, opcional)
- status: Filtrar por estado de resignación (0=esperando, 1=procesando, 2=exitoso, 3=fallido, 4=cancelado, 5=tiempo de espera agotado). (número, opcional)
get_publish_status_report - Obtiene el informe de estado de publicación, filtrado opcionalmente por rango de fechas, nombre de la aplicación, organización y estado. Paginado.
- Nivel de acceso: lectura
- start_date: Fecha de inicio opcional (AAAA-MM-DD). (cadena, opcional)
- end_date: Fecha de fin opcional (AAAA-MM-DD). (cadena, opcional)
- page: Número de página (predeterminado: 1). (número, opcional)
- size: Elementos por página (1-100, predeterminado: 50). (número, opcional)
- app_name: Filtrar por nombre de la aplicación. (cadena, opcional)
- organization_id: Filtrar por UUID de la organización. (cadena, opcional)
- status: Filtrar por estado de publicación (ej. 0=Exitoso, 1=Fallido, 91=Ejecutándose). (número, opcional)
get_signing_report - Obtiene el informe de firma, filtrado opcionalmente por rango de fechas, organización, SO y estado de compilación. Paginado.
- Nivel de acceso: lectura
- start_date: Fecha de inicio opcional (AAAA-MM-DD). (cadena, opcional)
- end_date: Fecha de fin opcional (AAAA-MM-DD). (cadena, opcional)
- page: Número de página (predeterminado: 1). (número, opcional)
- size: Elementos por página (1-100, predeterminado: 50). (número, opcional)
- organization_id: Filtrar por UUID de la organización. (cadena, opcional)
- os: Filtrar por SO ("ios" o "android"). (cadena, opcional)
- build_status: Filtrar por estado de compilación (ej. 0=Exitoso, 1=Fallido, 91=Ejecutándose). (número, opcional)

Ejecución del 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 dependiendo de 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 (ej. count, page, filters).
Error: { "success": false, "error": { "tool", "type", "message", "details" } }
Misma forma para todas las herramientas para que los clientes puedan analizar los errores de manera consistente.

Especificación completa: docs/tool_contract.md.

Pruebas

Instalar con dependencias de desarrollo:

pip install -e ".[dev]"

Pruebas unitarias (predeterminadas)

Usan una API simulada; no se necesita APPCIRCLE_ACCESS_TOKEN. El pytest predeterminado solo ejecuta estas (ver 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

Llaman a la API real de Appcircle. Establezca APPCIRCLE_ACCESS_TOKEN en el entorno, 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 (al ejecutar 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 el descubrimiento falla o las pruebas necesitan IDs reales; omítalas para saltar esas pruebas):

Variable	Descripción
`APPCIRCLE_TEST_ORGANIZATION_ID`	UUID de la organización. Usado por `test_with_organization_id` (informe de uso de aplicaciones de la tienda empresarial).
`APPCIRCLE_TEST_BRANCH_ID`	UUID de la rama. Usado por get_commits_by_branch y pruebas relacionadas cuando no se puede descubrir ninguna rama desde la API.
`APPCIRCLE_TEST_COMMIT_ID`	UUID del commit. Usado por las pruebas de get_commit_details cuando no se puede descubrir ningún commit desde la API.

Seguridad

Este proyecto depende de paquetes de código abierto de terceros listados en pyproject.toml. Si bien fijamos los rangos de versión de las dependencias y entregamos un archivo de bloqueo (uv.lock) con hashes criptográficos, estos paquetes son mantenidos de forma independiente y se proporcionan "tal cual". Appcircle no ofrece garantías con respecto a la seguridad o confiabilidad de las dependencias de terceros.

Recomendamos auditar los paquetes instalados antes de su uso:

uv run pip-audit