Appcircle MCP Server

oficial

Servidor MCP oficial da Appcircle

GitHub

O que você pode fazer com Appcircle MCP?

Listar e pesquisar perfis de build — Recupere perfis de build paginados e filtre por nome com get_build_profiles.
Inspecionar configurações de build e fluxos de trabalho — Obtenha detalhes de um perfil de build específico, suas configurações e fluxos de trabalho usando get_build_profile_details, get_build_configuration_details e get_workflow_detail.
Revisar identidades de assinatura — Liste certificados, keystores, perfis de provisionamento e identificadores de pacote por meio de get_certificates, get_keystores, get_provisioning_profiles e get_bundle_identifiers.
Verificar status de distribuição de teste e enterprise — Obtenha perfis de distribuição e suas versões de aplicativo com get_distribution_profiles e get_distribution_profile_details, ou inspecione perfis de loja enterprise via get_store_profiles.
Gerar relatórios de saúde de CI/CD e histórico de builds — Use get_build_insights_report para tendências agregadas e análise de causa raiz, ou get_build_history_report para registros brutos de build.

Documentação

Appcircle MCP Server

Servidor MCP para o 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 a 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 em nível de tarefa.

Casos de Uso

Inteligência de CI/CD e Workflow: Monitore execuções de pipeline, acompanhe o status de lançamento e obtenha insights sobre seus fluxos de trabalho de CI/CD móvel.
Insights de Configuração e Ambiente: Consulte configurações de build e setup de assinatura para entender como um projeto está configurado e onde os problemas podem se originar.
Insights de Relatórios e Operacionais: Gere resumos de estabilidade de CI, problemas recorrentes, desempenho de pipeline e saúde geral de 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 do Appcircle (ex.: `Authorization: Bearer <token>`) em cada requisição.
2. Local (stdio)	Execute o servidor a partir do código-fonte: clone o repositório, opcionalmente use um venv, então execute `appcircle-mcp` (transporte padrão é stdio). Requer Python e pip. Defina `APPCIRCLE_ACCESS_TOKEN` no ambiente. Seu cliente MCP executa o servidor como um subprocesso.
3. Local (streamable-http)	Execute o servidor localmente sobre HTTP: use `--transport streamable-http` e opcionalmente `--host` / `--port` (ex.: `appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000`). Os clientes se conectam a essa URL e enviam seu token na requisição.
4. Local (Docker)	Execute a imagem Docker oficial em sua máquina. Requer Docker. Use a porta padrão da imagem ou sobrescreva 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 do cliente:

