Microsoft 365 Reporting MCP — v1.0

Корпоративный MCP-сервер, через который ChatGPT, Clause и других MCP-совместимые AI-клиенты получают контролируемый доступ к информационным источникам Microsoft 365 (Outlook, Календарь, Teams, расшифровки встреч, OneNote, SharePoint, OneDrive, Loop, Search, Users).

Принцип: read broadly, write narrowly. Широкий слой READ в пределах реальных прав M365 вошедшего пользователя; единственная возможность 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

   • Для scope-ов .All требуется Admin consent.

4. Для HTTP-режима: Certificates & secrets → client secret.

5. Для stdio/dev-режима: Authentication → «Allow public client flows» = Yes (device code).

Примечание к пункту 11 спецификации: Sites.Selected существует как application permission; в 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

Endpoints в HTTP-режиме:

В HTTP-режиме сервер запускается даже без Entra-данных: превоначальную настройку можно выполнить через интерфейс /admin (Tenant ID, Client ID, Client Secret, Base URL, проверка подключения) — сохранение вступает в силу немедленно, настройки хранятся в data/settings.json и переопределяют значения .env.

Подключение ChatGPT (и других MCP-клиентов)

Сервер содержит встроенный OAuth-прокси перед Entra ID, поскольку коннектор ChatGPT ожидает dynamic client registration по RFC 7591, который Entra ID не поддерживает. Прокси предоставляет клиенту полный интерфейс OAuth 2.1 (DCR + PKCE), а в сторону Entra ID использует единственное зарегистрированное корпоративное приложение; выдаваемый клиенту access token — это сам токен, выпущенный Entra ID для api://<CLIENT_ID>, поэтому валидация на /mcp и OBO-обмен с Graphе остаются неизменными — все вызовы выполняются от имени вошедшего пользователя.

Подключение из ChatGPT:

1. В разделе Authentication приложения Entra ID добавьте как Web redirect URI: https://<BASE_URL>/auth/callback (точное значение показано на вкладке «Настройки» в админ).

2. ChatGPT → Settings → Connectors → new MCP connector, URL: https://<BASE_URL>/mcp.

3. Появившийся вход — это корпоративный вход Entra ID: пользователь входит с своей собственной учётной записью и получает только свои права M365.

Claude Desktop / Claude Code: тот же URL в качестве remote MCP или локально в stdio-режиме (claude mcp add m365-reporting -- node dist/index.js --stdio).

Уровень безопасности (см. п 19–20)

• Нет универсального tool graph_request(method, url, body) и нет $batch passthrough — доступны только 86 allowlist-енных endpoints.

• Нет операций записи в Calendar/Teams/Files/Sites/OneNote/User/Group и нет delete нигде.

• Создание черновика ≠ разрешение на отправку: каждый send/ reply/ forward защищён confirm=true, и описание tool предписывает AI сначала получить явное подтверждение пользователя.

• С помощью env-переменной READ_ONLY=true можно отключить все операторы записи; через ENABLED_TOOLSETS можно сузить профиль на уровне toolset (например, mail,calendar,meetings).

Audit (см. спецификацию 21)

Каждый вызов логируется в JSONL (logs/audit-YYYY-MM-DD.jsonl): timestamp, user, session, tool, operation (READ/WRITE), resourceType, endpoint, httpMethod, success, durationMs, а для WRITE также sender, recipients, cc, subject, messageId, result. Содержимое (тело, транскрипт, документ, токен) никогда не попадает в журнал.

Отказоустойчивость (спецификация 22–23)

• HTTP 429/503/504: автостатический retry с учётом Retry-After (максимум 4 попытки);

• @odata.nextLink пагиgnation во всех list-инструментах (параметр maxItems, с явным указанием truncation);

• истекший токен / отказ доступа / отсутствующий ресурс: понятное и пригодное для AI сооб расшифровка об ошибке;

• загрузка файлов с ограничением размера (MAX_DOWNLOAD_BYTES), DOCX/XLSX/PPT/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 API для Loop- рабочих пространств не существует, поэтому Loop-адаптер не использует вымышленные endpoints: через Search API и диски SharePoint/OneDrive он обращается к компонентам .loop/.fluid. Loop-workspaces, хранящиеся в контейнере SharePoint Embedded, могут быть недоступными через выполненный Graph — указание на это ограничение содержится в описании tool, чтобы AI сообщил о нём и пользователь знал.

Приёмочный тест (спецификация 26)

Из подключённого клиента на естественном языке: «Проанализй мою переписку, календарь, чаты Teams и расшифровки встреч за последние 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-onenote-pages + search-m365 → create-draft-email → (подтвердение пользователя) → send-draft-email(confirm=true).