msgraph

Microsoft Graph Agent Skill

搜索、查找并调用 Microsoft Graph 的 27,700 多个 API——全部在本地完成，无需网络调用。使用三个搜索命令查找合适的终结点、检查权限和参数，然后可选择直接执行调用，或交由 Graph MCP 服务处理。

包含内容

Microsoft Graph API 每周更新，包含 27,700 多个终结点——远超大模型训练数据的截止范围。此技能将完整的 API 范围打包为本地索引，可即时搜索，无需网络调用。

索引	数量	内容
OpenAPI 终结点	27,700+	路径、方法、摘要、说明、权限范围
终结点文档	6,200+	权限（委托/应用）、查询参数、必需标头、默认属性与仅 $select 属性
资源架构	4,200+	所有属性及其类型、支持的 $filter 运算符、默认/仅选择标记
社区示例	持续增加	经人工核验的查询，将自然语言任务映射到确切的 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 服务搭配使用

如果 Agent 可以访问 Microsoft Graph MCP 服务（例如 lokka.dev 或其他 Microsoft Graph MCP 服务），请使用上述搜索工具查找合适的端点、权限和请求语法，然后通过 MCP 服务执行。

在此模式下，无需通过此技能进行身份验证。此技能纯粹充当知识层，由 MCP 服务负责身份验证和 API 执行。

直接执行 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。

有关身份验证配置的详细信息，包括证书、托管标识、工作负载标识联合身份验证和所有环境变量，请参阅 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 端点——调用前务必先通过搜索确认。此技能的存在正是因为 Agent 会产生幻觉；请使用它。
2. 采用渐进式查询策略——从已知信息开始，然后根据需要依次使用 sample-search、api-docs-search 和 openapi-search。
3. 使用 --select 缩减响应大小——只请求所需字段。
4. 使用 --top 限制结果数——避免获取数千条记录。
5. 对目录对象（用户、组等）的 $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	详细的身份验证配置：证书、托管标识、工作负载标识、所有环境变量	约 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 行