Appcircle MCP Server

официальный

Официальный MCP-сервер Appcircle

GitHubПопробовать этот MCPСпонсировано

Что можно делать с Appcircle MCP?

  • Отслеживание статуса сборки и журналов — Используйте get_build_status и get_build_logs для проверки запусков конвейера и отладки сбоев.
  • Запуск или отмена сборок — Используйте trigger_build и cancel_build для запуска или остановки реальных сборок.
  • Формирование аналитики по CI/CD — Используйте get_build_insights_report для получения сводного снимка состояния, тенденций и анализа первопричин.
  • Управление распространением тестовых версий — Используйте get_distribution_profiles и send_app_version_to_testers для отправки сборок тестировщикам.
  • Проверка подписывающих идентификаторов — Используйте get_certificates, get_keystores и get_provisioning_profiles для проверки настройки подписи.
  • Отслеживание публикации в магазине — Используйте get_publish_profiles и get_publish_details для мониторинга запусков процесса публикации.

Документация

Appcircle MCP Server

MCP-сервер для Appcircle: предоставляет инструменты Build, Signing Identities, Testing Distribution, Enterprise App Store, Publish to Stores и Reporting любому MCP-совместимому клиенту (Claude Desktop, Cursor, VS Code и т. д.). Appcircle MCP Server выступает в роли моста между AI-инструментами и Appcircle; таким образом, AI-агенты, ассистенты и чат-боты могут безопасно получать доступ к ресурсам Appcircle и взаимодействовать с ними через структурированные, управляемые и ориентированные на задачи инструменты.

Варианты использования

  • Интеллект CI/CD и рабочих процессов: отслеживайте запуски конвейеров, контролируйте статус релизов и получайте аналитику по вашим мобильным CI/CD-процессам.
  • Конфигурация и аналитика окружения: запрашивайте конфигурации сборки и настройки подписи, чтобы понять, как настроен проект и где могут возникать проблемы.
  • Отчётность и операционная аналитика: формируйте сводки по стабильности CI, повторяющимся проблемам, производительности конвейеров и общему состоянию CI/CD.

Режимы запуска

Вы можете использовать MCP-сервер четырьмя способами:

РежимКраткое описание
1. Remote hostПодключение к https://mcp.appcircle.io. Без локальной установки; ваш клиент отправляет ваш токен Appcircle (например, Authorization: Bearer <token>) в каждом запросе.
2. Local (stdio)Запустите сервер из исходного кода: клонируйте репозиторий, при желании используйте venv, затем выполните appcircle-mcp (транспорт по умолчанию — stdio). Требуются Python и pip. Установите APPCIRCLE_ACCESS_TOKEN в переменных окружения. Ваш MCP-клиент запускает сервер как подпроцесс.
3. Local (streamable-http)Запустите сервер локально через HTTP: используйте --transport streamable-http и, при желании, --host / --port (например, appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000). Клиенты подключаются к этому URL и отправляют свой токен в запросе.
4. Local (Docker)Запустите официальный Docker-образ на вашей машине. Требуется Docker. Используйте порт по умолчанию из образа или переопределите его с помощью --port; точное использование см. в документации образа.

Подробная конфигурация клиентов (Cursor, Claude и т. д.) приведена в специальных руководствах по установке; этот раздел содержит только краткую сводку.

Установка

Руководства по настройке для конкретных клиентов:

  • Claude Applications — Руководство по установке для Claude Desktop и Claude Code CLI.
  • Cursor IDE — Руководство по установке для Cursor IDE.
  • Codex — Руководство по установке для приложения Codex и Codex CLI.
  • Antigravity IDE — Руководство по установке для Antigravity IDE.
  • VS Code (GitHub Copilot) — Руководство по установке для VS Code с GitHub Copilot.
  • Windsurf IDE — Руководство по установке для Windsurf IDE.
  • Gemini CLI — Руководство по установке для Gemini CLI.
  • GitHub Copilot CLI — Руководство по установке для GitHub Copilot CLI.

Конфигурация (переменные окружения)

