msgraph

Microsoft Graph エージェントスキル

27,700 以上ある Microsoft Graph API を検索、参照し、呼び出せます。すべてローカルで実行されるため、ネットワーク呼び出しは不要です。3 つの検索コマンドを使って適切なエンドポイントを見つけ、アクセス許可とパラメーターを確認してから、必要に応じて呼び出しを直接実行するか、Graph MCP サーバーに引き継ぎます。

含まれる内容

Microsoft Graph API には毎週更新される27,700 以上のエンドポイントがあり、LLM のトレーニングデータの対象期間を大きく超えています。このスキルには API 全体がローカルインデックスとして含まれており、ネットワーク呼び出しなしで即座に検索できます。

インデックス	件数	含まれる内容
OpenAPI エンドポイント	27,700 以上	パス、メソッド、概要、説明、アクセス許可のスコープ
エンドポイントのドキュメント	6,200 以上	アクセス許可（委任／アプリケーション）、クエリパラメーター、必須ヘッダー、既定で返されるプロパティと $select が必要なプロパティ
リソーススキーマ	4,200 以上	型を含むすべてのプロパティ、サポートされる $filter 演算子、既定で返されるか $select が必要かを示すフラグ
コミュニティサンプル	増加中	自然言語のタスクを正確な API 呼び出しに対応付けた、手動で検証済みのクエリ

実行方法

msgraph CLI はこのスキルに同梱されています。このスキルのディレクトリにあるランチャースクリプトを使って、すべてのコマンドを実行してください。

• macOS ／ Linux：bash <path-to-this-skill>/scripts/run.sh <command> [args...]
• Windows：powershell <path-to-this-skill>/scripts/run.ps1 <command> [args...]

たとえば、macOS でメール関連の API を検索するには、次のようにします。

bash /home/user/.opencode/skills/msgraph/scripts/run.sh openapi-search --query "send mail"

以下のすべての例で、msgraph はランチャーの呼び出し全体を表す省略形です。

適切な API を見つける

これがこのスキルの主な目的です。段階的な検索方法に従ってください。各段階で詳細情報が追加されます。

1. 自身の知識 — よく知られたエンドポイント（/me、/users、/groups）について、まず自身の知識を試してください。
2. sample-search — 厳選された、手動で検証済みのサンプルです。最も品質が高く、一般的なタスクや複数ステップのワークフローに使えます。
3. api-docs-search — エンドポイントごとのアクセス許可、サポートされるクエリパラメーター、必須ヘッダー、既定で返されるプロパティと $select が必要なプロパティ、フィルター演算子を含むリソースプロパティの詳細を確認できます。
4. openapi-search — 27,700 件の Graph API を網羅するカタログです。他の方法でエンドポイントを見つけられない場合に使います。
5. リファレンスファイル — クエリパラメーター、高度なクエリ、ページング、バッチ処理、スロットリング、エラー、ベストプラクティスに関する概念ドキュメントです。具体的なガイダンスが必要な場合にのみ参照してください。

この順序はあくまで目安です。タスクに応じて調整してください。たとえば、エンドポイントがすでにわかっていてアクセス許可を確認する必要がある場合は、api-docs-search に直接進んでください。

sample-search

自然言語のタスクを、正確な Microsoft Graph API クエリに対応付けた厳選済みのコミュニティサンプルを検索します。

msgraph sample-search --query "conditional access policies"
msgraph sample-search --product entra
msgraph sample-search --query "managed devices" --product intune

フラグ	説明
--query	フリーテキスト検索（意図とクエリのフィールドを検索）
--product	製品で絞り込みます：entra、intune、exchange、teams、sharepoint、security、general
--limit	最大結果数（既定値は 10）

--query または --product のいずれかが必須です。複数ステップのワークフローも結果に含まれます。

api-docs-search

特定のエンドポイントまたはリソースタイプの詳細なドキュメントを参照します。

msgraph api-docs-search --endpoint /users --method GET
msgraph api-docs-search --resource user
msgraph api-docs-search --query "ConsistencyLevel"

フラグ	説明
--endpoint	エンドポイントパスで検索します（例：/users、/me/messages）
--resource	リソースタイプ名で検索します（例：user、group、message）
--method	HTTP メソッドで絞り込みます：GET、POST、PUT、PATCH
--query	すべてのフィールドを対象にしたフリーテキスト検索
--limit	最大結果数（既定値は 10）

--endpoint、--resource、--query のいずれかが必須です。

