Appcircle MCP Server

oficial

Servidor MCP oficial da Appcircle

O que você pode fazer com Appcircle MCP?

  • Monitorar status e logs de build — Use get_build_status e get_build_logs para verificar execuções de pipeline e depurar falhas.
  • Disparar ou cancelar builds — Use trigger_build e cancel_build para iniciar ou interromper execuções reais de build.
  • Gerar insights de saúde de CI/CD — Use get_build_insights_report para obter um resumo agregado de saúde, tendências e análise de causa raiz.
  • Gerenciar distribuição de testes — Use get_distribution_profiles e send_app_version_to_testers para enviar builds para testadores.
  • Inspecionar identidades de assinatura — Use get_certificates, get_keystores e get_provisioning_profiles para revisar a configuração de assinatura.
  • Acompanhar publicação na loja — Use get_publish_profiles e get_publish_details para monitorar execuções do fluxo de publicação.

Documentação

Servidor MCP Appcircle

Servidor MCP para Appcircle: expõe ferramentas de Build, Signing Identities, Testing Distribution, Enterprise App Store, Publish to Stores e Reporting para qualquer cliente compatível com MCP (Claude Desktop, Cursor, VS Code, etc.). O Appcircle MCP Server atua como ponte entre ferramentas de IA e o Appcircle; assim, agentes de IA, assistentes e chatbots podem acessar e interagir com segurança com os recursos do Appcircle por meio de ferramentas estruturadas, governadas e de nível de tarefa.

Casos de Uso

  • Inteligência de CI/CD e Fluxo de Trabalho: Monitore execuções de pipeline, acompanhe o status de lançamentos e obtenha insights sobre seus fluxos de trabalho de CI/CD para dispositivos móveis.
  • Insights de Configuração e Ambiente: Consulte configurações de build e ajustes de assinatura para entender como um projeto está configurado e onde podem surgir problemas.
  • Relatórios e Insights Operacionais: Gere resumos de estabilidade de CI, problemas recorrentes, desempenho de pipeline e saúde geral do CI/CD.

Modos de Execução

Você pode usar o servidor MCP de quatro maneiras:

ModoResumo
1. Host remotoConecte-se ao https://mcp.appcircle.io. Sem instalação local; seu cliente envia seu token Appcircle (por exemplo, Authorization: Bearer <token>) em cada solicitação.
2. Local (stdio)Execute o servidor a partir do código-fonte: clone o repositório, opcionalmente use um venv, depois execute appcircle-mcp (o transporte padrão é stdio). Requer Python e pip. Defina APPCIRCLE_ACCESS_TOKEN no ambiente. Seu cliente MCP executa o servidor como subprocesso.
3. Local (streamable-http)Execute o servidor localmente via HTTP: use --transport streamable-http e opcionalmente --host / --port (por exemplo, appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000). Os clientes se conectam a essa URL e enviam seu token na solicitação.
4. Local (Docker)Execute a imagem Docker oficial na sua máquina. Requer Docker. Use a porta padrão da imagem ou substitua com --port; consulte a documentação da imagem para uso exato.

A configuração detalhada do cliente (Cursor, Claude, etc.) está nos guias de instalação dedicados; esta seção é apenas um resumo de alto nível.

Instalação

Guias de configuração específicos por cliente:

Configuração (Variáveis de Ambiente)