ПеременнаяОбязательностьОписание
APPCIRCLE_ACCESS_TOKENДа (только stdio)Токен доступа к API Appcircle. Обязателен при использовании транспорта stdio. Для streamable-http каждый клиент отправляет свой собственный токен. См. Получение токена, чтобы узнать, как его получить.
APPCIRCLE_API_URLНетБазовый URL API (по умолчанию: https://api.appcircle.io может отличаться для пользователей self-hosted).
APPCIRCLE_MCP_ALLOWED_HOSTНет (только streamable-http)Публичное имя хоста для MCP-сервера (например, mcp.appcircle.io). Установите это при развёртывании за обратным прокси, чтобы сервер принимал заголовок Host от клиентов. Для localhost не указывайте.
APPCIRCLE_MCP_PORTНет (только streamable-http)Порт привязки для HTTP-сервера (по умолчанию: 8000). Переопределяется значением --port, если оно указано. Полезно для on-prem или Docker, когда требуется конкретный порт.
LOG_LEVELНетУровень журналирования, например DEBUG, INFO (по умолчанию: INFO).
APPCIRCLE_EXCLUDED_TOOLSETSНетРазделённые запятыми наборы инструментов для исключения (например, build_module,report). См. Наборы инструментов ниже.
AC_MCP_ENABLE_WRITE_TOOLSНетИнструменты записи/действий (например, trigger_build, cancel_build) регистрируются по умолчанию. Установите значение false/0/no/off, чтобы отказаться и не регистрировать их вовсе (не просто отключить при вызове).

Установите их в вашей оболочке или в конфигурации вашего MCP-клиента.

Наборы инструментов

Доступные наборы инструментов

Доступны следующие наборы инструментов:

Набор инструментовОписание
build_moduleПрофили сборки, конфигурации, рабочие процессы, коммиты и операции конвейера
signing_identitiesИдентификаторы подписи и идентификаторы пакетов
testing_distributionПрофили тестового распространения и детали распространения
publish_to_storesПрофили публикации и операции публикации в магазинах
enterprise_app_storeПрофили корпоративного магазина приложений и детали магазина
reportОтчётность: история сборок, распространение, подпись, статус публикации и связанные отчёты

Вы можете исключить один или несколько наборов инструментов, чтобы их инструменты не регистрировались. Исключения можно задать через аргументы CLI или переменную окружения APPCIRCLE_EXCLUDED_TOOLSETS; оба способа объединяются (union).

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

Пример MCP-конфигурации (Cursor / Claude Desktop) с исключениями:

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

Инструменты

Инструменты предоставляются через MCP tools/list. В справочнике ниже перечислены все инструменты по наборам; о формате ответов и примерах см. docs/tool_contract.md.

Build

  • get_build_profiles — Получить профили сборки для текущей организации (с постраничной разбивкой). При желании можно фильтровать по имени профиля, платформе, статусу последней сборки и источнику репозитория. При желании можно сортировать.

    • Уровень доступа: чтение
    • page: Номер страницы (начиная с 1). По умолчанию: 1. (число, необязательно)
    • size: Размер страницы (1–100). По умолчанию: 25. Значения выше 100 ограничиваются до 100. (число, необязательно)
    • search: Необязательный поисковый запрос для фильтрации профилей (частичное совпадение без учёта регистра по имени профиля; поиск API может также сопоставлять другие поля профиля). (строка, необязательно)
    • platform: Необязательный список кодов платформ для фильтрации. Допустимые значения: 1=iOS, 2=Android. (список чисел, необязательно)
    • last_build_status: Необязательный список кодов статуса последней сборки для фильтрации. Допустимые значения: 0=Успех, 1=Ошибка, 2=Отменено, 3=Тайм-аут, 90=Ожидание, 91=Выполняется. (список чисел, необязательно)
    • repository_source: Необязательный список кодов источника репозитория для фильтрации. Допустимые значения: 1=GitHub, 2=Bitbucket, 3=GitLab, 4=Azure DevOps, 6=Публичный репозиторий, 7=Частный репозиторий, 8=SSH. (список чисел, необязательно)
    • sort: Необязательный код поля сортировки. Допустимые значения: 1=Имя профиля, 2=Дата создания, 3=Дата последней сборки. (число, необязательно)
    • sort_direction: Необязательный код направления сортировки. Допустимые значения: 1=ASC, 2=DESC. (число, необязательно)

  • get_build_profile_details — Получить один профиль сборки по ID, при желании включая его конфигурации сборки.

    • Уровень доступа: чтение
    • profile_id: ID профиля сборки (например, UUID). (строка, обязательно)
    • configurations: Если true, также получить конфигурации сборки профиля. По умолчанию: false. (логическое, необязательно)

  • get_build_configuration_details — Получить одну конфигурацию сборки по ID профиля и ID конфигурации.

    • Уровень доступа: чтение
    • profile_id: ID профиля сборки (например, UUID). (строка, обязательно)
    • configuration_id: ID конфигурации сборки (например, UUID). (строка, обязательно)

  • get_build_profile_workflows — Получить рабочие процессы для профиля сборки по ID профиля.

    • Уровень доступа: чтение
    • profile_id: ID профиля сборки (например, UUID). (строка, обязательно)

  • get_workflow_detail — Получить один рабочий процесс по ID профиля сборки и ID рабочего процесса.

    • Уровень доступа: чтение
    • profile_id: ID профиля сборки (например, UUID). (строка, обязательно)
    • workflow_id: ID рабочего процесса (например, UUID). (строка, обязательно)

  • get_commits_by_branch — Получить коммиты для ветки сборки (с постраничной разбивкой).

    • Уровень доступа: чтение
    • branch_id: ID ветки (например, UUID). (строка, обязательно)
    • page: Номер страницы (начиная с 1). Если указан вместе с размером, включает постраничную разбивку. По умолчанию: 1. (число, необязательно)
    • size: Размер страницы. Если указан вместе с номером страницы, включает постраничную разбивку. По умолчанию: 25, максимум 100. (число, необязательно)

  • get_commit_details — Получить один коммит по ID коммита (UUID) или по хешу коммита (git SHA). Укажите либо commit_id, либо commit_hash, но не оба.

    • Уровень доступа: чтение
    • commit_id: ID коммита (UUID). (строка, необязательно)
    • commit_hash: Хеш коммита (git SHA). (строка, необязательно)

  • get_last_commit — Получить самый последний коммит в ветке сборки.

    • Уровень доступа: чтение
    • branch_id: ID ветки (например, UUID). (строка, обязательно)

  • get_build_status — Получить статус сборки (например, 0=Успех, 1=Ошибка, 2=Отменено, 3=Тайм-аут, 90=Ожидание, 91=Выполняется, 92=Завершение, 99=Неизвестно).

    • Уровень доступа: чтение
    • commit_id: ID коммита (UUID). (строка, обязательно)
    • build_id: ID сборки (UUID). (строка, обязательно)

  • get_build_logs — Получить журналы сборки, при желании ограничившись одним шагом. По умолчанию используется усечённое представление с конца, чтобы не перегружать контекст модели.

    • Уровень доступа: чтение
    • commit_id: ID коммита (UUID). (строка, обязательно)
    • build_id: ID сборки (UUID). (строка, обязательно)
    • step: Необязательное точное имя шага (без учёта регистра) для ограничения вывода блоком журнала одного шага. (строка, необязательно)
    • full_log: Если true, вернуть весь журнал вместо усечённого с конца по умолчанию. По-прежнему ограничен 256 КБ. По умолчанию: false. (логическое, необязательно)
    • tail_lines: Количество строк, сохраняемых с конца, когда не используется full_log. По умолчанию: 200, максимум 1000. (число, необязательно)
    • grep: Фильтр подстроки без учёта регистра, применяемый к строкам перед усечением. (строка, необязательно)

  • get_variable_groups — Получить все группы переменных окружения сборки для организации, включая переменные каждой группы (key, value, isSecret, isFile). Секретные значения уже скрыты API.

    • Уровень доступа: чтение
    • Параметры не требуются.

  • trigger_build — ПОБОЧНЫЙ ЭФФЕКТ: запускает новый реальный прогон сборки (ставит в очередь фактическую сборку, расходуя минуты/кредиты сборки) либо в ветке (последний синхронизированный коммит), либо для одного конкретного коммита. Регистрируется по умолчанию; установите AC_MCP_ENABLE_WRITE_TOOLS=false, чтобы отказаться.

    • Уровень доступа: запись
    • profile_id: ID профиля сборки (например, UUID). Обязателен в режиме ветки (commit_id не указан); не используется в режиме коммита. (строка, необязательно)
    • workflow_id: ID рабочего процесса (например, UUID). Обязателен в режиме ветки. Необязателен в режиме коммита (если опущен, используется последний использованный/рабочий процесс по умолчанию). (строка, необязательно)
    • branch_name: Необязательное имя ветки (например, "main"). Только режим ветки; если опущено, используется ветка по умолчанию профиля. Не должно указываться вместе с commit_id. (строка, необязательно)
    • commit_id: Собственный ID коммита (не его git-хеш) для запуска сборки для конкретного коммита вместо последнего в ветке. Не должно указываться вместе с branch_name. (строка, необязательно)
    • configuration_id: Необязательный ID конфигурации сборки (например, UUID) для использования вместо конфигурации по умолчанию. (строка, необязательно)

  • cancel_build — ПОБОЧНЫЙ ЭФФЕКТ: отменяет поставленную в очередь или выполняющуюся сборку (реальная выполняемая работа останавливается; возобновить её нельзя). Регистрируется по умолчанию; установите AC_MCP_ENABLE_WRITE_TOOLS=false, чтобы отказаться.

    • Уровень доступа: запись
    • task_id: ID задачи сборки (поле "taskId", возвращаемое trigger_build). (строка, обязательно)
Signing Identities

  • get_bundle_identifiers — Получить все идентификаторы пакетов для организации (идентификаторы пакетов приложений iOS/macOS).

    • Уровень доступа: чтение
    • Параметры не требуются.

  • get_certificates — Получить все сертификаты подписи для организации. Конфиденциальные поля (p12Password, p12Binary, metaData, thumbprint) опущены.

    • Уровень доступа: чтение
    • Параметров нет.

  • get_keystores — Получить все хранилища ключей для организации (например, keystore для подписи Android). Конфиденциальные поля (password, aliasPassword, binary, checkSum, sha256FingerPrint) опущены.

    • Уровень доступа: чтение
    • Параметров нет.

  • get_provisioning_profiles — Получить профили provisioning для организации (например, iOS/macOS). Конфиденциальные/большие поля (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) опущены. Опционально фильтровать по идентификатору приложения (bundle).

    • Уровень доступа: чтение
    • app_id: Необязательный идентификатор приложения (bundle) для фильтрации профилей provisioning (например, com.example.app). (string, optional)
Распространение для тестирования

  • get_distribution_profiles — Получить профили распространения для тестирования текущей организации (с постраничной разбивкой). Опционально фильтровать по имени профиля, платформе и типу аутентификации. Опционально сортировать.

    • Уровень доступа: чтение
    • page: Номер страницы (с 1). По умолчанию: 1. (number, optional)
    • size: Размер страницы (1–100). По умолчанию: 25, максимум 100. (number, optional)
    • search: Необязательный поисковый запрос для фильтрации профилей (регистронезависимое частичное совпадение по имени профиля; поиск в API может также сопоставлять другие поля профиля). (string, optional)
    • platform: Необязательный список кодов платформ для фильтрации. Допустимые значения: 1=iOS, 2=Android. (list of numbers, optional)
    • authentication_type: Необязательный список кодов типов аутентификации для фильтрации. Допустимые значения: 1=None, 3=Static Login, 4=LDAP, 5=SSO. (list of numbers, optional)
    • sort: Необязательный код поля сортировки. Допустимые значения: 1=Profile Name, 2=Create Date, 3=Last Upload Date. (number, optional)
    • sort_direction: Необязательный код направления сортировки. Допустимые значения: 1=ASC, 2=DESC. (number, optional)

  • get_distribution_profile_details — Получить один профиль распространения для тестирования по идентификатору (с необязательной постраничной разбивкой версий приложения).

    • Уровень доступа: чтение
    • profile_id: Идентификатор профиля распространения (например, UUID). (string, required)
    • page: Номер страницы для версий приложения (с 1). По умолчанию: 1. (number, optional)
    • size: Размер страницы для версий приложения (1–100). По умолчанию: 25, максимум 100. (number, optional)

  • get_testing_groups — Получить все группы тестирования для организации, включая адреса электронной почты участников-тестировщиков и тип группы.

    • Уровень доступа: чтение
    • Параметров не принимает.

  • update_app_version_release_notes — ПОБОЧНЫЙ ЭФФЕКТ: перезаписывает примечания к выпуску («message»), показываемые тестировщикам, для версии приложения дистрибуции. Возвращает обновлённый объект версии приложения (без certThumbPrints). Зарегистрирован по умолчанию; установите AC_MCP_ENABLE_WRITE_TOOLS=false, чтобы отказаться.

    • Уровень доступа: запись
    • profile_id: Идентификатор профиля распространения (например, UUID). (string, required)
    • app_version_id: Идентификатор версии приложения (например, UUID). (string, required)
    • message: Текст новых примечаний к выпуску. (string, required)

  • send_app_version_to_testers — ПОБОЧНЫЙ ЭФФЕКТ: отправляет реальное уведомление тестировщикам/группе тестирования, запуская задачу распространения для конкретной версии приложения. Зарегистрирован по умолчанию; установите AC_MCP_ENABLE_WRITE_TOOLS=false, чтобы отказаться.

    • Уровень доступа: запись
    • profile_id: Идентификатор профиля распространения (например, UUID). (string, required)
    • app_version_id: Идентификатор версии приложения (например, UUID). (string, required)
    • message: Текст уведомления, показываемый тестировщикам. (string, required)
    • testers: Список тестировщиков для отправки. Каждая запись — либо адрес электронной почты тестировщика, либо идентификатор группы тестирования (поле «id» из get_testing_groups). (list of strings, required)
Публикация в магазины

  • get_publish_profiles — Получить профили публикации для текущей организации для заданного типа платформы (с постраничной разбивкой). Опционально фильтровать по статусу потока, целевому магазину, наличию релиз-кандидатного бинарного файла и статусу магазина. Опционально сортировать.

    • Уровень доступа: чтение
    • platform_type: Тип платформы профилей публикации («ios» или «android»). (string, required)
    • page: Номер страницы (с 1). По умолчанию: 1. (number, optional)
    • size: Размер страницы (1–100). По умолчанию: 25, максимум 100. (number, optional)
    • flow_status: Необязательный код статуса потока для фильтрации (например, 0=Success, 1=Failed, 91=Running). (number, optional)
    • market_place_type: Необязательный список кодов целевых магазинов для фильтрации. Допустимые значения зависят от platform_type — ios: 0=Not Available, 1=App Store Connect, 4=Intune; android: 0=Not Available, 2=Google Play, 3=AppGallery, 4=Intune. (list of numbers, optional)
    • has_rc_binary: Необязательный фильтр наличия релиз-кандидатного бинарного файла у профиля. (boolean, optional)
    • store_status: Необязательный список кодов статусов магазина для фильтрации. Допустимые значения зависят от platform_type (для ios кодов значительно больше, чем для android, например, ios: «IN_REVIEW», «READY_FOR_SALE», «REJECTED»; android: «NOT_AVAILABLE», «DRAFT», «IN_PROGRESS», «HALTED», «COMPLETED»). (list of strings, optional)
    • sort: Необязательный код поля сортировки. Допустимые значения: 1=Profile Name, 2=Create Date. (number, optional)
    • sort_direction: Необязательный код направления сортировки. Допустимые значения: 1=ASC, 2=DESC. (number, optional)

  • get_publish_profile_details — Получить один профиль публикации по типу платформы и идентификатору (с необязательной постраничной разбивкой версий приложения).

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • page: Номер страницы для версий приложения (с 1). По умолчанию: 1. (number, optional)
    • size: Размер страницы для версий приложения (1–100). По умолчанию: 25, максимум 100. (number, optional)

  • get_app_version_metadata — Получить метаданные листинга магазина для одной версии приложения (информация о рецензировании приложения, локализации, сведения о выпуске, информация о версии приложения). appReviewInformation.demoPassword исключён.

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • app_version_id: Идентификатор версии приложения (например, UUID). (string, required)

  • get_metadata_locales — Получить доступные локали метаданных магазина для одной версии приложения (name, code, localized, isPrimary).

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • app_version_id: Идентификатор версии приложения (например, UUID). (string, required)

  • get_intune_metadata — Получить метаданные приложения Microsoft Intune для одной версии приложения (отображаемое имя, издатель, bundle ID, версия, состояние публикации, применимые типы устройств, категории и т. д.).

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • app_version_id: Идентификатор версии приложения (например, UUID). (string, required)

  • get_publish_metadata_lock_status — Получить, заблокированы ли метаданные магазина профиля публикации для редактирования.

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)

  • get_publish_details — Получить сведения о запуске потока публикации для одной версии приложения (статус, время, упорядоченные шаги с историей выполнения/артефактами/идентификаторами ресурсов журналов).

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • app_version_id: Идентификатор версии приложения (например, UUID). (string, required)

  • get_publish_step_logs — Получить журналы запуска потока публикации, опционально ограничившись одним шагом. По умолчанию возвращается усечённое представление хвоста журнала, чтобы не перегружать контекст модели.

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • publish_id: Идентификатор запуска потока публикации (поле «id» из get_publish_details). (string, required)
    • step_id: Идентификатор шага (поле «id» шага из списка шагов get_publish_details). (string, required)
    • step: Необязательное точное имя шага (регистронезависимое) для ограничения вывода блоком журнала одного шага. (string, optional)
    • full_log: Если true, вернуть весь журнал вместо хвоста по умолчанию. По-прежнему ограничен 256 КБ. По умолчанию: false. (boolean, optional)
    • tail_lines: Количество строк, сохраняемых с конца, когда не используется full_log. По умолчанию: 200, максимум 1000. (number, optional)
    • grep: Регистронезависимый фильтр подстроки, применяемый к строкам перед усечением. (string, optional)

  • get_publish_flows — Получить потоки публикации, настроенные для профиля публикации (имя, идентификатор, полный документ потока в YAML).

    • Уровень доступа: чтение
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)

  • start_publish — ПОБОЧНЫЙ ЭФФЕКТ: запускает выполнение потока публикации (или перезапускает его с конкретного шага) — реальная работа по публикации (например, загрузка в App Store/Play Store/Intune). Зарегистрирован по умолчанию; установите AC_MCP_ENABLE_WRITE_TOOLS=false, чтобы отказаться.

    • Уровень доступа: запись
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • publish_id: Идентификатор запуска потока публикации (поле «id» из get_publish_details). (string, required)
    • step_id: Необязательный идентификатор шага, чтобы начать с этого шага вместо начала потока. (string, optional)
    • organization_pool_id: Необязательный идентификатор пула организации (например, UUID) для выполнения. (string, optional)

  • stop_publish — ПОБОЧНЫЙ ЭФФЕКТ: отменяет выполняющийся запуск потока публикации (реальная выполняемая работа останавливается; возобновление невозможно). Зарегистрирован по умолчанию; установите AC_MCP_ENABLE_WRITE_TOOLS=false, чтобы отказаться.

    • Уровень доступа: запись
    • platform_type: Тип платформы («ios» или «android»). (string, required)
    • profile_id: Идентификатор профиля публикации (например, UUID). (string, required)
    • publish_id: Идентификатор запуска потока публикации (поле «id» из get_publish_details). (string, required)
    • step_id: Необязательный идентификатор шага. (string, optional)
    • organization_pool_id: Необязательный идентификатор пула организации (например, UUID). (string, optional)
