Appcircle MCP Server

공식

Appcircle의 공식 MCP 서버

GitHub

Appcircle MCP(으)로 무엇을 할 수 있나요?

  • 빌드 프로필 목록 및 검색 — get_build_profiles를 사용하여 페이지별로 정리된 빌드 프로필을 검색하고 이름으로 필터링합니다.
  • 빌드 구성 및 워크플로 검사 — get_build_profile_details, get_build_configuration_details, get_workflow_detail을 사용하여 특정 빌드 프로필, 해당 구성 및 워크플로의 세부 정보를 가져옵니다.
  • 서명 ID 검토 — 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 서버

Appcircle용 MCP 서버: 빌드, 서명 ID, 테스트 배포, 엔터프라이즈 앱 스토어, 스토어 배포, 보고 도구를 모든 MCP 지원 클라이언트(Claude Desktop, Cursor, VS Code 등)에 제공합니다. Appcircle MCP 서버는 AI 도구와 Appcircle 사이의 가교 역할을 하므로, AI 에이전트, 어시스턴트, 챗봇이 구조화되고 통제된 작업 수준의 도구를 통해 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 등)은 전용 설치 가이드에 있습니다. 이 섹션은 개괄적인 요약입니다.

설치

클라이언트별 설정 가이드:

구성 (환경 변수)

변수필수설명
APPCIRCLE_ACCESS_TOKEN예 (stdio 전용)Appcircle API 액세스 토큰. stdio 전송 사용 시 필수. streamable-http의 경우 각 클라이언트가 자체 토큰을 전송합니다. 토큰 획득 방법은 토큰 얻기를 참조하세요.
APPCIRCLE_API_URL아니요API 기본 URL (기본값: https://api.appcircle.io, 자체 호스팅 사용자의 경우 다를 수 있음).
APPCIRCLE_MCP_ALLOWED_HOST아니요 (streamable-http 전용)MCP 서버의 공개 호스트 이름 (예: mcp.appcircle.io). 리버스 프록시 뒤에 배포할 때 설정하면 서버가 클라이언트의 Host 헤더를 수락합니다. 로컬 호스트의 경우 생략합니다.
APPCIRCLE_MCP_PORT아니요 (streamable-http 전용)HTTP 서버의 바인드 포트 (기본값: 8000). 제공된 경우 --port에 의해 재정의됩니다. 특정 포트가 필요한 온프레미스 또는 Docker 환경에 유용합니다.
LOG_LEVEL아니요로깅 레벨, 예: DEBUG, INFO (기본값: INFO).
APPCIRCLE_EXCLUDED_TOOLSETS아니요제외할 도구 세트의 쉼표 구분 목록 (예: build_module,report). 아래 도구 세트를 참조하세요.

셸 또는 MCP 클라이언트 구성에서 설정하세요.

도구 세트

사용 가능한 도구 세트

다음 도구 세트를 사용할 수 있습니다:

도구 세트설명
build_module빌드 프로필, 구성, 워크플로우, 커밋 및 파이프라인 작업
signing_identities서명 ID 및 번들 식별자
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부터 시작). 크기와 함께 제공되면 페이지 매김이 활성화됩니다. 기본값: 1. (숫자, 선택 사항)
    • size: 페이지 크기. 페이지와 함께 제공되면 페이지 매김이 활성화됩니다. 기본값: 25, 최대 100. (숫자, 선택 사항)

  • get_commit_details - 커밋 ID(UUID) 또는 커밋 해시(git SHA)로 단일 커밋을 가져옵니다. commit_id 또는 commit_hash 중 하나만 제공하세요.

    • 액세스 수준: 읽기
    • commit_id: 커밋 ID (UUID). (문자열, 선택 사항)
    • commit_hash: 커밋 해시 (git SHA). (문자열, 선택 사항)
