Appcircle MCP Server

公式

Appcircleの公式MCPサーバー

Appcircle MCPで何ができますか?

  • ビルドステータスとログの監視get_build_statusget_build_logs を使用して、パイプラインの実行を確認し、失敗をデバッグします。
  • ビルドのトリガーまたはキャンセルtrigger_buildcancel_build を使用して、実際のビルド実行を開始または停止します。
  • CI/CD ヘルスインサイトの生成get_build_insights_report を使用して、集約されたヘルススナップショット、トレンド、根本原因分析を取得します。
  • テスト配布の管理get_distribution_profilessend_app_version_to_testers を使用して、ビルドをテスターに送信します。
  • 署名 ID の検査get_certificatesget_keystoresget_provisioning_profiles を使用して、署名設定を確認します。
  • ストア公開の追跡get_publish_profilesget_publish_details を使用して、公開フローの実行を監視します。

ドキュメント

Appcircle MCP Server

Appcircle 用の MCP サーバー:ビルド、署名 ID、テスト配布、エンタープライズアプリストア、ストアへの公開、レポートツールを、MCP 対応クライアント(Claude Desktop、Cursor、VS Code など)に公開します。Appcircle MCP Server は AI ツールと Appcircle の間のブリッジとして機能し、AI エージェント、アシスタント、チャットボットが、構造化・管理されたタスクレベルのツールを通じて Appcircle リソースに安全にアクセスし、操作できるようにします。

ユースケース

  • CI/CD とワークフローインテリジェンス:パイプライン実行の監視、リリースステータスの追跡、モバイル CI/CD ワークフローに関するインサイトの取得。
  • 設定と環境インサイト:ビルド構成と署名設定を照会し、プロジェクトがどのように構成されているか、問題がどこから発生するかを理解します。
  • レポートと運用インサイト:CI 安定性、繰り返し発生する問題、パイプライン性能、CI/CD 全体の健全性に関するサマリーを生成します。

実行モード

MCP サーバーは 4 つの方法で使用できます:

モード概要
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 Applications - Claude Desktop および Claude Code CLI のインストールガイド。
  • Cursor IDE - Cursor IDE のインストールガイド。
  • Codex - Codex アプリおよび Codex CLI のインストールガイド。
  • Antigravity IDE - Antigravity IDE のインストールガイド。
  • VS Code (GitHub Copilot) - GitHub Copilot を使用した VS Code のインストールガイド。
  • Windsurf IDE - Windsurf IDE のインストールガイド。
  • Gemini CLI - Gemini CLI のインストールガイド。
  • GitHub Copilot CLI - GitHub Copilot CLI のインストールガイド。

設定(環境変数)

変数必須説明
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 ヘッダーを受け入れるようにします。localhost の場合は省略します。
APPCIRCLE_MCP_PORTいいえ (streamable-http のみ)HTTP サーバーのバインドポート(デフォルト:8000)。--port が指定されている場合は上書きされます。オンプレミスや Docker で特定のポートが必要な場合に便利です。
LOG_LEVELいいえロギングレベル。例:DEBUGINFO(デフォルト:INFO)。
APPCIRCLE_EXCLUDED_TOOLSETSいいえ除外するツールセットのカンマ区切りリスト(例:build_module,report)。下記のツールセットを参照してください。
AC_MCP_ENABLE_WRITE_TOOLSいいえ書き込み/アクションツール(例:trigger_buildcancel_build)はデフォルトで登録されます。false/0/no/off に設定すると、オプトアウトして登録しません(呼び出し時に無効にするだけでなく、まったく登録しません)。

これらはシェルまたは MCP クライアントの設定で設定します。

ツールセット

利用可能なツールセット

以下のツールセットが利用可能です:

ツールセット説明
build_moduleビルドプロファイル、構成、ワークフロー、コミット、パイプライン操作
signing_identities署名 ID とバンドル識別子
testing_distributionテスト配布プロファイルと配布詳細
publish_to_stores公開プロファイルとストア公開操作
enterprise_app_storeエンタープライズアプリストアプロファイルとストア詳細
reportレポート:ビルド履歴、配布、署名、公開ステータス、および関連レポート