Корпоративный магазин приложений
  • get_store_profiles — Получить профили корпоративного магазина приложений для текущей организации (с постраничной разбивкой). Поиск не поддерживается, но можно фильтровать по платформе, типу публикации и видимости. Опционально сортировать.
    • Уровень доступа: чтение
    • page: Номер страницы (с 1). По умолчанию: 1. (number, optional)
    • size: Размер страницы (1–100). По умолчанию: 25, максимум 100. (number, optional)
    • platform_type: Необязательный список кодов платформ для фильтрации. Допустимые значения: 1=iOS, 2=Android. (list of numbers, optional)
    • publish_type: Необязательный список кодов типов публикации для фильтрации. Допустимые значения: 1=Published to Beta, 2=Published to Live. (list of numbers, optional)
    • visibility: Необязательный фильтр публичной доступности профиля (true=Listed, false=Unlisted). (boolean, optional)
    • sort: Необязательный код поля сортировки. Допустимые значения: 1=App Name, 2=Create Date, 3=Download Count, 4=Binary Receive Date. (number, optional)
    • sort_direction: Необязательный код направления сортировки. Допустимые значения: 1=ASC, 2=DESC. (number, optional)
  • get_store_profile_details — Получить профиль корпоративного магазина приложений по ID (с опциональной пагинацией версий приложений).
    • Уровень доступа: чтение
    • profile_id: ID профиля корпоративного магазина приложений (например, UUID). (строка, обязательный)
    • page: Номер страницы для версий приложений (с 1). По умолчанию: 1. (число, необязательный)
    • size: Размер страницы для версий приложений (1–100). По умолчанию: 25, максимум 100. (число, необязательный)
    • Поле publishType каждой версии приложения — целое число: 0=Нет, 1=Бета, 2=Live.