서명 ID

  • get_bundle_identifiers - 조직의 모든 번들 식별자를 가져옵니다(iOS/macOS 앱 번들 ID).

    • 액세스 수준: 읽기
    • 매개변수 없음.

  • 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`: 선택적 시작 날짜 (YYYY-MM-DD). (문자열, 선택 사항) - `end_date`: 선택적 종료 날짜 (YYYY-MM-DD). (문자열, 선택 사항) - `page`: 페이지 번호 (기본값: 1). (숫자, 선택 사항) - `size`: 페이지당 항목 수 (1-100, 기본값: 50). (숫자, 선택 사항) - `build_profile_name`: 빌드 프로필 이름으로 필터링. (문자열, 선택 사항) - `organization_id`: 조직 UUID로 필터링. (문자열, 선택 사항)

  • get_build_insights_report - 빌드 이력에 대한 계산된 빌드 인사이트 보고서(상태 스냅샷 및 추세, 근본 원인, 아티팩트 상태, 워크플로우 품질, 대기 시간, 성숙도 평가 분석)를 서버 측에서 집계하여 가져옵니다. get_build_history_report와 달리, 이 도구는 내부적으로 모든 페이지를 가져와 원시 레코드 대신 사전 집계된 작은 결과를 반환합니다.

    • 접근 수준: 읽기
    • start_date: 현재 기간에 대한 선택적 시작 날짜 (YYYY-MM-DD). 기본값: 최근 30일. (문자열, 선택 사항)
    • end_date: 현재 기간에 대한 선택적 종료 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • sections: 계산할 섹션의 선택적 목록: health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. 기본값: 6개 모두. (문자열 배열, 선택 사항)
    • include_sub_orgs: true인 경우, 토큰 자체 조직으로 필터링하는 대신 이력 기반 메트릭에 교차 조직 빌드 기록을 유지합니다. 기본값: false. (부울, 선택 사항)

  • get_distribution_app_version_report - 배포된 앱 버전에 대한 일일 사용량 보고서를 가져옵니다. 페이지네이션 지원; 프로필, OS, 조직별 필터를 지원합니다.

    • 접근 수준: 읽기
    • start_date: 선택적 시작 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • end_date: 선택적 종료 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • page: 페이지 번호 (기본값: 1). (숫자, 선택 사항)
    • size: 페이지당 항목 수 (1-100, 기본값: 50). (숫자, 선택 사항)
    • profile_name: 배포 프로필 이름으로 필터링. (문자열, 선택 사항)
    • os: OS로 필터링 ("ios" 또는 "android"). (문자열, 선택 사항)
    • organization_id: 조직 UUID로 필터링. (문자열, 선택 사항)

  • get_distribution_sent_report - 배포된 앱 공유에 대한 일일 사용량 보고서를 가져옵니다. 페이지네이션 지원; 프로필, OS, 조직별 필터를 지원합니다.

    • 접근 수준: 읽기
    • start_date: 선택적 시작 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • end_date: 선택적 종료 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • page: 페이지 번호 (기본값: 1). (숫자, 선택 사항)
    • size: 페이지당 항목 수 (1-100, 기본값: 50). (숫자, 선택 사항)
    • profile_name: 배포 프로필 이름으로 필터링. (문자열, 선택 사항)
    • os: OS로 필터링 ("ios" 또는 "android"). (문자열, 선택 사항)
    • organization_id: 조직 UUID로 필터링. (문자열, 선택 사항)

  • get_enterprise_app_store_app_usage_report - 엔터프라이즈 앱 스토어에 대한 앱 사용량 보고서를 가져옵니다. start_date 및 end_date는 필수입니다. 페이지네이션 지원.

    • 접근 수준: 읽기
    • start_date: 시작 날짜 (YYYY-MM-DD). (문자열, 필수)
    • end_date: 종료 날짜 (YYYY-MM-DD). (문자열, 필수)
    • page: 페이지 번호 (기본값: 1). (숫자, 선택 사항)
    • size: 페이지당 항목 수 (1-100, 기본값: 50). (숫자, 선택 사항)
    • organization_id: 조직 UUID로 선택적 필터링. (문자열, 선택 사항)

  • get_publish_resign_report - 게시 재서명 보고서를 가져옵니다. 날짜 범위, 앱 이름, 조직, 상태별로 선택적 필터링이 가능합니다. 페이지네이션 지원.

    • 접근 수준: 읽기
    • start_date: 선택적 시작 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • end_date: 선택적 종료 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • page: 페이지 번호 (기본값: 1). (숫자, 선택 사항)
    • size: 페이지당 항목 수 (1-100, 기본값: 50). (숫자, 선택 사항)
    • app_name: 앱 이름으로 필터링. (문자열, 선택 사항)
    • organization_id: 조직 UUID로 필터링. (문자열, 선택 사항)
    • status: 재서명 상태로 필터링 (0=대기 중, 1=처리 중, 2=성공, 3=실패, 4=취소됨, 5=시간 초과). (숫자, 선택 사항)

  • get_publish_status_report - 게시 상태 보고서를 가져옵니다. 날짜 범위, 앱 이름, 조직, 상태별로 선택적 필터링이 가능합니다. 페이지네이션 지원.

    • 접근 수준: 읽기
    • start_date: 선택적 시작 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • end_date: 선택적 종료 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • page: 페이지 번호 (기본값: 1). (숫자, 선택 사항)
    • size: 페이지당 항목 수 (1-100, 기본값: 50). (숫자, 선택 사항)
    • app_name: 앱 이름으로 필터링. (문자열, 선택 사항)
    • organization_id: 조직 UUID로 필터링. (문자열, 선택 사항)
    • status: 게시 상태로 필터링 (예: 0=성공, 1=실패, 91=실행 중). (숫자, 선택 사항)

  • get_signing_report - 서명 보고서를 가져옵니다. 날짜 범위, 조직, OS, 빌드 상태별로 선택적 필터링이 가능합니다. 페이지네이션 지원.

    • 접근 수준: 읽기
    • start_date: 선택적 시작 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • end_date: 선택적 종료 날짜 (YYYY-MM-DD). (문자열, 선택 사항)
    • page: 페이지 번호 (기본값: 1). (숫자, 선택 사항)
    • size: 페이지당 항목 수 (1-100, 기본값: 50). (숫자, 선택 사항)
    • organization_id: 조직 UUID로 필터링. (문자열, 선택 사항)
    • os: 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은 이것만 실행합니다 (자세한 내용은 pyproject.toml의 testpaths 참조):

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_ID조직 UUID. test_with_organization_id (엔터프라이즈 앱 스토어 앱 사용량 보고서)에서 사용됩니다.
APPCIRCLE_TEST_BRANCH_ID브랜치 UUID. API에서 브랜치를 검색할 수 없을 때 get_commits_by_branch 및 관련 테스트에서 사용됩니다.
APPCIRCLE_TEST_COMMIT_ID커밋 UUID. API에서 커밋을 검색할 수 없을 때 get_commit_details 테스트에서 사용됩니다.

보안

이 프로젝트는 pyproject.toml에 나열된 서드파티 오픈 소스 패키지에 의존합니다. 의존성 버전 범위를 고정하고 암호화 해시가 포함된 잠금 파일(uv.lock)을 제공하지만, 이러한 패키지는 독립적으로 유지 관리되며 "있는 그대로" 제공됩니다. Appcircle은 서드파티 의존성의 보안 또는 신뢰성에 대해 어떠한 보증도 하지 않습니다.

사용 전에 설치된 패키지를 감사하는 것이 좋습니다:

uv run pip-audit