1 つ以上のツールセットを除外して、そのツールが登録されないようにできます。除外は 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: プロファイルをフィルタリングする任意の検索語(プロファイル名の大文字小文字を区別しない部分一致。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=昇順、2=降順。(数値、任意)
  • 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: 出力を 1 つのステップのログブロックに限定する任意の正確なステップ名(大文字小文字を区別しません)。(文字列、任意)
    • full_log: true の場合、デフォルトの末尾ではなく全ログを返します。それでも 256 KB で上限されます。デフォルト:false。(ブール値、任意)
    • tail_lines: full_log を使用しない場合に末尾から保持する行数。デフォルト:200、最大 1000。(数値、任意)
    • grep: 切り詰め前に各行に適用される大文字小文字を区別しない部分文字列フィルター。(文字列、任意)
  • get_variable_groups - 組織のすべてのビルド環境変数グループを取得します。各グループの変数(キー、値、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(trigger_build が返す「taskId」フィールド)。(文字列、必須)
署名 ID
  • get_bundle_identifiers - 組織のすべてのバンドル識別子(iOS/macOS アプリのバンドル ID)を取得します。

    • アクセスレベル: 読み取り
    • パラメータなし。
  • get_certificates - 組織のすべての署名証明書を取得します。機密フィールド(p12Password、p12Binary、metaData、thumbprint)は省略されます。

    • アクセスレベル: read
    • パラメータなし。
  • get_keystores - 組織のすべてのキーストアを取得します(例: Android署名キーストア)。機密フィールド(password、aliasPassword、binary、checkSum、sha256FingerPrint)は省略されます。

    • アクセスレベル: read
    • パラメータなし。
  • get_provisioning_profiles - 組織のプロビジョニングプロファイルを取得します(例: iOS/macOS)。機密/大容量フィールド(binary、metaData、certificateThumbPrints、provisionedDevices、connectApiKeyId)は省略されます。オプションでアプリ(バンドル)IDによるフィルタリングが可能です。

    • アクセスレベル: read
    • app_id: プロビジョニングプロファイルをフィルタリングするためのオプションのアプリ(バンドル)ID(例: com.example.app)。(string、任意)
テスト配布
  • get_distribution_profiles - 現在の組織のテスト配布プロファイルを取得します(ページング対応)。オプションでプロファイル名、プラットフォーム、認証タイプによるフィルタリングが可能です。オプションで並べ替えも可能です。

    • アクセスレベル: read
    • page: ページ番号(1始まり)。デフォルト: 1。(number、任意)
    • size: ページサイズ(1〜100)。デフォルト: 25、最大100。(number、任意)
    • search: プロファイルをフィルタリングするためのオプションの検索語(プロファイル名に対する大文字小文字を区別しない部分一致。APIの検索は他のプロファイルフィールドにも一致する場合があります)。(string、任意)
    • platform: フィルタリングするオプションのプラットフォームコードのリスト。許可値: 1=iOS、2=Android。(数値のリスト、任意)
    • authentication_type: フィルタリングするオプションの認証タイプコードのリスト。許可値: 1=None、3=静的ログイン、4=LDAP、5=SSO。(数値のリスト、任意)
    • sort: オプションの並べ替えフィールドコード。許可値: 1=プロファイル名、2=作成日、3=最終アップロード日。(number、任意)
    • sort_direction: オプションの並べ替え方向コード。許可値: 1=昇順、2=降順。(number、任意)
  • get_distribution_profile_details - IDで単一のテスト配布プロファイルを取得します(オプションでアプリバージョンのページング付き)。

    • アクセスレベル: read
    • profile_id: 配布プロファイルID(例: UUID)。(string、必須)
    • page: アプリバージョンのページ番号(1始まり)。デフォルト: 1。(number、任意)
    • size: アプリバージョンのページサイズ(1〜100)。デフォルト: 25、最大100。(number、任意)
  • get_testing_groups - 組織のすべてのテスト配布グループを取得します。各グループのメンバーテスターのメールアドレスとグループタイプも含まれます。

    • アクセスレベル: read
    • パラメータを受け取りません。
  • update_app_version_release_notes - 副作用: 配布アプリバージョンのテスターに表示されるリリースノート(「message」)を上書きします。 更新されたアプリバージョンオブジェクトを返します(certThumbPrintsは除外)。デフォルトで登録されています。オプトアウトするには AC_MCP_ENABLE_WRITE_TOOLS=false を設定します。

    • アクセスレベル: write
    • profile_id: 配布プロファイルID(例: UUID)。(string、必須)
    • app_version_id: アプリバージョンID(例: UUID)。(string、必須)
    • message: 新しいリリースノートのテキスト。(string、必須)
  • send_app_version_to_testers - 副作用: テスター/テストグループに実際の通知を送信し、特定のアプリバージョンの配布タスクを開始します。 デフォルトで登録されています。オプトアウトするには AC_MCP_ENABLE_WRITE_TOOLS=false を設定します。

    • アクセスレベル: write
    • profile_id: 配布プロファイルID(例: UUID)。(string、必須)
    • app_version_id: アプリバージョンID(例: UUID)。(string、必須)
    • message: テスターに表示される通知メッセージ。(string、必須)
    • testers: 送信先のテスターのリスト。各エントリはテスターのメールアドレスまたはテストグループID(get_testing_groups の「id」フィールド)です。(文字列のリスト、必須)
ストアへの公開
  • get_publish_profiles - 指定されたプラットフォームタイプの現在の組織の公開プロファイルを取得します(ページング対応)。オプションでフローステータス、対象マーケットプレイス、リリース候補バイナリの有無、ストアステータスによるフィルタリングが可能です。オプションで並べ替えも可能です。

    • アクセスレベル: read
    • platform_type: 公開プロファイルのプラットフォームタイプ(「ios」または「android」)。(string、必須)
    • page: ページ番号(1始まり)。デフォルト: 1。(number、任意)
    • size: ページサイズ(1〜100)。デフォルト: 25、最大100。(number、任意)
    • flow_status: フィルタリングするオプションのフローステータスコード(例: 0=成功、1=失敗、91=実行中)。(number、任意)
    • market_place_type: フィルタリングするオプションの対象マーケットプレイスコードのリスト。許可値は platform_type によって異なります -- ios: 0=利用不可、1=App Store Connect、4=Intune; android: 0=利用不可、2=Google Play、3=AppGallery、4=Intune。(数値のリスト、任意)
    • has_rc_binary: プロファイルにリリース候補バイナリがあるかどうかのオプションのフィルター。(boolean、任意)
    • store_status: フィルタリングするオプションのストアステータスコードのリスト。許可値は platform_type によって異なります(ios の方が android より多くのコードがあります。例: ios: "IN_REVIEW"、"READY_FOR_SALE"、"REJECTED"; android: "NOT_AVAILABLE"、"DRAFT"、"IN_PROGRESS"、"HALTED"、"COMPLETED")。(文字列のリスト、任意)
    • sort: オプションの並べ替えフィールドコード。許可値: 1=プロファイル名、2=作成日。(number、任意)
    • sort_direction: オプションの並べ替え方向コード。許可値: 1=昇順、2=降順。(number、任意)
  • get_publish_profile_details - プラットフォームタイプとIDで単一の公開プロファイルを取得します(オプションでアプリバージョンのページング付き)。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • page: アプリバージョンのページ番号(1始まり)。デフォルト: 1。(number、任意)
    • size: アプリバージョンのページサイズ(1〜100)。デフォルト: 25、最大100。(number、任意)
  • get_app_version_metadata - 単一のアプリバージョンのストア掲載メタデータを取得します(アプリレビュー情報、ローカリゼーション、リリース情報、アプリバージョン情報)。appReviewInformation.demoPassword は除外されます。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • app_version_id: アプリバージョンID(例: UUID)。(string、必須)
  • get_metadata_locales - 単一のアプリバージョンで利用可能なストアメタデータのロケールを取得します(name、code、localized、isPrimary)。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • app_version_id: アプリバージョンID(例: UUID)。(string、必須)
  • get_intune_metadata - 単一のアプリバージョンの Microsoft Intune アプリメタデータを取得します(表示名、発行元、バンドルID、バージョン、公開状態、対応デバイスタイプ、カテゴリなど)。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • app_version_id: アプリバージョンID(例: UUID)。(string、必須)
  • get_publish_metadata_lock_status - 公開プロファイルのストアメタデータが編集のためにロックされているかどうかを取得します。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
  • get_publish_details - 単一のアプリバージョンの公開フロー実行の詳細を取得します(ステータス、タイミング、実行履歴/アーティファクト/ログリソースIDを含む順序付きステップ)。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • app_version_id: アプリバージョンID(例: UUID)。(string、必須)
  • get_publish_step_logs - 公開フロー実行のログを取得します。オプションで単一のステップに限定できます。モデルのコンテキストを圧迫しないよう、デフォルトでは末尾切り詰め表示になります。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • publish_id: 公開フロー実行ID(get_publish_details の「id」フィールド)。(string、必須)
    • step_id: ステップID(get_publish_details の steps リストのステップの「id」フィールド)。(string、必須)
    • step: 出力を1つのステップのログブロックに限定するためのオプションの正確なステップ名(大文字小文字を区別しない)。(string、任意)
    • full_log: true の場合、デフォルトの末尾ではなくログ全体を返します。それでも256 KBに上限があります。デフォルト: false。(boolean、任意)
    • tail_lines: full_log を使用しない場合に末尾から保持する行数。デフォルト: 200、最大1000。(number、任意)
    • grep: 切り詰め前に各行に適用される大文字小文字を区別しない部分文字列フィルター。(string、任意)
  • get_publish_flows - 公開プロファイルに設定されている公開フローを取得します(名前、ID、完全なフロードキュメントYAML)。

    • アクセスレベル: read
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
  • start_publish - 副作用: 公開フロー実行を開始します(または特定のステップから再開します)-- 実際の公開作業(例: App Store/Play Store/Intune へのアップロード)を行います。デフォルトで登録されています。オプトアウトするには AC_MCP_ENABLE_WRITE_TOOLS=false を設定します。

    • アクセスレベル: write
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • publish_id: 公開フロー実行ID(get_publish_details の「id」フィールド)。(string、必須)
    • step_id: フローの最初ではなくそのステップから開始するためのオプションのステップID。(string、任意)
    • organization_pool_id: 実行するオプションの組織プールID(例: UUID)。(string、任意)
  • stop_publish - 副作用: 実行中の公開フロー実行をキャンセルします(実際の進行中の作業が停止され、再開できません)。デフォルトで登録されています。オプトアウトするには AC_MCP_ENABLE_WRITE_TOOLS=false を設定します。

    • アクセスレベル: write
    • platform_type: プラットフォームタイプ(「ios」または「android」)。(string、必須)
    • profile_id: 公開プロファイルID(例: UUID)。(string、必須)
    • publish_id: 公開フロー実行ID(get_publish_details の「id」フィールド)。(string、必須)
    • step_id: オプションのステップID。(string、任意)
    • organization_pool_id: オプションの組織プールID(例: UUID)。(string、任意)
エンタープライズアプリストア
  • get_store_profiles - 現在の組織のエンタープライズアプリストアプロファイルを取得します(ページング対応)。検索はサポートされていませんが、プラットフォーム、公開タイプ、可視性によるフィルタリングが可能です。オプションで並べ替えも可能です。
    • アクセスレベル: read
    • page: ページ番号(1始まり)。デフォルト: 1。(number、任意)
    • size: ページサイズ(1〜100)。デフォルト: 25、最大100。(number、任意)
    • platform_type: フィルタリングするオプションのプラットフォームコードのリスト。許可値: 1=iOS、2=Android。(数値のリスト、任意)
    • publish_type: フィルタリングするオプションの公開タイプコードのリスト。許可値: 1=ベータ版に公開、2=本番に公開。(数値のリスト、任意)
    • visibility: プロファイルが公開リストに含まれるかどうかのオプションのフィルター(true=公開、false=非公開)。(boolean、任意)
    • sort: オプションの並べ替えフィールドコード。許可値: 1=アプリ名、2=作成日、3=ダウンロード数、4=バイナリ受信日。(number、任意)
    • sort_direction: オプションの並べ替え方向コード。許可値: 1=昇順、2=降順。(number、任意)
  • get_store_profile_details - IDで単一のエンタープライズアプリストアプロフィールを取得します(オプションでアプリバージョンのページネーション付き)。
    • アクセスレベル: 読み取り
    • profile_id: エンタープライズアプリストアのプロフィールID(例: UUID)。(文字列、必須)
    • page: アプリバージョンのページ番号(1始まり)。デフォルト: 1。(数値、オプション)
    • size: アプリバージョンのページサイズ(1〜100)。デフォルト: 25、最大100。(数値、オプション)
    • 各アプリバージョンのpublishTypeフィールドは整数です: 0=None、1=Beta、2=Live。
レポート
  • get_build_history_report - ビルド履歴レポートを取得します。日付範囲、ビルドプロファイル、組織でオプションでフィルタリング可能。ページネーション対応。

    • アクセスレベル: 読み取り
    • start_date: オプションの開始日(YYYY-MM-DD)。(文字列、オプション)
    • end_date: オプションの終了日(YYYY-MM-DD)。(文字列、オプション)
    • page: ページ番号(デフォルト: 1)。(数値、オプション)
    • size: 1ページあたりの項目数(1〜100、デフォルト: 50)。(数値、オプション)
    • build_profile_name: ビルドプロファイル名でフィルタリング。(文字列、オプション)
    • organization_id: 組織UUIDでフィルタリング。(文字列、オプション)
  • get_build_queue_waiting_report - ビルドキューの待機レポートを取得します。日付範囲でオプションでフィルタリング可能。ページネーション対応。注: このエンドポイントでは、buildDurationは実行時間ではなくキュー待機時間(分)を意味します(get_build_history_reportとは異なります)。

    • アクセスレベル: 読み取り
    • start_date: オプションの開始日(YYYY-MM-DD)。両方が指定されている場合はend_date以下である必要があります。(文字列、オプション)
    • end_date: オプションの終了日(YYYY-MM-DD)。(文字列、オプション)
    • page: ページ番号(デフォルト: 1)。(数値、オプション)
    • size: 1ページあたりの項目数(1〜100、デフォルト: 50)。(数値、オプション)
  • get_build_activity_log - ビルドアクティビティログ(ワークフロー/プロフィール変更、CodePushリリースなど)を取得します。日付範囲やその他のパラメータでオプションでフィルタリング可能。ページネーション対応。

    • アクセスレベル: 読み取り
    • start_date: オプションの開始日(YYYY-MM-DD)。両方が指定されている場合はend_date以下である必要があります。(文字列、オプション)
    • end_date: オプションの終了日(YYYY-MM-DD)。(文字列、オプション)
    • page: ページ番号(デフォルト: 1)。(数値、オプション)
    • size: 1ページあたりの項目数(1〜100、デフォルト: 50)。(数値、オプション)
    • organization_id: 組織UUIDでフィルタリング。(文字列、オプション)
    • platform: プラットフォームタイプでフィルタリング(整数コード、例: 0=Android、1=iOS)。(数値、オプション)
    • email: 操作ユーザーのメールアドレスでフィルタリング。(文字列、オプション)
    • profile_name: ビルドプロファイル名でフィルタリング。(文字列、オプション)
    • action: アクティビティアクションコードでフィルタリング(整数。完全なマッピングはツールソース内のBUILD_ACTIVITY_ACTIONSを参照)。(数値、オプション)
  • get_build_insights_report - ビルド履歴に基づいて算出されたビルドインサイトレポート(ヘルススナップショット+トレンド、根本原因、アーティファクトヘルス、ワークフロー品質、キュー時間、成熟度評価分析)を取得します。サーバー側で集計されます。get_build_history_reportとは異なり、このツールは内部で全ページを取得し、生レコードではなく小さな事前集計結果を返します。

    • アクセスレベル: 読み取り
    • start_date: 現在の期間のオプションの開始日(YYYY-MM-DD)。デフォルト: 過去30日間。(文字列、オプション)
    • end_date: 現在の期間のオプションの終了日(YYYY-MM-DD)。(文字列、オプション)
    • sections: 計算するオプションのセクションリスト: health_snapshotroot_causeartifact_healthworkflow_qualityqueue_timematurity_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ページあたりの項目数(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ページあたりの項目数(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ページあたりの項目数(1〜100、デフォルト: 50)。(数値、オプション)
    • organization_id: 組織UUIDによるオプションのフィルタリング。(文字列、オプション)
  • get_publish_resign_report - パブリッシュ再署名レポートを取得します。日付範囲、アプリ名、組織、ステータスでオプションでフィルタリング可能。ページネーション対応。

    • アクセスレベル: 読み取り
    • start_date: オプションの開始日(YYYY-MM-DD)。(文字列、オプション)
    • end_date: オプションの終了日(YYYY-MM-DD)。(文字列、オプション)
    • page: ページ番号(デフォルト: 1)。(数値、オプション)
    • size: 1ページあたりの項目数(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ページあたりの項目数(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ページあたりの項目数(1〜100、デフォルト: 50)。(数値、オプション)
    • organization_id: 組織UUIDでフィルタリング。(文字列、オプション)
    • os: OSでフィルタリング("ios"または"android")。(文字列、オプション)
    • build_status: ビルドステータスでフィルタリング(例: 0=成功、1=失敗、91=実行中)。(数値、オプション)
  • get_signing_activity_log - 署名アクティビティログ(証明書/プロビジョニングプロフィール/キーストアの有効期限通知など)を取得します。日付範囲やその他のパラメータでオプションでフィルタリング可能。ページネーション対応。

    • アクセスレベル: 読み取り
    • start_date: オプションの開始日(YYYY-MM-DD)。両方が指定されている場合はend_date以下である必要があります。(文字列、オプション)
    • end_date: オプションの終了日(YYYY-MM-DD)。(文字列、オプション)
    • page: ページ番号(デフォルト: 1)。(数値、オプション)
    • size: 1ページあたりの項目数(1〜100、デフォルト: 50)。(数値、オプション)
    • organization_id: 組織UUIDでフィルタリング。(文字列、オプション)
    • platform: プラットフォームでフィルタリング(例: "iOS"、"Android")。(文字列、オプション)
    • email: 操作ユーザーのメールアドレスでフィルタリング。(文字列、オプション)
    • action: アクティビティアクションコードでフィルタリング(整数。完全なマッピングはツールソース内のSIGNING_ACTIVITY_ACTIONSを参照)。(数値、オプション)
  • get_publish_activity_log - パブリッシュアクティビティログ(再署名、パブリッシュフローイベントなど)を取得します。日付範囲やその他のパラメータでオプションでフィルタリング可能。ページネーション対応。

    • アクセスレベル: 読み取り
    • start_date: オプションの開始日(YYYY-MM-DD)。両方が指定されている場合はend_date以下である必要があります。(文字列、オプション)
    • end_date: オプションの終了日(YYYY-MM-DD)。(文字列、オプション)
    • page: ページ番号(デフォルト: 1)。(数値、オプション)
    • size: 1ページあたりの項目数(1〜100、デフォルト: 50)。(数値、オプション)
    • organization_id: 組織UUIDでフィルタリング。(文字列、オプション)
    • platform: プラットフォームでフィルタリング(例: "iOS"、"Android")。(文字列、オプション)
    • 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はオプションです(例: countpagefilters)。
  • エラー: { "success": false, "error": { "tool", "type", "message", "details" } }
    すべてのツールで同じ形状のため、クライアントはエラーを一貫して解析できます。

完全な仕様: docs/tool_contract.md

テスト

開発依存関係を含めてインストール:

pip install -e ".[dev]"

ユニットテスト(デフォルト)

モックされたAPIを使用します。APPCIRCLE_ACCESS_TOKENは不要です。デフォルトのpytestはこれらだけを実行します(pyproject.tomltestpathsを参照):

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/ -vpytest 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テストで使用されます。
書き込み/アクション統合テストtrigger_buildcancel_buildなど)は integration_write とマークされ、APPCIRCLE_ACCESS_TOKEN の上にオプトインです。実際のデータを変更する(実際のビルドをトリガーするなど)ため、pytest test/integration/ -v だけから実行されることはありません。有効にするには、APPCIRCLE_RUN_WRITE_INTEGRATION_TESTS=true を設定します(APPCIRCLE_ACCESS_TOKEN専用のテスト組織に向けます。本番ではありません)。

セキュリティ

このプロジェクトは、pyproject.toml に記載されたサードパーティのオープンソースパッケージに依存しています。依存関係のバージョン範囲を固定し、暗号ハッシュ付きのロックファイル(uv.lock)を提供していますが、これらのパッケージは独立して保守されており、「現状のまま」提供されます。Appcircle は、サードパーティの依存関係のセキュリティや信頼性について一切保証しません。

使用前にインストール済みパッケージを監査することをお勧めします:

uv run pip-audit