Отчёт

  • get_build_history_report — Получить отчёт по истории сборок, опционально отфильтрованный по диапазону дат, профилю сборки и организации. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • build_profile_name: Фильтр по имени профиля сборки. (строка, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)

  • get_build_queue_waiting_report — Получить отчёт об ожидании в очереди сборок, опционально отфильтрованный по диапазону дат. С пагинацией. Примечание: на этой конечной точке buildDuration означает время ожидания в очереди в минутах, а не время выполнения (в отличие от get_build_history_report).

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). Должна быть <= end_date, если указаны обе. (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)

  • get_build_activity_log — Получить журнал активности сборок (изменения рабочего процесса/профиля, выпуски CodePush и т. д.), опционально отфильтрованный по диапазону дат и другим параметрам. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). Должна быть <= end_date, если указаны обе. (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)
    • platform: Фильтр по типу платформы (целочисленный код, например 0=Android, 1=iOS). (число, необязательный)
    • email: Фильтр по email действующего пользователя. (строка, необязательный)
    • profile_name: Фильтр по имени профиля сборки. (строка, необязательный)
    • action: Фильтр по коду действия активности (целое число; полное соответствие см. в BUILD_ACTIVITY_ACTIONS в исходном коде инструмента). (число, необязательный)

  • get_build_insights_report — Получить вычисленный отчёт Build Insights (снимок здоровья + тенденции, первопричина, здоровье артефактов, качество рабочего процесса, время в очереди и анализ зрелости) по истории сборок, агрегированный на стороне сервера. В отличие от get_build_history_report, этот инструмент внутренне перебирает все страницы и возвращает небольшие предварительно агрегированные результаты вместо необработанных записей.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД) для текущего периода. По умолчанию: последние 30 дней. (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД) для текущего периода. (строка, необязательный)
    • sections: Необязательный список разделов для вычисления: health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. По умолчанию: все шесть. (массив строк, необязательный)
    • include_sub_orgs: Если true, сохранять записи сборок из других организаций в метриках, основанных на истории, вместо фильтрации по собственной организации токена. По умолчанию: false. (логический, необязательный)

  • get_distribution_app_version_report — Получить ежедневный отчёт об использовании распространённых версий приложений. С пагинацией; поддерживает фильтры по профилю, ОС, организации.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • profile_name: Фильтр по имени профиля распространения. (строка, необязательный)
    • os: Фильтр по ОС ("ios" или "android"). (строка, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)

  • get_distribution_sent_report — Получить ежедневный отчёт об использовании общего доступа к распространённым приложениям. С пагинацией; поддерживает фильтры по профилю, ОС, организации.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • profile_name: Фильтр по имени профиля распространения. (строка, необязательный)
    • os: Фильтр по ОС ("ios" или "android"). (строка, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)

  • get_enterprise_app_store_app_usage_report — Получить отчёт об использовании приложений в корпоративном магазине приложений. start_date и end_date обязательны. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Дата начала (ГГГГ-ММ-ДД). (строка, обязательный)
    • end_date: Дата окончания (ГГГГ-ММ-ДД). (строка, обязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • organization_id: Необязательный фильтр по UUID организации. (строка, необязательный)

  • get_publish_resign_report — Получить отчёт о повторном подписании при публикации, опционально отфильтрованный по диапазону дат, имени приложения, организации и статусу. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • app_name: Фильтр по имени приложения. (строка, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)
    • status: Фильтр по статусу повторного подписания (0=ожидание, 1=обработка, 2=успешно, 3=сбой, 4=отменено, 5=таймаут). (число, необязательный)

  • get_publish_status_report — Получить отчёт о статусе публикации, опционально отфильтрованный по диапазону дат, имени приложения, организации и статусу. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • app_name: Фильтр по имени приложения. (строка, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)
    • status: Фильтр по статусу публикации (например, 0=Успех, 1=Сбой, 91=Выполняется). (число, необязательный)

  • get_signing_report — Получить отчёт о подписании, опционально отфильтрованный по диапазону дат, организации, ОС и статусу сборки. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)
    • os: Фильтр по ОС ("ios" или "android"). (строка, необязательный)
    • build_status: Фильтр по статусу сборки (например, 0=Успех, 1=Сбой, 91=Выполняется). (число, необязательный)

  • get_signing_activity_log — Получить журнал активности подписания (например, уведомления об истечении срока действия сертификата/профиля подготовки/keystore), опционально отфильтрованный по диапазону дат и другим параметрам. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). Должна быть <= end_date, если указаны обе. (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)
    • platform: Фильтр по платформе (например, "iOS", "Android"). (строка, необязательный)
    • email: Фильтр по email действующего пользователя. (строка, необязательный)
    • action: Фильтр по коду действия активности (целое число; полное соответствие см. в SIGNING_ACTIVITY_ACTIONS в исходном коде инструмента). (число, необязательный)

  • get_publish_activity_log — Получить журнал активности публикации (повторное подписание, события потока публикации и т. д.), опционально отфильтрованный по диапазону дат и другим параметрам. С пагинацией.

    • Уровень доступа: чтение
    • start_date: Необязательная дата начала (ГГГГ-ММ-ДД). Должна быть <= end_date, если указаны обе. (строка, необязательный)
    • end_date: Необязательная дата окончания (ГГГГ-ММ-ДД). (строка, необязательный)
    • page: Номер страницы (по умолчанию: 1). (число, необязательный)
    • size: Элементов на странице (1–100, по умолчанию: 50). (число, необязательный)
    • organization_id: Фильтр по UUID организации. (строка, необязательный)
    • platform: Фильтр по платформе (например, "iOS", "Android"). (строка, необязательный)
    • email: Фильтр по email действующего пользователя. (строка, необязательный)
    • profile_name: Фильтр по имени профиля публикации. (строка, необязательный)
    • action: Фильтр по коду действия активности (целое число; полное соответствие см. в PUBLISH_ACTIVITY_ACTIONS в исходном коде инструмента). (число, необязательный)

