Appcircle MCP Server

официальный

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

GitHub

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

  • Список и поиск профилей сборки — Получение постраничных профилей сборки и фильтрация по имени с помощью get_build_profiles.
  • Просмотр конфигураций сборки и рабочих процессов — Получение сведений о конкретном профиле сборки, его конфигурациях и рабочих процессах с помощью get_build_profile_details, get_build_configuration_details и get_workflow_detail.
  • Просмотр подписывающих удостоверений — Вывод списка сертификатов, хранилищ ключей, профилей подготовки и идентификаторов пакетов через get_certificates, get_keystores, get_provisioning_profiles и get_bundle_identifiers.
  • Проверка статуса тестирования и корпоративного распространения — Получение профилей распространения и их версий приложений с помощью get_distribution_profiles и get_distribution_profile_details, или просмотр профилей корпоративного магазина через get_store_profiles.
  • Создание отчетов о состоянии CI/CD и истории сборок — Используйте get_build_insights_report для агрегированных трендов и анализа первопричин, или get_build_history_report для необработанных записей сборок.

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

Appcircle MCP Server

MCP-сервер для Appcircle: предоставляет инструменты сборки, идентификации подписей, тестового распространения, корпоративного магазина приложений, публикации в магазины и отчетности любому MCP-совместимому клиенту (Claude Desktop, Cursor, VS Code и др.). Appcircle MCP Server выступает в роли моста между инструментами ИИ и Appcircle, позволяя ИИ-агентам, ассистентам и чат-ботам безопасно получать доступ и взаимодействовать с ресурсами Appcircle через структурированные, управляемые инструменты на уровне задач.

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

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

Режимы работы

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

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

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

Установка

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

  • Приложения Claude — Руководство по установке для 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). См. Наборы инструментов ниже.

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

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

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

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

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

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

  • CLI: --exclude toolset1 toolset2 или --exclude-toolsets toolset1,toolset2
  • Окружение: 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.

Сборка

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

    • Уровень доступа: чтение
    • page: Номер страницы (начиная с 1). По умолчанию: 1. (число, опционально)
    • size: Размер страницы (1-100). По умолчанию: 25. Значения выше 100 ограничиваются 100. (число, опционально)
    • search: Опциональный поисковый запрос для фильтрации профилей по имени (частичное совпадение без учета регистра). (строка, опционально)

  • 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). Если указан вместе с size, включает пагинацию. По умолчанию: 1. (число, опционально)
    • size: Размер страницы. Если указан вместе с page, включает пагинацию. По умолчанию: 25, макс. 100. (число, опционально)

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

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

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

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

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

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

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

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

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

    • Уровень доступа: чтение
    • app_id: Опциональный ID приложения (пакета) для фильтрации профилей обеспечения (например, com.example.app). (строка, опционально)
Тестовое распространение

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

    • Уровень доступа: чтение
    • page: Номер страницы (начиная с 1). По умолчанию: 1. (число, опционально)
    • size: Размер страницы (1-100). По умолчанию: 25, макс. 100. (число, опционально)
    • search: Опциональный поисковый запрос для фильтрации профилей по имени. (строка, опционально)

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

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

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

    • Уровень доступа: чтение
    • platform_type: Тип платформы профилей публикации ("ios" или "android"). (строка, обязательно)
    • page: Номер страницы (начиная с 1). По умолчанию: 1. (число, опционально)
    • size: Размер страницы (1-100). По умолчанию: 25, макс. 100. (число, опционально)
    • flow_status: Опциональный код статуса потока для фильтрации (например, 0=Успех, 1=Ошибка, 91=Выполняется). (число, опционально)

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

    • Уровень доступа: чтение
    • platform_type: Тип платформы ("ios" или "android"). (строка, обязательно)
    • profile_id: ID профиля публикации (например, UUID). (строка, обязательно)
    • page: Номер страницы для версий приложения (начиная с 1). По умолчанию: 1. (число, опционально)
    • size: Размер страницы для версий приложения (1-100). По умолчанию: 25, макс. 100. (число, опционально)
Корпоративный магазин приложений

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

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

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

    • Уровень доступа: чтение
    • profile_id: ID профиля корпоративного магазина приложений (например, UUID). (строка, обязательно)
    • page: Номер страницы для версий приложения (начиная с 1). По умолчанию: 1. (число, опционально)
    • size: Размер страницы для версий приложения (1-100). По умолчанию: 25, макс. 100. (число, опционально)
Отчет - **get_build_history_report** — Получить отчёт об истории сборок, опционально отфильтрованный по диапазону дат, профилю сборки и организации. С постраничной навигацией. - **Уровень доступа:** чтение - `start_date`: Опциональная дата начала (ГГГГ-ММ-ДД). (строка, опционально) - `end_date`: Опциональная дата окончания (ГГГГ-ММ-ДД). (строка, опционально) - `page`: Номер страницы (по умолчанию: 1). (число, опционально) - `size`: Элементов на странице (1-100, по умолчанию: 50). (число, опционально) - `build_profile_name`: Фильтр по имени профиля сборки. (строка, опционально) - `organization_id`: Фильтр по UUID организации. (строка, опционально)

  • 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=Выполняется). (число, опционально)

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

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

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

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

Обращаются к реальному API Appcircle. Установите 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.

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

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

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

uv run pip-audit