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 앱 등록(Entra app registration)

1. App registration 생성(single tenant).

2. Expose an API: Application ID URI = api://<CLIENT_ID>, scope: access_as_user. manifest에서 accessTokenAcceptedVersion을 2로 설정.

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(메일만): Wal.Read.Write, Mail.Send, Mail.ReadWrite.Shared, Mail.Send.Shared

   • .Allow 스코프에는 애드민 승인이 필요합니다.

4. HTTP modes: Certificates & secrets → client secret.

5. stdio/dev 模式: AuthAuthentication → "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을 요구합니다. 프록시는 클라이언트에게 DCR + PKCE(OAuth 2.1) 기반 인증을 제공하고, Entra ID에 대해서는 등록된 단일 엔터프라이즈 앱만 사용합니다. 클라이언트가 받는 access token은 Entra가 api://<CLIENT_ID>에 대해 발급한 토큰이므로 /mcp 검증 및 OBO Graph 인증은 그대로 유지됩니다. — 모든 호출은 로그인한 사용자의 이름으로 실행됩니다.

ChatGPT 연결 방법:

1. api:// 앱의 화asis 설정에서 Web redirect URI로 https://<BASE_URL>/auth/callback을 추가합니다. (정확한 값은 관리자 대시보드의 경로 설정 탭에 표시됩니다)

2. ChatGPT → 설정 → 커넥터 → 새 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)로 사용합니다.

보안 계층 (spec 19–20)

• **일반적인 graph_request(method, url, body) 및 $batch 패스스트루우는 제외됩니다. 허용 목록에 있는 86개 엔드포인트만 접근할 수 있습니다.

• Calendar/Teams/SharePoint/File/OneNote/User/그룹 등에 대한 쓰기 작업과 삭제는 전혀 없습니다.

• 초안 생성 ≠ 전송 권한입니다. 모든 send/reply/forward는 confirm=true를 요구하며, 도구 설명은 AI가 먼저 명시적 사용자 동의를 받도록 지시합니다.

• 완료한 지시 환경 변수로 모든 WRITE 도구를 비활성화할 수 있고, ENABLED_TOOLSETS(예: mail,calendar,meetings)로 처리 범위를 제한할 수 있습니다.

감사 로그 (spec 21)

모든 호출은 logs/audit-YYYY-MM-DD.jsonl에 JSONL 형식으로 기록됩니다. 필드: timestamp, user, session, tool, operation (READ/WRITE), resourceType, graphEndpoint, httpMethod, success, durationMs. WRITE의 경우에는 sender, recipients, cc, subject, messageId, result도 함께 기록됩니다. 본문, 대화 내용, 문서, 토큰 등의 콘텐츠는 절대 로그에 포함되지 않습니다.

오류 허용 (spec 22–23)

• HTTP 429/503/504: 자동 재시도, Retry-After 준수 (최대 4회).

• 모든 목록 도구에서 @odata.nextLink 페이지네이션 지원 (maxItems 파라미터, 잘림 표기).

• 만료된 토큰 / 권한 거부 / 접근할 수 없는 리소스: AI가 이해하고 조치할 수 있는 오류 메시지 제공.

• 파일 다운로드에는 크기 제한이 있으며(MAX_DOWNLOAD_BYTES), DOCX/XLSX/PPTX/PDF/TXT/CSV → 텍스트 추출, 기타 이진 형식은 base64로 변환.

위치 도구 매트릭스 (개발자 참고)

전체 MCP 도구 → Graph endpoint → HTTP method → delegated permission → READ/WRITE → enabled 매트릭스는 생성 문서입니다. docs/tool-matrix.md (npm run matrix 와 함께 src/tools/endpoints/*.ts에서 자동 갱신).

Loop 어댑터 제한 사항 (spec 13)

Loop 전용 Graph API는 공개되지 않아 Loop 어댑터는 특정 가상 엔드포인트를 사용하지 않습니다: .loop/.fluid 구성 요소는 Search API와 SharePoint/OneDrive 드라이브를 통해 접근합니다. SharePoint Embedded 저장소의 Loop 워크스페이스는 delegated Graph에서 항상 접근할 수 있는 것은 아니며, 이는 툴 설명에서 사용자에게 알릴 수 있도록 안내됩니다.

수용 테스트 (spec 26)

연결된 클라이언트에서 사용자 입력: "지난 30일 동안의 이메일/달력/팀 채팅/미팅 기록를 검토하고... X 프로젝트에 대한 요약을 작성해... 그것으로 이메일을 생성하고 별도 승인 후 전송해." — 예상 도구 흐름: get-calendar-view → find-online-meeting-by-join-url → list-meeting-transcripts → get-meeting-transcript-content + list-mail-messages + list-chat-messages + search-one-notepad + search-m365 → create-draft-email → (사용자 승인) → send-draft-email(confirm=true)