Запуск сервера

Из корня репозитория:

python -m src.server

Или после pip install -e .:

appcircle-mcp

Сервер работает через stdio (или SSE/HTTP в зависимости от того, как ваш клиент его запускает).

Формат ответа

Каждый инструмент возвращает стандартную обёртку:

  • Успех: { "success": true, "data": <payload>, "meta": { ... } }
    data — результат инструмента; meta необязателен (например, count, page, filters).
  • Ошибка: { "success": false, "error": { "tool", "type", "message", "details" } }
    Одинаковая структура для всех инструментов, чтобы клиенты могли единообразно разбирать ошибки.

Полная спецификация: docs/tool_contract.md.

Тестирование

Установка с зависимостями для разработки:

pip install -e ".[dev]"

Модульные тесты (по умолчанию)

Используют имитированный API; APPCIRCLE_ACCESS_TOKEN не требуется. По умолчанию pytest запускает только их (см. testpaths в pyproject.toml):

pytest test/unit/ -v
  • Один файл: pytest test/unit/tools/build_module/test_get_build_profiles.py -v
  • С покрытием: pytest test/unit/ --cov=src --cov-report=term-missing

Интеграционные тесты

Вызывают реальный Appcircle API. Установите APPCIRCLE_ACCESS_TOKEN в окружении, затем выполните:

