Microsoft 365 Reporting MCP — v1.0

企业级 MCP 服务器，ChatGPT、Claude 及其他兼容 MCP 的 AI 客户端可以通过它以受控的方式访问 Microsoft 365 的信息源（Outlook、日历、Teams、会议记录、OneNote、SharePoint、OneDrive、Loop、搜索、用户）。

基本原则：read broadly, write narrowly。 在已登录用户实际拥有的 M365 权限范围内提供宽泛的 READ 层；唯一的 WRITE 能力是 Outlook 邮件发送（draft / send / reply / forward），任何实际发送都设有单独的 confirm=true 门控。

架构

ChatGPT / Claude / MCP kliens
        │  MCP over HTTPS (Streamable HTTP) + OAuth bearer token
        ▼
┌──────────────────────────────┐
│  m365-reporting-mcp          │   Tool allowlist (86 tool, 11 WRITE = csak mail)
│  · JWT validálás (Entra)     │   Nincs generikus graph-request / $batch passthrough
│  · On-Behalf-Of tokencsere   │   Audit log (JSONL, tartalom nélkül)
│  · Pagination + 429 retry    │   Forráskövetés (_source blokk minden objektumon)
│  · Admin dashboard (/admin)  │
└──────────────┬───────────────┘
               │  OAuth 2.0 OBO → delegated Graph token
               ▼
    Microsoft Entra ID → Microsoft Graph API (v1.0)

该服务器绝不使用 app-only 权限：所有 Graph 调用都以已登录用户身份运行（delegated），因此 MCP 无法绕过现有的 M365 访问规则。

Related MCP server: Microsoft Graph MCP Server

Entra ID 应用注册

1. 创建 App registration（单租户）。

2. Expose an API：Application ID URI = api://<CLIENT_ID>，scope：access_as_user。将 accessTokenAcceptedVersion 设置为 2（manifest）。

3. Grant API permissions（Microsoft Graph，Delegated）——完整列表见 docs/tool-matrix.md 附录；概括如下：

   • READ: Mail.Read, Mail.Read.Shared, Calendars.Read, Chat.Read, Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All, TeamMember.Read.All, OnlineMeetings.Read, OnlineMeetingTranscript.Read.All, OnlineMeetingRecording.Read.All, OnlineMeetingArtifact.Read.All, Notes.Read, Notes.Read.All, Sites.Read.All, Files.Read, Files.Read.All, People.Read, User.Read, User.ReadBasic.All, User.Read.All

   • WRITE（仅邮件）：Mail.ReadWrite, Mail.Send, Mail.ReadWrite.Shared, Mail.Send.Shared

   • 对 .All 作用域需要 Admin consent。

4. HTTP 模式：Certificates & secrets → client secret。

5. stdio/开发模式：Authentication → “Allow public client flows” = Yes（设备代码）。

针对 spec 第 11 点的说明：Sites.Selected 仅在 application 权限中存在；在 delegated（以用户身份运行）模式下，站点级（site-level）的收窄由用户自己的 SharePoint 权限提供——MCP 使用 delegated Sites.Read.All，而它本身并不会为访问者提供其原本无法访问的 site 的访问权限。

安装与运行

npm install
cp .env.example .env      # töltsd ki: TENANT_ID, CLIENT_ID, CLIENT_SECRET, BASE_URL, ADMIN_KEY
npm run build

# Webapp (remote MCP) mód:
npm run start:http

# Lokális/dev (stdio, device code login):
npm run login             # egyszeri bejelentkezés, token cache-elve
npm start

HTTP 模式的端点：

在 HTTP 模式中，服务器无需 Entra 数据也能启动：首次配置可以在 /admin 界面完成（Tenant ID、Client ID、Client Secret、Base URL、连接测试）——保存后立即生效，设置保存在 data/settings.json 中并覆盖 .env 的内容。

连接 ChatGPT（及其他 MCP 客户端）

