@illestcore/mcp — Illestcore 公式 MCP サーバ

Illestcore（ILLEST CORE）の Client API（/client_api/v1）を MCP ツールとして提供します。Claude / Cursor などの AI クライアントから、広告トラッキングデータの参照と日次オペレーションができます。

設計原則

このサーバは権限・データの新しい面を作りません。 認証・認可（endpoint 単位の read/write 許可）・テナント分離・IP 制限・レート制限・監査・冪等性は、すべて Client API 側がサーバサイドで強制します。@illestcore/mcp はその薄い変換層であり、API キーの権限で見えるもの・できることが MCP でもそのまま上限になります。

• ツールはキー権限で動的フィルタ: 許可された範囲のツールだけを AI クライアントに見せます
• 書き込みは実行前確認: 変更内容の要約を提示し、ユーザー承認後に実行します（確認 UI 非対応クライアントは confirmed: true 引数で明示実行）
• 冪等性: 書き込みには Idempotency-Key を自動付与（同一ツール + 同一引数 → 同一キー）。エージェントの自動リトライで二重実行されません。同一内容の再実行は初回結果の再掲（idempotency_replayed: true）になります — 意図的に同じ内容をもう一度実行したい場合は引数を変えるか 24 時間空けてください
• API キーはログ・エラーメッセージに一切出しません

利用の前提

• Node.js 20 以上（npx を使うため。未導入の場合は nodejs.org から LTS 版をインストール）
• Client API の利用が有効なこと: API アクセスの有効化・権限設定は ILLEST 側での事前設定が必要です（未設定のキーは 403 になります）
• API キー: ILLEST CORE 管理画面（基本設定 > クライアントAPI・MCP）で発行します。キー入りの設定スニペットは発行直後の画面からコピーできます

セットアップ

Claude Desktop / Cursor / Claude Code などの MCP 設定（mcpServers）に追加します:

