{
"canonical_name": "okapi-ca/ms-365-admin-mcp-server",
"compilation_id": "pack_291685217b9a49e4bbc03195e2a8856a",
"created_at": "2026-05-13T14:48:22.080623+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g @okapi-ca/ms-365-admin-mcp-server` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g @okapi-ca/ms-365-admin-mcp-server",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_7f35753a15c04c5c81ca6917c83c1372"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_987cc48ba124d36b5aeb01e0e431c265",
"canonical_name": "okapi-ca/ms-365-admin-mcp-server",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/okapi-ca/ms-365-admin-mcp-server",
"slug": "ms-365-admin-mcp-server",
"source_packet_id": "phit_d10e8351c1494a41906e823d2a931f03",
"source_validation_id": "dval_678c9500d6074d149e9cde5a9883812a"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 3,
"one_liner_en": "MCP server for Microsoft 365 admin operations via Graph API application permissions (security, audit, reports, service health)",
"one_liner_zh": "MCP server for Microsoft 365 admin operations via Graph API application permissions (security, audit, reports, service health)",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, server"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "ms-365-admin-mcp-server",
"title_zh": "ms-365-admin-mcp-server 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_d10e8351c1494a41906e823d2a931f03",
"page_model": {
"artifacts": {
"artifact_slug": "ms-365-admin-mcp-server",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g @okapi-ca/ms-365-admin-mcp-server",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/okapi-ca/ms-365-admin-mcp-server#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "MCP server for Microsoft 365 admin operations via Graph API application permissions (security, audit, reports, service health)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_6ede43fd3f7247e0981524934656dbeb | https://github.com/okapi-ca/ms-365-admin-mcp-server/issues/71 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 2,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3
},
"source_url": "https://github.com/okapi-ca/ms-365-admin-mcp-server",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "MCP server for Microsoft 365 admin operations via Graph API application permissions (security, audit, reports, service health)",
"title": "ms-365-admin-mcp-server 能力包",
"trial_prompt": "# ms-365-admin-mcp-server - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 ms-365-admin-mcp-server 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-features：核心功能特性。围绕“核心功能特性”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-authentication：认证系统。围绕“认证系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-authorization：授权机制。围绕“授权机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-features\n输入：用户提供的“核心功能特性”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-authentication\n输入：用户提供的“认证系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-authorization\n输入：用户提供的“授权机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-features：Step 2 必须围绕“核心功能特性”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-authentication：Step 4 必须围绕“认证系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-authorization：Step 5 必须围绕“授权机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/okapi-ca/ms-365-admin-mcp-server\n- https://github.com/okapi-ca/ms-365-admin-mcp-server#readme\n- agent-skills/ms365-admin-mcp/SKILL.md\n- README.md\n- package.json\n- src/tool-categories.ts\n- src/graph-tools.ts\n- docs/ARCHITECTURE.md\n- src/graph-client.ts\n- src/server.ts\n- bin/modules/generate-mcp-tools.mjs\n- src/auth.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 ms-365-admin-mcp-server 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: SEC-004: UPN persisted in logs without redaction option (PII / GDPR expo（https://github.com/okapi-ca/ms-365-admin-mcp-server/issues/71）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "SEC-004: UPN persisted in logs without redaction option (PII / GDPR expo",
"url": "https://github.com/okapi-ca/ms-365-admin-mcp-server/issues/71"
}
],
"status": "已收录 1 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "MCP server for Microsoft 365 admin operations via Graph API application permissions (security, audit, reports, service health)",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "ms-365-admin-mcp-server 能力包",
"risk": "需复核",
"slug": "ms-365-admin-mcp-server",
"stars": 3,
"tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/okapi-ca/ms-365-admin-mcp-server 项目说明书\n\n生成时间：2026-05-13 14:28:40 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [核心功能特性](#page-features)\n- [系统架构](#page-architecture)\n- [通信传输层](#page-transports)\n- [认证系统](#page-authentication)\n- [授权机制](#page-authorization)\n- [工具分类系统](#page-tool-categories)\n- [风险模型](#page-risk-model)\n- [部署指南](#page-deployment)\n- [配置参考](#page-configuration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[核心功能特性](#page-features), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/README.md)\n- [package.json](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/package.json)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n- [SECURITY.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/SECURITY.md)\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n \n\n# 项目介绍\n\n## 项目概述\n\n`ms-365-admin-mcp-server` 是一个基于 Microsoft Model Context Protocol (MCP) 的服务器项目，专门为 Microsoft 365 管理任务提供标准化的工具接口。该项目将 Microsoft Graph API 中的管理员操作封装为离散的、类型安全的工具（tools），使 AI 代理能够以受控和安全的方式执行 Microsoft 365 租户管理操作。 资料来源：[README.md]()\n\n项目支持发布到 npm 作为 `@okapi-ca/ms-365-admin-mcp-server`，同时容器镜像发布到 GHCR (`ghcr.io/okapi-ca/ms-365-admin-mcp-server`)。 资料来源：[CHANGELOG.md]()\n\n## 核心架构\n\n### 技术栈\n\n| 组件 | 技术选型 | 说明 |\n|------|---------|------|\n| 运行时 | Node.js / TypeScript | 严格模式，ESLint + Prettier 规范 |\n| API 层 | Microsoft Graph API | OpenAPI 规范自动生成客户端 |\n| 认证 | MSAL (Microsoft Authentication Library) | 客户端凭据流 |\n| 类型安全 | Zod | Graph 响应的运行时验证 |\n| 构建 | npm | 包管理和脚本执行 |\n\n### 模块结构\n\n```\nsrc/\n auth.ts # MSAL 客户端凭据流实现\n auth-bootstrap.ts # RFC 8628 设备代码引导认证\n cli.ts # Commander 参数解析\n cloud-config.ts # 全球版与中国世纪互联版端点配置\n endpoints.json # 工具定义的权威数据源\n generated/ # 自动生成的 Zod 客户端代码\n tool-categories.ts # 工具分类正则模式\n risk-level.ts # 风险等级计算模块\n user-token-authorization.ts # 用户令牌授权验证\n untrusted-envelope.ts # 不受信任响应包装器\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 核心功能\n\n### 工具生态\n\n项目当前包含 **444 个管理员工具**，覆盖以下主要类别：\n\n| 类别 | 功能范围 | 参考文档 |\n|------|---------|---------|\n| `identity` | 用户、组、角色、设备、PIM、来宾、外部身份 | usecase-identity.md |\n| `exchange` | 消息追踪、邮箱管理 | usecase-exchange.md |\n| `intune` | 设备、合规、配置、Autopilot、应用、RBAC | usecase-intune.md |\n| `governance` | 访问评审、权利管理、生命周期工作流、条款使用 | usecase-governance.md |\n| `compliance` | 许可证、安全评分、身份保护、风险检测、CA策略 | usecase-compliance.md |\n| `response` | 事件响应写入（禁用、撤销、确认、忽略） | usecase-response.md |\n| `ediscovery` | 电子发现案例（Microsoft Purview） | usecase-ediscovery.md |\n| `cloudpc` | 云 PC / Windows 365 | usecase-cloudpc.md |\n| `callrecords` | Teams 通话记录 | usecase-callrecords.md |\n| `print` | 通用打印 | usecase-print.md |\n| `infoprotection` | BitLocker、威胁评估、敏感度标签 | usecase-infoprotection.md |\n| `sharepointadmin` | SharePoint 租户管理 | usecase-sharepointadmin.md |\n| `retention` | 记录管理 | usecase-retention.md |\n\n资料来源：[tools-catalog.md]()\n\n### 工具分类模式\n\n工具类别通过正则表达式自动匹配工具名称：\n\n```typescript\nexport const TOOL_CATEGORIES: Record = {\n identity: {\n name: 'identity',\n pattern: /user|group|role|device|administrative|directory/i,\n description: '用户、组、角色、设备、PIM...',\n },\n response: {\n name: 'response',\n pattern:\n /disable-user|revoke|block|reset|isolate|update-security|.../i,\n description: '事件响应操作...',\n },\n // ...\n};\n```\n\n资料来源：[src/tool-categories.ts]()\n\n## 安全模型\n\n项目实现了多层安全防护机制。\n\n### 风险等级体系\n\n所有非 GET 操作必须标注风险等级，作为 MCP 工具注册的依据：\n\n| 风险等级 | 判定标准 | 示例工具 |\n|---------|---------|---------|\n| `low` | 只读或微小影响 | `run-hunting-query`, `add-security-alert-comment` |\n| `medium` | 单个实体的可逆变更 | `update-user`, `add-group-member`, `create-invitation` |\n| `high` | 广泛影响、凭据变更或破坏性操作 | `revoke-user-sessions`, `update-conditional-access-policy` |\n| `critical` | 不可逆或租户范围影响 | `delete-user`, `wipe-managed-device`, `delete-conditional-access-policy` |\n\n资料来源：[CONTRIBUTING.md]()\n\n### 安全机制\n\n| 机制 | 描述 |\n|------|------|\n| `--max-risk-level` | CLI 参数限制注册工具的最大风险等级 |\n| `--allow-writes` | 显式授权写入操作 |\n| 响应包装器 | Graph 响应使用 nonce 包装防提示注入 |\n| 最小权限 | 仅请求必需的 Graph API 权限 |\n\n项目包含 51 个单元测试覆盖所有五个安全关键模块。 资料来源：[CHANGELOG.md]()\n\n## 认证机制\n\n### 客户端凭据流\n\n```mermaid\ngraph TD\n A[启动服务器] --> B[读取 .env 配置]\n B --> C{环境变量检查}\n C -->|缺失 MSAL 配置| D[触发设备代码引导]\n C -->|有 MSAL 配置| E[初始化 MSAL 客户端]\n D --> F[RFC 8628 设备代码流程]\n F --> G[获取访问令牌]\n E --> G\n G --> H[缓存令牌到 mcp-remote]\n H --> I[服务器就绪]\n```\n\n### 云配置\n\n项目支持 Microsoft 365 全球版和中国世纪互联版（21Vianet）的不同端点，通过 `cloud-config.ts` 模块统一管理。 资料来源：[src/auth.ts]()\n\n## 开发工作流\n\n### 环境配置\n\n```bash\ngit clone https://github.com/okapi-ca/ms-365-admin-mcp-server.git\ncd ms-365-admin-mcp-server\nnpm install\nnpm run generate # 下载 Graph OpenAPI 规范并生成客户端\nnpm run build\nnpm test\n```\n\n本地 `.env` 文件配置：\n\n```\nMS365_ADMIN_MCP_CLIENT_ID=...\nMS365_ADMIN_MCP_CLIENT_SECRET=...\nMS365_ADMIN_MCP_TENANT_ID=...\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 添加工具流程\n\n```mermaid\ngraph LR\n A[编辑 endpoints.json] --> B[添加工具定义]\n B --> C[npm run generate]\n C --> D[生成 Zod 客户端代码]\n D --> E[node dist/index.js --list-tools]\n E --> F[验证工具注册]\n F --> G[添加单元测试]\n G --> H[更新 README.md 工具表]\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 工具定义规范\n\n`endpoints.json` 中每个工具定义包含：\n\n```json\n{\n \"toolName\": {\n \"method\": \"GET|POST|PATCH|DELETE\",\n \"appPermissions\": [\"Permission.Read.All\"],\n \"llmTip\": \"可选的 LLM 提示信息\",\n \"riskLevel\": \"low|medium|high|critical\"\n }\n}\n```\n\n## 版本历史\n\n| 版本 | 工具数 | 主要变更 |\n|------|-------|---------|\n| 当前 | 444 | 安全修复、BitLocker 恢复密钥等敏感读取标注 |\n| 之前 | 369 | 新增云 PC、Teams 通话记录、通用打印等5个类别 |\n| 更早 | 306 | 107 个高价值管理员端点 |\n| 更早 | 199 | 安全修复、权限范围缩减 |\n\n资料来源：[CHANGELOG.md]()\n\n## 使用场景\n\n### 管理员操作自动化\n\n项目主要用于以下场景：\n\n- **身份管理**：用户生命周期管理、组分配、角色权限\n- **设备管理**：Intune 设备合规性监控、丢失设备远程操作\n- **安全响应**：风险用户确认、 compromised 用户隔离\n- **合规审计**：电子发现、访问评审、审计日志查询\n- **租户配置**：SharePoint、Teams、Exchange 设置管理\n\n### MCP 客户端集成\n\n项目作为 MCP 服务器运行，Claude Desktop/Code 等客户端可通过 MCP Inspector 进行交互式调试：\n\n```bash\nnpm run inspector\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 质量保证\n\n| 检查项 | 命令 |\n|-------|------|\n| 代码格式检查 | `npm run format:check` |\n| ESLint 检查 | `npm run lint` |\n| 完整验证 | `npm run verify` |\n| 列出所有工具 | `node dist/index.js --list-tools` |\n| 列出所有权限 | `node dist/index.js --list-permissions` |\n\n## 许可证\n\n本项目采用 MIT 许可证。 资料来源：[CHANGELOG.md]()\n\n---\n\n\n\n## 核心功能特性\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [工具分类系统](#page-tool-categories)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/endpoints.json](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/endpoints.json)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n- [src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n \n\n# 核心功能特性\n\nms-365-admin-mcp-server 是一个基于 Model Context Protocol (MCP) 的 Microsoft 365 管理服务器，通过 Microsoft Graph API 为 AI 助手提供对 Microsoft 365 管理功能的标准化访问接口。该项目从 175 个工具起步，经过多次迭代已扩展至 **515 个管理工具**，覆盖安全、审计、合规、设备管理、身份治理等核心领域。\n\n## 1. 系统架构概览\n\n### 1.1 整体架构\n\nms-365-admin-mcp-server 采用分层架构设计，核心层负责与 Microsoft Graph API 交互，认证层处理 Azure AD 应用注册凭证，配置层支持全球版和中国区（21Vianet）两种部署模式。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[MCP 客户端 / Claude Code]\n B[MCP Inspector]\n end\n \n subgraph 服务端核心\n C[CLI 解析层
src/cli.ts]\n D[工具注册表
src/endpoints.json]\n E[风险评估引擎
src/risk-level.ts]\n end\n \n subgraph 认证与配置\n F[MSAL 认证
src/auth.ts]\n G[云配置
src/cloud-config.ts]\n end\n \n subgraph Microsoft Graph API\n H[全球版
graph.microsoft.com]\n I[中国版
graph.microsoft.cn]\n end\n \n A --> C\n B --> C\n C --> D\n C --> E\n C --> F\n F --> G\n G --> H\n G --> I\n D --> H\n D --> I\n```\n\n### 1.2 目录结构\n\n| 目录/文件 | 功能说明 |\n|-----------|----------|\n| `bin/` | 代码生成脚本（OpenAPI 规范转换为 Zod 客户端） |\n| `src/` | 核心源代码 |\n| `src/auth.ts` | MSAL 客户端凭证流认证 |\n| `src/cli.ts` | Commander 参数解析 |\n| `src/cloud-config.ts` | 全球版与中国区端点配置 |\n| `src/endpoints.json` | 工具定义的事实来源 |\n| `src/generated/` | 自动生成的 Zod 验证代码 |\n| `src/risk-level.ts` | 风险等级计算与权限校验 |\n| `src/tool-categories.ts` | 工具分类与预设定义 |\n| `docs/` | 使用文档、风险模型、剧本 |\n\n## 2. 工具分类与预设体系\n\n### 2.1 预设分类总览\n\n该服务器将 515 个工具组织为 **17 个功能预设（Preset）**，每个预设对应特定的管理场景。预设通过正则表达式匹配工具名称实现自动归类。\n\n| 预设名称 | 功能描述 | 对应用例文件 |\n|----------|----------|--------------|\n| `security` | 安全警报、事件、攻击模拟、威胁情报 | `usecase-security.md` |\n| `audit` | 目录审计、登录日志、预配记录、已删除项 | `usecase-audit.md` |\n| `health` | 服务运行状况、消息中心公告 | `usecase-health.md` |\n| `reports` | 使用报告（Teams、邮件、SharePoint、OneDrive） | `usecase-reports.md` |\n| `identity` | 用户、组、角色、设备、PIM、来宾用户、外部身份 | `usecase-identity.md` |\n| `exchange` | 邮件跟踪、邮箱管理 | `usecase-exchange.md` |\n| `intune` | 设备、合规、配置、Autopilot、应用、RBAC | `usecase-intune.md` |\n| `governance` | 访问评审、权利管理生命周期、条款使用 | `usecase-governance.md` |\n| `compliance` | 许可证、安全分数、身份保护、风险检测、CA 策略 | `usecase-compliance.md` |\n| `response` | 事件响应写入操作（禁用、吊销、确认、驳回） | `usecase-response.md` |\n| `ediscovery` | 电子发现案例（Purview） | `usecase-ediscovery.md` |\n| `cloudpc` | 云 PC / Windows 365 | `usecase-cloudpc.md` |\n| `callrecords` | Teams 通话记录 | `usecase-callrecords.md` |\n| `print` | 通用打印 | `usecase-print.md` |\n| `infoprotection` | BitLocker、威胁评估、敏感度标签 | `usecase-infoprotection.md` |\n| `sharepointadmin` | SharePoint 租户管理 | `usecase-sharepointadmin.md` |\n| `retention` | 记录管理 | `usecase-retention.md` |\n\n### 2.2 工具分类定义实现\n\n预设分类在 `src/tool-categories.ts` 中通过 TypeScript 接口和正则表达式定义：\n\n```typescript\nexport interface ToolCategory {\n name: string;\n pattern: RegExp;\n description: string;\n}\n\nexport const TOOL_CATEGORIES: Record = {\n security: {\n name: 'security',\n pattern: /security|alert|incident|attack-simulation|threat-intel/i,\n description: 'Security alerts, incidents, attack simulations...',\n },\n identity: {\n name: 'identity',\n pattern: /user|group|role|conditional|directory|domain|auth-method|.../i,\n description: 'Identity and access management...',\n },\n // ... 其他预设\n};\n```\n\n资料来源：[src/tool-categories.ts:1-20]()\n\n### 2.3 工具发现与验证\n\n服务器提供命令行工具用于验证工具分类和权限配置：\n\n```bash\n# 列出所有工具\nnode dist/index.js --list-tools\n\n# 按预设列出工具\nnode dist/index.js --preset security --list-tools\n\n# 列出所需权限\nnode dist/index.js --list-permissions\n\n# 验证特定预设\nnode dist/index.js --preset identity --list-tools | grep list-users\n```\n\n## 3. 风险等级管理体系\n\n### 3.1 风险等级定义\n\n服务器对所有非 GET 操作工具进行风险分类，确保高风险操作需要明确授权：\n\n| 风险等级 | 判断标准 | 影响范围 | 操作示例 |\n|----------|----------|----------|----------|\n| `low` | 只读效果或最小影响 | 有限 | 添加安全警报评论、重新处理用户许可证 |\n| `medium` | 可逆变更影响单个实体 | 单个实体 | 更新用户、创建组、添加工具成员 |\n| `high` | 重大影响、凭证变更或破坏性操作 | 多个实体 | 吊销用户会话、更新条件访问策略 |\n| `critical` | 不可逆或租户级影响 | 整个租户 | 删除用户、擦除托管设备、删除条件访问策略 |\n\n### 3.2 风险等级计算逻辑\n\n风险等级的计算遵循以下优先级：\n\n1. **已配置风险等级优先**：如果 `endpoints.json` 中明确指定了 `riskLevel`，则使用该值\n2. **GET 请求默认低风险**：GET 请求默认为 `low`（只读操作）\n3. **未标注写入操作默认为 critical**：对于没有明确标注风险等级的写入操作，默认设置为 `critical`（故障安全原则）\n\n```typescript\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n if (configuredRiskLevel) return configuredRiskLevel;\n return method.toUpperCase() === 'GET' ? 'low' : 'critical';\n}\n```\n\n资料来源：[src/risk-level.ts:9-17]()\n\n### 3.3 权限校验机制\n\n工具执行前会校验其风险等级是否在允许范围内：\n\n```typescript\nexport function isToolAllowed(\n configuredRiskLevel: RiskLevel | undefined,\n method: string,\n maxRiskLevel: RiskLevel\n): boolean {\n return rank(effectiveRiskLevel(configuredRiskLevel, method)) <= rank(maxRiskLevel);\n}\n```\n\n写入操作的默认行为需要显式启用：\n\n```bash\n# 允许中等风险操作\nnode dist/index.js --allow-writes medium\n\n# 允许高风险操作（需二次确认）\nnode dist/index.js --allow-writes high\n```\n\n### 3.4 高危工具分类\n\n#### Critical 级别（需带外审批）\n\n以下操作被视为不可逆或具有租户范围影响：\n\n- `delete-user` — 删除用户账户\n- `delete-group` — 删除安全组\n- `delete-conditional-access-policy` — 删除条件访问策略\n- `wipe-managed-device` — 远程擦除托管设备\n- `delete-managed-device` — 删除设备注册\n- `delete-ediscovery-case` — 删除电子发现案例\n\n#### High 级别（需显式确认 + 预演）\n\n以下操作需要操作员确认并可能需要干运行：\n\n- `revoke-user-sessions` — 吊销用户会话\n- `confirm-compromised-users` — 确认受损用户\n- `change-user-password` — 更改用户密码\n- `update-device` — 更新设备配置\n- `create-attack-simulation` — 创建攻击模拟（钓鱼测试）\n\n## 4. 认证与安全机制\n\n### 4.1 MSAL 客户端凭证流\n\n服务器使用 Microsoft Authentication Library (MSAL) 的客户端凭证流进行认证，适用于服务级（无用户交互）的管理操作：\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant MSAL as MSAL 库\n participant AAD as Azure AD\n \n MCP->>AAD: 请求访问令牌
(client_id, client_secret, tenant_id)\n AAD-->>MSAL: 返回 access_token\n MSAL-->>MCP: access_token\n MCP->>Graph: Graph API 请求
(Bearer token)\n Graph-->>MCP: API 响应\n```\n\n### 4.2 环境变量配置\n\n需要在 `.env` 文件中配置以下凭证：\n\n```bash\nMS365_ADMIN_MCP_CLIENT_ID=... # Azure AD 应用注册的应用 ID\nMS365_ADMIN_MCP_CLIENT_SECRET=... # 应用密钥\nMS365_ADMIN_MCP_TENANT_ID=... # 租户 ID\n```\n\n资料来源：[CONTRIBUTING.md:45-49]()\n\n### 4.3 查询字符串与错误信息防护\n\n服务器对以下内容进行脱敏处理以防止凭证泄露：\n\n- 查询字符串参数\n- `testLogin` 错误消息中的敏感信息\n\n> `sec: sanitize query strings and testLogin error leaks` — CHANGELOG.md\n\n## 5. 云配置与多租户支持\n\n### 5.1 全球版与中国区切换\n\n服务器支持两种 Microsoft Graph 端点配置，适用于不同的主权云环境：\n\n```mermaid\ngraph LR\n A[请求] --> B{cloud-config}\n B -->|全球版| C[graph.microsoft.com]\n B -->|中国版| D[graph.microsoft.cn
21Vianet]\n \n style C fill:#4CAF50\n style D fill:#FF9800\n```\n\n| 云类型 | Graph 端点 | 适用场景 |\n|--------|------------|----------|\n| Global | `graph.microsoft.com` | 全球 Microsoft 365 商业版 |\n| China | `graph.microsoft.cn` | 世纪互联运营的 Azure 中国区 |\n\n配置详情见 `src/cloud-config.ts`。\n\n## 6. 工具定义与代码生成\n\n### 6.1 端点定义格式\n\n工具定义以 JSON 格式存储在 `endpoints.json` 中，作为所有工具定义的事实来源：\n\n```json\n{\n \"toolName\": \"list-users\",\n \"endpoint\": \"/v1.0/users\",\n \"method\": \"GET\",\n \"appPermissions\": [\"User.Read.All\"],\n \"llmTip\": \"列出租户中的所有用户\",\n \"riskLevel\": \"low\"\n}\n```\n\n### 6.2 代码生成流程\n\n服务器采用 OpenAPI 规范驱动的工作流：\n\n```mermaid\ngraph LR\n A[Graph OpenAPI 规范] --> B[bin/ 脚本]\n B --> C[生成 Zod 验证代码]\n B --> D[更新 endpoints.json]\n C --> E[src/generated/]\n D --> F[src/endpoints.json]\n \n style A fill:#2196F3,color:#fff\n style E fill:#E3F2FD\n style F fill:#E3F2FD\n```\n\n生成命令：\n\n```bash\nnpm run generate # 下载 Graph OpenAPI 规范并生成客户端\n```\n\n**重要提示**：`src/generated/` 目录下的文件由代码生成脚本自动维护，请勿手动编辑。如需修改工具定义，应编辑 `endpoints.json` 后重新生成。\n\n资料来源：[CONTRIBUTING.md:88-94]()\n\n## 7. 命令行接口\n\n### 7.1 可用命令\n\n服务器通过 `src/cli.ts` 提供以下命令行选项：\n\n| 命令 | 功能 |\n|------|------|\n| `--list-tools` | 列出所有可用工具 |\n| `--list-permissions` | 列出所需 Graph API 权限 |\n| `--list-tools --preset ` | 按预设筛选工具 |\n| `--list-tools --category ` | 按类别筛选工具 |\n| `--allow-writes ` | 允许指定风险等级的写入操作 |\n| `--preset --list-tools` | 验证预设分类 |\n| `--inspector` | 启动 MCP Inspector |\n\n### 7.2 交互式调试\n\n使用 MCP Inspector 进行本地调试：\n\n```bash\nnpm run inspector\n```\n\n## 8. 开发与贡献指南\n\n### 8.1 开发环境搭建\n\n```bash\ngit clone https://github.com/okapi-ca/ms-365-admin-mcp-server.git\ncd ms-365-admin-mcp-server\nnpm install\nnpm run generate # 生成客户端代码\nnpm run build # 编译 TypeScript\nnpm test # 运行测试\nnpm run verify # 完整验证（lint + 测试）\n```\n\n### 8.2 添加新工具的工作流\n\n添加新工具的标准流程：\n\n1. **编辑端点定义**：在 `endpoints.json` 中添加工具定义\n\n ```json\n {\n \"toolName\": \"list-something\",\n \"endpoint\": \"/v1.0/something\",\n \"method\": \"GET\",\n \"appPermissions\": [\"Something.Read.All\"],\n \"llmTip\": \"可选的 LLM 提示\",\n \"riskLevel\": \"low\"\n }\n ```\n\n2. **重新生成客户端**：\n\n ```bash\n npm run generate\n ```\n\n3. **验证工具注册**：\n\n ```bash\n node dist/index.js --list-tools | grep list-something\n node dist/index.js --list-permissions | grep Something\n ```\n\n4. **添加测试**：为非平凡参数处理或 skipEncoding 规则添加测试\n\n5. **更新 README.md**：更新工具计数和类别表格\n\n### 8.3 提交规范\n\n| 前缀 | 使用场景 |\n|------|----------|\n| `feat:` | 新工具、预设或功能 |\n| `fix:` | 错误修复 |\n| `sec:` | 安全修复 |\n| `docs:` | 仅文档更改 |\n| `chore:` | 工具、依赖、非功能性变更 |\n| `refactor:` | 无行为变更的重构 |\n| `test:` | 仅测试 |\n| `build(deps):` | 依赖升级 |\n\n## 9. 权限模型\n\n### 9.1 最小权限原则\n\n所有新工具必须声明最小必需的 Graph API 权限：\n\n| 操作类型 | 推荐权限 | 避免 |\n|----------|----------|------|\n| 只读 | `*.Read.All` | `*.ReadWrite.All` |\n| 写入 | `*.ReadWrite.All` | 仅在必要时使用 |\n\n### 9.2 应用权限 vs 委托权限\n\n服务器使用 **应用权限**（application permissions），因为它是无用户交互的服务级操作：\n\n```typescript\n// endpoints.json 中的权限声明\n{\n \"appPermissions\": [\"User.Read.All\", \"Group.Read.All\"]\n}\n```\n\n## 10. 快速参考表\n\n### 10.1 关键文件速查\n\n| 文件路径 | 用途 |\n|----------|------|\n| `src/endpoints.json` | 工具定义的源文件 |\n| `src/tool-categories.ts` | 预设分类配置 |\n| `src/risk-level.ts` | 风险计算逻辑 |\n| `src/auth.ts` | MSAL 认证 |\n| `src/cloud-config.ts` | 云端点配置 |\n| `src/cli.ts` | 命令行接口 |\n| `docs/RISK_MODEL.md` | 风险模型文档 |\n| `docs/USE_CASES.md` | 用例文档 |\n\n### 10.2 风险等级快速对照\n\n```\n权限等级: low < medium < high < critical\n允许写入: --allow-writes medium 允许 low + medium\n```\n\n### 10.3 版本历史要点\n\n| 版本 | 工具数量 | 关键变更 |\n|------|----------|----------|\n| 当前 | 515 | 71 个管理写入端点 |\n| v1.0 | 444 | 75 个管理写入操作 |\n| - | 369 | Cloud PC、Teams 通话记录、通用打印、信息保护 |\n| - | 306 | eDiscovery、Intune、身份治理 |\n| - | 199 | 权限范围缩减至最小权限 |\n| 早期 | 175 | 基础安全、设备、PIM、风险检测 |\n\n资料来源：[CHANGELOG.md:1-50]()\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [通信传输层](#page-transports), [认证系统](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [src/graph-client.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-client.ts)\n- [src/server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/server.ts)\n- [src/graph-tools.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-tools.ts)\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n \n\n# 系统架构\n\n## 概述\n\n`ms-365-admin-mcp-server` 是一个基于 Model Context Protocol (MCP) 的 Microsoft 365 管理服务器，通过 Microsoft Graph API 为 AI 代理提供 515+ 管理工具的访问能力。服务器采用 TypeScript 开发，运行于 Node.js 环境，支持标准输入输出（STDIO）和 HTTP 两种传输模式，可部署在 Azure Container Apps 等云环境中。\n\n核心设计原则：\n- **安全优先**：所有写操作必须按风险等级分类，需要显式授权方可执行\n- **最小权限**：仅请求必要的 Graph API 权限\n- **零破坏变更**：工具名称、参数结构预设分类不可随意变更\n- **代码生成**：工具定义基于 OpenAPI 规范自动生成，确保与 Graph API 同步\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A1[Claude Desktop]\n A2[Claude Code]\n A3[其他 MCP 客户端]\n end\n\n subgraph 服务器传输层\n B1[STDIO 服务器
server.ts]\n B2[HTTP 服务器
http-server.ts
StreamableHTTP]\n end\n\n subgraph 核心服务层\n C1[认证模块
auth.ts]\n C2[工具注册
graph-tools.ts]\n C3[风险评估
risk-level.ts]\n C4[工具分类
tool-categories.ts]\n C5[云配置
cloud-config.ts]\n end\n\n subgraph Graph API 层\n D1[Graph 客户端
graph-client.ts]\n D2[端点配置
endpoints.json]\n D3[生成工具
generated/]\n end\n\n subgraph Microsoft 365\n E1[Microsoft Graph API]\n E2[Azure AD
令牌颁发]\n end\n\n A1 --> B1\n A2 --> B1\n A3 --> B2\n B1 --> C1\n B2 --> C1\n C1 --> D1\n D1 --> E1\n D1 --> E2\n C2 --> D2\n C2 --> D3\n```\n\n资料来源：[src/server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/server.ts)\n\n---\n\n## 核心组件\n\n### 组件职责矩阵\n\n| 组件文件 | 职责 | 关键类型/函数 |\n|---------|------|--------------|\n| `src/index.ts` | 应用入口点，CLI 参数解析 | Commander.js |\n| `src/auth.ts` | MSAL 客户端凭据流认证 | `getConfidentialClientApplication` |\n| `src/cloud-config.ts` | 全球版与世纪互联版端点切换 | `CloudConfig`, `getCloudConfig` |\n| `src/graph-client.ts` | Graph API HTTP 封装 | `GraphClient`, `fetchWithAuth` |\n| `src/graph-tools.ts` | MCP 工具注册与执行 | `registerTools`, `executeGraphTool` |\n| `src/risk-level.ts` | 风险等级计算与权限校验 | `effectiveRiskLevel`, `isToolAllowed` |\n| `src/tool-categories.ts` | 预设分类定义 | `TOOL_CATEGORIES`, `getCombinedPresetPattern` |\n| `src/server.ts` | STDIO 传输模式服务器 | `StdioServer`, `runStdioServer` |\n| `src/http-server.ts` | HTTP 传输模式服务器 | `StreamableHTTPTransport` |\n| `src/token-validator.ts` | HTTP 模式 JWT 验证 | `validateJwtToken` |\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## 工具注册流程\n\n### 工具定义来源\n\n所有工具定义存储在 `src/endpoints.json` 中，作为工具注册的唯一数据源。每个条目包含：\n\n```jsonc\n{\n \"toolName\": \"list-users\",\n \"pathPattern\": \"/users\",\n \"method\": \"GET\",\n \"appPermissions\": [\"User.Read.All\"],\n \"llmTip\": \"获取所有用户列表，支持 $select, $filter\",\n \"riskLevel\": \"low\" // 仅非 GET 操作需要\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n### 工具注册时序\n\n```mermaid\nsequenceDiagram\n participant CLI as 命令行解析\n participant Server as StdioServer\n participant Registry as 工具注册器\n participant Config as endpoints.json\n participant Generator as 代码生成器\n participant Graph as GraphClient\n\n CLI->>Server: 初始化服务器\n Server->>Registry: 加载 endpoints.json\n Registry->>Generator: 读取工具定义\n Generator->>Config: 解析工具元数据\n Config-->>Registry: 返回工具配置列表\n Registry->>Registry: 遍历每个工具\n Registry->>Registry: 计算 effectiveRiskLevel\n Registry->>Registry: 检查 maxRiskLevel 限制\n alt 工具被风险等级过滤\n Registry->>Registry: 跳过注册\n else 工具允许注册\n Registry->>Graph: 注册 MCP 工具\n Graph-->>Registry: 注册成功\n end\n Registry->>Server: 返回注册统计\n```\n\n资料来源：[src/graph-tools.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-tools.ts)\n\n---\n\n## 认证机制\n\n### MSAL 客户端凭据流\n\n服务器使用 MSAL (Microsoft Authentication Library) 的客户端凭据流进行无用户认证：\n\n```mermaid\ngraph LR\n A[服务器启动] --> B[初始化 MSAL 客户端]\n B --> C[从环境变量读取
CLIENT_ID, CLIENT_SECRET, TENANT_ID]\n C --> D{云类型}\n D -->|全球版| E[login.microsoftonline.com]\n D -->|世纪互联| F[login.partner.microsoftonline.cn]\n E --> G[获取访问令牌]\n F --> G\n G --> H[Graph API 请求]\n H -->|令牌过期| G\n```\n\n资料来源：[src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n\n### 云配置支持\n\n| 云类型 | 标识 | Graph 根端点 |\n|--------|------|-------------|\n| 全球版 (Commercial) | `global` | `graph.microsoft.com` |\n| 世纪互联版 (China 21Vianet) | `china` | `graph.microsoft.cn` |\n\n资料来源：[src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n\n---\n\n## 风险等级系统\n\n### 风险等级定义\n\n| 等级 | 描述 | 判定条件 |\n|------|------|---------|\n| `low` | 只读操作或无害写操作 | GET 请求默认；POST 查询报表 |\n| `medium` | 单个实体的可逆变更 | `update-user`, `add-group-member` |\n| `high` | 广泛影响、凭据变更或破坏性操作 | `revoke-user-sessions`, `update-conditional-access-policy` |\n| `critical` | 不可逆或租户级影响 | `delete-user`, `wipe-managed-device`, `delete-conditional-access-policy` |\n\n资料来源：[src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n### 风险等级计算逻辑\n\n```typescript\nfunction effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n // 1. 如果配置了显式风险等级，使用配置值\n if (configuredRiskLevel) return configuredRiskLevel;\n \n // 2. GET 请求默认 low\n if (method.toUpperCase() === 'GET') return 'low';\n \n // 3. 未标注的非 GET 请求默认为 critical（fail-safe）\n return 'critical';\n}\n\nfunction isToolAllowed(\n configuredRiskLevel: RiskLevel | undefined,\n method: string,\n maxRiskLevel: RiskLevel\n): boolean {\n return rank(effectiveRiskLevel(configuredRiskLevel, method)) <= rank(maxRiskLevel);\n}\n```\n\n**重要**：未在 `endpoints.json` 中显式标注风险等级的非 GET 操作会被视为 `critical`，确保敏感操作不会被意外暴露。\n\n资料来源：[src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n---\n\n## 工具分类预设\n\n### 预设分类列表\n\n| 预设名称 | 功能范围 | 正则匹配模式 |\n|---------|---------|-------------|\n| `security` | 安全警报、事件、攻击模拟、威胁情报 | `/security\\|alert\\|incident\\|attack/i` |\n| `audit` | 目录审计、登录日志、预配日志 | `/audit\\|sign-in\\|provision\\|deleted/i` |\n| `health` | 服务健康、消息中心 | `/serviceHealth\\|serviceStatus\\|messageCenter/i` |\n| `reports` | 使用报告（Teams、邮件、SharePoint 等） | `/report\\|usage/i` |\n| `identity` | 用户、组、角色、设备、PIM、来宾 | `/user\\|group\\|role\\|device\\|pim\\|guest/i` |\n| `exchange` | 消息跟踪、邮箱 | `/mail\\|messageTrace\\|mailbox/i` |\n| `intune` | 设备、合规、配置、Autopilot、应用、RBAC | `/intune\\|managedDevice\\|compliance/i` |\n| `governance` | 访问评审、权利管理、生命周期、PIM | `/accessReview\\|entitlement\\|lifecycle\\|pim/i` |\n| `compliance` | 许可证、安全分数、身份保护、条件访问 | `/license\\|secureScore\\|conditionalAccess/i` |\n| `response` | 事件响应写操作（禁用、撤销、确认） | `/disable\\|revoke\\|block\\|reset\\|wipe/i` |\n| `ediscovery` | 电子发现案件（Purview） | `/ediscovery/i` |\n| `cloudpc` | 云 PC / Windows 365 | `/cloud-pc\\|provisioning/i` |\n| `callrecords` | Teams 通话记录 | `/call-record\\|call-session\\|pstn/i` |\n| `print` | 通用打印 | `/print/i` |\n| `infoprotection` | BitLocker、威胁评估、敏感标签 | `/bitlocker\\|sensitivity\\|threatAssessment/i` |\n| `sharepointadmin` | SharePoint 租户管理 | `/sharepoint\\|spo/i` |\n| `retention` | 记录管理 | `/retention/i` |\n| `teamsadmin` | Teams 管理 | `/team\\|channel\\|teams-app/i` |\n| `all` | 所有可用工具 | `/.*/` |\n\n资料来源：[src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n\n---\n\n## 传输模式\n\n### STDIO 模式\n\n适用于本地运行和 Claude Desktop/Code 集成：\n\n```mermaid\ngraph LR\n A[Claude Desktop] <-->|STDIO| B[ms-365-admin-mcp-server]\n B --> C[MSAL 认证]\n C --> D[Graph API]\n```\n\n启动命令：\n```bash\nnode dist/index.js\n```\n\n### HTTP 模式\n\n适用于 Azure Container Apps 等云部署：\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|HTTPS + JWT| B[HTTP 服务器]\n B --> C[Token 验证
token-validator.ts]\n C --> D[MSAL 认证]\n D --> E[Graph API]\n```\n\n启动命令：\n```bash\nnode dist/index.js --http --port 3000 --jwt-secret \n```\n\n资料来源：[src/server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/server.ts)\n\n---\n\n## 代码生成流程\n\n### OpenAPI 规范生成工具\n\n```mermaid\ngraph TD\n A[Microsoft Graph
OpenAPI Spec] --> B[bin/generate-mcp-tools.mjs]\n B --> C[解析端点元数据]\n C --> D[生成 Zod 验证模式]\n D --> E[输出到 src/generated/]\n E --> F[类型安全的工具定义]\n```\n\n生成命令：\n```bash\nnpm run generate\n```\n\n生成的代码位于 `src/generated/` 目录，**请勿手动编辑**，所有修改应在 `src/endpoints.json` 中进行后重新生成。\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## Graph 客户端架构\n\n### 请求执行流程\n\n```mermaid\nsequenceDiagram\n participant Tool as MCP 工具调用\n participant GC as GraphClient\n participant Auth as MSAL Auth\n participant Graph as Graph API\n\n Tool->>GC: executeGraphTool(tool, params)\n GC->>GC: 构建请求 URL\n GC->>Auth: 获取访问令牌\n Auth-->>GC: accessToken\n GC->>Graph: HTTP 请求 (Bearer token)\n Graph-->>GC: JSON 响应\n GC->>GC: Zod 验证响应\n GC-->>Tool: 结构化结果\n \n Note over GC: 错误处理：
401 → 刷新令牌重试
429 → 指数退避重试
5xx → 返回错误\n```\n\n### 请求参数处理\n\n| 参数类型 | 处理方式 | 说明 |\n|---------|---------|------|\n| 路径参数 | URL 模板替换 | `/{user-id}/...` → `/{实际ID}/...` |\n| 查询参数 | $filter, $select 等 | 自动编码，支持 OData |\n| 请求体 | POST/PATCH | Zod 验证后 JSON 序列化 |\n\n资料来源：[src/graph-client.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-client.ts)\n\n---\n\n## 项目结构总览\n\n```\nms-365-admin-mcp-server/\n├── bin/ # 代码生成脚本\n│ └── modules/\n│ └── generate-mcp-tools.mjs # OpenAPI → Zod 生成器\n├── src/ # 核心源代码\n│ ├── auth.ts # MSAL 认证模块\n│ ├── auth-bootstrap.ts # RFC 8628 设备码引导\n│ ├── cli.ts # Commander CLI 参数解析\n│ ├── cloud-config.ts # 云配置（全球/世纪互联）\n│ ├── endpoints.json # 工具定义唯一数据源\n│ ├── generated/ # 自动生成的 Zod 客户端\n│ ├── graph-client.ts # Graph API HTTP 封装\n│ ├── graph-tools.ts # MCP 工具注册\n│ ├── http-server.ts # HTTP 传输服务器\n│ ├── index.ts # 应用入口\n│ ├── logger.ts # Winston 日志\n│ ├── risk-level.ts # 风险等级系统\n│ ├── secrets.ts # 密钥提供器（env/Key Vault）\n│ ├── server.ts # STDIO 服务器\n│ ├── token-validator.ts # JWT 验证\n│ └── tool-categories.ts # 预设分类定义\n├── infra/ # 基础设施代码\n│ └── main.bicep # Azure Container Apps 部署\n├── test/ # Vitest 测试\n├── docs/ # 文档\n│ ├── ARCHITECTURE.md\n│ ├── RISK_MODEL.md\n│ └── USE_CASES.md\n├── CONTRIBUTING.md\n├── SECURITY.md\n└── package.json\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## 安全考量\n\n### 权限最小化原则\n\n新工具必须声明最小 Graph API 权限：\n\n| 场景 | 推荐权限 | 禁止权限 |\n|------|---------|---------|\n| 仅读取用户 | `User.Read.All` | `User.ReadWrite.All` |\n| 仅读取组 | `Group.Read.All` | `Group.ReadWrite.All` |\n| 目录读取 | `Directory.Read.All` | `Directory.ReadWrite.All` |\n\n### 关键风险操作\n\n以下操作被分类为 `critical`，需要 MCP 客户端显式授权（`--allow-writes`）：\n\n- `delete-user` - 删除用户（不可逆）\n- `delete-group` - 删除组\n- `delete-application` - 删除应用注册\n- `delete-conditional-access-policy` - 删除条件访问策略\n- `wipe-managed-device` - 远程擦除设备\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n---\n\n## 部署架构\n\n### Azure Container Apps 部署\n\n```mermaid\ngraph TD\n subgraph Azure\n A[客户端] -->|HTTPS| B[Azure Container Apps]\n B --> C[ms-365-admin-mcp-server
容器实例]\n C --> D[Azure Key Vault
密钥存储]\n D --> E[Microsoft Graph API]\n end\n\n subgraph 认证流程\n F[Azure AD App Registration] -->|CLIENT_ID/SECRET| C\n end\n```\n\n环境变量配置：\n\n```bash\nMS365_ADMIN_MCP_CLIENT_ID=\nMS365_ADMIN_MCP_CLIENT_SECRET=<客户端密钥>\nMS365_ADMIN_MCP_TENANT_ID=<租户 ID>\n```\n\n部署模板：`infra/main.bicep`\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## 通信传输层\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [部署指南](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/http-server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/http-server.ts)\n- [src/index.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/index.ts)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n- [src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n- [src/upstream-error.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/upstream-error.ts)\n- [docs/HTTP_DEPLOYMENT.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/HTTP_DEPLOYMENT.md)\n- [docs/TROUBLESHOOTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/TROUBLESHOOTING.md)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# 通信传输层\n\n本文档详细介绍 ms-365-admin-mcp-server 项目中的通信传输层架构，涵盖客户端认证、HTTP 服务器部署、令牌管理以及远程调用的完整流程。\n\n## 概述\n\nms-365-admin-mcp-server 的通信传输层是连接 MCP 客户端（如 Claude Desktop/Code）与 Microsoft Graph API 的核心组件。该层负责处理 OAuth 2.0 身份认证、HTTP 服务器托管、MCP 协议通信以及令牌缓存等关键功能。\n\n项目的通信架构支持两种主要运行模式：\n\n| 运行模式 | 描述 | 适用场景 |\n|---------|------|---------|\n| **本地模式** | 直接在本地运行 MCP 服务器，通过标准输入/输出与客户端通信 | 开发调试、本地使用 |\n| **远程 HTTP 模式** | 通过 HTTP 服务器托管，支持远程客户端访问 | 生产部署、多用户环境 |\n\n资料来源：[CONTRIBUTING.md:35-45]()\n\n## 架构组件\n\n### 核心模块职责\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ MCP 客户端 (Claude) │\n└─────────────────────────────┬───────────────────────────────────┘\n │ HTTP / stdio\n┌─────────────────────────────▼───────────────────────────────────┐\n│ 通信传输层 │\n│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │\n│ │ http-server │ │ auth-bootstrap│ │ auth (MSAL) │ │\n│ └─────────────┘ └──────────────┘ └─────────────────────────┘ │\n└─────────────────────────────┬───────────────────────────────────┘\n │ HTTPS\n┌─────────────────────────────▼───────────────────────────────────┐\n│ Microsoft Graph API │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n| 模块 | 文件 | 主要职责 |\n|------|------|---------|\n| HTTP 服务器 | `src/http-server.ts` | 托管 MCP 端点、处理请求路由 |\n| 认证引导 | `src/auth-bootstrap.ts` | RFC 8628 device_code 流程初始化 |\n| MSAL 认证 | `src/auth.ts` | Microsoft 身份平台客户端凭证流 |\n| CLI 入口 | `src/cli.ts` | 命令行参数解析、模式切换 |\n| 错误处理 | `src/upstream-error.ts` | 上游 API 错误规范化 |\n\n资料来源：[src/http-server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/http-server.ts)、[src/auth-bootstrap.ts:45-60]()\n\n## HTTP 服务器部署\n\n### 部署方式\n\n项目支持多种 HTTP 服务器部署配置，主要通过环境变量和命令行参数进行控制。\n\n#### 环境变量配置\n\n| 环境变量 | 描述 | 默认值 |\n|---------|------|--------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | Azure AD 应用注册客户端 ID | 必需 |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | Azure AD 应用注册客户端密钥 | 必需 |\n| `MS365_ADMIN_MCP_TENANT_ID` | Azure AD 租户 ID | 必需 |\n| `MCP_REMOTE_CONFIG_DIR` | 远程配置目录路径 | `~/.mcp-auth/mcp-remote-/` |\n| `CI` | 是否在 CI 环境运行 | `false` |\n\n资料来源：[CONTRIBUTING.md:30-40]()\n\n#### 命令行参数\n\n```bash\nnode dist/index.js --preset --list-tools\nnode dist/index.js --preset --list-permissions\nnpm run inspector\n```\n\n| 参数 | 描述 |\n|------|------|\n| `--preset ` | 指定工具预设类别 |\n| `--list-tools` | 列出所有可用工具 |\n| `--list-permissions` | 列出所需 Graph API 权限 |\n| `--inspector` | 使用 MCP Inspector 交互式运行 |\n\n资料来源：[src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n\n### MCP Inspector 交互模式\n\n开发调试阶段可以使用 MCP Inspector 进行交互式测试：\n\n```bash\nnpm run inspector\n```\n\n该命令启动交互式调试服务器，便于验证工具注册、权限配置以及请求路由是否正常工作。\n\n资料来源：[CONTRIBUTING.md:43]()\n\n## 认证机制\n\n### MSAL 客户端凭证流\n\n`src/auth.ts` 模块实现了 Microsoft 身份库 (MSAL) 的客户端凭证流，用于服务器到服务器的认证场景。\n\n```typescript\n// 核心认证流程伪代码\nconst clientCredentialFlow = new ClientCredentialFlow({\n clientId: process.env.MS365_ADMIN_MCP_CLIENT_ID,\n clientSecret: process.env.MS365_ADMIN_MCP_CLIENT_SECRET,\n tenantId: process.env.MS365_ADMIN_MCP_TENANT_ID,\n});\n```\n\n此认证方式适用于后台服务场景，不需要用户交互即可获取访问令牌。\n\n资料来源：[src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n\n### RFC 8628 Device Code 引导流程\n\n`src/auth-bootstrap.ts` 实现了 RFC 8628 定义的 device_code 认证流程，专门用于为远程 MCP 客户端预先填充令牌缓存。\n\n#### 核心流程\n\n```\n┌──────────────┐ ┌───────────────┐ ┌──────────────────┐\n│ CLI 工具 │────▶│ OAuth 服务器 │────▶│ 用户设备/浏览器 │\n│ (auth-bootstrap)│ │ (/authorize) │ │ (验证页面) │\n└──────┬───────┘ └───────────────┘ └──────────────────┘\n │ │\n │ 轮询 /token │\n │◀──────────────────────────────────────────┤\n │ │\n ▼ │\n┌──────────────┐ │\n│ 缓存令牌 │ │\n│ _tokens.json│ │\n│ _client_info│ │\n└──────────────┘ │\n```\n\n#### 功能特性\n\n- **缓存键计算**：`md5(serverUrl)`，与 `mcp-remote` 的 `getServerUrlHash` 完全匹配，确保缓存正确关联\n- **缓存路径**：`~/.mcp-auth/mcp-remote-/`\n- **文件权限**：0600（仅所有者读写），保护敏感凭证\n- **剪贴板支持**：自动复制设备代码到剪贴板（`pbcopy`/`clip`/`wl-copy`/`xclip`），CI 或非 TTY 环境自动禁用\n\n资料来源：[src/auth-bootstrap.ts:60-75]()\n\n#### 命令行用法\n\n```bash\nms-365-admin-mcp-auth -s [--scope <范围>] [--cache-dir <路径>]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `-s, --server ` | MCP 服务器 URL（必需），支持带或不带 `/mcp` 后缀 |\n| `--scope ` | 覆盖默认 OAuth 范围（默认使用服务器元数据） |\n| `--cache-dir ` | 覆盖缓存目录路径 |\n\n#### 退出码\n\n| 退出码 | 含义 |\n|-------|------|\n| 0 | 认证成功 |\n| 1 | 用法错误 |\n| 2 | 网络错误 |\n| 3 | 认证被拒绝 |\n| 4 | 超时 |\n\n资料来源：[src/auth-bootstrap.ts:20-35]()\n\n### 令牌缓存机制\n\n认证引导工具生成的缓存文件包含两个关键文件：\n\n| 文件 | 用途 |\n|------|------|\n| `_client_info.json` | OAuth 客户端信息 |\n| `_tokens.json` | 访问令牌和刷新令牌 |\n\n缓存键采用 MD5 哈希算法，直接对应服务器 URL，确保多服务器部署场景下缓存隔离。\n\n资料来源：[src/auth-bootstrap.ts:68-70]()\n\n## 远程 HTTP 服务器架构\n\n### 请求处理流程\n\n```\n ┌─────────────────────────────────┐\n │ HTTP 请求入口 │\n │ (Azure Container Apps / VPS) │\n └───────────────┬─────────────────┘\n │\n ┌───────────────▼─────────────────┐\n │ 请求路由与中间件 │\n │ - 认证验证 │\n │ - 协议解析 │\n └───────────────┬─────────────────┘\n │\n ┌─────────────────────────┼─────────────────────────┐\n │ │ │\n┌─────────▼─────────┐ ┌──────────▼──────────┐ ┌────────▼────────┐\n│ MCP 协议处理器 │ │ 工具注册表 │ │ Graph API │\n│ (method routing) │──▶│ (endpoints.json) │──▶│ 客户端 │\n└───────────────────┘ └─────────────────────┘ └─────────────────┘\n```\n\n### 云端部署注意事项\n\n根据 `docs/TROUBLESHOOTING.md` 文档，远程 HTTP 部署需要考虑以下因素：\n\n| 注意事项 | 说明 |\n|---------|------|\n| **平台 SSO** | Azure AD 条件访问可能触发平台 SSO，导致 device_code 流程复杂化 |\n| **条件访问策略** | 需要确保部署的 MCP 服务器被条件访问策略允许 |\n| **Docker 挂载** | 使用 `--cache-dir` 和 `MCP_REMOTE_CONFIG_DIR` 环境变量支持 Docker 卷挂载 |\n| **多用户场景** | 不同用户需配置独立的缓存目录 |\n\n资料来源：[docs/TROUBLESHOOTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/TROUBLESHOOTING.md)\n\n### 认证流程对比\n\n#### 本地模式（标准输入/输出）\n\n```\nClaude Desktop ──▶ stdio ──▶ MCP Server ──▶ Graph API\n```\n\n- 直接进程间通信\n- 无需网络配置\n- 适用于单用户场景\n\n#### 远程模式（HTTP 服务器）\n\n```\nClaude Desktop/Code ──▶ HTTPS ──▶ MCP Remote Proxy ──▶ MCP Server ──▶ Graph API\n │\n device_code 认证\n (预填充令牌缓存)\n```\n\n- 基于 HTTP 的远程调用\n- 支持分布式部署\n- 需要令牌缓存配置\n\n资料来源：[docs/HTTP_DEPLOYMENT.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/HTTP_DEPLOYMENT.md)\n\n## 错误处理\n\n### 上游错误规范化\n\n`src/upstream-error.ts` 模块负责解析和规范化来自 Microsoft Graph API 的错误响应。\n\n#### 错误代码提取\n\n```typescript\n// 从 OAuth 错误响应中提取 error_codes\nif (parsed.error_codes && Array.isArray(parsed.error_codes)) {\n const codes = parsed.error_codes\n .filter((c) => typeof c === 'number')\n .slice(0, 5);\n if (codes.length > 0) {\n parts.push(`error_codes=[${codes.join(',')}]`);\n }\n}\n```\n\n#### 错误格式化\n\n| 场景 | 输出格式 |\n|------|---------|\n| 可解析的错误 | `error=X error_description=Y error_codes=[...]` |\n| 不可解析响应 | `` |\n| 无可识别字段 | `` |\n\n资料来源：[src/upstream-error.ts:10-25]()\n\n### 认证错误分类\n\n| 错误类型 | 处理方式 |\n|---------|---------|\n| 网络错误 | 退出码 2，可重试 |\n| 认证拒绝 | 退出码 3，检查权限配置 |\n| 超时 | 退出码 4，增加超时配置 |\n\n## 安全性考虑\n\n### 令牌存储安全\n\n| 安全措施 | 实现 |\n|---------|------|\n| 文件权限 | 0600，仅进程所有者可访问 |\n| 缓存隔离 | MD5 URL 哈希确保不同服务器缓存分离 |\n| 环境变量 | 敏感信息通过环境变量注入，避免硬编码 |\n\n资料来源：[src/auth-bootstrap.ts:70]()\n\n### 最小权限原则\n\n新增工具必须声明最小 Graph API 权限，禁止请求 `.ReadWrite.All` 当 `.Read.All` 即可满足需求。\n\n资料来源：[CONTRIBUTING.md:18-20]()\n\n## 配置示例\n\n### 本地开发配置\n\n```bash\n# .env 文件\nMS365_ADMIN_MCP_CLIENT_ID=your-client-id\nMS365_ADMIN_MCP_CLIENT_SECRET=your-client-secret\nMS365_ADMIN_MCP_TENANT_ID=your-tenant-id\n```\n\n### Docker 部署配置\n\n```bash\ndocker run -e MS365_ADMIN_MCP_CLIENT_ID=xxx \\\n -e MS365_ADMIN_MCP_CLIENT_SECRET=xxx \\\n -e MS365_ADMIN_MCP_TENANT_ID=xxx \\\n -e MCP_REMOTE_CONFIG_DIR=/data/mcp-cache \\\n -v /path/to/cache:/data/mcp-cache \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server\n```\n\n### Device Code 认证\n\n```bash\nms-365-admin-mcp-auth -s https://your-host.azurecontainerapps.io/mcp \\\n --cache-dir /data/mcp-cache\n```\n\n## 故障排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|---------|---------|\n| `Server disconnected` | 网络连接问题或服务器未运行 | 检查服务器状态和网络连通性 |\n| 设备代码流程超时 | 用户未在规定时间内完成认证 | 使用较长的超时时间或重新发起流程 |\n| 条件访问阻止 | 平台 SSO 或 CA 策略限制 | 检查并配置条件访问策略 |\n| 缓存权限错误 | Docker 卷挂载权限问题 | 确保挂载目录权限正确 |\n\n资料来源：[docs/TROUBLESHOOTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/TROUBLESHOOTING.md)\n\n## 相关文档\n\n| 文档 | 位置 | 内容 |\n|------|------|------|\n| HTTP 部署指南 | `docs/HTTP_DEPLOYMENT.md` | 远程服务器部署详细说明 |\n| 故障排查指南 | `docs/TROUBLESHOOTING.md` | 常见问题与解决方案 |\n| 贡献指南 | `CONTRIBUTING.md` | 开发设置与代码规范 |\n| 安全模型 | `docs/RISK_MODEL.md` | 风险分级与安全要求 |\n\n---\n\n\n\n## 认证系统\n\n### 相关页面\n\n相关主题：[授权机制](#page-authorization), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/oauth-proxy.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-proxy.ts)\n- [src/token-validator.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/token-validator.ts)\n- [src/jwks-stale-cache.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/jwks-stale-cache.ts)\n- [src/secrets.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/secrets.ts)\n- [src/http-server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/http-server.ts)\n- [src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n \n\n# 认证系统\n\n## 概述\n\nms-365-admin-mcp-server 的认证系统负责保护 MCP 服务器的访问安全，支持两种主要的认证模式：\n\n1. **服务令牌模式（Service Token Mode）**：使用客户端 ID 和客户端密钥进行身份验证，适用于服务到服务的通信\n2. **OAuth 2.0 代理模式（OAuth Mode）**：通过 Microsoft Entra ID 实现用户身份验证，支持 Claude Desktop、Claude Code 和 Claude.ai Web 等客户端的 OAuth 授权流程\n\n该认证系统的核心目标是确保只有经过授权的用户和服务才能调用 Microsoft Graph API 执行租户管理操作。\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[Claude Desktop]\n B[Claude Code]\n C[Claude.ai Web]\n D[第三方 MCP 客户端]\n end\n \n subgraph \"认证层\"\n E[MCP 认证中间件]\n F[OAuth 代理]\n G[令牌验证器]\n H[JWKS 缓存]\n end\n \n subgraph \"Microsoft Entra ID\"\n I[令牌颁发]\n J[JWKS 端点]\n end\n \n subgraph \"资源层\"\n K[Graph API]\n L[MCP 工具]\n end\n \n A --> E\n B --> E\n C --> F\n D --> E\n D --> F\n \n E --> G\n F --> I\n G --> H\n H --> J\n \n E --> L\n G --> K\n F --> K\n```\n\n## 核心组件\n\n### 1. 认证模块（src/auth.ts）\n\n认证模块实现了 MSAL（Microsoft Authentication Library）的客户端凭据流，用于获取访问 Microsoft Graph API 的应用程序级令牌。\n\n| 功能 | 说明 |\n|------|------|\n| 客户端凭据流 | 使用应用 ID 和证书/密钥获取应用级访问令牌 |\n| 云配置支持 | 支持全球云和世纪互联（21Vianet）中国区云端点 |\n| 令牌缓存 | 内置令牌缓存机制，避免频繁请求新令牌 |\n\n### 2. OAuth 代理（src/oauth-proxy.ts）\n\nOAuth 代理实现了完整的 OAuth 2.0 + PKCE 授权代码流程，使 Claude 客户端能够通过 Microsoft Entra ID 进行身份验证。\n\n```mermaid\nsequenceDiagram\n participant Client as Claude 客户端\n participant Proxy as OAuth 代理\n participant Entra as Microsoft Entra ID\n participant Graph as Graph API\n\n Client->>Proxy: GET /.well-known/oauth-authorization-server\n Proxy->>Client: 返回元数据\n \n Client->>Proxy: GET /authorize?response_type=code&...\n Proxy->>Entra: 重定向到 Entra 授权端点\n Entra->>User: 显示登录页面\n User->>Entra: 完成身份验证\n Entra->>Proxy: 重定向回 /callback?code=xxx\n \n Client->>Proxy: POST /token (authorization_code)\n Proxy->>Entra: 使用 code 兑换令牌\n Entra->>Proxy: 返回 access_token, refresh_token\n \n Proxy->>Client: 返回令牌\n \n Client->>Proxy: GET /mcp (Bearer token)\n Proxy->>Graph: 使用 access_token 调用 API\n Graph->>Proxy: 返回数据\n Proxy->>Client: 返回结果\n```\n\n#### OAuth 代理端点\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/.well-known/oauth-authorization-server` | GET | 返回 OAuth 2.0 服务器元数据 |\n| `/.well-known/oauth-protected-resource` | GET | 返回受保护资源元数据（用于客户端发现）|\n| `/authorize` | GET | 授权端点，启动 PKCE 流程 |\n| `/callback` | GET | 授权回调处理 |\n| `/token` | POST | 令牌颁发端点 |\n| `/client/register` | POST | 动态客户端注册（DCR） |\n\n### 3. 令牌验证器（src/token-validator.ts）\n\n令牌验证器负责验证 HTTP 传输模式下传入的 Bearer 令牌，确保令牌的有效性和合法性。\n\n| 验证项目 | 说明 |\n|----------|------|\n| JWT 签名验证 | 使用 JWKS 端点获取公钥验证 JWT 签名 |\n| 颁发者验证 | 确认令牌由预期的 Entra 租户颁发 |\n| 受众验证 | 确认令牌适用于此应用（`aud` 声明）|\n| 租户验证 | 确认令牌来自授权的租户（`tid` 声明）|\n| 用户范围验证 | 确认令牌包含必需的 `scp` 声明（默认 `access_as_user`）|\n\n验证失败时的日志记录包括违规的 `aud`、`tid` 和 `upn` 信息，便于排查问题。\n\n### 4. JWKS 缓存（src/jwks-stale-cache.ts）\n\n为了提高性能和减少网络请求，令牌验证器使用 JWKS 缓存来存储和重用公钥信息。\n\n| 特性 | 说明 |\n|------|------|\n| 内存缓存 | 将 JWKS 数据缓存在内存中 |\n| 过期策略 | 支持配置缓存过期时间 |\n| 后台刷新 | 令牌验证前自动刷新过期缓存 |\n| 错误处理 | 缓存过期时优雅降级 |\n\n### 5. 密钥管理（src/secrets.ts）\n\n密钥管理模块负责从多种来源获取敏感配置信息：\n\n| 来源 | 优先级 | 说明 |\n|------|--------|------|\n| 环境变量 | 最高 | 直接从 `process.env` 读取 |\n| Azure Key Vault | 次高 | 从 Key Vault 获取存储的密钥 |\n| 默认值 | 最低 | 使用编译时默认值 |\n\n支持的密钥类型：\n- `AZURE_CLIENT_ID`：应用（客户端）ID\n- `AZURE_CLIENT_SECRET`：客户端密钥\n- `AZURE_TENANT_ID`：租户 ID\n\n### 6. HTTP 服务器认证中间件（src/http-server.ts）\n\nHTTP 服务器实现了 `/mcp` 端点的 Bearer 令牌验证中间件，遵循 RFC 6750 标准。\n\n```mermaid\nflowchart LR\n A[收到 /mcp 请求] --> B{Authorization Header}\n \n B -->|无或非 Bearer| C[返回 401
WWW-Authenticate Header]\n B -->|有 Bearer| D[提取令牌]\n \n D --> E{令牌类型}\n \n E -->|用户令牌| F[用户令牌验证器]\n E -->|服务令牌| G[服务令牌验证器]\n \n F -->|通过| H[允许访问]\n F -->|失败| I{原因}\n I -->|无授权用户| J[返回 403]\n I -->|其他| K[返回 401]\n \n G -->|通过| H\n G -->|失败| L[返回 403]\n \n H --> M[处理 MCP 请求]\n```\n\n#### WWW-Authenticate 响应头\n\n| 场景 | 状态码 | WWW-Authenticate Header |\n|------|--------|------------------------|\n| 缺少令牌 | 401 | `Bearer resource_metadata=\"...\"` |\n| 令牌验证失败 | 403 | `Bearer resource_metadata=\"...\", error=\"invalid_token\"` |\n\n### 7. 认证引导工具（src/auth-bootstrap.ts）\n\n认证引导工具实现了 RFC 8628 设备代码流，用于在 CLI 环境中自动化 OAuth 认证过程。\n\n| 功能 | 说明 |\n|------|------|\n| 设备代码获取 | 从服务器获取设备代码和用户验证码 |\n| PKCE 支持 | 自动生成 code_verifier 和 code_challenge |\n| 令牌缓存 | 将客户端信息和令牌保存到本地文件 |\n| 缓存目录 | 默认 `$MCP_REMOTE_CONFIG_DIR/mcp-remote-` |\n\n## 认证流程\n\n### 服务令牌模式\n\n```mermaid\ngraph LR\n A[客户端] -->|携带 Bearer Token| B[MCP 中间件]\n B --> C[令牌验证器]\n C -->|验证 JWT 签名| D[JWKS 缓存]\n D -->|返回公钥| C\n C -->|验证声明| E{验证结果}\n E -->|通过| F[Graph API 调用]\n E -->|失败| G[返回 401/403]\n```\n\n### OAuth 模式\n\n```mermaid\ngraph TD\n A[Claude Desktop 启动] -->|无缓存令牌| B[发起设备代码流]\n B --> C[auth-bootstrap 获取设备代码]\n C --> D[用户完成浏览器认证]\n D --> E[缓存令牌到本地]\n E --> F[MCP 连接携带缓存令牌]\n F --> G[OAuth 代理验证令牌]\n G -->|有效| H[允许 Graph API 调用]\n G -->|无效/过期| I[使用 refresh_token 刷新]\n I -->|刷新成功| H\n I -->|刷新失败| J[提示重新认证]\n```\n\n## 安全配置\n\n### 启动参数\n\n| 参数 | 说明 | 默认值 | 安全性 |\n|------|------|--------|--------|\n| `--allowed-clients` | 允许的服务客户端 ID 列表 | 必需（无默认）| P1 |\n| `--oauth-mode` | 启用 OAuth 2.0 代理模式 | false | P1 |\n| `--authorized-users` | OAuth 模式下允许的用户 OID 列表 | 必需（无默认值）| P1 |\n| `--allow-any-tenant-user` | 允许任意租户用户（需明确启用）| false | P1 |\n| `--public-url` | OAuth 模式的公共 URL | 必需（behind proxy 时）| P1 |\n| `--required-user-scopes` | 用户令牌必需的 scope | `access_as_user` | P1 |\n| `--client-secret` | 服务客户端密钥 | 从环境变量获取 | P2 |\n| `--trusted-ip-headers` | 信任的 IP 来源头 | 无 | P2 |\n\n### 安全修复记录\n\n| 标识 | 描述 | 版本 | 严重性 |\n|------|------|------|--------|\n| SEC-F01 | OAuth 模式在空用户白名单时失败关闭 | 0.2.0 | P1 |\n| SEC-F02 | `--public-url` 对 OAuth 模式为必需项 | 0.2.0 | P1 |\n| SEC-F03 | 新增 `--required-user-scopes` 强制验证 scope 声明 | 0.2.3 | P1 |\n| SEC-F04 | `/token` 端点速率限制：10 req/min/IP | 0.2.3 | P1 |\n| SEC-F05 | PKCE 桥接内存化，降低多副本部署风险 | 0.2.3 | P1 |\n\n## 部署注意事项\n\n### OAuth 模式部署\n\nOAuth 模式部署需要满足以下条件：\n\n1. **Entra 应用注册配置**：\n - 公开暴露 `access_as_user` 委托 scope（`api:///access_as_user`）\n - 配置 `requestedAccessTokenVersion: 2`\n - 授予管理员同意\n\n2. **网络配置**：\n - 必须设置 `--public-url`（反向代理后必需）\n - 配置 `trust proxy` 设置（如适用）\n\n3. **多副本部署**：\n - 由于 PKCE 桥接内存化特性，默认单副本部署\n - 多副本部署需显式设置 `maxReplicas` 并考虑外部化 PKCE 桥接\n\n### 从旧版本迁移\n\n| 场景 | 操作 |\n|------|------|\n| 使用 OAuth 模式且依赖\"任意认证用户\"行为 | 添加 `--allow-any-tenant-user` |\n| OAuth 模式部署在反向代理后 | 添加 `--public-url https://` |\n| Entra 应用未暴露 `access_as_user` scope | 添加 `--required-user-scopes \"\"` |\n| Bicep 部署依赖默认 `maxReplicas = 3` | 显式设置 `maxReplicas` |\n\n## 相关文件\n\n| 文件 | 职责 |\n|------|------|\n| `src/auth.ts` | MSAL 客户端凭据流实现 |\n| `src/oauth-proxy.ts` | OAuth 2.0 授权代码流代理 |\n| `src/token-validator.ts` | JWT 令牌验证 |\n| `src/jwks-stale-cache.ts` | JWKS 密钥缓存管理 |\n| `src/secrets.ts` | 密钥和环境变量管理 |\n| `src/http-server.ts` | HTTP 传输和认证中间件 |\n| `src/auth-bootstrap.ts` | RFC 8628 设备代码引导 |\n| `infra/main.bicep` | Azure Container Apps 部署配置 |\n\n---\n\n\n\n## 授权机制\n\n### 相关页面\n\n相关主题：[认证系统](#page-authentication), [风险模型](#page-risk-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/user-token-authorization.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/user-token-authorization.ts)\n- [src/user-token-validator.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/user-token-validator.ts)\n- [src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n- [src/oauth-proxy.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-proxy.ts)\n- [src/oauth-rate-limiters.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-rate-limiters.ts)\n- [src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n \n\n# 授权机制\n\n## 概述\n\nms-365-admin-mcp-server 的授权机制采用分层设计，支持两种主要的认证模式：**OAuth 2.0 代理模式**和**服务令牌模式**。系统通过用户令牌授权模块验证调用者身份，并结合速率限制和范围检查确保安全性。\n\n授权机制的核心职责包括：\n- 验证用户令牌的签名、颁发者和范围\n- 实施基于允许列表的访问控制\n- 提供细粒度的范围（scope）验证\n- 支持 Entra ID（Azure AD）集成的 OAuth 2.0 流程\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[HTTP 请求] --> B[/mcp 认证中间件]\n B --> C{OAuth 模式启用?}\n C -->|是| D[用户令牌验证]\n C -->|否| E{允许客户端模式?}\n E -->|是| F[服务令牌验证]\n E -->|否| G[返回 403]\n \n D --> H{令牌有效?}\n D --> I{在授权用户列表?}\n D --> J{范围满足?}\n \n H -->|否| K[返回 invalid_token / 401]\n I -->|否| L[返回 unauthorized / 403]\n J -->|否| M[返回 insufficient_scope / 403]\n \n H -->|是| I\n I -->|是| J\n J -->|是| N[提取 claims
oid, upn, name, appid]\n \n F --> O[验证服务令牌签名]\n O -->|成功| P[允许访问]\n \n N --> P\n```\n\n## 用户令牌授权\n\n### 核心验证流程\n\n用户令牌授权模块（`src/user-token-authorization.ts`）负责验证通过 OAuth 2.0 流程获取的用户令牌。验证过程遵循以下步骤：\n\n1. **签名验证** — 验证 JWT 签名来自可信的 JWKS 端点\n2. **声明验证** — 检查 `aud`（受众）、`tid`（租户 ID）等关键声明\n3. **用户白名单检查** — 验证 `upn` 是否在授权用户列表中\n4. **范围验证** — 确认令牌包含所需的 OAuth 范围\n\n### 关键函数\n\n```typescript\nexport function authorizeUserClaims(\n payload: UserTokenPayload,\n options: UserTokenValidatorOptions\n): UserTokenAuthorizationResult\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `payload` | `UserTokenPayload` | 解码后的 JWT 载荷 |\n| `options.requiredScopes` | `string[]` | 必需的 OAuth 范围列表 |\n| `options.authorizedUsers` | `string[]` | 授权用户 UPN 列表 |\n| `options.requiredAudiences` | `string[]` | 必需的受众声明 |\n| `options.requiredTenantId` | `string` | 必需的租户 ID |\n\n**返回值：**\n\n| 字段 | 说明 |\n|------|------|\n| `ok: true` | 授权成功，返回包含 `claims` 的对象 |\n| `ok: false` | 授权失败，`reason` 指示失败原因 |\n\n### 失败原因与 HTTP 状态码\n\n| 失败原因 | HTTP 状态 | 说明 |\n|----------|-----------|------|\n| `invalid_token` | 401 | 令牌格式错误或签名验证失败 |\n| `insufficient_scope` | 403 | 令牌缺少必需的范围 |\n| `unauthorized_user` | 403 | 用户不在授权列表中 |\n\n```typescript\n// 资料来源：src/user-token-authorization.ts:46-52\nif (missing.length > 0) {\n logger.warn(\n `User token missing required scope(s): ${missing.join(', ')}; token scp=${payload.scp ?? ''}`\n );\n return { ok: false, reason: 'insufficient_scope' };\n}\n```\n\n### 范围解析逻辑\n\n系统通过 `parseTokenScopes` 函数解析令牌中的 `scp` 声明，并与必需范围进行比对：\n\n```mermaid\ngraph LR\n A[scp 声明] --> B{解析范围列表}\n B --> C[requiredScopes]\n C --> D[过滤出不匹配项]\n D --> E{missing.length > 0?}\n E -->|是| F[返回 insufficient_scope]\n E -->|否| G[授权通过]\n```\n\n## OAuth 2.0 代理模式\n\n### 概述\n\n当服务器以 `--oauth-mode` 运行时，启用 OAuth 2.0 代理功能。用户通过 Entra ID 进行身份验证后，服务器代理令牌交换和验证流程。\n\n### 端点列表\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/.well-known/oauth-authorization-server` | GET | OAuth 发现文档 |\n| `/.well-known/oauth-protected-resource` | GET | 受保护资源元数据 |\n| `/authorize` | GET | 授权请求入口 |\n| `/token` | POST | 令牌交换 |\n| `/devicecode` | POST | 设备代码流 |\n\n### 授权流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant S as MCP Server\n participant E as Entra ID\n \n U->>S: 访问 MCP 端点 (无令牌)\n S->>U: 返回 401 + WWW-Authenticate\n U->>S: GET /authorize\n S->>E: 重定向到 Entra ID
client_id, redirect_uri, scope\n E->>U: 登录页面\n U->>E: 完成身份验证 + MFA\n E->>S: redirect_uri + auth_code\n S->>E: POST /token
client_id, client_secret, code\n E->>S: access_token, refresh_token\n S->>U: 返回令牌给客户端\n```\n\n### 客户端认证\n\nOAuth 代理在 `/token` 端点强制要求客户端凭证：\n\n```typescript\n// 资料来源：src/oauth-proxy.ts:85-100\nconst { clientId: reqClientId, clientSecret: reqClientSecret } = extractClientCredentials(req);\nif (!reqClientId || !reqClientSecret) {\n res.status(401).json({\n error: 'invalid_client',\n error_description: 'Missing client_id or client_secret',\n });\n return;\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| `client_id` | 注册的 OAuth 应用客户端 ID |\n| `client_secret` | 对应的客户端密钥 |\n\n### 设备代码引导\n\n对于无浏览器环境，服务器提供 RFC 8628 设备代码流程：\n\n```bash\nms-365-admin-mcp-auth -s https://your-host.azurecontainerapps.io/mcp\n```\n\n**工作流程：**\n\n1. 客户端向 `/devicecode` 请求设备代码\n2. 服务器返回 `device_code` 和 `user_code`\n3. 用户在另一设备访问 `verification_uri` 并输入 `user_code`\n4. 轮询 `/token` 直到授权完成\n\n```typescript\n// 资料来源：src/auth-bootstrap.ts:60-80\nconst { verification_uri, user_code, device_code, interval, expires_in } = await getDeviceCode(\n serverUrl,\n clientId,\n scope\n);\n```\n\n## 服务令牌模式\n\n### 概述\n\n当部署使用 `--allowed-clients` 参数时，系统接受预注册的服务令牌（如 MCP Remote 客户端令牌）。\n\n### 认证中间件顺序\n\n```mermaid\ngraph TD\n A[请求到达 /mcp] --> B{oauth-mode 启用?}\n B -->|是| C[尝试用户令牌验证]\n B -->|否| D{allowed-clients 启用?}\n \n C --> E{用户令牌验证成功?}\n E -->|是| F[允许访问]\n E -->|否| G{allowed-clients 启用?}\n \n D -->|是| H[尝试服务令牌验证]\n D -->|否| I[返回 403]\n \n H --> J{服务令牌验证成功?}\n J -->|是| F\n J -->|否| I\n G -->|是| H\n G -->|否| I\n```\n\n### 令牌缓存\n\n用户令牌和客户端信息缓存到本地目录：\n\n```bash\n$MCP_REMOTE_CONFIG_DIR/mcp-remote-/\n├── client-info.json\n└── tokens.json\n```\n\n缓存文件权限设置为 `0700`（目录）和 `0600`（文件），确保令牌安全存储。\n\n## 速率限制\n\n### 限制器配置\n\n系统通过 `src/oauth-rate-limiters.ts` 为 OAuth 端点配置多层速率限制：\n\n| 端点 | 限制器 | 窗口 | 最大请求 |\n|------|--------|------|----------|\n| `/token` (device_code) | `tokenDevicePollLimiter` | 1 分钟 | 10 次 |\n| `/token` (其他) | `tokenTightLimiter` | 1 分钟 | 5 次 |\n| `/register` | `tokenTightLimiter` | 1 分钟 | 5 次 |\n| `/devicecode` | `tokenTightLimiter` | 1 分钟 | 5 次 |\n\n### 设备代码轮询限制\n\n设备代码轮询（polling）有特殊的速率限制，防止客户端过度请求：\n\n```typescript\n// 资料来源：src/oauth-rate-limiters.ts:25-35\nconst tokenDevicePollLimiter = rateLimit({\n windowMs: 60 * 1000,\n max: 10,\n standardHeaders: true,\n legacyHeaders: false,\n message: {\n error: 'invalid_request',\n error_description: 'Too many device_code poll requests',\n },\n});\n```\n\n## CLI 配置选项\n\n通过 `src/cli.ts` 暴露的启动参数控制授权行为：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--oauth-mode` | 启用 OAuth 2.0 代理模式 | `false` |\n| `--allowed-clients` | 允许的服务客户端 ID 列表（逗号分隔） | 无 |\n| `--public-url` | OAuth 模式下的公共 URL | 必需（OAuth 模式下） |\n| `--required-user-scopes` | 必需的 OAuth 用户范围 | 必需（OAuth 模式下） |\n| `--allow-any-tenant-user` | 允许任何已验证租户的用户 | `false` |\n\n### 必需参数组合\n\n```mermaid\ngraph TD\n A[启动参数检查] --> B{OAuth 模式?}\n B -->|是| C{提供 --public-url?}\n C -->|否| D[错误：需要 public-url]\n C -->|是| E{提供 --required-user-scopes?}\n E -->|否| F[使用默认值]\n E -->|是| G[使用指定范围]\n \n B -->|否| H{提供 --allowed-clients?}\n H -->|否| I[错误：需要 allowed-clients 或 oauth-mode]\n H -->|是| J[启动成功]\n```\n\n### 示例启动命令\n\n```bash\n# OAuth 模式（Claude Desktop 集成）\nms-365-admin-mcp-server --transport streamable-http \\\n --oauth-mode \\\n --public-url https://mcp.contoso.com \\\n --required-user-scopes \"access_as_user\"\n\n# 服务客户端模式\nms-365-admin-mcp-server --transport streamable-http \\\n --allowed-clients \"client-id-1,client-id-2\"\n\n# 混合模式\nms-365-admin-mcp-server --transport streamable-http \\\n --oauth-mode \\\n --allowed-clients \"legacy-client-id\" \\\n --public-url https://mcp.contoso.com\n```\n\n## 安全考量\n\n### 令牌验证原则\n\n1. **签名验证优先** — 所有 JWT 必须通过 JWKS 验证签名\n2. **范围最小化** — 仅接受明确声明的范围\n3. **租户隔离** — 除非明确允许，否则仅接受同一租户的用户\n4. **客户端认证** — OAuth 端点强制要求客户端凭证\n\n### 日志记录\n\n授权失败时，系统记录详细诊断信息：\n\n```typescript\n// 资料来源：src/user-token-authorization.ts:40-45\nlogger.warn(\n `User (${upnForLog}) not in authorized-users allowlist`\n);\nreturn { ok: false, reason: 'invalid_token' };\n```\n\n日志包含的信息：\n- 用户主体名称（UPN）\n- 缺失的范围列表\n- 令牌受众（aud）和租户 ID（tid）\n\n### 速率限制保护\n\n- 防止设备代码轮询滥用\n- 限制令牌注册请求频率\n- 防止暴力破解客户端凭证\n\n## 迁移指南\n\n### 从旧版本升级\n\n| 版本 | 变更 |\n|------|------|\n| 0.2.0+ | 新增 `--oauth-mode` 支持 |\n| 0.2.4+ | 允许客户端参数变为可选（需要 `--oauth-mode` 或 `--allowed-clients`） |\n\n### 常见配置错误\n\n| 错误 | 解决方案 |\n|------|----------|\n| `ERR_MISSING_PUBLIC_URL` | 添加 `--public-url` 参数 |\n| `ERR_MISSING_REQUIRED_SCOPES` | 添加 `--required-user-scopes` 参数 |\n| `ERR_RATE_LIMIT_EXCEEDED` | 减少设备代码轮询频率 |\n\n## 参考资料\n\n- 授权核心实现：[src/user-token-authorization.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/user-token-authorization.ts)\n- OAuth 代理：[src/oauth-proxy.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-proxy.ts)\n- 设备代码引导：[src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n- 速率限制：[src/oauth-rate-limiters.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-rate-limiters.ts)\n- CLI 配置：[src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n- 安全审查文档：[docs/SECURITY_REVIEW_2026-04-20.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/SECURITY_REVIEW_2026-04-20.md)\n\n---\n\n\n\n## 工具分类系统\n\n### 相关页面\n\n相关主题：[核心功能特性](#page-features), [风险模型](#page-risk-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [agent-skills/ms365-admin-mcp/SKILL.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/SKILL.md)\n- [agent-skills/ms365-admin-mcp/references/tools-catalog.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n \n\n# 工具分类系统\n\n## 概述\n\n工具分类系统（Tool Categories System）是 ms-365-admin-mcp-server 项目中用于组织和管理 515 个 Microsoft Graph API 工具的核心组件。该系统通过正则表达式模式匹配将工具自动归类到不同的功能域，使管理员和 AI 代理能够根据业务场景快速定位所需工具。 资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:1]()\n\n### 核心设计目标\n\n| 目标 | 说明 |\n|------|------|\n| **按领域组织** | 将 515 个工具按功能域（安全、身份、合规等）分组 |\n| **模式匹配** | 使用正则表达式自动识别工具所属分类 |\n| **预设管理** | 支持通过 `--preset` 参数动态加载相关工具集 |\n| **风险分层** | 每个分类关联特定的风险级别，便于权限管控 |\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[endpoints.json] --> B[工具注册表]\n B --> C{工具分类器}\n C --> D[TOOL_CATEGORIES]\n C --> E[CLI preset 参数]\n \n D --> F[security
audit
health
reports]\n D --> G[identity
governance
response]\n D --> H[exchange
intune
ediscovery]\n D --> I[cloudpc
callrecords
print
infoprotection
sharepointadmin
retention]\n \n E --> J[list-tools
filter by pattern]\n \n F --> K[MCP Inspector
动态加载]\n G --> K\n H --> K\n I --> K\n```\n\n### 核心接口定义\n\n工具分类系统定义了一个简洁的接口，包含三个必需属性： 资料来源：[src/tool-categories.ts:1-5]()\n\n```typescript\nexport interface ToolCategory {\n name: string; // 分类唯一标识符\n pattern: RegExp; // 匹配工具名称的正则表达式\n description: string; // 人类可读的分类描述\n}\n```\n\n## 分类清单\n\n### 完整分类对照表\n\n| 分类名称 | 模式关键词 | 描述 | 文档参考 |\n|----------|------------|------|----------|\n| `security` | security, alert, incident, attack-simulation, threat-intel | Microsoft 365 Defender 安全告警、事件、攻击模拟和威胁情报 | usecase-security.md |\n| `audit` | audit, sign-in, provisioning, directory, deleted-user, deleted-group | 审计日志、目录审计、登录记录和已删除项目 | usecase-audit.md |\n| `health` | service, health, issue, message | 服务健康状态和消息中心公告 | usecase-health.md |\n| `reports` | report, activity, usage | Teams、邮箱、SharePoint、OneDrive、M365 应用使用报告 | usecase-reports.md |\n| `identity` | user, group, role, conditional, directory, domain, auth-method, credential, application, service-principal, sp-password, sp-key, sp-token, sp-owner, oauth2, organization, named-location, device, administrative-unit, cross-tenant, pim, app-role, invitation, identity-provider, b2x, api-connector, custom-auth | Entra ID 用户、组、角色、设备、PIM、来宾用户、外部身份的身份和访问管理 | usecase-identity.md |\n| `governance` | role-resource-namespace | 访问评审、权利管理、生命周期工作流、角色/组 PIM、使用条款、应用同意的身份治理 | usecase-governance.md |\n| `response` | disable-user, revoke, block, reset, isolate, update-security, delete-user-auth, delete-user-phone, update-device, update-user-auth, confirm-compromised, dismiss-risky, confirm-safe, hunting-query, wipe-managed, retire-managed, remote-lock, locate-managed, bypass-activation, apply-hold, remove-hold | 事件响应操作（禁用用户、撤销会话、确认泄露/安全、 dismissal 风险、威胁狩猎查询） | usecase-response.md |\n| `ediscovery` | ediscovery | Microsoft Purview 电子发现案例 | usecase-ediscovery.md |\n| `cloudpc` | cloud-pc, provisioning-polic | Cloud PC / Windows 365（云电脑、配置策略、设备镜像） | usecase-cloudpc.md |\n| `callrecords` | call-record, call-session, pstn-call, direct-routing | Teams 通话记录（会话、分段、参与方、PSTN 通话、直接路由） | usecase-callrecords.md |\n| `print` | print | 通用打印（打印机、共享、连接器、服务、任务定义） | usecase-print.md |\n| `infoprotection` | sensitivity, bitlocker, threat-assessment, mip | BitLocker、威胁评估、敏感度标签 | usecase-infoprotection.md |\n| `sharepointadmin` | spo, sharepoint | SharePoint 租户管理 | usecase-sharepointadmin.md |\n| `retention` | retention, records | 记录管理 | usecase-retention.md |\n| `exchange` | exchange, mailbox, message-trace | 消息追踪、邮箱管理 | usecase-exchange.md |\n| `intune` | intune, mdm, mam, compliance, autopilot | 设备管理、合规配置、Autopilot、应用保护策略 | usecase-intune.md |\n| `teamsadmin` | teams, channel, meeting | Teams 团队、频道、会议、应用设置 | usecase-teamsadmin.md |\n\n资料来源：[src/tool-categories.ts:7-85]()\n\n## 使用方式\n\n### 命令行预设加载\n\n通过 `--preset` 参数加载特定分类的工具集：\n\n```bash\n# 列出所有安全相关工具\nnode dist/index.js --preset security --list-tools\n\n# 列出所有身份管理工具\nnode dist/index.js --preset identity --list-tools\n\n# 列出所有合规相关工具\nnode dist/index.js --preset compliance --list-tools\n```\n\n### 验证工具分类\n\n检查特定工具是否被正确分类：\n\n```bash\nnode dist/index.js --preset mypreset --list-tools\n```\n\n资料来源：[CONTRIBUTING.md:27-30]()\n\n## 扩展机制\n\n### 添加新分类\n\n在 `src/tool-categories.ts` 文件中扩展 `TOOL_CATEGORIES` 对象：\n\n```typescript\nexport const TOOL_CATEGORIES: Record = {\n // ... 现有分类 ...\n mypreset: {\n name: 'mypreset',\n pattern: /pattern-matching-tool-names/i,\n description: 'Short human-readable description',\n },\n};\n```\n\n### 分类匹配规则\n\n正则表达式必须能够匹配 `endpoints.json` 中定义的 `toolName`。验证方法：\n\n```bash\nnode dist/index.js --preset mypreset --list-tools | grep list-something\n```\n\n资料来源：[CONTRIBUTING.md:20-32]()\n\n## 与风险级别系统的集成\n\n工具分类系统与风险级别系统（risk-level.ts）协同工作，为每个操作提供安全保障：\n\n```typescript\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n if (configuredRiskLevel) return configuredRiskLevel;\n // GET 请求默认为 low，危险操作默认为 critical\n return method.toUpperCase() === 'GET' ? 'low' : 'critical';\n}\n```\n\n### 风险级别分类\n\n| 级别 | 描述 | 包含的操作类型 |\n|------|------|----------------|\n| `low` | 仅读取或无害操作 | GET 请求、报表生成 |\n| `medium` | 可逆的单实体变更 | update-user, add-group-member |\n| `high` | 影响范围大或凭证变更 | revoke-user-sessions, update-conditional-access-policy |\n| `critical` | 不可逆或租户级影响 | delete-user, wipe-managed-device, delete-conditional-access-policy |\n\n资料来源：[src/risk-level.ts:1-25]()\n\n## 技术实现细节\n\n### 模式匹配优先级\n\n当一个工具名称同时匹配多个分类的正则表达式时，系统按以下原则处理：\n\n1. **最长匹配优先** — 选择模式最具体的分类\n2. **精确分类优先** — 明确命名的分类（如 `ediscovery`）优先于宽泛匹配\n3. **配置覆盖** — `endpoints.json` 中的显式分类配置优先于自动匹配\n\n### 分类与文档映射\n\n工具目录（tools-catalog.md）建立了分类与用例文档的完整映射：\n\n```mermaid\ngraph LR\n A[security preset] --> B[usecase-security.md]\n A --> C[usecase-threatintel.md]\n D[identity preset] --> E[usecase-identity.md]\n F[compliance preset] --> G[usecase-compliance.md]\n F --> H[usecase-response.md]\n```\n\n每个用例文档包含：\n\n- 工具清单表格（操作、用途、风险级别）\n- 常见操作模式（Pattern）\n- 安全护栏（Guardrails）\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:1-50]()\n\n## 开发工作流\n\n### 添加新工具到现有分类\n\n1. 在 `src/endpoints.json` 中添加工具定义\n2. 运行 `npm run generate` 重新生成客户端代码\n3. 验证工具是否被正确分类：`node dist/index.js --list-tools | grep `\n4. 检查所需 Graph API 权限：`node dist/index.js --list-permissions | grep `\n\n### 创建新分类\n\n1. 编辑 `src/tool-categories.ts` 添加新的 `ToolCategory` 条目\n2. 编写对应的 `usecase-.md` 参考文档\n3. 在 `agent-skills/ms365-admin-mcp/references/tools-catalog.md` 中添加索引\n4. 运行测试验证：`npm run verify`\n\n资料来源：[CONTRIBUTING.md:33-75]()\n\n## 总结\n\n工具分类系统是 ms-365-admin-mcp-server 的核心组织机制，通过 16 个预设分类覆盖了 Microsoft 365 管理的全部功能域。系统利用正则表达式模式实现自动化分类，结合风险级别系统提供了完整的安全保障。该设计遵循了最小权限原则，所有新工具必须声明最小必需的 Graph API 权限，且非 GET 操作必须明确标注风险级别。\n\n---\n\n\n\n## 风险模型\n\n### 相关页面\n\n相关主题：[授权机制](#page-authorization), [工具分类系统](#page-tool-categories)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/RISK_MODEL.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/RISK_MODEL.md)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [agent-skills/ms365-admin-mcp/references/tools-catalog.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n- [agent-skills/ms365-admin-mcp/references/usecase-compliance.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/usecase-compliance.md)\n \n\n# 风险模型\n\n## 概述\n\n风险模型是 ms-365-admin-mcp-server 安全架构的核心组件，为所有管理工具提供风险级别的分类和访问控制机制。该模型确保高风险操作得到适当的审查和确认，防止意外或恶意的租户级别更改。\n\n风险模型的主要职责包括：\n\n- 为每个管理工具分配明确的风险等级（`low`、`medium`、`high`、`critical`）\n- 提供运行时风险级别检查机制\n- 支持通过 CLI 参数 `--max-risk-level` 限制可执行的最高风险级别\n- 默认为安全策略：未明确标注的写操作自动归类为 `critical`\n\n资料来源：[src/risk-level.ts:1-30](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n## 风险等级定义\n\n### 四级风险体系\n\n| 风险等级 | 判定标准 | 示例工具 |\n|---------|---------|---------|\n| `low` | 只读效果（POST 查询、报告）或trivial注解 | `run-hunting-query`、`add-security-alert-comment`、Intune 报告 |\n| `medium` | 可逆的单一实体变更 | `update-user`、`add-group-member`、`create-invitation` |\n| `high` | 重大影响：范围广、凭证变更或破坏性操作 | `revoke-user-sessions`、`update-conditional-access-policy` |\n| `critical` | 不可逆或租户级别影响 | `delete-user`、`wipe-managed-device`、`delete-conditional-access-policy` |\n\n资料来源：[CONTRIBUTING.md:55-60](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n### 判定规则\n\n风险等级判定遵循以下原则：\n\n1. **已配置风险优先**：如果工具显式配置了 `configuredRiskLevel`，直接使用该值\n2. **方法默认策略**：未配置的工具，GET 请求默认为 `low`，写操作默认为 `critical`（fail-safe 机制）\n3. **高风险优先原则**：难以判断时，选择更高的风险等级\n\n```typescript\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n if (configuredRiskLevel) return configuredRiskLevel;\n return method.toUpperCase() === 'GET' ? 'low' : 'critical';\n}\n```\n\n资料来源：[src/risk-level.ts:15-22](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n## 风险级别函数\n\n### 函数列表\n\n```typescript\n// 计算有效风险级别\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel\n\n// 检查工具是否在允许范围内\nexport function isToolAllowed(\n configuredRiskLevel: RiskLevel | undefined,\n method: string,\n maxRiskLevel: RiskLevel\n): boolean\n```\n\n### 级别排序\n\n风险级别按严重程度排序为：`low < medium < high < critical`\n\n```typescript\nfunction rank(level: RiskLevel): number {\n const ranking: Record = {\n low: 0,\n medium: 1,\n high: 2,\n critical: 3,\n };\n return ranking[level];\n}\n```\n\n### 允许检查逻辑\n\n工具是否允许执行取决于其有效风险级别是否不超过配置的最大风险级别：\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B{获取有效风险级别}\n B --> C{获取最大风险级别 cap}\n C --> D{rank有效级别 <= rank最大级别?}\n D -->|是| E[允许执行]\n D -->|否| F[拒绝执行 + 提示]\n```\n\n资料来源：[src/risk-level.ts:25-30](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n## CLI 风险控制\n\n### 命令行参数\n\n| 参数 | 说明 | 隐含效果 |\n|-----|------|---------|\n| `--allow-writes` | 允许执行写操作 | 启用写入工具注册 |\n| `--max-risk-level ` | 设置最高可执行风险级别 | 隐含 `--allow-writes`，隐藏更高级别工具 |\n\n### 风险限制示例\n\n```bash\n# 只允许只读操作\nms-365-admin-mcp-server --max-risk-level low\n\n# 允许低和中风险操作\nms-365-admin-mcp-server --max-risk-level medium\n\n# 允许所有操作（含高风险）\nms-365-admin-mcp-server --max-risk-level high\n\n# 允许所有操作（含关键风险）\nms-365-admin-mcp-server --max-risk-level critical\n```\n\n资料来源：[CHANGELOG.md:1-20](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n\n## 关键工具风险映射\n\n### Critical 级别工具（需带外审批）\n\n以下工具具有不可逆或租户级别影响，执行前必须获得正式变更请求审批：\n\n| 工具名称 | 影响描述 |\n|---------|---------|\n| `delete-user` | 永久删除用户账户 |\n| `delete-group` | 永久删除安全组/Microsoft 365 组 |\n| `delete-application` | 删除应用注册 |\n| `delete-service-principal` | 删除服务主体 |\n| `delete-conditional-access-policy` | 删除条件访问策略 |\n| `delete-exchange-mailbox` | 删除 Exchange 邮箱 |\n| `delete-ediscovery-case` | 删除 eDiscovery 案例 |\n| `delete-team` | 删除 Teams 团队 |\n| `delete-managed-device` | 删除托管设备记录 |\n| `wipe-managed-device` | 完全擦除设备数据 |\n| `clean-windows-device` | 清理 Windows 设备 |\n| `add-directory-role-member` | 添加特权目录角色成员 |\n| `create-pim-role-assignment-request` | 特权角色的 PIM 分配请求 |\n| `create-pim-role-eligibility-request` | 特权角色资格请求 |\n| `disable-user-account` | 禁用特权或紧急访问账户 |\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:30-45](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n### High 级别工具（需明确确认 + 预演）\n\n| 工具名称 | 风险描述 |\n|---------|---------|\n| `revoke-user-sessions` | 撤销用户所有会话，影响用户当前工作 |\n| `confirm-compromised-users` | 确认用户账户已被泄露 |\n| `confirm-safe-users` | 将用户标记为安全（误报处理） |\n| `dismiss-risky-users` | 忽略风险用户 |\n| `confirm-compromised-service-principals` | 确认服务主体泄露 |\n| `dismiss-risky-service-principals` | 忽略风险服务主体 |\n| `delete-user-phone-auth-method` | 删除用户手机认证方法 |\n| `change-user-password` | 更改用户密码 |\n| `update-device` | 更新设备配置 |\n| `create-conditional-access-policy` | 创建条件访问策略 |\n| `update-conditional-access-policy` | 更新条件访问策略 |\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:50-60](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n### 敏感读取工具\n\n某些 GET 操作因暴露敏感信息也被标注风险级别：\n\n| 风险等级 | 工具类型 | 示例 |\n|---------|---------|------|\n| `high` | 密钥/恢复信息 | BitLocker 恢复密钥、LAPS 密码 |\n| `medium` | 认证信息 | 认证方法、登录记录、风险检测 |\n| `high` | 合规数据 | eDiscovery 案例、保管人、搜索、主题权限请求 |\n\n资料来源：[CHANGELOG.md:1-20](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n\n## 高危操作安全模式\n\n### 必须遵循的操作流程\n\n对于 `high` 和 `critical` 级别的工具，必须执行以下序列：\n\n```mermaid\ngraph TD\n A[识别目标对象] --> B[预演 Dry-Run]\n B --> C[读取目标对象详情]\n C --> D[列出预期影响]\n D --> E[请求明确确认]\n E --> F{确认?}\n F -->|是| G[执行操作]\n F -->|否| H[取消操作]\n G --> I[记录审计日志]\n```\n\n### 标准确认话术\n\n执行高风险操作前，必须向操作员说明：\n\n> \"即将调用 `<工具名称>` 对 `<目标>` 执行 `<影响描述>`。此操作 `<可逆性/不可逆>`。是否确认执行？\"\n\n资料来源：[agent-skills/ms365-admin-mcp/SKILL.md:50-70](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/SKILL.md)\n\n## 工具目录中的风险索引\n\n工具目录按预设（preset）和风险级别双重索引，便于快速查找：\n\n```mermaid\ngraph LR\n A[工具目录] --> B[按预设索引]\n A --> C[按风险级别索引]\n B --> B1[security
audit
health
reports
identity
exchange
intune
governance
compliance
response
ediscovery
cloudpc
callrecords
print
infoprotection
sharepointadmin
retention]\n C --> C1[Critical
需带外审批]\n C --> C2[High
确认+预演]\n C --> C3[Medium
明确确认]\n C --> C4[Low
常规操作]\n```\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:1-30](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n## 安全集成\n\n### 与其他安全机制的关系\n\n| 安全组件 | 集成点 | 说明 |\n|---------|-------|------|\n| SEC-G01 | `--max-risk-level` | 风险级别 cap 作为安全门控 |\n| SEC-G02 | 响应包装器 | Graph 响应被nonce信封包装，防止提示注入 |\n| SEC-G03 | 敏感读取标注 | 22个敏感GET工具已标注风险级别 |\n\n### 最小权限原则\n\n新工具必须：\n\n1. 声明最小必需的 Graph API 权限（`appPermissions`）\n2. 避免请求 `.ReadWrite.All` 当 `.Read.All` 足够时\n3. 所有写操作必须附带风险级别标注\n\n资料来源：[CONTRIBUTING.md:40-50](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n## 最佳实践\n\n### 开发新工具时的风险标注\n\n在 `endpoints.json` 中添加新工具时，必须包含风险级别：\n\n```json\n{\n \"toolName\": \"create-something\",\n \"method\": \"POST\",\n \"appPermissions\": [\"Something.ReadWrite.All\"],\n \"riskLevel\": \"medium\"\n}\n```\n\n### 风险升级场景\n\n以下情况应提升风险等级：\n\n- 操作影响多个实体\n- 操作修改凭证或访问权限\n- 操作产生不可逆的数据变更\n- 操作具有租户范围的影响\n\n### 降低风险的方法\n\n如需降低操作风险，可考虑：\n\n1. 添加预演/确认步骤\n2. 限制操作范围（单用户而非批量）\n3. 添加延迟执行或审批工作流\n4. 提供回滚机制\n\n## 总结\n\n风险模型是 ms-365-admin-mcp-server 安全架构的基础，通过四级风险体系（`low`、`medium`、`high`、`critical`）对所有515个管理工具进行分类。该模型配合 CLI 风险上限参数 `--max-risk-level` 和强制性的确认流程，确保管理员在执行敏感操作时经过充分审查，防止租户级别的意外或恶意更改。\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[配置参考](#page-configuration), [通信传输层](#page-transports)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/Dockerfile)\n- [docs/APP_REGISTRATION.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/APP_REGISTRATION.md)\n- [docs/AZURE_DEPLOYMENT_SECURITY.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/AZURE_DEPLOYMENT_SECURITY.md)\n- [infra/main.bicep](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/infra/main.bicep)\n \n\n# 部署指南\n\n本文档提供 ms-365-admin-mcp-server 的完整部署指南，涵盖从 Azure AD 应用注册到容器化部署的全流程。\n\n## 1. 部署概述\n\n### 1.1 部署模式\n\nms-365-admin-mcp-server 支持两种主要部署模式：\n\n| 部署模式 | 说明 | 适用场景 |\n|---------|------|---------|\n| **STDIO 模式** | 标准输入输出通信，适合本地开发和 Claude Code 集成 | 本地开发、单用户 |\n| **HTTP 服务器模式** | REST API 服务，支持远程访问和 Docker 部署 | 生产环境、多租户 |\n\n### 1.2 核心部署架构\n\n```mermaid\ngraph TD\n A[客户端 MCP Client] -->|HTTP/gRPC| B[ms-365-admin-mcp-server]\n B --> C[Azure AD 应用注册]\n B --> D[Microsoft Graph API]\n D --> E[Microsoft 365 管理 API]\n \n F[Docker 容器] --> B\n G[Azure Container Instances] --> F\n H[Azure App Service] --> B\n```\n\n### 1.3 部署前提条件\n\n- Node.js 18+ (STDIO 模式)\n- Docker 20.10+ (容器模式)\n- Azure 订阅\n- Microsoft 365 租户管理员权限\n\n## 2. Azure AD 应用注册\n\n### 2.1 创建应用注册\n\n在 Azure Portal 中创建应用注册，配置以下设置：\n\n| 设置项 | 推荐值 | 说明 |\n|-------|--------|------|\n| 支持的账户类型 | 仅此组织目录中的账户 | 单租户部署 |\n| 重定向 URI | `http://localhost:7000` | 本地开发 |\n| 重定向 URI (生产) | `https:///mcp` | HTTP 服务器模式 |\n\n### 2.2 配置应用程序权限\n\nms-365-admin-mcp-server 使用应用程序权限（application permissions），需要以下 Graph API 权限：\n\n```json\n{\n \"requiredResourceAccess\": [\n {\n \"resourceAppId\": \"00000003-0000-0000-c000-000000000000\",\n \"resourceAccess\": [\n {\n \"id\": \"\",\n \"type\": \"Role\"\n }\n ]\n }\n ]\n}\n```\n\n资料来源：[docs/APP_REGISTRATION.md:1-50]()\n\n### 2.3 获取凭据\n\n部署需要以下环境变量：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | Azure AD 应用程序客户端 ID |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | 应用程序客户端密钥 |\n| `MS365_ADMIN_MCP_TENANT_ID` | Azure AD 租户 ID |\n\n## 3. Docker 部署\n\n### 3.1 拉取镜像\n\n```bash\n# 从 GitHub Container Registry 拉取\ndocker pull ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n\n# 验证镜像\ndocker run -d \\\n --name mcp-server \\\n -p 7000:7000 \\\n -e MS365_ADMIN_MCP_CLIENT_ID=\"\" \\\n -e MS365_ADMIN_MCP_CLIENT_SECRET=\"\" \\\n -e MS365_ADMIN_MCP_TENANT_ID=\"\" \\\n -e MS365_ADMIN_MCP_ALLOWED_CLIENTS=\"*\" \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n```\n\n### 3.2 Docker 容器安全配置\n\nDocker 镜像使用非 root 用户运行，确保容器安全性：\n\n```dockerfile\n# 基础镜像配置\nFROM node:18-alpine\n\n# 创建非 root 用户\nRUN addgroup -g 1001 -S mcpuser && \\\n adduser -S mcpuser -u 1001\n\n# 切换到非 root 用户\nUSER mcpuser\n\n# 设置工作目录\nWORKDIR /app\n```\n\n资料来源：[Dockerfile:1-30]()\n\n### 3.3 卷挂载配置\n\n生产环境建议挂载日志目录：\n\n```bash\ndocker run -d \\\n --name mcp-server \\\n -p 7000:7000 \\\n -v /path/to/config:/app/config:ro \\\n -v /path/to/logs:/var/log/mcp-server \\\n -e MS365_ADMIN_MCP_LOG_DIR=\"/var/log/mcp-server\" \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n```\n\n## 4. Azure 基础设施部署\n\n### 4.1 Bicep 部署架构\n\n```mermaid\ngraph TD\n A[main.bicep] --> B[Azure Container Instance]\n A --> C[用户托管身份 UAMI]\n A --> D[Azure Key Vault]\n A --> E[虚拟网络]\n \n B --> C\n B --> D\n C --> D\n \n F[Private Container Registry] --> B\n```\n\n### 4.2 必需参数\n\n| 参数名 | 类型 | 必需 | 说明 |\n|-------|------|-----|------|\n| `allowedClients` | string | 是 | 允许访问的客户端 CIDR 列表 |\n| `acrLoginServer` | string | 否 | 私有容器注册表服务器 |\n| `tags` | object | 否 | 资源标签 |\n| `location` | string | 否 | 部署区域 |\n\n资料来源：[infra/main.bicep:1-100]()\n\n### 4.3 部署命令\n\n```bash\n# 使用 Azure CLI 部署\naz deployment sub create \\\n --location eastus \\\n --template-file infra/main.bicep \\\n --parameters allowedClients=\"['10.0.0.0/8']\" \\\n --parameters acrLoginServer=\"myregistry.azurecr.io\"\n\n# 验证部署\naz container show --resource-group --name \n```\n\n### 4.4 用户托管身份配置\n\nBicep 模板自动配置用户托管身份（UAMI）用于：\n\n- 从 Azure Key Vault 检索客户端密钥\n- 访问 Azure 资源\n- 容器注册表拉取镜像\n\n```bicep\nresource uami 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {\n name: 'mcp-server-identity'\n location: location\n}\n```\n\n资料来源：[infra/main.bicep:100-150]()\n\n## 5. HTTP 服务器模式配置\n\n### 5.1 启动参数\n\n| 参数 | 默认值 | 说明 |\n|-----|-------|------|\n| `--port` | 7000 | HTTP 服务器监听端口 |\n| `--host` | 0.0.0.0 | 绑定地址 |\n| `--allowed-clients` | - | 允许的客户端 IP/CIDR |\n| `--log-dir` | - | 日志目录 |\n| `--allow-writes` | false | 允许写操作 |\n| `--max-risk-level` | medium | 最大风险级别 |\n| `--preset` | - | 预置工具类别 |\n| `--enabled-tools` | - | 启用工具正则表达式 |\n\n### 5.2 安全配置\n\n| 安全功能 | 默认状态 | 说明 |\n|---------|---------|------|\n| 安全头 | 启用 | X-Content-Type-Options, X-Frame-Options, CSP |\n| Body 大小限制 | 100KB | 防止大文件攻击 |\n| 路径参数验证 | 启用 | 防止路径遍历 |\n| ReDoS 保护 | 启用 | 正则表达式长度限制 500 字符 |\n| 敏感数据脱敏 | 启用 | 日志中不泄露密钥 |\n\n资料来源：[docs/AZURE_DEPLOYMENT_SECURITY.md:1-50]()\n\n### 5.3 设备代码认证流程\n\nHTTP 服务器支持设备代码认证（device_code flow），适用于无法使用客户端密钥的场景：\n\n```bash\n# 启动服务器并触发设备代码认证\nnode dist/index.js --http --device-code\n\n# 输出示例\n# To sign in, use a web browser to open the page https://microsoft.com/devicelogin\n# and enter the code ABC12345 to authenticate.\n```\n\n认证流程：\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant S as MCP 服务器\n participant A as Azure AD\n \n C->>S: 请求 /token (device_code)\n S->>A: POST /devicecode\n A-->>S: device_code, user_code\n S-->>C: 显示 user_code\n C->>S: 轮询 /token\n Note over C: 用户在浏览器输入 code\n C->>A: 用户在 microsoft.com/devicelogin 认证\n A-->>S: 返回 tokens\n S-->>C: 返回 access_token\n```\n\n## 6. 环境变量配置\n\n### 6.1 完整环境变量列表\n\n| 环境变量 | 必需 | 默认值 | 说明 |\n|---------|-----|-------|------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | 是 | - | Azure AD 客户端 ID |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | 是* | - | 客户端密钥 |\n| `MS365_ADMIN_MCP_TENANT_ID` | 是 | - | 租户 ID |\n| `MS365_ADMIN_MCP_LOG_DIR` | 否 | - | 日志目录 |\n| `MS365_ADMIN_MCP_PORT` | 否 | 7000 | HTTP 端口 |\n| `MS365_ADMIN_MCP_HOST` | 否 | 0.0.0.0 | 绑定主机 |\n| `MS365_ADMIN_MCP_ALLOWED_CLIENTS` | 否 | - | 允许的客户端 |\n| `MS365_ADMIN_MCP_ALLOW_WRITES` | 否 | false | 允许写操作 |\n| `MS365_ADMIN_MCP_MAX_RISK_LEVEL` | 否 | medium | 最大风险级别 |\n| `MCP_REMOTE_CONFIG_DIR` | 否 | ~/.mcp-auth | OAuth 缓存目录 |\n\n*设备代码模式下不需要\n\n### 6.2 日志配置\n\nWinston 日志默认使用以下路径：\n\n```bash\n# 容器环境默认日志路径\nMS365_ADMIN_MCP_LOG_DIR=/tmp/.ms365-admin-mcp/logs\n```\n\n注意：在 Bicep 模板中已配置为 `/tmp/...`，避免 rootless 用户在 `/nonexistent/.ms365-admin-mcp/logs` 出现权限错误。\n\n## 7. 生产环境检查清单\n\n### 7.1 部署前检查\n\n- [ ] Azure AD 应用注册已完成\n- [ ] 所需 Graph API 权限已获批准\n- [ ] 客户端 ID 和租户 ID 已获取\n- [ ] 客户端密钥已生成并安全存储\n- [ ] 网络策略已配置（允许来自 MCP 客户端的访问）\n- [ ] 日志存储已配置\n\n### 7.2 安全检查清单\n\n- [ ] 使用 HTTPS（生产环境）\n- [ ] 配置 `allowedClients` 限制访问\n- [ ] `ALLOW_WRITES` 默认关闭\n- [ ] 监控日志中的敏感信息泄露\n- [ ] 定期轮换客户端密钥\n- [ ] 配置 Key Vault 存储密钥\n\n资料来源：[docs/AZURE_DEPLOYMENT_SECURITY.md:50-100]()\n\n### 7.3 高可用性配置\n\n```bash\n# 使用 Azure Container Apps 实现高可用\naz containerapp create \\\n --name mcp-server \\\n --resource-group \\\n --environment \\\n --image ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest \\\n --min-replicas 2 \\\n --max-replicas 10\n```\n\n## 8. 故障排除\n\n### 8.1 常见部署错误\n\n| 错误 | 原因 | 解决方案 |\n|-----|------|---------|\n| `EACCES` 日志写入失败 | 权限问题 | 设置 `MS365_ADMIN_MCP_LOG_DIR=/tmp/...` |\n| `tenant_rejected` | 使用了 `common` 端点 | 改用单租户 `organizations` 端点 |\n| `Server disconnected` | 设备代码认证超时 | 重新启动认证流程 |\n| 401 Unauthorized | 客户端密钥过期 | 更新密钥或使用设备代码流 |\n\n### 8.2 容器日志查看\n\n```bash\n# 查看容器日志\ndocker logs mcp-server\n\n# 实时跟踪日志\ndocker logs -f mcp-server\n\n# 进入容器调试\ndocker exec -it mcp-server sh\n```\n\n### 8.3 网络连通性测试\n\n```bash\n# 测试 Graph API 连通性\ncurl -v https://graph.microsoft.com/v1.0/$select\n\n# 测试 Token 端点\ncurl -v -X POST https://login.microsoftonline.com//oauth2/v2.0/token\n```\n\n## 9. 相关文档\n\n- [应用注册指南](docs/APP_REGISTRATION.md)\n- [Azure 部署安全](docs/AZURE_DEPLOYMENT_SECURITY.md)\n- [架构文档](docs/ARCHITECTURE.md)\n- [使用案例](docs/USE_CASES.md)\n- [故障排除](docs/TROUBLESHOOTING.md)\n\n---\n\n\n\n## 配置参考\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment), [认证系统](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n- [src/endpoints.json](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/endpoints.json)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/secrets.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/secrets.ts)\n- [README.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/README.md)\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n \n\n# 配置参考\n\n本页面详细说明 ms-365-admin-mcp-server 的所有配置选项，包括环境变量、云端配置、认证方式、预设分组以及风险级别策略。\n\n## 1. 环境变量配置\n\n服务器通过环境变量读取 Azure AD 应用注册凭据。支持两种模式：标准环境和 Azure 中国区（21Vianet）。\n\n### 1.1 必需的环境变量\n\n| 环境变量 | 描述 | 示例 |\n|---------|------|------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | Azure AD 应用程序（客户端）ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | 客户端密钥 | `~xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |\n| `MS365_ADMIN_MCP_TENANT_ID` | Azure AD 租户 ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |\n\n### 1.2 云端环境配置\n\n| 环境变量 | 默认值 | 描述 |\n|---------|--------|------|\n| `MS365_ADMIN_MCP_CLOUD` | `global` | 云环境：`global`（全球版）或 `cn`（中国区 21Vianet） |\n\n资料来源：[src/cloud-config.ts:1-50](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n\n### 1.3 服务器运行配置\n\n| 环境变量 | 默认值 | 描述 |\n|---------|--------|------|\n| `MS365_ADMIN_MCP_PORT` | `3000` | HTTP 服务器监听端口 |\n| `MS365_ADMIN_MCP_HOST` | `0.0.0.0` | HTTP 服务器绑定地址 |\n| `MS365_ADMIN_MCP_ALLOW_WRITES` | `false` | 允许执行写入操作 |\n| `MS365_ADMIN_MCP_MAX_RISK_LEVEL` | `medium` | 最大允许风险级别 |\n| `MS365_ADMIN_MCP_PRESET` | `all` | 初始工具预设分组 |\n\n### 1.4 认证缓存配置\n\n| 环境变量 | 默认值 | 描述 |\n|---------|--------|------|\n| `MCP_REMOTE_CONFIG_DIR` | `~/.mcp-auth/mcp-remote-/` | 设备码认证缓存目录 |\n| `AZURE_CLIENT_SECRET` | - | Key Vault 密钥保管库模式下的客户端密钥 |\n\n资料来源：[src/secrets.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/secrets.ts)\n\n## 2. 云端配置详解\n\n### 2.1 云环境端点\n\n服务器支持两种 Microsoft 365 云环境：\n\n```mermaid\ngraph TD\n A[启动服务器] --> B{MS365_ADMIN_MCP_CLOUD?}\n B -->|global| C[全球版端点]\n B -->|cn| D[中国区端点 21Vianet]\n C --> E[login.microsoftonline.com]\n D --> F[login.partner.microsoftonline.cn]\n```\n\n**全球版端点：**\n\n| 用途 | 端点 URL |\n|------|----------|\n| Microsoft Graph | `https://graph.microsoft.com` |\n| Azure AD 令牌 | `https://login.microsoftonline.com` |\n| Azure Key Vault | `https://vault.azure.net` |\n\n**中国区（21Vianet）端点：**\n\n| 用途 | 端点 URL |\n|------|----------|\n| Microsoft Graph | `https://microsoftgraph.chinacloudapi.cn` |\n| Azure AD 令牌 | `https://login.partner.microsoftonline.cn` |\n| Azure Key Vault | `https://vault.azure.cn` |\n\n资料来源：[src/cloud-config.ts:10-45](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n\n## 3. 认证配置\n\n### 3.1 认证流程\n\n服务器使用 MSAL（Microsoft Authentication Library）的客户端凭据流（Client Credentials Flow）进行身份验证：\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Azure AD\n \n Client->>Server: 请求调用工具\n Server->>Azure AD: 获取访问令牌 (client_credentials)\n Azure AD-->>Server: access_token\n Server->>Microsoft Graph: API 请求 + access_token\n Microsoft Graph-->>Server: 响应数据\n Server-->>Client: 工具执行结果\n```\n\n### 3.2 认证模式\n\n| 模式 | 配置方式 | 说明 |\n|------|----------|------|\n| 环境变量 | `MS365_ADMIN_MCP_CLIENT_SECRET` | 最简方式，直接明文存储密钥 |\n| Key Vault | `AZURE_CLIENT_SECRET` + Key Vault URI | 生产环境推荐，密钥由 Azure Key Vault 管理 |\n\n资料来源：[src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n\n### 3.3 设备码认证（远程 HTTP 服务器）\n\n对于远程 HTTP 服务器部署，服务器支持 RFC 8628 设备码流：\n\n```bash\n# 预填充认证缓存\nms-365-admin-mcp-auth --server https://your-host.azurecontainerapps.io/mcp\n\n# 退出码说明\n# 0 - 成功\n# 1 - 用法错误\n# 2 - 网络错误\n# 3 - 认证被拒绝\n# 4 - 超时\n```\n\n认证缓存位置：`~/.mcp-auth/mcp-remote-/`，包含：\n- `_client_info.json`\n- `_tokens.json`\n\n缓存密钥使用 `md5(serverUrl)` 计算，与 `mcp-remote` 的 `getServerUrlHash` 完全匹配。\n\n## 4. 工具预设分组\n\n工具预设（Presets）用于按功能域分组暴露管理工具，减少 MCP 客户端需要处理的工具数量。\n\n### 4.1 可用预设列表\n\n| 预设名称 | 说明 | 包含工具类型 |\n|---------|------|-------------|\n| `security` | 安全警报、事件、攻击模拟、威胁情报 | Microsoft 365 Defender 相关 |\n| `audit` | 审计日志、登录日志、已删除项目 | 目录审计、登录、预配 |\n| `health` | 服务健康状况、消息中心公告 | 服务状态、问题、消息 |\n| `reports` | 使用报告 | Teams、邮件、SharePoint、OneDrive、M365 应用 |\n| `identity` | 身份和访问管理 | 用户、组、角色、设备、PIM、访客用户、外部身份 |\n| `exchange` | Exchange 管理 | 邮件追踪、邮箱、收件人 |\n| `intune` | Intune 设备管理 | 设备、合规、配置、Autopilot、应用、RBAC |\n| `governance` | 标识治理 | 访问评审、权利管理、生命周期工作流、TOU、应用同意 |\n| `compliance` | 合规性管理 | 许可证、安全分数、身份保护、风险检测、条件访问 |\n| `response` | 事件响应操作 | 禁用用户、撤销会话、确认泄露、 dismissing 风险 |\n| `ediscovery` | 电子发现案例 | Microsoft Purview |\n| `cloudpc` | Cloud PC / Windows 365 | 云电脑、预配策略、设备镜像 |\n| `callrecords` | Teams 通话记录 | 会话、段、参与者、PSTN 通话、Direct Routing |\n| `print` | 通用打印 | 打印机、共享、连接器、服务 |\n| `infoprotection` | 信息保护 | BitLocker、威胁评估、敏感度标签 |\n| `sharepointadmin` | SharePoint 管理 | SharePoint 租户管理 |\n| `retention` | 记录管理 | 保留策略、处置工作流 |\n| `teamsadmin` | Teams 管理 | 团队、频道、成员、应用、策略 |\n| `all` | 所有可用工具 | 全部 515 个工具 |\n\n资料来源：[src/tool-categories.ts:1-80](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n\n### 4.2 预设模式匹配规则\n\n每个预设通过正则表达式模式匹配工具名称：\n\n```typescript\n// 示例：identity 预设的匹配模式\n/role|directory|domain|auth-method|credential|application|service-principal|sp-password|sp-key|sp-token|sp-owner|oauth2|organization|named-location|device|administrative-unit|cross-tenant|pim|app-role|invitation|identity-provider|b2x|api-connector|custom-auth/i\n```\n\n### 4.3 组合预设\n\n支持同时启用多个预设：\n\n```typescript\nimport { getCombinedPresetPattern } from './tool-categories';\n\nconst combined = getCombinedPresetPattern(['security', 'audit']);\n// 返回组合后的正则表达式\n```\n\n## 5. 风险级别策略\n\n### 5.1 风险级别定义\n\n| 级别 | 含义 | 示例工具 |\n|------|------|----------|\n| `low` | 只读操作，查询类操作 | `list-users`、`get-team` |\n| `medium` | 有限影响，局部修改 | `create-team`、`update-user` |\n| `high` | 重大影响，范围广泛或凭证变更 | `revoke-user-sessions`、`update-conditional-access-policy` |\n| `critical` | 不可逆或租户范围影响 | `delete-user`、`wipe-managed-device`、`delete-conditional-access-policy` |\n\n资料来源：[src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n### 5.2 风险级别判定逻辑\n\n```mermaid\ngraph TD\n A[工具执行请求] --> B{配置了 riskLevel?}\n B -->|是| C[使用配置的 riskLevel]\n B -->|否| D{HTTP 方法是 GET?}\n D -->|是| E[默认为 low]\n D -->|否| F[默认为 critical]\n C --> G[与 maxRiskLevel 比较]\n E --> G\n F --> G\n G --> H{rank ≤ maxRiskLevel?}\n H -->|是| I[允许执行]\n H -->|否| J[拒绝执行]\n```\n\n风险等级排序（从小到大）：`low` < `medium` < `high` < `critical`\n\n### 5.3 关键工具列表\n\n**Critical 级别（需要带外审批）：**\n\n| 工具 | 风险 |\n|------|------|\n| `delete-user` | critical |\n| `delete-group` | critical |\n| `delete-application` | critical |\n| `delete-service-principal` | critical |\n| `delete-conditional-access-policy` | critical |\n| `delete-exchange-mailbox` | critical |\n| `delete-ediscovery-case` | critical |\n| `delete-team` | critical |\n| `delete-managed-device` | critical |\n| `wipe-managed-device` | critical |\n| `clean-windows-device` | critical |\n| `add-directory-role-member` | critical |\n| `create-pim-role-assignment-request` | critical |\n| `disable-user-account` | critical |\n\n**High 级别（需要明确确认）：**\n\n| 工具 | 风险 |\n|------|------|\n| `revoke-user-sessions` | high |\n| `confirm-compromised-users` | high |\n| `dismiss-risky-users` | high |\n| `change-user-password` | high |\n| `create-conditional-access-policy` | high |\n| `delete-named-location` | high |\n| `create-auth-strength-policy` | high |\n\n## 6. 端点配置\n\n### 6.1 端点定义格式\n\n`endpoints.json` 是工具定义的信任源，每个端点包含：\n\n```jsonc\n{\n \"toolName\": \"list-users\",\n \"pathPattern\": \"/users\",\n \"method\": \"GET\",\n \"appPermissions\": [\"User.Read.All\"],\n \"llmTip\": \"可选的提示信息，显示在工具描述中\"\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `toolName` | string | 是 | 工具唯一标识符 |\n| `pathPattern` | string | 是 | Microsoft Graph API 路径 |\n| `method` | string | 是 | HTTP 方法（GET/POST/PATCH/DELETE） |\n| `appPermissions` | string[] | 是 | 所需的应用权限 |\n| `llmTip` | string | 否 | 展示给 LLM 的提示信息 |\n| `riskLevel` | string | 否 | 风险级别（仅非 GET 方法需要） |\n\n### 6.2 必需权限示例\n\n| 工具域 | 所需权限 |\n|--------|----------|\n| 用户管理 | `User.Read.All`, `User.ReadWrite.All` |\n| 组管理 | `Group.Read.All`, `Group.ReadWrite.All` |\n| 设备管理 | `Device.Read.All`, `Device.ReadWrite.All` |\n| 安全 | `SecurityEvents.Read.All`, `SecurityEvents.ReadWrite.All` |\n| Intune | `DeviceManagementManagedDevices.Read.All` |\n\n## 7. CLI 命令行参数\n\n### 7.1 本地模式（Stdio）\n\n```bash\nms-365-admin-mcp-server [options]\n\n选项：\n --preset 工具预设分组\n --allow-writes 允许写入操作\n --max-risk-level 最大风险级别 (low/medium/high/critical)\n --list-tools 列出指定预设的工具\n --list-permissions 列出所需 Graph 权限\n --version, -v 显示版本\n --help, -h 显示帮助\n```\n\n### 7.2 HTTP 服务器模式\n\n```bash\nms-365-admin-mcp-server --http [options]\n\nHTTP 专用选项：\n --port 监听端口 (默认: 3000)\n --host 绑定地址 (默认: 0.0.0.0)\n```\n\n### 7.3 认证引导\n\n```bash\nms-365-admin-mcp-auth --server [options]\n\n选项：\n -s, --server MCP 服务器 URL（必需）\n --scope 覆盖 OAuth scope\n --cache-dir 缓存目录覆盖\n```\n\n## 8. 本地开发配置\n\n### 8.1 本地 .env 文件格式\n\n```bash\n# Azure AD 应用注册\nMS365_ADMIN_MCP_CLIENT_ID=your-client-id\nMS365_ADMIN_MCP_CLIENT_SECRET=your-client-secret\nMS365_ADMIN_MCP_TENANT_ID=your-tenant-id\n\n# 可选：云环境 (默认 global)\nMS365_ADMIN_MCP_CLOUD=global\n```\n\n### 8.2 开发验证命令\n\n```bash\n# 验证工具列表\nnode dist/index.js --preset security --list-tools\n\n# 验证所需权限\nnode dist/index.js --preset identity --list-permissions\n\n# 运行 MCP 检查器\nnpm run inspector\n```\n\n## 9. Docker 部署配置\n\n### 9.1 环境变量配置\n\n```bash\ndocker run -e MS365_ADMIN_MCP_CLIENT_ID=xxx \\\n -e MS365_ADMIN_MCP_CLIENT_SECRET=xxx \\\n -e MS365_ADMIN_MCP_TENANT_ID=xxx \\\n -e MS365_ADMIN_MCP_PORT=3000 \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n```\n\n### 9.2 Docker Compose 示例\n\n```yaml\nservices:\n mcp-server:\n image: ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n environment:\n MS365_ADMIN_MCP_CLIENT_ID: \"${CLIENT_ID}\"\n MS365_ADMIN_MCP_CLIENT_SECRET: \"${CLIENT_SECRET}\"\n MS365_ADMIN_MCP_TENANT_ID: \"${TENANT_ID}\"\n MS365_ADMIN_MCP_CLOUD: \"global\"\n MS365_ADMIN_MCP_PORT: \"3000\"\n ports:\n - \"3000:3000\"\n```\n\n## 10. Azure Container Apps 部署\n\n通过 Bicep 模板部署时，可在 `infra/main.bicep` 中配置：\n\n```bicep\n// 环境变量通过 Key Vault 引用\nMS365_ADMIN_MCP_CLIENT_ID: keyVaultSecret('client-id')\nMS365_ADMIN_MCP_CLIENT_SECRET: keyVaultSecret('client-secret')\nMS365_ADMIN_MCP_TENANT_ID: keyVaultSecret('tenant-id')\nMS365_ADMIN_MCP_CLOUD: 'global'\n```\n\n## 11. 故障排除配置\n\n### 11.1 常见配置问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 认证失败 | 客户端密钥过期 | 续订 Azure AD 应用密钥 |\n| 权限不足 | 缺少 Graph API 权限 | 在 Azure AD 中添加所需权限 |\n| 工具不可用 | 预设配置错误 | 使用 `--list-tools` 验证工具列表 |\n| 写入被拒绝 | `--allow-writes` 未启用 | 添加 `--allow-writes` 参数 |\n\n### 11.2 调试日志\n\n服务器使用 Winston 日志记录器，通过设置日志级别环境变量可获取详细调试信息：\n\n```bash\n# 启用调试日志\nDEBUG=ms-365-admin-mcp-server:* ms-365-admin-mcp-server\n```\n\n## 12. 配置验证清单\n\n部署前请确认以下配置项：\n\n- [ ] Azure AD 应用已注册且 `CLIENT_ID`、`CLIENT_SECRET`、`TENANT_ID` 已获取\n- [ ] 应用已授权所需 Graph API 权限（使用最小权限原则）\n- [ ] 根据部署区域选择正确的 `MS365_ADMIN_MCP_CLOUD` 值\n- [ ] 生产环境建议使用 Azure Key Vault 管理密钥\n- [ ] `max-risk-level` 已根据组织安全策略配置\n- [ ] 对于远程 HTTP 部署，已运行设备码引导流程\n- [ ] 已通过 `--list-permissions` 验证所需权限\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：okapi-ca/ms-365-admin-mcp-server\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ede43fd3f7247e0981524934656dbeb | https://github.com/okapi-ca/ms-365-admin-mcp-server/issues/71 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | release_recency=unknown\n\n\n",
"markdown_key": "ms-365-admin-mcp-server",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1210842314",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/okapi-ca/ms-365-admin-mcp-server"
},
{
"evidence_id": "art_c4bcfedbb261436f9832f43b69287515",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/okapi-ca/ms-365-admin-mcp-server#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "ms-365-admin-mcp-server 说明书",
"toc": [
"https://github.com/okapi-ca/ms-365-admin-mcp-server 项目说明书",
"目录",
"项目介绍",
"项目概述",
"核心架构",
"核心功能",
"安全模型",
"认证机制",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @okapi-ca/ms-365-admin-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @okapi-ca/ms-365-admin-mcp-server 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`agent-skills/ms365-admin-mcp/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`agent-skills/ms365-admin-mcp/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @okapi-ca/ms-365-admin-mcp-server` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/okapi-ca/ms-365-admin-mcp-server.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx @okapi-ca/ms-365-admin-mcp-server@latest auth \\` 证据：`README.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`agent-skills/ms365-admin-mcp/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`agent-skills/ms365-admin-mcp/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`agent-skills/ms365-admin-mcp/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`agent-skills/ms365-admin-mcp/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CONTRIBUTING.md`, `README.md`, `SECURITY.md`, `docs/APP_REGISTRATION.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`agent-skills/ms365-admin-mcp/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：117\n- 重要文件覆盖：40/117\n- 证据索引条目：80\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @okapi-ca/ms-365-admin-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @okapi-ca/ms-365-admin-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @okapi-ca/ms-365-admin-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **ms365-admin-mcp**（skill）：Reference skill for operating ms-365-admin-mcp-server through an LLM client. Load when a request involves a Microsoft 365 administrative operation requiring tenant-level permissions — Defender alert triage, sign-in investigation, PIM audit, Intune actions, eDiscovery, KQL hunting, Conditional Access management, or any tenant-scoped directory operation through application client credentials permissions. 激活提示：当用户任务与“ms365-admin-mcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agent-skills/ms365-admin-mcp/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Security Incident Response Playbooks**（documentation）：Security Incident Response Playbooks 证据：`docs/playbooks/README.md`\n- **ms-365-admin-mcp-server**（documentation）：! CI https://github.com/okapi-ca/ms-365-admin-mcp-server/actions/workflows/ci.yml/badge.svg?branch=main https://github.com/okapi-ca/ms-365-admin-mcp-server/actions/workflows/ci.yml ! npm version https://img.shields.io/npm/v/@okapi-ca/ms-365-admin-mcp-server.svg https://www.npmjs.com/package/@okapi-ca/ms-365-admin-mcp-server ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg LICENSE 证据：`README.md`\n- **Agent skills**（documentation）：Drop-in skills for LLM agents that operate ms-365-admin-mcp-server . Skills wrap the server's 515 tools with a structured safety pattern dry-run → confirm → audit and route requests by use case to keep the model focused on the right subset. 证据：`agent-skills/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@okapi-ca/ms-365-admin-mcp-server\", \"version\": \"0.6.2\", \"description\": \"A Model Context Protocol MCP server for Microsoft 365 admin operations via Graph API application permissions\", \"type\": \"module\", \"main\": \"dist/index.js\", \"bin\": { \"ms-365-admin-mcp-server\": \"dist/index.js\", \"ms-365-admin-mcp-auth\": \"dist/auth-bootstrap.js\" }, \"files\": \"dist\", \"README.md\", \"LICENSE\", \"CHANGELOG.md\" , \"publishConfig\": { \"access\": \"public\" }, \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/okapi-ca/ms-365-admin-mcp-server.git\" }, \"bugs\": { \"url\": \"https://github.com/okapi-ca/ms-365-admin-mcp-server/issues\" }, \"homepage\": \"https://github.com/okapi-ca/ms-365-admin-mcp-server readme\",… 证据：`package.json`\n- **Contributing**（documentation）：Thanks for your interest in contributing to ms-365-admin-mcp-server . 证据：`CONTRIBUTING.md`\n- **ms365-admin-mcp**（skill_instruction）：A reusable Claude Code skill that wraps ms-365-admin-mcp-server with a structured safety pattern: discover the right tool by use case, dry-run first, confirm explicitly, audit after. The skill is a router — its reference files index the server's 515 tools by domain and point back to the authoritative documentation in docs/USE CASES.md ../../docs/USE CASES.md and docs/playbooks/ ../../docs/playbooks/README.md . 证据：`agent-skills/ms365-admin-mcp/SKILL.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Azure AD App Registration Guide**（documentation）：This guide walks through creating an Entra ID Azure AD app registration with the application permissions required by ms-365-admin-mcp-server . 证据：`docs/APP_REGISTRATION.md`\n- **Architecture**（documentation）：This document describes the internal design of ms-365-admin-mcp-server . 证据：`docs/ARCHITECTURE.md`\n- **Azure Container Apps — Deployment Security Architecture**（documentation）：Azure Container Apps — Deployment Security Architecture 证据：`docs/AZURE_DEPLOYMENT_SECURITY.md`\n- **HTTP Transport and Remote Deployment**（documentation）：HTTP Transport and Remote Deployment 证据：`docs/HTTP_DEPLOYMENT.md`\n- **Risk Model**（documentation）：Every write tool in ms-365-admin-mcp-server is labeled with a risk level. This document explains the classification, how it's surfaced, and how to use it. 证据：`docs/RISK_MODEL.md`\n- **Security Review — 2026-04-20**（documentation）：Internal security review covering the highest-value portions of the codebase. Finding IDs are stable SEC-Fxx for Priority 1 / OAuth, SEC-Gxx for Priority 2 / tool invocation gating so remediation PRs and future reviews can reference them cleanly. 证据：`docs/SECURITY_REVIEW_2026-04-20.md`\n- **Security Review — 2026-04-25**（documentation）：Comprehensive security review of ms-365-admin-mcp-server v0.6.1 covering the entire codebase. Finding IDs in this review use the SEC-NNN scheme independent from the P1/P2 series SEC-Fxx / SEC-Gxx in SECURITY REVIEW 2026-04-20.md ./SECURITY REVIEW 2026-04-20.md so remediation PRs and future reviews can reference them cleanly. 证据：`docs/SECURITY_REVIEW_2026-04-25.md`\n- **MS 365 Admin MCP — macOS setup guide**（documentation）：MS 365 Admin MCP — macOS setup guide 证据：`docs/SETUP_MACOS_EN.md`\n- **MS 365 Admin MCP — Guide d'installation macOS**（documentation）：MS 365 Admin MCP — Guide d'installation macOS 证据：`docs/SETUP_MACOS_FR.md`\n- **MS 365 Admin MCP — Windows setup guide device code flow**（documentation）：MS 365 Admin MCP — Windows setup guide device code flow 证据：`docs/SETUP_WINDOWS_EN.md`\n- **MS 365 Admin MCP — Guide d'installation Windows flux device code**（documentation）：MS 365 Admin MCP — Guide d'installation Windows flux device code 证据：`docs/SETUP_WINDOWS_FR.md`\n- **Troubleshooting**（documentation）：Common errors and how to diagnose them. 证据：`docs/TROUBLESHOOTING.md`\n- **Use Cases**（documentation）：Typical scenarios for using ms-365-admin-mcp-server through an LLM client Claude Desktop, Claude Code, custom agent, etc. . 证据：`docs/USE_CASES.md`\n- **CYSEC-1422 — Baseline des permissions Microsoft Graph**（documentation）：CYSEC-1422 — Baseline des permissions Microsoft Graph 证据：`docs/CYSEC-1420/graph-permissions-baseline.md`\n- **CYSEC-1420 — Network Design — Infrastructure Gate**（documentation）：CYSEC-1420 — Network Design — Infrastructure Gate 证据：`docs/CYSEC-1420/network-design-gate.md`\n- **CYSEC-1420 — Pre-Migration Inventory**（documentation）：CYSEC-1420 — Pre-Migration Inventory 证据：`docs/CYSEC-1420/pre-migration-inventory.md`\n- **Playbook — Compromised Account**（documentation）：End-to-end incident response scenario driven through ms-365-admin-mcp-server . From the first risk signal to the post-incident audit report, every step maps to a concrete MCP tool. 证据：`docs/playbooks/compromised-account.md`\n- **Playbook — OAuth Illicit Consent Consent Phishing**（documentation）：Playbook — OAuth Illicit Consent Consent Phishing 证据：`docs/playbooks/oauth-illicit-consent.md`\n- **Playbook — Phishing Campaign Tenant-Wide**（documentation）：Playbook — Phishing Campaign Tenant-Wide 证据：`docs/playbooks/phishing-tenant-wide.md`\n- **Playbook — SharePoint / OneDrive Exfiltration**（documentation）：Playbook — SharePoint / OneDrive Exfiltration 证据：`docs/playbooks/sharepoint-exfiltration.md`\n- **Summary**（documentation）：- feat — new tool, preset, or feature - fix — bug fix - sec — security fix - docs — documentation only - chore — tooling, deps, non-functional - refactor — no behavior change - test — tests only 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Changelog**（documentation）：All notable changes to ms-365-admin-mcp-server are documented here. 证据：`CHANGELOG.md`\n- **Security Policy**（documentation）：Only the latest release of ms-365-admin-mcp-server receives security updates. Older versions may contain vulnerabilities that have been fixed upstream. 证据：`SECURITY.md`\n- **Description**（documentation）：- Version / commit SHA: - Node version: node --version - OS: - Transport: stdio / HTTP - Cloud: global / china - Presets enabled: - --allow-writes : yes / no 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Use case**（documentation）：- Graph API endpoint: /path/to/endpoint - HTTP method: GET / POST / PATCH / DELETE - Graph API permissions required: - Suggested toolName: - Suggested riskLevel if non-GET, see RISK MODEL.md ../../docs/RISK MODEL.md : - Matching preset: security / identity / ... / new preset 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Graph API permissions**（documentation）：Reference list of Microsoft Graph application permissions client credentials consumed by ms-365-admin-mcp-server . Match these to the app registration backing your deployment. 证据：`agent-skills/ms365-admin-mcp/references/graph-permissions.md`\n- **Tools catalogue**（documentation）：Index of the 515 tools exposed by ms-365-admin-mcp-server , organized by preset and by risk level. Do not preload this file — prefer the per-domain usecase- .md files. This is a reference for cross-cutting questions \"what's critical across the server?\", \"which preset contains tool X?\" . 证据：`agent-skills/ms365-admin-mcp/references/tools-catalog.md`\n- **usecase-audit — Sign-ins, directory audits, deleted items**（documentation）：usecase-audit — Sign-ins, directory audits, deleted items 证据：`agent-skills/ms365-admin-mcp/references/usecase-audit.md`\n- **usecase-callrecords — Teams call records and PSTN**（documentation）：usecase-callrecords — Teams call records and PSTN 证据：`agent-skills/ms365-admin-mcp/references/usecase-callrecords.md`\n- **usecase-cloudpc — Cloud PC / Windows 365**（documentation）：usecase-cloudpc — Cloud PC / Windows 365 证据：`agent-skills/ms365-admin-mcp/references/usecase-cloudpc.md`\n- **usecase-compliance — Licenses, Secure Score, Identity Protection, Conditional Access**（documentation）：usecase-compliance — Licenses, Secure Score, Identity Protection, Conditional Access 证据：`agent-skills/ms365-admin-mcp/references/usecase-compliance.md`\n- **usecase-ediscovery — Microsoft Purview eDiscovery**（documentation）：usecase-ediscovery — Microsoft Purview eDiscovery 证据：`agent-skills/ms365-admin-mcp/references/usecase-ediscovery.md`\n- **usecase-exchange — Message traces and mailboxes**（documentation）：usecase-exchange — Message traces and mailboxes 证据：`agent-skills/ms365-admin-mcp/references/usecase-exchange.md`\n- **usecase-governance — Access reviews, entitlement, lifecycle workflows**（documentation）：usecase-governance — Access reviews, entitlement, lifecycle workflows 证据：`agent-skills/ms365-admin-mcp/references/usecase-governance.md`\n- **usecase-health — Service health and Message Center**（documentation）：usecase-health — Service health and Message Center 证据：`agent-skills/ms365-admin-mcp/references/usecase-health.md`\n- **usecase-identity — Users, groups, PIM, applications, guests**（documentation）：usecase-identity — Users, groups, PIM, applications, guests 证据：`agent-skills/ms365-admin-mcp/references/usecase-identity.md`\n- **usecase-infoprotection — BitLocker, sensitivity labels, threat assessment**（documentation）：usecase-infoprotection — BitLocker, sensitivity labels, threat assessment 证据：`agent-skills/ms365-admin-mcp/references/usecase-infoprotection.md`\n- **usecase-intune — Devices, compliance, Autopilot, MAM, remote actions**（documentation）：usecase-intune — Devices, compliance, Autopilot, MAM, remote actions 证据：`agent-skills/ms365-admin-mcp/references/usecase-intune.md`\n- **usecase-print — Universal Print**（documentation）：When to load: Universal Print inventory, usage, shares audit. 证据：`agent-skills/ms365-admin-mcp/references/usecase-print.md`\n- **usecase-reports — M365 usage reports**（documentation）：usecase-reports — M365 usage reports 证据：`agent-skills/ms365-admin-mcp/references/usecase-reports.md`\n- **usecase-response — Incident response and containment**（documentation）：usecase-response — Incident response and containment 证据：`agent-skills/ms365-admin-mcp/references/usecase-response.md`\n- **usecase-retention — Records management**（documentation）：usecase-retention — Records management 证据：`agent-skills/ms365-admin-mcp/references/usecase-retention.md`\n- **usecase-security — Alert and incident triage**（documentation）：usecase-security — Alert and incident triage 证据：`agent-skills/ms365-admin-mcp/references/usecase-security.md`\n- **usecase-sharepointadmin — SharePoint tenant administration**（documentation）：usecase-sharepointadmin — SharePoint tenant administration 证据：`agent-skills/ms365-admin-mcp/references/usecase-sharepointadmin.md`\n- **usecase-teamsadmin — Teams tenant-level administration**（documentation）：usecase-teamsadmin — Teams tenant-level administration 证据：`agent-skills/ms365-admin-mcp/references/usecase-teamsadmin.md`\n- **usecase-threatintel — Threat intelligence and KQL hunting**（documentation）：usecase-threatintel — Threat intelligence and KQL hunting 证据：`agent-skills/ms365-admin-mcp/references/usecase-threatintel.md`\n- **Endpoints**（structured_config）：{ \"pathPattern\": \"/security/alerts v2\", \"method\": \"get\", \"toolName\": \"list-security-alerts\", \"appPermissions\": \"SecurityAlert.Read.All\" , \"llmTip\": \"Lists security alerts from Microsoft 365 Defender. Use $filter=status eq 'new' or status eq 'inProgress' to filter by status. Use $filter=severity eq 'high' to filter by severity informational, low, medium, high . Use $orderby=createdDateTime desc to sort by newest. Use $top to limit results. Each alert has title, description, severity, status, category, serviceSource, detectionSource, and evidence.\" }, { \"pathPattern\": \"/security/alerts v2/{alert-id}\", \"method\": \"get\", \"toolName\": \"get-security-alert\", \"appPermissions\": \"SecurityAlert.Read.All… 证据：`src/endpoints.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2020\", \"module\": \"NodeNext\", \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"resolveJsonModule\": true }, \"include\": \"src/ / \" , \"exclude\": \"test/ / \" } 证据：`tsconfig.json`\n- **.dockerignore**（source_file）：.env .env. .git .gitignore .claude node modules openapi infra coverage .lcov .nyc output .DS Store .idea .vscode-test .token-cache.json .mcp.json CLAUDE.md README.md Dockerfile .dockerignore 证据：`.dockerignore`\n- **Dependabot**（source_file）：version: 2 updates: - package-ecosystem: npm directory: / schedule: interval: weekly day: monday open-pull-requests-limit: 10 reviewers: - okapi-ca labels: - dependencies groups: dev-dependencies: dependency-type: development update-types: - minor - patch mcp-sdk: patterns: - \"@modelcontextprotocol/ \" azure: patterns: - \"@azure/ \" 证据：`.github/dependabot.yml`\n- **Environment**（source_file）：node modules/ dist coverage .lcov .nyc output .tsbuildinfo .npm .eslintcache 证据：`.gitignore`\n- **.prettierignore**（source_file）：node modules dist coverage src/generated .venv .claude openapi 证据：`.prettierignore`\n- **.prettierrc**（source_file）：{ \"semi\": true, \"singleQuote\": true, \"trailingComma\": \"es5\", \"printWidth\": 100, \"tabWidth\": 2 } 证据：`.prettierrc`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/playbooks/README.md`, `README.md`, `agent-skills/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/playbooks/README.md`, `README.md`, `agent-skills/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, package.json\n- **核心功能特性**：importance `high`\n - source_paths: src/tool-categories.ts, src/graph-tools.ts\n- **系统架构**：importance `high`\n - source_paths: docs/ARCHITECTURE.md, src/graph-client.ts, src/server.ts, bin/modules/generate-mcp-tools.mjs\n- **通信传输层**：importance `medium`\n - source_paths: docs/HTTP_DEPLOYMENT.md, src/http-server.ts, src/index.ts\n- **认证系统**：importance `high`\n - source_paths: src/auth.ts, src/oauth-proxy.ts, src/token-validator.ts, src/jwks-stale-cache.ts, src/secrets.ts\n- **授权机制**：importance `high`\n - source_paths: src/user-token-authorization.ts, src/user-token-validator.ts, src/risk-level.ts, src/cli.ts\n- **工具分类系统**：importance `high`\n - source_paths: src/tool-categories.ts, agent-skills/ms365-admin-mcp/SKILL.md, agent-skills/ms365-admin-mcp/references/tools-catalog.md\n- **风险模型**：importance `high`\n - source_paths: docs/RISK_MODEL.md, src/risk-level.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_6ede43fd3f7247e0981524934656dbeb | https://github.com/okapi-ca/ms-365-admin-mcp-server/issues/71 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：okapi-ca/ms-365-admin-mcp-server\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/okapi-ca/ms-365-admin-mcp-server 项目说明书\n\n生成时间：2026-05-13 14:28:40 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [核心功能特性](#page-features)\n- [系统架构](#page-architecture)\n- [通信传输层](#page-transports)\n- [认证系统](#page-authentication)\n- [授权机制](#page-authorization)\n- [工具分类系统](#page-tool-categories)\n- [风险模型](#page-risk-model)\n- [部署指南](#page-deployment)\n- [配置参考](#page-configuration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[核心功能特性](#page-features), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/README.md)\n- [package.json](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/package.json)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n- [SECURITY.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/SECURITY.md)\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n \n\n# 项目介绍\n\n## 项目概述\n\n`ms-365-admin-mcp-server` 是一个基于 Microsoft Model Context Protocol (MCP) 的服务器项目，专门为 Microsoft 365 管理任务提供标准化的工具接口。该项目将 Microsoft Graph API 中的管理员操作封装为离散的、类型安全的工具（tools），使 AI 代理能够以受控和安全的方式执行 Microsoft 365 租户管理操作。 资料来源：[README.md]()\n\n项目支持发布到 npm 作为 `@okapi-ca/ms-365-admin-mcp-server`，同时容器镜像发布到 GHCR (`ghcr.io/okapi-ca/ms-365-admin-mcp-server`)。 资料来源：[CHANGELOG.md]()\n\n## 核心架构\n\n### 技术栈\n\n| 组件 | 技术选型 | 说明 |\n|------|---------|------|\n| 运行时 | Node.js / TypeScript | 严格模式，ESLint + Prettier 规范 |\n| API 层 | Microsoft Graph API | OpenAPI 规范自动生成客户端 |\n| 认证 | MSAL (Microsoft Authentication Library) | 客户端凭据流 |\n| 类型安全 | Zod | Graph 响应的运行时验证 |\n| 构建 | npm | 包管理和脚本执行 |\n\n### 模块结构\n\n```\nsrc/\n auth.ts # MSAL 客户端凭据流实现\n auth-bootstrap.ts # RFC 8628 设备代码引导认证\n cli.ts # Commander 参数解析\n cloud-config.ts # 全球版与中国世纪互联版端点配置\n endpoints.json # 工具定义的权威数据源\n generated/ # 自动生成的 Zod 客户端代码\n tool-categories.ts # 工具分类正则模式\n risk-level.ts # 风险等级计算模块\n user-token-authorization.ts # 用户令牌授权验证\n untrusted-envelope.ts # 不受信任响应包装器\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 核心功能\n\n### 工具生态\n\n项目当前包含 **444 个管理员工具**，覆盖以下主要类别：\n\n| 类别 | 功能范围 | 参考文档 |\n|------|---------|---------|\n| `identity` | 用户、组、角色、设备、PIM、来宾、外部身份 | usecase-identity.md |\n| `exchange` | 消息追踪、邮箱管理 | usecase-exchange.md |\n| `intune` | 设备、合规、配置、Autopilot、应用、RBAC | usecase-intune.md |\n| `governance` | 访问评审、权利管理、生命周期工作流、条款使用 | usecase-governance.md |\n| `compliance` | 许可证、安全评分、身份保护、风险检测、CA策略 | usecase-compliance.md |\n| `response` | 事件响应写入（禁用、撤销、确认、忽略） | usecase-response.md |\n| `ediscovery` | 电子发现案例（Microsoft Purview） | usecase-ediscovery.md |\n| `cloudpc` | 云 PC / Windows 365 | usecase-cloudpc.md |\n| `callrecords` | Teams 通话记录 | usecase-callrecords.md |\n| `print` | 通用打印 | usecase-print.md |\n| `infoprotection` | BitLocker、威胁评估、敏感度标签 | usecase-infoprotection.md |\n| `sharepointadmin` | SharePoint 租户管理 | usecase-sharepointadmin.md |\n| `retention` | 记录管理 | usecase-retention.md |\n\n资料来源：[tools-catalog.md]()\n\n### 工具分类模式\n\n工具类别通过正则表达式自动匹配工具名称：\n\n```typescript\nexport const TOOL_CATEGORIES: Record = {\n identity: {\n name: 'identity',\n pattern: /user|group|role|device|administrative|directory/i,\n description: '用户、组、角色、设备、PIM...',\n },\n response: {\n name: 'response',\n pattern:\n /disable-user|revoke|block|reset|isolate|update-security|.../i,\n description: '事件响应操作...',\n },\n // ...\n};\n```\n\n资料来源：[src/tool-categories.ts]()\n\n## 安全模型\n\n项目实现了多层安全防护机制。\n\n### 风险等级体系\n\n所有非 GET 操作必须标注风险等级，作为 MCP 工具注册的依据：\n\n| 风险等级 | 判定标准 | 示例工具 |\n|---------|---------|---------|\n| `low` | 只读或微小影响 | `run-hunting-query`, `add-security-alert-comment` |\n| `medium` | 单个实体的可逆变更 | `update-user`, `add-group-member`, `create-invitation` |\n| `high` | 广泛影响、凭据变更或破坏性操作 | `revoke-user-sessions`, `update-conditional-access-policy` |\n| `critical` | 不可逆或租户范围影响 | `delete-user`, `wipe-managed-device`, `delete-conditional-access-policy` |\n\n资料来源：[CONTRIBUTING.md]()\n\n### 安全机制\n\n| 机制 | 描述 |\n|------|------|\n| `--max-risk-level` | CLI 参数限制注册工具的最大风险等级 |\n| `--allow-writes` | 显式授权写入操作 |\n| 响应包装器 | Graph 响应使用 nonce 包装防提示注入 |\n| 最小权限 | 仅请求必需的 Graph API 权限 |\n\n项目包含 51 个单元测试覆盖所有五个安全关键模块。 资料来源：[CHANGELOG.md]()\n\n## 认证机制\n\n### 客户端凭据流\n\n```mermaid\ngraph TD\n A[启动服务器] --> B[读取 .env 配置]\n B --> C{环境变量检查}\n C -->|缺失 MSAL 配置| D[触发设备代码引导]\n C -->|有 MSAL 配置| E[初始化 MSAL 客户端]\n D --> F[RFC 8628 设备代码流程]\n F --> G[获取访问令牌]\n E --> G\n G --> H[缓存令牌到 mcp-remote]\n H --> I[服务器就绪]\n```\n\n### 云配置\n\n项目支持 Microsoft 365 全球版和中国世纪互联版（21Vianet）的不同端点，通过 `cloud-config.ts` 模块统一管理。 资料来源：[src/auth.ts]()\n\n## 开发工作流\n\n### 环境配置\n\n```bash\ngit clone https://github.com/okapi-ca/ms-365-admin-mcp-server.git\ncd ms-365-admin-mcp-server\nnpm install\nnpm run generate # 下载 Graph OpenAPI 规范并生成客户端\nnpm run build\nnpm test\n```\n\n本地 `.env` 文件配置：\n\n```\nMS365_ADMIN_MCP_CLIENT_ID=...\nMS365_ADMIN_MCP_CLIENT_SECRET=...\nMS365_ADMIN_MCP_TENANT_ID=...\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 添加工具流程\n\n```mermaid\ngraph LR\n A[编辑 endpoints.json] --> B[添加工具定义]\n B --> C[npm run generate]\n C --> D[生成 Zod 客户端代码]\n D --> E[node dist/index.js --list-tools]\n E --> F[验证工具注册]\n F --> G[添加单元测试]\n G --> H[更新 README.md 工具表]\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 工具定义规范\n\n`endpoints.json` 中每个工具定义包含：\n\n```json\n{\n \"toolName\": {\n \"method\": \"GET|POST|PATCH|DELETE\",\n \"appPermissions\": [\"Permission.Read.All\"],\n \"llmTip\": \"可选的 LLM 提示信息\",\n \"riskLevel\": \"low|medium|high|critical\"\n }\n}\n```\n\n## 版本历史\n\n| 版本 | 工具数 | 主要变更 |\n|------|-------|---------|\n| 当前 | 444 | 安全修复、BitLocker 恢复密钥等敏感读取标注 |\n| 之前 | 369 | 新增云 PC、Teams 通话记录、通用打印等5个类别 |\n| 更早 | 306 | 107 个高价值管理员端点 |\n| 更早 | 199 | 安全修复、权限范围缩减 |\n\n资料来源：[CHANGELOG.md]()\n\n## 使用场景\n\n### 管理员操作自动化\n\n项目主要用于以下场景：\n\n- **身份管理**：用户生命周期管理、组分配、角色权限\n- **设备管理**：Intune 设备合规性监控、丢失设备远程操作\n- **安全响应**：风险用户确认、 compromised 用户隔离\n- **合规审计**：电子发现、访问评审、审计日志查询\n- **租户配置**：SharePoint、Teams、Exchange 设置管理\n\n### MCP 客户端集成\n\n项目作为 MCP 服务器运行，Claude Desktop/Code 等客户端可通过 MCP Inspector 进行交互式调试：\n\n```bash\nnpm run inspector\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 质量保证\n\n| 检查项 | 命令 |\n|-------|------|\n| 代码格式检查 | `npm run format:check` |\n| ESLint 检查 | `npm run lint` |\n| 完整验证 | `npm run verify` |\n| 列出所有工具 | `node dist/index.js --list-tools` |\n| 列出所有权限 | `node dist/index.js --list-permissions` |\n\n## 许可证\n\n本项目采用 MIT 许可证。 资料来源：[CHANGELOG.md]()\n\n---\n\n\n\n## 核心功能特性\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [工具分类系统](#page-tool-categories)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/endpoints.json](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/endpoints.json)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n- [src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n \n\n# 核心功能特性\n\nms-365-admin-mcp-server 是一个基于 Model Context Protocol (MCP) 的 Microsoft 365 管理服务器，通过 Microsoft Graph API 为 AI 助手提供对 Microsoft 365 管理功能的标准化访问接口。该项目从 175 个工具起步，经过多次迭代已扩展至 **515 个管理工具**，覆盖安全、审计、合规、设备管理、身份治理等核心领域。\n\n## 1. 系统架构概览\n\n### 1.1 整体架构\n\nms-365-admin-mcp-server 采用分层架构设计，核心层负责与 Microsoft Graph API 交互，认证层处理 Azure AD 应用注册凭证，配置层支持全球版和中国区（21Vianet）两种部署模式。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[MCP 客户端 / Claude Code]\n B[MCP Inspector]\n end\n \n subgraph 服务端核心\n C[CLI 解析层
src/cli.ts]\n D[工具注册表
src/endpoints.json]\n E[风险评估引擎
src/risk-level.ts]\n end\n \n subgraph 认证与配置\n F[MSAL 认证
src/auth.ts]\n G[云配置
src/cloud-config.ts]\n end\n \n subgraph Microsoft Graph API\n H[全球版
graph.microsoft.com]\n I[中国版
graph.microsoft.cn]\n end\n \n A --> C\n B --> C\n C --> D\n C --> E\n C --> F\n F --> G\n G --> H\n G --> I\n D --> H\n D --> I\n```\n\n### 1.2 目录结构\n\n| 目录/文件 | 功能说明 |\n|-----------|----------|\n| `bin/` | 代码生成脚本（OpenAPI 规范转换为 Zod 客户端） |\n| `src/` | 核心源代码 |\n| `src/auth.ts` | MSAL 客户端凭证流认证 |\n| `src/cli.ts` | Commander 参数解析 |\n| `src/cloud-config.ts` | 全球版与中国区端点配置 |\n| `src/endpoints.json` | 工具定义的事实来源 |\n| `src/generated/` | 自动生成的 Zod 验证代码 |\n| `src/risk-level.ts` | 风险等级计算与权限校验 |\n| `src/tool-categories.ts` | 工具分类与预设定义 |\n| `docs/` | 使用文档、风险模型、剧本 |\n\n## 2. 工具分类与预设体系\n\n### 2.1 预设分类总览\n\n该服务器将 515 个工具组织为 **17 个功能预设（Preset）**，每个预设对应特定的管理场景。预设通过正则表达式匹配工具名称实现自动归类。\n\n| 预设名称 | 功能描述 | 对应用例文件 |\n|----------|----------|--------------|\n| `security` | 安全警报、事件、攻击模拟、威胁情报 | `usecase-security.md` |\n| `audit` | 目录审计、登录日志、预配记录、已删除项 | `usecase-audit.md` |\n| `health` | 服务运行状况、消息中心公告 | `usecase-health.md` |\n| `reports` | 使用报告（Teams、邮件、SharePoint、OneDrive） | `usecase-reports.md` |\n| `identity` | 用户、组、角色、设备、PIM、来宾用户、外部身份 | `usecase-identity.md` |\n| `exchange` | 邮件跟踪、邮箱管理 | `usecase-exchange.md` |\n| `intune` | 设备、合规、配置、Autopilot、应用、RBAC | `usecase-intune.md` |\n| `governance` | 访问评审、权利管理生命周期、条款使用 | `usecase-governance.md` |\n| `compliance` | 许可证、安全分数、身份保护、风险检测、CA 策略 | `usecase-compliance.md` |\n| `response` | 事件响应写入操作（禁用、吊销、确认、驳回） | `usecase-response.md` |\n| `ediscovery` | 电子发现案例（Purview） | `usecase-ediscovery.md` |\n| `cloudpc` | 云 PC / Windows 365 | `usecase-cloudpc.md` |\n| `callrecords` | Teams 通话记录 | `usecase-callrecords.md` |\n| `print` | 通用打印 | `usecase-print.md` |\n| `infoprotection` | BitLocker、威胁评估、敏感度标签 | `usecase-infoprotection.md` |\n| `sharepointadmin` | SharePoint 租户管理 | `usecase-sharepointadmin.md` |\n| `retention` | 记录管理 | `usecase-retention.md` |\n\n### 2.2 工具分类定义实现\n\n预设分类在 `src/tool-categories.ts` 中通过 TypeScript 接口和正则表达式定义：\n\n```typescript\nexport interface ToolCategory {\n name: string;\n pattern: RegExp;\n description: string;\n}\n\nexport const TOOL_CATEGORIES: Record = {\n security: {\n name: 'security',\n pattern: /security|alert|incident|attack-simulation|threat-intel/i,\n description: 'Security alerts, incidents, attack simulations...',\n },\n identity: {\n name: 'identity',\n pattern: /user|group|role|conditional|directory|domain|auth-method|.../i,\n description: 'Identity and access management...',\n },\n // ... 其他预设\n};\n```\n\n资料来源：[src/tool-categories.ts:1-20]()\n\n### 2.3 工具发现与验证\n\n服务器提供命令行工具用于验证工具分类和权限配置：\n\n```bash\n# 列出所有工具\nnode dist/index.js --list-tools\n\n# 按预设列出工具\nnode dist/index.js --preset security --list-tools\n\n# 列出所需权限\nnode dist/index.js --list-permissions\n\n# 验证特定预设\nnode dist/index.js --preset identity --list-tools | grep list-users\n```\n\n## 3. 风险等级管理体系\n\n### 3.1 风险等级定义\n\n服务器对所有非 GET 操作工具进行风险分类，确保高风险操作需要明确授权：\n\n| 风险等级 | 判断标准 | 影响范围 | 操作示例 |\n|----------|----------|----------|----------|\n| `low` | 只读效果或最小影响 | 有限 | 添加安全警报评论、重新处理用户许可证 |\n| `medium` | 可逆变更影响单个实体 | 单个实体 | 更新用户、创建组、添加工具成员 |\n| `high` | 重大影响、凭证变更或破坏性操作 | 多个实体 | 吊销用户会话、更新条件访问策略 |\n| `critical` | 不可逆或租户级影响 | 整个租户 | 删除用户、擦除托管设备、删除条件访问策略 |\n\n### 3.2 风险等级计算逻辑\n\n风险等级的计算遵循以下优先级：\n\n1. **已配置风险等级优先**：如果 `endpoints.json` 中明确指定了 `riskLevel`，则使用该值\n2. **GET 请求默认低风险**：GET 请求默认为 `low`（只读操作）\n3. **未标注写入操作默认为 critical**：对于没有明确标注风险等级的写入操作，默认设置为 `critical`（故障安全原则）\n\n```typescript\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n if (configuredRiskLevel) return configuredRiskLevel;\n return method.toUpperCase() === 'GET' ? 'low' : 'critical';\n}\n```\n\n资料来源：[src/risk-level.ts:9-17]()\n\n### 3.3 权限校验机制\n\n工具执行前会校验其风险等级是否在允许范围内：\n\n```typescript\nexport function isToolAllowed(\n configuredRiskLevel: RiskLevel | undefined,\n method: string,\n maxRiskLevel: RiskLevel\n): boolean {\n return rank(effectiveRiskLevel(configuredRiskLevel, method)) <= rank(maxRiskLevel);\n}\n```\n\n写入操作的默认行为需要显式启用：\n\n```bash\n# 允许中等风险操作\nnode dist/index.js --allow-writes medium\n\n# 允许高风险操作（需二次确认）\nnode dist/index.js --allow-writes high\n```\n\n### 3.4 高危工具分类\n\n#### Critical 级别（需带外审批）\n\n以下操作被视为不可逆或具有租户范围影响：\n\n- `delete-user` — 删除用户账户\n- `delete-group` — 删除安全组\n- `delete-conditional-access-policy` — 删除条件访问策略\n- `wipe-managed-device` — 远程擦除托管设备\n- `delete-managed-device` — 删除设备注册\n- `delete-ediscovery-case` — 删除电子发现案例\n\n#### High 级别（需显式确认 + 预演）\n\n以下操作需要操作员确认并可能需要干运行：\n\n- `revoke-user-sessions` — 吊销用户会话\n- `confirm-compromised-users` — 确认受损用户\n- `change-user-password` — 更改用户密码\n- `update-device` — 更新设备配置\n- `create-attack-simulation` — 创建攻击模拟（钓鱼测试）\n\n## 4. 认证与安全机制\n\n### 4.1 MSAL 客户端凭证流\n\n服务器使用 Microsoft Authentication Library (MSAL) 的客户端凭证流进行认证，适用于服务级（无用户交互）的管理操作：\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant MSAL as MSAL 库\n participant AAD as Azure AD\n \n MCP->>AAD: 请求访问令牌
(client_id, client_secret, tenant_id)\n AAD-->>MSAL: 返回 access_token\n MSAL-->>MCP: access_token\n MCP->>Graph: Graph API 请求
(Bearer token)\n Graph-->>MCP: API 响应\n```\n\n### 4.2 环境变量配置\n\n需要在 `.env` 文件中配置以下凭证：\n\n```bash\nMS365_ADMIN_MCP_CLIENT_ID=... # Azure AD 应用注册的应用 ID\nMS365_ADMIN_MCP_CLIENT_SECRET=... # 应用密钥\nMS365_ADMIN_MCP_TENANT_ID=... # 租户 ID\n```\n\n资料来源：[CONTRIBUTING.md:45-49]()\n\n### 4.3 查询字符串与错误信息防护\n\n服务器对以下内容进行脱敏处理以防止凭证泄露：\n\n- 查询字符串参数\n- `testLogin` 错误消息中的敏感信息\n\n> `sec: sanitize query strings and testLogin error leaks` — CHANGELOG.md\n\n## 5. 云配置与多租户支持\n\n### 5.1 全球版与中国区切换\n\n服务器支持两种 Microsoft Graph 端点配置，适用于不同的主权云环境：\n\n```mermaid\ngraph LR\n A[请求] --> B{cloud-config}\n B -->|全球版| C[graph.microsoft.com]\n B -->|中国版| D[graph.microsoft.cn
21Vianet]\n \n style C fill:#4CAF50\n style D fill:#FF9800\n```\n\n| 云类型 | Graph 端点 | 适用场景 |\n|--------|------------|----------|\n| Global | `graph.microsoft.com` | 全球 Microsoft 365 商业版 |\n| China | `graph.microsoft.cn` | 世纪互联运营的 Azure 中国区 |\n\n配置详情见 `src/cloud-config.ts`。\n\n## 6. 工具定义与代码生成\n\n### 6.1 端点定义格式\n\n工具定义以 JSON 格式存储在 `endpoints.json` 中，作为所有工具定义的事实来源：\n\n```json\n{\n \"toolName\": \"list-users\",\n \"endpoint\": \"/v1.0/users\",\n \"method\": \"GET\",\n \"appPermissions\": [\"User.Read.All\"],\n \"llmTip\": \"列出租户中的所有用户\",\n \"riskLevel\": \"low\"\n}\n```\n\n### 6.2 代码生成流程\n\n服务器采用 OpenAPI 规范驱动的工作流：\n\n```mermaid\ngraph LR\n A[Graph OpenAPI 规范] --> B[bin/ 脚本]\n B --> C[生成 Zod 验证代码]\n B --> D[更新 endpoints.json]\n C --> E[src/generated/]\n D --> F[src/endpoints.json]\n \n style A fill:#2196F3,color:#fff\n style E fill:#E3F2FD\n style F fill:#E3F2FD\n```\n\n生成命令：\n\n```bash\nnpm run generate # 下载 Graph OpenAPI 规范并生成客户端\n```\n\n**重要提示**：`src/generated/` 目录下的文件由代码生成脚本自动维护，请勿手动编辑。如需修改工具定义，应编辑 `endpoints.json` 后重新生成。\n\n资料来源：[CONTRIBUTING.md:88-94]()\n\n## 7. 命令行接口\n\n### 7.1 可用命令\n\n服务器通过 `src/cli.ts` 提供以下命令行选项：\n\n| 命令 | 功能 |\n|------|------|\n| `--list-tools` | 列出所有可用工具 |\n| `--list-permissions` | 列出所需 Graph API 权限 |\n| `--list-tools --preset ` | 按预设筛选工具 |\n| `--list-tools --category ` | 按类别筛选工具 |\n| `--allow-writes ` | 允许指定风险等级的写入操作 |\n| `--preset --list-tools` | 验证预设分类 |\n| `--inspector` | 启动 MCP Inspector |\n\n### 7.2 交互式调试\n\n使用 MCP Inspector 进行本地调试：\n\n```bash\nnpm run inspector\n```\n\n## 8. 开发与贡献指南\n\n### 8.1 开发环境搭建\n\n```bash\ngit clone https://github.com/okapi-ca/ms-365-admin-mcp-server.git\ncd ms-365-admin-mcp-server\nnpm install\nnpm run generate # 生成客户端代码\nnpm run build # 编译 TypeScript\nnpm test # 运行测试\nnpm run verify # 完整验证（lint + 测试）\n```\n\n### 8.2 添加新工具的工作流\n\n添加新工具的标准流程：\n\n1. **编辑端点定义**：在 `endpoints.json` 中添加工具定义\n\n ```json\n {\n \"toolName\": \"list-something\",\n \"endpoint\": \"/v1.0/something\",\n \"method\": \"GET\",\n \"appPermissions\": [\"Something.Read.All\"],\n \"llmTip\": \"可选的 LLM 提示\",\n \"riskLevel\": \"low\"\n }\n ```\n\n2. **重新生成客户端**：\n\n ```bash\n npm run generate\n ```\n\n3. **验证工具注册**：\n\n ```bash\n node dist/index.js --list-tools | grep list-something\n node dist/index.js --list-permissions | grep Something\n ```\n\n4. **添加测试**：为非平凡参数处理或 skipEncoding 规则添加测试\n\n5. **更新 README.md**：更新工具计数和类别表格\n\n### 8.3 提交规范\n\n| 前缀 | 使用场景 |\n|------|----------|\n| `feat:` | 新工具、预设或功能 |\n| `fix:` | 错误修复 |\n| `sec:` | 安全修复 |\n| `docs:` | 仅文档更改 |\n| `chore:` | 工具、依赖、非功能性变更 |\n| `refactor:` | 无行为变更的重构 |\n| `test:` | 仅测试 |\n| `build(deps):` | 依赖升级 |\n\n## 9. 权限模型\n\n### 9.1 最小权限原则\n\n所有新工具必须声明最小必需的 Graph API 权限：\n\n| 操作类型 | 推荐权限 | 避免 |\n|----------|----------|------|\n| 只读 | `*.Read.All` | `*.ReadWrite.All` |\n| 写入 | `*.ReadWrite.All` | 仅在必要时使用 |\n\n### 9.2 应用权限 vs 委托权限\n\n服务器使用 **应用权限**（application permissions），因为它是无用户交互的服务级操作：\n\n```typescript\n// endpoints.json 中的权限声明\n{\n \"appPermissions\": [\"User.Read.All\", \"Group.Read.All\"]\n}\n```\n\n## 10. 快速参考表\n\n### 10.1 关键文件速查\n\n| 文件路径 | 用途 |\n|----------|------|\n| `src/endpoints.json` | 工具定义的源文件 |\n| `src/tool-categories.ts` | 预设分类配置 |\n| `src/risk-level.ts` | 风险计算逻辑 |\n| `src/auth.ts` | MSAL 认证 |\n| `src/cloud-config.ts` | 云端点配置 |\n| `src/cli.ts` | 命令行接口 |\n| `docs/RISK_MODEL.md` | 风险模型文档 |\n| `docs/USE_CASES.md` | 用例文档 |\n\n### 10.2 风险等级快速对照\n\n```\n权限等级: low < medium < high < critical\n允许写入: --allow-writes medium 允许 low + medium\n```\n\n### 10.3 版本历史要点\n\n| 版本 | 工具数量 | 关键变更 |\n|------|----------|----------|\n| 当前 | 515 | 71 个管理写入端点 |\n| v1.0 | 444 | 75 个管理写入操作 |\n| - | 369 | Cloud PC、Teams 通话记录、通用打印、信息保护 |\n| - | 306 | eDiscovery、Intune、身份治理 |\n| - | 199 | 权限范围缩减至最小权限 |\n| 早期 | 175 | 基础安全、设备、PIM、风险检测 |\n\n资料来源：[CHANGELOG.md:1-50]()\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [通信传输层](#page-transports), [认证系统](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [src/graph-client.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-client.ts)\n- [src/server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/server.ts)\n- [src/graph-tools.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-tools.ts)\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n \n\n# 系统架构\n\n## 概述\n\n`ms-365-admin-mcp-server` 是一个基于 Model Context Protocol (MCP) 的 Microsoft 365 管理服务器，通过 Microsoft Graph API 为 AI 代理提供 515+ 管理工具的访问能力。服务器采用 TypeScript 开发，运行于 Node.js 环境，支持标准输入输出（STDIO）和 HTTP 两种传输模式，可部署在 Azure Container Apps 等云环境中。\n\n核心设计原则：\n- **安全优先**：所有写操作必须按风险等级分类，需要显式授权方可执行\n- **最小权限**：仅请求必要的 Graph API 权限\n- **零破坏变更**：工具名称、参数结构预设分类不可随意变更\n- **代码生成**：工具定义基于 OpenAPI 规范自动生成，确保与 Graph API 同步\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A1[Claude Desktop]\n A2[Claude Code]\n A3[其他 MCP 客户端]\n end\n\n subgraph 服务器传输层\n B1[STDIO 服务器
server.ts]\n B2[HTTP 服务器
http-server.ts
StreamableHTTP]\n end\n\n subgraph 核心服务层\n C1[认证模块
auth.ts]\n C2[工具注册
graph-tools.ts]\n C3[风险评估
risk-level.ts]\n C4[工具分类
tool-categories.ts]\n C5[云配置
cloud-config.ts]\n end\n\n subgraph Graph API 层\n D1[Graph 客户端
graph-client.ts]\n D2[端点配置
endpoints.json]\n D3[生成工具
generated/]\n end\n\n subgraph Microsoft 365\n E1[Microsoft Graph API]\n E2[Azure AD
令牌颁发]\n end\n\n A1 --> B1\n A2 --> B1\n A3 --> B2\n B1 --> C1\n B2 --> C1\n C1 --> D1\n D1 --> E1\n D1 --> E2\n C2 --> D2\n C2 --> D3\n```\n\n资料来源：[src/server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/server.ts)\n\n---\n\n## 核心组件\n\n### 组件职责矩阵\n\n| 组件文件 | 职责 | 关键类型/函数 |\n|---------|------|--------------|\n| `src/index.ts` | 应用入口点，CLI 参数解析 | Commander.js |\n| `src/auth.ts` | MSAL 客户端凭据流认证 | `getConfidentialClientApplication` |\n| `src/cloud-config.ts` | 全球版与世纪互联版端点切换 | `CloudConfig`, `getCloudConfig` |\n| `src/graph-client.ts` | Graph API HTTP 封装 | `GraphClient`, `fetchWithAuth` |\n| `src/graph-tools.ts` | MCP 工具注册与执行 | `registerTools`, `executeGraphTool` |\n| `src/risk-level.ts` | 风险等级计算与权限校验 | `effectiveRiskLevel`, `isToolAllowed` |\n| `src/tool-categories.ts` | 预设分类定义 | `TOOL_CATEGORIES`, `getCombinedPresetPattern` |\n| `src/server.ts` | STDIO 传输模式服务器 | `StdioServer`, `runStdioServer` |\n| `src/http-server.ts` | HTTP 传输模式服务器 | `StreamableHTTPTransport` |\n| `src/token-validator.ts` | HTTP 模式 JWT 验证 | `validateJwtToken` |\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## 工具注册流程\n\n### 工具定义来源\n\n所有工具定义存储在 `src/endpoints.json` 中，作为工具注册的唯一数据源。每个条目包含：\n\n```jsonc\n{\n \"toolName\": \"list-users\",\n \"pathPattern\": \"/users\",\n \"method\": \"GET\",\n \"appPermissions\": [\"User.Read.All\"],\n \"llmTip\": \"获取所有用户列表，支持 $select, $filter\",\n \"riskLevel\": \"low\" // 仅非 GET 操作需要\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n### 工具注册时序\n\n```mermaid\nsequenceDiagram\n participant CLI as 命令行解析\n participant Server as StdioServer\n participant Registry as 工具注册器\n participant Config as endpoints.json\n participant Generator as 代码生成器\n participant Graph as GraphClient\n\n CLI->>Server: 初始化服务器\n Server->>Registry: 加载 endpoints.json\n Registry->>Generator: 读取工具定义\n Generator->>Config: 解析工具元数据\n Config-->>Registry: 返回工具配置列表\n Registry->>Registry: 遍历每个工具\n Registry->>Registry: 计算 effectiveRiskLevel\n Registry->>Registry: 检查 maxRiskLevel 限制\n alt 工具被风险等级过滤\n Registry->>Registry: 跳过注册\n else 工具允许注册\n Registry->>Graph: 注册 MCP 工具\n Graph-->>Registry: 注册成功\n end\n Registry->>Server: 返回注册统计\n```\n\n资料来源：[src/graph-tools.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-tools.ts)\n\n---\n\n## 认证机制\n\n### MSAL 客户端凭据流\n\n服务器使用 MSAL (Microsoft Authentication Library) 的客户端凭据流进行无用户认证：\n\n```mermaid\ngraph LR\n A[服务器启动] --> B[初始化 MSAL 客户端]\n B --> C[从环境变量读取
CLIENT_ID, CLIENT_SECRET, TENANT_ID]\n C --> D{云类型}\n D -->|全球版| E[login.microsoftonline.com]\n D -->|世纪互联| F[login.partner.microsoftonline.cn]\n E --> G[获取访问令牌]\n F --> G\n G --> H[Graph API 请求]\n H -->|令牌过期| G\n```\n\n资料来源：[src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n\n### 云配置支持\n\n| 云类型 | 标识 | Graph 根端点 |\n|--------|------|-------------|\n| 全球版 (Commercial) | `global` | `graph.microsoft.com` |\n| 世纪互联版 (China 21Vianet) | `china` | `graph.microsoft.cn` |\n\n资料来源：[src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n\n---\n\n## 风险等级系统\n\n### 风险等级定义\n\n| 等级 | 描述 | 判定条件 |\n|------|------|---------|\n| `low` | 只读操作或无害写操作 | GET 请求默认；POST 查询报表 |\n| `medium` | 单个实体的可逆变更 | `update-user`, `add-group-member` |\n| `high` | 广泛影响、凭据变更或破坏性操作 | `revoke-user-sessions`, `update-conditional-access-policy` |\n| `critical` | 不可逆或租户级影响 | `delete-user`, `wipe-managed-device`, `delete-conditional-access-policy` |\n\n资料来源：[src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n### 风险等级计算逻辑\n\n```typescript\nfunction effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n // 1. 如果配置了显式风险等级，使用配置值\n if (configuredRiskLevel) return configuredRiskLevel;\n \n // 2. GET 请求默认 low\n if (method.toUpperCase() === 'GET') return 'low';\n \n // 3. 未标注的非 GET 请求默认为 critical（fail-safe）\n return 'critical';\n}\n\nfunction isToolAllowed(\n configuredRiskLevel: RiskLevel | undefined,\n method: string,\n maxRiskLevel: RiskLevel\n): boolean {\n return rank(effectiveRiskLevel(configuredRiskLevel, method)) <= rank(maxRiskLevel);\n}\n```\n\n**重要**：未在 `endpoints.json` 中显式标注风险等级的非 GET 操作会被视为 `critical`，确保敏感操作不会被意外暴露。\n\n资料来源：[src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n---\n\n## 工具分类预设\n\n### 预设分类列表\n\n| 预设名称 | 功能范围 | 正则匹配模式 |\n|---------|---------|-------------|\n| `security` | 安全警报、事件、攻击模拟、威胁情报 | `/security\\|alert\\|incident\\|attack/i` |\n| `audit` | 目录审计、登录日志、预配日志 | `/audit\\|sign-in\\|provision\\|deleted/i` |\n| `health` | 服务健康、消息中心 | `/serviceHealth\\|serviceStatus\\|messageCenter/i` |\n| `reports` | 使用报告（Teams、邮件、SharePoint 等） | `/report\\|usage/i` |\n| `identity` | 用户、组、角色、设备、PIM、来宾 | `/user\\|group\\|role\\|device\\|pim\\|guest/i` |\n| `exchange` | 消息跟踪、邮箱 | `/mail\\|messageTrace\\|mailbox/i` |\n| `intune` | 设备、合规、配置、Autopilot、应用、RBAC | `/intune\\|managedDevice\\|compliance/i` |\n| `governance` | 访问评审、权利管理、生命周期、PIM | `/accessReview\\|entitlement\\|lifecycle\\|pim/i` |\n| `compliance` | 许可证、安全分数、身份保护、条件访问 | `/license\\|secureScore\\|conditionalAccess/i` |\n| `response` | 事件响应写操作（禁用、撤销、确认） | `/disable\\|revoke\\|block\\|reset\\|wipe/i` |\n| `ediscovery` | 电子发现案件（Purview） | `/ediscovery/i` |\n| `cloudpc` | 云 PC / Windows 365 | `/cloud-pc\\|provisioning/i` |\n| `callrecords` | Teams 通话记录 | `/call-record\\|call-session\\|pstn/i` |\n| `print` | 通用打印 | `/print/i` |\n| `infoprotection` | BitLocker、威胁评估、敏感标签 | `/bitlocker\\|sensitivity\\|threatAssessment/i` |\n| `sharepointadmin` | SharePoint 租户管理 | `/sharepoint\\|spo/i` |\n| `retention` | 记录管理 | `/retention/i` |\n| `teamsadmin` | Teams 管理 | `/team\\|channel\\|teams-app/i` |\n| `all` | 所有可用工具 | `/.*/` |\n\n资料来源：[src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n\n---\n\n## 传输模式\n\n### STDIO 模式\n\n适用于本地运行和 Claude Desktop/Code 集成：\n\n```mermaid\ngraph LR\n A[Claude Desktop] <-->|STDIO| B[ms-365-admin-mcp-server]\n B --> C[MSAL 认证]\n C --> D[Graph API]\n```\n\n启动命令：\n```bash\nnode dist/index.js\n```\n\n### HTTP 模式\n\n适用于 Azure Container Apps 等云部署：\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|HTTPS + JWT| B[HTTP 服务器]\n B --> C[Token 验证
token-validator.ts]\n C --> D[MSAL 认证]\n D --> E[Graph API]\n```\n\n启动命令：\n```bash\nnode dist/index.js --http --port 3000 --jwt-secret \n```\n\n资料来源：[src/server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/server.ts)\n\n---\n\n## 代码生成流程\n\n### OpenAPI 规范生成工具\n\n```mermaid\ngraph TD\n A[Microsoft Graph
OpenAPI Spec] --> B[bin/generate-mcp-tools.mjs]\n B --> C[解析端点元数据]\n C --> D[生成 Zod 验证模式]\n D --> E[输出到 src/generated/]\n E --> F[类型安全的工具定义]\n```\n\n生成命令：\n```bash\nnpm run generate\n```\n\n生成的代码位于 `src/generated/` 目录，**请勿手动编辑**，所有修改应在 `src/endpoints.json` 中进行后重新生成。\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## Graph 客户端架构\n\n### 请求执行流程\n\n```mermaid\nsequenceDiagram\n participant Tool as MCP 工具调用\n participant GC as GraphClient\n participant Auth as MSAL Auth\n participant Graph as Graph API\n\n Tool->>GC: executeGraphTool(tool, params)\n GC->>GC: 构建请求 URL\n GC->>Auth: 获取访问令牌\n Auth-->>GC: accessToken\n GC->>Graph: HTTP 请求 (Bearer token)\n Graph-->>GC: JSON 响应\n GC->>GC: Zod 验证响应\n GC-->>Tool: 结构化结果\n \n Note over GC: 错误处理：
401 → 刷新令牌重试
429 → 指数退避重试
5xx → 返回错误\n```\n\n### 请求参数处理\n\n| 参数类型 | 处理方式 | 说明 |\n|---------|---------|------|\n| 路径参数 | URL 模板替换 | `/{user-id}/...` → `/{实际ID}/...` |\n| 查询参数 | $filter, $select 等 | 自动编码，支持 OData |\n| 请求体 | POST/PATCH | Zod 验证后 JSON 序列化 |\n\n资料来源：[src/graph-client.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/graph-client.ts)\n\n---\n\n## 项目结构总览\n\n```\nms-365-admin-mcp-server/\n├── bin/ # 代码生成脚本\n│ └── modules/\n│ └── generate-mcp-tools.mjs # OpenAPI → Zod 生成器\n├── src/ # 核心源代码\n│ ├── auth.ts # MSAL 认证模块\n│ ├── auth-bootstrap.ts # RFC 8628 设备码引导\n│ ├── cli.ts # Commander CLI 参数解析\n│ ├── cloud-config.ts # 云配置（全球/世纪互联）\n│ ├── endpoints.json # 工具定义唯一数据源\n│ ├── generated/ # 自动生成的 Zod 客户端\n│ ├── graph-client.ts # Graph API HTTP 封装\n│ ├── graph-tools.ts # MCP 工具注册\n│ ├── http-server.ts # HTTP 传输服务器\n│ ├── index.ts # 应用入口\n│ ├── logger.ts # Winston 日志\n│ ├── risk-level.ts # 风险等级系统\n│ ├── secrets.ts # 密钥提供器（env/Key Vault）\n│ ├── server.ts # STDIO 服务器\n│ ├── token-validator.ts # JWT 验证\n│ └── tool-categories.ts # 预设分类定义\n├── infra/ # 基础设施代码\n│ └── main.bicep # Azure Container Apps 部署\n├── test/ # Vitest 测试\n├── docs/ # 文档\n│ ├── ARCHITECTURE.md\n│ ├── RISK_MODEL.md\n│ └── USE_CASES.md\n├── CONTRIBUTING.md\n├── SECURITY.md\n└── package.json\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n## 安全考量\n\n### 权限最小化原则\n\n新工具必须声明最小 Graph API 权限：\n\n| 场景 | 推荐权限 | 禁止权限 |\n|------|---------|---------|\n| 仅读取用户 | `User.Read.All` | `User.ReadWrite.All` |\n| 仅读取组 | `Group.Read.All` | `Group.ReadWrite.All` |\n| 目录读取 | `Directory.Read.All` | `Directory.ReadWrite.All` |\n\n### 关键风险操作\n\n以下操作被分类为 `critical`，需要 MCP 客户端显式授权（`--allow-writes`）：\n\n- `delete-user` - 删除用户（不可逆）\n- `delete-group` - 删除组\n- `delete-application` - 删除应用注册\n- `delete-conditional-access-policy` - 删除条件访问策略\n- `wipe-managed-device` - 远程擦除设备\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n---\n\n## 部署架构\n\n### Azure Container Apps 部署\n\n```mermaid\ngraph TD\n subgraph Azure\n A[客户端] -->|HTTPS| B[Azure Container Apps]\n B --> C[ms-365-admin-mcp-server
容器实例]\n C --> D[Azure Key Vault
密钥存储]\n D --> E[Microsoft Graph API]\n end\n\n subgraph 认证流程\n F[Azure AD App Registration] -->|CLIENT_ID/SECRET| C\n end\n```\n\n环境变量配置：\n\n```bash\nMS365_ADMIN_MCP_CLIENT_ID=\nMS365_ADMIN_MCP_CLIENT_SECRET=<客户端密钥>\nMS365_ADMIN_MCP_TENANT_ID=<租户 ID>\n```\n\n部署模板：`infra/main.bicep`\n\n资料来源：[CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## 通信传输层\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [部署指南](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/http-server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/http-server.ts)\n- [src/index.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/index.ts)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n- [src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n- [src/upstream-error.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/upstream-error.ts)\n- [docs/HTTP_DEPLOYMENT.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/HTTP_DEPLOYMENT.md)\n- [docs/TROUBLESHOOTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/TROUBLESHOOTING.md)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n \n\n# 通信传输层\n\n本文档详细介绍 ms-365-admin-mcp-server 项目中的通信传输层架构，涵盖客户端认证、HTTP 服务器部署、令牌管理以及远程调用的完整流程。\n\n## 概述\n\nms-365-admin-mcp-server 的通信传输层是连接 MCP 客户端（如 Claude Desktop/Code）与 Microsoft Graph API 的核心组件。该层负责处理 OAuth 2.0 身份认证、HTTP 服务器托管、MCP 协议通信以及令牌缓存等关键功能。\n\n项目的通信架构支持两种主要运行模式：\n\n| 运行模式 | 描述 | 适用场景 |\n|---------|------|---------|\n| **本地模式** | 直接在本地运行 MCP 服务器，通过标准输入/输出与客户端通信 | 开发调试、本地使用 |\n| **远程 HTTP 模式** | 通过 HTTP 服务器托管，支持远程客户端访问 | 生产部署、多用户环境 |\n\n资料来源：[CONTRIBUTING.md:35-45]()\n\n## 架构组件\n\n### 核心模块职责\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ MCP 客户端 (Claude) │\n└─────────────────────────────┬───────────────────────────────────┘\n │ HTTP / stdio\n┌─────────────────────────────▼───────────────────────────────────┐\n│ 通信传输层 │\n│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │\n│ │ http-server │ │ auth-bootstrap│ │ auth (MSAL) │ │\n│ └─────────────┘ └──────────────┘ └─────────────────────────┘ │\n└─────────────────────────────┬───────────────────────────────────┘\n │ HTTPS\n┌─────────────────────────────▼───────────────────────────────────┐\n│ Microsoft Graph API │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n| 模块 | 文件 | 主要职责 |\n|------|------|---------|\n| HTTP 服务器 | `src/http-server.ts` | 托管 MCP 端点、处理请求路由 |\n| 认证引导 | `src/auth-bootstrap.ts` | RFC 8628 device_code 流程初始化 |\n| MSAL 认证 | `src/auth.ts` | Microsoft 身份平台客户端凭证流 |\n| CLI 入口 | `src/cli.ts` | 命令行参数解析、模式切换 |\n| 错误处理 | `src/upstream-error.ts` | 上游 API 错误规范化 |\n\n资料来源：[src/http-server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/http-server.ts)、[src/auth-bootstrap.ts:45-60]()\n\n## HTTP 服务器部署\n\n### 部署方式\n\n项目支持多种 HTTP 服务器部署配置，主要通过环境变量和命令行参数进行控制。\n\n#### 环境变量配置\n\n| 环境变量 | 描述 | 默认值 |\n|---------|------|--------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | Azure AD 应用注册客户端 ID | 必需 |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | Azure AD 应用注册客户端密钥 | 必需 |\n| `MS365_ADMIN_MCP_TENANT_ID` | Azure AD 租户 ID | 必需 |\n| `MCP_REMOTE_CONFIG_DIR` | 远程配置目录路径 | `~/.mcp-auth/mcp-remote-/` |\n| `CI` | 是否在 CI 环境运行 | `false` |\n\n资料来源：[CONTRIBUTING.md:30-40]()\n\n#### 命令行参数\n\n```bash\nnode dist/index.js --preset --list-tools\nnode dist/index.js --preset --list-permissions\nnpm run inspector\n```\n\n| 参数 | 描述 |\n|------|------|\n| `--preset ` | 指定工具预设类别 |\n| `--list-tools` | 列出所有可用工具 |\n| `--list-permissions` | 列出所需 Graph API 权限 |\n| `--inspector` | 使用 MCP Inspector 交互式运行 |\n\n资料来源：[src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n\n### MCP Inspector 交互模式\n\n开发调试阶段可以使用 MCP Inspector 进行交互式测试：\n\n```bash\nnpm run inspector\n```\n\n该命令启动交互式调试服务器，便于验证工具注册、权限配置以及请求路由是否正常工作。\n\n资料来源：[CONTRIBUTING.md:43]()\n\n## 认证机制\n\n### MSAL 客户端凭证流\n\n`src/auth.ts` 模块实现了 Microsoft 身份库 (MSAL) 的客户端凭证流，用于服务器到服务器的认证场景。\n\n```typescript\n// 核心认证流程伪代码\nconst clientCredentialFlow = new ClientCredentialFlow({\n clientId: process.env.MS365_ADMIN_MCP_CLIENT_ID,\n clientSecret: process.env.MS365_ADMIN_MCP_CLIENT_SECRET,\n tenantId: process.env.MS365_ADMIN_MCP_TENANT_ID,\n});\n```\n\n此认证方式适用于后台服务场景，不需要用户交互即可获取访问令牌。\n\n资料来源：[src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n\n### RFC 8628 Device Code 引导流程\n\n`src/auth-bootstrap.ts` 实现了 RFC 8628 定义的 device_code 认证流程，专门用于为远程 MCP 客户端预先填充令牌缓存。\n\n#### 核心流程\n\n```\n┌──────────────┐ ┌───────────────┐ ┌──────────────────┐\n│ CLI 工具 │────▶│ OAuth 服务器 │────▶│ 用户设备/浏览器 │\n│ (auth-bootstrap)│ │ (/authorize) │ │ (验证页面) │\n└──────┬───────┘ └───────────────┘ └──────────────────┘\n │ │\n │ 轮询 /token │\n │◀──────────────────────────────────────────┤\n │ │\n ▼ │\n┌──────────────┐ │\n│ 缓存令牌 │ │\n│ _tokens.json│ │\n│ _client_info│ │\n└──────────────┘ │\n```\n\n#### 功能特性\n\n- **缓存键计算**：`md5(serverUrl)`，与 `mcp-remote` 的 `getServerUrlHash` 完全匹配，确保缓存正确关联\n- **缓存路径**：`~/.mcp-auth/mcp-remote-/`\n- **文件权限**：0600（仅所有者读写），保护敏感凭证\n- **剪贴板支持**：自动复制设备代码到剪贴板（`pbcopy`/`clip`/`wl-copy`/`xclip`），CI 或非 TTY 环境自动禁用\n\n资料来源：[src/auth-bootstrap.ts:60-75]()\n\n#### 命令行用法\n\n```bash\nms-365-admin-mcp-auth -s [--scope <范围>] [--cache-dir <路径>]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `-s, --server ` | MCP 服务器 URL（必需），支持带或不带 `/mcp` 后缀 |\n| `--scope ` | 覆盖默认 OAuth 范围（默认使用服务器元数据） |\n| `--cache-dir ` | 覆盖缓存目录路径 |\n\n#### 退出码\n\n| 退出码 | 含义 |\n|-------|------|\n| 0 | 认证成功 |\n| 1 | 用法错误 |\n| 2 | 网络错误 |\n| 3 | 认证被拒绝 |\n| 4 | 超时 |\n\n资料来源：[src/auth-bootstrap.ts:20-35]()\n\n### 令牌缓存机制\n\n认证引导工具生成的缓存文件包含两个关键文件：\n\n| 文件 | 用途 |\n|------|------|\n| `_client_info.json` | OAuth 客户端信息 |\n| `_tokens.json` | 访问令牌和刷新令牌 |\n\n缓存键采用 MD5 哈希算法，直接对应服务器 URL，确保多服务器部署场景下缓存隔离。\n\n资料来源：[src/auth-bootstrap.ts:68-70]()\n\n## 远程 HTTP 服务器架构\n\n### 请求处理流程\n\n```\n ┌─────────────────────────────────┐\n │ HTTP 请求入口 │\n │ (Azure Container Apps / VPS) │\n └───────────────┬─────────────────┘\n │\n ┌───────────────▼─────────────────┐\n │ 请求路由与中间件 │\n │ - 认证验证 │\n │ - 协议解析 │\n └───────────────┬─────────────────┘\n │\n ┌─────────────────────────┼─────────────────────────┐\n │ │ │\n┌─────────▼─────────┐ ┌──────────▼──────────┐ ┌────────▼────────┐\n│ MCP 协议处理器 │ │ 工具注册表 │ │ Graph API │\n│ (method routing) │──▶│ (endpoints.json) │──▶│ 客户端 │\n└───────────────────┘ └─────────────────────┘ └─────────────────┘\n```\n\n### 云端部署注意事项\n\n根据 `docs/TROUBLESHOOTING.md` 文档，远程 HTTP 部署需要考虑以下因素：\n\n| 注意事项 | 说明 |\n|---------|------|\n| **平台 SSO** | Azure AD 条件访问可能触发平台 SSO，导致 device_code 流程复杂化 |\n| **条件访问策略** | 需要确保部署的 MCP 服务器被条件访问策略允许 |\n| **Docker 挂载** | 使用 `--cache-dir` 和 `MCP_REMOTE_CONFIG_DIR` 环境变量支持 Docker 卷挂载 |\n| **多用户场景** | 不同用户需配置独立的缓存目录 |\n\n资料来源：[docs/TROUBLESHOOTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/TROUBLESHOOTING.md)\n\n### 认证流程对比\n\n#### 本地模式（标准输入/输出）\n\n```\nClaude Desktop ──▶ stdio ──▶ MCP Server ──▶ Graph API\n```\n\n- 直接进程间通信\n- 无需网络配置\n- 适用于单用户场景\n\n#### 远程模式（HTTP 服务器）\n\n```\nClaude Desktop/Code ──▶ HTTPS ──▶ MCP Remote Proxy ──▶ MCP Server ──▶ Graph API\n │\n device_code 认证\n (预填充令牌缓存)\n```\n\n- 基于 HTTP 的远程调用\n- 支持分布式部署\n- 需要令牌缓存配置\n\n资料来源：[docs/HTTP_DEPLOYMENT.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/HTTP_DEPLOYMENT.md)\n\n## 错误处理\n\n### 上游错误规范化\n\n`src/upstream-error.ts` 模块负责解析和规范化来自 Microsoft Graph API 的错误响应。\n\n#### 错误代码提取\n\n```typescript\n// 从 OAuth 错误响应中提取 error_codes\nif (parsed.error_codes && Array.isArray(parsed.error_codes)) {\n const codes = parsed.error_codes\n .filter((c) => typeof c === 'number')\n .slice(0, 5);\n if (codes.length > 0) {\n parts.push(`error_codes=[${codes.join(',')}]`);\n }\n}\n```\n\n#### 错误格式化\n\n| 场景 | 输出格式 |\n|------|---------|\n| 可解析的错误 | `error=X error_description=Y error_codes=[...]` |\n| 不可解析响应 | `` |\n| 无可识别字段 | `` |\n\n资料来源：[src/upstream-error.ts:10-25]()\n\n### 认证错误分类\n\n| 错误类型 | 处理方式 |\n|---------|---------|\n| 网络错误 | 退出码 2，可重试 |\n| 认证拒绝 | 退出码 3，检查权限配置 |\n| 超时 | 退出码 4，增加超时配置 |\n\n## 安全性考虑\n\n### 令牌存储安全\n\n| 安全措施 | 实现 |\n|---------|------|\n| 文件权限 | 0600，仅进程所有者可访问 |\n| 缓存隔离 | MD5 URL 哈希确保不同服务器缓存分离 |\n| 环境变量 | 敏感信息通过环境变量注入，避免硬编码 |\n\n资料来源：[src/auth-bootstrap.ts:70]()\n\n### 最小权限原则\n\n新增工具必须声明最小 Graph API 权限，禁止请求 `.ReadWrite.All` 当 `.Read.All` 即可满足需求。\n\n资料来源：[CONTRIBUTING.md:18-20]()\n\n## 配置示例\n\n### 本地开发配置\n\n```bash\n# .env 文件\nMS365_ADMIN_MCP_CLIENT_ID=your-client-id\nMS365_ADMIN_MCP_CLIENT_SECRET=your-client-secret\nMS365_ADMIN_MCP_TENANT_ID=your-tenant-id\n```\n\n### Docker 部署配置\n\n```bash\ndocker run -e MS365_ADMIN_MCP_CLIENT_ID=xxx \\\n -e MS365_ADMIN_MCP_CLIENT_SECRET=xxx \\\n -e MS365_ADMIN_MCP_TENANT_ID=xxx \\\n -e MCP_REMOTE_CONFIG_DIR=/data/mcp-cache \\\n -v /path/to/cache:/data/mcp-cache \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server\n```\n\n### Device Code 认证\n\n```bash\nms-365-admin-mcp-auth -s https://your-host.azurecontainerapps.io/mcp \\\n --cache-dir /data/mcp-cache\n```\n\n## 故障排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|---------|---------|\n| `Server disconnected` | 网络连接问题或服务器未运行 | 检查服务器状态和网络连通性 |\n| 设备代码流程超时 | 用户未在规定时间内完成认证 | 使用较长的超时时间或重新发起流程 |\n| 条件访问阻止 | 平台 SSO 或 CA 策略限制 | 检查并配置条件访问策略 |\n| 缓存权限错误 | Docker 卷挂载权限问题 | 确保挂载目录权限正确 |\n\n资料来源：[docs/TROUBLESHOOTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/TROUBLESHOOTING.md)\n\n## 相关文档\n\n| 文档 | 位置 | 内容 |\n|------|------|------|\n| HTTP 部署指南 | `docs/HTTP_DEPLOYMENT.md` | 远程服务器部署详细说明 |\n| 故障排查指南 | `docs/TROUBLESHOOTING.md` | 常见问题与解决方案 |\n| 贡献指南 | `CONTRIBUTING.md` | 开发设置与代码规范 |\n| 安全模型 | `docs/RISK_MODEL.md` | 风险分级与安全要求 |\n\n---\n\n\n\n## 认证系统\n\n### 相关页面\n\n相关主题：[授权机制](#page-authorization), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/oauth-proxy.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-proxy.ts)\n- [src/token-validator.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/token-validator.ts)\n- [src/jwks-stale-cache.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/jwks-stale-cache.ts)\n- [src/secrets.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/secrets.ts)\n- [src/http-server.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/http-server.ts)\n- [src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n \n\n# 认证系统\n\n## 概述\n\nms-365-admin-mcp-server 的认证系统负责保护 MCP 服务器的访问安全，支持两种主要的认证模式：\n\n1. **服务令牌模式（Service Token Mode）**：使用客户端 ID 和客户端密钥进行身份验证，适用于服务到服务的通信\n2. **OAuth 2.0 代理模式（OAuth Mode）**：通过 Microsoft Entra ID 实现用户身份验证，支持 Claude Desktop、Claude Code 和 Claude.ai Web 等客户端的 OAuth 授权流程\n\n该认证系统的核心目标是确保只有经过授权的用户和服务才能调用 Microsoft Graph API 执行租户管理操作。\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[Claude Desktop]\n B[Claude Code]\n C[Claude.ai Web]\n D[第三方 MCP 客户端]\n end\n \n subgraph \"认证层\"\n E[MCP 认证中间件]\n F[OAuth 代理]\n G[令牌验证器]\n H[JWKS 缓存]\n end\n \n subgraph \"Microsoft Entra ID\"\n I[令牌颁发]\n J[JWKS 端点]\n end\n \n subgraph \"资源层\"\n K[Graph API]\n L[MCP 工具]\n end\n \n A --> E\n B --> E\n C --> F\n D --> E\n D --> F\n \n E --> G\n F --> I\n G --> H\n H --> J\n \n E --> L\n G --> K\n F --> K\n```\n\n## 核心组件\n\n### 1. 认证模块（src/auth.ts）\n\n认证模块实现了 MSAL（Microsoft Authentication Library）的客户端凭据流，用于获取访问 Microsoft Graph API 的应用程序级令牌。\n\n| 功能 | 说明 |\n|------|------|\n| 客户端凭据流 | 使用应用 ID 和证书/密钥获取应用级访问令牌 |\n| 云配置支持 | 支持全球云和世纪互联（21Vianet）中国区云端点 |\n| 令牌缓存 | 内置令牌缓存机制，避免频繁请求新令牌 |\n\n### 2. OAuth 代理（src/oauth-proxy.ts）\n\nOAuth 代理实现了完整的 OAuth 2.0 + PKCE 授权代码流程，使 Claude 客户端能够通过 Microsoft Entra ID 进行身份验证。\n\n```mermaid\nsequenceDiagram\n participant Client as Claude 客户端\n participant Proxy as OAuth 代理\n participant Entra as Microsoft Entra ID\n participant Graph as Graph API\n\n Client->>Proxy: GET /.well-known/oauth-authorization-server\n Proxy->>Client: 返回元数据\n \n Client->>Proxy: GET /authorize?response_type=code&...\n Proxy->>Entra: 重定向到 Entra 授权端点\n Entra->>User: 显示登录页面\n User->>Entra: 完成身份验证\n Entra->>Proxy: 重定向回 /callback?code=xxx\n \n Client->>Proxy: POST /token (authorization_code)\n Proxy->>Entra: 使用 code 兑换令牌\n Entra->>Proxy: 返回 access_token, refresh_token\n \n Proxy->>Client: 返回令牌\n \n Client->>Proxy: GET /mcp (Bearer token)\n Proxy->>Graph: 使用 access_token 调用 API\n Graph->>Proxy: 返回数据\n Proxy->>Client: 返回结果\n```\n\n#### OAuth 代理端点\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/.well-known/oauth-authorization-server` | GET | 返回 OAuth 2.0 服务器元数据 |\n| `/.well-known/oauth-protected-resource` | GET | 返回受保护资源元数据（用于客户端发现）|\n| `/authorize` | GET | 授权端点，启动 PKCE 流程 |\n| `/callback` | GET | 授权回调处理 |\n| `/token` | POST | 令牌颁发端点 |\n| `/client/register` | POST | 动态客户端注册（DCR） |\n\n### 3. 令牌验证器（src/token-validator.ts）\n\n令牌验证器负责验证 HTTP 传输模式下传入的 Bearer 令牌，确保令牌的有效性和合法性。\n\n| 验证项目 | 说明 |\n|----------|------|\n| JWT 签名验证 | 使用 JWKS 端点获取公钥验证 JWT 签名 |\n| 颁发者验证 | 确认令牌由预期的 Entra 租户颁发 |\n| 受众验证 | 确认令牌适用于此应用（`aud` 声明）|\n| 租户验证 | 确认令牌来自授权的租户（`tid` 声明）|\n| 用户范围验证 | 确认令牌包含必需的 `scp` 声明（默认 `access_as_user`）|\n\n验证失败时的日志记录包括违规的 `aud`、`tid` 和 `upn` 信息，便于排查问题。\n\n### 4. JWKS 缓存（src/jwks-stale-cache.ts）\n\n为了提高性能和减少网络请求，令牌验证器使用 JWKS 缓存来存储和重用公钥信息。\n\n| 特性 | 说明 |\n|------|------|\n| 内存缓存 | 将 JWKS 数据缓存在内存中 |\n| 过期策略 | 支持配置缓存过期时间 |\n| 后台刷新 | 令牌验证前自动刷新过期缓存 |\n| 错误处理 | 缓存过期时优雅降级 |\n\n### 5. 密钥管理（src/secrets.ts）\n\n密钥管理模块负责从多种来源获取敏感配置信息：\n\n| 来源 | 优先级 | 说明 |\n|------|--------|------|\n| 环境变量 | 最高 | 直接从 `process.env` 读取 |\n| Azure Key Vault | 次高 | 从 Key Vault 获取存储的密钥 |\n| 默认值 | 最低 | 使用编译时默认值 |\n\n支持的密钥类型：\n- `AZURE_CLIENT_ID`：应用（客户端）ID\n- `AZURE_CLIENT_SECRET`：客户端密钥\n- `AZURE_TENANT_ID`：租户 ID\n\n### 6. HTTP 服务器认证中间件（src/http-server.ts）\n\nHTTP 服务器实现了 `/mcp` 端点的 Bearer 令牌验证中间件，遵循 RFC 6750 标准。\n\n```mermaid\nflowchart LR\n A[收到 /mcp 请求] --> B{Authorization Header}\n \n B -->|无或非 Bearer| C[返回 401
WWW-Authenticate Header]\n B -->|有 Bearer| D[提取令牌]\n \n D --> E{令牌类型}\n \n E -->|用户令牌| F[用户令牌验证器]\n E -->|服务令牌| G[服务令牌验证器]\n \n F -->|通过| H[允许访问]\n F -->|失败| I{原因}\n I -->|无授权用户| J[返回 403]\n I -->|其他| K[返回 401]\n \n G -->|通过| H\n G -->|失败| L[返回 403]\n \n H --> M[处理 MCP 请求]\n```\n\n#### WWW-Authenticate 响应头\n\n| 场景 | 状态码 | WWW-Authenticate Header |\n|------|--------|------------------------|\n| 缺少令牌 | 401 | `Bearer resource_metadata=\"...\"` |\n| 令牌验证失败 | 403 | `Bearer resource_metadata=\"...\", error=\"invalid_token\"` |\n\n### 7. 认证引导工具（src/auth-bootstrap.ts）\n\n认证引导工具实现了 RFC 8628 设备代码流，用于在 CLI 环境中自动化 OAuth 认证过程。\n\n| 功能 | 说明 |\n|------|------|\n| 设备代码获取 | 从服务器获取设备代码和用户验证码 |\n| PKCE 支持 | 自动生成 code_verifier 和 code_challenge |\n| 令牌缓存 | 将客户端信息和令牌保存到本地文件 |\n| 缓存目录 | 默认 `$MCP_REMOTE_CONFIG_DIR/mcp-remote-` |\n\n## 认证流程\n\n### 服务令牌模式\n\n```mermaid\ngraph LR\n A[客户端] -->|携带 Bearer Token| B[MCP 中间件]\n B --> C[令牌验证器]\n C -->|验证 JWT 签名| D[JWKS 缓存]\n D -->|返回公钥| C\n C -->|验证声明| E{验证结果}\n E -->|通过| F[Graph API 调用]\n E -->|失败| G[返回 401/403]\n```\n\n### OAuth 模式\n\n```mermaid\ngraph TD\n A[Claude Desktop 启动] -->|无缓存令牌| B[发起设备代码流]\n B --> C[auth-bootstrap 获取设备代码]\n C --> D[用户完成浏览器认证]\n D --> E[缓存令牌到本地]\n E --> F[MCP 连接携带缓存令牌]\n F --> G[OAuth 代理验证令牌]\n G -->|有效| H[允许 Graph API 调用]\n G -->|无效/过期| I[使用 refresh_token 刷新]\n I -->|刷新成功| H\n I -->|刷新失败| J[提示重新认证]\n```\n\n## 安全配置\n\n### 启动参数\n\n| 参数 | 说明 | 默认值 | 安全性 |\n|------|------|--------|--------|\n| `--allowed-clients` | 允许的服务客户端 ID 列表 | 必需（无默认）| P1 |\n| `--oauth-mode` | 启用 OAuth 2.0 代理模式 | false | P1 |\n| `--authorized-users` | OAuth 模式下允许的用户 OID 列表 | 必需（无默认值）| P1 |\n| `--allow-any-tenant-user` | 允许任意租户用户（需明确启用）| false | P1 |\n| `--public-url` | OAuth 模式的公共 URL | 必需（behind proxy 时）| P1 |\n| `--required-user-scopes` | 用户令牌必需的 scope | `access_as_user` | P1 |\n| `--client-secret` | 服务客户端密钥 | 从环境变量获取 | P2 |\n| `--trusted-ip-headers` | 信任的 IP 来源头 | 无 | P2 |\n\n### 安全修复记录\n\n| 标识 | 描述 | 版本 | 严重性 |\n|------|------|------|--------|\n| SEC-F01 | OAuth 模式在空用户白名单时失败关闭 | 0.2.0 | P1 |\n| SEC-F02 | `--public-url` 对 OAuth 模式为必需项 | 0.2.0 | P1 |\n| SEC-F03 | 新增 `--required-user-scopes` 强制验证 scope 声明 | 0.2.3 | P1 |\n| SEC-F04 | `/token` 端点速率限制：10 req/min/IP | 0.2.3 | P1 |\n| SEC-F05 | PKCE 桥接内存化，降低多副本部署风险 | 0.2.3 | P1 |\n\n## 部署注意事项\n\n### OAuth 模式部署\n\nOAuth 模式部署需要满足以下条件：\n\n1. **Entra 应用注册配置**：\n - 公开暴露 `access_as_user` 委托 scope（`api:///access_as_user`）\n - 配置 `requestedAccessTokenVersion: 2`\n - 授予管理员同意\n\n2. **网络配置**：\n - 必须设置 `--public-url`（反向代理后必需）\n - 配置 `trust proxy` 设置（如适用）\n\n3. **多副本部署**：\n - 由于 PKCE 桥接内存化特性，默认单副本部署\n - 多副本部署需显式设置 `maxReplicas` 并考虑外部化 PKCE 桥接\n\n### 从旧版本迁移\n\n| 场景 | 操作 |\n|------|------|\n| 使用 OAuth 模式且依赖\"任意认证用户\"行为 | 添加 `--allow-any-tenant-user` |\n| OAuth 模式部署在反向代理后 | 添加 `--public-url https://` |\n| Entra 应用未暴露 `access_as_user` scope | 添加 `--required-user-scopes \"\"` |\n| Bicep 部署依赖默认 `maxReplicas = 3` | 显式设置 `maxReplicas` |\n\n## 相关文件\n\n| 文件 | 职责 |\n|------|------|\n| `src/auth.ts` | MSAL 客户端凭据流实现 |\n| `src/oauth-proxy.ts` | OAuth 2.0 授权代码流代理 |\n| `src/token-validator.ts` | JWT 令牌验证 |\n| `src/jwks-stale-cache.ts` | JWKS 密钥缓存管理 |\n| `src/secrets.ts` | 密钥和环境变量管理 |\n| `src/http-server.ts` | HTTP 传输和认证中间件 |\n| `src/auth-bootstrap.ts` | RFC 8628 设备代码引导 |\n| `infra/main.bicep` | Azure Container Apps 部署配置 |\n\n---\n\n\n\n## 授权机制\n\n### 相关页面\n\n相关主题：[认证系统](#page-authentication), [风险模型](#page-risk-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/user-token-authorization.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/user-token-authorization.ts)\n- [src/user-token-validator.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/user-token-validator.ts)\n- [src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n- [src/oauth-proxy.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-proxy.ts)\n- [src/oauth-rate-limiters.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-rate-limiters.ts)\n- [src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n \n\n# 授权机制\n\n## 概述\n\nms-365-admin-mcp-server 的授权机制采用分层设计，支持两种主要的认证模式：**OAuth 2.0 代理模式**和**服务令牌模式**。系统通过用户令牌授权模块验证调用者身份，并结合速率限制和范围检查确保安全性。\n\n授权机制的核心职责包括：\n- 验证用户令牌的签名、颁发者和范围\n- 实施基于允许列表的访问控制\n- 提供细粒度的范围（scope）验证\n- 支持 Entra ID（Azure AD）集成的 OAuth 2.0 流程\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[HTTP 请求] --> B[/mcp 认证中间件]\n B --> C{OAuth 模式启用?}\n C -->|是| D[用户令牌验证]\n C -->|否| E{允许客户端模式?}\n E -->|是| F[服务令牌验证]\n E -->|否| G[返回 403]\n \n D --> H{令牌有效?}\n D --> I{在授权用户列表?}\n D --> J{范围满足?}\n \n H -->|否| K[返回 invalid_token / 401]\n I -->|否| L[返回 unauthorized / 403]\n J -->|否| M[返回 insufficient_scope / 403]\n \n H -->|是| I\n I -->|是| J\n J -->|是| N[提取 claims
oid, upn, name, appid]\n \n F --> O[验证服务令牌签名]\n O -->|成功| P[允许访问]\n \n N --> P\n```\n\n## 用户令牌授权\n\n### 核心验证流程\n\n用户令牌授权模块（`src/user-token-authorization.ts`）负责验证通过 OAuth 2.0 流程获取的用户令牌。验证过程遵循以下步骤：\n\n1. **签名验证** — 验证 JWT 签名来自可信的 JWKS 端点\n2. **声明验证** — 检查 `aud`（受众）、`tid`（租户 ID）等关键声明\n3. **用户白名单检查** — 验证 `upn` 是否在授权用户列表中\n4. **范围验证** — 确认令牌包含所需的 OAuth 范围\n\n### 关键函数\n\n```typescript\nexport function authorizeUserClaims(\n payload: UserTokenPayload,\n options: UserTokenValidatorOptions\n): UserTokenAuthorizationResult\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `payload` | `UserTokenPayload` | 解码后的 JWT 载荷 |\n| `options.requiredScopes` | `string[]` | 必需的 OAuth 范围列表 |\n| `options.authorizedUsers` | `string[]` | 授权用户 UPN 列表 |\n| `options.requiredAudiences` | `string[]` | 必需的受众声明 |\n| `options.requiredTenantId` | `string` | 必需的租户 ID |\n\n**返回值：**\n\n| 字段 | 说明 |\n|------|------|\n| `ok: true` | 授权成功，返回包含 `claims` 的对象 |\n| `ok: false` | 授权失败，`reason` 指示失败原因 |\n\n### 失败原因与 HTTP 状态码\n\n| 失败原因 | HTTP 状态 | 说明 |\n|----------|-----------|------|\n| `invalid_token` | 401 | 令牌格式错误或签名验证失败 |\n| `insufficient_scope` | 403 | 令牌缺少必需的范围 |\n| `unauthorized_user` | 403 | 用户不在授权列表中 |\n\n```typescript\n// 资料来源：src/user-token-authorization.ts:46-52\nif (missing.length > 0) {\n logger.warn(\n `User token missing required scope(s): ${missing.join(', ')}; token scp=${payload.scp ?? ''}`\n );\n return { ok: false, reason: 'insufficient_scope' };\n}\n```\n\n### 范围解析逻辑\n\n系统通过 `parseTokenScopes` 函数解析令牌中的 `scp` 声明，并与必需范围进行比对：\n\n```mermaid\ngraph LR\n A[scp 声明] --> B{解析范围列表}\n B --> C[requiredScopes]\n C --> D[过滤出不匹配项]\n D --> E{missing.length > 0?}\n E -->|是| F[返回 insufficient_scope]\n E -->|否| G[授权通过]\n```\n\n## OAuth 2.0 代理模式\n\n### 概述\n\n当服务器以 `--oauth-mode` 运行时，启用 OAuth 2.0 代理功能。用户通过 Entra ID 进行身份验证后，服务器代理令牌交换和验证流程。\n\n### 端点列表\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/.well-known/oauth-authorization-server` | GET | OAuth 发现文档 |\n| `/.well-known/oauth-protected-resource` | GET | 受保护资源元数据 |\n| `/authorize` | GET | 授权请求入口 |\n| `/token` | POST | 令牌交换 |\n| `/devicecode` | POST | 设备代码流 |\n\n### 授权流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant S as MCP Server\n participant E as Entra ID\n \n U->>S: 访问 MCP 端点 (无令牌)\n S->>U: 返回 401 + WWW-Authenticate\n U->>S: GET /authorize\n S->>E: 重定向到 Entra ID
client_id, redirect_uri, scope\n E->>U: 登录页面\n U->>E: 完成身份验证 + MFA\n E->>S: redirect_uri + auth_code\n S->>E: POST /token
client_id, client_secret, code\n E->>S: access_token, refresh_token\n S->>U: 返回令牌给客户端\n```\n\n### 客户端认证\n\nOAuth 代理在 `/token` 端点强制要求客户端凭证：\n\n```typescript\n// 资料来源：src/oauth-proxy.ts:85-100\nconst { clientId: reqClientId, clientSecret: reqClientSecret } = extractClientCredentials(req);\nif (!reqClientId || !reqClientSecret) {\n res.status(401).json({\n error: 'invalid_client',\n error_description: 'Missing client_id or client_secret',\n });\n return;\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| `client_id` | 注册的 OAuth 应用客户端 ID |\n| `client_secret` | 对应的客户端密钥 |\n\n### 设备代码引导\n\n对于无浏览器环境，服务器提供 RFC 8628 设备代码流程：\n\n```bash\nms-365-admin-mcp-auth -s https://your-host.azurecontainerapps.io/mcp\n```\n\n**工作流程：**\n\n1. 客户端向 `/devicecode` 请求设备代码\n2. 服务器返回 `device_code` 和 `user_code`\n3. 用户在另一设备访问 `verification_uri` 并输入 `user_code`\n4. 轮询 `/token` 直到授权完成\n\n```typescript\n// 资料来源：src/auth-bootstrap.ts:60-80\nconst { verification_uri, user_code, device_code, interval, expires_in } = await getDeviceCode(\n serverUrl,\n clientId,\n scope\n);\n```\n\n## 服务令牌模式\n\n### 概述\n\n当部署使用 `--allowed-clients` 参数时，系统接受预注册的服务令牌（如 MCP Remote 客户端令牌）。\n\n### 认证中间件顺序\n\n```mermaid\ngraph TD\n A[请求到达 /mcp] --> B{oauth-mode 启用?}\n B -->|是| C[尝试用户令牌验证]\n B -->|否| D{allowed-clients 启用?}\n \n C --> E{用户令牌验证成功?}\n E -->|是| F[允许访问]\n E -->|否| G{allowed-clients 启用?}\n \n D -->|是| H[尝试服务令牌验证]\n D -->|否| I[返回 403]\n \n H --> J{服务令牌验证成功?}\n J -->|是| F\n J -->|否| I\n G -->|是| H\n G -->|否| I\n```\n\n### 令牌缓存\n\n用户令牌和客户端信息缓存到本地目录：\n\n```bash\n$MCP_REMOTE_CONFIG_DIR/mcp-remote-/\n├── client-info.json\n└── tokens.json\n```\n\n缓存文件权限设置为 `0700`（目录）和 `0600`（文件），确保令牌安全存储。\n\n## 速率限制\n\n### 限制器配置\n\n系统通过 `src/oauth-rate-limiters.ts` 为 OAuth 端点配置多层速率限制：\n\n| 端点 | 限制器 | 窗口 | 最大请求 |\n|------|--------|------|----------|\n| `/token` (device_code) | `tokenDevicePollLimiter` | 1 分钟 | 10 次 |\n| `/token` (其他) | `tokenTightLimiter` | 1 分钟 | 5 次 |\n| `/register` | `tokenTightLimiter` | 1 分钟 | 5 次 |\n| `/devicecode` | `tokenTightLimiter` | 1 分钟 | 5 次 |\n\n### 设备代码轮询限制\n\n设备代码轮询（polling）有特殊的速率限制，防止客户端过度请求：\n\n```typescript\n// 资料来源：src/oauth-rate-limiters.ts:25-35\nconst tokenDevicePollLimiter = rateLimit({\n windowMs: 60 * 1000,\n max: 10,\n standardHeaders: true,\n legacyHeaders: false,\n message: {\n error: 'invalid_request',\n error_description: 'Too many device_code poll requests',\n },\n});\n```\n\n## CLI 配置选项\n\n通过 `src/cli.ts` 暴露的启动参数控制授权行为：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--oauth-mode` | 启用 OAuth 2.0 代理模式 | `false` |\n| `--allowed-clients` | 允许的服务客户端 ID 列表（逗号分隔） | 无 |\n| `--public-url` | OAuth 模式下的公共 URL | 必需（OAuth 模式下） |\n| `--required-user-scopes` | 必需的 OAuth 用户范围 | 必需（OAuth 模式下） |\n| `--allow-any-tenant-user` | 允许任何已验证租户的用户 | `false` |\n\n### 必需参数组合\n\n```mermaid\ngraph TD\n A[启动参数检查] --> B{OAuth 模式?}\n B -->|是| C{提供 --public-url?}\n C -->|否| D[错误：需要 public-url]\n C -->|是| E{提供 --required-user-scopes?}\n E -->|否| F[使用默认值]\n E -->|是| G[使用指定范围]\n \n B -->|否| H{提供 --allowed-clients?}\n H -->|否| I[错误：需要 allowed-clients 或 oauth-mode]\n H -->|是| J[启动成功]\n```\n\n### 示例启动命令\n\n```bash\n# OAuth 模式（Claude Desktop 集成）\nms-365-admin-mcp-server --transport streamable-http \\\n --oauth-mode \\\n --public-url https://mcp.contoso.com \\\n --required-user-scopes \"access_as_user\"\n\n# 服务客户端模式\nms-365-admin-mcp-server --transport streamable-http \\\n --allowed-clients \"client-id-1,client-id-2\"\n\n# 混合模式\nms-365-admin-mcp-server --transport streamable-http \\\n --oauth-mode \\\n --allowed-clients \"legacy-client-id\" \\\n --public-url https://mcp.contoso.com\n```\n\n## 安全考量\n\n### 令牌验证原则\n\n1. **签名验证优先** — 所有 JWT 必须通过 JWKS 验证签名\n2. **范围最小化** — 仅接受明确声明的范围\n3. **租户隔离** — 除非明确允许，否则仅接受同一租户的用户\n4. **客户端认证** — OAuth 端点强制要求客户端凭证\n\n### 日志记录\n\n授权失败时，系统记录详细诊断信息：\n\n```typescript\n// 资料来源：src/user-token-authorization.ts:40-45\nlogger.warn(\n `User (${upnForLog}) not in authorized-users allowlist`\n);\nreturn { ok: false, reason: 'invalid_token' };\n```\n\n日志包含的信息：\n- 用户主体名称（UPN）\n- 缺失的范围列表\n- 令牌受众（aud）和租户 ID（tid）\n\n### 速率限制保护\n\n- 防止设备代码轮询滥用\n- 限制令牌注册请求频率\n- 防止暴力破解客户端凭证\n\n## 迁移指南\n\n### 从旧版本升级\n\n| 版本 | 变更 |\n|------|------|\n| 0.2.0+ | 新增 `--oauth-mode` 支持 |\n| 0.2.4+ | 允许客户端参数变为可选（需要 `--oauth-mode` 或 `--allowed-clients`） |\n\n### 常见配置错误\n\n| 错误 | 解决方案 |\n|------|----------|\n| `ERR_MISSING_PUBLIC_URL` | 添加 `--public-url` 参数 |\n| `ERR_MISSING_REQUIRED_SCOPES` | 添加 `--required-user-scopes` 参数 |\n| `ERR_RATE_LIMIT_EXCEEDED` | 减少设备代码轮询频率 |\n\n## 参考资料\n\n- 授权核心实现：[src/user-token-authorization.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/user-token-authorization.ts)\n- OAuth 代理：[src/oauth-proxy.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-proxy.ts)\n- 设备代码引导：[src/auth-bootstrap.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth-bootstrap.ts)\n- 速率限制：[src/oauth-rate-limiters.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/oauth-rate-limiters.ts)\n- CLI 配置：[src/cli.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cli.ts)\n- 安全审查文档：[docs/SECURITY_REVIEW_2026-04-20.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/SECURITY_REVIEW_2026-04-20.md)\n\n---\n\n\n\n## 工具分类系统\n\n### 相关页面\n\n相关主题：[核心功能特性](#page-features), [风险模型](#page-risk-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [agent-skills/ms365-admin-mcp/SKILL.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/SKILL.md)\n- [agent-skills/ms365-admin-mcp/references/tools-catalog.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n \n\n# 工具分类系统\n\n## 概述\n\n工具分类系统（Tool Categories System）是 ms-365-admin-mcp-server 项目中用于组织和管理 515 个 Microsoft Graph API 工具的核心组件。该系统通过正则表达式模式匹配将工具自动归类到不同的功能域，使管理员和 AI 代理能够根据业务场景快速定位所需工具。 资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:1]()\n\n### 核心设计目标\n\n| 目标 | 说明 |\n|------|------|\n| **按领域组织** | 将 515 个工具按功能域（安全、身份、合规等）分组 |\n| **模式匹配** | 使用正则表达式自动识别工具所属分类 |\n| **预设管理** | 支持通过 `--preset` 参数动态加载相关工具集 |\n| **风险分层** | 每个分类关联特定的风险级别，便于权限管控 |\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[endpoints.json] --> B[工具注册表]\n B --> C{工具分类器}\n C --> D[TOOL_CATEGORIES]\n C --> E[CLI preset 参数]\n \n D --> F[security
audit
health
reports]\n D --> G[identity
governance
response]\n D --> H[exchange
intune
ediscovery]\n D --> I[cloudpc
callrecords
print
infoprotection
sharepointadmin
retention]\n \n E --> J[list-tools
filter by pattern]\n \n F --> K[MCP Inspector
动态加载]\n G --> K\n H --> K\n I --> K\n```\n\n### 核心接口定义\n\n工具分类系统定义了一个简洁的接口，包含三个必需属性： 资料来源：[src/tool-categories.ts:1-5]()\n\n```typescript\nexport interface ToolCategory {\n name: string; // 分类唯一标识符\n pattern: RegExp; // 匹配工具名称的正则表达式\n description: string; // 人类可读的分类描述\n}\n```\n\n## 分类清单\n\n### 完整分类对照表\n\n| 分类名称 | 模式关键词 | 描述 | 文档参考 |\n|----------|------------|------|----------|\n| `security` | security, alert, incident, attack-simulation, threat-intel | Microsoft 365 Defender 安全告警、事件、攻击模拟和威胁情报 | usecase-security.md |\n| `audit` | audit, sign-in, provisioning, directory, deleted-user, deleted-group | 审计日志、目录审计、登录记录和已删除项目 | usecase-audit.md |\n| `health` | service, health, issue, message | 服务健康状态和消息中心公告 | usecase-health.md |\n| `reports` | report, activity, usage | Teams、邮箱、SharePoint、OneDrive、M365 应用使用报告 | usecase-reports.md |\n| `identity` | user, group, role, conditional, directory, domain, auth-method, credential, application, service-principal, sp-password, sp-key, sp-token, sp-owner, oauth2, organization, named-location, device, administrative-unit, cross-tenant, pim, app-role, invitation, identity-provider, b2x, api-connector, custom-auth | Entra ID 用户、组、角色、设备、PIM、来宾用户、外部身份的身份和访问管理 | usecase-identity.md |\n| `governance` | role-resource-namespace | 访问评审、权利管理、生命周期工作流、角色/组 PIM、使用条款、应用同意的身份治理 | usecase-governance.md |\n| `response` | disable-user, revoke, block, reset, isolate, update-security, delete-user-auth, delete-user-phone, update-device, update-user-auth, confirm-compromised, dismiss-risky, confirm-safe, hunting-query, wipe-managed, retire-managed, remote-lock, locate-managed, bypass-activation, apply-hold, remove-hold | 事件响应操作（禁用用户、撤销会话、确认泄露/安全、 dismissal 风险、威胁狩猎查询） | usecase-response.md |\n| `ediscovery` | ediscovery | Microsoft Purview 电子发现案例 | usecase-ediscovery.md |\n| `cloudpc` | cloud-pc, provisioning-polic | Cloud PC / Windows 365（云电脑、配置策略、设备镜像） | usecase-cloudpc.md |\n| `callrecords` | call-record, call-session, pstn-call, direct-routing | Teams 通话记录（会话、分段、参与方、PSTN 通话、直接路由） | usecase-callrecords.md |\n| `print` | print | 通用打印（打印机、共享、连接器、服务、任务定义） | usecase-print.md |\n| `infoprotection` | sensitivity, bitlocker, threat-assessment, mip | BitLocker、威胁评估、敏感度标签 | usecase-infoprotection.md |\n| `sharepointadmin` | spo, sharepoint | SharePoint 租户管理 | usecase-sharepointadmin.md |\n| `retention` | retention, records | 记录管理 | usecase-retention.md |\n| `exchange` | exchange, mailbox, message-trace | 消息追踪、邮箱管理 | usecase-exchange.md |\n| `intune` | intune, mdm, mam, compliance, autopilot | 设备管理、合规配置、Autopilot、应用保护策略 | usecase-intune.md |\n| `teamsadmin` | teams, channel, meeting | Teams 团队、频道、会议、应用设置 | usecase-teamsadmin.md |\n\n资料来源：[src/tool-categories.ts:7-85]()\n\n## 使用方式\n\n### 命令行预设加载\n\n通过 `--preset` 参数加载特定分类的工具集：\n\n```bash\n# 列出所有安全相关工具\nnode dist/index.js --preset security --list-tools\n\n# 列出所有身份管理工具\nnode dist/index.js --preset identity --list-tools\n\n# 列出所有合规相关工具\nnode dist/index.js --preset compliance --list-tools\n```\n\n### 验证工具分类\n\n检查特定工具是否被正确分类：\n\n```bash\nnode dist/index.js --preset mypreset --list-tools\n```\n\n资料来源：[CONTRIBUTING.md:27-30]()\n\n## 扩展机制\n\n### 添加新分类\n\n在 `src/tool-categories.ts` 文件中扩展 `TOOL_CATEGORIES` 对象：\n\n```typescript\nexport const TOOL_CATEGORIES: Record = {\n // ... 现有分类 ...\n mypreset: {\n name: 'mypreset',\n pattern: /pattern-matching-tool-names/i,\n description: 'Short human-readable description',\n },\n};\n```\n\n### 分类匹配规则\n\n正则表达式必须能够匹配 `endpoints.json` 中定义的 `toolName`。验证方法：\n\n```bash\nnode dist/index.js --preset mypreset --list-tools | grep list-something\n```\n\n资料来源：[CONTRIBUTING.md:20-32]()\n\n## 与风险级别系统的集成\n\n工具分类系统与风险级别系统（risk-level.ts）协同工作，为每个操作提供安全保障：\n\n```typescript\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n if (configuredRiskLevel) return configuredRiskLevel;\n // GET 请求默认为 low，危险操作默认为 critical\n return method.toUpperCase() === 'GET' ? 'low' : 'critical';\n}\n```\n\n### 风险级别分类\n\n| 级别 | 描述 | 包含的操作类型 |\n|------|------|----------------|\n| `low` | 仅读取或无害操作 | GET 请求、报表生成 |\n| `medium` | 可逆的单实体变更 | update-user, add-group-member |\n| `high` | 影响范围大或凭证变更 | revoke-user-sessions, update-conditional-access-policy |\n| `critical` | 不可逆或租户级影响 | delete-user, wipe-managed-device, delete-conditional-access-policy |\n\n资料来源：[src/risk-level.ts:1-25]()\n\n## 技术实现细节\n\n### 模式匹配优先级\n\n当一个工具名称同时匹配多个分类的正则表达式时，系统按以下原则处理：\n\n1. **最长匹配优先** — 选择模式最具体的分类\n2. **精确分类优先** — 明确命名的分类（如 `ediscovery`）优先于宽泛匹配\n3. **配置覆盖** — `endpoints.json` 中的显式分类配置优先于自动匹配\n\n### 分类与文档映射\n\n工具目录（tools-catalog.md）建立了分类与用例文档的完整映射：\n\n```mermaid\ngraph LR\n A[security preset] --> B[usecase-security.md]\n A --> C[usecase-threatintel.md]\n D[identity preset] --> E[usecase-identity.md]\n F[compliance preset] --> G[usecase-compliance.md]\n F --> H[usecase-response.md]\n```\n\n每个用例文档包含：\n\n- 工具清单表格（操作、用途、风险级别）\n- 常见操作模式（Pattern）\n- 安全护栏（Guardrails）\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:1-50]()\n\n## 开发工作流\n\n### 添加新工具到现有分类\n\n1. 在 `src/endpoints.json` 中添加工具定义\n2. 运行 `npm run generate` 重新生成客户端代码\n3. 验证工具是否被正确分类：`node dist/index.js --list-tools | grep `\n4. 检查所需 Graph API 权限：`node dist/index.js --list-permissions | grep `\n\n### 创建新分类\n\n1. 编辑 `src/tool-categories.ts` 添加新的 `ToolCategory` 条目\n2. 编写对应的 `usecase-.md` 参考文档\n3. 在 `agent-skills/ms365-admin-mcp/references/tools-catalog.md` 中添加索引\n4. 运行测试验证：`npm run verify`\n\n资料来源：[CONTRIBUTING.md:33-75]()\n\n## 总结\n\n工具分类系统是 ms-365-admin-mcp-server 的核心组织机制，通过 16 个预设分类覆盖了 Microsoft 365 管理的全部功能域。系统利用正则表达式模式实现自动化分类，结合风险级别系统提供了完整的安全保障。该设计遵循了最小权限原则，所有新工具必须声明最小必需的 Graph API 权限，且非 GET 操作必须明确标注风险级别。\n\n---\n\n\n\n## 风险模型\n\n### 相关页面\n\n相关主题：[授权机制](#page-authorization), [工具分类系统](#page-tool-categories)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/RISK_MODEL.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/RISK_MODEL.md)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n- [CONTRIBUTING.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n- [agent-skills/ms365-admin-mcp/references/tools-catalog.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n- [agent-skills/ms365-admin-mcp/references/usecase-compliance.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/usecase-compliance.md)\n \n\n# 风险模型\n\n## 概述\n\n风险模型是 ms-365-admin-mcp-server 安全架构的核心组件，为所有管理工具提供风险级别的分类和访问控制机制。该模型确保高风险操作得到适当的审查和确认，防止意外或恶意的租户级别更改。\n\n风险模型的主要职责包括：\n\n- 为每个管理工具分配明确的风险等级（`low`、`medium`、`high`、`critical`）\n- 提供运行时风险级别检查机制\n- 支持通过 CLI 参数 `--max-risk-level` 限制可执行的最高风险级别\n- 默认为安全策略：未明确标注的写操作自动归类为 `critical`\n\n资料来源：[src/risk-level.ts:1-30](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n## 风险等级定义\n\n### 四级风险体系\n\n| 风险等级 | 判定标准 | 示例工具 |\n|---------|---------|---------|\n| `low` | 只读效果（POST 查询、报告）或trivial注解 | `run-hunting-query`、`add-security-alert-comment`、Intune 报告 |\n| `medium` | 可逆的单一实体变更 | `update-user`、`add-group-member`、`create-invitation` |\n| `high` | 重大影响：范围广、凭证变更或破坏性操作 | `revoke-user-sessions`、`update-conditional-access-policy` |\n| `critical` | 不可逆或租户级别影响 | `delete-user`、`wipe-managed-device`、`delete-conditional-access-policy` |\n\n资料来源：[CONTRIBUTING.md:55-60](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n### 判定规则\n\n风险等级判定遵循以下原则：\n\n1. **已配置风险优先**：如果工具显式配置了 `configuredRiskLevel`，直接使用该值\n2. **方法默认策略**：未配置的工具，GET 请求默认为 `low`，写操作默认为 `critical`（fail-safe 机制）\n3. **高风险优先原则**：难以判断时，选择更高的风险等级\n\n```typescript\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel {\n if (configuredRiskLevel) return configuredRiskLevel;\n return method.toUpperCase() === 'GET' ? 'low' : 'critical';\n}\n```\n\n资料来源：[src/risk-level.ts:15-22](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n## 风险级别函数\n\n### 函数列表\n\n```typescript\n// 计算有效风险级别\nexport function effectiveRiskLevel(\n configuredRiskLevel: RiskLevel | undefined,\n method: string\n): RiskLevel\n\n// 检查工具是否在允许范围内\nexport function isToolAllowed(\n configuredRiskLevel: RiskLevel | undefined,\n method: string,\n maxRiskLevel: RiskLevel\n): boolean\n```\n\n### 级别排序\n\n风险级别按严重程度排序为：`low < medium < high < critical`\n\n```typescript\nfunction rank(level: RiskLevel): number {\n const ranking: Record = {\n low: 0,\n medium: 1,\n high: 2,\n critical: 3,\n };\n return ranking[level];\n}\n```\n\n### 允许检查逻辑\n\n工具是否允许执行取决于其有效风险级别是否不超过配置的最大风险级别：\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B{获取有效风险级别}\n B --> C{获取最大风险级别 cap}\n C --> D{rank有效级别 <= rank最大级别?}\n D -->|是| E[允许执行]\n D -->|否| F[拒绝执行 + 提示]\n```\n\n资料来源：[src/risk-level.ts:25-30](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n## CLI 风险控制\n\n### 命令行参数\n\n| 参数 | 说明 | 隐含效果 |\n|-----|------|---------|\n| `--allow-writes` | 允许执行写操作 | 启用写入工具注册 |\n| `--max-risk-level ` | 设置最高可执行风险级别 | 隐含 `--allow-writes`，隐藏更高级别工具 |\n\n### 风险限制示例\n\n```bash\n# 只允许只读操作\nms-365-admin-mcp-server --max-risk-level low\n\n# 允许低和中风险操作\nms-365-admin-mcp-server --max-risk-level medium\n\n# 允许所有操作（含高风险）\nms-365-admin-mcp-server --max-risk-level high\n\n# 允许所有操作（含关键风险）\nms-365-admin-mcp-server --max-risk-level critical\n```\n\n资料来源：[CHANGELOG.md:1-20](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n\n## 关键工具风险映射\n\n### Critical 级别工具（需带外审批）\n\n以下工具具有不可逆或租户级别影响，执行前必须获得正式变更请求审批：\n\n| 工具名称 | 影响描述 |\n|---------|---------|\n| `delete-user` | 永久删除用户账户 |\n| `delete-group` | 永久删除安全组/Microsoft 365 组 |\n| `delete-application` | 删除应用注册 |\n| `delete-service-principal` | 删除服务主体 |\n| `delete-conditional-access-policy` | 删除条件访问策略 |\n| `delete-exchange-mailbox` | 删除 Exchange 邮箱 |\n| `delete-ediscovery-case` | 删除 eDiscovery 案例 |\n| `delete-team` | 删除 Teams 团队 |\n| `delete-managed-device` | 删除托管设备记录 |\n| `wipe-managed-device` | 完全擦除设备数据 |\n| `clean-windows-device` | 清理 Windows 设备 |\n| `add-directory-role-member` | 添加特权目录角色成员 |\n| `create-pim-role-assignment-request` | 特权角色的 PIM 分配请求 |\n| `create-pim-role-eligibility-request` | 特权角色资格请求 |\n| `disable-user-account` | 禁用特权或紧急访问账户 |\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:30-45](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n### High 级别工具（需明确确认 + 预演）\n\n| 工具名称 | 风险描述 |\n|---------|---------|\n| `revoke-user-sessions` | 撤销用户所有会话，影响用户当前工作 |\n| `confirm-compromised-users` | 确认用户账户已被泄露 |\n| `confirm-safe-users` | 将用户标记为安全（误报处理） |\n| `dismiss-risky-users` | 忽略风险用户 |\n| `confirm-compromised-service-principals` | 确认服务主体泄露 |\n| `dismiss-risky-service-principals` | 忽略风险服务主体 |\n| `delete-user-phone-auth-method` | 删除用户手机认证方法 |\n| `change-user-password` | 更改用户密码 |\n| `update-device` | 更新设备配置 |\n| `create-conditional-access-policy` | 创建条件访问策略 |\n| `update-conditional-access-policy` | 更新条件访问策略 |\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:50-60](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n### 敏感读取工具\n\n某些 GET 操作因暴露敏感信息也被标注风险级别：\n\n| 风险等级 | 工具类型 | 示例 |\n|---------|---------|------|\n| `high` | 密钥/恢复信息 | BitLocker 恢复密钥、LAPS 密码 |\n| `medium` | 认证信息 | 认证方法、登录记录、风险检测 |\n| `high` | 合规数据 | eDiscovery 案例、保管人、搜索、主题权限请求 |\n\n资料来源：[CHANGELOG.md:1-20](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CHANGELOG.md)\n\n## 高危操作安全模式\n\n### 必须遵循的操作流程\n\n对于 `high` 和 `critical` 级别的工具，必须执行以下序列：\n\n```mermaid\ngraph TD\n A[识别目标对象] --> B[预演 Dry-Run]\n B --> C[读取目标对象详情]\n C --> D[列出预期影响]\n D --> E[请求明确确认]\n E --> F{确认?}\n F -->|是| G[执行操作]\n F -->|否| H[取消操作]\n G --> I[记录审计日志]\n```\n\n### 标准确认话术\n\n执行高风险操作前，必须向操作员说明：\n\n> \"即将调用 `<工具名称>` 对 `<目标>` 执行 `<影响描述>`。此操作 `<可逆性/不可逆>`。是否确认执行？\"\n\n资料来源：[agent-skills/ms365-admin-mcp/SKILL.md:50-70](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/SKILL.md)\n\n## 工具目录中的风险索引\n\n工具目录按预设（preset）和风险级别双重索引，便于快速查找：\n\n```mermaid\ngraph LR\n A[工具目录] --> B[按预设索引]\n A --> C[按风险级别索引]\n B --> B1[security
audit
health
reports
identity
exchange
intune
governance
compliance
response
ediscovery
cloudpc
callrecords
print
infoprotection
sharepointadmin
retention]\n C --> C1[Critical
需带外审批]\n C --> C2[High
确认+预演]\n C --> C3[Medium
明确确认]\n C --> C4[Low
常规操作]\n```\n\n资料来源：[agent-skills/ms365-admin-mcp/references/tools-catalog.md:1-30](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/agent-skills/ms365-admin-mcp/references/tools-catalog.md)\n\n## 安全集成\n\n### 与其他安全机制的关系\n\n| 安全组件 | 集成点 | 说明 |\n|---------|-------|------|\n| SEC-G01 | `--max-risk-level` | 风险级别 cap 作为安全门控 |\n| SEC-G02 | 响应包装器 | Graph 响应被nonce信封包装，防止提示注入 |\n| SEC-G03 | 敏感读取标注 | 22个敏感GET工具已标注风险级别 |\n\n### 最小权限原则\n\n新工具必须：\n\n1. 声明最小必需的 Graph API 权限（`appPermissions`）\n2. 避免请求 `.ReadWrite.All` 当 `.Read.All` 足够时\n3. 所有写操作必须附带风险级别标注\n\n资料来源：[CONTRIBUTING.md:40-50](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/CONTRIBUTING.md)\n\n## 最佳实践\n\n### 开发新工具时的风险标注\n\n在 `endpoints.json` 中添加新工具时，必须包含风险级别：\n\n```json\n{\n \"toolName\": \"create-something\",\n \"method\": \"POST\",\n \"appPermissions\": [\"Something.ReadWrite.All\"],\n \"riskLevel\": \"medium\"\n}\n```\n\n### 风险升级场景\n\n以下情况应提升风险等级：\n\n- 操作影响多个实体\n- 操作修改凭证或访问权限\n- 操作产生不可逆的数据变更\n- 操作具有租户范围的影响\n\n### 降低风险的方法\n\n如需降低操作风险，可考虑：\n\n1. 添加预演/确认步骤\n2. 限制操作范围（单用户而非批量）\n3. 添加延迟执行或审批工作流\n4. 提供回滚机制\n\n## 总结\n\n风险模型是 ms-365-admin-mcp-server 安全架构的基础，通过四级风险体系（`low`、`medium`、`high`、`critical`）对所有515个管理工具进行分类。该模型配合 CLI 风险上限参数 `--max-risk-level` 和强制性的确认流程，确保管理员在执行敏感操作时经过充分审查，防止租户级别的意外或恶意更改。\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[配置参考](#page-configuration), [通信传输层](#page-transports)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/Dockerfile)\n- [docs/APP_REGISTRATION.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/APP_REGISTRATION.md)\n- [docs/AZURE_DEPLOYMENT_SECURITY.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/docs/AZURE_DEPLOYMENT_SECURITY.md)\n- [infra/main.bicep](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/infra/main.bicep)\n \n\n# 部署指南\n\n本文档提供 ms-365-admin-mcp-server 的完整部署指南，涵盖从 Azure AD 应用注册到容器化部署的全流程。\n\n## 1. 部署概述\n\n### 1.1 部署模式\n\nms-365-admin-mcp-server 支持两种主要部署模式：\n\n| 部署模式 | 说明 | 适用场景 |\n|---------|------|---------|\n| **STDIO 模式** | 标准输入输出通信，适合本地开发和 Claude Code 集成 | 本地开发、单用户 |\n| **HTTP 服务器模式** | REST API 服务，支持远程访问和 Docker 部署 | 生产环境、多租户 |\n\n### 1.2 核心部署架构\n\n```mermaid\ngraph TD\n A[客户端 MCP Client] -->|HTTP/gRPC| B[ms-365-admin-mcp-server]\n B --> C[Azure AD 应用注册]\n B --> D[Microsoft Graph API]\n D --> E[Microsoft 365 管理 API]\n \n F[Docker 容器] --> B\n G[Azure Container Instances] --> F\n H[Azure App Service] --> B\n```\n\n### 1.3 部署前提条件\n\n- Node.js 18+ (STDIO 模式)\n- Docker 20.10+ (容器模式)\n- Azure 订阅\n- Microsoft 365 租户管理员权限\n\n## 2. Azure AD 应用注册\n\n### 2.1 创建应用注册\n\n在 Azure Portal 中创建应用注册，配置以下设置：\n\n| 设置项 | 推荐值 | 说明 |\n|-------|--------|------|\n| 支持的账户类型 | 仅此组织目录中的账户 | 单租户部署 |\n| 重定向 URI | `http://localhost:7000` | 本地开发 |\n| 重定向 URI (生产) | `https:///mcp` | HTTP 服务器模式 |\n\n### 2.2 配置应用程序权限\n\nms-365-admin-mcp-server 使用应用程序权限（application permissions），需要以下 Graph API 权限：\n\n```json\n{\n \"requiredResourceAccess\": [\n {\n \"resourceAppId\": \"00000003-0000-0000-c000-000000000000\",\n \"resourceAccess\": [\n {\n \"id\": \"\",\n \"type\": \"Role\"\n }\n ]\n }\n ]\n}\n```\n\n资料来源：[docs/APP_REGISTRATION.md:1-50]()\n\n### 2.3 获取凭据\n\n部署需要以下环境变量：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | Azure AD 应用程序客户端 ID |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | 应用程序客户端密钥 |\n| `MS365_ADMIN_MCP_TENANT_ID` | Azure AD 租户 ID |\n\n## 3. Docker 部署\n\n### 3.1 拉取镜像\n\n```bash\n# 从 GitHub Container Registry 拉取\ndocker pull ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n\n# 验证镜像\ndocker run -d \\\n --name mcp-server \\\n -p 7000:7000 \\\n -e MS365_ADMIN_MCP_CLIENT_ID=\"\" \\\n -e MS365_ADMIN_MCP_CLIENT_SECRET=\"\" \\\n -e MS365_ADMIN_MCP_TENANT_ID=\"\" \\\n -e MS365_ADMIN_MCP_ALLOWED_CLIENTS=\"*\" \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n```\n\n### 3.2 Docker 容器安全配置\n\nDocker 镜像使用非 root 用户运行，确保容器安全性：\n\n```dockerfile\n# 基础镜像配置\nFROM node:18-alpine\n\n# 创建非 root 用户\nRUN addgroup -g 1001 -S mcpuser && \\\n adduser -S mcpuser -u 1001\n\n# 切换到非 root 用户\nUSER mcpuser\n\n# 设置工作目录\nWORKDIR /app\n```\n\n资料来源：[Dockerfile:1-30]()\n\n### 3.3 卷挂载配置\n\n生产环境建议挂载日志目录：\n\n```bash\ndocker run -d \\\n --name mcp-server \\\n -p 7000:7000 \\\n -v /path/to/config:/app/config:ro \\\n -v /path/to/logs:/var/log/mcp-server \\\n -e MS365_ADMIN_MCP_LOG_DIR=\"/var/log/mcp-server\" \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n```\n\n## 4. Azure 基础设施部署\n\n### 4.1 Bicep 部署架构\n\n```mermaid\ngraph TD\n A[main.bicep] --> B[Azure Container Instance]\n A --> C[用户托管身份 UAMI]\n A --> D[Azure Key Vault]\n A --> E[虚拟网络]\n \n B --> C\n B --> D\n C --> D\n \n F[Private Container Registry] --> B\n```\n\n### 4.2 必需参数\n\n| 参数名 | 类型 | 必需 | 说明 |\n|-------|------|-----|------|\n| `allowedClients` | string | 是 | 允许访问的客户端 CIDR 列表 |\n| `acrLoginServer` | string | 否 | 私有容器注册表服务器 |\n| `tags` | object | 否 | 资源标签 |\n| `location` | string | 否 | 部署区域 |\n\n资料来源：[infra/main.bicep:1-100]()\n\n### 4.3 部署命令\n\n```bash\n# 使用 Azure CLI 部署\naz deployment sub create \\\n --location eastus \\\n --template-file infra/main.bicep \\\n --parameters allowedClients=\"['10.0.0.0/8']\" \\\n --parameters acrLoginServer=\"myregistry.azurecr.io\"\n\n# 验证部署\naz container show --resource-group --name \n```\n\n### 4.4 用户托管身份配置\n\nBicep 模板自动配置用户托管身份（UAMI）用于：\n\n- 从 Azure Key Vault 检索客户端密钥\n- 访问 Azure 资源\n- 容器注册表拉取镜像\n\n```bicep\nresource uami 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {\n name: 'mcp-server-identity'\n location: location\n}\n```\n\n资料来源：[infra/main.bicep:100-150]()\n\n## 5. HTTP 服务器模式配置\n\n### 5.1 启动参数\n\n| 参数 | 默认值 | 说明 |\n|-----|-------|------|\n| `--port` | 7000 | HTTP 服务器监听端口 |\n| `--host` | 0.0.0.0 | 绑定地址 |\n| `--allowed-clients` | - | 允许的客户端 IP/CIDR |\n| `--log-dir` | - | 日志目录 |\n| `--allow-writes` | false | 允许写操作 |\n| `--max-risk-level` | medium | 最大风险级别 |\n| `--preset` | - | 预置工具类别 |\n| `--enabled-tools` | - | 启用工具正则表达式 |\n\n### 5.2 安全配置\n\n| 安全功能 | 默认状态 | 说明 |\n|---------|---------|------|\n| 安全头 | 启用 | X-Content-Type-Options, X-Frame-Options, CSP |\n| Body 大小限制 | 100KB | 防止大文件攻击 |\n| 路径参数验证 | 启用 | 防止路径遍历 |\n| ReDoS 保护 | 启用 | 正则表达式长度限制 500 字符 |\n| 敏感数据脱敏 | 启用 | 日志中不泄露密钥 |\n\n资料来源：[docs/AZURE_DEPLOYMENT_SECURITY.md:1-50]()\n\n### 5.3 设备代码认证流程\n\nHTTP 服务器支持设备代码认证（device_code flow），适用于无法使用客户端密钥的场景：\n\n```bash\n# 启动服务器并触发设备代码认证\nnode dist/index.js --http --device-code\n\n# 输出示例\n# To sign in, use a web browser to open the page https://microsoft.com/devicelogin\n# and enter the code ABC12345 to authenticate.\n```\n\n认证流程：\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant S as MCP 服务器\n participant A as Azure AD\n \n C->>S: 请求 /token (device_code)\n S->>A: POST /devicecode\n A-->>S: device_code, user_code\n S-->>C: 显示 user_code\n C->>S: 轮询 /token\n Note over C: 用户在浏览器输入 code\n C->>A: 用户在 microsoft.com/devicelogin 认证\n A-->>S: 返回 tokens\n S-->>C: 返回 access_token\n```\n\n## 6. 环境变量配置\n\n### 6.1 完整环境变量列表\n\n| 环境变量 | 必需 | 默认值 | 说明 |\n|---------|-----|-------|------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | 是 | - | Azure AD 客户端 ID |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | 是* | - | 客户端密钥 |\n| `MS365_ADMIN_MCP_TENANT_ID` | 是 | - | 租户 ID |\n| `MS365_ADMIN_MCP_LOG_DIR` | 否 | - | 日志目录 |\n| `MS365_ADMIN_MCP_PORT` | 否 | 7000 | HTTP 端口 |\n| `MS365_ADMIN_MCP_HOST` | 否 | 0.0.0.0 | 绑定主机 |\n| `MS365_ADMIN_MCP_ALLOWED_CLIENTS` | 否 | - | 允许的客户端 |\n| `MS365_ADMIN_MCP_ALLOW_WRITES` | 否 | false | 允许写操作 |\n| `MS365_ADMIN_MCP_MAX_RISK_LEVEL` | 否 | medium | 最大风险级别 |\n| `MCP_REMOTE_CONFIG_DIR` | 否 | ~/.mcp-auth | OAuth 缓存目录 |\n\n*设备代码模式下不需要\n\n### 6.2 日志配置\n\nWinston 日志默认使用以下路径：\n\n```bash\n# 容器环境默认日志路径\nMS365_ADMIN_MCP_LOG_DIR=/tmp/.ms365-admin-mcp/logs\n```\n\n注意：在 Bicep 模板中已配置为 `/tmp/...`，避免 rootless 用户在 `/nonexistent/.ms365-admin-mcp/logs` 出现权限错误。\n\n## 7. 生产环境检查清单\n\n### 7.1 部署前检查\n\n- [ ] Azure AD 应用注册已完成\n- [ ] 所需 Graph API 权限已获批准\n- [ ] 客户端 ID 和租户 ID 已获取\n- [ ] 客户端密钥已生成并安全存储\n- [ ] 网络策略已配置（允许来自 MCP 客户端的访问）\n- [ ] 日志存储已配置\n\n### 7.2 安全检查清单\n\n- [ ] 使用 HTTPS（生产环境）\n- [ ] 配置 `allowedClients` 限制访问\n- [ ] `ALLOW_WRITES` 默认关闭\n- [ ] 监控日志中的敏感信息泄露\n- [ ] 定期轮换客户端密钥\n- [ ] 配置 Key Vault 存储密钥\n\n资料来源：[docs/AZURE_DEPLOYMENT_SECURITY.md:50-100]()\n\n### 7.3 高可用性配置\n\n```bash\n# 使用 Azure Container Apps 实现高可用\naz containerapp create \\\n --name mcp-server \\\n --resource-group \\\n --environment \\\n --image ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest \\\n --min-replicas 2 \\\n --max-replicas 10\n```\n\n## 8. 故障排除\n\n### 8.1 常见部署错误\n\n| 错误 | 原因 | 解决方案 |\n|-----|------|---------|\n| `EACCES` 日志写入失败 | 权限问题 | 设置 `MS365_ADMIN_MCP_LOG_DIR=/tmp/...` |\n| `tenant_rejected` | 使用了 `common` 端点 | 改用单租户 `organizations` 端点 |\n| `Server disconnected` | 设备代码认证超时 | 重新启动认证流程 |\n| 401 Unauthorized | 客户端密钥过期 | 更新密钥或使用设备代码流 |\n\n### 8.2 容器日志查看\n\n```bash\n# 查看容器日志\ndocker logs mcp-server\n\n# 实时跟踪日志\ndocker logs -f mcp-server\n\n# 进入容器调试\ndocker exec -it mcp-server sh\n```\n\n### 8.3 网络连通性测试\n\n```bash\n# 测试 Graph API 连通性\ncurl -v https://graph.microsoft.com/v1.0/$select\n\n# 测试 Token 端点\ncurl -v -X POST https://login.microsoftonline.com//oauth2/v2.0/token\n```\n\n## 9. 相关文档\n\n- [应用注册指南](docs/APP_REGISTRATION.md)\n- [Azure 部署安全](docs/AZURE_DEPLOYMENT_SECURITY.md)\n- [架构文档](docs/ARCHITECTURE.md)\n- [使用案例](docs/USE_CASES.md)\n- [故障排除](docs/TROUBLESHOOTING.md)\n\n---\n\n\n\n## 配置参考\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment), [认证系统](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cloud-config.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n- [src/endpoints.json](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/endpoints.json)\n- [src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n- [src/secrets.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/secrets.ts)\n- [README.md](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/README.md)\n- [src/tool-categories.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n- [src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n \n\n# 配置参考\n\n本页面详细说明 ms-365-admin-mcp-server 的所有配置选项，包括环境变量、云端配置、认证方式、预设分组以及风险级别策略。\n\n## 1. 环境变量配置\n\n服务器通过环境变量读取 Azure AD 应用注册凭据。支持两种模式：标准环境和 Azure 中国区（21Vianet）。\n\n### 1.1 必需的环境变量\n\n| 环境变量 | 描述 | 示例 |\n|---------|------|------|\n| `MS365_ADMIN_MCP_CLIENT_ID` | Azure AD 应用程序（客户端）ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |\n| `MS365_ADMIN_MCP_CLIENT_SECRET` | 客户端密钥 | `~xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |\n| `MS365_ADMIN_MCP_TENANT_ID` | Azure AD 租户 ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |\n\n### 1.2 云端环境配置\n\n| 环境变量 | 默认值 | 描述 |\n|---------|--------|------|\n| `MS365_ADMIN_MCP_CLOUD` | `global` | 云环境：`global`（全球版）或 `cn`（中国区 21Vianet） |\n\n资料来源：[src/cloud-config.ts:1-50](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n\n### 1.3 服务器运行配置\n\n| 环境变量 | 默认值 | 描述 |\n|---------|--------|------|\n| `MS365_ADMIN_MCP_PORT` | `3000` | HTTP 服务器监听端口 |\n| `MS365_ADMIN_MCP_HOST` | `0.0.0.0` | HTTP 服务器绑定地址 |\n| `MS365_ADMIN_MCP_ALLOW_WRITES` | `false` | 允许执行写入操作 |\n| `MS365_ADMIN_MCP_MAX_RISK_LEVEL` | `medium` | 最大允许风险级别 |\n| `MS365_ADMIN_MCP_PRESET` | `all` | 初始工具预设分组 |\n\n### 1.4 认证缓存配置\n\n| 环境变量 | 默认值 | 描述 |\n|---------|--------|------|\n| `MCP_REMOTE_CONFIG_DIR` | `~/.mcp-auth/mcp-remote-/` | 设备码认证缓存目录 |\n| `AZURE_CLIENT_SECRET` | - | Key Vault 密钥保管库模式下的客户端密钥 |\n\n资料来源：[src/secrets.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/secrets.ts)\n\n## 2. 云端配置详解\n\n### 2.1 云环境端点\n\n服务器支持两种 Microsoft 365 云环境：\n\n```mermaid\ngraph TD\n A[启动服务器] --> B{MS365_ADMIN_MCP_CLOUD?}\n B -->|global| C[全球版端点]\n B -->|cn| D[中国区端点 21Vianet]\n C --> E[login.microsoftonline.com]\n D --> F[login.partner.microsoftonline.cn]\n```\n\n**全球版端点：**\n\n| 用途 | 端点 URL |\n|------|----------|\n| Microsoft Graph | `https://graph.microsoft.com` |\n| Azure AD 令牌 | `https://login.microsoftonline.com` |\n| Azure Key Vault | `https://vault.azure.net` |\n\n**中国区（21Vianet）端点：**\n\n| 用途 | 端点 URL |\n|------|----------|\n| Microsoft Graph | `https://microsoftgraph.chinacloudapi.cn` |\n| Azure AD 令牌 | `https://login.partner.microsoftonline.cn` |\n| Azure Key Vault | `https://vault.azure.cn` |\n\n资料来源：[src/cloud-config.ts:10-45](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/cloud-config.ts)\n\n## 3. 认证配置\n\n### 3.1 认证流程\n\n服务器使用 MSAL（Microsoft Authentication Library）的客户端凭据流（Client Credentials Flow）进行身份验证：\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Azure AD\n \n Client->>Server: 请求调用工具\n Server->>Azure AD: 获取访问令牌 (client_credentials)\n Azure AD-->>Server: access_token\n Server->>Microsoft Graph: API 请求 + access_token\n Microsoft Graph-->>Server: 响应数据\n Server-->>Client: 工具执行结果\n```\n\n### 3.2 认证模式\n\n| 模式 | 配置方式 | 说明 |\n|------|----------|------|\n| 环境变量 | `MS365_ADMIN_MCP_CLIENT_SECRET` | 最简方式，直接明文存储密钥 |\n| Key Vault | `AZURE_CLIENT_SECRET` + Key Vault URI | 生产环境推荐，密钥由 Azure Key Vault 管理 |\n\n资料来源：[src/auth.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/auth.ts)\n\n### 3.3 设备码认证（远程 HTTP 服务器）\n\n对于远程 HTTP 服务器部署，服务器支持 RFC 8628 设备码流：\n\n```bash\n# 预填充认证缓存\nms-365-admin-mcp-auth --server https://your-host.azurecontainerapps.io/mcp\n\n# 退出码说明\n# 0 - 成功\n# 1 - 用法错误\n# 2 - 网络错误\n# 3 - 认证被拒绝\n# 4 - 超时\n```\n\n认证缓存位置：`~/.mcp-auth/mcp-remote-/`，包含：\n- `_client_info.json`\n- `_tokens.json`\n\n缓存密钥使用 `md5(serverUrl)` 计算，与 `mcp-remote` 的 `getServerUrlHash` 完全匹配。\n\n## 4. 工具预设分组\n\n工具预设（Presets）用于按功能域分组暴露管理工具，减少 MCP 客户端需要处理的工具数量。\n\n### 4.1 可用预设列表\n\n| 预设名称 | 说明 | 包含工具类型 |\n|---------|------|-------------|\n| `security` | 安全警报、事件、攻击模拟、威胁情报 | Microsoft 365 Defender 相关 |\n| `audit` | 审计日志、登录日志、已删除项目 | 目录审计、登录、预配 |\n| `health` | 服务健康状况、消息中心公告 | 服务状态、问题、消息 |\n| `reports` | 使用报告 | Teams、邮件、SharePoint、OneDrive、M365 应用 |\n| `identity` | 身份和访问管理 | 用户、组、角色、设备、PIM、访客用户、外部身份 |\n| `exchange` | Exchange 管理 | 邮件追踪、邮箱、收件人 |\n| `intune` | Intune 设备管理 | 设备、合规、配置、Autopilot、应用、RBAC |\n| `governance` | 标识治理 | 访问评审、权利管理、生命周期工作流、TOU、应用同意 |\n| `compliance` | 合规性管理 | 许可证、安全分数、身份保护、风险检测、条件访问 |\n| `response` | 事件响应操作 | 禁用用户、撤销会话、确认泄露、 dismissing 风险 |\n| `ediscovery` | 电子发现案例 | Microsoft Purview |\n| `cloudpc` | Cloud PC / Windows 365 | 云电脑、预配策略、设备镜像 |\n| `callrecords` | Teams 通话记录 | 会话、段、参与者、PSTN 通话、Direct Routing |\n| `print` | 通用打印 | 打印机、共享、连接器、服务 |\n| `infoprotection` | 信息保护 | BitLocker、威胁评估、敏感度标签 |\n| `sharepointadmin` | SharePoint 管理 | SharePoint 租户管理 |\n| `retention` | 记录管理 | 保留策略、处置工作流 |\n| `teamsadmin` | Teams 管理 | 团队、频道、成员、应用、策略 |\n| `all` | 所有可用工具 | 全部 515 个工具 |\n\n资料来源：[src/tool-categories.ts:1-80](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/tool-categories.ts)\n\n### 4.2 预设模式匹配规则\n\n每个预设通过正则表达式模式匹配工具名称：\n\n```typescript\n// 示例：identity 预设的匹配模式\n/role|directory|domain|auth-method|credential|application|service-principal|sp-password|sp-key|sp-token|sp-owner|oauth2|organization|named-location|device|administrative-unit|cross-tenant|pim|app-role|invitation|identity-provider|b2x|api-connector|custom-auth/i\n```\n\n### 4.3 组合预设\n\n支持同时启用多个预设：\n\n```typescript\nimport { getCombinedPresetPattern } from './tool-categories';\n\nconst combined = getCombinedPresetPattern(['security', 'audit']);\n// 返回组合后的正则表达式\n```\n\n## 5. 风险级别策略\n\n### 5.1 风险级别定义\n\n| 级别 | 含义 | 示例工具 |\n|------|------|----------|\n| `low` | 只读操作，查询类操作 | `list-users`、`get-team` |\n| `medium` | 有限影响，局部修改 | `create-team`、`update-user` |\n| `high` | 重大影响，范围广泛或凭证变更 | `revoke-user-sessions`、`update-conditional-access-policy` |\n| `critical` | 不可逆或租户范围影响 | `delete-user`、`wipe-managed-device`、`delete-conditional-access-policy` |\n\n资料来源：[src/risk-level.ts](https://github.com/okapi-ca/ms-365-admin-mcp-server/blob/main/src/risk-level.ts)\n\n### 5.2 风险级别判定逻辑\n\n```mermaid\ngraph TD\n A[工具执行请求] --> B{配置了 riskLevel?}\n B -->|是| C[使用配置的 riskLevel]\n B -->|否| D{HTTP 方法是 GET?}\n D -->|是| E[默认为 low]\n D -->|否| F[默认为 critical]\n C --> G[与 maxRiskLevel 比较]\n E --> G\n F --> G\n G --> H{rank ≤ maxRiskLevel?}\n H -->|是| I[允许执行]\n H -->|否| J[拒绝执行]\n```\n\n风险等级排序（从小到大）：`low` < `medium` < `high` < `critical`\n\n### 5.3 关键工具列表\n\n**Critical 级别（需要带外审批）：**\n\n| 工具 | 风险 |\n|------|------|\n| `delete-user` | critical |\n| `delete-group` | critical |\n| `delete-application` | critical |\n| `delete-service-principal` | critical |\n| `delete-conditional-access-policy` | critical |\n| `delete-exchange-mailbox` | critical |\n| `delete-ediscovery-case` | critical |\n| `delete-team` | critical |\n| `delete-managed-device` | critical |\n| `wipe-managed-device` | critical |\n| `clean-windows-device` | critical |\n| `add-directory-role-member` | critical |\n| `create-pim-role-assignment-request` | critical |\n| `disable-user-account` | critical |\n\n**High 级别（需要明确确认）：**\n\n| 工具 | 风险 |\n|------|------|\n| `revoke-user-sessions` | high |\n| `confirm-compromised-users` | high |\n| `dismiss-risky-users` | high |\n| `change-user-password` | high |\n| `create-conditional-access-policy` | high |\n| `delete-named-location` | high |\n| `create-auth-strength-policy` | high |\n\n## 6. 端点配置\n\n### 6.1 端点定义格式\n\n`endpoints.json` 是工具定义的信任源，每个端点包含：\n\n```jsonc\n{\n \"toolName\": \"list-users\",\n \"pathPattern\": \"/users\",\n \"method\": \"GET\",\n \"appPermissions\": [\"User.Read.All\"],\n \"llmTip\": \"可选的提示信息，显示在工具描述中\"\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `toolName` | string | 是 | 工具唯一标识符 |\n| `pathPattern` | string | 是 | Microsoft Graph API 路径 |\n| `method` | string | 是 | HTTP 方法（GET/POST/PATCH/DELETE） |\n| `appPermissions` | string[] | 是 | 所需的应用权限 |\n| `llmTip` | string | 否 | 展示给 LLM 的提示信息 |\n| `riskLevel` | string | 否 | 风险级别（仅非 GET 方法需要） |\n\n### 6.2 必需权限示例\n\n| 工具域 | 所需权限 |\n|--------|----------|\n| 用户管理 | `User.Read.All`, `User.ReadWrite.All` |\n| 组管理 | `Group.Read.All`, `Group.ReadWrite.All` |\n| 设备管理 | `Device.Read.All`, `Device.ReadWrite.All` |\n| 安全 | `SecurityEvents.Read.All`, `SecurityEvents.ReadWrite.All` |\n| Intune | `DeviceManagementManagedDevices.Read.All` |\n\n## 7. CLI 命令行参数\n\n### 7.1 本地模式（Stdio）\n\n```bash\nms-365-admin-mcp-server [options]\n\n选项：\n --preset 工具预设分组\n --allow-writes 允许写入操作\n --max-risk-level 最大风险级别 (low/medium/high/critical)\n --list-tools 列出指定预设的工具\n --list-permissions 列出所需 Graph 权限\n --version, -v 显示版本\n --help, -h 显示帮助\n```\n\n### 7.2 HTTP 服务器模式\n\n```bash\nms-365-admin-mcp-server --http [options]\n\nHTTP 专用选项：\n --port 监听端口 (默认: 3000)\n --host 绑定地址 (默认: 0.0.0.0)\n```\n\n### 7.3 认证引导\n\n```bash\nms-365-admin-mcp-auth --server [options]\n\n选项：\n -s, --server MCP 服务器 URL（必需）\n --scope 覆盖 OAuth scope\n --cache-dir 缓存目录覆盖\n```\n\n## 8. 本地开发配置\n\n### 8.1 本地 .env 文件格式\n\n```bash\n# Azure AD 应用注册\nMS365_ADMIN_MCP_CLIENT_ID=your-client-id\nMS365_ADMIN_MCP_CLIENT_SECRET=your-client-secret\nMS365_ADMIN_MCP_TENANT_ID=your-tenant-id\n\n# 可选：云环境 (默认 global)\nMS365_ADMIN_MCP_CLOUD=global\n```\n\n### 8.2 开发验证命令\n\n```bash\n# 验证工具列表\nnode dist/index.js --preset security --list-tools\n\n# 验证所需权限\nnode dist/index.js --preset identity --list-permissions\n\n# 运行 MCP 检查器\nnpm run inspector\n```\n\n## 9. Docker 部署配置\n\n### 9.1 环境变量配置\n\n```bash\ndocker run -e MS365_ADMIN_MCP_CLIENT_ID=xxx \\\n -e MS365_ADMIN_MCP_CLIENT_SECRET=xxx \\\n -e MS365_ADMIN_MCP_TENANT_ID=xxx \\\n -e MS365_ADMIN_MCP_PORT=3000 \\\n ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n```\n\n### 9.2 Docker Compose 示例\n\n```yaml\nservices:\n mcp-server:\n image: ghcr.io/okapi-ca/ms-365-admin-mcp-server:latest\n environment:\n MS365_ADMIN_MCP_CLIENT_ID: \"${CLIENT_ID}\"\n MS365_ADMIN_MCP_CLIENT_SECRET: \"${CLIENT_SECRET}\"\n MS365_ADMIN_MCP_TENANT_ID: \"${TENANT_ID}\"\n MS365_ADMIN_MCP_CLOUD: \"global\"\n MS365_ADMIN_MCP_PORT: \"3000\"\n ports:\n - \"3000:3000\"\n```\n\n## 10. Azure Container Apps 部署\n\n通过 Bicep 模板部署时，可在 `infra/main.bicep` 中配置：\n\n```bicep\n// 环境变量通过 Key Vault 引用\nMS365_ADMIN_MCP_CLIENT_ID: keyVaultSecret('client-id')\nMS365_ADMIN_MCP_CLIENT_SECRET: keyVaultSecret('client-secret')\nMS365_ADMIN_MCP_TENANT_ID: keyVaultSecret('tenant-id')\nMS365_ADMIN_MCP_CLOUD: 'global'\n```\n\n## 11. 故障排除配置\n\n### 11.1 常见配置问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 认证失败 | 客户端密钥过期 | 续订 Azure AD 应用密钥 |\n| 权限不足 | 缺少 Graph API 权限 | 在 Azure AD 中添加所需权限 |\n| 工具不可用 | 预设配置错误 | 使用 `--list-tools` 验证工具列表 |\n| 写入被拒绝 | `--allow-writes` 未启用 | 添加 `--allow-writes` 参数 |\n\n### 11.2 调试日志\n\n服务器使用 Winston 日志记录器，通过设置日志级别环境变量可获取详细调试信息：\n\n```bash\n# 启用调试日志\nDEBUG=ms-365-admin-mcp-server:* ms-365-admin-mcp-server\n```\n\n## 12. 配置验证清单\n\n部署前请确认以下配置项：\n\n- [ ] Azure AD 应用已注册且 `CLIENT_ID`、`CLIENT_SECRET`、`TENANT_ID` 已获取\n- [ ] 应用已授权所需 Graph API 权限（使用最小权限原则）\n- [ ] 根据部署区域选择正确的 `MS365_ADMIN_MCP_CLOUD` 值\n- [ ] 生产环境建议使用 Azure Key Vault 管理密钥\n- [ ] `max-risk-level` 已根据组织安全策略配置\n- [ ] 对于远程 HTTP 部署，已运行设备码引导流程\n- [ ] 已通过 `--list-permissions` 验证所需权限\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：okapi-ca/ms-365-admin-mcp-server\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ede43fd3f7247e0981524934656dbeb | https://github.com/okapi-ca/ms-365-admin-mcp-server/issues/71 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：okapi-ca/ms-365-admin-mcp-server\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：SEC-004: UPN persisted in logs without redaction option (PII / GDPR exposure)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ede43fd3f7247e0981524934656dbeb | https://github.com/okapi-ca/ms-365-admin-mcp-server/issues/71 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1210842314 | https://github.com/okapi-ca/ms-365-admin-mcp-server | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# ms-365-admin-mcp-server - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 ms-365-admin-mcp-server 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-features：核心功能特性。围绕“核心功能特性”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-authentication：认证系统。围绕“认证系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-authorization：授权机制。围绕“授权机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-features\n输入：用户提供的“核心功能特性”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-authentication\n输入：用户提供的“认证系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-authorization\n输入：用户提供的“授权机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-features：Step 2 必须围绕“核心功能特性”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-authentication：Step 4 必须围绕“认证系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-authorization：Step 5 必须围绕“授权机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/okapi-ca/ms-365-admin-mcp-server\n- https://github.com/okapi-ca/ms-365-admin-mcp-server#readme\n- agent-skills/ms365-admin-mcp/SKILL.md\n- README.md\n- package.json\n- src/tool-categories.ts\n- src/graph-tools.ts\n- docs/ARCHITECTURE.md\n- src/graph-client.ts\n- src/server.ts\n- bin/modules/generate-mcp-tools.mjs\n- src/auth.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 ms-365-admin-mcp-server 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：okapi-ca/ms-365-admin-mcp-server\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @okapi-ca/ms-365-admin-mcp-server\n```\n\n来源：https://github.com/okapi-ca/ms-365-admin-mcp-server#readme\n\n## 来源\n\n- repo: https://github.com/okapi-ca/ms-365-admin-mcp-server\n- docs: https://github.com/okapi-ca/ms-365-admin-mcp-server#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_678c9500d6074d149e9cde5a9883812a"
}