Microsoft 365 Reporting MCP — v1.0

企業向けMCPサーバー。ChatGPT、Claude、およびその他のMCP互換AIクライアントが、Microsoft 365の情報ソース（Outlook、カレンダー、Teams、会議文字起こし、OneNote、SharePoint、OneDrive、Loop、Search、Users）に制御された形でアクセスできるようにする。

基本原則: 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を作成（single tenant）。

2. Expose an API: Application ID URI = api://<CLIENT_ID>、scope: access_as_user。accessTokenAcceptedVersionを2に設定する（manifest）。

3. 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スコープには管理者の同意が必要。

4. HTTPモードの場合: Certificates & secrets → client secret。

5. stdio/devモードの場合: Authentication → 「Allow public client flows」 = Yes（device code）。

仕様の項目11への注記: Sites.Selectedはapplication権限としてのみ存在する。delegated（ユーザー名義で実行）モデルでは、サイトレベルの制限はユーザー自身のSharePoint権限によって与えられる。MCPはdelegated Sites.Read.Allを使用するが、これは単独では、ユーザーが通常アクセスできないサイトへのアクセスを許可するものではない。

インストールと実行

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プロキシを含む。ChatGPTコネクタはRFC 7591に基づくdynamic client registrationを要求するが、Entraはこれをサポートしないためである。プロキシはクライアントに対して完全なOAuth 2.1インターフェース（DCR + PKCE）を提供し、Entraに対しては登録済みの単一の企業アプリを使用する。クライアントに発行されるアクセストークンは、Entraがapi://<CLIENT_ID>に対して発行したトークンそのものであり、/mcpの検証とOBO Graph交換は変更されない。すべての呼び出しはログイン済みユーザーの名義で実行される。

ChatGPTからの接続:

1. EntraアプリのAuthenticationセクションで、Web redirect URIとしてhttps://<BASE_URL>/auth/callbackを追加する（正確な値は管理画面の設定タブに表示される）。

2. ChatGPT → Settings → Connectors → 新しいMCPコネクタ、URL: https://<BASE_URL>/mcp。

3. 表示されるログインは企業のEntra IDログインであり、ユーザーは自分のアカウントでログインし、自分のM365権限のみを取得する。

Claude Desktop / Claude Code: 同じURLをリモートMCPとして使用するか、ローカルでstdioモード（claude mcp add m365-reporting -- node dist/index.js --stdio）を使用する。

セキュリティレイヤー（仕様19–20）

• 汎用のgraph_request(method, url, body)ツールや$batchパススルーは存在しない。利用可能なのは許可リスト登録済みの86エンドポイントのみ。

• Calendar/Teams/Files/Sites/OneNote/User/Groupの書き込みは存在せず、削除もどこにも存在しない。

• 下書き作成≠送信権限: すべてのsend/reply/forwardはconfirm=trueを要求し、ツールの説明はAIに対し、先に明示的なユーザー承認を求めるよう指示する。

• READ_ONLY=true環境変数で全writeツールを無効化できる。ENABLED_TOOLSETSでツールセットレベルのプロファイルを絞り込める（例: mail,calendar,meetings）。

監査（仕様21）

すべての呼び出しはJSONLでログに記録される（logs/audit-YYYY-MM-DD.jsonl）: timestamp, user, session, tool, operation (READ/WRITE), resourceType, graphEndpoint, httpMethod, success, durationMs、WRITEの場合はさらにsender, recipients, cc, subject, messageId, result。コンテンツ（本文、文字起こし、ドキュメント、トークン）がログに記録されることは決してない。

障害耐性（仕様22–23）

• HTTP 429/503/504: 自動リトライ、Retry-Afterを尊重（最大4回の試行）。

• @odata.nextLinkページネーションはすべてのリストツールで対応（maxItemsパラメータ、切り捨てを明示）。

• 期限切れトークン / 権限拒否 / リソース不存在: AIが理解でき、行動可能なエラーメッセージ。

• ファイルダウンロードにはサイズ制限（MAX_DOWNLOAD_BYTES）、DOCX/XLSX/PPTX/PDF/TXT/CSV → テキスト抽出、その他のバイナリ → base64。

ツールマトリックス（開発者向け付録）

完全なMCP tool → Graph endpoint → HTTP method → delegated permission → READ/WRITE → enabledマトリックスは生成ドキュメントとして: docs/tool-matrix.md（npm run matrixがsrc/tools/endpoints/*.tsの定義から更新）。

Loopアダプタの制限（仕様13）

一般的に利用可能な専用のGraph Loop workspace APIはないため、Loopアダプタは架空のエンドポイントを使用しない: .loop/.fluidコンポーネントにはSearch APIおよびSharePoint/OneDriveドライブ経由でアクセスする。SharePoint Embeddedコンテナに保存されたLoopワークスペースは、delegated Graphでは必ずしもアクセスできない。この制限はツールの説明でAIに示され、ユーザーにも伝えるよう指示される。

受け入れテスト（仕様26）

接続済みクライアントから自然言語で: 「過去30日間のメール、カレンダー、Teamsチャット、会議の文字起こしを調べて… Xプロジェクトについての要約を作成して… それをメールにして、別途承認を得てから送信して。」 — 期待されるツールチェーン: 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)。