服务器在 Entra ID 之前包含内置的 OAuth proxy，因为 ChatGPT connector 需要 RFC 7591 规范的 dynamic client 注册，而 Entra 不支持。该 proxy 对客户端提供完整的 OAuth 2.1 接口（DCR + PKCE），对 Entra 则使用唯一已注册的企业应用；发给客户端的 access token 就是 Entra 为 api://<CLIENT_ID> 签发的 token，因此 /mcp 的校验和 OBO Graph 交换保持不变——每次调用都会以已记录的用户身份进行。

从 ChatGPT 连接：

1. 在 Entra 应用的 Authentication 部分，添加 Web 重定向 URI：https://<BASE_URL>/auth/callback（准确值可由子 Admin 中“设置”选项卡）。

2. ChatGPT → Settings → Connectors → 新建一个 MCP connector，URL：https://<BASE_URL>/mcp。

3. 出现的登录界面是企业 Entra ID 登录窗口——用户将登录自己的账户，并获得自己拥有的 M365 权限。

Claude Desktop / Claude Code：用同一 URL 作为 remote MCP，Claude code 可在本地使用 stdio 模式（claude mcp add m365-reporting -- node dist/index.js --stdio）。

安全层（spec 19–20）

• 不提供可对任意 method, url, body 的工具端点的通用 graph_request，也不充当 $batch passthrough——只有 86 个被允许的端点可用。

• 不会写入Calendar/Teams/Files/Sites/OneNote/Users/Groups，也没有 delete 操作。

• 创建草稿不等于发送权限：每个 send/reply/forward 都要求 confirm=true，而且工具描述要求 AI 先跟用户确认确认。

• READ_ONLY=true（read-only syscall）可以将所有写工具禁用；TOOLS /（TOOLSETS）ENABLED_TOOLSETS 可以按套件收敛工具集（例如 mail,calendar,meetings）。

审计（spec 21）

所有调用都会记录到 JSON lines（logs/audit-YYYY-MM-DD.jsonl）：timestamp, user, session, tool, operation (READ/WRITE), resourceType, graphEndpoint, httpMethod, success, durationMs，此外，WRITE 还返回 sender, recipients, Bcc处省略, subject, messageId, result。绝不将正文、transcript、文档或 token 写入日志。

容错（spec 22–23）

• HTTP 429/503/504：自动重试，依从 Retry-After（最多 4 次）；

• 所有列表型工具都支持 @odata.nextLink 分页（maxParameters 参数，并注明截断）；

• token 过期 / 无权限 / 资源及时：返回对 AI 明确且可操作的错误消息（如 error-based；

• 文件基于 MAX_DOWNLOAD_BYTES 设置大小限制，DOCX/XLSX/PPTX/PDF/TXT/CSV → 文本抽取，其他二进制 → base64 编码。

Tool 矩阵（开发者附件）

完整的 MCP tool → Graph endpoint → HTTP method → delegated permission → READ/WRITE → enabled 矩阵作为生成文档给出：docs/tool-matrix.md（npm run 用 src/tools/endpoints/*.ts 中的定义更新 npm run 矩阵）。

Loop 适配器限制（spec 13）

并没有通常可用的专用于 Graph Loop workspaces API，因此 Loop adapter 不发送 fake endpoints：它通过 Search API 和 SharePoint/OneDrive drives 访问 .loop/.fluid 组件。存储在 SharePoint Embedded 容器中的 Loop workspaces 可能可以在 delegated Graph 中访问——这个限制也由 tool description 告诉 AI，让 AI 还将此限制传给用户。

验收测试（spec 26）

从已连接的客户端发出自然语言指令：„检查我过去 30 天的邮件、日历、Teams 聊天和会议記錄……为 X 项目做一份摘要……摘录做成 email，并在单独确认后发送。"——预期工具链为：get-calendar-view → find-online-meeting-by-join-url → list-meeting-transcripts → get-meeting-transcript-content + list-mail-messages + list-chat-messages + search-onenote-pages + search-m365 → create-draft-email →（用户确认）→ send-draft-email(confirm=true)。