Appcircle MCP Server

resmi

Server MCP resmi Appcircle

GitHub

Apa yang bisa Anda lakukan dengan Appcircle MCP?

  • Daftar dan cari profil build — Ambil profil build yang dipaginasi dan filter berdasarkan nama menggunakan get_build_profiles.
  • Periksa konfigurasi build dan alur kerja — Ambil detail untuk profil build tertentu, konfigurasinya, dan alur kerja menggunakan get_build_profile_details, get_build_configuration_details, dan get_workflow_detail.
  • Tinjau identitas penandatanganan — Daftar sertifikat, penyimpanan kunci, profil provisioning, dan pengenal bundel melalui get_certificates, get_keystores, get_provisioning_profiles, dan get_bundle_identifiers.
  • Periksa status pengujian dan distribusi enterprise — Dapatkan profil distribusi dan versi aplikasinya dengan get_distribution_profiles dan get_distribution_profile_details, atau periksa profil toko enterprise melalui get_store_profiles.
  • Hasilkan laporan kesehatan CI/CD dan riwayat build — Gunakan get_build_insights_report untuk tren agregat dan analisis akar penyebab, atau get_build_history_report untuk catatan build mentah.

Dokumentasi

Appcircle MCP Server

Server MCP untuk Appcircle: menyediakan alat Build, Signing Identities, Testing Distribution, Enterprise App Store, Publish to Stores, dan Reporting kepada klien apa pun yang mendukung MCP (Claude Desktop, Cursor, VS Code, dll.). Appcircle MCP Server bertindak sebagai jembatan antara alat AI dan Appcircle; dengan demikian, agen AI, asisten, dan chatbot dapat mengakses dan berinteraksi dengan sumber daya Appcircle secara aman melalui alat terstruktur, terkelola, dan pada tingkat tugas.

Kasus Penggunaan

  • Intelijen CI/CD dan Alur Kerja: Pantau jalannya pipeline, lacak status rilis, dan dapatkan wawasan tentang alur kerja CI/CD seluler Anda.
  • Wawasan Konfigurasi dan Lingkungan: Kueri konfigurasi build dan pengaturan penandatanganan untuk memahami bagaimana proyek dikonfigurasi dan dari mana masalah mungkin berasal.
  • Pelaporan dan Wawasan Operasional: Hasilkan ringkasan stabilitas CI, masalah berulang, kinerja pipeline, dan kesehatan CI/CD secara keseluruhan.

Mode Berjalan

Anda dapat menggunakan server MCP dalam empat cara:

ModeRingkasan
1. Host jarak jauhTerhubung ke https://mcp.appcircle.io. Tidak perlu instalasi lokal; klien Anda mengirimkan token Appcircle Anda (mis. Authorization: Bearer <token>) pada setiap permintaan.
2. Lokal (stdio)Jalankan server dari sumber: kloning repositori, opsional gunakan venv, lalu jalankan appcircle-mcp (transport default adalah stdio). Memerlukan Python dan pip. Atur APPCIRCLE_ACCESS_TOKEN di lingkungan. Klien MCP Anda menjalankan server sebagai subproses.
3. Lokal (streamable-http)Jalankan server secara lokal melalui HTTP: gunakan --transport streamable-http dan opsional --host / --port (mis. appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000). Klien terhubung ke URL tersebut dan mengirimkan token mereka dalam permintaan.
4. Lokal (Docker)Jalankan image Docker resmi di mesin Anda. Memerlukan Docker. Gunakan port default image atau timpa dengan --port; lihat dokumentasi image untuk penggunaan yang tepat.

Konfigurasi klien terperinci (Cursor, Claude, dll.) terdapat di panduan instalasi khusus; bagian ini hanyalah ringkasan tingkat tinggi.

Instalasi

Panduan pengaturan khusus klien:

Konfigurasi (Variabel Lingkungan)