{
  "mcpServers": {
    "illestcore": {
      "command": "npx",
      "args": ["-y", "@illestcore/mcp"],
      "env": {
        "IC_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

環境変数:

| 変数 | 説明 | |---|---| | IC_API_KEY | 必須。Client API キー | | IC_API_BASE | 任意。既定 https://api.ilco.io/client_api/v1 |

MCP の利用可否は API と同一の権限に従属します（MCP 固有の課金・権限はありません）。運用側は api_access 設定の "mcp": false で該当プロダクトの MCP 利用を停止できます（既定は有効。起動時に /me の mcp_enabled で判定）。

ツール一覧

| ツール | 種別 | 内容 | |---|---|---| | ic_get_account | read | 疎通確認・キー権限の取得（常時） | | ic_list_ads | read | 広告マスタ（一覧・単体） | | ic_list_masters | read | asps / ad_categories / ad_types / cv_settings / redirects | | ic_search_logs | read | アクセス / クリック / CV / 成果通知 / リジェクト / Webhook キュー | | ic_search_cv_details | read | 中間CV / CV接触履歴（アトリビューション） / オフラインCV原本 | | ic_get_performance | read | 日次集計 / 月次実績・LTV / 顧客帰属 | | ic_get_adsync_data | read | 媒体連携実績（Google/Yahoo/Meta 等） | | ic_get_budgets_costs | read | 広告予算・広告費（月次/日次） | | ic_get_line_friends | read | LINE 友だち計測 | | ic_register_ad | write | 広告の新規登録 | | ic_update_ad | write | 広告の部分更新 | | ic_manage_masters | write | 設定マスタの作成・更新 | | ic_upsert_budget_cost | write | 予算・費用の登録・更新 | | ic_approve_result | write | 成果通知の承認/非承認（金銭直結） | | ic_import_conversion | write | オフライン CV の後追い登録 | | ic_api_request | 汎用 | Client API への生リクエスト（保険・上級者向け） |

ログの保持期間

計測ログ・CV 詳細（ic_search_logs / ic_search_cv_details）は保持期間内しか取得できません（既定 12 か月 + 猶予 1 か月。プランにより 6 か月 + 1）。保持期間より前を指定してもエラーにはならず、下限が自動で丸められます（レスポンスヘッダ X-Log-Retention-Clamped: 1、実際の下限は X-Log-Retention-From）。取得できる期間は ic_get_account の log_retention_days（日数）/ log_retention_months（月数）で確認できます。

保持期間より前の分析には集計系（ic_get_performance の ad_summaries / ad_performances / customer_attributions）をご利用ください。集計はこの制限を受けません。

ページングと page_size

一覧系はカーソルページングです（レスポンスの next_cursor を cursor 引数に渡すと続きが取れます）。page_size は 既定 20・MCP 経由の上限は 1,000（超過はエラーにせず 1,000 に丸め）。大きなレスポンスは AI の文脈を圧迫するため、MCP 経由では 1,000 を上限にしています。既定を小さくしているのも同じ理由で、必要に応じて大きな page_size を指定できます。生 API を直接ご利用の場合の上限は ic_get_api_spec（API 仕様）が返す値をご確認ください。

ナレッジ層（AI が IC を理解するための同梱ドキュメント）

knowledge/ を MCP resources（ic://knowledge/*）と ic_explain（検索）・ic_get_api_spec（endpoint 仕様）で配信します。

• コード値辞書・endpoint 索引・API 仕様（サーバ実装から機械生成し、CI で乖離を検知）
• データモデル（計測フロー）と指標定義（「CV数」の3解釈など）の監修つき解説
• よくある誤り・つまずき集（ic://knowledge/typical-mistakes）— 「CPA が出ない」「数字が合わない」の原因と確認手順
• 月次レポート / 未承認棚卸し / 計測不調切り分けの MCP prompts

検索は見出しセクション単位の BM25（日本語は文字 bigram で近似）で、外部への問い合わせは発生しません。すべてパッケージ同梱のため、オフラインでも同じ内容が引けます。

プロトコル互換性

MCP TypeScript SDK v2（spec 2026-07-28 世代）で実装。ツールは modern 流儀（MRTR / inputRequired パターン）で書かれており、旧世代クライアント（2025-11-25 以前）には SDK が elicitation/create へ自動ブリッジします。トランスポートは stdio（リモート提供は将来対応予定）。

更新履歴

npx -y @illestcore/mcp は AI クライアントの起動時に最新版を取得します。更新を反映するには AI クライアントを再起動してください（バージョンを固定している場合は固定を外してください）。

• 0.2.3 — 広告月次実績（ad_performances）に追加された新規/既存の評価の 6 列（cohort_last_amount_* / cohort_acq_amount）の意味と計算式を、ナレッジと API 仕様に追加。運営向けの機能を追加（一般のキーでは動作に変化なし）
• 0.2.2 — 計測ログ・CV詳細の保持期間（既定 12 か月 + 猶予 1 か月）の案内を追加: 保持期間より前を指定すると下限が自動で丸められること、ic_get_account の log_retention_days で下限を確認できること、保持期間より前の分析は集計系を使うことを、ツールの説明とナレッジ（よくある誤り・つまずき集）に追加。ic_search_cv_details に CV 発生日時での絞り込み（conversion_created_at_from / conversion_created_at_to）を追加
• 0.2.1 — 配布物に含まれていた未使用ファイル（dist/http.js / dist/cli.js）を除去。ビルド時に dist/ を掃除するよう修正（動作の変更なし）
• 0.2.0 — ナレッジ層を拡充: 「よくある誤り・つまずき集」（ic://knowledge/typical-mistakes）を同梱し、ic_explain の検索を BM25 に改善（日本語の検索精度を改善）。
• 0.1.3 — page_size の上限を 100 → 1,000 に拡大（既定 20 は据え置き）。起動失敗時（キー未設定・401・403）に Windows で発生していた終了時のアサーションを修正。全リクエストに User-Agent: ic-mcp/<version> を付与。生ログ取得の前に集計系を検討するよう AI への指示を追加
• 0.1.2 — 起動失敗時のエラーメッセージが出力されないことがある問題を修正。page_size の上限超過をエラーにせず丸めるように変更
• 0.1.1 — ナレッジのコード値辞書を修正（result_method の値を復元）
• 0.1.0 — 初回公開

ライセンス

Apache-2.0 © SQULD Inc.