エンドポイントの検索結果には、必須のアクセス許可（職場または学校アカウントへの委任、個人アカウントへの委任、アプリケーション）、サポートされる OData クエリパラメーター、必須ヘッダー、既定のプロパティ、エンドポイント固有の注意事項が含まれます。

リソースの検索結果には、型を含むすべてのプロパティ、サポートされる $filter 演算子（eq、ne、startsWith など）、各プロパティが既定で返されるか、$select が必要かどうかが含まれます。

openapi-search

27,700 件の Microsoft Graph API を網羅した OpenAPI カタログを検索します：

msgraph openapi-search --query "send mail"
msgraph openapi-search --resource messages --method GET

フラグ	説明
--query	フリーテキスト検索（パス、概要、説明を検索）
--resource	リソース名で絞り込みます（例：users、groups、messages）
--method	HTTP メソッドで絞り込みます
--limit	最大結果数（デフォルトは 20）

--query、--resource、--method のいずれかを指定する必要があります。

MCP サーバーでの使用

エージェントが Microsoft Graph MCP サーバー（lokka.dev など、またはその他の Microsoft Graph MCP サーバー）にアクセスできる場合は、上記の検索ツールを使って適切なエンドポイント、アクセス許可、リクエスト構文を確認し、その情報を使用して MCP サーバーで実行してください。

このモードでは、このスキルを通じた認証は不要です。このスキルはナレッジレイヤーとしてのみ機能し、認証と API の実行は MCP サーバーが処理します。

Microsoft Graph API の直接実行

Graph MCP サーバーを利用できない場合、このスキルは Microsoft 365 で認証し、Microsoft Graph API 呼び出しを直接実行できます。

認証

このツールは、環境変数から自動判定される**委任認証（ユーザー）とアプリ専用認証（アプリケーション）**に対応しています。

クイックスタート：

msgraph auth status          # check if signed in
msgraph auth signin          # sign in (opens browser) - recommended
msgraph auth signin --device-code  # sign in via device code (headless)
msgraph auth signout         # clear the session

• 委任認証（デフォルト）：対話型ブラウザーサインインを使用します。ヘッドレス環境ではデバイスコードにフォールバックします。段階的な同意に対応しており、403 が発生すると、必要なスコープで再認証して自動的に再試行します。
• アプリ専用認証：MSGRAPH_CLIENT_SECRET、MSGRAPH_CLIENT_CERTIFICATE_PATH、MSGRAPH_FEDERATED_TOKEN_FILE、または MSGRAPH_AUTH_METHOD=managed-identity が設定されている場合に自動検出されます。MSGRAPH_TENANT_ID が必要です。

証明書、マネージド ID、ワークロード ID フェデレーション、すべての環境変数を含む詳細な認証設定については、references/docs/authentication.md を参照してください。

Graph API 呼び出しの実行

重要：セッション中に初めて graph-call を実行する前に、msgraph auth status を実行して認証を確認してください。

msgraph graph-call <METHOD> <URL> [flags]

読み取り操作

msgraph graph-call GET /me
msgraph graph-call GET /users --select "displayName,mail" --top 10
msgraph graph-call GET /me/messages --filter "isRead eq false" --top 5 --select "subject,from,receivedDateTime"
msgraph graph-call GET /users --filter "startsWith(displayName,'John')"

書き込み操作

重要：書き込み操作を行う前に、必ずユーザーに確認してください。書き込み操作には --allow-writes フラグが必要です。

msgraph graph-call POST /me/sendMail --body '{"message":{"subject":"Hello","body":{"content":"Hi"},"toRecipients":[{"emailAddress":{"address":"[email protected]"}}]}}' --allow-writes
msgraph graph-call PATCH /me --body '{"jobTitle":"Engineer"}' --allow-writes

フラグに関係なく、DELETE は常にブロックされます。

graph-call フラグ

フラグ	説明	例
--select	OData の $select	--select "displayName,mail"
--filter	OData の $filter	--filter "isRead eq false"
--top	OData の $top（結果数を制限）	--top 10
--expand	OData の $expand	--expand "members"
--orderby	OData の $orderby	--orderby "displayName desc"
--api-version	v1.0 または beta（デフォルト：beta）	--api-version v1.0
--scopes	追加のアクセス許可スコープを要求します	--scopes "Mail.Read"
--headers	カスタム HTTP ヘッダー	--headers "ConsistencyLevel:eventual"
--body	リクエスト本文（JSON）	--body '{"key":"value"}'
--output	json（デフォルト）または raw	--output raw
--allow-writes	POST/PUT/PATCH を許可します（ユーザーの確認が必要）

