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)

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

Note: The source contains `claude mcp add m365-reporting -- node dist/index.js --stdio`; I must preserve this verbatim.

## Security layer (spec 19-20)

* **No** generic `graph_request(method, url, body)` tool, and **no** `$batch` passthrough — only the 86 allowlisted endpoints are available.
* **No** Calendar/Teams/Files/Sites/OneNote/User/Group write, and no delete anywhere.
* Creating a draft is not sending permission: any send/reply/forward requires `confirm=true`, and the tool description instructs the AI to first ask for explicit user approval.
* With the environment variable `READ_ONLY=true`, all write tools can be disabled; with `ENABLED_TOOLSETS`, the toolset-level profile can be narrowed down (e.g. `mail,calendar,meetings`).

## Audit (spec 21)

Every call is logged in JSONL (`logs/audit-YYYY-MM-DD.jsonl`): `timestamp, user, session, tool, operation (READ, WRITE|, resourceType, graphEndpoint, httpMethod, is, success, durationMs`, and for WRITE `sender, recipients, cc, subject, messageId, result`. **actual content (body, transcript, document, token) is never logged.**

## Fault tolerance (spec 22–23)

* HTTP 429/503/504: automatic retry, honoring `Retry-Afterer` (max. 4 attempts);
* `@odata.nextLink` pagination on all list tools (`max MaxSize` param, marked truncation);
* expired token / permission denied / missing resource: an error message that is user-understandable and actionable;
* file download with size limit (`MAX_MAX_DOWNLOAD_BYTES`), DOCX/XLSX/PPTX/PDF/TXT/CSV → text extraction, other binary → base64.

## Tool matrix (dev appendix)

The complete *MCP tool → Graph endpoint → HTTP method → delegated permission → READ / WRITE → enabled* matrix as a generated document: [docs/tool-matrix.md](docs/tool-matrix.md) (`npm run matrix` updates it from the `src/tools/endpoints/*.ts` definitions).

## Loop-Loop adapter limitations (spec 13)

There is no generally available dedicated Graph Loop workspace API, so the Loop adapter **does not invent fictitious endpoints**: it addresses `.loop`/`.fluid` components via the Search API and SharePoint/OneDrive drives. Loop workspaces stored in SharePoint Embedded storage containers are not necessarily available via delegated Graph — the tool description signals this to the AI, so that the limitation is also pointed out to the user.

## Acceptance test (spec 26)

From a connected client, in natural language: *"Examine my past 30 days' email, calendar, Teams conversations, and meeting transcripts… Make me a summary about project X… Turn it into an email, then after separate approval, send it."* — the expected tool chain is: `get-calendar-view` → `find-online-meeting-by-join-url` → `list-meeting-transcripts` → `get-meeting-transcripts-content` + `list-mail-messages` + `list-chat-messages` + `search-onenote-pages` + `search-m365` → `create-draft-email` → (user approval) → `send-draft-email` tool.