Appcircle MCP Server
oficialServidor MCP oficial da Appcircle
O que você pode fazer com Appcircle MCP?
- Monitorar status e logs de build — Use
get_build_statuseget_build_logspara verificar execuções de pipeline e depurar falhas. - Disparar ou cancelar builds — Use
trigger_buildecancel_buildpara iniciar ou interromper execuções reais de build. - Gerar insights de saúde de CI/CD — Use
get_build_insights_reportpara obter um resumo agregado de saúde, tendências e análise de causa raiz. - Gerenciar distribuição de testes — Use
get_distribution_profilesesend_app_version_to_testerspara enviar builds para testadores. - Inspecionar identidades de assinatura — Use
get_certificates,get_keystoreseget_provisioning_profilespara revisar a configuração de assinatura. - Acompanhar publicação na loja — Use
get_publish_profileseget_publish_detailspara 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:
| Modo | Resumo |
|---|---|
| 1. Host remoto | Conecte-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:
- Claude Applications - Guia de instalação para Claude Desktop e Claude Code CLI.
- Cursor IDE - Guia de instalação para Cursor IDE.
- Codex - Guia de instalação para Codex app e Codex CLI.
- Antigravity IDE - Guia de instalação para Antigravity IDE.
- VS Code (GitHub Copilot) - Guia de instalação para VS Code com GitHub Copilot.
- Windsurf IDE - Guia de instalação para Windsurf IDE.
- Gemini CLI - Guia de instalação para Gemini CLI.
- GitHub Copilot CLI - Guia de instalação para GitHub Copilot CLI.
Configuração (Variáveis de Ambiente)
| Variável | Obrigatória | Descrição |
|---|---|---|
APPCIRCLE_ACCESS_TOKEN | Sim (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_URL | Não | URL base da API (padrão: https://api.appcircle.io pode diferir para usuários self-hosted). |
APPCIRCLE_MCP_ALLOWED_HOST | Nã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_PORT | Nã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_LEVEL | Não | Nível de registro (logging), por exemplo, DEBUG, INFO (padrão: INFO). |
APPCIRCLE_EXCLUDED_TOOLSETS | Não | Toolsets separados por vírgula para excluir (por exemplo, build_module,report). Consulte Toolsets abaixo. |
AC_MCP_ENABLE_WRITE_TOOLS | Não | Ferramentas 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
| Toolset | Descrição |
|---|---|
build_module | Perfis de build, configurações, fluxos de trabalho, commits e operações de pipeline |
signing_identities | Identidades de assinatura e identificadores de bundle |
testing_distribution | Perfis de distribuição de testes e detalhes de distribuição |
publish_to_stores | Perfis de publicação e operações de publicação em lojas |
enterprise_app_store | Perfis de app store corporativa e detalhes de loja |
report | Relató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 toolset2ou--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=falsepara 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=falsepara 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=falsepara 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=falsepara 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=falsepara 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=falsepara 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
publishTypede 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,
buildDurationsignifica 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; vejaBUILD_ACTIVITY_ACTIONSno 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; vejaSIGNING_ACTIVITY_ACTIONSno 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; vejaPUBLISH_ACTIVITY_ACTIONSno 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ável | Descrição |
|---|---|
APPCIRCLE_TEST_ORGANIZATION_ID | UUID da organização. Usado por test_with_organization_id (relatório de uso de aplicativos da loja empresarial). |
APPCIRCLE_TEST_BRANCH_ID | UUID do branch. Usado por get_commits_by_branch e testes relacionados quando nenhum branch pode ser descoberto pela API. |
APPCIRCLE_TEST_COMMIT_ID | UUID 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