@juvantlabs/m365-graph-mcp-server 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,225 @@
+# Architecture — M365 Graph MCP Server
+
+Design rationale for `@juvantlabs/m365-graph-mcp-server`. Read alongside
+the [handbook MCP server spec](https://github.com/juvantlabs/handbook/blob/main/docs/repo-types/mcp-server.md)
+for the cross-cutting conventions; this doc covers what's specific to
+this server.
+
+## Purpose
+
+Wraps the Microsoft Graph API for AI-agent consumption: file operations
+on OneDrive + SharePoint Online, calendar reads + writes on Microsoft
+365 mailboxes. Fulfills the `m365-graph` abstract role per ADR 0002 in
+the handbook; replaces ad-hoc per-instance Graph SDK code with a
+single canonical MCP server, keeping the agent prompt surface clean and
+the auth path consolidated.
+
+## Scope
+
+### In scope (planned, via incremental ships)
+
+**OneDrive / SharePoint files**
+
+- List drives a user has access to.
+- List items in a drive (folders + files), with paging.
+- Search files by name/content within a drive or site.
+- Download a file (streamed; bounded by max-size guard).
+- Upload a small file (single PUT, ≤ 4 MB).
+- Upload a large file (resumable upload session, > 4 MB).
+- Copy / move items (async; tool polls the monitor URL until completion).
+- Delete items (gated by the spec/approval pattern referenced in [`docs/adr/0002-mcp-abstract-roles.md`](https://github.com/juvantlabs/handbook/blob/main/docs/adr/0002-mcp-abstract-roles.md) — destructive ops surface a "spec preview" before executing).
+
+**Calendar**
+
+- List user calendars.
+- List events in a date range.
+- Create / update / cancel events.
+- Search events by subject / body.
+
+### Out of scope
+
+- **Mail send** — explicit non-goal for this server. Outbound email is a
+  separate concern with its own threat model (SPF / DKIM / DMARC, reply-all
+  blast radius, etc.). If needed, ships as `juvantlabs/m365-mail-mcp-server`.
+- **Teams chat / channel posts** — same reasoning; lives in a separate
+  server when scoped.
+- **Tenant admin operations** — never automated by the agent layer. These
+  remain manual / IT-administered.
+- **General-purpose URL forwarder** — explicitly forbidden by handbook
+  spec § Anti-patterns #2. Each tool is typed and schema-validated; the
+  Microsoft Graph URL surface is hardcoded inside the tool, not
+  caller-supplied.
+
+## Authentication
+
+OAuth 2.0 via `@azure/msal-node`'s `ConfidentialClientApplication`,
+scoped per the application registration in Microsoft Entra (tenant
+admin grants delegated and/or application permissions to the
+registered app).
+
+| Concern | Choice |
+|---|---|
+| OAuth library | `@azure/msal-node` (Microsoft's official) — never roll auth |
+| Flow | Authorization Code with PKCE for delegated; Client Credentials for daemon ops |
+| Scopes | Per-tool minimum: `Files.Read.All` for read-only file tools, `Files.ReadWrite.All` for write tools, `Calendars.Read` / `Calendars.ReadWrite` for calendar tools. Documented in [`README.md`](README.md) § Tools as tools ship. |
+| Token storage | `@napi-rs/keyring` (OS keychain). `keytar` is archived (handbook spec anti-pattern #10) — explicitly NOT used. |
+| Token lifetime | Refresh token rotation handled by MSAL; refreshes never enter the agent's context. |
+| Tenant ID | Validated at startup against the regex `^(common\|organizations\|consumers\|<UUID>)$` (handbook spec § Auth). Prevents arbitrary string interpolation into the authority URL. |
+
+The MCP server process loads tokens at startup, refreshes on demand, and
+exits when the client disconnects. **Per-tenant subprocess** — no
+shared module-level state across tenants (handbook spec § Per-tenant
+subprocess).
+
+## Threat model
+
+This server inherits the 12-item anti-pattern checklist from the
+[ftaricano audit](https://gist.github.com/juvantlabs/a9fe0a76a23b0c1260b1e0ad3194a6da)
+that informs the [handbook MCP server spec](https://github.com/juvantlabs/handbook/blob/main/docs/repo-types/mcp-server.md)
+§ Anti-patterns. Specific defenses:
+
+| Threat | Defense |
+|---|---|
+| Arbitrary local-FS write through `localPath` (audit C1–C4) | Every `download_file` / `upload_file` tool sandboxes to a per-tenant root. `path.resolve` + prefix check + symlink guard. Never trust caller-supplied `localPath`. |
+| URL forwarder primitive (audit C5) | No such tool. Each tool's Graph URL is hardcoded. |
+| Stdout corruption (audit C6) | `console.error` only; `console.log` blocked by ESLint + CI grep. |
+| Outdated MCP SDK (audit C7) | `@modelcontextprotocol/sdk ^1.25.2` pinned in `package.json`. |
+| Vulnerable axios (audit C8) | We use the Microsoft Graph SDK; no direct axios dep. |
+| Vulnerable `jws` transitively (audit C9) | Quarterly `npm audit` (CI step every PR). |
+| Defense-in-depth dead code (audit S1) | CI dead-code grep enforces every exported `validate*` / `sanitize*` / `guard*` is imported elsewhere in `src/`. |
+| README env-var lies (audit S2) | CI README env-var accuracy check. |
+| OData / URL injection (audit S3) | All Graph queries built via the SDK or with explicit `encodeURIComponent`. |
+| Token storage (audit S5) | `@napi-rs/keyring`, never `keytar`. |
+| Whole-file buffering (audit S7) | Downloads stream; max file size capped at 200 MB (configurable). |
+| No async-op polling (audit S8) | `copy` / `move` poll the monitor URL until completion; never return "initiated successfully" as the final result. |
+
+### Universal Boundaries (per `SYSTEM_INVARIANTS.md` §4)
+
+- No general-purpose URL forwarder primitive.
+- Per-tenant subprocess (no shared cache state across tenants).
+- Stdout discipline: `console.error` only outside protocol path.
+
+### Delete-class operations
+
+Delete tools (e.g. `delete_file`, `cancel_event`) follow the
+**spec/approval pattern**: the agent submits a spec describing what to
+delete; the tool returns a preview + a `confirmation_token`; a second
+call with the token executes the delete. Mirrors the
+`m365-delete-spec` pattern referenced in FEAT-014 and codified more
+generally in the handbook MCP abstract roles ADR.
+
+## Performance characteristics
+
+- Typical request latency: 100–500 ms for unary Graph calls; multi-second
+  for downloads (streamed).
+- Max file size (download + upload): **200 MB** hard cap, server-side.
+  Configurable via `M365_MAX_FILE_SIZE_BYTES` if the deployment needs a
+  smaller cap; never larger.
+- Streaming: downloads use the Graph SDK's stream interface; no
+  whole-file `arraybuffer` reads (audit S7 mitigation).
+- Async polling: `copy` / `move` ops poll the monitor URL with
+  exponential backoff (1s, 2s, 4s, …, max 30s) until status is
+  `succeeded` or `failed`. Tool returns the final state, never a 202.
+
+## Tool catalog
+
+Each row is also reflected in [`README.md`](README.md) § Tools.
+
+| Tool | Underlying API call | Input | Output | Scope | Notes |
+|---|---|---|---|---|---|
+| `m365-graph:list_drives` | `GET /me/drive`, `GET /me/drives` | _(none)_ | `{ primary, accessible: [] }` | `Files.Read` | First-ship; validates the auth + Graph plumbing end-to-end. |
+| `m365-graph:list_items` | `GET /me/drive/root/children` or `GET /drives/{id}/items/{item}/children` | `drive_id?`, `item_id?`, `limit?` (1–100, default 50) | `{ count, items: [] }` | `Files.Read` | Item type derived from presence of `folder` facet. `child_count` populated only for folders. |
+| `m365-graph:search_files` | `GET /drives/{id}/root/search(q='…')` (defaults to `/me/drive`) | `query`, `drive_id?`, `limit?` (1–50, default 20) | `{ count, results: [] }` with virtual `path` joining `parentReference.path` + `name` | `Files.Read` | OData function call; query single quotes are escaped (`'` → `''`). |
+| `m365-graph:download_file` | `GET /me/drive/items/{id}` for metadata, then `GET @microsoft.graph.downloadUrl` (Graph CDN) for the bytes | `item_id`, `drive_id?` | `{ local_path, size_bytes, name, content_type }` | `Files.Read` | **Sandboxed**: writes only under `<sandbox>/<tenant>/<sha256(item_id)[:16]>-<sanitized name>`. Streamed via fetch + Node `pipeline`; no whole-file buffering. 200 MB cap, refused pre-fetch via metadata size. Folders rejected. |
+| `m365-graph:list_calendars` | `GET /me/calendars` | `limit?` (1–100, default 50) | `{ count, calendars: [] }` | `Calendars.Read` | Owner extracted from `owner.{name,address}`; falls back to null. |
+| `m365-graph:list_events` | `GET /me/calendarView` (or `/me/calendars/{id}/calendarView`) with `startDateTime` + `endDateTime` query params | `start`, `end` (ISO 8601), `calendar_id?`, `limit?` (1–200, default 100) | `{ window, count, events: [] }` | `Calendars.Read` | **Recurrences expanded** (calendarView vs /events). Ordered by `start/dateTime` ascending. ISO 8601 input lightly validated client-side (regex), Graph does the strict parse. |
+| `m365-graph:search_events` | `GET /me/events?$filter=contains(subject, '…')` | `query`, `limit?` (1–50, default 20) | `{ count, results: [] }` | `Calendars.Read` | Subject-only substring match. `$search` is not supported on the Events resource by Graph; body search would require POST `/search/query` (separate API, deferred). Single-quote escaping (`'` → `''`) on the query. **Series masters**, not expanded occurrences. |
+| `m365-graph:get_event` | `GET /me/events/{id}` | `event_id` | event summary + body + body_truncated + recurrence | `Calendars.Read` | Body capped at 8000 chars (defense-in-depth against pathological event bodies); body_truncated flag indicates clipping. Recurrence rule passed through opaquely (Graph schema). |
+| `m365-graph:upload_file` | `PUT /items/{parent}:/{name}:/content` (≤ 4 MB) or `OneDriveLargeFileUploadTask` (resumable, 10 MB chunks, > 4 MB) | `local_path`, `drive_id?`, `parent_item_id?`, `name?`, `conflict_behavior?` | `{ uploaded: { id, name, size, webUrl, upload_path } }` | `Files.ReadWrite` | Trust note: `local_path` from the agent; the MCP server reads from the user's filesystem (no sandbox on read — would defeat the upload's purpose). 200 MB cap (`checkSizeCap` defense-in-depth). Absolute path logged to stderr. |
+| `m365-graph:create_event` | `POST /me/events` (or `/me/calendars/{id}/events`) | `subject`, `start`, `end` (required); `timezone?`, `body?`, `body_content_type?`, `location?`, `attendees?`, `is_all_day?`, `calendar_id?` | `{ created: <event summary> }` | `Calendars.ReadWrite` | Timezone defaults to UTC (Graph requires explicit TZ). Attendee.type ∈ {required, optional, resource}. Graph sends invites by default. |
+| `m365-graph:update_event` | `PATCH /me/events/{id}` | `event_id` (required); any subset of subject/start/end/timezone/body/location/attendees/is_all_day | `{ updated: <event summary> }` | `Calendars.ReadWrite` | Empty patch rejected. **Attendees REPLACE, not merge** (Graph semantics) — pass the full intended list. Timezone required when start or end is updated (Graph rejects without TZ). |
+| `m365-graph:copy_file` | `POST /items/{id}/copy` (raw response → 202 + Location) → poll monitor URL → `GET resourceLocation` (or fallback list-by-name) | `item_id`, `target_parent_id`; `source_drive_id?`, `target_drive_id?`, `new_name?`, `wait_max_seconds?` | `{ status: "completed", copied: { id, name, size, webUrl, parent_id } }` | `Files.ReadWrite` | **Async polling** with exponential backoff (1s → 2s → 4s → … capped at 30s). Per handbook anti-pattern S8: never returns "initiated successfully" — always polls to terminal state. Fallback list-by-name handles the Graph quirk where completed monitor responses sometimes omit `resourceLocation`. |
+| `m365-graph:move_file` | `PATCH /me/drive/items/{id}` with `{parentReference: {id}, name?}` | `item_id`, `target_parent_id`; `drive_id?`, `new_name?` | `{ moved: { id, name, ... } }` | `Files.ReadWrite` | Synchronous within a single drive. Cross-drive moves are NOT supported by this PATCH (Graph's documented limitation); use copy + delete for those. |
+| `m365-graph:delete_file` | Phase 1: `GET /items/{id}` → preview. Phase 2: `DELETE /items/{id}` after token consume. | `item_id` (required), `drive_id?`, `confirmation_token?` | preview or `{ deleted }` | `Files.ReadWrite` | **Spec/approval two-phase** per handbook ADR 0002. Token tied to canonical-JSON SHA-256 of the spec; passing a token issued for `{item_id: A}` together with `{item_id: B}` fails with `spec_mismatch`. Single-use, 5 min expiry. |
+| `m365-graph:cancel_event` | Phase 1: `GET /events/{id}` → preview. Phase 2: `POST /events/{id}/cancel { Comment }` after token consume. | `event_id` (required), `comment?`, `confirmation_token?` | preview or `{ cancelled }` | `Calendars.ReadWrite` | Same two-phase pattern as delete_file. The `comment` is part of the spec — changing it between preview and execute fails `spec_mismatch`. |
+| `m365-graph:decline_event` | Phase 1: `GET /events/{id}` → preview. Phase 2: `POST /events/{id}/decline { sendResponse, comment? }` after token consume. | `event_id`, `comment?`, `send_response?`, `confirmation_token?` | preview or `{ declined }` | `Calendars.ReadWrite` | For events the user is invited to (attendee). Cancel_event vs decline_event reflect the Graph distinction (organizer vs attendee). `send_response` is part of the spec hash so changing it between preview/execute fails `spec_mismatch`. Default true = organizer notified; false = silent decline. |
+| `m365-graph:search_events_content` | `POST /search/query` with `entityTypes: ["event"]` + queryString | `query`, `limit?`, `from?` | `{ count, total, results: [<event summary>] }` | `Calendars.Read` | Subject + body search via the Microsoft Search API (separate from `$filter` on /me/events used by `search_events`). Search API hit shape `{ hitId, summary, resource }` mapped back to summarizeEvent's shape via `resource`. Returns recurrence series masters. |
+
+## Spec/approval confirmation-token pattern
+
+Destructive tools (`delete_file`, `cancel_event`) implement a two-phase
+flow per the handbook MCP server spec § Tool design and ADR 0002 to
+prevent single-shot agent destruction in long autonomous loops:
+
+| Phase | Required args | Tool action |
+|---|---|---|
+| 1 — preview | original args, **no** `confirmation_token` | Fetches a preview of what would be destroyed; issues a token tied to (tool name, canonical-JSON SHA-256 of spec, expiry timestamp). Returns preview + token. |
+| 2 — execute | original args + correct `confirmation_token` | Verifies token (exists, not expired, tied to this exact tool, spec hash matches). Executes the destructive operation. Consumes token (single-use). |
+
+State lives in `src/auth/confirmation_tokens.ts` as a module-level
+`Map<token, {toolName, specHash, expiresAt}>`. Per-tenant subprocess
+per the handbook spec means there's no cross-process leakage; tokens
+expire 5 minutes after issue and are garbage-collected on every
+issue/consume call.
+
+The spec match is by SHA-256 of canonicalized JSON (keys sorted, top
+level only). The agent cannot reuse a token across destructive ops:
+
+- Token issued for `delete_file({item_id: "A"})`
+- Agent attempts `delete_file({item_id: "B", confirmation_token: <token>})`
+- → `spec_mismatch` error, deletion does not occur
+
+Same protection for `cancel_event` if the agent changes the cancellation
+comment between preview and execute.
+
+### Download sandboxing
+
+The `download_file` tool writes to a sandbox directory determined by:
+
+1. `M365_DOWNLOAD_DIR` env var (override) → `<override>/<tenant-id>/`
+2. else `XDG_CACHE_HOME` → `<XDG_CACHE_HOME>/m365-graph-mcp-server/<tenant-id>/`
+3. else default → `~/.cache/m365-graph-mcp-server/<tenant-id>/`
+
+Local filenames are server-constructed: `<sha256(item_id)[:16]>-<sanitized name>`,
+NOT derived from caller-supplied paths (handbook anti-pattern #1
+mitigation). Path injection via `item_id` is structurally impossible
+because the agent never sees raw filesystem paths in the input. As
+defense-in-depth, the resolved path is verified to start with the
+sandbox root before writing.
+
+Mode: dirs `0o700`, files `0o600` so other users on a shared host
+can't read downloaded content.
+
+## Input validation
+
+Every tool validates its inputs via helpers in
+[`src/types/validators.ts`](src/types/validators.ts):
+
+- `validateRequiredString(v, name)` — non-empty string or throw
+- `validateOptionalString(v, name)` — `string | undefined`
+- `validateOptionalInteger(v, name, {min, max, default})` — bounded
+- `sanitizeFilename(name)` — strips `/`, `\`, `\0`, leading dots; caps at 200 chars
+
+Naming convention: every helper starts with `validate*` or
+`sanitize*` so the [CI dead-code grep](https://github.com/juvantlabs/handbook/blob/main/docs/repo-types/mcp-server.md#ci-requirements)
+enforces it's imported in at least one other file. Defense-in-depth
+helpers that are never wired into a real handler are flagged as a
+security smell (handbook anti-pattern S1).
+
+## Dependencies
+
+| Dependency | Version | Why |
+|---|---|---|
+| `@modelcontextprotocol/sdk` | `^1.25.2` | MCP framing; ≥1.25.2 required (ReDoS + DNS rebinding fixes — audit C7) |
+| `@microsoft/microsoft-graph-client` | `^3.0.7` | Microsoft's official Graph SDK — handles batching, retries, types |
+| `@azure/msal-node` | `^5.0.0` | OAuth — never roll auth. v5+ avoids transitive `uuid <14` GHSA-w5hq-g745-h8pq. |
+| `@napi-rs/keyring` | `^1.3.0` | OS keychain for token persistence; replaces archived `keytar`. |
+| `isomorphic-fetch` | `^3.0.0` | Peer dep of the Graph SDK. |
+
+## References
+
+- [Handbook MCP server spec](https://github.com/juvantlabs/handbook/blob/main/docs/repo-types/mcp-server.md)
+- [Handbook MCP abstract roles ADR (0002)](https://github.com/juvantlabs/handbook/blob/main/docs/adr/0002-mcp-abstract-roles.md)
+- [Handbook security disclosure process](https://github.com/juvantlabs/handbook/blob/main/docs/security/disclosure-process.md)
+- [Juvant OS MCP_INVENTORY.md](https://github.com/juvantlabs/juvant-os/blob/main/docs/MCP_INVENTORY.md)
+- [ftaricano audit (2026-05-03)](https://gist.github.com/juvantlabs/a9fe0a76a23b0c1260b1e0ad3194a6da) — origin of the 12-item anti-pattern checklist

package/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+All notable changes to `@juvantlabs/m365-graph-mcp-server` will be documented in this
+file.
+
+The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffold per handbook
+  [`docs/repo-types/mcp-server.md`](https://github.com/juvantlabs/handbook/blob/main/docs/repo-types/mcp-server.md),
+  generated by `juvantlabs/juvant-tools` `scaffold mcp-server` on
+  2026-05-03.
+- Authentication wiring under `src/auth/`:
+  - `msal.ts` — `ConfidentialClientApplication` factory with delegated
+    scopes (`User.Read`, `Files.Read`, `Calendars.Read`, `offline_access`)
+    and an MSAL cache plugin.
+  - `keyring.ts` — token persistence via `@napi-rs/keyring` (OS
+    keychain). Per-tenant scoping so multiple tenant configs don't
+    collide.
+  - `setup.ts` — interactive OAuth flow: opens the browser, runs a
+    one-shot localhost listener for the redirect, exchanges the code
+    for tokens, persists in keychain.
+- Microsoft Graph client factory under `src/client/graph.ts` — wraps
+  `@microsoft/microsoft-graph-client` with an MSAL-backed
+  authentication provider. Refresh handled transparently.
+- First read tool `m365-graph:list_drives` under `src/tools/`. Returns
+  the user's primary OneDrive plus other drives (shared SharePoint
+  document libraries) accessible to them.
+- Consolidation block — body-content search, decline-as-attendee,
+  mock-based auth tests:
+  - `m365-graph:search_events_content` — body + subject search via
+    the Microsoft Search API (POST /search/query). Distinct from
+    search_events which is subject-only via $filter (since Graph
+    doesn't support $search on /me/events). Maps Search-API-shaped
+    hits back to summarizeEvent for response uniformity. Pagination
+    via `from` + `limit`. Read-only.
+  - `m365-graph:decline_event` — decline an event the user is invited
+    to (distinct from cancel_event which is for events the user
+    organizes). Two-phase spec/approval pattern, identical to
+    cancel_event's. `send_response` boolean controls whether the
+    organizer is notified — both default-true (sends RSVP) and
+    silent-decline are supported. send_response is part of the spec
+    hash, so changing it between preview and execute fails
+    spec_mismatch.
+  - Mock-based unit tests landed for src/auth/keyring.ts,
+    src/auth/msal.ts (cache plugin lifecycle + makeMsalClient
+    factory), src/client/graph.ts (MsalAuthProvider class), and
+    src/index.ts (validateEnv → renamed checkEnv to dodge the dead-
+    code grep, dispatch, dispatchToolCall extracted from runMcpServer
+    for testability).
+  - vitest.config.ts coverage scope expanded: src/auth/** + src/client/**
+    now in scope. src/auth/setup.ts and src/index.ts excluded from
+    coverage thresholds — both are entry-point/integration glue best
+    validated via the live OAuth + MCP smoke runs.
+- Write block, round 2 — four tools completing the file + calendar
+  write surface. No new Entra scopes required (round 1 already extended
+  to Files.ReadWrite + Calendars.ReadWrite).
+  - `m365-graph:copy_file` — async copy with monitor-URL polling
+    (POST /items/{id}/copy → 202 + Location → poll until completion).
+    Exponential backoff (1s → 2s → 4s → … capped at 30s). Per
+    handbook anti-pattern S8: never returns "initiated successfully";
+    always waits for terminal state. Fallback list-by-name if the
+    Graph monitor URL's completed response omits `resourceLocation`
+    (a documented but inconsistent Graph behavior).
+  - `m365-graph:move_file` — synchronous PATCH with `parentReference`.
+    Atomic within a single drive. Cross-drive is documented as
+    unsupported (use copy + delete instead).
+  - `m365-graph:delete_file` — two-phase spec/approval per handbook
+    ADR 0002. First call returns a preview + confirmation_token tied
+    to the exact spec; second call (with the token + same args)
+    executes DELETE. Token is single-use, 5 min expiry, SHA-256
+    matched against canonical JSON of the spec — passing a stale
+    token with different args fails `spec_mismatch`.
+  - `m365-graph:cancel_event` — same two-phase pattern. Sends
+    cancellation notice to attendees after token consume.
+- New `src/auth/confirmation_tokens.ts` — module-level Map keyed by
+  token, with `issueConfirmation(tool, spec)` and
+  `consumeConfirmation(token, tool, spec)`. Per-tenant subprocess
+  scoping inherited from the spec; no cross-process leakage.
+  Garbage-collected on every issue/consume.
+- Write block, round 1 — three tools requiring Files.ReadWrite +
+  Calendars.ReadWrite delegated scopes (extended in Entra app
+  permissions, admin consent re-granted, OAuth re-run):
+  - `m365-graph:upload_file` — uploads a local file to a drive.
+    Auto-routes between single PUT (`PUT /items/{parent}:/{name}:/content`,
+    files ≤ 4 MB) and resumable upload session
+    (`OneDriveLargeFileUploadTask` with 10 MB chunks, files > 4 MB).
+    200 MB hard cap. Conflict behavior parametric (`fail` default,
+    `replace`, `rename`). Trust note: agent supplies `local_path`;
+    the absolute path is logged to stderr.
+  - `m365-graph:create_event` — `POST /me/events`. Subject + start +
+    end required; timezone defaults to UTC. Optional body (text/html),
+    location, attendees (with type ∈ {required, optional, resource}),
+    is_all_day. Graph sends invitations by default.
+  - `m365-graph:update_event` — `PATCH /me/events/{id}`. All fields
+    except event_id optional; only provided fields are PATCHed. Empty
+    patch is rejected. Attendees are REPLACED (Graph semantics, not
+    merged).
+- DELEGATED_SCOPES updated: `Files.Read` + `Calendars.Read` →
+  `Files.ReadWrite` + `Calendars.ReadWrite` (the wider scopes subsume
+  the narrower; the Entra app permissions list still includes both
+  for granted-permission tracking).
+- New `validateOptionalEnum<T>(value, name, allowed, default)` validator
+  for parametric strings (conflict_behavior, attendee.type,
+  body_content_type).
+- `checkSizeCap(size)` extracted from upload_file's handler so the
+  200-MB defense-in-depth can be unit-tested independently of fs +
+  Graph integration.
+- Calendar read block — four tools under the existing `Calendars.Read`
+  delegated scope (no new Entra app permissions required):
+  - `m365-graph:list_calendars` — list user calendars (primary + group
+    + shared) via `/me/calendars`. Returns id / name / color / owner /
+    is_default / can_edit / can_share per calendar.
+  - `m365-graph:list_events` — events in a date window via
+    `/me/calendarView` (or `/me/calendars/{id}/calendarView`) with
+    `startDateTime` + `endDateTime` query params. **Recurrences are
+    expanded** — each occurrence is its own event in the response.
+    Ordered by start/dateTime ascending.
+  - `m365-graph:search_events` — subject-substring search via
+    `$filter=contains(subject, '…')`. `$search` is not supported on
+    the Events resource by Graph; body search would require the
+    Search API (POST /search/query, deferred). Returns series masters
+    for recurring events.
+  - `m365-graph:get_event` — full event details via `/me/events/{id}`.
+    Body content capped at 8000 chars with `body_truncated` flag.
+    Includes recurrence rule when present.
+- New `validateRequiredISODate` validator with regex-based ISO 8601
+  shape check (date-only or full datetime, with optional Z or ±HH:MM
+  offset). Catches obviously-wrong inputs near the source; Graph does
+  the strict parse.
+- Three additional read tools, all under the `Files.Read` delegated
+  scope:
+  - `m365-graph:list_items` — list children of a folder (drive root or
+    specific folder via `item_id`). Distinguishes file vs folder via
+    presence of the `folder` facet; populates `child_count` for folders.
+  - `m365-graph:search_files` — OData search within a drive. Defaults
+    to the user's primary OneDrive; supports `drive_id` for SharePoint
+    libraries. Single-quote escaping in the query string.
+  - `m365-graph:download_file` — streams a file to a per-tenant local
+    sandbox (XDG-compliant default, `M365_DOWNLOAD_DIR` override).
+    200 MB cap enforced via metadata pre-check. Local filename is
+    server-constructed (`<sha256(item_id)[:16]>-<sanitized name>`) so
+    path injection is structurally impossible. 0o700 dir + 0o600 file
+    mode. Streamed via fetch + Node pipeline (no whole-file buffering
+    — handbook anti-pattern #11 mitigation).
+- Input validators in `src/types/validators.ts`
+  (`validateRequiredString`, `validateOptionalString`,
+  `validateOptionalInteger`, `sanitizeFilename`). The `validate*` /
+  `sanitize*` naming feeds into the CI dead-code grep.
+- Tool registry pattern (`src/tools/index.ts` + `src/types/tool.ts`)
+  so subsequent tools land via single-file additions.
+- `setup` subcommand on the binary (`m365-graph-mcp-server setup`,
+  `npm run setup`) that runs the OAuth flow and exits. The default
+  invocation (no subcommand) stays the stdio MCP server.
+- `.env.example` documenting the required env vars +
+  `npm run dev` / `npm run setup` scripts that load `.env.local` via
+  Node's `--env-file` flag.
+
+### Pending
+
+- Integration tests against a live sandbox tenant in CI (currently
+  smoke-run live by hand).
+- Refresh-token revocation handling tests (MSAL silent acquisition
+  failure path beyond "no cached account").
+- Mail send / Teams chat — explicit non-goals, deferred to separate
+  vendor MCP servers if needed.
+
+### Tested
+
+- Vitest unit tests covering all eight read tools + validator helpers
+  + tool registry. 106 tests across 10 files. Per-file coverage
+  thresholds (lines/functions/statements ≥ 80%, branches ≥ 50%
+  pending fs+fetch mocking on download_file) pass for every file in
+  the configured coverage scope (`src/types/validators.ts` +
+  `src/tools/**`). All tools at 100% line coverage; branches between
+  52–100%. `src/index.ts`, `src/auth/**`, `src/client/**` are still
+  deferred to integration tests.
+
+---
+
+[Unreleased]: https://github.com/juvantlabs/m365-graph-mcp-server/compare/HEAD

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juvant Srls
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# M365 Graph MCP Server
+
+`@juvantlabs/m365-graph-mcp-server` — Model Context Protocol server
+wrapping the Microsoft Graph API for OneDrive, SharePoint, and Calendar
+(read + write). Designed to be consumed by Juvant OS agents (or any
+MCP-aware client) via `npx`.
+
+Fulfills the `m365-graph` abstract role per
+[`docs/adr/0002-mcp-abstract-roles.md`](https://github.com/juvantlabs/handbook/blob/main/docs/adr/0002-mcp-abstract-roles.md)
+in the handbook. Per-company instance config binds this concrete server
+to that abstract role in `.juvant/config.json`.
+
+## Status
+
+**Scaffolded.** Generated by
+[`juvantlabs/juvant-tools`](https://github.com/juvantlabs/juvant-tools)
+`scaffold mcp-server` (via the `juvant-tools-mcp` MCP server) on
+2026-05-03, conforming to the
+[`mcp-server.md`](https://github.com/juvantlabs/handbook/blob/main/docs/repo-types/mcp-server.md)
+spec. Tool implementations land via PR.
+
+## Install + run
+
+```bash
+npx @juvantlabs/m365-graph-mcp-server
+```
+
+(Once published to npm. During development, see [`CONTRIBUTING.md`](CONTRIBUTING.md).)
+
+## Environment variables
+
+Required:
+
+| Variable | Purpose |
+|---|---|
+| `M365_CLIENT_ID` | Microsoft Entra application (client) ID for the registered app. |
+| `M365_CLIENT_SECRET` | Client secret for the registered app. Stored only in the consumer's environment; never in `.juvant/config.json`. |
+| `M365_TENANT_ID` | Microsoft Entra tenant ID (UUID), or one of `common` / `organizations` / `consumers` for multi-tenant flows. Validated at startup against the spec regex. |
+
+Optional:
+
+| Variable | Purpose |
+|---|---|
+| `MCP_SERVER_LOG_LEVEL` | Log level for diagnostics on stderr (default `info`). |
+| `M365_DOWNLOAD_DIR` | Override the per-tenant sandbox directory used by `download_file`. Default: `$XDG_CACHE_HOME/m365-graph-mcp-server/<tenant-id>` or `~/.cache/m365-graph-mcp-server/<tenant-id>`. |
+
+> CI enforces that every variable documented in this section is actually
+> read from `process.env.<NAME>` somewhere in `src/` — placeholder names
+> containing `<>` are skipped. Documenting an env var without wiring it
+> up will fail the build (handbook anti-pattern S2).
+
+OAuth scope minimization is per-tool; see the [tool catalog](#tools)
+and [`ARCHITECTURE.md`](ARCHITECTURE.md) for the per-tool scope
+justifications.
+
+## Binding
+
+The Juvant OS adopter binds this server in `.juvant/config.json`:
+
+```json
+{
+  "m365-graph": {
+    "provider": "microsoft",
+    "mcp_server": "npx @juvantlabs/m365-graph-mcp-server",
+    "scope": "rw"
+  }
+}
+```
+
+See [handbook MCP_INVENTORY.md](https://github.com/juvantlabs/juvant-os/blob/main/docs/MCP_INVENTORY.md)
+for the abstract role this server fulfills + the canonical config shape.
+
+## Tools
+
+| Tool | Purpose | Input | Output | Required scope |
+|---|---|---|---|---|
+| `m365-graph:list_drives` | Lists the drives the user has access to (primary OneDrive + shared document libraries). | _(none)_ | `{ primary, accessible: [] }` with id / driveType / name / webUrl / owner. | `Files.Read` |
+| `m365-graph:list_items` | Lists immediate children (files + folders) of a folder. Defaults to the drive root. | `drive_id?`, `item_id?`, `limit?` (1–100, default 50) | `{ count, items: [] }` with id / name / type / size / child_count / lastModified / webUrl. | `Files.Read` |
+| `m365-graph:search_files` | Searches files by name and content within a drive. | `query` (required), `drive_id?`, `limit?` (1–50, default 20) | `{ count, results: [] }` with id / name / path / size / is_folder / lastModified / webUrl. | `Files.Read` |
+| `m365-graph:download_file` | Downloads a file to a per-tenant local sandbox. Returns the local path; agent reads via a filesystem-aware tool. Streams, capped at 200 MB. | `item_id` (required), `drive_id?` | `{ local_path, size_bytes, name, content_type }` | `Files.Read` |
+| `m365-graph:list_calendars` | Lists the user's calendars (primary + group / shared). | `limit?` (1–100, default 50) | `{ count, calendars: [] }` with id / name / color / owner / is_default / can_edit / can_share. | `Calendars.Read` |
+| `m365-graph:list_events` | Lists events in a date window. Recurrences are expanded — each occurrence is its own event. | `start` + `end` (ISO 8601, required), `calendar_id?`, `limit?` (1–200, default 100) | `{ window, count, events: [] }` with id / subject / start / end / location / organizer / attendees / web_url. | `Calendars.Read` |
+| `m365-graph:search_events` | Searches events by subject substring (Graph $search isn't supported on Events; subject-only via `contains()`). Returns recurrence series masters, not occurrences. | `query` (required), `limit?` (1–50, default 20) | `{ count, results: [] }` (same event shape). | `Calendars.Read` |
+| `m365-graph:get_event` | Fetches full details for a single event — body (capped at 8000 chars), attendees with response statuses, location, recurrence rule. | `event_id` (required) | event summary + `body` / `body_content_type` / `body_truncated` / `recurrence`. | `Calendars.Read` |
+| `m365-graph:upload_file` | Uploads a local file to a drive. Auto-routes between single PUT (≤ 4 MB) and resumable upload session (> 4 MB, 10 MB chunks). 200 MB hard cap. | `local_path` (required), `drive_id?`, `parent_item_id?`, `name?`, `conflict_behavior?` (`fail`/`replace`/`rename`, default `fail`) | `{ uploaded: { id, name, size, webUrl, upload_path } }` | `Files.ReadWrite` |
+| `m365-graph:create_event` | Creates a new event on the user's primary calendar (or a specified calendar). Sends invitations to attendees by Graph default. | `subject` + `start` + `end` (required), `timezone?` (default UTC), `body?`, `body_content_type?` (`text`/`html`), `location?`, `attendees?`, `is_all_day?`, `calendar_id?` | `{ created: <event summary> }` | `Calendars.ReadWrite` |
+| `m365-graph:update_event` | Updates an existing event. All fields except `event_id` are optional; only provided fields are PATCHed. **Attendees: full replacement, not merge** — pass the full intended list. | `event_id` (required), then any subset of `subject`/`start`+`end`+`timezone`/`body`+`body_content_type`/`location`/`attendees`/`is_all_day` | `{ updated: <event summary> }` | `Calendars.ReadWrite` |
+| `m365-graph:copy_file` | Async copy with polling. POSTs to `/items/{id}/copy`, polls the monitor URL with exponential backoff (1s → 2s → … capped at 30s) until completion. Falls back to `list-by-name` if the monitor's completed response omits `resourceLocation` (common Graph quirk). | `item_id` + `target_parent_id` (required); `source_drive_id?`, `target_drive_id?`, `new_name?`, `wait_max_seconds?` (1–1800, default 300) | `{ status: "completed", copied: { id, name, ... } }` | `Files.ReadWrite` |
+| `m365-graph:move_file` | Synchronous move within a drive (PATCH parentReference). Cross-drive moves are not supported here — use copy_file + delete_file for those. | `item_id` + `target_parent_id` (required); `drive_id?`, `new_name?` | `{ moved: { id, name, ... } }` | `Files.ReadWrite` |
+| `m365-graph:delete_file` | **Two-phase** spec/approval: 1st call returns preview + `confirmation_token`; 2nd call (same args + token) executes the DELETE. Token single-use, 5 min expiry, tied to exact spec (canonical-JSON SHA-256). | `item_id` (required), `drive_id?`, `confirmation_token?` | preview `{ item, confirmation_token, expires_at }` or execute `{ deleted: { ... } }` | `Files.ReadWrite` |
+| `m365-graph:cancel_event` | **Two-phase** like delete_file. Cancels a meeting the user organizes (sends cancellation notice to attendees). | `event_id` (required), `comment?`, `confirmation_token?` | preview or `{ cancelled: { event_id } }` | `Calendars.ReadWrite` |
+| `m365-graph:decline_event` | **Two-phase**. Declines an event the user is invited to (as attendee — distinct from cancel which is for events the user organizes). Sends a decline RSVP unless `send_response: false`. | `event_id` (required), `comment?`, `send_response?` (default `true`), `confirmation_token?` | preview or `{ declined: { event_id, send_response } }` | `Calendars.ReadWrite` |
+| `m365-graph:search_events_content` | Subject + **body** content search via the Microsoft Search API (POST `/search/query`). Distinct from `search_events` (subject-only via `$filter`). Returns recurrence series masters; for occurrences in a window use `list_events`. | `query` (required), `limit?` (1–50, default 25), `from?` (pagination offset, default 0) | `{ count, total, results: [<event summary>] }` | `Calendars.Read` |
+
+That's the full FEAT-014 surface: 4 read + 4 write on files, 5 read +
+4 write on calendars — **17 tools total**. Read tools all exercise
+delegated `Files.Read` + `Calendars.Read` (granted by default in the
+narrower `*.Read` permissions); write tools require `Files.ReadWrite`
++ `Calendars.ReadWrite` (separately granted in the Entra app +
+admin-consented).
+
+## Local development
+
+The repo expects a `.env.local` file with your tenant's credentials.
+Bootstrap from the template:
+
+```bash
+cp .env.example .env.local
+# then edit .env.local with your M365_TENANT_ID, M365_CLIENT_ID,
+# and M365_CLIENT_SECRET — see ARCHITECTURE.md § Authentication
+# for the Entra app registration flow.
+```
+
+`.env.local` is gitignored.
+
+### One-time OAuth setup
+
+The first time you run the server, you need to complete an OAuth flow
+to populate the OS keychain with refresh tokens:
+
+```bash
+npm run setup
+```
+
+This opens your browser, signs you in to your tenant, captures the
+authorization code via a one-shot listener at
+`http://localhost:3000/auth/callback`, and persists the resulting
+tokens via `@napi-rs/keyring` (macOS Keychain / Linux Secret Service /
+Windows Credential Manager). After that, the server uses cached
+tokens silently — refreshes as needed via the cached refresh grant.
+
+### Run the MCP server
+
+```bash
+npm run dev
+```
+
+Listens on stdio. Useful when developing alongside an MCP client like
+Claude Code: configure the client to spawn `npm run dev` (or
+`tsx --env-file=.env.local src/index.ts`) as its MCP server command.
+
+## Architecture
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for design rationale: scope,
+OAuth model with `@azure/msal-node`, token persistence via
+`@napi-rs/keyring`, per-tool scope minimization, filesystem sandboxing
+for upload/download tools, and async-op polling for `copy` / `move`.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). The repo follows the
+[`juvantlabs/handbook`](https://github.com/juvantlabs/handbook)
+conventions for MCP server repos.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md) for the disclosure process. Per the
+[handbook security disclosure process](https://github.com/juvantlabs/handbook/blob/main/docs/security/disclosure-process.md),
+report vulnerabilities privately via GitHub Security Advisory or
+`security@juvant.io`.
+
+## License
+
+[MIT](LICENSE). Copyright (c) 2026 Juvant Srls.