Aplicativos Claude - 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 aplicativo Codex 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. Veja 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 (ex.: `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 bind para o servidor HTTP (padrão: `8000`). Sobrescrita por `--port` se fornecida. Útil para on-prem ou Docker quando uma porta específica é necessária.
`LOG_LEVEL`	Não	Nível de logging, ex.: `DEBUG`, `INFO` (padrão: `INFO`).
`APPCIRCLE_EXCLUDED_TOOLSETS`	Não	Conjuntos de ferramentas a excluir, separados por vírgula (ex.: `build_module,report`). Veja Conjuntos de Ferramentas abaixo.

Defina-as no seu shell ou na configuração do seu cliente MCP.

Conjuntos de Ferramentas

Conjuntos de Ferramentas Disponíveis

Os seguintes conjuntos de ferramentas estão disponíveis:

Conjunto de Ferramentas	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 teste 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 loja de aplicativos empresariais e detalhes da loja
`report`	Relatórios: histórico de build, distribuição, assinatura, status de publicação e relatórios relacionados

Você pode excluir um ou mais conjuntos de ferramentas para que suas ferramentas não sejam registradas. As exclusões podem ser definidas via argumentos 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 conjunto; para formato de resposta e exemplos, veja docs/tool_contract.md.

Build

get_build_profiles - Obtém perfis de build para a organização atual (paginado). Opcionalmente filtra por nome do perfil.
- 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 por nome (correspondência parcial sem distinção entre maiúsculas/minúsculas). (string, 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 verdadeiro, também busca as configurações de build do perfil. Padrão: falso. (booleano, opcional)
get_build_configuration_details - Obtém uma única configuração de build por 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 por 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 por 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 fluxo de trabalho (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, habilita a paginação. Padrão: 1. (número, opcional)
- size: Tamanho da página. Se fornecido com page, habilita a paginação. Padrão: 25, máximo 100. (número, opcional)
get_commit_details - Obtém um único commit por ID do commit (UUID) ou por 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)

Signing Identities

get_bundle_identifiers - Obtém todos os identificadores de bundle para a organização (IDs de bundle de app iOS/macOS).
- Nível de acesso: leitura
- Sem parâmetros.
get_certificates - Obtém todos os certificados de assinatura para a organização. Campos sensíveis (p12Password, p12Binary, metaData, thumbprint) são omitidos.
- Nível de acesso: leitura
- Sem parâmetros.
get_keystores - Obtém todas as keystores para a organização (ex.: keystores de assinatura Android). Campos sensíveis (password, aliasPassword, binary, checkSum, sha256FingerPrint) são omitidos.
- Nível de acesso: leitura
- Sem parâmetros.
get_provisioning_profiles - Obtém perfis de provisionamento para a organização (ex.: iOS/macOS). Campos sensíveis/grandes (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) são omitidos. Opcionalmente filtra por ID do app (bundle).
- Nível de acesso: leitura
- app_id: ID do app (bundle) opcional para filtrar perfis de provisionamento (ex.: com.example.app). (string, opcional)

Testing Distribution

get_distribution_profiles - Obtém perfis de distribuição de teste para a organização atual (paginado). Opcionalmente filtra por nome do perfil.
- 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, máximo 100. (número, opcional)
- search: Termo de busca opcional para filtrar perfis por nome. (string, opcional)
get_distribution_profile_details - Obtém um único perfil de distribuição de teste por ID (com paginação opcional de versões do app).
- Nível de acesso: leitura
- profile_id: O ID do perfil de distribuição (ex.: UUID). (string, obrigatório)
- page: Número da página para versões do app (baseado em 1). Padrão: 1. (número, opcional)
- size: Tamanho da página para versões do app (1-100). Padrão: 25, máximo 100. (número, opcional)

Publish to Stores

get_publish_profiles - Obtém perfis de publicação para a organização atual para um determinado tipo de plataforma (paginado). Opcionalmente filtra por status do fluxo.
- Nível de acesso: leitura
- 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 de status do fluxo opcional para filtrar (ex.: 0=Sucesso, 1=Falha, 91=Executando). (número, opcional)
get_publish_profile_details - Obtém um único perfil de publicação por tipo de plataforma e ID (com paginação opcional de versões do app).
- Nível de acesso: leitura
- 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 do app (baseado em 1). Padrão: 1. (número, opcional)
- size: Tamanho da página para versões do app (1-100). Padrão: 25, máximo 100. (número, opcional)

Enterprise App Store

get_store_profiles - Obtém perfis de loja de aplicativos empresariais para a organização atual (paginado).
- 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, máximo 100. (número, opcional)
get_store_profile_details - Obtém um único perfil de loja de aplicativos empresariais por ID (com paginação opcional de versões do app).
- Nível de acesso: leitura
- profile_id: O ID do perfil de loja de aplicativos empresariais (ex.: UUID). (string, obrigatório)
- page: Número da página para versões do app (baseado em 1). Padrão: 1. (número, opcional)
- size: Tamanho da página para versões do app (1-100). Padrão: 25, máximo 100. (número, opcional)

Report

- **get_build_history_report** - Obtém relatório de histórico de builds, opcionalmente filtrado por intervalo de datas, perfil de build e organização. Paginado. - **Nível de acesso:** leitura - `start_date`: Data de início opcional (AAAA-MM-DD). (string, opcional) - `end_date`: Data de término 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`: Filtrar por nome do perfil de build. (string, opcional) - `organization_id`: Filtrar por UUID da organização. (string, opcional)

get_build_insights_report - Obtém um Relatório de Insights de Build computado (Análise de Snapshot de Saúde + Tendências, Causa Raiz, Saúde de Artefato, Qualidade do Fluxo de Trabalho, Tempo de Fila e Avaliação de Maturidade) sobre o histórico de builds, agregado no lado do servidor. Diferente de get_build_history_report, este busca cada página internamente e retorna pequenos resultados pré-agregados em vez de registros brutos.
- Nível de acesso: leitura
- start_date: Data de início opcional (AAAA-MM-DD) para o período atual. Padrão: últimos 30 dias. (string, opcional)
- end_date: Data de término opcional (AAAA-MM-DD) para o período atual. (string, opcional)
- sections: Lista opcional de seções a computar: 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 pela própria 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, SO, organização.
- Nível de acesso: leitura
- start_date: Data de início opcional (AAAA-MM-DD). (string, opcional)
- end_date: Data de término 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: Filtrar por nome do perfil de distribuição. (string, opcional)
- os: Filtrar por SO ("ios" ou "android"). (string, opcional)
- organization_id: Filtrar 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, SO, organização.
- Nível de acesso: leitura
- start_date: Data de início opcional (AAAA-MM-DD). (string, opcional)
- end_date: Data de término 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: Filtrar por nome do perfil de distribuição. (string, opcional)
- os: Filtrar por SO ("ios" ou "android"). (string, opcional)
- organization_id: Filtrar por UUID da organização. (string, opcional)
get_enterprise_app_store_app_usage_report - Obtém relatório de uso de aplicativo para a loja de aplicativos corporativa. start_date e end_date são obrigatórios. Paginado.
- Nível de acesso: leitura
- start_date: Data de início (AAAA-MM-DD). (string, obrigatório)
- end_date: Data de término (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 reassinatura de publicação, opcionalmente filtrado por intervalo de datas, nome do aplicativo, organização e status. Paginado.
- Nível de acesso: leitura
- start_date: Data de início opcional (AAAA-MM-DD). (string, opcional)
- end_date: Data de término 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: Filtrar por nome do aplicativo. (string, opcional)
- organization_id: Filtrar por UUID da organização. (string, opcional)
- status: Filtrar por status de reassinatura (0=aguardando, 1=processando, 2=bem-sucedido, 3=falhou, 4=cancelado, 5=tempo esgotado). (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: leitura
- start_date: Data de início opcional (AAAA-MM-DD). (string, opcional)
- end_date: Data de término 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: Filtrar por nome do aplicativo. (string, opcional)
- organization_id: Filtrar por UUID da organização. (string, opcional)
- status: Filtrar por status de publicação (ex.: 0=Sucesso, 1=Falhou, 91=Executando). (number, opcional)
get_signing_report - Obtém relatório de assinatura, opcionalmente filtrado por intervalo de datas, organização, SO e status de build. Paginado.
- Nível de acesso: leitura
- start_date: Data de início opcional (AAAA-MM-DD). (string, opcional)
- end_date: Data de término 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: Filtrar por UUID da organização. (string, opcional)
- os: Filtrar por SO ("ios" ou "android"). (string, opcional)
- build_status: Filtrar por status de build (ex.: 0=Sucesso, 1=Falhou, 91=Executando). (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 é executado sobre stdio (ou SSE/HTTP, dependendo de como seu cliente o inicia).

Formato de resposta

Cada 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" } }
Mesmo formato 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 padrão pytest 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 a partir da raiz do repositório; inclui apenas testes de integração se ambos, unitários e de 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 aplicativo da loja corporativa).
`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.

Segurança

Este projeto depende de pacotes de código aberto de terceiros listados em pyproject.toml. Embora fixemos intervalos de versão de dependências e forneçamos um arquivo de lock (uv.lock) com hashes criptográficos, esses pacotes são mantidos independentemente e fornecidos "como estão". A Appcircle não oferece garantias quanto à segurança ou confiabilidade de dependências de terceiros.

Recomendamos auditar os pacotes instalados antes do uso:

uv run pip-audit