VariabelDiperlukanDeskripsi
APPCIRCLE_ACCESS_TOKENYa (hanya stdio)Token akses API Appcircle. Diperlukan saat menggunakan transport stdio. Untuk streamable-http, setiap klien mengirimkan tokennya sendiri. Lihat Mendapatkan token untuk cara mendapatkannya.
APPCIRCLE_API_URLTidakURL dasar API (default: https://api.appcircle.io mungkin berbeda untuk pengguna self-hosted).
APPCIRCLE_MCP_ALLOWED_HOSTTidak (hanya streamable-http)Nama host publik untuk server MCP (mis. mcp.appcircle.io). Atur ini saat menerapkan di belakang proxy terbalik sehingga server menerima header Host dari klien. Abaikan untuk localhost.
APPCIRCLE_MCP_PORTTidak (hanya streamable-http)Port bind untuk server HTTP (default: 8000). Ditimpa oleh --port jika disediakan. Berguna untuk on-prem atau Docker saat port tertentu diperlukan.
LOG_LEVELTidakTingkat logging, mis. DEBUG, INFO (default: INFO).
APPCIRCLE_EXCLUDED_TOOLSETSTidakKumpulan alat yang dipisahkan koma untuk dikecualikan (mis. build_module,report). Lihat Kumpulan Alat di bawah.

Atur ini di shell Anda atau di konfigurasi klien MCP Anda.

Kumpulan Alat

Kumpulan Alat yang Tersedia

Kumpulan alat berikut tersedia:

Kumpulan AlatDeskripsi
build_moduleProfil build, konfigurasi, alur kerja, komit, dan operasi pipeline
signing_identitiesIdentitas penandatanganan dan pengidentifikasi bundel
testing_distributionProfil distribusi pengujian dan detail distribusi
publish_to_storesProfil publikasi dan operasi penerbitan toko
enterprise_app_storeProfil toko aplikasi perusahaan dan detail toko
reportPelaporan: riwayat build, distribusi, penandatanganan, status publikasi, dan laporan terkait

Anda dapat mengecualikan satu atau beberapa kumpulan alat sehingga alatnya tidak terdaftar. Pengecualian dapat diatur melalui argumen CLI atau variabel lingkungan APPCIRCLE_EXCLUDED_TOOLSETS; keduanya digabungkan (gabungan).

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

Contoh konfigurasi MCP (Cursor / Claude Desktop) dengan pengecualian:

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

Alat

Alat diekspos melalui MCP tools/list. Referensi di bawah mencantumkan semua alat berdasarkan kumpulan alat; untuk bentuk respons dan contoh lihat docs/tool_contract.md.

Build

  • get_build_profiles - Dapatkan profil build untuk organisasi saat ini (dipaginasi). Opsional filter berdasarkan nama profil.

    • Tingkat akses: baca
    • page: Nomor halaman (berbasis 1). Default: 1. (angka, opsional)
    • size: Ukuran halaman (1-100). Default: 25. Nilai di atas 100 dibatasi pada 100. (angka, opsional)
    • search: Istilah pencarian opsional untuk memfilter profil berdasarkan nama (pencocokan sebagian tidak peka huruf besar/kecil). (string, opsional)

  • get_build_profile_details - Dapatkan satu profil build berdasarkan ID, opsional termasuk konfigurasi build-nya.

    • Tingkat akses: baca
    • profile_id: ID profil build (mis. UUID). (string, diperlukan)
    • configurations: Jika true, ambil juga konfigurasi build profil. Default: false. (boolean, opsional)

  • get_build_configuration_details - Dapatkan satu konfigurasi build berdasarkan ID profil dan ID konfigurasi.

    • Tingkat akses: baca
    • profile_id: ID profil build (mis. UUID). (string, diperlukan)
    • configuration_id: ID konfigurasi build (mis. UUID). (string, diperlukan)

  • get_build_profile_workflows - Dapatkan alur kerja untuk profil build berdasarkan ID profil.

    • Tingkat akses: baca
    • profile_id: ID profil build (mis. UUID). (string, diperlukan)

  • get_workflow_detail - Dapatkan satu alur kerja berdasarkan ID profil build dan ID alur kerja.

    • Tingkat akses: baca
    • profile_id: ID profil build (mis. UUID). (string, diperlukan)
    • workflow_id: ID alur kerja (mis. UUID). (string, diperlukan)

  • get_commits_by_branch - Dapatkan komit untuk cabang build (dipaginasi).

    • Tingkat akses: baca
    • branch_id: ID cabang (mis. UUID). (string, diperlukan)
    • page: Nomor halaman (berbasis 1). Jika disediakan dengan ukuran, mengaktifkan paginasi. Default: 1. (angka, opsional)
    • size: Ukuran halaman. Jika disediakan dengan halaman, mengaktifkan paginasi. Default: 25, maks 100. (angka, opsional)

  • get_commit_details - Dapatkan satu komit berdasarkan ID komit (UUID) atau berdasarkan hash komit (git SHA). Sediakan commit_id atau commit_hash, jangan keduanya.

    • Tingkat akses: baca
    • commit_id: ID komit (UUID). (string, opsional)
    • commit_hash: Hash komit (git SHA). (string, opsional)
Identitas Penandatanganan

  • get_bundle_identifiers - Dapatkan semua pengidentifikasi bundel untuk organisasi (ID bundel aplikasi iOS/macOS).

    • Tingkat akses: baca
    • Tidak ada parameter.

  • get_certificates - Dapatkan semua sertifikat penandatanganan untuk organisasi. Bidang sensitif (p12Password, p12Binary, metaData, thumbprint) dihilangkan.

    • Tingkat akses: baca
    • Tidak ada parameter.

  • get_keystores - Dapatkan semua keystore untuk organisasi (mis. keystore penandatanganan Android). Bidang sensitif (password, aliasPassword, binary, checkSum, sha256FingerPrint) dihilangkan.

    • Tingkat akses: baca
    • Tidak ada parameter.

  • get_provisioning_profiles - Dapatkan profil provisioning untuk organisasi (mis. iOS/macOS). Bidang sensitif/besar (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) dihilangkan. Opsional filter berdasarkan ID aplikasi (bundel).

    • Tingkat akses: baca
    • app_id: ID aplikasi (bundel) opsional untuk memfilter profil provisioning (mis. com.example.app). (string, opsional)
Distribusi Pengujian

  • get_distribution_profiles - Dapatkan profil distribusi pengujian untuk organisasi saat ini (dipaginasi). Opsional filter berdasarkan nama profil.

    • Tingkat akses: baca
    • page: Nomor halaman (berbasis 1). Default: 1. (angka, opsional)
    • size: Ukuran halaman (1-100). Default: 25, maks 100. (angka, opsional)
    • search: Istilah pencarian opsional untuk memfilter profil berdasarkan nama. (string, opsional)

  • get_distribution_profile_details - Dapatkan satu profil distribusi pengujian berdasarkan ID (dengan paginasi versi aplikasi opsional).

    • Tingkat akses: baca
    • profile_id: ID profil distribusi (mis. UUID). (string, diperlukan)
    • page: Nomor halaman untuk versi aplikasi (berbasis 1). Default: 1. (angka, opsional)
    • size: Ukuran halaman untuk versi aplikasi (1-100). Default: 25, maks 100. (angka, opsional)
Publikasi ke Toko

  • get_publish_profiles - Dapatkan profil publikasi untuk organisasi saat ini untuk tipe platform tertentu (dipaginasi). Opsional filter berdasarkan status alur.

    • Tingkat akses: baca
    • platform_type: Tipe platform profil publikasi ("ios" atau "android"). (string, diperlukan)
    • page: Nomor halaman (berbasis 1). Default: 1. (angka, opsional)
    • size: Ukuran halaman (1-100). Default: 25, maks 100. (angka, opsional)
    • flow_status: Kode status alur opsional untuk memfilter (mis. 0=Sukses, 1=Gagal, 91=Berjalan). (angka, opsional)

  • get_publish_profile_details - Dapatkan satu profil publikasi berdasarkan tipe platform dan ID (dengan paginasi versi aplikasi opsional).

    • Tingkat akses: baca
    • platform_type: Tipe platform ("ios" atau "android"). (string, diperlukan)
    • profile_id: ID profil publikasi (mis. UUID). (string, diperlukan)
    • page: Nomor halaman untuk versi aplikasi (berbasis 1). Default: 1. (angka, opsional)
    • size: Ukuran halaman untuk versi aplikasi (1-100). Default: 25, maks 100. (angka, opsional)
Toko Aplikasi Perusahaan

  • get_store_profiles - Dapatkan profil toko aplikasi perusahaan untuk organisasi saat ini (dipaginasi).

    • Tingkat akses: baca
    • page: Nomor halaman (berbasis 1). Default: 1. (angka, opsional)
    • size: Ukuran halaman (1-100). Default: 25, maks 100. (angka, opsional)

  • get_store_profile_details - Dapatkan satu profil toko aplikasi perusahaan berdasarkan ID (dengan paginasi versi aplikasi opsional).

    • Tingkat akses: baca
    • profile_id: ID profil toko aplikasi perusahaan (mis. UUID). (string, diperlukan)
    • page: Nomor halaman untuk versi aplikasi (berbasis 1). Default: 1. (angka, opsional)
    • size: Ukuran halaman untuk versi aplikasi (1-100). Default: 25, maks 100. (angka, opsional)
Laporan - **get_build_history_report** - Dapatkan laporan riwayat build, opsional difilter berdasarkan rentang tanggal, profil build, dan organisasi. Dipaginasi. - **Tingkat akses:** baca - `start_date`: Tanggal mulai opsional (YYYY-MM-DD). (string, opsional) - `end_date`: Tanggal akhir opsional (YYYY-MM-DD). (string, opsional) - `page`: Nomor halaman (default: 1). (number, opsional) - `size`: Item per halaman (1-100, default: 50). (number, opsional) - `build_profile_name`: Filter berdasarkan nama profil build. (string, opsional) - `organization_id`: Filter berdasarkan UUID organisasi. (string, opsional)

  • get_build_insights_report - Dapatkan Laporan Wawasan Build yang terkomputasi (Snapshot Kesehatan + Tren, Akar Masalah, Kesehatan Artefak, Kualitas Alur Kerja, Waktu Antrean, dan analisis Penilaian Kematangan) dari riwayat build, diagregasi di sisi server. Tidak seperti get_build_history_report, ini mengambil setiap halaman secara internal dan mengembalikan hasil pra-agregasi kecil alih-alih catatan mentah.

    • Tingkat akses: baca
    • start_date: Tanggal mulai opsional (YYYY-MM-DD) untuk periode saat ini. Default: 30 hari terakhir. (string, opsional)
    • end_date: Tanggal akhir opsional (YYYY-MM-DD) untuk periode saat ini. (string, opsional)
    • sections: Daftar opsional bagian yang akan dikomputasi: health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. Default: keenamnya. (array of strings, opsional)
    • include_sub_orgs: Jika true, simpan catatan build lintas organisasi dalam metrik turunan riwayat alih-alih memfilter ke organisasi token sendiri. Default: false. (boolean, opsional)

  • get_distribution_app_version_report - Dapatkan laporan penggunaan harian untuk versi aplikasi yang didistribusikan. Dipaginasi; mendukung filter berdasarkan profil, OS, organisasi.

    • Tingkat akses: baca
    • start_date: Tanggal mulai opsional (YYYY-MM-DD). (string, opsional)
    • end_date: Tanggal akhir opsional (YYYY-MM-DD). (string, opsional)
    • page: Nomor halaman (default: 1). (number, opsional)
    • size: Item per halaman (1-100, default: 50). (number, opsional)
    • profile_name: Filter berdasarkan nama profil distribusi. (string, opsional)
    • os: Filter berdasarkan OS ("ios" atau "android"). (string, opsional)
    • organization_id: Filter berdasarkan UUID organisasi. (string, opsional)

  • get_distribution_sent_report - Dapatkan laporan penggunaan harian untuk berbagi aplikasi yang didistribusikan. Dipaginasi; mendukung filter berdasarkan profil, OS, organisasi.

    • Tingkat akses: baca
    • start_date: Tanggal mulai opsional (YYYY-MM-DD). (string, opsional)
    • end_date: Tanggal akhir opsional (YYYY-MM-DD). (string, opsional)
    • page: Nomor halaman (default: 1). (number, opsional)
    • size: Item per halaman (1-100, default: 50). (number, opsional)
    • profile_name: Filter berdasarkan nama profil distribusi. (string, opsional)
    • os: Filter berdasarkan OS ("ios" atau "android"). (string, opsional)
    • organization_id: Filter berdasarkan UUID organisasi. (string, opsional)

  • get_enterprise_app_store_app_usage_report - Dapatkan laporan penggunaan aplikasi untuk toko aplikasi enterprise. start_date dan end_date wajib diisi. Dipaginasi.

    • Tingkat akses: baca
    • start_date: Tanggal mulai (YYYY-MM-DD). (string, wajib)
    • end_date: Tanggal akhir (YYYY-MM-DD). (string, wajib)
    • page: Nomor halaman (default: 1). (number, opsional)
    • size: Item per halaman (1-100, default: 50). (number, opsional)
    • organization_id: Filter opsional berdasarkan UUID organisasi. (string, opsional)

  • get_publish_resign_report - Dapatkan laporan resign publikasi, opsional difilter berdasarkan rentang tanggal, nama aplikasi, organisasi, dan status. Dipaginasi.

    • Tingkat akses: baca
    • start_date: Tanggal mulai opsional (YYYY-MM-DD). (string, opsional)
    • end_date: Tanggal akhir opsional (YYYY-MM-DD). (string, opsional)
    • page: Nomor halaman (default: 1). (number, opsional)
    • size: Item per halaman (1-100, default: 50). (number, opsional)
    • app_name: Filter berdasarkan nama aplikasi. (string, opsional)
    • organization_id: Filter berdasarkan UUID organisasi. (string, opsional)
    • status: Filter berdasarkan status resign (0=menunggu, 1=memproses, 2=berhasil, 3=gagal, 4=dibatalkan, 5=waktu habis). (number, opsional)

  • get_publish_status_report - Dapatkan laporan status publikasi, opsional difilter berdasarkan rentang tanggal, nama aplikasi, organisasi, dan status. Dipaginasi.

    • Tingkat akses: baca
    • start_date: Tanggal mulai opsional (YYYY-MM-DD). (string, opsional)
    • end_date: Tanggal akhir opsional (YYYY-MM-DD). (string, opsional)
    • page: Nomor halaman (default: 1). (number, opsional)
    • size: Item per halaman (1-100, default: 50). (number, opsional)
    • app_name: Filter berdasarkan nama aplikasi. (string, opsional)
    • organization_id: Filter berdasarkan UUID organisasi. (string, opsional)
    • status: Filter berdasarkan status publikasi (mis. 0=Sukses, 1=Gagal, 91=Berjalan). (number, opsional)

  • get_signing_report - Dapatkan laporan signing, opsional difilter berdasarkan rentang tanggal, organisasi, OS, dan status build. Dipaginasi.

    • Tingkat akses: baca
    • start_date: Tanggal mulai opsional (YYYY-MM-DD). (string, opsional)
    • end_date: Tanggal akhir opsional (YYYY-MM-DD). (string, opsional)
    • page: Nomor halaman (default: 1). (number, opsional)
    • size: Item per halaman (1-100, default: 50). (number, opsional)
    • organization_id: Filter berdasarkan UUID organisasi. (string, opsional)
    • os: Filter berdasarkan OS ("ios" atau "android"). (string, opsional)
    • build_status: Filter berdasarkan status build (mis. 0=Sukses, 1=Gagal, 91=Berjalan). (number, opsional)

Menjalankan server

Dari root repo:

python -m src.server

Atau setelah pip install -e .:

appcircle-mcp

Server berjalan melalui stdio (atau SSE/HTTP tergantung bagaimana klien Anda memulainya).

Format respons

Setiap alat mengembalikan amplop standar:

  • Sukses: { "success": true, "data": <payload>, "meta": { ... } }
    data adalah hasil alat; meta bersifat opsional (mis. count, page, filters).
  • Error: { "success": false, "error": { "tool", "type", "message", "details" } }
    Bentuk yang sama untuk semua alat sehingga klien dapat mengurai error secara konsisten.

Spesifikasi lengkap: docs/tool_contract.md.

Pengujian

Instal dengan dependensi pengembangan:

pip install -e ".[dev]"

Pengujian unit (default)

Gunakan API tiruan; tidak memerlukan APPCIRCLE_ACCESS_TOKEN. Default pytest hanya menjalankan ini (lihat testpaths di pyproject.toml):

pytest test/unit/ -v
  • File tunggal: pytest test/unit/tools/build_module/test_get_build_profiles.py -v
  • Dengan cakupan: pytest test/unit/ --cov=src --cov-report=term-missing

Pengujian integrasi

Panggil API Appcircle asli. Atur APPCIRCLE_ACCESS_TOKEN di environment, lalu jalankan:

pytest test/integration/ -v
  • Semua pengujian integrasi: pytest test/integration/ -v
  • Berdasarkan alat: pytest test/integration/build_module/ -v, pytest test/integration/report/ -v, dll.
  • Berdasarkan penanda: pytest -m integration -v (saat dijalankan dari root repo; hanya menyertakan pengujian integrasi jika pengujian unit dan integrasi dikumpulkan)

Jika APPCIRCLE_ACCESS_TOKEN tidak diatur, pengujian integrasi akan dilewati (tidak gagal).

Variabel env opsional untuk pengujian integrasi (saat penemuan gagal atau pengujian memerlukan ID asli; abaikan untuk melewati pengujian tersebut):

VariabelDeskripsi
APPCIRCLE_TEST_ORGANIZATION_IDUUID Organisasi. Digunakan oleh test_with_organization_id (laporan penggunaan aplikasi toko aplikasi enterprise).
APPCIRCLE_TEST_BRANCH_IDUUID Cabang. Digunakan oleh get_commits_by_branch dan pengujian terkait saat tidak ada cabang yang dapat ditemukan dari API.
APPCIRCLE_TEST_COMMIT_IDUUID Komit. Digunakan oleh pengujian get_commit_details saat tidak ada komit yang dapat ditemukan dari API.

Keamanan

Proyek ini bergantung pada paket sumber terbuka pihak ketiga yang tercantum di pyproject.toml. Meskipun kami menetapkan rentang versi dependensi dan menyertakan lockfile (uv.lock) dengan hash kriptografis, paket-paket ini dikelola secara independen dan disediakan "apa adanya." Appcircle tidak memberikan jaminan mengenai keamanan atau keandalan dependensi pihak ketiga.

Kami merekomendasikan untuk mengaudit paket yang terinstal sebelum digunakan:

uv run pip-audit