pytest test/integration/ -v
  • Все интеграционные тесты: pytest test/integration/ -v
  • По инструменту: pytest test/integration/build_module/ -v, pytest test/integration/report/ -v и т. д.
  • По маркеру: pytest -m integration -v (при запуске из корня репозитория; включает только интеграционные тесты, если собираются и модульные, и интеграционные)

Если APPCIRCLE_ACCESS_TOKEN не установлен, интеграционные тесты пропускаются (без сбоя).

Необязательные переменные окружения для интеграционных тестов (если обнаружение не удаётся или тестам нужны реальные ID; опустите, чтобы пропустить эти тесты):

ПеременнаяОписание
APPCIRCLE_TEST_ORGANIZATION_IDUUID организации. Используется test_with_organization_id (отчёт об использовании приложений в корпоративном магазине приложений).
APPCIRCLE_TEST_BRANCH_IDUUID ветки. Используется get_commits_by_branch и связанными тестами, когда ветку невозможно обнаружить через API.
APPCIRCLE_TEST_COMMIT_IDUUID коммита. Используется тестами get_commit_details, когда коммит невозможно обнаружить через API.
Интеграционные тесты записи/действий (trigger_build, cancel_build и т. д.) помечены как integration_write и являются опциональными в дополнение к APPCIRCLE_ACCESS_TOKEN — они изменяют реальные данные (запускают реальные сборки и т. д.), поэтому никогда не запускаются просто из pytest test/integration/ -v. Установите APPCIRCLE_RUN_WRITE_INTEGRATION_TESTS=true (указывая APPCIRCLE_ACCESS_TOKEN на выделенную тестовую организацию, а не на продакшн), чтобы включить их.

Безопасность

Этот проект зависит от сторонних пакетов с открытым исходным кодом, перечисленных в pyproject.toml. Хотя мы фиксируем диапазоны версий зависимостей и поставляем lockfile (uv.lock) с криптографическими хешами, эти пакеты поддерживаются независимо и предоставляются «как есть». Appcircle не дает никаких гарантий относительно безопасности или надежности сторонних зависимостей.

Мы рекомендуем проверять установленные пакеты перед использованием:

uv run pip-audit