重要なルール

常に守ること（検索とナレッジ）

1. Microsoft Graph のエンドポイントを推測したり捏造したりしないでください。呼び出す前に必ず検索して確認してください。このスキルは、エージェントがエンドポイントを幻覚することを防ぐためのものです。活用してください。
2. 段階的な検索戦略を使用してください。まず既知の情報から始め、必要に応じて sample-search、api-docs-search、openapi-search の順に検索します。
3. --select を使用してレスポンスサイズを削減してください。必要なフィールドのみをリクエストします。
4. --top を使用して結果数を制限してください。数千件ものレコードを取得しないようにします。
5. ディレクトリオブジェクト（users、groups など）で $count と $search を使う場合、ConsistencyLevel ヘッダーが必要です。--headers "ConsistencyLevel:eventual" を使用してください。
6. デフォルトの API バージョンは beta です。本番環境で安定したエンドポイントには --api-version v1.0 を使用してください。

直接実行（graph-call）を使用する場合

7. セッションで最初の graph-call を実行する前に、認証状態を確認してください。
8. GET がデフォルトです — 特別なフラグは不要です。
9. 書き込み操作には --allow-writes が必要です — 必ず事前にユーザーの確認を得てください。
10. DELETE は常にブロックされます — サポートされていないことをユーザーに伝えてください。
11. 403 が発生すると自動的に再認証されます — ツールが追加のスコープを要求して再試行します（委任認証のみ）。
12. すべての出力は JSON です — 応答から statusCode フィールドと body フィールドを解析してください。

エラー処理

ステータス	意味	対処方法
401	トークンの有効期限切れ	msgraph auth signin を再度実行します
403	権限不足	ツールが段階的な同意を求めて自動的に再試行します。それでも失敗する場合は、ユーザーが管理者の同意を得る必要があります。
404	リソースが見つかりません	エンドポイントのパスを確認します
429	レート制限	Retry-After の時間だけ待ってから再試行します

環境変数

変数	説明	デフォルト
MSGRAPH_CLIENT_ID	カスタム Entra ID アプリのクライアント ID	Microsoft Graph CLI Tools アプリ
MSGRAPH_TENANT_ID	対象のテナント ID（アプリのみの場合は必須）	common
MSGRAPH_API_VERSION	デフォルトの API バージョン	beta
MSGRAPH_INDEX_DB_PATH	OpenAPI インデックスデータベースのパス	自動検出
MSGRAPH_SAMPLES_DB_PATH	サンプルインデックスデータベースのパス	自動検出
MSGRAPH_API_DOCS_DB_PATH	API ドキュメントインデックスデータベースのパス	自動検出
MSGRAPH_NO_TOKEN_CACHE	永続的なトークンキャッシュを無効化（メモリ内のみ）	false

認証関連の環境変数の全一覧については、references/docs/authentication.md を参照してください。

互換性

検索ツールは完全にオフラインで動作し、ネットワークアクセスは不要です。API の直接実行には、login.microsoftonline.com と graph.microsoft.com へのネットワークアクセスが必要です。対話型認証にはシステムブラウザーを使用し、ヘッドレス環境ではデバイスコードフローに切り替わります。

リファレンスファイル

特定のガイダンスが必要な場合に、必要に応じて以下を読み込んでください。事前に読み込まないでください。

ファイル	読み込むタイミング	サイズ
references/REFERENCE.md	一般的なリソースパス、OData パターン、アクセス許可スコープ	約 230 行
references/docs/authentication.md	詳細な認証設定：証明書、マネージド ID、ワークロード ID、すべての環境変数	約 200 行
references/docs/query-parameters.md	OData の $select、$filter、$expand、$top、$orderby、$search の構文と注意点	約 300 行
references/docs/advanced-queries.md	ConsistencyLevel ヘッダー、$count、$search、ディレクトリオブジェクトでの ne/not/endsWith	約 190 行
references/docs/paging.md	@odata.nextLink によるページネーション、サーバー側とクライアント側のページネーション	約 50 行
references/docs/batching.md	$batch エンドポイント、複数リクエストの結合、dependsOn による順序指定	約 280 行
references/docs/throttling.md	429 の処理、Retry-After、バックオフ戦略	約 90 行
references/docs/errors.md	HTTP ステータスコード、エラー応答形式、エラーコード	約 105 行
references/docs/best-practices.md	パフォーマンス向上のための $select、ページネーション、差分クエリ、バッチ処理	約 155 行