VariávelObrigatóriaDescrição
APPCIRCLE_ACCESS_TOKENSim (somente stdio)Token de acesso à API do Appcircle. Obrigatório ao usar transporte stdio. Para streamable-http, cada cliente envia seu próprio token. Consulte Obtendo um token para saber como obter um.
APPCIRCLE_API_URLNãoURL base da API (padrão: https://api.appcircle.io pode diferir para usuários self-hosted).
APPCIRCLE_MCP_ALLOWED_HOSTNão (somente streamable-http)Nome de host público para o servidor MCP (por exemplo, mcp.appcircle.io). Defina isso ao implantar atrás de um proxy reverso para que o servidor aceite o cabeçalho Host dos clientes. Omita para localhost.
APPCIRCLE_MCP_PORTNão (somente streamable-http)Porta de vinculação para o servidor HTTP (padrão: 8000). Substituída por --port se fornecida. Útil para on-prem ou Docker quando uma porta específica é necessária.
LOG_LEVELNãoNível de registro (logging), por exemplo, DEBUG, INFO (padrão: INFO).
APPCIRCLE_EXCLUDED_TOOLSETSNãoToolsets separados por vírgula para excluir (por exemplo, build_module,report). Consulte Toolsets abaixo.
AC_MCP_ENABLE_WRITE_TOOLSNãoFerramentas de escrita/ação (por exemplo, trigger_build, cancel_build) são registradas por padrão. Defina para false/0/no/off para optar por não registrá-las (não apenas desabilitá-las no momento da chamada).

Defina essas variáveis no seu shell ou na configuração do cliente MCP.

Toolsets

Toolsets Disponíveis

ToolsetDescrição
build_modulePerfis de build, configurações, fluxos de trabalho, commits e operações de pipeline
signing_identitiesIdentidades de assinatura e identificadores de bundle
testing_distributionPerfis de distribuição de testes e detalhes de distribuição
publish_to_storesPerfis de publicação e operações de publicação em lojas
enterprise_app_storePerfis de app store corporativa e detalhes de loja
reportRelatórios: histórico de builds, distribuição, assinatura, status de publicação e relatórios relacionados

Você pode excluir um ou mais toolsets para que suas ferramentas não sejam registradas. As exclusões podem ser definidas via argumentos de CLI ou pela variável de ambiente APPCIRCLE_EXCLUDED_TOOLSETS; ambas são mescladas (união).

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

Exemplo de configuração MCP (Cursor / Claude Desktop) com exclusões:

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

Ferramentas

As ferramentas são expostas via MCP tools/list. A referência abaixo lista todas as ferramentas por toolset; para forma de resposta e exemplos, consulte docs/tool_contract.md.

Build
  • get_build_profiles - Obtém perfis de build para a organização atual (paginado). Opcionalmente, filtre por nome do perfil, plataforma, status do último build e fonte do repositório. Opcionalmente, ordene.

    • Nível de acesso: leitura
    • page: Número da página (baseado em 1). Padrão: 1. (número, opcional)
    • size: Tamanho da página (1-100). Padrão: 25. Valores acima de 100 são limitados a 100. (número, opcional)
    • search: Termo de busca opcional para filtrar perfis (correspondência parcial sem diferenciar maiúsculas/minúsculas no nome do perfil; a busca da API também pode corresponder a outros campos do perfil). (string, 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 status do último build para filtrar. Valores permitidos: 0=Success, 1=Failed, 2=Canceled, 3=Timeout, 90=Waiting, 91=Running. (lista de números, opcional)
    • repository_source: Lista opcional de códigos de fonte de repositório para filtrar. Valores permitidos: 1=GitHub, 2=Bitbucket, 3=GitLab, 4=Azure DevOps, 6=Public Repository, 7=Private Repository, 8=SSH. (lista de números, opcional)
    • sort: Código de campo de ordenação opcional. Valores permitidos: 1=Profile Name, 2=Create Date, 3=Last Build Date. (número, opcional)
    • sort_direction: Código de direção de ordenação opcional. Valores permitidos: 1=ASC, 2=DESC. (número, opcional)
  • get_build_profile_details - Obtém um único perfil de build por ID, opcionalmente incluindo suas configurações de build.

    • Nível de acesso: leitura
    • profile_id: O ID do perfil de build (ex.: UUID). (string, obrigatório)
    • configurations: Se true, também busca as configurações de build do perfil. Padrão: false. (boolean, opcional)
  • get_build_configuration_details - Obtém uma única configuração de build pelo ID do perfil e ID da configuração.

    • Nível de acesso: leitura
    • profile_id: O ID do perfil de build (ex.: UUID). (string, obrigatório)
    • configuration_id: O ID da configuração de build (ex.: UUID). (string, obrigatório)
  • get_build_profile_workflows - Obtém fluxos de trabalho para um perfil de build pelo ID do perfil.

    • Nível de acesso: leitura
    • profile_id: O ID do perfil de build (ex.: UUID). (string, obrigatório)
  • get_workflow_detail - Obtém um único fluxo de trabalho pelo ID do perfil de build e ID do fluxo de trabalho.

    • Nível de acesso: leitura
    • profile_id: O ID do perfil de build (ex.: UUID). (string, obrigatório)
    • workflow_id: O ID do workflow (ex.: UUID). (string, obrigatório)
  • get_commits_by_branch - Obtém commits para um branch de build (paginado).

    • Nível de acesso: leitura
    • branch_id: O ID do branch (ex.: UUID). (string, obrigatório)
    • page: Número da página (baseado em 1). Se fornecido com size, permite paginação. Padrão: 1. (número, opcional)
    • size: Tamanho da página. Se fornecido com page, permite paginação. Padrão: 25, máximo 100. (número, opcional)
  • get_commit_details - Obtém um único commit pelo ID do commit (UUID) ou pelo hash do commit (git SHA). Forneça commit_id ou commit_hash, não ambos.

    • Nível de acesso: leitura
    • commit_id: O ID do commit (UUID). (string, opcional)
    • commit_hash: O hash do commit (git SHA). (string, opcional)
  • get_last_commit - Obtém o commit mais recente em um branch de build.

    • Nível de acesso: leitura
    • branch_id: O ID do branch (ex.: UUID). (string, obrigatório)
  • get_build_status - Obtém o status de um build (ex.: 0=Success, 1=Failed, 2=Canceled, 3=Timeout, 90=Waiting, 91=Running, 92=Completing, 99=Unknown).

    • Nível de acesso: leitura
    • commit_id: O ID do commit (UUID). (string, obrigatório)
    • build_id: O ID do build (UUID). (string, obrigatório)
  • get_build_logs - Obtém os logs de um build, opcionalmente limitados a um único passo. Padrão: exibição truncada no final para evitar sobrecarregar o contexto do modelo.

    • Nível de acesso: leitura
    • commit_id: O ID do commit (UUID). (string, obrigatório)
    • build_id: O ID do build (UUID). (string, obrigatório)
    • step: Nome exato do passo (sem diferenciar maiúsculas/minúsculas) para limitar a saída ao bloco de log de um passo. (string, opcional)
    • full_log: Se true, retorna o log inteiro em vez do padrão final. Ainda limitado a 256 KB. Padrão: false. (boolean, opcional)
    • tail_lines: Número de linhas a manter do final quando não se usa full_log. Padrão: 200, máximo 1000. (número, opcional)
    • grep: Filtro de substring sem diferenciar maiúsculas/minúsculas aplicado às linhas antes do truncamento. (string, opcional)
  • get_variable_groups - Obtém todos os grupos de variáveis de ambiente de build para a organização, incluindo as variáveis de cada grupo (key, value, isSecret, isFile). Valores secretos já são mascarados pela API.

    • Nível de acesso: leitura
    • Não recebe parâmetros.
  • trigger_build - EFEITO COLATERAL: inicia uma nova execução real de build (enfileira um build real, consumindo minutos/créditos de build) em um branch (último commit sincronizado) ou para um commit específico. Registrado por padrão; defina AC_MCP_ENABLE_WRITE_TOOLS=false para não participar.

    • Nível de acesso: gravação
    • profile_id: O ID do perfil de build (ex.: UUID). Obrigatório no modo branch (quando commit_id não é fornecido); não usado no modo commit. (string, opcional)
    • workflow_id: O ID do workflow (ex.: UUID). Obrigatório no modo branch. Opcional no modo commit (usa o workflow padrão/último usado se omitido). (string, opcional)
    • branch_name: Nome do branch opcional (ex.: "main"). Apenas no modo branch; usa o branch padrão do perfil se omitido. Não deve ser fornecido junto com commit_id. (string, opcional)
    • commit_id: O ID do próprio commit (não o hash git) para disparar um build para um commit específico em vez do mais recente em um branch. Não deve ser fornecido junto com branch_name. (string, opcional)
    • configuration_id: ID da configuração de build opcional (ex.: UUID) para usar em vez do padrão. (string, opcional)
  • cancel_build - EFEITO COLATERAL: cancela um build em fila ou em execução (trabalho real em andamento é interrompido; não pode ser retomado). Registrado por padrão; defina AC_MCP_ENABLE_WRITE_TOOLS=false para não participar.

    • Nível de acesso: gravação
    • task_id: O ID da tarefa do build (o campo "taskId" retornado por trigger_build). (string, obrigatório)
Signing Identities
  • get_bundle_identifiers - Obtém todos os identificadores de bundle para a organização (IDs de bundle de apps iOS/macOS).

    • Nível de acesso: leitura
    • Sem parâmetros.
  • get_certificates - Obtenha todos os certificados de assinatura para a organização. Campos confidenciais (p12Password, p12Binary, metaData, thumbprint) são omitidos.

    • Nível de acesso: read
    • Sem parâmetros.
  • get_keystores - Obtenha todos os keystores para a organização (ex.: keystores de assinatura Android). Campos confidenciais (password, aliasPassword, binary, checkSum, sha256FingerPrint) são omitidos.

    • Nível de acesso: read
    • Sem parâmetros.
  • get_provisioning_profiles - Obtenha perfis de provisionamento para a organização (ex.: iOS/macOS). Campos confidenciais/grandes (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) são omitidos. Opcionalmente, filtre por ID do aplicativo (bundle).

    • Nível de acesso: read
    • app_id: ID opcional do aplicativo (bundle) para filtrar perfis de provisionamento (ex.: com.example.app). (string, opcional)
Distribuição de Testes
  • get_distribution_profiles - Obtenha perfis de distribuição de testes para a organização atual (paginado). Opcionalmente, filtre por nome do perfil, plataforma e tipo de autenticação. Opcionalmente, ordene.

    • Nível de acesso: read
    • page: Número da página (baseado em 1). Padrão: 1. (número, opcional)
    • size: Tamanho da página (1-100). Padrão: 25, máximo 100. (número, opcional)
    • search: Termo de pesquisa opcional para filtrar perfis (correspondência parcial sem diferenciar maiúsculas/minúsculas no nome do perfil; a pesquisa da API também pode corresponder a outros campos do perfil). (string, opcional)
    • platform: Lista opcional de códigos de plataforma para filtrar. Valores permitidos: 1=iOS, 2=Android. (lista de números, opcional)
    • authentication_type: Lista opcional de códigos de tipo de autenticação para filtrar. Valores permitidos: 1=Nenhum, 3=Login estático, 4=LDAP, 5=SSO. (lista de números, opcional)
    • sort: Código opcional do campo de ordenação. Valores permitidos: 1=Nome do perfil, 2=Data de criação, 3=Data do último upload. (número, opcional)
    • sort_direction: Código opcional da direção de ordenação. Valores permitidos: 1=ASC, 2=DESC. (número, opcional)
  • get_distribution_profile_details - Obtenha um único perfil de distribuição de testes por ID (com paginação opcional de versões de aplicativos).

    • Nível de acesso: read
    • profile_id: O ID do perfil de distribuição (ex.: UUID). (string, obrigatório)
    • page: Número da página para versões de aplicativos (baseado em 1). Padrão: 1. (número, opcional)
    • size: Tamanho da página para versões de aplicativos (1-100). Padrão: 25, máximo 100. (número, opcional)
  • get_testing_groups - Obtenha todos os grupos de distribuição de testes para a organização, incluindo os e-mails dos testadores membros de cada grupo e o tipo de grupo.

    • Nível de acesso: read
    • Não recebe parâmetros.
  • update_app_version_release_notes - EFEITO COLATERAL: sobrescreve as notas de versão ("message") exibidas aos testadores para uma versão de aplicativo de distribuição. Retorna o objeto da versão do aplicativo atualizado (exclui certThumbPrints). Registrado por padrão; defina AC_MCP_ENABLE_WRITE_TOOLS=false para optar por não participar.

    • Nível de acesso: write
    • profile_id: O ID do perfil de distribuição (ex.: UUID). (string, obrigatório)
    • app_version_id: O ID da versão do aplicativo (ex.: UUID). (string, obrigatório)
    • message: O texto das novas notas de versão. (string, obrigatório)
  • send_app_version_to_testers - EFEITO COLATERAL: envia uma notificação real aos testadores/um grupo de testes, despachando uma tarefa de distribuição para uma versão específica do aplicativo. Registrado por padrão; defina AC_MCP_ENABLE_WRITE_TOOLS=false para optar por não participar.

    • Nível de acesso: write
    • profile_id: O ID do perfil de distribuição (ex.: UUID). (string, obrigatório)
    • app_version_id: O ID da versão do aplicativo (ex.: UUID). (string, obrigatório)
    • message: A mensagem de notificação exibida aos testadores. (string, obrigatório)
    • testers: Lista de testadores para envio. Cada entrada é o e-mail de um testador ou um ID de grupo de testes (o campo "id" de get_testing_groups). (lista de strings, obrigatório)
Publicar nas Lojas
  • get_publish_profiles - Obtenha perfis de publicação para a organização atual para um determinado tipo de plataforma (paginado). Opcionalmente, filtre por status do fluxo, marketplace de destino, presença de binário candidato a lançamento e status da loja. Opcionalmente, ordene.

    • Nível de acesso: read
    • platform_type: Tipo de plataforma dos perfis de publicação ("ios" ou "android"). (string, obrigatório)
    • page: Número da página (baseado em 1). Padrão: 1. (número, opcional)
    • size: Tamanho da página (1-100). Padrão: 25, máximo 100. (número, opcional)
    • flow_status: Código opcional de status do fluxo para filtrar (ex.: 0=Sucesso, 1=Falha, 91=Em execução). (número, opcional)
    • market_place_type: Lista opcional de códigos de marketplace de destino para filtrar. Valores permitidos dependem do platform_type -- ios: 0=Não disponível, 1=App Store Connect, 4=Intune; android: 0=Não disponível, 2=Google Play, 3=AppGallery, 4=Intune. (lista de números, opcional)
    • has_rc_binary: Filtro opcional para saber se o perfil possui um binário candidato a lançamento. (boolean, opcional)
    • store_status: Lista opcional de códigos de status de loja para filtrar. Valores permitidos dependem do platform_type (muito mais códigos para ios do que android, ex.: ios: "IN_REVIEW", "READY_FOR_SALE", "REJECTED"; android: "NOT_AVAILABLE", "DRAFT", "IN_PROGRESS", "HALTED", "COMPLETED"). (lista de strings, opcional)
    • sort: Código opcional do campo de ordenação. Valores permitidos: 1=Nome do perfil, 2=Data de criação. (número, opcional)
    • sort_direction: Código opcional da direção de ordenação. Valores permitidos: 1=ASC, 2=DESC. (número, opcional)
  • get_publish_profile_details - Obtenha um único perfil de publicação por tipo de plataforma e ID (com paginação opcional de versões de aplicativos).

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • page: Número da página para versões de aplicativos (baseado em 1). Padrão: 1. (número, opcional)
    • size: Tamanho da página para versões de aplicativos (1-100). Padrão: 25, máximo 100. (número, opcional)
  • get_app_version_metadata - Obtenha metadados de listagem na loja para uma única versão do aplicativo (informações de revisão do aplicativo, localizações, informações de lançamento, informações da versão do aplicativo). appReviewInformation.demoPassword é excluído.

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • app_version_id: O ID da versão do aplicativo (ex.: UUID). (string, obrigatório)
  • get_metadata_locales - Obtenha os locales de metadados de loja disponíveis para uma única versão do aplicativo (nome, código, localizado, isPrimary).

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • app_version_id: O ID da versão do aplicativo (ex.: UUID). (string, obrigatório)
  • get_intune_metadata - Obtenha metadados do aplicativo Microsoft Intune para uma única versão do aplicativo (nome de exibição, editor, ID do bundle, versão, estado de publicação, tipos de dispositivo aplicáveis, categorias, etc.).

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • app_version_id: O ID da versão do aplicativo (ex.: UUID). (string, obrigatório)
  • get_publish_metadata_lock_status - Verifique se os metadados de loja de um perfil de publicação estão bloqueados para edição.

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
  • get_publish_details - Obtenha os detalhes da execução do fluxo de publicação para uma única versão do aplicativo (status, tempo, etapas ordenadas com histórico/artefatos/IDs de recursos de log).

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • app_version_id: O ID da versão do aplicativo (ex.: UUID). (string, obrigatório)
  • get_publish_step_logs - Obtenha os logs de uma execução do fluxo de publicação, opcionalmente limitados a uma única etapa. Padrão: visualização truncada no final para evitar sobrecarregar o contexto do modelo.

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • publish_id: O ID da execução do fluxo de publicação (o campo "id" de get_publish_details). (string, obrigatório)
    • step_id: O ID da etapa (o campo "id" de uma etapa na lista de etapas de get_publish_details). (string, obrigatório)
    • step: Nome exato opcional da etapa (sem diferenciar maiúsculas/minúsculas) para limitar a saída ao bloco de log de uma etapa. (string, opcional)
    • full_log: Se verdadeiro, retorna o log inteiro em vez do final padrão. Ainda limitado a 256 KB. Padrão: false. (boolean, opcional)
    • tail_lines: Número de linhas a manter do final quando não usar full_log. Padrão: 200, máximo 1000. (número, opcional)
    • grep: Filtro de substring sem diferenciar maiúsculas/minúsculas aplicado às linhas antes da truncagem. (string, opcional)
  • get_publish_flows - Obtenha os fluxos de publicação configurados para um perfil de publicação (nome, ID, documento YAML completo do fluxo).

    • Nível de acesso: read
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
  • start_publish - EFEITO COLATERAL: inicia uma execução do fluxo de publicação (ou a reinicia a partir de uma etapa específica) -- trabalho real de publicação (ex.: envio para App Store/Play Store/Intune). Registrado por padrão; defina AC_MCP_ENABLE_WRITE_TOOLS=false para optar por não participar.

    • Nível de acesso: write
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • publish_id: O ID da execução do fluxo de publicação (o campo "id" de get_publish_details). (string, obrigatório)
    • step_id: ID opcional da etapa para iniciar a partir dessa etapa em vez do início do fluxo. (string, opcional)
    • organization_pool_id: ID opcional do pool da organização (ex.: UUID) para execução. (string, opcional)
  • stop_publish - EFEITO COLATERAL: cancela uma execução do fluxo de publicação em andamento (trabalho real em andamento é interrompido; não pode ser retomado). Registrado por padrão; defina AC_MCP_ENABLE_WRITE_TOOLS=false para optar por não participar.

    • Nível de acesso: write
    • platform_type: Tipo de plataforma ("ios" ou "android"). (string, obrigatório)
    • profile_id: O ID do perfil de publicação (ex.: UUID). (string, obrigatório)
    • publish_id: O ID da execução do fluxo de publicação (o campo "id" de get_publish_details). (string, obrigatório)
    • step_id: ID opcional da etapa. (string, opcional)
    • organization_pool_id: ID opcional do pool da organização (ex.: UUID). (string, opcional)
Loja de Aplicativos Empresarial
  • get_store_profiles - Obtenha perfis de loja de aplicativos empresariais para a organização atual (paginado). Não suporta pesquisa, mas pode filtrar por plataforma, tipo de publicação e visibilidade. Opcionalmente, ordene.
    • Nível de acesso: read
    • page: Número da página (baseado em 1). Padrão: 1. (número, opcional)
    • size: Tamanho da página (1-100). Padrão: 25, máximo 100. (número, opcional)
    • platform_type: Lista opcional de códigos de plataforma para filtrar. Valores permitidos: 1=iOS, 2=Android. (lista de números, opcional)
    • publish_type: Lista opcional de códigos de tipo de publicação para filtrar. Valores permitidos: 1=Publicado para Beta, 2=Publicado para Produção. (lista de números, opcional)
    • visibility: Filtro opcional para saber se o perfil é listado publicamente (true=Listado, false=Não listado). (boolean, opcional)
    • sort: Código opcional do campo de ordenação. Valores permitidos: 1=Nome do aplicativo, 2=Data de criação, 3=Contagem de downloads, 4=Data de recebimento do binário. (número, opcional)
    • sort_direction: Código opcional da direção de ordenação. Valores permitidos: 1=ASC, 2=DESC. (número, opcional)
  • get_store_profile_details - Obtém um único perfil de loja de aplicativos empresarial por ID (com paginação opcional de versões de aplicativos).
    • Nível de acesso: read
    • profile_id: O ID do perfil da loja de aplicativos empresarial (por exemplo, UUID). (string, obrigatório)
    • page: Número da página para versões de aplicativos (baseado em 1). Padrão: 1. (number, opcional)
    • size: Tamanho da página para versões de aplicativos (1-100). Padrão: 25, máx 100. (number, opcional)
    • O campo publishType de cada versão de aplicativo é um int: 0= Nenhum, 1=Beta, 2=Live.
Relatório
  • get_build_history_report - Obtém o relatório de histórico de build, opcionalmente filtrado por intervalo de datas, perfil de build e organização. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • build_profile_name: Filtro por nome do perfil de build. (string, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
  • get_build_queue_waiting_report - Obtém o relatório de tempo de espera na fila de build, opcionalmente filtrado por intervalo de datas. Paginado. Nota: neste endpoint, buildDuration significa tempo de espera na fila em minutos, não tempo de execução (ao contrário de get_build_history_report).

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). Deve ser <= data_final se ambos forem fornecidos. (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
  • get_build_activity_log - Obtém o log de atividade de build (alterações de fluxo de trabalho/perfil, lançamentos CodePush, etc.), opcionalmente filtrado por intervalo de datas e outros parâmetros. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). Deve ser <= data_final se ambos forem fornecidos. (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
    • platform: Filtro por tipo de plataforma (código inteiro, ex.: 0=Android, 1=iOS). (number, opcional)
    • email: Filtro pelo e-mail do usuário que realizou a ação. (string, opcional)
    • profile_name: Filtro por nome do perfil de build. (string, opcional)
    • action: Filtro por código de ação de atividade (inteiro; veja BUILD_ACTIVITY_ACTIONS no código-fonte da ferramenta para o mapeamento completo). (number, opcional)
  • get_build_insights_report - Obtém um Relatório de Insights de Build (Snapshot de Saúde + Tendências, Causa Raiz, Saúde de Artefatos, Qualidade de Fluxo de Trabalho, Tempo de Fila e análise de Avaliação de Maturidade) sobre o histórico de build, agregado no servidor. Ao contrário de get_build_history_report, este busca todas as páginas internamente e retorna resultados pequenos pré-agregados em vez de registros brutos.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD) para o período atual. Padrão: últimos 30 dias. (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD) para o período atual. (string, opcional)
    • sections: Lista opcional de seções para calcular: health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. Padrão: todas as seis. (array de strings, opcional)
    • include_sub_orgs: Se verdadeiro, mantém registros de build entre organizações nas métricas derivadas do histórico, em vez de filtrar para a organização do token. Padrão: falso. (boolean, opcional)
  • get_distribution_app_version_report - Obtém relatório de uso diário para versões de aplicativos distribuídos. Paginado; suporta filtros por perfil, sistema operacional, organização.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • profile_name: Filtro por nome do perfil de distribuição. (string, opcional)
    • os: Filtro por sistema operacional ("ios" ou "android"). (string, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
  • get_distribution_sent_report - Obtém relatório de uso diário para compartilhamento de aplicativos distribuídos. Paginado; suporta filtros por perfil, sistema operacional, organização.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • profile_name: Filtro por nome do perfil de distribuição. (string, opcional)
    • os: Filtro por sistema operacional ("ios" ou "android"). (string, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
  • get_enterprise_app_store_app_usage_report - Obtém relatório de uso de aplicativos para a loja de aplicativos empresarial. start_date e end_date são obrigatórios. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial (AAAA-MM-DD). (string, obrigatório)
    • end_date: Data final (AAAA-MM-DD). (string, obrigatório)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • organization_id: Filtro opcional por UUID da organização. (string, opcional)
  • get_publish_resign_report - Obtém relatório de republicação (resign), opcionalmente filtrado por intervalo de datas, nome do aplicativo, organização e status. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • app_name: Filtro por nome do aplicativo. (string, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
    • status: Filtro por status de republicação (0=aguardando, 1=processando, 2=sucesso, 3=falha, 4=cancelado, 5=timeout). (number, opcional)
  • get_publish_status_report - Obtém relatório de status de publicação, opcionalmente filtrado por intervalo de datas, nome do aplicativo, organização e status. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • app_name: Filtro por nome do aplicativo. (string, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
    • status: Filtro por status de publicação (ex.: 0=Sucesso, 1=Falha, 91=Em execução). (number, opcional)
  • get_signing_report - Obtém relatório de assinatura, opcionalmente filtrado por intervalo de datas, organização, sistema operacional e status de build. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
    • os: Filtro por sistema operacional ("ios" ou "android"). (string, opcional)
    • build_status: Filtro por status de build (ex.: 0=Sucesso, 1=Falha, 91=Em execução). (number, opcional)
  • get_signing_activity_log - Obtém o log de atividade de assinatura (ex.: avisos de expiração de certificado/perfil de provisionamento/keystore), opcionalmente filtrado por intervalo de datas e outros parâmetros. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). Deve ser <= data_final se ambos forem fornecidos. (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
    • platform: Filtro por plataforma (ex.: "iOS", "Android"). (string, opcional)
    • email: Filtro pelo e-mail do usuário que realizou a ação. (string, opcional)
    • action: Filtro por código de ação de atividade (inteiro; veja SIGNING_ACTIVITY_ACTIONS no código-fonte da ferramenta para o mapeamento completo). (number, opcional)
  • get_publish_activity_log - Obtém o log de atividade de publicação (re-assinatura, eventos do fluxo de publicação, etc.), opcionalmente filtrado por intervalo de datas e outros parâmetros. Paginado.

    • Nível de acesso: read
    • start_date: Data inicial opcional (AAAA-MM-DD). Deve ser <= data_final se ambos forem fornecidos. (string, opcional)
    • end_date: Data final opcional (AAAA-MM-DD). (string, opcional)
    • page: Número da página (padrão: 1). (number, opcional)
    • size: Itens por página (1-100, padrão: 50). (number, opcional)
    • organization_id: Filtro por UUID da organização. (string, opcional)
    • platform: Filtro por plataforma (ex.: "iOS", "Android"). (string, opcional)
    • email: Filtro pelo e-mail do usuário que realizou a ação. (string, opcional)
    • profile_name: Filtro por nome do perfil de publicação. (string, opcional)
    • action: Filtro por código de ação de atividade (inteiro; veja PUBLISH_ACTIVITY_ACTIONS no código-fonte da ferramenta para o mapeamento completo). (number, opcional)

Executando o servidor

A partir da raiz do repositório:

python -m src.server

Ou após pip install -e .:

appcircle-mcp

O servidor roda via stdio (ou SSE/HTTP dependendo de como seu cliente o inicia).

Formato de resposta

Toda ferramenta retorna um envelope padrão:

  • Sucesso: { "success": true, "data": <payload>, "meta": { ... } }
    data é o resultado da ferramenta; meta é opcional (ex.: count, page, filters).
  • Erro: { "success": false, "error": { "tool", "type", "message", "details" } }
    Mesma forma para todas as ferramentas para que os clientes possam analisar erros de forma consistente.

Especificação completa: docs/tool_contract.md.

Testes

Instale com dependências de desenvolvimento:

pip install -e ".[dev]"

Testes unitários (padrão)

Usam uma API simulada; nenhum APPCIRCLE_ACCESS_TOKEN necessário. O pytest padrão executa apenas estes (veja testpaths em pyproject.toml):

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

Testes de integração

Chamam a API real do Appcircle. Defina APPCIRCLE_ACCESS_TOKEN no ambiente e execute:

pytest test/integration/ -v
  • Todos os testes de integração: pytest test/integration/ -v
  • Por ferramenta: pytest test/integration/build_module/ -v, pytest test/integration/report/ -v, etc.
  • Por marcador: pytest -m integration -v (ao executar da raiz do repositório; inclui apenas testes de integração se ambos unitários e integração forem coletados)

Se APPCIRCLE_ACCESS_TOKEN não estiver definido, os testes de integração são ignorados (sem falha).

Variáveis de ambiente opcionais para testes de integração (quando a descoberta falha ou os testes precisam de IDs reais; omita para pular esses testes):

VariávelDescrição
APPCIRCLE_TEST_ORGANIZATION_IDUUID da organização. Usado por test_with_organization_id (relatório de uso de aplicativos da loja empresarial).
APPCIRCLE_TEST_BRANCH_IDUUID do branch. Usado por get_commits_by_branch e testes relacionados quando nenhum branch pode ser descoberto pela API.
APPCIRCLE_TEST_COMMIT_IDUUID do commit. Usado por testes de get_commit_details quando nenhum commit pode ser descoberto pela API.
Testes de integração de escrita/ação (trigger_build, cancel_build, etc.) são marcados como integration_write e são opt-in além de APPCIRCLE_ACCESS_TOKEN — eles mutam dados reais (disparam builds reais, etc.), então nunca são executados apenas a partir de pytest test/integration/ -v. Defina APPCIRCLE_RUN_WRITE_INTEGRATION_TESTS=true (apontando APPCIRCLE_ACCESS_TOKEN para uma org de teste dedicada, não produção) para habilitá-los.

Segurança

Este projeto depende de pacotes open-source de terceiros listados em pyproject.toml. Embora fixemos intervalos de versão das dependências e distribuamos um lockfile (uv.lock) com hashes criptográficos, esses pacotes são mantidos de forma independente e fornecidos "como estão". A Appcircle não oferece garantias em relação à segurança ou confiabilidade das dependências de terceiros.

Recomendamos auditar os pacotes instalados antes do uso:

uv run pip-audit